@dailephd/my-dev-kit-lab 0.2.2 → 0.3.1

package/dist/src/audits/report/auditReportModel.js

@@ -0,0 +1,253 @@
+import { getHighestSeverity, AUDIT_EXIT_CODES } from "../core/auditExitCode.js";
+import { DEFAULT_AUDIT_REGISTRY, selectDetectors } from "../core/auditRegistry.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 5 — stable, versioned audit report model.
+//
+// Pure transform: AuditResult (+ the richer AuditTarget the CLI script
+// already has in scope) -> AuditReportModel. No I/O here (that lives in
+// writeAuditReports.ts). This is what replaces the inline
+// buildJsonReport()/renderMinimalTextSummary()/summarizeInventory()/
+// summarizeSourceOfTruth() functions that previously lived directly in
+// scripts/audits/runAudit.ts (Batch 1/2) -- the summarize* condensing logic
+// is preserved verbatim here (inventory/sourceOfTruth shapes are unchanged,
+// see spec 3.2 "inventory"/"sourceOfTruth" sections), just relocated so the
+// CLI script can stay thin.
+// ---------------------------------------------------------------------------
+export const AUDIT_REPORT_SCHEMA_VERSION = "1.0";
+export function summarizeInventory(inventory) {
+    return {
+        targetRoot: inventory.targetRoot,
+        totalFileCount: inventory.totalFileCount,
+        totalScannedFileCount: inventory.totalScannedFileCount,
+        skippedFileCount: inventory.skippedFileCount,
+        filesByCategory: inventory.filesByCategory,
+        filesByExtension: inventory.filesByExtension,
+        filesByLanguage: inventory.filesByLanguage,
+        filesByRole: inventory.filesByRole,
+        excludedDirectorySummary: inventory.excludedDirectorySummary,
+        warnings: inventory.warnings,
+    };
+}
+export function summarizeSourceOfTruth(sourceOfTruth) {
+    const scriptCountByGroup = Object.fromEntries(Object.entries(sourceOfTruth.commands.scriptsByGroup).map(([group, names]) => [group, names.length]));
+    const nodeVersionsReferenced = [
+        ...new Set(sourceOfTruth.ci.workflows.flatMap((w) => w.nodeVersionsReferenced)),
+    ].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+    return {
+        packageName: sourceOfTruth.package?.name ?? null,
+        packageVersion: sourceOfTruth.package?.version ?? null,
+        scriptCountByGroup,
+        hasReadme: sourceOfTruth.docs.hasReadme,
+        hasChangelog: sourceOfTruth.docs.hasChangelog,
+        docsFileCount: sourceOfTruth.docs.files.length,
+        ciWorkflowCount: sourceOfTruth.ci.workflows.length,
+        nodeVersionsReferenced,
+        buildTooling: sourceOfTruth.buildTooling,
+        tests: sourceOfTruth.tests,
+        security: sourceOfTruth.security,
+        experiment: sourceOfTruth.experiment,
+        warnings: sourceOfTruth.warnings,
+    };
+}
+export function summarizeSourceFacts(sourceFacts) {
+    return {
+        totalFilesAnalyzed: sourceFacts.files.length,
+        filesByLanguage: sourceFacts.filesByLanguage,
+        filesByParseStatus: sourceFacts.filesByParseStatus,
+        analyzerDiagnosticCount: sourceFacts.analyzerDiagnostics.length,
+        warnings: sourceFacts.warnings,
+    };
+}
+const MAX_JSON_RECOMMENDATIONS = 200;
+const MAX_TEXT_RECOMMENDATIONS = 10;
+const SEVERITY_ORDER = ["blocker", "high", "medium", "low", "info"];
+function severityRankForSort(severity) {
+    return SEVERITY_ORDER.indexOf(severity);
+}
+// Aggregates AuditIssue.recommendedAction strings: dedupes identical text,
+// tracks which issues/detectors map to each, sorts blocker/high-severity
+// recommendations first (stable by highest severity among contributing
+// issues, then by first-occurrence order). Only derives text from actual
+// issue.recommendedAction fields -- never invents new recommendation text.
+export function buildRecommendations(issues) {
+    const byText = new Map();
+    issues.forEach((issue, index) => {
+        const text = issue.recommendedAction;
+        const existing = byText.get(text);
+        if (existing) {
+            if (!existing.detectorIds.includes(issue.detectorId))
+                existing.detectorIds.push(issue.detectorId);
+            existing.issueIds.push(issue.id);
+            if (severityRankForSort(issue.severity) < severityRankForSort(existing.highestSeverity)) {
+                existing.highestSeverity = issue.severity;
+            }
+            return;
+        }
+        byText.set(text, {
+            text,
+            detectorIds: [issue.detectorId],
+            issueIds: [issue.id],
+            highestSeverity: issue.severity,
+            firstIndex: index,
+        });
+    });
+    const all = [...byText.values()].sort((a, b) => {
+        const rankDiff = severityRankForSort(a.highestSeverity) - severityRankForSort(b.highestSeverity);
+        if (rankDiff !== 0)
+            return rankDiff;
+        return a.firstIndex - b.firstIndex;
+    });
+    return all.slice(0, MAX_JSON_RECOMMENDATIONS).map(({ firstIndex: _firstIndex, ...rec }) => rec);
+}
+export { MAX_TEXT_RECOMMENDATIONS };
+// Precedence (documented per spec 3.7): a fail-on breach is always the
+// primary label when both a breach AND detector errors are present, because
+// the process exit code (what actually blocks automation) is driven by the
+// breach, not by detector errors. "detector errors" is only ever the primary
+// label when there is no breach -- callers that want to know about detector
+// errors independently of the primary label should check
+// summary.detectorErrorCount directly (always present regardless of which
+// verdict label won).
+export function computeVerdictLabel(result, breached) {
+    if (breached)
+        return "fail-on threshold breached";
+    if (result.detectorErrors.length > 0)
+        return "detector errors";
+    if (result.issues.length === 0)
+        return "no issues";
+    return "issues found below fail-on threshold";
+}
+export function categorizeDetectorError(message) {
+    if (/ENOENT|no such file|ENOTDIR|EACCES|EPERM/i.test(message))
+        return "filesystem";
+    if (/JSON|unexpected token|parse/i.test(message))
+        return "parse";
+    return "unknown";
+}
+export function buildAuditReportModel(result, opts) {
+    const registry = opts.registry ?? DEFAULT_AUDIT_REGISTRY;
+    const generatedAt = opts.generatedAt ?? new Date().toISOString();
+    const command = opts.command ?? reconstructCommand(result);
+    const issues = result.issues;
+    const breached = result.exitCode === AUDIT_EXIT_CODES.THRESHOLD_BREACHED;
+    const verdictLabel = computeVerdictLabel(result, breached);
+    const issuesByConfidence = countBy(issues, (i) => i.confidence, ["high", "medium", "low"]);
+    const issuesByFalsePositiveRisk = countBy(issues, (i) => i.falsePositiveRisk, ["high", "medium", "low"]);
+    const issuesByDetector = {};
+    for (const issue of issues) {
+        issuesByDetector[issue.detectorId] = (issuesByDetector[issue.detectorId] ?? 0) + 1;
+    }
+    const detectors = buildDetectorReportEntries(registry, result);
+    const selectedDetectorCount = detectors.filter((d) => d.status === "selected" || d.status === "error").length;
+    const recommendations = buildRecommendations(issues);
+    return {
+        schemaVersion: AUDIT_REPORT_SCHEMA_VERSION,
+        metadata: {
+            packageName: result.sourceOfTruth.package?.name ?? null,
+            packageVersion: result.sourceOfTruth.package?.version ?? null,
+            generatedAt,
+            command,
+            reportType: "code-rot-audit",
+            auditType: result.configSummary.types.join(","),
+            auditTypes: result.configSummary.types,
+        },
+        target: {
+            displayName: opts.target.displayName,
+            rootPath: opts.target.rootPath,
+            targetKind: opts.target.isSelf ? "self" : "external",
+            hasPackageJson: opts.target.packageJsonPath !== null,
+            hasGitRoot: opts.target.gitRoot !== null,
+        },
+        config: {
+            types: result.configSummary.types,
+            include: result.configSummary.include,
+            formats: result.configSummary.formats,
+            failOn: result.configSummary.failOn,
+            out: result.configSummary.out,
+            isDefaultRun: result.configSummary.isDefaultRun,
+        },
+        summary: {
+            totalIssues: issues.length,
+            issuesBySeverity: result.issueCounts,
+            issuesByConfidence,
+            issuesByFalsePositiveRisk,
+            issuesByDetector,
+            releaseBlockingCount: issues.filter((i) => i.releaseBlocking).length,
+            implementationBlockingCount: issues.filter((i) => i.implementationBlocking).length,
+            autoFixEligibleCount: issues.filter((i) => i.autoFixEligible).length,
+            detectorCount: registry.length,
+            selectedDetectorCount,
+            skippedDetectorCount: result.skippedDetectors.length,
+            detectorErrorCount: result.detectorErrors.length,
+            noDetectorsRegistered: selectedDetectorCount === 0,
+            highestSeverity: getHighestSeverity(issues),
+            failOnBreached: breached,
+            finalExitCode: result.exitCode,
+            finalVerdictLabel: verdictLabel,
+        },
+        inventory: summarizeInventory(result.inventory),
+        sourceOfTruth: summarizeSourceOfTruth(result.sourceOfTruth),
+        sourceFacts: summarizeSourceFacts(result.sourceFacts),
+        detectors,
+        issues,
+        skippedDetectors: result.skippedDetectors,
+        detectorErrors: result.detectorErrors.map((e) => ({ ...e, category: categorizeDetectorError(e.message) })),
+        recommendations,
+        exit: {
+            code: result.exitCode,
+            reason: result.exitReason,
+            failOnThreshold: result.configSummary.failOn,
+            breached,
+        },
+    };
+}
+function countBy(issues, selector, levels) {
+    const counts = Object.fromEntries(levels.map((l) => [l, 0]));
+    for (const issue of issues) {
+        counts[selector(issue)] += 1;
+    }
+    return counts;
+}
+function buildDetectorReportEntries(registry, result) {
+    const types = result.configSummary.types;
+    const include = result.configSummary.include;
+    const selected = new Set(selectDetectors(registry, types, include).map((d) => d.id));
+    const skippedIds = new Set(result.skippedDetectors.map((d) => d.id));
+    const erroredIds = new Set(result.detectorErrors.map((d) => d.id));
+    return registry.map((detector) => {
+        let status;
+        if (!selected.has(detector.id)) {
+            status = "excluded";
+        }
+        else if (erroredIds.has(detector.id)) {
+            status = "error";
+        }
+        else if (skippedIds.has(detector.id)) {
+            status = "skipped";
+        }
+        else {
+            status = "selected";
+        }
+        return {
+            id: detector.id,
+            auditType: detector.auditType,
+            title: detector.title,
+            supportedIncludeAreas: detector.supportedIncludeAreas,
+            status,
+            issueCount: result.issues.filter((i) => i.detectorId === detector.id).length,
+        };
+    });
+}
+function reconstructCommand(result) {
+    const parts = ["npm", "run", "audit", "--"];
+    const cfg = result.configSummary;
+    if (cfg.types.length > 0)
+        parts.push("--types", cfg.types.join(","));
+    if (cfg.include.length > 0)
+        parts.push("--include", cfg.include.join(","));
+    if (cfg.formats.length > 0)
+        parts.push("--format", cfg.formats.join(","));
+    parts.push("--fail-on", cfg.failOn);
+    parts.push("--out", cfg.out);
+    return parts.join(" ");
+}

