@specferret/core 0.1.2 → 0.1.4

package/src/extractor/frontmatter.test.ts

@@ -0,0 +1,217 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'bun:test';
+import { extractFromSpecFile } from './frontmatter.js';
+import { CONTRACT_TYPES } from './contract-types.js';
+
+const VALID_SPEC = `---
+ferret:
+  id: api.GET/users
+  type: api
+  shape:
+    response:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+            format: uuid
+          name:
+            type: string
+        required: [id, name]
+---
+
+# Users Endpoint
+
+Returns all users.
+`;
+
+const SPEC_WITH_IMPORTS = `---
+ferret:
+  id: api.GET/search
+  type: api
+  shape:
+    response:
+      type: array
+      items:
+        type: string
+  imports:
+    - auth.jwt
+    - tables.document
+---
+`;
+
+const SPEC_WITH_UNSUPPORTED_KEYWORD = `---
+ferret:
+  id: tables.user
+  type: table
+  shape:
+    type: object
+    allOf:
+      - type: string
+    properties:
+      id:
+        type: string
+---
+`;
+
+const SPEC_NO_FRONTMATTER = `# Just a markdown file
+
+No frontmatter here. Ferret should skip this.
+`;
+
+const SPEC_MISSING_FIELDS = `---
+ferret:
+  id: api.GET/broken
+  type: api
+---
+`;
+
+const SPEC_INVALID_TYPE = `---
+ferret:
+  id: api.GET/broken
+  type: service
+  shape:
+    type: object
+---
+`;
+
+describe('extractFromSpecFile — Task 3', () => {
+  it('extracts valid frontmatter correctly', () => {
+    const result = extractFromSpecFile('contracts/users.contract.md', VALID_SPEC);
+    assert.equal(result.filePath, 'contracts/users.contract.md');
+    assert.equal(result.fileType, 'spec');
+    assert.equal(result.extractedBy, 'gray-matter');
+    assert.equal(result.warning, undefined);
+    assert.equal(result.contracts.length, 1);
+    assert.equal(result.contracts[0].id, 'api.GET/users');
+    assert.equal(result.contracts[0].type, 'api');
+    assert.notEqual(result.contracts[0].shape_hash, undefined);
+    assert.equal(result.contracts[0].shape_hash.length, 64);
+    assert.deepEqual(result.contracts[0].imports, []);
+  });
+
+  it('extracts imports correctly', () => {
+    const result = extractFromSpecFile('contracts/search.contract.md', SPEC_WITH_IMPORTS);
+    assert.deepEqual(result.contracts[0].imports, ['auth.jwt', 'tables.document']);
+  });
+
+  it('missing frontmatter returns warning, empty contracts, does not throw', () => {
+    const result = extractFromSpecFile('contracts/plain.contract.md', SPEC_NO_FRONTMATTER);
+    assert.equal(result.warning, 'no-frontmatter');
+    assert.equal(result.contracts.length, 0);
+    assert.equal(result.filePath, 'contracts/plain.contract.md');
+    assert.equal(result.fileType, 'spec');
+  });
+
+  it('missing required field "shape" throws with field name in message', () => {
+    assert.throws(() => extractFromSpecFile('contracts/broken.contract.md', SPEC_MISSING_FIELDS), /shape/);
+  });
+
+  it('missing multiple required fields throws with all field names in message', () => {
+    const specMissingAll = `---\nferret:\n  someField: value\n---\n`;
+    assert.throws(() => extractFromSpecFile('contracts/broken.contract.md', specMissingAll), /id.*type.*shape|Missing required/);
+  });
+
+  it('invalid top-level contract type throws and lists allowed values', () => {
+    assert.throws(
+      () => extractFromSpecFile('contracts/broken.contract.md', SPEC_INVALID_TYPE),
+      /Invalid contract type 'service'.*Allowed types: api, table, type, event, flow, config/,
+    );
+  });
+
+  it('unsupported schema keyword produces warning, does not fail', () => {
+    const stderrOutput: string[] = [];
+    const originalWrite = process.stderr.write.bind(process.stderr);
+    // Capture stderr writes
+    process.stderr.write = (chunk: any) => {
+      stderrOutput.push(String(chunk));
+      return true;
+    };
+
+    let result: ReturnType<typeof extractFromSpecFile> | undefined;
+    try {
+      result = extractFromSpecFile('contracts/complex.contract.md', SPEC_WITH_UNSUPPORTED_KEYWORD);
+    } finally {
+      process.stderr.write = originalWrite;
+    }
+
+    assert.notEqual(result, undefined);
+    assert.equal(result!.contracts.length, 1);
+    assert.equal(result!.warning, undefined);
+    assert.equal(
+      stderrOutput.some((line) => line.includes('allOf')),
+      true,
+    );
+  });
+
+  it('all six allowed types are accepted without error', () => {
+    for (const contractType of CONTRACT_TYPES) {
+      const spec = `---
+ferret:
+  id: test.${contractType}
+  type: ${contractType}
+  shape:
+    type: object
+---
+`;
+      assert.doesNotThrow(() => extractFromSpecFile(`contracts/${contractType}.contract.md`, spec));
+    }
+  });
+
+  it('extraction is synchronous — the function itself has no async/await', () => {
+    // If extractFromSpecFile returns a Promise, this would be a thenable object
+    const result = extractFromSpecFile('contracts/users.contract.md', VALID_SPEC);
+    assert.equal(result instanceof Promise, false);
+    assert.notEqual(typeof (result as any).then, 'function');
+  });
+
+  it('identical files produce identical shape_hash', () => {
+    const r1 = extractFromSpecFile('contracts/a.contract.md', VALID_SPEC);
+    const r2 = extractFromSpecFile('contracts/b.contract.md', VALID_SPEC);
+    assert.equal(r1.contracts[0].shape_hash, r2.contracts[0].shape_hash);
+  });
+
+  it('different shapes produce different shape_hash', () => {
+    const specA = VALID_SPEC;
+    const specB = specA.replace('format: uuid', 'format: email');
+    const r1 = extractFromSpecFile('contracts/a.contract.md', specA);
+    const r2 = extractFromSpecFile('contracts/b.contract.md', specB);
+    assert.notEqual(r1.contracts[0].shape_hash, r2.contracts[0].shape_hash);
+  });
+
+  it('property order change in shape does NOT change shape_hash', () => {
+    const specA = `---
+ferret:
+  id: api.GET/test
+  type: api
+  shape:
+    type: object
+    properties:
+      id:
+        type: string
+      name:
+        type: string
+    required: [id, name]
+---
+`;
+    const specB = `---
+ferret:
+  id: api.GET/test
+  type: api
+  shape:
+    type: object
+    properties:
+      name:
+        type: string
+      id:
+        type: string
+    required: [id, name]
+---
+`;
+    const r1 = extractFromSpecFile('contracts/a.contract.md', specA);
+    const r2 = extractFromSpecFile('contracts/b.contract.md', specB);
+    // Keys are sorted before hashing — order change is a no-change
+    assert.equal(r1.contracts[0].shape_hash, r2.contracts[0].shape_hash);
+  });
+});

