@specferret/core 0.2.0 → 0.3.0

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/package.json

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

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.ts

@@ -20,7 +20,7 @@ export interface ExtractionResult {
     /** 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';
 }

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/index.ts

@@ -2,6 +2,7 @@
 // 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';
@@ -15,3 +16,5 @@ 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';