package/dist/src/audits/report/auditReportPaths.js

@@ -0,0 +1,13 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 5 — audit report filename constants.
+//
+// Keeps the exact filenames already committed to in Batch 1/2/3/4
+// (tests/audits/auditReportInventoryOutput.test.ts,
+// tests/audits/auditCommandSmoke.test.ts,
+// tests/audits/auditCommandCodeRotSmoke.test.ts all hardcode
+// "code-rot-audit.json"/"code-rot-audit.txt") -- the Batch 5 spec's
+// "suggested" names are only suggestions; the filename convention itself is
+// unchanged, only the JSON content schema changes in this batch.
+// ---------------------------------------------------------------------------
+export const AUDIT_JSON_REPORT_FILENAME = "code-rot-audit.json";
+export const AUDIT_TEXT_REPORT_FILENAME = "code-rot-audit.txt";

package/dist/src/audits/report/renderAuditJsonReport.js

@@ -0,0 +1,30 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 5 — stable JSON report renderer.
+//
+// Pure: JSON.stringify with a fixed, explicit key order (not
+// insertion-order-dependent on how auditReportModel.ts happens to construct
+// the object) and 2-space indent. No sanitization needed here -- JSON.stringify
+// already escapes control characters into safe \u00XX sequences by spec, so
+// hostile evidence content cannot corrupt the JSON structure. See
+// sanitizeAuditText.ts's header comment for the same reasoning from the text
+// renderer's side.
+// ---------------------------------------------------------------------------
+export function renderAuditJsonReport(model) {
+    const ordered = {
+        schemaVersion: model.schemaVersion,
+        metadata: model.metadata,
+        target: model.target,
+        config: model.config,
+        summary: model.summary,
+        inventory: model.inventory,
+        sourceOfTruth: model.sourceOfTruth,
+        sourceFacts: model.sourceFacts,
+        detectors: model.detectors,
+        issues: model.issues,
+        skippedDetectors: model.skippedDetectors,
+        detectorErrors: model.detectorErrors,
+        recommendations: model.recommendations,
+        exit: model.exit,
+    };
+    return JSON.stringify(ordered, null, 2);
+}

