@sfqa/scar 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,14 @@
+// packages/scar/src/index.ts - public surface of the scar-tissue reviewer.
+export * from './types.js';
+export * from './rules.js';
+export * from './scan.js';
+export * from './report.js';
+export * from './redact.js';
+export * from './hash.js';
+export * from './ignore.js';
+export * from './capture.js';
+export * from './local.js';
+export * from './harvest.js';
+export * from './cli.js';
+export * from './prove.js';
+export * from './new-rule.js';

package/dist/local.d.ts

@@ -0,0 +1,17 @@
+export type ReportFormat = 'auto' | 'playwright' | 'junit';
+export interface LocalFailure {
+    test: string;
+    file: string | null;
+    status: string;
+    message: string;
+    occurrences: number;
+    fingerprint: string;
+    ignoredAt?: string;
+    ignoreReason?: string;
+}
+/**
+ * Read one or more report paths (file or directory) and merge duplicate
+ * failures. Duplicates are the signal: the same test failing in four runs is a
+ * stronger candidate than a one-off.
+ */
+export declare function readLocalReports(paths: readonly string[], format?: ReportFormat, cwd?: string): LocalFailure[];

package/dist/local.js

@@ -0,0 +1,163 @@
+// packages/scar/src/local.ts
+// -----------------------------------------------------------------------------
+// Local-run harvesting. Git history shows the failures a team already fixed;
+// a test report shows the failures it is currently living with. This reads the
+// two formats most runners emit - Playwright JSON and JUnit XML - and turns
+// repeated failures into briefs, not rules: a runtime error is not yet a
+// source pattern.
+// -----------------------------------------------------------------------------
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { extname, join, resolve } from 'node:path';
+import { fingerprint } from './hash.js';
+import { redactText } from './redact.js';
+const FAILED_STATUSES = new Set(['failed', 'timedOut', 'interrupted', 'error']);
+function readReportFiles(path, output = []) {
+    let stat;
+    try {
+        stat = statSync(path);
+    }
+    catch {
+        return output;
+    }
+    if (stat.isDirectory()) {
+        for (const entry of readdirSync(path, { withFileTypes: true })) {
+            if (entry.name === 'node_modules' || entry.name === '.git')
+                continue;
+            readReportFiles(join(path, entry.name), output);
+        }
+    }
+    else if (/\.(json|xml)$/i.test(path)) {
+        output.push(path);
+    }
+    return output;
+}
+/** Very small XML entity decoder - enough for JUnit attributes and text. */
+function decodeXml(value) {
+    return value
+        .replace(/"/g, '"')
+        .replace(/'/g, "'")
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&#10;/g, '\n')
+        .replace(/&amp;/g, '&');
+}
+function attr(attrs, name) {
+    const match = new RegExp(`(?:^|\\s)${name}\\s*=\\s*("([^"]*)"|'([^']*)')`).exec(attrs);
+    return match ? decodeXml(match[2] ?? match[3] ?? '') : null;
+}
+function stripTags(value) {
+    return value.replace(/<[^>]+>/g, '').trim();
+}
+function parseJUnit(xml) {
+    const failures = [];
+    const testcase = /<testcase\b([^>]*)>([\s\S]*?)<\/testcase>|<testcase\b([^>]*)\/>/g;
+    let match;
+    while ((match = testcase.exec(xml)) !== null) {
+        const attrs = match[1] ?? match[3] ?? '';
+        const body = match[2] ?? '';
+        if (!/<(failure|error)\b/.test(body))
+            continue;
+        const blocking = /<(failure|error)\b([^>]*)>([\s\S]*?)<\/\1>/.exec(body);
+        const selfClosing = /<(failure|error)\b([^>]*)\/>/.exec(body);
+        const failureAttrs = blocking?.[2] ?? selfClosing?.[2] ?? '';
+        const failureBody = blocking?.[3] ?? '';
+        const name = attr(attrs, 'name') ?? 'unnamed test';
+        const classname = attr(attrs, 'classname') ?? '';
+        const test = classname && classname !== name ? `${classname} > ${name}` : name;
+        const message = attr(failureAttrs, 'message') ?? (stripTags(failureBody) || 'failed without a message');
+        failures.push({
+            test,
+            file: attr(attrs, 'file'),
+            status: 'failed',
+            message: redactText(message).trim().slice(0, 500),
+        });
+    }
+    return failures;
+}
+function walkPlaywright(suite, output) {
+    for (const spec of suite.specs ?? []) {
+        for (const test of spec.tests ?? []) {
+            for (const result of test.results ?? []) {
+                if (!result.status || !FAILED_STATUSES.has(result.status))
+                    continue;
+                output.push({
+                    test: [suite.title, spec.title, test.title].filter(Boolean).join(' > ') || 'unnamed test',
+                    file: spec.file ?? suite.file ?? null,
+                    status: result.status,
+                    message: redactText(result.error?.message ?? 'failed without a message')
+                        .trim()
+                        .slice(0, 500),
+                });
+            }
+        }
+    }
+    for (const child of suite.suites ?? [])
+        walkPlaywright(child, output);
+}
+function parsePlaywright(data) {
+    if (!data || typeof data !== 'object')
+        return [];
+    const suites = data.suites;
+    if (!Array.isArray(suites))
+        return [];
+    const failures = [];
+    for (const suite of suites)
+        walkPlaywright(suite, failures);
+    return failures;
+}
+function parseReport(path, format) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const trimmed = text.trimStart();
+    const detected = format !== 'auto'
+        ? format
+        : trimmed.startsWith('<')
+            ? 'junit'
+            : trimmed.startsWith('{')
+                ? 'playwright'
+                : null;
+    if (detected === 'junit')
+        return parseJUnit(text);
+    if (detected === 'playwright') {
+        try {
+            return parsePlaywright(JSON.parse(text));
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
+/**
+ * Read one or more report paths (file or directory) and merge duplicate
+ * failures. Duplicates are the signal: the same test failing in four runs is a
+ * stronger candidate than a one-off.
+ */
+export function readLocalReports(paths, format = 'auto', cwd = process.cwd()) {
+    const raw = [];
+    for (const path of paths) {
+        for (const file of readReportFiles(resolve(cwd, path))) {
+            raw.push(...parseReport(file, format));
+        }
+    }
+    const merged = new Map();
+    for (const failure of raw) {
+        const key = `${failure.test}\n${failure.file ?? ''}\n${failure.message}`;
+        const existing = merged.get(key);
+        if (existing) {
+            existing.occurrences += 1;
+            continue;
+        }
+        merged.set(key, {
+            ...failure,
+            occurrences: 1,
+            fingerprint: `test:${fingerprint([failure.test, failure.file ?? '', failure.message])}`,
+        });
+    }
+    return [...merged.values()];
+}

package/dist/new-rule.d.ts

@@ -0,0 +1,39 @@
+import type { Severity } from './types.js';
+export declare class ScaffoldError extends Error {
+    constructor(message: string);
+}
+export interface ScaffoldOptions {
+    /** The rule in one imperative sentence: what must not happen again. */
+    title: string;
+    /** Glob(s) the rule is allowed to fire in. The fixture is placed to match. */
+    scope: readonly string[];
+    severity?: Severity;
+    id?: string;
+    rulesPath: string;
+    fixtureRoot: string;
+    cwd: string;
+}
+export interface ScaffoldResult {
+    id: string;
+    rulesPath: string;
+    positivePath: string;
+    negativePath: string;
+    /** Fixture paths when --scope was given more than once. */
+    otherFixtures: string[];
+    createdRuleFile: boolean;
+    nextSteps: string[];
+}
+/**
+ * Where the fixture has to live: the literal directory in front of the first
+ * wildcard, plus the scope's own extension. A fixture outside this path is never
+ * scanned, which is the failure mode people hit when they place it by hand.
+ */
+export declare function fixtureRelativePath(rawScope: string, id: string): string;
+/**
+ * People write `--scope test-pages/` when they mean "everything under it". A
+ * literal path with no wildcard would scope the rule to one file that does not
+ * exist yet, so a trailing slash or an existing directory becomes a subtree.
+ */
+export declare function normaliseScope(entry: string): string;
+export declare function scaffoldRule(options: ScaffoldOptions): ScaffoldResult;
+export declare function formatScaffold(result: ScaffoldResult): string;

package/dist/new-rule.js

@@ -0,0 +1,209 @@
+// packages/scar/src/new-rule.ts
+// -----------------------------------------------------------------------------
+// Scaffolding one rule. The two steps people get wrong are mechanical, not
+// thoughtful: picking an id, and putting the fixture where the rule actually
+// looks. This does both, then prints the three things left to a person.
+//
+// It writes a skeleton, never an enforced rule: the pattern starts empty, so the
+// proof reports the rule as a gap until someone supplies a detector.
+// -----------------------------------------------------------------------------
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { globToRegex } from './rules.js';
+import { relPosix, walk } from './scan.js';
+const ID_SHAPE = /^[A-Z]+-\d+$/;
+export class ScaffoldError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ScaffoldError';
+    }
+}
+function readRuleSet(path) {
+    if (!existsSync(path)) {
+        return { ruleSet: { version: 1, description: 'Scar tissue this repository has paid for.', rules: [] }, created: true };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new ScaffoldError(`${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const candidate = raw;
+    if (!candidate || typeof candidate !== 'object' || !Array.isArray(candidate.rules)) {
+        throw new ScaffoldError(`${path} has no "rules" array`);
+    }
+    return { ruleSet: candidate, created: false };
+}
+/** Next free id for the prefix already used in this rule set (ST by default). */
+function nextId(rules, requested) {
+    if (requested) {
+        if (!ID_SHAPE.test(requested))
+            throw new ScaffoldError(`--id must look like "ST-020", got "${requested}"`);
+        if (rules.some((rule) => rule.id === requested))
+            throw new ScaffoldError(`${requested} already exists in this rule set`);
+        return requested;
+    }
+    const used = rules.map((rule) => /^([A-Z]+)-(\d+)$/.exec(rule.id)).filter(Boolean);
+    const prefix = used.length > 0 ? used[0][1] : 'ST';
+    const highest = used
+        .filter((match) => match[1] === prefix)
+        .reduce((max, match) => Math.max(max, Number(match[2])), 0);
+    return `${prefix}-${String(highest + 1).padStart(3, '0')}`;
+}
+/**
+ * Where the fixture has to live: the literal directory in front of the first
+ * wildcard, plus the scope's own extension. A fixture outside this path is never
+ * scanned, which is the failure mode people hit when they place it by hand.
+ */
+export function fixtureRelativePath(rawScope, id) {
+    const scope = rawScope.replace(/^\.\//, '');
+    const wildcard = scope.search(/[*?[{]/);
+    if (wildcard === -1)
+        return scope.replace(/^\/+/, '');
+    const literal = scope.slice(0, wildcard);
+    const directory = literal.endsWith('/') ? literal.slice(0, -1) : dirname(literal);
+    // Prefer the extension the scope names (`features/**/*.feature`), then the
+    // one on a literal suffix (`playwright.config.ts`), then TypeScript.
+    const extension = /\*\.([a-z0-9]{1,8})(?![a-z0-9])/i.exec(scope)?.[1] ??
+        /\.([a-z0-9]{1,8})$/.exec(scope)?.[1] ??
+        // `features/**` names no extension, and a .ts file there is never run.
+        (/\bfeatures\b/.test(directory) ? 'feature' : 'ts');
+    const file = `${id.toLowerCase()}.${extension}`;
+    return directory && directory !== '.' ? `${directory}/${file}` : file;
+}
+/** `#` for features and markdown, `//` for code. Keep the fixture valid in its language. */
+function commentFor(path) {
+    return /\.(feature|md|ya?ml|sh|py|rb)$/.test(path) ? '#' : '//';
+}
+/**
+ * People write `--scope test-pages/` when they mean "everything under it". A
+ * literal path with no wildcard would scope the rule to one file that does not
+ * exist yet, so a trailing slash or an existing directory becomes a subtree.
+ */
+export function normaliseScope(entry) {
+    const trimmed = entry.replace(/^\.\//, '').replace(/\/+$/, '');
+    if (!trimmed)
+        throw new ScaffoldError('--scope cannot be the repository root; name a directory');
+    const wildcard = /[*?[{]/.test(trimmed);
+    const looksLikeFile = /\.[a-z0-9]{1,8}$/i.test(trimmed);
+    if (wildcard || looksLikeFile)
+        return trimmed;
+    return `${trimmed}/**`;
+}
+/**
+ * A scope that matches nothing today is usually a typo (`test-page/`), and the
+ * proof cannot catch it: the fixture is placed to match the same wrong scope, so
+ * it fires while the rule never sees a real file. Count what is really there and
+ * say so.
+ */
+function filesInScope(cwd, scope, fixtureRoot) {
+    const matchers = scope.map(globToRegex);
+    const root = resolve(cwd);
+    const skipFixture = resolve(cwd, fixtureRoot);
+    let count = 0;
+    for (const file of walk(root)) {
+        if (file.startsWith(skipFixture))
+            continue;
+        const rel = relPosix(root, file);
+        if (matchers.some((matcher) => matcher.test(rel)))
+            count++;
+    }
+    return count;
+}
+export function scaffoldRule(options) {
+    const title = options.title.trim();
+    if (!title)
+        throw new ScaffoldError('--rule needs the rule in one sentence');
+    if (options.scope.length === 0) {
+        throw new ScaffoldError('--scope is required: the rule needs a place it can fire, and the fixture is placed to match it. Try: --scope "test-pages/"');
+    }
+    const rulesPath = resolve(options.cwd, options.rulesPath);
+    const { ruleSet, created } = readRuleSet(rulesPath);
+    const id = nextId(ruleSet.rules, options.id);
+    // Running `new` twice with the same sentence is a duplicate, not a second rule.
+    const sameSentence = ruleSet.rules.find((rule) => rule.rule.trim().toLowerCase() === title.toLowerCase());
+    if (sameSentence) {
+        throw new ScaffoldError(`${sameSentence.id} already says that: "${sameSentence.rule}". Edit it with --id ${sameSentence.id}, or write a different rule.`);
+    }
+    const scope = options.scope.map(normaliseScope);
+    const positiveRels = scope.map((entry) => fixtureRelativePath(entry, id));
+    const negativeRels = positiveRels.map((rel) => rel);
+    const fixtureRoot = resolve(options.cwd, options.fixtureRoot);
+    const positivePaths = positiveRels.map((rel) => join(fixtureRoot, 'positive', rel));
+    const negativePaths = negativeRels.map((rel) => join(fixtureRoot, 'negative', rel));
+    for (const target of [...positivePaths, ...negativePaths]) {
+        if (existsSync(target))
+            throw new ScaffoldError(`${relPosix(options.cwd, target)} already exists - refusing to overwrite it`);
+    }
+    const rule = {
+        id,
+        rule: title,
+        context: `Files matching ${scope.join(', ')}. TODO: name the objects or helpers this applies to.`,
+        origin: {
+            commit: null,
+            pr: null,
+            summary: 'TODO: what broke, and what it cost. Keep the detail that makes the rule defensible.',
+        },
+        severity: options.severity ?? 'med',
+        detection_pattern: 'TODO: what a reviewer should look for, in concrete syntax.',
+        match: { pathInclude: scope, linePatterns: [] },
+        recommendation: 'TODO: the fix that worked, specific enough to paste.',
+    };
+    ruleSet.rules.push(rule);
+    mkdirSync(dirname(rulesPath), { recursive: true });
+    writeFileSync(rulesPath, `${JSON.stringify(ruleSet, null, 2)}\n`, 'utf8');
+    positivePaths.forEach((positivePath, index) => {
+        const negativePath = negativePaths[index];
+        const marker = commentFor(positiveRels[index]);
+        mkdirSync(dirname(positivePath), { recursive: true });
+        mkdirSync(dirname(negativePath), { recursive: true });
+        writeFileSync(positivePath, `${marker} ${id} positive fixture: the bad line goes here.\n${marker} The rule must fire on it. Delete these comments once it does.\n`, 'utf8');
+        writeFileSync(negativePath, `${marker} ${id} clean fixture: the same code with the fix applied.\n${marker} The rule must fire zero times here. Delete these comments once it stays silent.\n`, 'utf8');
+    });
+    const inScope = filesInScope(options.cwd, scope, options.fixtureRoot);
+    const shownRules = relPosix(options.cwd, rulesPath);
+    const shownPositive = relPosix(options.cwd, positivePaths[0]);
+    const shownNegative = relPosix(options.cwd, negativePaths[0]);
+    const scopeHint = scope.join(', ');
+    return {
+        id,
+        rulesPath: shownRules,
+        positivePath: shownPositive,
+        negativePath: shownNegative,
+        otherFixtures: positivePaths
+            .slice(1)
+            .flatMap((positivePath, index) => [
+            relPosix(options.cwd, positivePath),
+            relPosix(options.cwd, negativePaths[index + 1]),
+        ]),
+        createdRuleFile: created,
+        nextSteps: [
+            `open ${shownRules}, replace the TODOs, and put the pattern in match.linePatterns`,
+            `not sure of the pattern? prompts/turn-incident-into-rule.md (in the package) drafts it from the incident`,
+            `paste the bad line into ${shownPositive}`,
+            `paste the same code with the fix into ${shownNegative}`,
+            `prove just this rule: sfqa-scar prove --id ${id}`,
+            `it is scoped to ${scopeHint}; a fixture outside that path is never scanned`,
+            ...(inScope === 0
+                ? [
+                    `warning: nothing in this repo matches ${scopeHint} yet. If that is a typo, the rule will never fire - delete it with --id ${id} and start again`,
+                ]
+                : []),
+        ],
+    };
+}
+export function formatScaffold(result) {
+    const lines = [];
+    lines.push(`created ${result.id}${result.createdRuleFile ? ` (new rule file)` : ''}`);
+    lines.push('');
+    lines.push(`  rule      ${result.rulesPath}`);
+    lines.push(`  positive  ${result.positivePath}`);
+    lines.push(`  clean     ${result.negativePath}`);
+    for (const other of result.otherFixtures)
+        lines.push(`  also      ${other}`);
+    lines.push('');
+    lines.push('what to do next');
+    result.nextSteps.forEach((step, index) => lines.push(`  ${index + 1}. ${step}`));
+    return lines.join('\n');
+}

package/dist/prove.d.ts

@@ -0,0 +1,37 @@
+import type { ScarRule, Severity } from './types.js';
+/** Where `new` writes fixtures and `prove` reads them, unless told otherwise. */
+export declare const DEFAULT_FIXTURE_ROOT = "scar-fixtures";
+export declare class ProveError extends Error {
+    constructor(message: string);
+}
+export interface RuleProof {
+    id: string;
+    severity: Severity;
+    /** False when the rule has no machine detector: it cannot fire by design. */
+    executable: boolean;
+    positive: 'fires' | 'missing' | 'n/a';
+    clean: 'clean' | 'leak' | 'n/a';
+    pathInclude: string[];
+}
+export interface ProofResult {
+    fixtureRoot: string;
+    executable: number;
+    gaps: number;
+    covered: number;
+    proofs: RuleProof[];
+    /** True only when every executable rule fires and the clean set leaks nothing. */
+    passed: boolean;
+}
+/**
+ * Run every selected rule against the fixture pair.
+ * `ids` limits the run to particular rules, which is what `--id` uses after
+ * `new` so a person sees one verdict instead of nineteen.
+ */
+export declare function proveRules(rules: readonly ScarRule[], fixtureRoot: string, ids?: readonly string[]): ProofResult;
+/**
+ * The table the proof has printed since v0.1, plus one addition: when a rule
+ * has a detector but no fixture made it fire, the scope is printed. Without it
+ * the person has to guess which directory the fixture belongs in, and puts it
+ * somewhere the rule never looks.
+ */
+export declare function formatProof(result: ProofResult, ruleSet: string, total: number, fixtureRoot?: string): string;

package/dist/prove.js

@@ -0,0 +1,158 @@
+// packages/scar/src/prove.ts
+// -----------------------------------------------------------------------------
+// The proof. One fixture that must fire per rule, one clean set that must stay
+// silent. A rule with no detector is reported as a gap, never counted as
+// coverage - a rule that cannot fire is worse than a missing rule, because it
+// buys trust it has not earned.
+//
+// This lives in the package, not only in this repository's harness, so someone
+// who installed @sfqa/scar can prove the rules they write without cloning
+// anything. `sfqa-scar prove` is the command; `npm run validate:scar` is the
+// same code path.
+// -----------------------------------------------------------------------------
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { compileRule, isExecutable } from './rules.js';
+import { lintContent, relPosix, walk } from './scan.js';
+/** Where `new` writes fixtures and `prove` reads them, unless told otherwise. */
+export const DEFAULT_FIXTURE_ROOT = 'scar-fixtures';
+export class ProveError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProveError';
+    }
+}
+function readFixtures(dir) {
+    if (!existsSync(dir))
+        return [];
+    return walk(dir).map((file) => ({
+        rel: relPosix(dir, file),
+        content: readFileSync(file, 'utf8'),
+    }));
+}
+/**
+ * Run every selected rule against the fixture pair.
+ * `ids` limits the run to particular rules, which is what `--id` uses after
+ * `new` so a person sees one verdict instead of nineteen.
+ */
+export function proveRules(rules, fixtureRoot, ids = []) {
+    const root = resolve(fixtureRoot);
+    const positiveDir = join(root, 'positive');
+    const negativeDir = join(root, 'negative');
+    const positive = readFixtures(positiveDir);
+    const negative = readFixtures(negativeDir);
+    if (positive.length === 0 && negative.length === 0) {
+        throw new ProveError(`no fixtures under ${fixtureRoot}. Expected ${fixtureRoot}/positive/ and ${fixtureRoot}/negative/. Create the first pair with: sfqa-scar new --rule "what must not happen again"`);
+    }
+    const selected = ids.length > 0 ? rules.filter((rule) => ids.includes(rule.id)) : [...rules];
+    if (ids.length > 0) {
+        const known = new Set(rules.map((rule) => rule.id));
+        const unknown = ids.filter((id) => !known.has(id));
+        if (unknown.length > 0) {
+            throw new ProveError(`no rule with id ${unknown.join(', ')} in this rule set`);
+        }
+    }
+    const proofs = selected.map((rule) => {
+        const executable = isExecutable(rule);
+        const pathInclude = rule.match?.pathInclude ?? [];
+        if (!executable) {
+            return {
+                id: rule.id,
+                severity: rule.severity,
+                executable,
+                positive: 'n/a',
+                clean: 'n/a',
+                pathInclude,
+            };
+        }
+        const compiled = compileRule(rule);
+        const fires = positive.some((fixture) => lintContent(fixture.rel, fixture.content, [compiled]).length > 0);
+        const leaks = negative.some((fixture) => lintContent(fixture.rel, fixture.content, [compiled]).length > 0);
+        return {
+            id: rule.id,
+            severity: rule.severity,
+            executable,
+            positive: fires ? 'fires' : 'missing',
+            clean: leaks ? 'leak' : 'clean',
+            pathInclude,
+        };
+    });
+    const executable = proofs.filter((proof) => proof.executable).length;
+    const covered = proofs.filter((proof) => proof.positive === 'fires').length;
+    const gaps = selected.length - executable;
+    // A gap is reported, never counted as a pass. But a rule set where nothing
+    // can fire is not "0 failures" - it is a rule set that proves nothing, and
+    // saying PROOF over it would be the exact false confidence this tool exists to
+    // remove. So passing requires no missing, no leak, and at least one fire.
+    const passed = covered > 0 &&
+        proofs.every((proof) => !proof.executable || (proof.positive === 'fires' && proof.clean === 'clean'));
+    return { fixtureRoot, executable, gaps, covered, proofs, passed };
+}
+function pad(text, width) {
+    return text.length >= width ? text : text + ' '.repeat(width - text.length);
+}
+/**
+ * The table the proof has printed since v0.1, plus one addition: when a rule
+ * has a detector but no fixture made it fire, the scope is printed. Without it
+ * the person has to guess which directory the fixture belongs in, and puts it
+ * somewhere the rule never looks.
+ */
+export function formatProof(result, ruleSet, total, fixtureRoot = result.fixtureRoot) {
+    const lines = [];
+    lines.push(`sfqa-scar prove - ${total} rule(s), ${result.executable} executable`);
+    lines.push(`rule set: ${ruleSet}`);
+    lines.push(`fixtures: ${fixtureRoot}`);
+    lines.push('');
+    lines.push('rule    severity  detector   positive   clean');
+    lines.push('------  --------  ---------  ---------  -------');
+    for (const proof of result.proofs) {
+        const id = pad(proof.id, 6);
+        const severity = pad(proof.severity, 8);
+        const detector = pad(proof.executable ? 'yes' : 'NO', 9);
+        const positive = pad(proof.positive, 9);
+        lines.push(`${id}  ${severity}  ${detector}  ${positive}  ${proof.clean}`);
+    }
+    lines.push('');
+    const missing = result.proofs.filter((proof) => proof.positive === 'missing');
+    const leaks = result.proofs.filter((proof) => proof.clean === 'leak');
+    const gaps = result.proofs.filter((proof) => !proof.executable);
+    if (gaps.length > 0) {
+        lines.push(`GAPS (no machine detector, cannot fire): ${gaps.map((p) => p.id).join(', ')}`);
+        lines.push('  These rules are documentation until a detector is added.');
+        for (const gap of gaps) {
+            const where = gap.pathInclude.length > 0 ? gap.pathInclude.join(', ') : 'no path scope';
+            lines.push(`  ${gap.id} is scoped to: ${where}`);
+        }
+        lines.push('');
+    }
+    if (missing.length > 0) {
+        lines.push(`MISSING (detector exists but no fixture made it fire): ${missing.map((p) => p.id).join(', ')}`);
+        for (const proof of missing) {
+            const where = proof.pathInclude.length > 0 ? proof.pathInclude.join(', ') : 'any file';
+            lines.push(`  ${proof.id} is scoped to: ${where}`);
+            lines.push(`  put a file containing the bad line under ${result.fixtureRoot}/positive/ so it matches that scope`);
+        }
+        lines.push('  A fixture outside the scope is never scanned by the rule.');
+        lines.push('');
+    }
+    if (leaks.length > 0) {
+        lines.push(`FALSE POSITIVES on the clean set: ${leaks.map((p) => p.id).join(', ')}`);
+        for (const proof of leaks.filter((p) => p.clean === 'leak')) {
+            lines.push(`  ${proof.id} matched a file under ${result.fixtureRoot}/negative/ - either the clean fixture still contains the bad shape, or the pattern is too wide`);
+        }
+        lines.push('');
+    }
+    if (result.passed) {
+        lines.push(`PROOF: ${result.covered}/${result.executable} executable rules fire on a positive fixture and stay silent on the clean set.`);
+        lines.push(`Coverage: ${result.covered}/${total} rules enforced today; ${result.gaps} rule(s) have no detector.`);
+    }
+    else if (result.covered === 0) {
+        lines.push('FAIL: no rule fired on a positive fixture, so nothing is proven.');
+        lines.push('  The usual cause is an empty detector: a scaffolded rule keeps `linePatterns: []` until you fill it.');
+        lines.push('  Add a pattern under match.linePatterns, or delete the rule - an unproved rule is a comment.');
+    }
+    else {
+        lines.push(`FAIL: ${missing.length} missing, ${leaks.length} false positive(s).`);
+    }
+    return lines.join('\n');
+}

package/dist/redact.d.ts

@@ -0,0 +1,3 @@
+export declare function redactLine(line: string): string;
+export declare function redactText(text: string): string;
+export declare function isSecretShaped(line: string): boolean;

package/dist/redact.js

@@ -0,0 +1,20 @@
+// packages/scar/src/redact.ts
+// -----------------------------------------------------------------------------
+// Discovery reads failures, and failures sometimes contain the secret that
+// caused them. Nothing from a credential-shaped line reaches stdout, a JSON
+// report or a draft. The name stays; the value is replaced.
+// -----------------------------------------------------------------------------
+const SECRET_NAME = /\b(password|passwd|pwd|secret|token|api[_-]?key|apikey|credential|authorization|bearer|private[_-]?key|access[_-]?key)\b/i;
+export function redactLine(line) {
+    if (!SECRET_NAME.test(line))
+        return line;
+    return line
+        .replace(/(['"])([^'"\n]{2,})\1/g, '$1<redacted>$1')
+        .replace(/(=\s*)([^\s;,'"]+)/, '$1<redacted>');
+}
+export function redactText(text) {
+    return text.split('\n').map(redactLine).join('\n');
+}
+export function isSecretShaped(line) {
+    return redactLine(line) !== line;
+}