@specferret/core 0.1.4 → 0.3.0

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],
+};

package/src/extractor/__fixtures__/three-unresolved.fixture.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+// Three separate unresolvable external references (not exported, no id)
+const ext1 = { value: 'ext1', output: { a: z.string() } };
+const ext2 = { value: 'ext2', output: { b: z.string() } };
+const ext3 = { value: 'ext3', output: { c: z.string() } };
+
+export const contractA = {
+  value: 'Contract A',
+  output: { x: z.string() },
+  consumes: [ext1],
+};
+
+export const contractB = {
+  value: 'Contract B',
+  output: { y: z.string() },
+  consumes: [ext2],
+};
+
+export const contractC = {
+  value: 'Contract C',
+  output: { zField: z.string() },
+  consumes: [ext3],
+};

package/src/extractor/__fixtures__/throws-on-import.fixture.ts

@@ -0,0 +1,3 @@
+// Fixture: throws synchronously at module top-level.
+// Used to verify that extractFromContractFile() does not swallow import errors.
+throw new Error('intentional module-level throw');

package/src/extractor/frontmatter.test.ts

@@ -215,3 +215,77 @@ ferret:
     assert.equal(r1.contracts[0].shape_hash, r2.contracts[0].shape_hash);
   });
 });
+
+describe('extractFromSpecFile — S50 source block', () => {
+  const SPEC_WITH_SOURCE = `---
+ferret:
+  id: auth.jwt
+  type: type
+  source:
+    file: src/auth/jwt.ts
+    symbol: JwtPayload
+  shape:
+    type: object
+    properties:
+      sub:
+        type: string
+    required: [sub]
+---
+`;
+
+  const SPEC_WITHOUT_SOURCE = `---
+ferret:
+  id: auth.jwt
+  type: type
+  shape:
+    type: object
+    properties:
+      sub:
+        type: string
+    required: [sub]
+---
+`;
+
+  it('parses source.file and source.symbol when present', () => {
+    const result = extractFromSpecFile('contracts/auth/jwt.contract.md', SPEC_WITH_SOURCE);
+    assert.equal(result.contracts.length, 1);
+    assert.equal(result.contracts[0].sourceFile, 'src/auth/jwt.ts');
+    assert.equal(result.contracts[0].sourceSymbol, 'JwtPayload');
+  });
+
+  it('has undefined sourceFile and sourceSymbol when source block absent', () => {
+    const result = extractFromSpecFile('contracts/auth/jwt.contract.md', SPEC_WITHOUT_SOURCE);
+    assert.equal(result.contracts.length, 1);
+    assert.equal(result.contracts[0].sourceFile, undefined);
+    assert.equal(result.contracts[0].sourceSymbol, undefined);
+  });
+
+  it('ignores source block with non-string fields gracefully', () => {
+    const specBadSource = `---
+ferret:
+  id: auth.jwt
+  type: type
+  source:
+    file: 42
+    symbol: [not, a, string]
+  shape:
+    type: object
+---
+`;
+    const result = extractFromSpecFile('contracts/auth/jwt.contract.md', specBadSource);
+    assert.equal(result.contracts[0].sourceFile, undefined);
+    assert.equal(result.contracts[0].sourceSymbol, undefined);
+  });
+
+  it('source block does not affect shape_hash', () => {
+    const r1 = extractFromSpecFile('contracts/a.contract.md', SPEC_WITH_SOURCE);
+    const r2 = extractFromSpecFile('contracts/b.contract.md', SPEC_WITHOUT_SOURCE);
+    assert.equal(r1.contracts[0].shape_hash, r2.contracts[0].shape_hash);
+  });
+
+  it('identical source blocks produce identical shape_hash (deterministic snapshot)', () => {
+    const r1 = extractFromSpecFile('contracts/a.contract.md', SPEC_WITH_SOURCE);
+    const r2 = extractFromSpecFile('contracts/b.contract.md', SPEC_WITH_SOURCE);
+    assert.equal(r1.contracts[0].shape_hash, r2.contracts[0].shape_hash);
+  });
+});

package/src/extractor/frontmatter.ts

@@ -15,8 +15,12 @@ export interface ExtractionResult {
     shape: object;
     shape_hash: string;
     imports: string[];
+    /** Path to the TypeScript source file (code-first contracts only). */
+    sourceFile?: string;
+    /** TypeScript symbol name (code-first contracts only). */
+    sourceSymbol?: string;
   }>;
