@specferret/core 0.1.4 → 0.3.0

package/dist/extractor/upward-classifier.d.ts

@@ -0,0 +1,25 @@
+export type UpwardDriftClass = 'BREAKING' | 'NON_BREAKING' | 'NOOP';
+export interface UpwardDriftResult {
+    contractId: string;
+    driftClass: UpwardDriftClass;
+    sourceFile: string;
+    sourceSymbol: string;
+    reason: string;
+}
+/**
+ * Classifies the drift between a declared contract schema and the live code-derived schema.
+ *
+ * Input:
+ *   - declaredSchema: the schema declared in the .contract.md frontmatter (the spec)
+ *   - codeSchema:     the schema extracted from the TypeScript source at lint time
+ *
+ * Output:
+ *   - BREAKING:     code change breaks the declared contract (required field removed, type changed, etc.)
+ *   - NON_BREAKING: code change is additive but not declared (optional field added, enum value added)
+ *   - NOOP:         code and declared schema are semantically identical (hash-stable, no action needed)
+ *
+ * Uses the same classification taxonomy as compareSchemas for consistency.
+ * No-op formatting changes (property reorder with stable hash) return NOOP.
+ */
+export declare function classifyUpwardDrift(contractId: string, declaredSchema: unknown, codeSchema: unknown, sourceFile: string, sourceSymbol: string): UpwardDriftResult;
+//# sourceMappingURL=upward-classifier.d.ts.map

package/dist/extractor/upward-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upward-classifier.d.ts","sourceRoot":"","sources":["../../src/extractor/upward-classifier.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,cAAc,GAAG,MAAM,CAAC;AAEpE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,OAAO,EACvB,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,iBAAiB,CA8BnB"}

package/dist/extractor/upward-classifier.js

@@ -0,0 +1,48 @@
+// Pure function. No I/O. No side effects. Ever.
+// Upward drift classifier — detects when a TypeScript implementation diverges from
+// its declared contract schema (code → spec direction).
+import { compareSchemas } from './validator.js';
+/**
+ * Classifies the drift between a declared contract schema and the live code-derived schema.
+ *
+ * Input:
+ *   - declaredSchema: the schema declared in the .contract.md frontmatter (the spec)
+ *   - codeSchema:     the schema extracted from the TypeScript source at lint time
+ *
+ * Output:
+ *   - BREAKING:     code change breaks the declared contract (required field removed, type changed, etc.)
+ *   - NON_BREAKING: code change is additive but not declared (optional field added, enum value added)
+ *   - NOOP:         code and declared schema are semantically identical (hash-stable, no action needed)
+ *
+ * Uses the same classification taxonomy as compareSchemas for consistency.
+ * No-op formatting changes (property reorder with stable hash) return NOOP.
+ */
+export function classifyUpwardDrift(contractId, declaredSchema, codeSchema, sourceFile, sourceSymbol) {
+    const comparison = compareSchemas(declaredSchema, codeSchema);
+    if (comparison.classification === 'no-change') {
+        return {
+            contractId,
+            driftClass: 'NOOP',
+            sourceFile,
+            sourceSymbol,
+            reason: comparison.reason,
+        };
+    }
+    if (comparison.classification === 'breaking') {
+        return {
+            contractId,
+            driftClass: 'BREAKING',
+            sourceFile,
+            sourceSymbol,
+            reason: comparison.reason,
+        };
+    }
+    return {
+        contractId,
+        driftClass: 'NON_BREAKING',
+        sourceFile,
+        sourceSymbol,
+        reason: comparison.reason,
+    };
+}
+//# sourceMappingURL=upward-classifier.js.map

package/dist/extractor/upward-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upward-classifier.js","sourceRoot":"","sources":["../../src/extractor/upward-classifier.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,mFAAmF;AACnF,wDAAwD;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAYhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CACjC,UAAkB,EAClB,cAAuB,EACvB,UAAmB,EACnB,UAAkB,EAClB,YAAoB;IAEpB,MAAM,UAAU,GAAG,cAAc,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;IAE9D,IAAI,UAAU,CAAC,cAAc,KAAK,WAAW,EAAE,CAAC;QAC9C,OAAO;YACL,UAAU;YACV,UAAU,EAAE,MAAM;YAClB,UAAU;YACV,YAAY;YACZ,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,cAAc,KAAK,UAAU,EAAE,CAAC;QAC7C,OAAO;YACL,UAAU;YACV,UAAU,EAAE,UAAU;YACtB,UAAU;YACV,YAAY;YACZ,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC;IACJ,CAAC;IAED,OAAO;QACL,UAAU;QACV,UAAU,EAAE,cAAc;QAC1B,UAAU;QACV,YAAY;QACZ,MAAM,EAAE,UAAU,CAAC,MAAM;KAC1B,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 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';
 export * from './extractor/hash.js';