package/dist/src/audits/report/renderAuditTextReport.js

@@ -0,0 +1,181 @@
+import { MAX_TEXT_RECOMMENDATIONS } from "./auditReportModel.js";
+import { sanitizeAuditText } from "./sanitizeAuditText.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 5 — human-readable text report renderer.
+//
+// Pure: takes an already-built AuditReportModel and renders terminal-
+// friendly text. Sanitizes any text sourced from scanned project content
+// (issue titles/descriptions/evidence excerpts, recommendedAction strings)
+// via sanitizeAuditText() so a hostile source file cannot poison the report
+// with ANSI escapes or a fake section header. Evidence excerpts are quoted
+// with a leading "> " marker precisely so a fake "===" divider or a fake
+// "[BLOCKER]"-looking line embedded in scanned content reads as quoted
+// evidence, not as a real report section (see spec 3.9/tests/audits/
+// auditReportSanitization.test.ts).
+// ---------------------------------------------------------------------------
+const SEVERITY_HEADING_ORDER = ["blocker", "high", "medium", "low", "info"];
+const MAX_EVIDENCE_PER_ISSUE = 2;
+const MAX_EXCERPT_LENGTH = 300;
+function divider(char = "=", width = 72) {
+    return char.repeat(width);
+}
+function sanitizeLine(raw) {
+    // Defensive bound even for non-excerpt text (titles/descriptions) --
+    // sanitizeAuditText() strips control chars and only truncates past
+    // maxLength, so ordinary short strings pass through unchanged. Also
+    // collapses any embedded real newlines to a single space: these fields
+    // (title/description/category/reason/message) are rendered as a single
+    // "label: value" line, so a hostile source containing a literal newline
+    // must not be allowed to inject what looks like a second, unindented
+    // report line.
+    return sanitizeAuditText(raw, 500).replace(/\r\n|\r|\n/g, " ");
+}
+// Renders a (possibly multi-line) evidence excerpt as one or more clearly
+// quoted lines, each individually prefixed with "> " -- this is what stops a
+// hostile excerpt containing an embedded newline plus a fake "===" divider
+// or a fake "[BLOCKER] ..." header line from ever appearing as a bare,
+// unindented line that could be mistaken for real report structure. Every
+// physical line of the excerpt is quoted, not just the first.
+function renderQuotedExcerpt(raw, indent) {
+    const sanitized = sanitizeAuditText(raw, MAX_EXCERPT_LENGTH);
+    return sanitized.split(/\r\n|\r|\n/).map((line) => `${indent}> ${line}`);
+}
+export function renderAuditTextReport(model) {
+    const lines = [];
+    lines.push("my-dev-kit-lab audit report");
+    lines.push(divider());
+    lines.push(`Schema version: ${model.schemaVersion}`);
+    lines.push(`Generated: ${model.metadata.generatedAt}`);
+    lines.push(`Report type: ${model.metadata.reportType} (audit type: ${model.metadata.auditType})`);
+    lines.push(`Package: ${model.metadata.packageName ?? "(none)"}@${model.metadata.packageVersion ?? "?"}`);
+    lines.push("");
+    lines.push("Target");
+    lines.push(divider("-"));
+    lines.push(`  ${sanitizeLine(model.target.displayName)} (${model.target.rootPath})`);
+    lines.push(`  kind=${model.target.targetKind} hasPackageJson=${model.target.hasPackageJson} hasGitRoot=${model.target.hasGitRoot}`);
+    lines.push("");
+    lines.push("Config");
+    lines.push(divider("-"));
+    lines.push(`  types=${model.config.types.join(",")} include=${model.config.include.join(",")}`);
+    lines.push(`  formats=${model.config.formats.join(",")} failOn=${model.config.failOn} isDefaultRun=${model.config.isDefaultRun}`);
+    lines.push(`  out=${model.config.out}`);
+    lines.push("");
+    lines.push("Detectors");
+    lines.push(divider("-"));
+    for (const d of model.detectors) {
+        lines.push(`  [${d.status.padEnd(8)}] ${d.id} (${d.auditType}) issues=${d.issueCount}`);
+    }
+    lines.push("");
+    lines.push("Inventory summary");
+    lines.push(divider("-"));
+    lines.push(`  total=${model.inventory.totalFileCount} scanned=${model.inventory.totalScannedFileCount} skipped=${model.inventory.skippedFileCount}`);
+    lines.push(`  source=${model.inventory.filesByCategory.source} tests=${model.inventory.filesByCategory.tests} docs=${model.inventory.filesByCategory.docs} package=${model.inventory.filesByCategory.package} config=${model.inventory.filesByCategory.config} scripts=${model.inventory.filesByCategory.scripts} ci=${model.inventory.filesByCategory.ci} generated=${model.inventory.filesByCategory.generated} report=${model.inventory.filesByCategory.report} unknown=${model.inventory.filesByCategory.unknown}`);
+    lines.push(`  languages: typescript=${model.inventory.filesByLanguage.typescript} javascript=${model.inventory.filesByLanguage.javascript} python=${model.inventory.filesByLanguage.python} java=${model.inventory.filesByLanguage.java} kotlin=${model.inventory.filesByLanguage.kotlin} json=${model.inventory.filesByLanguage.json} markdown=${model.inventory.filesByLanguage.markdown} yaml=${model.inventory.filesByLanguage.yaml} xml=${model.inventory.filesByLanguage.xml} toml=${model.inventory.filesByLanguage.toml} unknown=${model.inventory.filesByLanguage.unknown}`);
+    lines.push(`  roles: source=${model.inventory.filesByRole.source} test=${model.inventory.filesByRole.test} docs=${model.inventory.filesByRole.docs} config=${model.inventory.filesByRole.config} package=${model.inventory.filesByRole.package} generated=${model.inventory.filesByRole.generated} build-output=${model.inventory.filesByRole["build-output"]} vendor=${model.inventory.filesByRole.vendor} report-output=${model.inventory.filesByRole["report-output"]} unknown=${model.inventory.filesByRole.unknown}`);
+    if (model.inventory.warnings.length > 0) {
+        lines.push(`  warnings: ${model.inventory.warnings.length}`);
+    }
+    lines.push("");
+    lines.push("Source facts summary");
+    lines.push(divider("-"));
+    lines.push(`  analyzed=${model.sourceFacts.totalFilesAnalyzed}`);
+    lines.push(`  parsed=${model.sourceFacts.filesByParseStatus.parsed} file-level-only=${model.sourceFacts.filesByParseStatus["file-level-only"]} unsupported=${model.sourceFacts.filesByParseStatus.unsupported} parse-error=${model.sourceFacts.filesByParseStatus["parse-error"]} skipped=${model.sourceFacts.filesByParseStatus.skipped}`);
+    if (model.sourceFacts.analyzerDiagnosticCount > 0) {
+        lines.push(`  analyzer diagnostics: ${model.sourceFacts.analyzerDiagnosticCount}`);
+    }
+    lines.push("");
+    lines.push("Source-of-truth summary");
+    lines.push(divider("-"));
+    lines.push(`  package: ${model.sourceOfTruth.packageName ?? "(none)"}@${model.sourceOfTruth.packageVersion ?? "?"}`);
+    lines.push(`  README present=${model.sourceOfTruth.hasReadme} CHANGELOG present=${model.sourceOfTruth.hasChangelog} docs files=${model.sourceOfTruth.docsFileCount}`);
+    lines.push(`  CI workflows=${model.sourceOfTruth.ciWorkflowCount} node versions referenced=${model.sourceOfTruth.nodeVersionsReferenced.join(",") || "(none)"}`);
+    if (model.sourceOfTruth.warnings.length > 0) {
+        lines.push(`  warnings: ${model.sourceOfTruth.warnings.length}`);
+    }
+    lines.push("");
+    lines.push("Issue summary");
+    lines.push(divider("-"));
+    lines.push(`  Total issues: ${model.summary.totalIssues}`);
+    lines.push(`  By severity: blocker=${model.summary.issuesBySeverity.blocker} high=${model.summary.issuesBySeverity.high} medium=${model.summary.issuesBySeverity.medium} low=${model.summary.issuesBySeverity.low} info=${model.summary.issuesBySeverity.info}`);
+    lines.push(`  By confidence: high=${model.summary.issuesByConfidence.high} medium=${model.summary.issuesByConfidence.medium} low=${model.summary.issuesByConfidence.low}`);
+    lines.push(`  By false-positive risk: high=${model.summary.issuesByFalsePositiveRisk.high} medium=${model.summary.issuesByFalsePositiveRisk.medium} low=${model.summary.issuesByFalsePositiveRisk.low}`);
+    lines.push(`  Release-blocking=${model.summary.releaseBlockingCount} Implementation-blocking=${model.summary.implementationBlockingCount} Auto-fix-eligible=${model.summary.autoFixEligibleCount}`);
+    lines.push(`  Detectors: total=${model.summary.detectorCount} selected=${model.summary.selectedDetectorCount} skipped=${model.summary.skippedDetectorCount} errors=${model.summary.detectorErrorCount}`);
+    lines.push(`  Highest severity: ${model.summary.highestSeverity ?? "(none)"}`);
+    lines.push(`  Verdict: ${model.summary.finalVerdictLabel}`);
+    lines.push("");
+    if (model.recommendations.length > 0) {
+        lines.push(`Top recommendations (showing up to ${MAX_TEXT_RECOMMENDATIONS} of ${model.recommendations.length})`);
+        lines.push(divider("-"));
+        for (const rec of model.recommendations.slice(0, MAX_TEXT_RECOMMENDATIONS)) {
+            lines.push(`  - [${rec.highestSeverity}] ${sanitizeLine(rec.text)} (${rec.issueIds.length} issue(s), detector(s): ${rec.detectorIds.join(", ")})`);
+        }
+        lines.push("");
+    }
+    lines.push("Issues (grouped by severity)");
+    lines.push(divider("-"));
+    if (model.issues.length === 0) {
+        lines.push("  (no issues in this run)");
+    }
+    else {
+        for (const severity of SEVERITY_HEADING_ORDER) {
+            const group = model.issues.filter((i) => i.severity === severity);
+            if (group.length === 0)
+                continue;
+            lines.push(`  -- ${severity.toUpperCase()} (${group.length}) --`);
+            for (const issue of group) {
+                lines.push(...renderIssueBlock(issue));
+            }
+        }
+    }
+    lines.push("");
+    lines.push("Skipped detectors");
+    lines.push(divider("-"));
+    if (model.skippedDetectors.length === 0) {
+        lines.push("  (none)");
+    }
+    else {
+        for (const s of model.skippedDetectors) {
+            lines.push(`  [${s.id}] ${sanitizeLine(s.reason)}`);
+        }
+    }
+    lines.push("");
+    lines.push("Detector errors");
+    lines.push(divider("-"));
+    if (model.detectorErrors.length === 0) {
+        lines.push("  (none)");
+    }
+    else {
+        for (const e of model.detectorErrors) {
+            lines.push(`  [${e.id}] (${e.category}) ${sanitizeLine(e.message)}`);
+        }
+    }
+    lines.push("");
+    lines.push("Exit result");
+    lines.push(divider("-"));
+    lines.push(`  code=${model.exit.code} failOnThreshold=${model.exit.failOnThreshold} breached=${model.exit.breached}`);
+    lines.push(`  reason: ${sanitizeLine(model.exit.reason)}`);
+    return lines.join("\n");
+}
+function renderIssueBlock(issue) {
+    const lines = [];
+    lines.push(`  * ${sanitizeLine(issue.title)}`);
+    lines.push(`      severity=${issue.severity} confidence=${issue.confidence} category=${sanitizeLine(issue.category)}`);
+    lines.push(`      detector=${issue.detectorId} id=${issue.id}`);
+    for (const evidence of issue.evidence.slice(0, MAX_EVIDENCE_PER_ISSUE)) {
+        // v0.3.1 Batch 5 -- an evidence entry's `message` (the human-readable
+        // "why") and `excerpt` (a quoted snippet/reference list) are
+        // independent fields on the same entry -- render both when both are
+        // present. Previously an `excerpt` silently suppressed `message`
+        // entirely, which dropped the only readable explanation for
+        // source-facts-derived findings (e.g. duplicateImplementationDetector's
+        // "Source facts: an exported ... was parsed in N distinct files.") and
+        // left only a bare file-path excerpt in text output.
+        lines.push(`      > ${sanitizeLine(evidence.message)}`);
+        if (evidence.excerpt) {
+            lines.push(...renderQuotedExcerpt(evidence.excerpt, "      "));
+        }
+    }
+    lines.push(`      recommendedAction: ${sanitizeLine(issue.recommendedAction)}`);
+    return lines;
+}

