@specferret/core 0.2.0 → 0.4.0

package/dist/extractor/typescript-contract.js

@@ -0,0 +1,67 @@
+// Extractor layer — turns a .contract.ts file into an ExtractionResult.
+// Uses Bun's native import() — no ts-morph, no AST, no compile step.
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { isContract } from '../contract.js';
+import { hashSchema } from './hash.js';
+export async function extractFromContractFile(filePath) {
+    const mod = (await import(filePath));
+    // Pass 1: build Map<contract object reference → export name> for same-file resolution
+    const exportNameMap = new Map();
+    for (const [exportName, exportValue] of Object.entries(mod)) {
+        if (isContract(exportValue)) {
+            exportNameMap.set(exportValue, exportName);
+        }
+    }
+    if (exportNameMap.size === 0) {
+        return {
+            filePath,
+            fileType: 'code',
+            contracts: [],
+            extractedBy: 'typescript',
+            extractedAt: Date.now(),
+            warning: 'no-frontmatter',
+        };
+    }
+    const contracts = [];
+    for (const [exportName, exportValue] of Object.entries(mod)) {
+        if (!isContract(exportValue))
+            continue;
+        const shape = zodToJsonSchema(z.object(exportValue.output), { $refStrategy: 'none' });
+        const shape_hash = hashSchema(shape);
+        // Pass 2: resolve consumes → import IDs
+        const imports = [];
+        if (exportValue.consumes) {
+            for (const consumed of exportValue.consumes) {
+                const samefile = exportNameMap.get(consumed);
+                if (samefile !== undefined) {
+                    imports.push(samefile);
+                }
+                else if (consumed.id !== undefined) {
+                    imports.push(consumed.id);
+                }
+                else {
+                    process.stderr.write(`[specferret] warning: unresolvable consumes reference in '${filePath}' — export '${exportName}' references a contract with no id and no matching same-file export\n`);
+                    imports.push('[unresolved]');
+                }
+            }
+        }
+        contracts.push({
+            id: exportName,
+            type: 'type',
+            shape,
+            shape_hash,
+            imports,
+            sourceFile: filePath,
+            sourceSymbol: exportName,
+        });
+    }
+    return {
+        filePath,
+        fileType: 'code',
+        contracts,
+        extractedBy: 'typescript',
+        extractedAt: Date.now(),
+    };
+}
+//# sourceMappingURL=typescript-contract.js.map

package/dist/extractor/typescript-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-contract.js","sourceRoot":"","sources":["../../src/extractor/typescript-contract.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,qEAAqE;AAErE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,QAAgB;IAC5D,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,QAAQ,CAAC,CAA4B,CAAC;IAEhE,sFAAsF;IACtF,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD,KAAK,MAAM,CAAC,UAAU,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5D,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAC5B,aAAa,CAAC,GAAG,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,IAAI,aAAa,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO;YACL,QAAQ;YACR,QAAQ,EAAE,MAAM;YAChB,SAAS,EAAE,EAAE;YACb,WAAW,EAAE,YAAY;YACzB,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;YACvB,OAAO,EAAE,gBAAgB;SAC1B,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAkC,EAAE,CAAC;IAEpD,KAAK,MAAM,CAAC,UAAU,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5D,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;YAAE,SAAS;QAEvC,MAAM,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC;QACtF,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QAErC,wCAAwC;QACxC,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;YACzB,KAAK,MAAM,QAAQ,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;gBAC5C,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBAC7C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACzB,CAAC;qBAAM,IAAI,QAAQ,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;oBACrC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;gBAC5B,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,6DAA6D,QAAQ,eAAe,UAAU,uEAAuE,CACtK,CAAC;oBACF,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;QACH,CAAC;QAED,SAAS,CAAC,IAAI,CAAC;YACb,EAAE,EAAE,UAAU;YACd,IAAI,EAAE,MAAM;YACZ,KAAK;YACL,UAAU;YACV,OAAO;YACP,UAAU,EAAE,QAAQ;YACpB,YAAY,EAAE,UAAU;SACzB,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,QAAQ;QACR,QAAQ,EAAE,MAAM;QAChB,SAAS;QACT,WAAW,EAAE,YAAY;QACzB,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;KACxB,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './extractor/frontmatter.js';
+export * from './extractor/typescript-contract.js';
 export * from './extractor/typescript.js';
 export * from './extractor/validator.js';
 export * from './extractor/contract-types.js';
