@specferret/core 0.2.0 → 0.4.0

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,7 @@ export * from './reconciler/index.js';
 export * from './reconciler/import-suggestions.js';
 export * from './config.js';
 export * from './utils/paths.js';
+export * from './contract.js';
+export * from './status/index.js';
+export * from './watch/index.js';
+export * from './audit/index.js';

package/src/status/index.ts

@@ -0,0 +1,68 @@
+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 async function buildStatusReport(store: DBStore): Promise<StatusReport> {
+  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<string, string[]>();
+
+  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: StatusContractEntry[] = 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: StatusReport): string {
+  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';
+}

package/src/watch/index.ts

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