package/src/extractor/frontmatter.ts

@@ -0,0 +1,77 @@
+// Synchronous only. No async. No await. Anywhere in this file.
+// Extractor layer — turns a spec file into an ExtractionResult using gray-matter.
+
+import matter from 'gray-matter';
+import { validateContractType, validateFerretSchema } from './validator.js';
+import { hashSchema } from './hash.js';
+import type { ContractType } from './contract-types.js';
+
+export interface ExtractionResult {
+  filePath: string;
+  fileType: 'spec' | 'code';
+  contracts: Array<{
+    id: string;
+    type: ContractType;
+    shape: object;
+    shape_hash: string;
+    imports: string[];
+  }>;
+  extractedBy: 'gray-matter' | 'tree-sitter';
+  extractedAt: number; // unix ms
+  warning?: 'no-frontmatter';
+}
+
+/**
+ * Extracts a FerretContract from a spec file's YAML frontmatter.
+ *
+ * Rules:
+ *   - No frontmatter → return empty contracts + warning: 'no-frontmatter'
+ *   - Missing required field (id, type, shape) → throw with field name in message
+ *   - Unsupported schema keyword → warn via validateFerretSchema, continue
+ *   - Identical files → identical shape_hash (deterministic)
+ */
+export function extractFromSpecFile(filePath: string, fileContent: string): ExtractionResult {
+  const { data } = matter(fileContent);
+  const ferret = data?.ferret;
+
+  if (!ferret) {
+    return {
+      filePath,
+      fileType: 'spec',
+      contracts: [],
+      extractedBy: 'gray-matter',
+      extractedAt: Date.now(),
+      warning: 'no-frontmatter',
+    };
+  }
+
+  const missingFields = ['id', 'type', 'shape'].filter((f) => !ferret[f]);
+  if (missingFields.length > 0) {
+    throw new Error(`Missing required frontmatter fields in ${filePath}: ${missingFields.join(', ')}`);
+  }
+
+  const typeValidation = validateContractType(ferret.type, filePath);
+  if (!typeValidation.valid) {
+    throw new Error(typeValidation.error);
+  }
+
+  // validateFerretSchema never throws — only warns on unsupported keywords
+  const validation = validateFerretSchema(ferret.shape, filePath);
+  validation.warnings.forEach((w) => process.stderr.write(w + '\n'));
+
+  return {
+    filePath,
+    fileType: 'spec',
+    contracts: [
+      {
+        id: ferret.id as string,
+        type: typeValidation.value,
+        shape: ferret.shape as object,
+        shape_hash: hashSchema(ferret.shape),
+        imports: Array.isArray(ferret.imports) ? (ferret.imports as string[]) : [],
+      },
+    ],
+    extractedBy: 'gray-matter',
+    extractedAt: Date.now(),
+  };
+}

package/src/extractor/hash.ts

@@ -0,0 +1,26 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Produces a stable SHA-256 hex fingerprint of a schema object.
+ * Used for quick change detection — if the hash changes, the schema changed.
+ * JSON.stringify is order-sensitive on keys, so we sort keys for stability.
+ */
+export function hashSchema(schema: unknown): string {
+  const sortObject = (obj: any): any => {
+    if (obj === null || typeof obj !== 'object') {
+      return obj;
+    }
+    if (Array.isArray(obj)) {
+      return obj.map(sortObject);
+    }
+    return Object.keys(obj)
+      .sort()
+      .reduce((acc, key) => {
+        acc[key] = sortObject(obj[key]);
+        return acc;
+      }, {} as any);
+  };
+
+  const stable = JSON.stringify(sortObject(schema));
+  return createHash('sha256').update(stable).digest('hex');
+}

package/src/extractor/typescript.test.ts

@@ -0,0 +1,339 @@
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { describe, it } from 'bun:test';
+import { CONTRACT_TYPES } from './contract-types.js';
+import { extractContractsFromTypeScript } from './typescript.js';
+
+describe('extractContractsFromTypeScript — S28 acceptance criteria', () => {
+  it('extracts deterministic contract shapes from exported interfaces without annotations', () => {
+    const src = `
+export interface GetUsersResponse {
+  id: string;
+  email: string;
+  active: boolean;
+  createdAt: Date;
+}
+`;
+
+    const first = extractContractsFromTypeScript('src/users.ts', src);
+    const second = extractContractsFromTypeScript('src/users.ts', src);
+
+    assert.equal(first.diagnostics.length, 0);
+    assert.equal(JSON.stringify(first), JSON.stringify(second));
+    assert.equal(first.contracts.length, 1);
+
+    const contract = first.contracts[0];
+    assert.equal(contract.id, 'type.src/users/getusersresponse');
+    assert.equal(contract.type, 'type');
+    assert.equal(contract.sourceSymbol, 'GetUsersResponse');
+
+    const shape = contract.shape as Record<string, unknown>;
+    assert.equal(shape.type, 'object');
+  });
+
+  it('extracts enum and function signatures from exported declarations', () => {
+    const src = `
+export enum UserRole {
+  Admin,
+  Viewer,
+}
+
+export function getUser(id: string): UserRole {
+  return UserRole.Admin;
+}
+`;
+
+    const result = extractContractsFromTypeScript('src/roles.ts', src);
+
+    assert.equal(result.contracts.length, 2);
+    const enumContract = result.contracts.find((contract) => contract.sourceSymbol === 'UserRole');
+    const functionContract = result.contracts.find((contract) => contract.sourceSymbol === 'getUser');
+
+    assert.ok(enumContract);
+    assert.ok(functionContract);
+
+    const enumShape = enumContract?.shape as Record<string, unknown>;
+    assert.equal(enumShape.type, 'string');
+
+    const functionShape = functionContract?.shape as Record<string, unknown>;
+    assert.equal(functionShape.type, 'object');
+  });
+
+  it('records diagnostics for unsupported unions', () => {
+    const src = `
+export interface ProfileResponse {
+  email: string | null;
+}
+`;
+
+    const result = extractContractsFromTypeScript('src/profile.ts', src);
+
+    assert.equal(result.contracts.length, 1);
+    assert.ok(result.diagnostics.some((d) => d.includes('Union types are not supported')));
+  });
+
+  it('applies annotation overrides for id and type when present', () => {
+    const src = `
+// @ferret-contract: api.GET/profile api
+export interface ProfileResponse {
+  email: string;
+}
+`;
+    const result = extractContractsFromTypeScript('src/missing.ts', src);
+
+    assert.equal(result.contracts.length, 1);
+    assert.equal(result.contracts[0].id, 'api.GET/profile');
+    assert.equal(result.contracts[0].type, 'api');
+  });
+
+  it('accepts all supported annotation contract types', () => {
+    for (const contractType of CONTRACT_TYPES) {
+      const src = `
+// @ferret-contract: ${contractType}.GET/profile ${contractType}
+export interface ProfileResponse {
+  email: string;
+}
+`;
+      const result = extractContractsFromTypeScript('src/annotated.ts', src);
+      assert.equal(result.errors.length, 0);
+      assert.equal(result.contracts.length, 1);
+      assert.equal(result.contracts[0].type, contractType);
+    }
+  });
+
+  it('reports unmatched annotations', () => {
+    const src = `
+// @ferret-contract: api.GET/missing api
+interface MissingContract {
+  id: string;
+}
+`;
+    const result = extractContractsFromTypeScript('src/missing.ts', src);
+
+    assert.equal(result.contracts.length, 0);
+    assert.ok(result.errors.some((d) => d.includes('did not match')));
+  });
+
+  it('extracts type alias with primitive value', () => {
+    const src = `
+export type UserId = string;
+`;
+    const result = extractContractsFromTypeScript('src/ids.ts', src);
+
+    assert.equal(result.contracts.length, 1);
+    const contract = result.contracts[0];
+    assert.equal(contract.sourceSymbol, 'UserId');
+    assert.deepEqual(contract.shape, { type: 'string' });
+  });
+
+  it('extracts enum members with string initialisers', () => {
+    const src = `
+export enum Role {
+  Admin = "admin",
+  Viewer = "viewer",
+}
+`;
+    const result = extractContractsFromTypeScript('src/roles.ts', src);
+
+    assert.equal(result.contracts.length, 1);
+    const shape = result.contracts[0].shape as Record<string, unknown>;
+    assert.equal(shape.type, 'string');
+    assert.deepEqual(shape.enum, ['Admin', 'Viewer']);
+  });
+
+  it('does not mark required methods with optional parameters as optional', () => {
+    const src = `
+export interface Service {
+  bar: string;
+  baz?: string;
+  fn(x?: string): void;
+}
+`;
+    const result = extractContractsFromTypeScript('src/service.ts', src);
+    assert.equal(result.diagnostics.length, 0);
+
+    const shape = result.contracts[0].shape as {
+      required: string[];
+      properties: Record<string, unknown>;
+    };
+    // 'bar' and 'fn' are required; 'baz' is optional
+    assert.ok(shape.required.includes('bar'));
+    assert.ok(shape.required.includes('fn'));
+    assert.ok(!shape.required.includes('baz'));
+  });
+
+  it('does not mark rest parameters as required', () => {
+    const src = `
+export function log(message: string, ...args: string[]): void {}
+`;
+    const result = extractContractsFromTypeScript('src/log.ts', src);
+    assert.equal(result.contracts.length, 1);
+
+    const shape = result.contracts[0].shape as {
+      properties: { params: { required: string[] } };
+    };
+    const paramsRequired = shape.properties.params.required;
+    assert.ok(paramsRequired.includes('message'), 'message should be required');
+    assert.ok(!paramsRequired.includes('args'), 'rest param args should not be required');
+  });
+
+  it('extracts function with typed parameters', () => {
+    const src = `
+export function getUser(id: string, active: boolean): void {}
+`;
+    const result = extractContractsFromTypeScript('src/user.ts', src);
+    assert.equal(result.contracts.length, 1);
+
+    const shape = result.contracts[0].shape as {
+      properties: {
+        params: { properties: Record<string, unknown>; required: string[] };
+      };
+    };
+    assert.deepEqual(shape.properties.params.properties['id'], {
+      type: 'string',
+    });
+    assert.deepEqual(shape.properties.params.properties['active'], {
+      type: 'boolean',
+    });
+    assert.deepEqual(shape.properties.params.required, ['id', 'active']);
+  });
+
+  it('normalizes absolute paths to deterministic ids', () => {
+    const src = `
+export interface ProfileResponse {
+  id: string;
+}
+`;
+
+    const windowsPath = 'C:/Users/alice/work/specferret/src/contracts/profile.ts';
+    const unixPath = '/home/bob/work/specferret/src/contracts/profile.ts';
+
+    const windowsResult = extractContractsFromTypeScript(windowsPath, src);
+    const unixResult = extractContractsFromTypeScript(unixPath, src);
+
+    assert.equal(windowsResult.contracts.length, 1);
+    assert.equal(unixResult.contracts.length, 1);
+    assert.equal(windowsResult.contracts[0].id, 'type.src/contracts/profile/profileresponse');
+    assert.equal(unixResult.contracts[0].id, 'type.src/contracts/profile/profileresponse');
+  });
+
+  it('falls back to last 3 path segments for absolute paths without src/', () => {
+    const src = `
+export interface Config {
+  debug: boolean;
+}
+`;
+
+    // Without a recognizable src/ segment the normalizer falls back to the
+    // last 3 path segments.  This limits machine-specific prefix noise but
+    // does NOT guarantee cross-machine determinism (usernames may differ).
+    const result = extractContractsFromTypeScript('/home/bob/myproject/config.ts', src);
+
+    assert.equal(result.contracts.length, 1);
+    assert.equal(result.contracts[0].id, 'type.bob/myproject/config/config');
+  });
+
+  it('falls back to core contract type for inferred declarations', () => {
+    const src = `
+export interface Team {
+  id: string;
+}
+`;
+
+    const result = extractContractsFromTypeScript('src/team.ts', src);
+
+    assert.equal(result.contracts.length, 1);
+    assert.equal(result.contracts[0].type, 'type');
+  });
+
+  it('deterministically suffixes inferred ids when collisions occur', () => {
+    const src = `
+export interface UserProfile {
+  id: string;
+}
+
+export interface userprofile {
+  id: string;
+}
+`;
+
+    const result = extractContractsFromTypeScript('src/collision.ts', src);
+
+    assert.equal(result.contracts.length, 2);
+    const bySymbol = new Map(result.contracts.map((contract) => [contract.sourceSymbol, contract.id]));
+    assert.equal(bySymbol.get('UserProfile'), 'type.src/collision/userprofile');
+    assert.equal(bySymbol.get('userprofile'), 'type.src/collision/userprofile-2');
+  });
+
+  it('suffixes inferred id when explicit override already uses base id', () => {
+    const src = `
+// @ferret-contract: type.src/collision/userprofile type
+export interface Explicit {
+  id: string;
+}
+
+export interface UserProfile {
+  id: string;
+}
+`;
+
+    const result = extractContractsFromTypeScript('src/collision.ts', src);
+
+    assert.equal(result.contracts.length, 2);
+    const bySymbol = new Map(result.contracts.map((contract) => [contract.sourceSymbol, contract.id]));
+
+    assert.equal(bySymbol.get('Explicit'), 'type.src/collision/userprofile');
+    assert.equal(bySymbol.get('UserProfile'), 'type.src/collision/userprofile-2');
+    assert.ok(result.diagnostics.some((d) => d.includes('Inferred id collision') && d.includes('userprofile-2')));
+  });
+
+  it('matches golden outputs for fixture-driven regression cases', () => {
+    const fixtureDir = path.join(import.meta.dir, '__fixtures__', 'typescript');
+    const fixtureFiles = fs
+      .readdirSync(fixtureDir)
+      .filter((name) => name.endsWith('.ts'))
+      .sort();
+
+    assert.ok(fixtureFiles.length > 0, 'expected at least one fixture file');
+
+    for (const fixtureFile of fixtureFiles) {
+      const fixturePath = path.join(fixtureDir, fixtureFile);
+      const goldenPath = path.join(fixtureDir, fixtureFile.replace(/\.ts$/, '.golden.json'));
+
+      assert.ok(fs.existsSync(goldenPath), `missing golden snapshot for ${fixtureFile}`);
+
+      const source = fs.readFileSync(fixturePath, 'utf-8');
+      const logicalPath = `src/fixtures/${fixtureFile}`;
+
+      const first = extractContractsFromTypeScript(logicalPath, source);
+      const second = extractContractsFromTypeScript(logicalPath, source);
+      const golden = JSON.parse(fs.readFileSync(goldenPath, 'utf-8'));
+
+      assert.deepEqual(first, golden, `fixture output mismatch for ${fixtureFile}`);
+      assert.deepEqual(second, golden, `fixture output was non-deterministic for ${fixtureFile}`);
+    }
+  });
+
+  it('captures unsupported syntax as deterministic diagnostics without crashing', () => {
+    const fixtureDir = path.join(import.meta.dir, '__fixtures__', 'typescript');
+    const filePath = path.join(fixtureDir, 'unsupported-syntax.ts');
+    const source = fs.readFileSync(filePath, 'utf-8');
+
+    const first = extractContractsFromTypeScript('src/fixtures/unsupported-syntax.ts', source);
+    const second = extractContractsFromTypeScript('src/fixtures/unsupported-syntax.ts', source);
+
+    assert.equal(first.errors.length, 0);
+    assert.ok(first.contracts.length > 0);
+    assert.ok(
+      first.diagnostics.some(
+        (d) =>
+          d.includes('Unsupported node type') ||
+          d.includes('Unsupported object member type') ||
+          d.includes('Intersection types are not supported') ||
+          d.includes('Union types are not supported'),
+      ),
+    );
+    assert.deepEqual(first.diagnostics, second.diagnostics);
+  });
+});