@@ -12,4 +13,8 @@ export * from './reconciler/index.js';
 export * from './reconciler/import-suggestions.js';
 export * from './config.js';
 export * from './utils/paths.js';
+export * from './contract.js';
+export * from './status/index.js';
+export * from './watch/index.js';
+export * from './audit/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 // @specferret/core public API
 // Do not export llm-fallback — dynamic import only, never a default export.
 export * from './extractor/frontmatter.js';
+export * from './extractor/typescript-contract.js';
 export * from './extractor/typescript.js';
 export * from './extractor/validator.js';
 export * from './extractor/contract-types.js';
@@ -14,4 +15,8 @@ export * from './reconciler/index.js';
 export * from './reconciler/import-suggestions.js';
 export * from './config.js';
 export * from './utils/paths.js';
+export * from './contract.js';
+export * from './status/index.js';
+export * from './watch/index.js';
+export * from './audit/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,4EAA4E;AAE5E,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,4EAA4E;AAE5E,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC"}

package/dist/status/index.d.ts

@@ -0,0 +1,20 @@
+import type { DBStore, ContractStatus } from '../store/types.js';
+export type StatusContractEntry = {
+    id: string;
+    status: ContractStatus;
+    driftClass: 'breaking' | 'stable' | 'roadmap';
+    dependentCount: number;
+    dependents: string[];
+};
+export type StatusReport = {
+    version: '2.0';
+    timestamp: string;
+    total: number;
+    stable: number;
+    roadmap: number;
+    needsReview: number;
+    contracts: StatusContractEntry[];
+};
+export declare function buildStatusReport(store: DBStore): Promise<StatusReport>;
+export declare function buildStatusMarkdown(report: StatusReport): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/status/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/status/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEjE,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,KAAK,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,mBAAmB,EAAE,CAAC;CAClC,CAAC;AAEF,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAkC7E;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAWhE"}

package/dist/status/index.js