-  extractedBy: 'gray-matter' | 'tree-sitter';
+  extractedBy: 'gray-matter' | 'tree-sitter' | 'typescript';
   extractedAt: number; // unix ms
   warning?: 'no-frontmatter';
 }
@@ -59,6 +63,10 @@ export function extractFromSpecFile(filePath: string, fileContent: string): Extr
   const validation = validateFerretSchema(ferret.shape, filePath);
   validation.warnings.forEach((w) => process.stderr.write(w + '\n'));
 
+  const source = ferret.source as { file?: unknown; symbol?: unknown } | undefined;
+  const sourceFile = typeof source?.file === 'string' ? source.file : undefined;
+  const sourceSymbol = typeof source?.symbol === 'string' ? source.symbol : undefined;
+
   return {
     filePath,
     fileType: 'spec',
@@ -69,6 +77,8 @@ 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[]) : [],
+        ...(sourceFile !== undefined && { sourceFile }),
+        ...(sourceSymbol !== undefined && { sourceSymbol }),
       },
     ],
     extractedBy: 'gray-matter',

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

@@ -0,0 +1,143 @@
+import assert from 'node:assert/strict';
+import { describe, expect, it, spyOn } from 'bun:test';
+import { join } from 'node:path';
+import { extractFromContractFile } from './typescript-contract.js';
+
+const fixtures = (name: string) => join(import.meta.dir, '__fixtures__', name);
+
+describe('extractFromContractFile', () => {
+  it('single valid export → one contract with correct id, shape, shape_hash, imports', async () => {
+    const result = await extractFromContractFile(fixtures('one-contract.fixture.ts'));
+
+    assert.equal(result.contracts.length, 1);
+    assert.equal(result.contracts[0].id, 'userContract');
+    assert.equal(typeof result.contracts[0].shape, 'object');
+    assert.equal(typeof result.contracts[0].shape_hash, 'string');
+    assert.equal(result.contracts[0].shape_hash.length, 64);
+    assert.deepEqual(result.contracts[0].imports, []);
+    assert.equal(result.warning, undefined);
+  });
+
+  it('multiple exports — only valid contracts extracted, non-contracts skipped', async () => {
+    const result = await extractFromContractFile(fixtures('mixed.fixture.ts'));
+
+    const ids = result.contracts.map((c) => c.id);
+    assert.equal(result.contracts.length, 2);
+    assert.ok(ids.includes('validContract'));
+    assert.ok(ids.includes('anotherValid'));
+  });
+
+  it('no ferret contracts → empty contracts array + warning: no-frontmatter', async () => {
+    const result = await extractFromContractFile(fixtures('empty.fixture.ts'));
+
+    assert.equal(result.contracts.length, 0);
+    assert.equal(result.warning, 'no-frontmatter');
+  });
+
+  it('extractedBy is always "typescript"', async () => {
+    const a = await extractFromContractFile(fixtures('one-contract.fixture.ts'));
+    const b = await extractFromContractFile(fixtures('empty.fixture.ts'));
+
+    assert.equal(a.extractedBy, 'typescript');
+    assert.equal(b.extractedBy, 'typescript');
+  });
+
+  it('extractedAt is a unix ms timestamp within 1s of Date.now()', async () => {
+    const before = Date.now();
+    const result = await extractFromContractFile(fixtures('one-contract.fixture.ts'));
+    const after = Date.now();
+
+    assert.ok(result.extractedAt >= before - 1000);
+    assert.ok(result.extractedAt <= after + 1000);
+  });
+
+  it('shape hash is deterministic — two runs on same file produce identical hash', async () => {
+    // Clear module cache by using a unique query approach isn't possible cleanly in Bun,
+    // but the hash must be stable across calls even with the cached module.
+    const r1 = await extractFromContractFile(fixtures('one-contract.fixture.ts'));
+    const r2 = await extractFromContractFile(fixtures('one-contract.fixture.ts'));
+
+    assert.equal(r1.contracts[0].shape_hash, r2.contracts[0].shape_hash);
+  });
+
+  it('zod schema with optional fields extracts without throwing', async () => {
+    await assert.doesNotReject(() =>
+      extractFromContractFile(fixtures('optional-fields.fixture.ts')),
+    );
+
+    const result = await extractFromContractFile(fixtures('optional-fields.fixture.ts'));
+    assert.equal(result.contracts.length, 1);
+    assert.equal(result.contracts[0].id, 'optionalFieldsContract');
+  });
+
+  it('same-file consumes reference resolves to the correct export name', async () => {
+    const result = await extractFromContractFile(fixtures('same-file-consumes.fixture.ts'));
+
+    const dependent = result.contracts.find((c) => c.id === 'dependentContract');
+    assert.ok(dependent, 'dependentContract not found in result');
+    assert.deepEqual(dependent.imports, ['baseContract']);
+  });
+
+  it('cross-file reference with explicit id resolves to c.id', async () => {
+    const result = await extractFromContractFile(fixtures('cross-file-id.fixture.ts'));
+
+    assert.equal(result.contracts.length, 1);
+    assert.deepEqual(result.contracts[0].imports, ['external.known.id']);
+  });
+
+  it('cross-file reference without id emits exactly one warning and returns [unresolved]', async () => {
+    const spy = spyOn(process.stderr, 'write').mockImplementation(() => true);
+    try {
+      const result = await extractFromContractFile(fixtures('cross-file-unresolved.fixture.ts'));
+
+      expect(spy.mock.calls.length).toBe(1);
+      assert.deepEqual(result.contracts[0].imports, ['[unresolved]']);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('three contracts each with unresolvable cross-file ref → three warnings emitted', async () => {
+    const spy = spyOn(process.stderr, 'write').mockImplementation(() => true);
+    try {
+      const result = await extractFromContractFile(fixtures('three-unresolved.fixture.ts'));
+
+      expect(spy.mock.calls.length).toBe(3);
+      assert.equal(result.contracts.length, 3);
+      result.contracts.forEach((c) => {
+        assert.deepEqual(c.imports, ['[unresolved]']);
+      });
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('filePath and fileType are set correctly in the result', async () => {
+    const filePath = fixtures('one-contract.fixture.ts');
+    const result = await extractFromContractFile(filePath);
+
+    assert.equal(result.filePath, filePath);
+    assert.equal(result.fileType, 'code');
+  });
+
+  it('fileType is "code" even when no contracts found', async () => {
+    const result = await extractFromContractFile(fixtures('empty.fixture.ts'));
+
+    assert.equal(result.fileType, 'code');
+  });
+
+  it('each contract has sourceFile and sourceSymbol populated', async () => {
+    const filePath = fixtures('one-contract.fixture.ts');
+    const result = await extractFromContractFile(filePath);
+
+    assert.equal(result.contracts[0].sourceFile, filePath);
+    assert.equal(result.contracts[0].sourceSymbol, 'userContract');
+  });
+
+  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/,
+    );
+  });
+});

package/src/extractor/typescript-contract.ts

@@ -0,0 +1,76 @@
+// 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';
+import type { ExtractionResult } from './frontmatter.js';
+
+export async function extractFromContractFile(filePath: string): Promise<ExtractionResult> {
+  const mod = (await import(filePath)) as Record<string, unknown>;
+
+  // Pass 1: build Map<contract object reference → export name> for same-file resolution
+  const exportNameMap = new Map<object, string>();
+  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: ExtractionResult['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: string[] = [];
+    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(),
+  };
+}

package/src/extractor/upward-classifier.test.ts

@@ -0,0 +1,188 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'bun:test';
+import { classifyUpwardDrift } from './upward-classifier.js';
+
+const FILE = 'src/auth/jwt.ts';
+const SYMBOL = 'JwtPayload';
+const CONTRACT_ID = 'auth.jwt';
+
+// ─── Canonical declared schema ────────────────────────────────────────────────
+
+const DECLARED_SCHEMA = {
+  type: 'object',
+  properties: {
+    sub: { type: 'string' },
+    role: { type: 'string', enum: ['admin', 'user'] },
+    exp: { type: 'number' },
+  },
+  required: ['sub', 'role'],
+};
+
+describe('classifyUpwardDrift — S51: BREAKING cases', () => {
+  it('required field removed from code shape → BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        role: { type: 'string', enum: ['admin', 'user'] },
+        exp: { type: 'number' },
+      },
+      required: ['role'],
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'BREAKING');
+    assert.match(result.reason, /required field\(s\) removed: sub/);
+    assert.equal(result.contractId, CONTRACT_ID);
+    assert.equal(result.sourceFile, FILE);
+    assert.equal(result.sourceSymbol, SYMBOL);
+  });
+
+  it('field type changed in code → BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        sub: { type: 'number' }, // was string
+        role: { type: 'string', enum: ['admin', 'user'] },
+        exp: { type: 'number' },
+      },
+      required: ['sub', 'role'],
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'BREAKING');
+    assert.match(result.reason, /type changed/);
+  });
+
+  it('required field added in code → BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        sub: { type: 'string' },
+        role: { type: 'string', enum: ['admin', 'user'] },
+        exp: { type: 'number' },
+        iat: { type: 'number' },
+      },
+      required: ['sub', 'role', 'iat'], // iat newly required
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'BREAKING');
+    assert.match(result.reason, /required field\(s\) added: iat/);
+  });
+
+  it('property removed entirely from code → BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        sub: { type: 'string' },
+        exp: { type: 'number' },
+        // role removed entirely
+      },
+      required: ['sub'],
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'BREAKING');
+    assert.match(result.reason, /property 'role' removed|required field\(s\) removed/);
+  });
+
+  it('enum value removed from code → BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        sub: { type: 'string' },
+        role: { type: 'string', enum: ['admin'] }, // 'user' removed
+        exp: { type: 'number' },
+      },
+      required: ['sub', 'role'],
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'BREAKING');
+    assert.match(result.reason, /enum value\(s\) removed/);
+  });
+});
+
+describe('classifyUpwardDrift — S51: NON_BREAKING cases', () => {
+  it('optional field added in code → NON_BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        sub: { type: 'string' },
+        role: { type: 'string', enum: ['admin', 'user'] },
+        exp: { type: 'number' },
+        nbf: { type: 'number' }, // new optional field
+      },
+      required: ['sub', 'role'],
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'NON_BREAKING');
+    assert.match(result.reason, /optional field\(s\) added/);
+  });
+
+  it('enum value added to code → NON_BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        sub: { type: 'string' },
+        role: { type: 'string', enum: ['admin', 'user', 'superuser'] }, // 'superuser' added
+        exp: { type: 'number' },
+      },
+      required: ['sub', 'role'],
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'NON_BREAKING');
+    assert.match(result.reason, /enum value\(s\) added/);
+  });
+});
+
+describe('classifyUpwardDrift — S51: NOOP cases', () => {
+  it('identical schemas → NOOP', () => {
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, DECLARED_SCHEMA, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'NOOP');
+    assert.match(result.reason, /semantically identical/);
+  });
+
+  it('property order change in code does not produce drift (hash-stable)', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        // same properties, different key order
+        exp: { type: 'number' },
+        role: { type: 'string', enum: ['admin', 'user'] },
+        sub: { type: 'string' },
+      },
+      required: ['role', 'sub'], // reordered required array
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'NOOP');
+  });
+
+  it('empty vs empty schemas → NOOP', () => {
+    const result = classifyUpwardDrift(CONTRACT_ID, {}, {}, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'NOOP');
+  });
+});
+
+describe('classifyUpwardDrift — S51: result shape', () => {
+  it('result always contains all required fields', () => {
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, DECLARED_SCHEMA, FILE, SYMBOL);
+    assert.ok('contractId' in result);
+    assert.ok('driftClass' in result);
+    assert.ok('sourceFile' in result);
+    assert.ok('sourceSymbol' in result);
+    assert.ok('reason' in result);
+    assert.equal(typeof result.reason, 'string');
+  });
+
+  it('is a pure function — same inputs produce same output', () => {
+    const r1 = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, DECLARED_SCHEMA, FILE, SYMBOL);
+    const r2 = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, DECLARED_SCHEMA, FILE, SYMBOL);
+    assert.deepEqual(r1, r2);
+  });
+
+  it('does not mutate inputs', () => {
+    const declared = { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] };
+    const code = { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] };
+    const declaredBefore = JSON.stringify(declared);
+    const codeBefore = JSON.stringify(code);
+    classifyUpwardDrift(CONTRACT_ID, declared, code, FILE, SYMBOL);
+    assert.equal(JSON.stringify(declared), declaredBefore);
+    assert.equal(JSON.stringify(code), codeBefore);
+  });
+});