package/dist/src/audits/report/sanitizeAuditText.js

@@ -0,0 +1,39 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 5 — audit text-report sanitization.
+//
+// Same technique as src/securityValidation/attackScenarios/exploitEvidence.ts's
+// stripUnsafeControlChars()/sanitizeForTextReport() (strip ANSI CSI escapes
+// and other unsafe control bytes before printing hostile-sourced text into a
+// terminal-readable report). Deliberately NOT imported from
+// src/securityValidation/ -- audit and security-validation are kept as
+// independent frameworks throughout this codebase (see the header comment in
+// src/audits/core/auditIssue.ts), and this is a small, self-contained,
+// dependency-free function, so a 10-line local copy is cheaper than adding a
+// cross-framework import for one helper.
+//
+// JSON output does not need this: JSON.stringify already escapes control
+// characters (including ESC, 0x1b) into safe \u00XX sequences by
+// specification, so hostile control bytes can never corrupt JSON structure.
+// This sanitizer is used only by renderAuditTextReport.ts.
+// ---------------------------------------------------------------------------
+// ANSI CSI (Control Sequence Introducer) escape sequences, e.g. "\x1b[31m".
+const ANSI_CSI_PATTERN = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+// Other C0 control characters except common whitespace (tab \t, newline \n,
+// carriage return \r), plus the DEL character (0x7f).
+// eslint-disable-next-line no-control-regex
+const OTHER_CONTROL_CHARS_PATTERN = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g;
+export function stripUnsafeControlChars(raw) {
+    return raw.replace(ANSI_CSI_PATTERN, "").replace(OTHER_CONTROL_CHARS_PATTERN, "");
+}
+const DEFAULT_MAX_TEXT_EXCERPT_LENGTH = 300;
+// Bounds+sanitizes a string for inclusion in the text report: strips unsafe
+// control bytes first (so a payload cannot hide behind control characters),
+// then re-bounds length defensively even though callers (e.g. AuditEvidence
+// excerpts) are usually already bounded upstream by boundExcerpt() in
+// auditIssue.ts.
+export function sanitizeAuditText(raw, maxLength = DEFAULT_MAX_TEXT_EXCERPT_LENGTH) {
+    const stripped = stripUnsafeControlChars(raw);
+    if (stripped.length <= maxLength)
+        return stripped;
+    return `${stripped.slice(0, maxLength)}... [truncated, ${stripped.length} chars total]`;
+}

