gswd 1.0.1 → 1.1.0

package/dist/lib/audit.d.ts

@@ -0,0 +1,205 @@
+/**
+ * GSWD Audit Module — Coverage matrix, checks, report generation, auto-fix, workflow
+ *
+ * Mechanically checks spec artifacts for coverage gaps, cross-reference integrity,
+ * and heading compliance. Produces PASS or actionable FAIL checklist in AUDIT.md.
+ *
+ * Schema: GSWD_SPEC.md Section 8.4 (audit workflow), 6.1-6.3 (IDs and headings)
+ */
+import { type ExtractedId } from './parse.js';
+export interface Finding {
+    id: string;
+    issue: string;
+    fix: string;
+    severity: 'error' | 'warning';
+}
+export interface CheckResult {
+    check: string;
+    passed: boolean;
+    findings: Finding[];
+}
+export interface CoverageMatrix {
+    journeyToFRs: Map<string, Set<string>>;
+    frToJourneys: Map<string, Set<string>>;
+    journeyToTests: Map<string, string[]>;
+    journeyToIntegrations: Map<string, Set<string>>;
+    integrationStatus: Map<string, {
+        status: string;
+        hasFallback: boolean;
+    }>;
+    frScopes: Map<string, string>;
+    allJourneyIds: string[];
+    allFRIds: string[];
+    allNFRIds: string[];
+    allIntegrationIds: string[];
+}
+export interface AuditResult {
+    passed: boolean;
+    checks: CheckResult[];
+    matrix: CoverageMatrix;
+    summary: {
+        total_checks: number;
+        passed: number;
+        failed: number;
+        findings_count: number;
+    };
+}
+/**
+ * Extract all ID types from artifact content using parse.ts extractIds().
+ * Works on content strings (not file paths) for testability.
+ */
+export declare function extractArtifactIds(content: string): {
+    journeyIds: ExtractedId[];
+    frIds: ExtractedId[];
+    nfrIds: ExtractedId[];
+    integrationIds: ExtractedId[];
+};
+/**
+ * Split JOURNEYS.md by ### J-NNN headings.
+ * Returns map of normalized journey ID -> section content.
+ */
+export declare function parseJourneySections(journeysContent: string): Map<string, string>;
+/**
+ * Extract FR scope tags from SPEC.md content.
+ * Looks for patterns: **Scope:** v1, Scope: v2, etc.
+ * Defaults to "v1" if scope not found (conservative).
+ */
+export declare function parseFRScope(specContent: string): Map<string, string>;
+/**
+ * Parse integration statuses from INTEGRATIONS.md.
+ * Looks for Status: and Fallback: fields per integration.
+ */
+export declare function parseIntegrationStatus(integrationsContent: string): Map<string, {
+    status: string;
+    hasFallback: boolean;
+}>;
+/**
+ * Build the full coverage matrix from spec artifact contents.
+ */
+export declare function buildCoverageMatrix(files: {
+    journeys?: string;
+    spec?: string;
+    nfr?: string;
+    integrations?: string;
+    architecture?: string;
+}): CoverageMatrix;
+/**
+ * Check: Every journey references >= 1 FR (AUDT-02 partial)
+ */
+export declare function checkJourneyFRCoverage(matrix: CoverageMatrix): CheckResult;
+/**
+ * Check: Every journey has >= 1 acceptance test (AUDT-02 partial)
+ */
+export declare function checkJourneyTestCoverage(matrix: CoverageMatrix): CheckResult;
+/**
+ * Check: Every Scope:v1 FR is referenced by >= 1 journey (AUDT-03)
+ * Skips v2 and out-of-scope FRs.
+ */
+export declare function checkOrphanV1FRs(matrix: CoverageMatrix): CheckResult;
+/**
+ * Check: No unapproved integration referenced by v1 journey without fallback (AUDT-04)
+ */
+export declare function checkIntegrationApproval(matrix: CoverageMatrix): CheckResult;
+/**
+ * Check: All required headings exist in artifact files (AUDT-05)
+ */
+export declare function checkRequiredHeadings(files: Record<string, string>): CheckResult;
+/**
+ * Run all audit checks and return structured result.
+ */
+export declare function runAudit(files: {
+    journeys?: string;
+    spec?: string;
+    nfr?: string;
+    integrations?: string;
+    architecture?: string;
+}): AuditResult;
+/**
+ * Format coverage matrix as a markdown table.
+ * Sorted by journey ID ascending.
+ */
+export declare function formatCoverageMatrixTable(matrix: CoverageMatrix): string;
+/**
+ * Format a single check result as a markdown section.
+ */
+export declare function formatCheckSection(result: CheckResult): string;
+/**
+ * Generate full AUDIT.md report content from audit result.
+ * Groups findings by check type. FAIL includes actionable checklist.
+ */
+export declare function generateAuditReport(result: AuditResult): string;
+export interface AutoFixChange {
+    file: string;
+    change: string;
+    finding: Finding;
+}
+export interface AutoFixResult {
+    applied: AutoFixChange[];
+    skipped: Finding[];
+    updatedFiles: Map<string, string>;
+}
+/**
+ * Apply surgical auto-fixes to spec artifacts.
+ *
+ * CAN do:
+ *  - Add stub acceptance tests for journeys missing them
+ *  - Add fallback stubs for unapproved integrations
+ *
+ * CANNOT do:
+ *  - Invent new FRs, journeys, or integrations
+ *  - Approve paid integrations
+ *  - Change existing content (only append)
+ */
+export declare function applyAutoFix(result: AuditResult, files: Record<string, string>): AutoFixResult;
+/**
+ * Check audit gate: returns true ONLY when audit status is "pass".
+ * Fail-closed: returns false for any non-"pass" state, including read errors.
+ */
+export declare function checkAuditGate(statePath: string): boolean;
+/**
+ * Update STATE.json with audit result.
+ * Sets stage_status.audit to "pass" or "fail".
+ * On pass: also updates stage to "audit".
+ */
+export declare function updateAuditState(statePath: string, passed: boolean): void;
+export interface AuditWorkflowResult {
+    passed: boolean;
+    auditResult: AuditResult;
+    reportPath: string;
+    autoFixCycles: number;
+    autoFixChanges: AutoFixChange[];
+}
+/**
+ * Read all spec artifact files from a planning directory.
+ * Returns a content map. Missing files get empty string (audit checks will flag them).
+ */
+export declare function readArtifactFiles(planningDir: string): Record<string, string>;
+/**
+ * Write AUDIT.md atomically to the planning directory.
+ * Returns the written file path.
+ */
+export declare function writeAuditReport(planningDir: string, reportContent: string): string;
+/**
+ * Returns the list of artifact file names that audit checks.
+ */
+export declare function getAuditableFileTypes(): string[];
+/**
+ * Full audit workflow orchestrator.
+ *
+ * Steps:
+ *   1. Update state -> in_progress
+ *   2. Read all artifact files
+ *   3. Run audit
+ *   4. If PASS -> generate report, write AUDIT.md, update state -> pass, write checkpoint, return
+ *   5. If FAIL and autoFix enabled:
+ *      - Run auto-fix cycles (max 2 by default per GSWD_SPEC Section 10.4)
+ *      - Write fixed files to disk after each cycle
+ *      - Re-read files and re-run audit
+ *   6. Generate report, write AUDIT.md, update state -> pass or fail, write checkpoint
+ */
+export declare function runAuditWorkflow(options: {
+    planningDir: string;
+    statePath: string;
+    autoFix?: boolean;
+    maxCycles?: number;
+}): AuditWorkflowResult;