+export * from './extractor/upward-classifier.js';
 export * from './context/index.js';
 export * from './store/types.js';
 export * from './store/sqlite.js';
@@ -11,4 +13,6 @@ 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';
 //# 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,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"}

package/dist/index.js

@@ -1,10 +1,12 @@
 // @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';
 export * from './extractor/hash.js';
+export * from './extractor/upward-classifier.js';
 export * from './context/index.js';
 export * from './store/types.js';
 export * from './store/sqlite.js';
@@ -13,4 +15,6 @@ 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';
 //# 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,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"}

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":"AAoBA,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAAc;IACpD,MAAM,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;IAEtH,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,MAAM,sBAAsB,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE3D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,IAAI,GAAG,sBAAsB,CAAC,GAAG,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;QACtE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9D,sBAAsB,CAAC,GAAG,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;IAC3D,CAAC;IAED,MAAM,OAAO,GAA0B,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACzD,MAAM,UAAU,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QAC1D,OAAO;YACL,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,UAAU,EAAE,CAAC,CAAC,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ;YACpG,cAAc,EAAE,UAAU,CAAC,MAAM;YACjC,UAAU;SACX,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,OAAO,EAAE,KAAK;QACd,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,KAAK,EAAE,SAAS,CAAC,MAAM;QACvB,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,MAAM;QAC7D,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,MAAM;QAC/D,WAAW,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,cAAc,CAAC,CAAC,MAAM;QACxE,SAAS,EAAE,OAAO;KACnB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAoB;IACtD,MAAM,KAAK,GAAG;QACZ,mBAAmB;QACnB,EAAE;QACF,cAAc,MAAM,CAAC,SAAS,EAAE;QAChC,EAAE;QACF,kDAAkD;QAClD,2BAA2B;QAC3B,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,UAAU,MAAM,CAAC,CAAC,cAAc,IAAI,CAAC;KACpG,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACjC,CAAC"}

package/dist/store/sqlite.d.ts