package/dist/src/audits/report/writeAuditReports.js

@@ -0,0 +1,27 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AUDIT_JSON_REPORT_FILENAME, AUDIT_TEXT_REPORT_FILENAME } from "./auditReportPaths.js";
+import { renderAuditJsonReport } from "./renderAuditJsonReport.js";
+import { renderAuditTextReport } from "./renderAuditTextReport.js";
+export function writeAuditReports(options) {
+    const { model, config, outDir } = options;
+    const resolvedOutDir = path.resolve(outDir);
+    const writtenPaths = [];
+    if (config.formats.length === 0) {
+        return { writtenPaths };
+    }
+    if (!fs.existsSync(resolvedOutDir)) {
+        fs.mkdirSync(resolvedOutDir, { recursive: true });
+    }
+    if (config.formats.includes("json")) {
+        const jsonPath = path.join(resolvedOutDir, AUDIT_JSON_REPORT_FILENAME);
+        fs.writeFileSync(jsonPath, renderAuditJsonReport(model), "utf8");
+        writtenPaths.push(jsonPath);
+    }
+    if (config.formats.includes("text")) {
+        const textPath = path.join(resolvedOutDir, AUDIT_TEXT_REPORT_FILENAME);
+        fs.writeFileSync(textPath, renderAuditTextReport(model), "utf8");
+        writtenPaths.push(textPath);
+    }
+    return { writtenPaths };
+}