@@ -0,0 +1,46 @@
+export async function buildStatusReport(store) {
+    const [contracts, nodes, deps] = await Promise.all([store.getContracts(), store.getNodes(), store.getDependencies()]);
+    const nodeById = new Map(nodes.map((n) => [n.id, n]));
+    const dependentsByContractId = new Map();
+    for (const dep of deps) {
+        const node = nodeById.get(dep.source_node_id);
+        if (!node)
+            continue;
+        const list = dependentsByContractId.get(dep.target_contract_id) ?? [];
+        if (!list.includes(node.file_path))
+            list.push(node.file_path);
+        dependentsByContractId.set(dep.target_contract_id, list);
+    }
+    const entries = contracts.map((c) => {
+        const dependents = dependentsByContractId.get(c.id) ?? [];
+        return {
+            id: c.id,
+            status: c.status,
+            driftClass: c.status === 'needs-review' ? 'breaking' : c.status === 'roadmap' ? 'roadmap' : 'stable',
+            dependentCount: dependents.length,
+            dependents,
+        };
+    });
+    return {
+        version: '2.0',
+        timestamp: new Date().toISOString(),
+        total: contracts.length,
+        stable: contracts.filter((c) => c.status === 'stable').length,
+        roadmap: contracts.filter((c) => c.status === 'roadmap').length,
+        needsReview: contracts.filter((c) => c.status === 'needs-review').length,
+        contracts: entries,
+    };
+}
+export function buildStatusMarkdown(report) {
+    const lines = [
+        '# Contract Status',
+        '',
+        `Generated: ${report.timestamp}`,
+        '',
+        '| Contract | Status | Drift Class | Dependents |',
+        '| --- | --- | --- | --- |',
+        ...report.contracts.map((c) => `| ${c.id} | ${c.status} | ${c.driftClass} | ${c.dependentCount} |`),
+    ];
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=index.js.map

package/dist/status/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/status/index.ts"],"names":[],"mappings":"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"}

package/dist/watch/index.d.ts

@@ -0,0 +1,11 @@
+export interface WatcherOptions {
+    specDir: string;
+    projectRoot: string;
+    debounceMs?: number;
+    onChange: (changedFiles: string[]) => void | Promise<void>;
+}
+export interface ContractWatcher {
+    close: () => void;
+}
+export declare function createContractWatcher(options: WatcherOptions): ContractWatcher;
+//# sourceMappingURL=index.d.ts.map

package/dist/watch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watch/index.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,GAAG,eAAe,CAmC9E"}

package/dist/watch/index.js

@@ -0,0 +1,42 @@
+// Watch layer — file system watcher with debounce for contract files.
+// No business logic. No parsing. No traversal.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export function createContractWatcher(options) {
+    const { specDir, projectRoot, debounceMs = 300, onChange } = options;
+    const watchDir = path.resolve(projectRoot, specDir);
+    let debounceTimer = null;
+    let pendingFiles = new Set();
+    let running = false;
+    const watcher = fs.watch(watchDir, { recursive: true }, (_eventType, filename) => {
+        if (!filename)
+            return;
+        const normalized = filename.replace(/\\/g, '/');
+        if (!normalized.endsWith('.contract.md') && !normalized.endsWith('.contract.ts'))
+            return;
+        pendingFiles.add(path.join(specDir, normalized).replace(/\\/g, '/'));
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(async () => {
+            if (running)
+                return;
+            running = true;
+            const files = [...pendingFiles];
+            pendingFiles = new Set();
+            try {
+                await onChange(files);
+            }
+            finally {
+                running = false;
+            }
+        }, debounceMs);
+    });
+    return {
+        close: () => {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            watcher.close();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/watch/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/watch/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,+CAA+C;AAE/C,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAalC,MAAM,UAAU,qBAAqB,CAAC,OAAuB;IAC3D,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,GAAG,GAAG,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAEpD,IAAI,aAAa,GAAyC,IAAI,CAAC;IAC/D,IAAI,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,EAAE;QAC/E,IAAI,CAAC,QAAQ;YAAE,OAAO;QACtB,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAChD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,cAAc,CAAC;YAAE,OAAO;QAEzF,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;QAErE,IAAI,aAAa;YAAE,YAAY,CAAC,aAAa,CAAC,CAAC;QAC/C,aAAa,GAAG,UAAU,CAAC,KAAK,IAAI,EAAE;YACpC,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,KAAK,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC;YAChC,YAAY,GAAG,IAAI,GAAG,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;YACxB,CAAC;oBAAS,CAAC;gBACT,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;QACH,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,aAAa;gBAAE,YAAY,CAAC,aAAa,CAAC,CAAC;YAC/C,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specferret/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "SpecFerret core engine — spec drift detection.",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,8 @@
     "gray-matter": "^4.0.3",
     "tree-sitter": "^0.22.4",
     "tree-sitter-typescript": "^0.23.2",
-    "zod": "^3.22.4"
+    "zod": "^3.22.4",
+    "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
     "@types/bun": "^1.3.11",

package/src/audit/index.ts

@@ -0,0 +1,120 @@
+// Audit layer — read-only bidirectional drift report.
+// Combines downward drift (reconciler), upward drift (code → spec), and status.
+// No mutations. No side effects beyond reading the store and filesystem.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { DBStore } from '../store/types.js';
+import type { ImportIntegrityReport, ReconcileReport } from '../reconciler/index.js';
+import type { UpwardDriftResult } from '../extractor/upward-classifier.js';
+import type { StatusReport } from '../status/index.js';
+import type { ExtractionResult } from '../extractor/frontmatter.js';
+import { Reconciler } from '../reconciler/index.js';
+import { classifyUpwardDrift } from '../extractor/upward-classifier.js';
+import { buildStatusReport } from '../status/index.js';
+import { extractContractsFromTypeScript } from '../extractor/typescript.js';
+import { extractFromContractFile } from '../extractor/typescript-contract.js';
+
+export interface AuditSummary {
+  totalContracts: number;
+  stable: number;
+  needsReview: number;
+  roadmap: number;
+  downwardBreaking: number;
+  downwardNonBreaking: number;
+  upwardBreaking: number;
+  upwardNonBreaking: number;
+  integrityViolationCount: number;
+}
+
+export interface AuditReport {
+  version: '1.0';
+  timestamp: string;
+  summary: AuditSummary;
+  downwardDrift: ReconcileReport['flagged'];
+  upwardDrift: UpwardDriftResult[];
+  integrityViolations: ImportIntegrityReport;
+  importSuggestions: ReconcileReport['importSuggestions'];
+  statusReport: StatusReport;
+}
+
+export async function buildAuditReport(store: DBStore, projectRoot: string): Promise<AuditReport> {
+  const reconciler = new Reconciler(store);
+  const reconcileReport = await reconciler.reconcile();
+  const statusReport = await buildStatusReport(store);
+
+  const contracts = await store.getContracts();
+  const breakingTriggerIds = new Set(contracts.filter((c) => c.status === 'needs-review').map((c) => c.id));
+
+  // Upward drift detection — re-extract live TypeScript and compare to declared schema.
+  const upwardDrift: UpwardDriftResult[] = [];
+  const tsExtractionCache = new Map<string, ExtractionResult>();
+
+  for (const contract of contracts) {
+    if (!contract.code_source_file || !contract.code_source_symbol) continue;
+    const sourceAbsPath = path.resolve(projectRoot, contract.code_source_file);
+    if (!fs.existsSync(sourceAbsPath)) continue;
+
+    let codeShape: unknown;
+    try {
+      if (sourceAbsPath.endsWith('.contract.ts')) {
+        let tsExtraction = tsExtractionCache.get(sourceAbsPath);
+        if (!tsExtraction) {
+          tsExtraction = await extractFromContractFile(sourceAbsPath);
+          tsExtractionCache.set(sourceAbsPath, tsExtraction);
+        }
+        const found = tsExtraction.contracts.find((c) => c.id === contract.code_source_symbol);
+        if (!found) continue;
+        codeShape = found.shape;
+      } else {
+        const fileContent = fs.readFileSync(sourceAbsPath, 'utf-8');
+        const extraction = extractContractsFromTypeScript(sourceAbsPath, fileContent);
+        const found = extraction.contracts.find((c) => c.sourceSymbol === contract.code_source_symbol);
+        if (!found) continue;
+        codeShape = found.shape;
+      }
+    } catch {
+      continue;
+    }
+
+    let declaredSchema: unknown = {};
+    try {
+      declaredSchema = JSON.parse(contract.shape_schema);
+    } catch {}
+
+    const result = classifyUpwardDrift(contract.id, declaredSchema, codeShape, contract.code_source_file, contract.code_source_symbol);
+    if (result.driftClass !== 'NOOP') {
+      upwardDrift.push(result);
+    }
+  }
+
+  const downwardBreaking = reconcileReport.flagged.filter((f) => breakingTriggerIds.has(f.triggeredByContractId)).length;
+  const downwardNonBreaking = reconcileReport.flagged.filter((f) => !breakingTriggerIds.has(f.triggeredByContractId)).length;
+  const upwardBreaking = upwardDrift.filter((d) => d.driftClass === 'BREAKING').length;
+  const upwardNonBreaking = upwardDrift.filter((d) => d.driftClass === 'NON_BREAKING').length;
+  const integrityViolationCount =
+    reconcileReport.integrityViolations.unresolvedImports.length +
+    reconcileReport.integrityViolations.selfImports.length +
+    reconcileReport.integrityViolations.circularImports.length;
+
+  return {
+    version: '1.0',
+    timestamp: new Date().toISOString(),
+    summary: {
+      totalContracts: contracts.length,
+      stable: statusReport.stable,
+      needsReview: statusReport.needsReview,
+      roadmap: statusReport.roadmap,
+      downwardBreaking,
+      downwardNonBreaking,
+      upwardBreaking,
+      upwardNonBreaking,
+      integrityViolationCount,
+    },
+    downwardDrift: reconcileReport.flagged,
+    upwardDrift,
+    integrityViolations: reconcileReport.integrityViolations,
+    importSuggestions: reconcileReport.importSuggestions,
+    statusReport,
+  };
+}

package/src/config.ts

@@ -14,6 +14,9 @@ export interface FerretConfig {
     include: string[];
     watchNodes?: string[];
   };
+  contractParsers?: {
+    typescript?: boolean;
+  };
 }
 
 export const DEFAULT_CONFIG: FerretConfig = {

package/src/contract.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'bun:test';
+import { z } from 'zod';
+import { defineContract, isContract } from './contract.js';
+
+describe('isContract', () => {
+  it('returns true for a minimal valid object', () => {
+    expect(isContract({ value: 'x', output: {} })).toBe(true);
+  });
+
+  it('returns true for object with id set', () => {
+    expect(isContract({ id: 'auth.jwt', value: 'x', output: {} })).toBe(true);
+  });
+
+  it('returns true for object without id — id is optional and not checked', () => {
+    expect(isContract({ value: 'x', output: { name: z.string() } })).toBe(true);
+  });
+
+  it('returns false for null', () => {
+    expect(isContract(null)).toBe(false);
+  });
+
+  it('returns false for undefined', () => {
+    expect(isContract(undefined)).toBe(false);
+  });
+
+  it('returns false for a number', () => {
+    expect(isContract(42)).toBe(false);
+  });
+
+  it('returns false for a string', () => {
+    expect(isContract('string')).toBe(false);
+  });
+
+  it('returns false for object missing value', () => {
+    expect(isContract({ output: {} })).toBe(false);
+  });
+
+  it('returns false for object missing output', () => {
+    expect(isContract({ value: 'x' })).toBe(false);
+  });
+
+  it('returns false when value is not a string', () => {
+    expect(isContract({ value: 42, output: {} })).toBe(false);
+  });
+
+  it('returns false when output is null', () => {
+    expect(isContract({ value: 'x', output: null })).toBe(false);
+  });
+
+  it('returns false when output is an array', () => {
+    expect(isContract({ value: 'x', output: [] })).toBe(false);
+  });
+});
+
+describe('defineContract', () => {
+  it('returns the exact object passed to it when valid', () => {
+    const contract = { value: 'x', output: {} };
+    expect(defineContract(contract)).toBe(contract);
+  });
+
+  it('does not throw when id is omitted', () => {
+    expect(() => defineContract({ value: 'x', output: {} })).not.toThrow();
+  });
+
+  it('does not throw when id is explicitly undefined', () => {
+    expect(() => defineContract({ id: undefined, value: 'x', output: {} })).not.toThrow();
+  });
+
+  it('does not throw when id is a valid non-empty string', () => {
+    expect(() => defineContract({ id: 'auth.jwt', value: 'x', output: {} })).not.toThrow();
+  });
+
+  it('throws when id is an empty string', () => {
+    expect(() => defineContract({ id: '', value: 'x', output: {} })).toThrow(
+      'id must be a non-empty string',
+    );
+  });
+
+  it('throws when id is whitespace only', () => {
+    expect(() => defineContract({ id: '   ', value: 'x', output: {} })).toThrow(
+      'id must be a non-empty string',
+    );
+  });
+
+  it('enforces typed invariant argument — compile-time check via typed fixture', () => {
+    // If r is not typed as { name: string }, the _: string assignment below is a compile error.
+    const contract = defineContract({
+      value: 'typed invariant test',
+      output: { name: z.string() },
+      invariants: [
+        (r) => {
+          const _: string = r.name;
+          return _.length > 0;
+        },
+      ],
+    });
+    expect(isContract(contract)).toBe(true);
+  });
+});

package/src/contract.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+
+export interface Contract<
+  T extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>,
+> {
+  id?: string;
+  value: string;
+  output: T;
+  invariants?: Array<(r: z.infer<z.ZodObject<T>>) => boolean>;
+  consumes?: Contract[];
+  forbids?: string[];
+  status?: 'complete' | 'active' | 'pending';
+  closedBy?: string;
+  closedWhen?: string;
+  dependsOn?: Contract[];
+}
+
+export function defineContract<T extends Record<string, z.ZodTypeAny>>(
+  contract: Contract<T>,
+): Contract<T> {
+  if ('id' in contract && contract.id !== undefined && contract.id.trim() === '') {
+    throw new Error('defineContract: id must be a non-empty string if provided');
+  }
+  return contract;
+}
+
+export function isContract(value: unknown): value is Contract {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'value' in value &&
+    typeof (value as Record<string, unknown>).value === 'string' &&
+    'output' in value &&
+    typeof (value as Record<string, unknown>).output === 'object' &&
+    (value as Record<string, unknown>).output !== null &&
+    !Array.isArray((value as Record<string, unknown>).output)
+  );
+}

package/src/extractor/__fixtures__/cross-file-id.fixture.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { externalWithId } from './external-with-id.fixture.js';
+
+// Consumes an external contract that has an explicit id — resolves via c.id
+export const myContract = {
+  value: 'Contract consuming known external',
+  output: { result: z.string() },
+  consumes: [externalWithId],
+};

package/src/extractor/__fixtures__/cross-file-unresolved.fixture.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { externalNoId } from './external-no-id.fixture.js';
+
+// Consumes an external contract with no id — triggers exactly one warning
+export const myContract = {
+  value: 'Contract consuming unresolvable external',
+  output: { result: z.string() },
+  consumes: [externalNoId],
+};

package/src/extractor/__fixtures__/empty.fixture.ts

@@ -0,0 +1,4 @@
+// No ferret contracts here — only primitives and non-contract objects
+export const version = '1.0.0';
+export const count = 42;
+export const config = { debug: true };

package/src/extractor/__fixtures__/external-no-id.fixture.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+
+// External contract with no id — cross-file refs to this will be unresolvable
+export const externalNoId = {
+  value: 'External contract without id',
+  output: { data: z.string() },
+};

package/src/extractor/__fixtures__/external-with-id.fixture.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+// External contract with an explicit id — cross-file refs resolve via c.id
+export const externalWithId = {
+  value: 'External contract with explicit id',
+  output: { data: z.string() },
+  id: 'external.known.id',
+};

package/src/extractor/__fixtures__/mixed.fixture.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+
+export const validContract = {
+  value: 'valid',
+  output: { name: z.string() },
+};
+
+export const anotherValid = {
+  value: 'another valid',
+  output: { count: z.number() },
+};
+
+// These should be skipped by isContract
+export const notAContract = 42;
+export const alsoNotAContract = 'just a string';
+export const missingOutput = { value: 'oops' };
+export const missingValue = { output: { x: z.string() } };

package/src/extractor/__fixtures__/one-contract.fixture.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+export const userContract = {
+  value: 'User shape contract',
+  output: {
+    id: z.string().uuid(),
+    name: z.string(),
+    email: z.string().email(),
+  },
+};

package/src/extractor/__fixtures__/optional-fields.fixture.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+export const optionalFieldsContract = {
+  value: 'Contract with optional fields',
+  output: {
+    required_field: z.string(),
+    optional_field: z.string().optional(),
+    optional_number: z.number().optional(),
+  },
+};

package/src/extractor/__fixtures__/same-file-consumes.fixture.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+export const baseContract = {
+  value: 'Base contract',
+  output: { token: z.string() },
+};
+
+export const dependentContract = {
+  value: 'Dependent contract that consumes baseContract',
+  output: { result: z.string() },
+  consumes: [baseContract],
+};