@specferret/core 0.4.2 → 0.5.0

package/src/audit/index.test.ts

@@ -0,0 +1,129 @@
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { describe, it } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import { buildAuditReport } from './index.js';
+import { SqliteStore } from '../store/sqlite.js';
+
+function makeTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'ferret-audit-test-'));
+}
+
+describe('buildAuditReport — S63 source field upward drift', () => {
+  it('matching src type → no upward drift', async () => {
+    const tmpDir = makeTmpDir();
+    try {
+      const srcDir = path.join(tmpDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+      fs.writeFileSync(path.join(srcDir, 'handler.ts'), `export interface HandlerResponse {\n  name: string;\n}\n`, 'utf-8');
+
+      const store = new SqliteStore(':memory:');
+      await store.init();
+
+      const nodeId = randomUUID();
+      await store.upsertNode({
+        id: nodeId,
+        file_path: 'contracts/handler.contract.ts',
+        hash: randomUUID(),
+        status: 'stable',
+      });
+
+      await store.upsertContract({
+        id: 'api.handler',
+        node_id: nodeId,
+        shape_hash: 'abc',
+        shape_schema: JSON.stringify({
+          type: 'object',
+          properties: { name: { type: 'string' } },
+          required: ['name'],
+        }),
+        type: 'type',
+        status: 'stable',
+        code_source_file: 'src/handler.ts',
+        code_source_symbol: 'HandlerResponse',
+      });
+
+      const report = await buildAuditReport(store, tmpDir);
+      assert.equal(report.upwardDrift.length, 0, 'expected no upward drift when src matches declared schema');
+
+      await store.close();
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it('diverged src type (extra required field) → BREAKING upward drift', async () => {
+    const tmpDir = makeTmpDir();
+    try {
+      const srcDir = path.join(tmpDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+      // src has an extra required field not in the declared schema
+      fs.writeFileSync(path.join(srcDir, 'handler.ts'), `export interface HandlerResponse {\n  name: string;\n  email: string;\n}\n`, 'utf-8');
+
+      const store = new SqliteStore(':memory:');
+      await store.init();
+
+      const nodeId = randomUUID();
+      await store.upsertNode({
+        id: nodeId,
+        file_path: 'contracts/handler.contract.ts',
+        hash: randomUUID(),
+        status: 'stable',
+      });
+
+      await store.upsertContract({
+        id: 'api.handler',
+        node_id: nodeId,
+        shape_hash: 'abc',
+        shape_schema: JSON.stringify({
+          type: 'object',
+          properties: { name: { type: 'string' } },
+          required: ['name'],
+        }),
+        type: 'type',
+        status: 'stable',
+        code_source_file: 'src/handler.ts',
+        code_source_symbol: 'HandlerResponse',
+      });
+
+      const report = await buildAuditReport(store, tmpDir);
+      assert.equal(report.upwardDrift.length, 1, 'expected 1 upward drift item');
+      assert.equal(report.upwardDrift[0].contractId, 'api.handler');
+      assert.equal(report.upwardDrift[0].driftClass, 'BREAKING');
+
+      await store.close();
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it('no source fields → no upward drift (behaviour identical to today)', async () => {
+    const store = new SqliteStore(':memory:');
+    await store.init();
+
+    const nodeId = randomUUID();
+    await store.upsertNode({
+      id: nodeId,
+      file_path: 'contracts/handler.contract.ts',
+      hash: randomUUID(),
+      status: 'stable',
+    });
+
+    await store.upsertContract({
+      id: 'api.handler',
+      node_id: nodeId,
+      shape_hash: 'abc',
+      shape_schema: JSON.stringify({ type: 'object' }),
+      type: 'type',
+      status: 'stable',
+      // no code_source_file or code_source_symbol
+    });
+
+    const report = await buildAuditReport(store, process.cwd());
+    assert.equal(report.upwardDrift.length, 0, 'contracts without source fields must not produce upward drift');
+
+    await store.close();
+  });
+});

package/src/audit/index.ts

@@ -19,7 +19,7 @@ export interface AuditSummary {
   totalContracts: number;
   stable: number;
   needsReview: number;
-  roadmap: number;
+  pending: number;
   downwardBreaking: number;
   downwardNonBreaking: number;
   upwardBreaking: number;
@@ -104,7 +104,7 @@ export async function buildAuditReport(store: DBStore, projectRoot: string): Pro
       totalContracts: contracts.length,
       stable: statusReport.stable,
       needsReview: statusReport.needsReview,
-      roadmap: statusReport.roadmap,
+      pending: statusReport.pending,
       downwardBreaking,
       downwardNonBreaking,
       upwardBreaking,

package/src/context/index.test.ts

@@ -113,7 +113,7 @@ describe("writeContext — Task 5", () => {
     await store.close();
   });
 
-  it('contains version "2.0"', async () => {
+  it('contains version "3.0"', async () => {
     const tmpDir = makeTmpDir();
     tmps.push(tmpDir);
     const { store } = await makeStoreWithData(tmpDir);
@@ -123,7 +123,7 @@ describe("writeContext — Task 5", () => {
     const ctx = JSON.parse(
       fs.readFileSync(path.join(tmpDir, ".ferret", "context.json"), "utf-8"),
     ) as FerretContext;
-    assert.equal(ctx.version, "2.0");
+    assert.equal(ctx.version, "3.0");
 
     await store.close();
   });
@@ -143,7 +143,7 @@ describe("writeContext — Task 5", () => {
     await store.close();
   });
 
-  it("readContextFile migrates known legacy V2 payload without schemaVersion", () => {
+  it("readContextFile migrates v2.0 payload to v3.0 (no schemaVersion)", () => {
     const tmpDir = makeTmpDir();
     tmps.push(tmpDir);
     const ferretDir = path.join(tmpDir, ".ferret");
@@ -166,7 +166,7 @@ describe("writeContext — Task 5", () => {
     );
 
     const context = readContextFile(contextPath);
-    assert.equal(context.version, "2.0");
+    assert.equal(context.version, "3.0");
     assert.equal(context.schemaVersion, CONTEXT_SCHEMA_VERSION);
     assert.deepEqual(context.contracts, []);
     assert.deepEqual(context.edges, []);
@@ -207,7 +207,7 @@ describe("writeContext — Task 5", () => {
     fs.writeFileSync(
       contextPath,
       JSON.stringify({
-        version: "2.0",
+        version: "3.0",
         schemaVersion: "9.0.0",
         generated: new Date().toISOString(),
         contracts: [],
@@ -271,4 +271,33 @@ describe("writeContext — Task 5", () => {
 
     await store.close();
   });
+
+  it("readContextFile v2.0 migration: roadmap entries become pending", () => {
+    const tmpDir = makeTmpDir();
+    tmps.push(tmpDir);
+    const ferretDir = path.join(tmpDir, ".ferret");
+    fs.mkdirSync(ferretDir, { recursive: true });
+    const contextPath = path.join(ferretDir, "context.json");
+    fs.writeFileSync(
+      contextPath,
+      JSON.stringify({
+        version: "2.0",
+        generated: "2026-01-01T00:00:00.000Z",
+        contracts: [
+          { id: "api.roadmap", type: "api", shape: {}, status: "roadmap", specFile: "contracts/api.contract.md", codeFile: null },
+          { id: "api.stable", type: "api", shape: {}, status: "stable", specFile: "contracts/stable.contract.md", codeFile: null },
+        ],
+        edges: [],
+        needsReview: [],
+      }),
+      "utf-8",
+    );
+
+    const context = readContextFile(contextPath);
+    assert.equal(context.version, "3.0");
+    const roadmapContract = context.contracts.find((c) => c.id === "api.roadmap");
+    const stableContract = context.contracts.find((c) => c.id === "api.stable");
+    assert.equal(roadmapContract?.status, "pending");
+    assert.equal(stableContract?.status, "stable");
+  });
 });

package/src/context/index.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { DBStore } from "../store/types.js";
 
-export const CONTEXT_VERSION = "2.0" as const;
+export const CONTEXT_VERSION = "3.0" as const;
 export const CONTEXT_SCHEMA_VERSION = "1.0.0" as const;
 
 type LegacyFerretContextV2 = {
@@ -43,6 +43,31 @@ function normalizeContext(raw: unknown): FerretContext {
 
   const candidate = raw as Record<string, unknown>;
   const contextVersion = candidate.version;
+
+  // Migration: v2.0 → v3.0 (roadmap → pending)
+  if (contextVersion === "2.0") {
+    const legacy = candidate as Partial<LegacyFerretContextV2>;
+    const migratedContracts = (Array.isArray(legacy.contracts) ? legacy.contracts : [])
+      .filter((c: unknown): c is Record<string, unknown> => !!c && typeof c === 'object')
+      .map((entry) => ({
+        ...entry,
+        status: entry['status'] === 'roadmap' ? 'pending' : entry['status'],
+      })) as ContextContract[];
+    return {
+      version: CONTEXT_VERSION,
+      schemaVersion: CONTEXT_SCHEMA_VERSION,
+      generated:
+        typeof legacy.generated === "string"
+          ? legacy.generated
+          : new Date(0).toISOString(),
+      contracts: migratedContracts,
+      edges: Array.isArray(legacy.edges) ? legacy.edges : [],
+      needsReview: Array.isArray(legacy.needsReview)
+        ? legacy.needsReview
+        : [],
+    };
+  }
+
   if (contextVersion !== CONTEXT_VERSION) {
     throw new Error(
       `ferret: unsupported context.json version '${String(contextVersion)}'. Run 'ferret scan' with the current CLI to regenerate .ferret/context.json.`,
@@ -56,7 +81,7 @@ function normalizeContext(raw: unknown): FerretContext {
     );
   }
 
-  // Known migration path: V2 payloads created before schemaVersion was introduced.
+  // Known migration path: V3 payloads created before schemaVersion was introduced.
   const legacy = candidate as Partial<LegacyFerretContextV2>;
   return {
     version: CONTEXT_VERSION,

package/src/contract.ts

@@ -1,8 +1,6 @@
 import { z } from 'zod';
 
-export interface Contract<
-  T extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>,
-> {
+export interface Contract<T extends Record<string, z.ZodTypeAny> = Record<string, z.ZodTypeAny>> {
   id?: string;
   value: string;
   output: T;
@@ -12,6 +10,7 @@ export interface Contract<
   consumes?: ContractRef[];
   forbids?: string[];
   status?: 'complete' | 'active' | 'pending';
+  source?: { file: string; symbol: string };
   closedBy?: string;
   closedWhen?: string;
   dependsOn?: ContractRef[];
@@ -24,9 +23,7 @@ export type ContractRef = Omit<Contract<any>, 'invariants' | 'schema'> & {
   schema?: z.ZodObject<any>;
 };
 
-export function defineContract<T extends Record<string, z.ZodTypeAny>>(
-  contract: Contract<T>,
-): Contract<T> & { schema: z.ZodObject<T> } {
+export function defineContract<T extends Record<string, z.ZodTypeAny>>(contract: Contract<T>): Contract<T> & { schema: z.ZodObject<T> } {
   if ('id' in contract && contract.id !== undefined && contract.id.trim() === '') {
     throw new Error('defineContract: id must be a non-empty string if provided');
   }

package/src/extractor/__fixtures__/active-status.fixture.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+export const activeContract = {
+  id: 'activeContract',
+  value: 'Active contract — should map to stable',
+  status: 'active' as const,
+  output: {
+    id: z.string(),
+  },
+};

package/src/extractor/__fixtures__/no-status.fixture.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+
+export const pendingContract = {
+  id: 'pendingContract',
+  value: 'Pending contract — should map to pending',
+  output: {
+    id: z.string(),
+  },
+};

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

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+// Export name uses underscores; .id uses dot notation — the standard convention.
+export const tables_dataSource = {
+  id: 'tables.dataSource',
+  value: 'tables data source',
+  output: { data: z.string() },
+};
+
+export const tables_ingestionRun = {
+  id: 'tables.ingestionRun',
+  value: 'tables ingestion run',
+  output: { runId: z.string() },
+  consumes: [tables_dataSource],
+};

package/src/extractor/__fixtures__/source-field.fixture.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { defineContract } from '../../contract.js';
+
+export const apiGetKeywords = defineContract({
+  id: 'api.getKeywords',
+  value: 'Keywords endpoint',
+  output: {
+    keywords: z.array(z.string()),
+  },
+  source: { file: 'src/routes/keywords.ts', symbol: 'KeywordsResponse' },
+});

package/src/extractor/frontmatter.test.ts

@@ -289,3 +289,74 @@ ferret:
     assert.equal(r1.contracts[0].shape_hash, r2.contracts[0].shape_hash);
   });
 });
+
+describe('extractFromSpecFile — S62 contractStatus mapping', () => {
+  it('no status field → contractStatus is "pending"', () => {
+    const spec = `---
+ferret:
+  id: api.no-status
+  type: api
+  shape:
+    type: object
+---
+`;
+    const result = extractFromSpecFile('contracts/no-status.contract.md', spec);
+    assert.equal(result.contracts[0].contractStatus, 'pending');
+  });
+
+  it('status: active → contractStatus is "stable"', () => {
+    const spec = `---
+ferret:
+  id: api.active
+  type: api
+  status: active
+  shape:
+    type: object
+---
+`;
+    const result = extractFromSpecFile('contracts/active.contract.md', spec);
+    assert.equal(result.contracts[0].contractStatus, 'stable');
+  });
+
+  it('status: complete → contractStatus is "stable"', () => {
+    const spec = `---
+ferret:
+  id: api.complete
+  type: api
+  status: complete
+  shape:
+    type: object
+---
+`;
+    const result = extractFromSpecFile('contracts/complete.contract.md', spec);
+    assert.equal(result.contracts[0].contractStatus, 'stable');
+  });
+
+  it('status: pending → contractStatus is "pending"', () => {
+    const spec = `---
+ferret:
+  id: api.pending
+  type: api
+  status: pending
+  shape:
+    type: object
+---
+`;
+    const result = extractFromSpecFile('contracts/pending.contract.md', spec);
+    assert.equal(result.contracts[0].contractStatus, 'pending');
+  });
+
+  it('unknown status value → contractStatus defaults to "pending"', () => {
+    const spec = `---
+ferret:
+  id: api.unknown
+  type: api
+  status: some-unknown-value
+  shape:
+    type: object
+---
+`;
+    const result = extractFromSpecFile('contracts/unknown.contract.md', spec);
+    assert.equal(result.contracts[0].contractStatus, 'pending');
+  });
+});

package/src/extractor/frontmatter.ts

@@ -5,6 +5,15 @@ import matter from 'gray-matter';
 import { validateContractType, validateFerretSchema } from './validator.js';
 import { hashSchema } from './hash.js';
 import type { ContractType } from './contract-types.js';
+import type { ContractStatus } from '../store/types.js';
+
+/**
+ * Maps a raw `ferret.status` string value to a normalised ContractStatus.
+ * `active` and `complete` map to `'stable'`; anything else (including `undefined`) maps to `'pending'`.
+ */
+export function mapToContractStatus(rawStatus: unknown): ContractStatus {
+  return rawStatus === 'active' || rawStatus === 'complete' ? 'stable' : 'pending';
+}
 
 export interface ExtractionResult {
   filePath: string;
@@ -15,6 +24,7 @@ export interface ExtractionResult {
     shape: object;
     shape_hash: string;
     imports: string[];
+    contractStatus?: ContractStatus;
     /** Path to the TypeScript source file (code-first contracts only). */
     sourceFile?: string;
     /** TypeScript symbol name (code-first contracts only). */
@@ -67,6 +77,9 @@ export function extractFromSpecFile(filePath: string, fileContent: string): Extr
   const sourceFile = typeof source?.file === 'string' ? source.file : undefined;
   const sourceSymbol = typeof source?.symbol === 'string' ? source.symbol : undefined;
 
+  const rawStatus = ferret.status as string | undefined;
+  const contractStatus: ContractStatus = mapToContractStatus(rawStatus);
+
   return {
     filePath,
     fileType: 'spec',
@@ -77,6 +90,7 @@ export function extractFromSpecFile(filePath: string, fileContent: string): Extr
         shape: ferret.shape as object,
         shape_hash: hashSchema(ferret.shape),
         imports: Array.isArray(ferret.imports) ? (ferret.imports as string[]) : [],
+        contractStatus,
         ...(sourceFile !== undefined && { sourceFile }),
         ...(sourceSymbol !== undefined && { sourceSymbol }),
       },

package/src/extractor/typescript-contract.test.ts

@@ -61,9 +61,7 @@ describe('extractFromContractFile', () => {
   });
 
   it('zod schema with optional fields extracts without throwing', async () => {
-    await assert.doesNotReject(() =>
-      extractFromContractFile(fixtures('optional-fields.fixture.ts')),
-    );
+    await assert.doesNotReject(() => extractFromContractFile(fixtures('optional-fields.fixture.ts')));
 
     const result = await extractFromContractFile(fixtures('optional-fields.fixture.ts'));
     assert.equal(result.contracts.length, 1);
@@ -134,10 +132,45 @@ describe('extractFromContractFile', () => {
     assert.equal(result.contracts[0].sourceSymbol, 'userContract');
   });
 
+  it('stored contract id uses .id field when present, not export name', async () => {
+    const result = await extractFromContractFile(fixtures('same-file-dotted-id-consumes.fixture.ts'));
+
+    const ids = result.contracts.map((c) => c.id);
+    assert.ok(ids.includes('tables.dataSource'), 'expected tables.dataSource stored id');
+    assert.ok(ids.includes('tables.ingestionRun'), 'expected tables.ingestionRun stored id');
+    assert.ok(!ids.includes('tables_dataSource'), 'export name must not be used as stored id when .id is present');
+    assert.ok(!ids.includes('tables_ingestionRun'), 'export name must not be used as stored id when .id is present');
+  });
+
+  it('same-file consumes with dotted .id resolves to .id, not export name', async () => {
+    const result = await extractFromContractFile(fixtures('same-file-dotted-id-consumes.fixture.ts'));
+
+    const ingestionRun = result.contracts.find((c) => c.id === 'tables.ingestionRun');
+    assert.ok(ingestionRun, 'tables.ingestionRun not found');
+    assert.deepEqual(ingestionRun.imports, ['tables.dataSource']);
+  });
+
   it('module that throws at top-level causes extractFromContractFile to reject', async () => {
-    await assert.rejects(
-      () => extractFromContractFile(fixtures('throws-on-import.fixture.ts')),
-      /intentional module-level throw/,
-    );
+    await assert.rejects(() => extractFromContractFile(fixtures('throws-on-import.fixture.ts')), /intentional module-level throw/);
+  });
+
+  it('S62: contract with status: active → contractStatus is "stable"', async () => {
+    const result = await extractFromContractFile(fixtures('active-status.fixture.ts'));
+    assert.equal(result.contracts.length, 1);
+    assert.equal(result.contracts[0].contractStatus, 'stable');
+  });
+
+  it('S62: contract with no status field → contractStatus is "pending"', async () => {
+    const result = await extractFromContractFile(fixtures('no-status.fixture.ts'));
+    assert.equal(result.contracts.length, 1);
+    assert.equal(result.contracts[0].contractStatus, 'pending');
+  });
+
+  it('S63: source field set → sourceFile is source.file and sourceSymbol is source.symbol', async () => {
+    const result = await extractFromContractFile(fixtures('source-field.fixture.ts'));
+
+    assert.equal(result.contracts.length, 1);
+    assert.equal(result.contracts[0].sourceFile, 'src/routes/keywords.ts');
+    assert.equal(result.contracts[0].sourceSymbol, 'KeywordsResponse');
   });
 });

package/src/extractor/typescript-contract.ts

@@ -5,6 +5,7 @@ import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { isContract } from '../contract.js';
 import { hashSchema } from './hash.js';
+import { mapToContractStatus } from './frontmatter.js';
 import type { ExtractionResult } from './frontmatter.js';
 
 export async function extractFromContractFile(filePath: string): Promise<ExtractionResult> {
@@ -44,7 +45,7 @@ export async function extractFromContractFile(filePath: string): Promise<Extract
       for (const consumed of exportValue.consumes) {
         const samefile = exportNameMap.get(consumed);
         if (samefile !== undefined) {
-          imports.push(samefile);
+          imports.push(consumed.id ?? samefile);
         } else if (consumed.id !== undefined) {
           imports.push(consumed.id);
         } else {
@@ -57,13 +58,14 @@ export async function extractFromContractFile(filePath: string): Promise<Extract
     }
 
     contracts.push({
-      id: exportName,
+      id: exportValue.id ?? exportName,
       type: 'type',
       shape,
       shape_hash,
       imports,
-      sourceFile: filePath,
-      sourceSymbol: exportName,
+      contractStatus: mapToContractStatus(exportValue.status),
+      sourceFile: exportValue.source?.file || filePath,
+      sourceSymbol: exportValue.source?.symbol || exportName,
     });
   }
 

package/src/reconciler/index.ts

@@ -139,10 +139,10 @@ export class Reconciler {
 
         if (!dependentNode) continue;
 
-        // Skip nodes that are already reviewing or roadmap, per S011 instructions.
+        // Skip nodes that are already reviewing or pending, per S011 instructions.
         if (
           dependentNode.status === "needs-review" ||
-          dependentNode.status === "roadmap"
+          dependentNode.status === "pending"
         ) {
           continue;
         }
@@ -169,12 +169,12 @@ export class Reconciler {
       }
     }
 
-    // S012: graph is consistent when no nodes need review and all nodes are stable or roadmap.
-    // Roadmap nodes are planned-but-not-yet-built and are an acceptable stable state.
+    // S012: graph is consistent when no nodes need review and all nodes are stable or pending.
+    // Pending nodes are unverified and are an acceptable stable state.
     return {
       consistent:
         flaggedNodes.length === 0 &&
-        nodes.every((n) => n.status === "stable" || n.status === "roadmap"),
+        nodes.every((n) => n.status === "stable" || n.status === "pending"),
       flagged: flaggedNodes,
       integrityViolations,
       importSuggestions,

package/src/status/index.ts

@@ -3,7 +3,7 @@ import type { DBStore, ContractStatus } from '../store/types.js';
 export type StatusContractEntry = {
   id: string;
   status: ContractStatus;
-  driftClass: 'breaking' | 'stable' | 'roadmap';
+  driftClass: 'breaking' | 'stable' | 'pending';
   dependentCount: number;
   dependents: string[];
 };
@@ -13,7 +13,7 @@ export type StatusReport = {
   timestamp: string;
   total: number;
   stable: number;
-  roadmap: number;
+  pending: number;
   needsReview: number;
   contracts: StatusContractEntry[];
 };
@@ -37,7 +37,7 @@ export async function buildStatusReport(store: DBStore): Promise<StatusReport> {
     return {
       id: c.id,
       status: c.status,
-      driftClass: c.status === 'needs-review' ? 'breaking' : c.status === 'roadmap' ? 'roadmap' : 'stable',
+      driftClass: c.status === 'needs-review' ? 'breaking' : c.status === 'pending' ? 'pending' : 'stable',
       dependentCount: dependents.length,
       dependents,
     };
@@ -48,7 +48,7 @@ export async function buildStatusReport(store: DBStore): Promise<StatusReport> {
     timestamp: new Date().toISOString(),
     total: contracts.length,
     stable: contracts.filter((c) => c.status === 'stable').length,
-    roadmap: contracts.filter((c) => c.status === 'roadmap').length,
+    pending: contracts.filter((c) => c.status === 'pending').length,
     needsReview: contracts.filter((c) => c.status === 'needs-review').length,
     contracts: entries,
   };