package/dist/src/core/resolveCommand.js

@@ -4,17 +4,27 @@ const windowsExtensionPreference = [".cmd", ".exe", ".bat", ".ps1", ""];
 export function resolveCommand(command, options = {}) {
     const platform = options.platform ?? process.platform;
     const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
     if (platform !== "win32") {
+        const posixCandidate = findPosixCommandCandidate(command, env, cwd);
+        if (!posixCandidate) {
+            return {
+                originalCommand: command,
+                command,
+                argsPrefix: [],
+                resolutionKind: "unavailable",
+                warnings: [`Command was not found on PATH: ${command}`]
+            };
+        }
         return {
             originalCommand: command,
             command,
             argsPrefix: [],
             resolutionKind: "direct",
-            resolvedPath: command,
+            resolvedPath: posixCandidate,
             warnings: []
         };
     }
-    const cwd = options.cwd ?? process.cwd();
     const candidate = findWindowsCommandCandidate(command, env, cwd);
     if (!candidate) {
         return {
@@ -68,6 +78,47 @@ function commandForWindowsCandidate(originalCommand, resolvedPath, env, allowPow
         warnings: []
     };
 }
+// POSIX (Linux/macOS) command resolution. Unlike the Windows branch above,
+// there is no extension-guessing -- a bare command name must match exactly
+// one PATH entry, and the match must actually be executable (checked via
+// X_OK, not just file existence, so a non-executable regular file with a
+// matching name is correctly treated as absent). This mirrors the Windows
+// branch's "search PATH, report unavailable if nothing matches" contract:
+// previously this platform branch unconditionally reported "direct" without
+// ever checking PATH, so a genuinely-missing command (e.g. codeql, semgrep)
+// was only discovered as absent when the downstream spawn failed with
+// ENOENT -- which staticScans/codeql.ts and staticScans/semgrep.ts
+// misclassify as a MAJOR/failed finding rather than a graceful skip,
+// causing security:validate to falsely report a release blocker on
+// Linux/macOS whenever an optional static-analysis tool is not installed.
+function findPosixCommandCandidate(command, env, cwd) {
+    if (hasPathSeparator(command) || path.isAbsolute(command)) {
+        const resolved = path.resolve(cwd, command);
+        return isExecutablePosixFile(resolved) ? resolved : undefined;
+    }
+    for (const searchDir of getPosixPathEntries(env)) {
+        const candidate = path.join(searchDir, command);
+        if (isExecutablePosixFile(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function getPosixPathEntries(env) {
+    const pathValue = env.PATH ?? env.Path ?? "";
+    return pathValue.split(path.delimiter).filter(Boolean);
+}
+function isExecutablePosixFile(candidatePath) {
+    try {
+        if (!fs.statSync(candidatePath).isFile())
+            return false;
+        fs.accessSync(candidatePath, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function findWindowsCommandCandidate(command, env, cwd) {
     if (hasPathSeparator(command) || path.isAbsolute(command)) {
         return findCandidateInDirectory(path.resolve(cwd, command));