@@ -1,4 +1,4 @@
-import type { DBStore, FerretNode, FerretContract, FerretDependency, FerretReconciliationLog, FerretPlacementDecision, NodeStatus } from "./types.js";
+import type { DBStore, FerretNode, FerretContract, FerretDependency, FerretReconciliationLog, FerretPlacementDecision, NodeStatus } from './types.js';
 export declare class SqliteStore implements DBStore {
     private db;
     private dbPath;

package/dist/store/sqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/store/sqlite.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,EACvB,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,qBAAa,WAAY,YAAW,OAAO;IACzC,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,MAAM,CAAS;gBAEX,UAAU,CAAC,EAAE,MAAM;IAWzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAyErB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAO/D,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3C,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAMtC,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBvD,gBAAgB,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7D,gCAAgC,CACpC,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC;IAsBV,QAAQ,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAMjC,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAM3D,YAAY,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAMzC,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAOvD,eAAe,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAM9C,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnE,uBAAuB,CAAC,GAAG,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAepE,qBAAqB,IAAI,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAM3D,uBAAuB,CAC3B,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAAC,IAAI,CAAC;IAcV,qBAAqB,IAAI,OAAO,CAAC,uBAAuB,EAAE,CAAC;CAKlE"}
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/store/sqlite.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtJ,qBAAa,WAAY,YAAW,OAAO;IACzC,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,MAAM,CAAS;gBAEX,UAAU,CAAC,EAAE,MAAM;IAMzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA2ErB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAK/D,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3C,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAItC,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BvD,gBAAgB,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7D,gCAAgC,CAAC,YAAY,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBlG,QAAQ,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAIjC,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAI3D,YAAY,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAIzC,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAKvD,eAAe,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAI9C,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE,uBAAuB,CAAC,GAAG,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IASpE,qBAAqB,IAAI,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAM3D,uBAAuB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IASzE,qBAAqB,IAAI,OAAO,CAAC,uBAAuB,EAAE,CAAC;CAGlE"}

package/dist/store/sqlite.js

@@ -1,38 +1,33 @@
-import { Database } from "bun:sqlite";
-import * as path from "node:path";
-import * as fs from "node:fs";
-import { randomUUID } from "node:crypto";
-import { findProjectRoot } from "../utils/paths.js";
+import { Database } from 'bun:sqlite';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { findProjectRoot } from '../utils/paths.js';
 export class SqliteStore {
     db = null;
     dbPath;
     constructor(customPath) {
         const root = findProjectRoot();
-        const defaultPath = path.join(root, ".ferret", "graph.db");
-        this.dbPath =
-            customPath === ":memory:"
-                ? ":memory:"
-                : customPath
-                    ? path.resolve(root, customPath)
-                    : defaultPath;
+        const defaultPath = path.join(root, '.ferret', 'graph.db');
+        this.dbPath = customPath === ':memory:' ? ':memory:' : customPath ? path.resolve(root, customPath) : defaultPath;
     }
     async init() {
         if (this.db)
             return;
-        if (this.dbPath !== ":memory:") {
+        if (this.dbPath !== ':memory:') {
             const ferretDir = path.dirname(this.dbPath);
             if (!fs.existsSync(ferretDir)) {
                 fs.mkdirSync(ferretDir, { recursive: true });
             }
-            const gitignorePath = path.join(ferretDir, ".gitignore");
+            const gitignorePath = path.join(ferretDir, '.gitignore');
             try {
-                fs.writeFileSync(gitignorePath, "*\n!.gitignore\n!context.json\n", "utf-8");
+                fs.writeFileSync(gitignorePath, '*\n!.gitignore\n!context.json\n', 'utf-8');
             }
             catch { }
         }
         this.db = new Database(this.dbPath);
-        this.db.exec("PRAGMA journal_mode = WAL;");
-        this.db.exec("PRAGMA foreign_keys = ON;");
+        this.db.exec('PRAGMA journal_mode = WAL;');
+        this.db.exec('PRAGMA foreign_keys = ON;');
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS ferret_nodes (
         id TEXT PRIMARY KEY,
@@ -80,6 +75,14 @@ export class SqliteStore {
             this.db.exec(`ALTER TABLE ferret_contracts ADD COLUMN shape_schema TEXT NOT NULL DEFAULT '{}';`);
         }
         catch { }
+        try {
+            this.db.exec(`ALTER TABLE ferret_contracts ADD COLUMN code_source_file TEXT;`);
+        }
+        catch { }
+        try {
+            this.db.exec(`ALTER TABLE ferret_contracts ADD COLUMN code_source_symbol TEXT;`);
+        }
+        catch { }
     }
     async close() {
         if (this.db) {
@@ -88,7 +91,7 @@ export class SqliteStore {
         }
     }
     async getNodeByFilePath(filePath) {
-        const row = this.db.prepare("SELECT * FROM ferret_nodes WHERE file_path = ?").get(filePath);
+        const row = this.db.prepare('SELECT * FROM ferret_nodes WHERE file_path = ?').get(filePath);
         return row ?? null;
     }
     async upsertNode(node) {
@@ -103,19 +106,21 @@ export class SqliteStore {
     `).run(node.id, node.file_path, node.hash, node.status);
     }
     async getAllContractIds() {
-        return this.db.prepare("SELECT id FROM ferret_contracts").all().map((r) => r.id);
+        return this.db.prepare('SELECT id FROM ferret_contracts').all().map((r) => r.id);
     }
     async upsertContract(contract) {
         this.db.prepare(`
-      INSERT INTO ferret_contracts (id, node_id, shape_hash, shape_schema, type, status)
-      VALUES (?, ?, ?, ?, ?, ?)
+      INSERT INTO ferret_contracts (id, node_id, shape_hash, shape_schema, type, status, code_source_file, code_source_symbol)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(id) DO UPDATE SET
         node_id = excluded.node_id,
         shape_hash = excluded.shape_hash,
         shape_schema = excluded.shape_schema,
         type = excluded.type,
-        status = excluded.status
-    `).run(contract.id, contract.node_id, contract.shape_hash, contract.shape_schema, contract.type, contract.status);
+        status = excluded.status,
+        code_source_file = excluded.code_source_file,
+        code_source_symbol = excluded.code_source_symbol
+    `).run(contract.id, contract.node_id, contract.shape_hash, contract.shape_schema, contract.type, contract.status, contract.code_source_file ?? null, contract.code_source_symbol ?? null);
     }
     async upsertDependency(dependency) {
         this.db.prepare(`
@@ -126,7 +131,7 @@ export class SqliteStore {
     }
     async replaceDependenciesForSourceNode(sourceNodeId, targetContractIds) {
         const uniqueTargets = [...new Set(targetContractIds)].sort();
-        const deleteStatement = this.db.prepare("DELETE FROM ferret_dependencies WHERE source_node_id = ?");
+        const deleteStatement = this.db.prepare('DELETE FROM ferret_dependencies WHERE source_node_id = ?');
         const insertStatement = this.db.prepare(`
       INSERT INTO ferret_dependencies (id, source_node_id, target_contract_id)
       VALUES (?, ?, ?)
@@ -140,23 +145,23 @@ export class SqliteStore {
         transaction(sourceNodeId);
     }
     async getNodes() {
-        return this.db.prepare("SELECT * FROM ferret_nodes").all();
+        return this.db.prepare('SELECT * FROM ferret_nodes').all();
     }
     async getNodesByStatus(status) {
-        return this.db.prepare("SELECT * FROM ferret_nodes WHERE status = ?").all(status);
+        return this.db.prepare('SELECT * FROM ferret_nodes WHERE status = ?').all(status);
     }
     async getContracts() {
-        return this.db.prepare("SELECT * FROM ferret_contracts").all();
+        return this.db.prepare('SELECT * FROM ferret_contracts').all();
     }
     async getContract(id) {
-        const row = this.db.prepare("SELECT * FROM ferret_contracts WHERE id = ?").get(id);
+        const row = this.db.prepare('SELECT * FROM ferret_contracts WHERE id = ?').get(id);
         return row ?? null;
     }
     async getDependencies() {
-        return this.db.prepare("SELECT * FROM ferret_dependencies").all();
+        return this.db.prepare('SELECT * FROM ferret_dependencies').all();
     }
     async updateNodeStatus(nodeId, status) {
-        this.db.prepare("UPDATE ferret_nodes SET status = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?").run(status, nodeId);
+        this.db.prepare('UPDATE ferret_nodes SET status = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run(status, nodeId);
     }
     async insertReconciliationLog(log) {
         this.db.prepare(`
@@ -165,7 +170,7 @@ export class SqliteStore {
     `).run(log.id, log.node_id, log.triggered_by, log.resolved_by ?? null, log.resolution_notes ?? null);
     }
     async getReconciliationLogs() {
-        return this.db.prepare("SELECT id, node_id, triggered_by, resolved_by, resolution_notes FROM ferret_reconciliation_log").all();
+        return this.db.prepare('SELECT id, node_id, triggered_by, resolved_by, resolution_notes FROM ferret_reconciliation_log').all();
     }
     async insertPlacementDecision(decision) {
         this.db.prepare(`
@@ -174,7 +179,7 @@ export class SqliteStore {
     `).run(decision.id, decision.node_id, decision.placed_by, decision.reasoning ?? null);
     }
     async getPlacementDecisions() {
-        return this.db.prepare("SELECT id, node_id, placed_by, reasoning FROM ferret_placement_decisions").all();
+        return this.db.prepare('SELECT id, node_id, placed_by, reasoning FROM ferret_placement_decisions').all();
     }
 }
 //# sourceMappingURL=sqlite.js.map

package/dist/store/sqlite.js.map

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

package/dist/store/types.d.ts

@@ -1,5 +1,5 @@
-export type NodeStatus = "stable" | "needs-review" | "roadmap" | "blocked";
-export type ContractStatus = "stable" | "roadmap" | "needs-review";
+export type NodeStatus = 'stable' | 'needs-review' | 'roadmap' | 'blocked';
+export type ContractStatus = 'stable' | 'roadmap' | 'needs-review';
 export interface FerretNode {
     id: string;
     file_path: string;
@@ -14,6 +14,10 @@ export interface FerretContract {
     shape_schema: string;
     type: string;
     status: ContractStatus;
+    /** Path to the TypeScript file this contract was generated from (code-first contracts only). */
+    code_source_file?: string;
+    /** TypeScript symbol name this contract was generated from (code-first contracts only). */
+    code_source_symbol?: string;
 }
 export interface FerretDependency {
     id: string;

package/dist/store/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specferret/core",
-  "version": "0.1.4",
+  "version": "0.3.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/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],
+};