GaZmagik/iso-24495 / skills/iso-24495-text-audit
iso-24495-text-audit
VerifiedAudit user-selected Markdown or text files for deterministic plain-language findings. Use only when the user explicitly invokes this skill.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.2 KB |
| agents/openai.yaml | config | 270 B |
| scripts/audit-text-cli.ts | script | 107 B |
| scripts/audit-text.ts | script | 5.0 KB |
scripts/audit-text.ts
View on GitHubimport { 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;
}
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |