Skip to content

GaZmagik/iso-24495 / skills/iso-24495-text-audit

iso-24495-text-audit

Verified

Audit user-selected Markdown or text files for deterministic plain-language findings. Use only when the user explicitly invokes this skill.

FileKindSize
SKILL.mdskill md3.2 KB
agents/openai.yamlconfig270 B
scripts/audit-text-cli.tsscript107 B
scripts/audit-text.tsscript5.0 KB

scripts/audit-text.ts

View on GitHub
import { lstatSync, readFileSync, writeFileSync } from "node:fs";
import { relative, resolve } from "node:path";
import {
  auditText,
  configHash,
  isAuditedDocument,
  listTextFiles,
  projectAcronyms,
} from "../../iso-24495-4/scripts/audit-corpus.ts";
import type { Reading } from "../../iso-24495-4/scripts/lib/parse.ts";
import type { Findings } from "../../iso-24495-4/scripts/lib/types.ts";

export interface TextAuditResult extends Findings {
  skipped: string[];
}

type ReadTextFile = (path: string, encoding: "utf8") => string;

function displayPath(path: string, projectDir: string): string {
  return relative(projectDir, path).replaceAll("\\", "/");
}

export function auditTarget(
  target: string,
  projectDir: string,
  readText: ReadTextFile = readFileSync,
  reading: Reading = {},
): TextAuditResult {
  const absoluteTarget = resolve(target);
  const absoluteProject = resolve(projectDir);
  const skipped: string[] = [];
  const targetStat = lstatSync(absoluteTarget);
  if (targetStat.isSymbolicLink()) {
    return { configHash: configHash(), files: {}, totals: {}, skipped: [absoluteTarget] };
  }
  const paths = targetStat.isDirectory()
    ? listTextFiles(absoluteTarget, (path) => skipped.push(path))
    : [absoluteTarget];
  if (!targetStat.isDirectory() && !isAuditedDocument(absoluteTarget)) {
    throw new Error(`Select a supported text file: ${target}`);
  }

  const knownAcronyms = projectAcronyms(absoluteProject);
  const findings: TextAuditResult = {
    configHash: configHash(),
    files: {},
    totals: {},
    skipped,
  };
  for (const path of paths) {
    let text: string;
    try {
      text = readText(path, "utf8");
    } catch {
      skipped.push(path);
      continue;
    }
    const violations = auditText(text, { knownAcronyms, frontMatter: reading.frontMatter });
    findings.files[displayPath(path, absoluteProject)] = { violations };
    for (const violation of violations) {
      findings.totals[violation.rule] = (findings.totals[violation.rule] ?? 0) + 1;
    }
  }
  return findings;
}

function tableCell(value: string): string {
  return value.replaceAll("|", "\\|").replaceAll(/\r?\n/g, " ");
}

export function formatFindings(findings: TextAuditResult): string {
  const lines = [
    "| File | Line | Rule | Finding |",
    "|------|------|------|---------|",
  ];
  for (const [file, result] of Object.entries(findings.files)) {
    for (const violation of result.violations) {
      lines.push(
        `| ${tableCell(file)} | ${violation.line} | ${tableCell(violation.rule)} | ${tableCell(violation.detail)} |`,
      );
    }
  }
  const findingCount = Object.values(findings.totals).reduce((total, count) => total + count, 0);
  lines.push(
    "",
    `Finding count: ${findingCount}. Files read: ${Object.keys(findings.files).length}. Skipped entries: ${findings.skipped.length}.`,
    "Mechanical findings are proxies, not an ISO judgement.",
    "The user decides whether the text suits its readers and purpose.",
  );
  return lines.join("\n");
}

export function runCli(
  argv: string[],
  stdout: (text: string) => void,
  stderr: (text: string) => void,
): number {
  const target = argv[2];
  if (!target) {
    stderr(
      "Usage: bun audit-text-cli.ts <file-or-directory> [--project-dir <directory>] [--json <out-file>] [--no-front-matter]",
    );
    return 2;
  }
  let jsonPath: string | undefined;
  let projectDir = process.cwd();
  // A file in a repository may open with front matter, which is metadata. A pull
  // request description cannot, and GitHub shows a leading "---" block as a rule
  // and a heading, so the check that reads one says there is no front matter.
  let frontMatter = true;
  const seenOptions = new Set<string>();
  for (let index = 3; index < argv.length; index++) {
    const option = argv[index];
    if (option !== "--json" && option !== "--project-dir" && option !== "--no-front-matter") {
      const kind = option.startsWith("--") ? "unknown option" : "unexpected argument";
      stderr(`audit-text: ${kind}: ${option}`);
      return 2;
    }
    if (seenOptions.has(option)) {
      stderr(`audit-text: ${option} appears more than once`);
      return 2;
    }
    seenOptions.add(option);
    if (option === "--no-front-matter") {
      frontMatter = false;
      continue;
    }
    const value = argv[index + 1];
    if (!value || value.startsWith("--")) {
      const expected = option === "--json" ? "an output file" : "a directory";
      stderr(`audit-text: ${option} requires ${expected}`);
      return 2;
    }
    if (option === "--json") {
      jsonPath = value;
    } else {
      projectDir = value;
    }
    index++;
  }

  try {
    const findings = auditTarget(target, projectDir, readFileSync, { frontMatter });
    for (const path of findings.skipped) {
      stderr(`warning: skipped unreadable entry: ${path}`);
    }
    if (jsonPath !== undefined) {
      writeFileSync(jsonPath, JSON.stringify(findings, null, 2));
    }
    stdout(formatFindings(findings));
    return 0;
  } catch (error) {
    stderr(`audit-text: ${error instanceof Error ? error.message : String(error)}`);
    return 1;
  }
}
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall