@specferret/core 0.1.3 → 0.1.4

package/src/context/index.ts

@@ -0,0 +1,178 @@
+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_SCHEMA_VERSION = "1.0.0" as const;
+
+type LegacyFerretContextV2 = {
+  version: "2.0";
+  generated: string;
+  contracts: ContextContract[];
+  edges: ContextEdge[];
+  needsReview: string[];
+};
+
+export interface ContextContract {
+  id: string;
+  type: string;
+  shape: unknown;
+  status: string;
+  specFile: string | null;
+  codeFile: string | null;
+}
+
+export interface ContextEdge {
+  from: string; // source node file_path
+  to: string; // target contract id
+}
+
+export interface FerretContext {
+  version: typeof CONTEXT_VERSION;
+  schemaVersion: typeof CONTEXT_SCHEMA_VERSION;
+  generated: string; // ISO timestamp
+  contracts: ContextContract[];
+  edges: ContextEdge[];
+  needsReview: string[]; // contract IDs currently flagged
+}
+
+function normalizeContext(raw: unknown): FerretContext {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("ferret: invalid context.json format. Run 'ferret scan' to regenerate .ferret/context.json.");
+  }
+
+  const candidate = raw as Record<string, unknown>;
+  const contextVersion = candidate.version;
+  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.`,
+    );
+  }
+
+  const schemaVersion = candidate.schemaVersion;
+  if (schemaVersion !== undefined && schemaVersion !== CONTEXT_SCHEMA_VERSION) {
+    throw new Error(
+      `ferret: unsupported context schemaVersion '${String(schemaVersion)}'. Run 'ferret scan' with the current CLI to migrate .ferret/context.json.`,
+    );
+  }
+
+  // Known migration path: V2 payloads created before schemaVersion was introduced.
+  const legacy = candidate as Partial<LegacyFerretContextV2>;
+  return {
+    version: CONTEXT_VERSION,
+    schemaVersion: CONTEXT_SCHEMA_VERSION,
+    generated:
+      typeof legacy.generated === "string"
+        ? legacy.generated
+        : new Date(0).toISOString(),
+    contracts: Array.isArray(legacy.contracts)
+      ? legacy.contracts
+      : [],
+    edges: Array.isArray(legacy.edges) ? legacy.edges : [],
+    needsReview: Array.isArray(legacy.needsReview)
+      ? legacy.needsReview
+      : [],
+  };
+}
+
+export function readContextFile(contextPath: string): FerretContext {
+  try {
+    const raw = fs.readFileSync(contextPath, "utf-8");
+    return normalizeContext(JSON.parse(raw));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith("ferret:")) {
+      throw error;
+    }
+    throw new Error(
+      `ferret: unable to read .ferret/context.json (${message}). Run 'ferret scan' to regenerate it.`,
+    );
+  }
+}
+
+/**
+ * Reads the full graph from the store and writes .ferret/context.json.
+ * Called automatically at the end of every ferret scan.
+ * Silent — no output. If write fails, it logs to stderr and continues.
+ */
+export async function writeContext(
+  store: DBStore,
+  projectRoot: string,
+): Promise<void> {
+  const [nodes, contracts, dependencies] = await Promise.all([
+    store.getNodes(),
+    store.getContracts(),
+    store.getDependencies(),
+  ]);
+
+  // Build a map of node_id → node for quick lookup
+  const nodeById = new Map(nodes.map((n) => [n.id, n]));
+
+  // Map contracts to context shape
+  const contextContracts: ContextContract[] = contracts.map((c) => {
+    const parentNode = nodeById.get(c.node_id);
+    const nodeType = (parentNode as any)?.type ?? "spec"; // nodes don't store type in V2 yet
+
+    let shape: unknown = {};
+    try {
+      shape = JSON.parse(c.shape_schema);
+    } catch {
+      shape = {};
+    }
+
+    return {
+      id: c.id,
+      type: c.type,
+      shape,
+      status: c.status,
+      specFile:
+        nodeType !== "code"
+          ? (parentNode?.file_path?.replace(/\\/g, "/") ?? null)
+          : null,
+      codeFile:
+        nodeType === "code"
+          ? (parentNode?.file_path?.replace(/\\/g, "/") ?? null)
+          : null,
+    };
+  });
+
+  // Build edges: source_node file_path → target_contract_id
+  const edges: ContextEdge[] = dependencies.map((d) => {
+    const sourceNode = nodeById.get(d.source_node_id);
+    return {
+      from: (sourceNode?.file_path ?? d.source_node_id).replace(/\\/g, "/"),
+      to: d.target_contract_id,
+    };
+  });
+
+  // needsReview: contract IDs whose parent node is flagged needs-review
+  const needsReviewNodeIds = new Set(
+    nodes.filter((n) => n.status === "needs-review").map((n) => n.id),
+  );
+  const needsReview = contracts
+    .filter(
+      (c) => needsReviewNodeIds.has(c.node_id) || c.status === "needs-review",
+    )
+    .map((c) => c.id);
+
+  const context: FerretContext = {
+    version: CONTEXT_VERSION,
+    schemaVersion: CONTEXT_SCHEMA_VERSION,
+    generated: new Date().toISOString(),
+    contracts: contextContracts,
+    edges,
+    needsReview,
+  };
+
+  const ferretDir = path.join(projectRoot, ".ferret");
+  const contextPath = path.join(ferretDir, "context.json");
+
+  try {
+    if (!fs.existsSync(ferretDir)) {
+      fs.mkdirSync(ferretDir, { recursive: true });
+    }
+    fs.writeFileSync(contextPath, JSON.stringify(context, null, 2), "utf-8");
+  } catch (err) {
+    process.stderr.write(`⚠ Could not write context.json: ${err}\n`);
+  }
+}

package/src/extractor/__fixtures__/typescript/generics.golden.json

@@ -0,0 +1,36 @@
+{
+  "contracts": [
+    {
+      "id": "type.src/fixtures/generics/paginatedresponse",
+      "type": "type",
+      "shape": {
+        "type": "object",
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            }
+          },
+          "total": {
+            "type": "number"
+          },
+          "nextCursor": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "items",
+          "total"
+        ]
+      },
+      "sourceSymbol": "PaginatedResponse",
+      "filePath": "src/fixtures/generics.ts",
+      "idSource": "inferred"
+    }
+  ],
+  "errors": [],
+  "diagnostics": [
+    "src/fixtures/generics.ts (PaginatedResponse): Unsupported referenced type 'T'. Falling back to object."
+  ]
+}

package/src/extractor/__fixtures__/typescript/generics.ts

@@ -0,0 +1,5 @@
+export interface PaginatedResponse<T> {
+  items: T[];
+  total: number;
+  nextCursor?: string;
+}

package/src/extractor/__fixtures__/typescript/intersections.golden.json

@@ -0,0 +1,18 @@
+{
+  "contracts": [
+    {
+      "id": "type.src/fixtures/intersections/useridentity",
+      "type": "type",
+      "shape": {
+        "type": "object"
+      },
+      "sourceSymbol": "UserIdentity",
+      "filePath": "src/fixtures/intersections.ts",
+      "idSource": "inferred"
+    }
+  ],
+  "errors": [],
+  "diagnostics": [
+    "src/fixtures/intersections.ts (UserIdentity): Intersection types are not supported in extraction. Falling back to object."
+  ]
+}

package/src/extractor/__fixtures__/typescript/intersections.ts

@@ -0,0 +1,5 @@
+export type UserIdentity = {
+  id: string;
+} & {
+  tenantId: string;
+};

package/src/extractor/__fixtures__/typescript/optional-nested.golden.json

@@ -0,0 +1,41 @@
+{
+  "contracts": [
+    {
+      "id": "type.src/fixtures/optional-nested/searchresult",
+      "type": "type",
+      "shape": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "metadata": {
+            "type": "object",
+            "properties": {
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "score": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "score"
+            ]
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "sourceSymbol": "SearchResult",
+      "filePath": "src/fixtures/optional-nested.ts",
+      "idSource": "inferred"
+    }
+  ],
+  "errors": [],
+  "diagnostics": []
+}

package/src/extractor/__fixtures__/typescript/optional-nested.ts

@@ -0,0 +1,7 @@
+export interface SearchResult {
+  id: string;
+  metadata?: {
+    tags?: string[];
+    score: number;
+  };
+}

package/src/extractor/__fixtures__/typescript/unions.golden.json

@@ -0,0 +1,30 @@
+{
+  "contracts": [
+    {
+      "id": "type.src/fixtures/unions/maybeuser",
+      "type": "type",
+      "shape": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "object"
+          },
+          "displayName": {
+            "type": "object"
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "sourceSymbol": "MaybeUser",
+      "filePath": "src/fixtures/unions.ts",
+      "idSource": "inferred"
+    }
+  ],
+  "errors": [],
+  "diagnostics": [
+    "src/fixtures/unions.ts (MaybeUser): Union types are not supported in extraction. Falling back to object.",
+    "src/fixtures/unions.ts (MaybeUser): Union types are not supported in extraction. Falling back to object."
+  ]
+}

package/src/extractor/__fixtures__/typescript/unions.ts

@@ -0,0 +1,4 @@
+export interface MaybeUser {
+  id: string | null;
+  displayName?: string | null;
+}

package/src/extractor/__fixtures__/typescript/unsupported-syntax.golden.json

@@ -0,0 +1,20 @@
+{
+  "contracts": [
+    {
+      "id": "type.src/fixtures/unsupported-syntax/routemap",
+      "type": "type",
+      "shape": {
+        "type": "object",
+        "properties": {},
+        "required": []
+      },
+      "sourceSymbol": "RouteMap",
+      "filePath": "src/fixtures/unsupported-syntax.ts",
+      "idSource": "inferred"
+    }
+  ],
+  "errors": [],
+  "diagnostics": [
+    "src/fixtures/unsupported-syntax.ts (RouteMap): Unsupported object member type 'index_signature'. Falling back by skipping this member."
+  ]
+}

package/src/extractor/__fixtures__/typescript/unsupported-syntax.ts

@@ -0,0 +1,6 @@
+export type RouteMap<T extends string> = {
+  [K in T]: {
+    method: 'GET' | 'POST';
+    secured?: boolean;
+  };
+};

package/src/extractor/contract-types.ts

@@ -0,0 +1,11 @@
+export const CONTRACT_TYPES = ['api', 'table', 'type', 'event', 'flow', 'config'] as const;
+
+export type ContractType = (typeof CONTRACT_TYPES)[number];
+
+export function isContractType(value: unknown): value is ContractType {
+  return typeof value === 'string' && (CONTRACT_TYPES as readonly string[]).includes(value);
+}
+
+export function formatAllowedContractTypes(): string {
+  return CONTRACT_TYPES.join(', ');
+}

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