@specferret/core 0.1.3 → 0.2.0

package/src/context/index.test.ts

@@ -0,0 +1,274 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "bun:test";
+import {
+  CONTEXT_SCHEMA_VERSION,
+  readContextFile,
+  writeContext,
+  type FerretContext,
+} from "./index.js";
+import { SqliteStore } from "../store/sqlite.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { randomUUID } from "node:crypto";
+
+function makeTmpDir(): string {
+  const tmp = path.join(os.tmpdir(), `ferret-ctx-test-${randomUUID()}`);
+  fs.mkdirSync(tmp, { recursive: true });
+  return tmp;
+}
+
+async function makeStoreWithData(tmpDir: string) {
+  // Use in-memory store but fake the projectRoot for file writing
+  const store = new SqliteStore(":memory:");
+  await store.init();
+
+  const nodeId = randomUUID();
+  await store.upsertNode({
+    id: nodeId,
+    file_path: "contracts/auth.contract.md",
+    hash: "abc",
+    status: "stable",
+  });
+
+  const contractId = "auth.jwt";
+  await store.upsertContract({
+    id: contractId,
+    node_id: nodeId,
+    shape_hash: "sha256hash",
+    shape_schema: JSON.stringify({
+      type: "object",
+      properties: { token: { type: "string" } },
+      required: ["token"],
+    }),
+    type: "api",
+    status: "stable",
+  });
+
+  // Second node that imports auth.jwt
+  const nodeId2 = randomUUID();
+  await store.upsertNode({
+    id: nodeId2,
+    file_path: "contracts/search.contract.md",
+    hash: "def",
+    status: "needs-review",
+  });
+
+  const contractId2 = "api.GET/search";
+  await store.upsertContract({
+    id: contractId2,
+    node_id: nodeId2,
+    shape_hash: "sha256hash2",
+    shape_schema: JSON.stringify({ type: "array" }),
+    type: "api",
+    status: "stable",
+  });
+
+  await store.upsertDependency({
+    id: randomUUID(),
+    source_node_id: nodeId2,
+    target_contract_id: contractId,
+  });
+
+  return { store, contractId, contractId2 };
+}
+
+describe("writeContext — Task 5", () => {
+  const tmps: string[] = [];
+
+  afterEach(() => {
+    // Clean up temp directories
+    for (const tmp of tmps) {
+      try {
+        fs.rmSync(tmp, { recursive: true, force: true });
+      } catch {}
+    }
+    tmps.length = 0;
+  });
+
+  it("creates context.json at the correct path", async () => {
+    const tmpDir = makeTmpDir();
+    tmps.push(tmpDir);
+    const { store } = await makeStoreWithData(tmpDir);
+
+    await writeContext(store, tmpDir);
+
+    const contextPath = path.join(tmpDir, ".ferret", "context.json");
+    assert.equal(fs.existsSync(contextPath), true);
+
+    await store.close();
+  });
+
+  it("produces valid JSON", async () => {
+    const tmpDir = makeTmpDir();
+    tmps.push(tmpDir);
+    const { store } = await makeStoreWithData(tmpDir);
+
+    await writeContext(store, tmpDir);
+
+    const contextPath = path.join(tmpDir, ".ferret", "context.json");
+    const raw = fs.readFileSync(contextPath, "utf-8");
+    assert.doesNotThrow(() => JSON.parse(raw));
+
+    await store.close();
+  });
+
+  it('contains version "2.0"', async () => {
+    const tmpDir = makeTmpDir();
+    tmps.push(tmpDir);
+    const { store } = await makeStoreWithData(tmpDir);
+
+    await writeContext(store, tmpDir);
+
+    const ctx = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, ".ferret", "context.json"), "utf-8"),
+    ) as FerretContext;
+    assert.equal(ctx.version, "2.0");
+
+    await store.close();
+  });
+
+  it("contains context schemaVersion", async () => {
+    const tmpDir = makeTmpDir();
+    tmps.push(tmpDir);
+    const { store } = await makeStoreWithData(tmpDir);
+
+    await writeContext(store, tmpDir);
+
+    const ctx = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, ".ferret", "context.json"), "utf-8"),
+    ) as FerretContext;
+    assert.equal(ctx.schemaVersion, CONTEXT_SCHEMA_VERSION);
+
+    await store.close();
+  });
+
+  it("readContextFile migrates known legacy V2 payload without schemaVersion", () => {
+    const tmpDir = makeTmpDir();
+    tmps.push(tmpDir);
+    const ferretDir = path.join(tmpDir, ".ferret");
+    fs.mkdirSync(ferretDir, { recursive: true });
+    const contextPath = path.join(ferretDir, "context.json");
+    fs.writeFileSync(
+      contextPath,
+      JSON.stringify(
+        {
+          version: "2.0",
+          generated: "2026-01-01T00:00:00.000Z",
+          contracts: [],
+          edges: [],
+          needsReview: [],
+        },
+        null,
+        2,
+      ),
+      "utf-8",
+    );
+
+    const context = readContextFile(contextPath);
+    assert.equal(context.version, "2.0");
+    assert.equal(context.schemaVersion, CONTEXT_SCHEMA_VERSION);
+    assert.deepEqual(context.contracts, []);
+    assert.deepEqual(context.edges, []);
+    assert.deepEqual(context.needsReview, []);
+  });
+
+  it("readContextFile fails with upgrade guidance on unknown context version", () => {
+    const tmpDir = makeTmpDir();
+    tmps.push(tmpDir);
+    const ferretDir = path.join(tmpDir, ".ferret");
+    fs.mkdirSync(ferretDir, { recursive: true });
+    const contextPath = path.join(ferretDir, "context.json");
+    fs.writeFileSync(
+      contextPath,
+      JSON.stringify({
+        version: "9.9",
+        schemaVersion: CONTEXT_SCHEMA_VERSION,
+        generated: new Date().toISOString(),
+        contracts: [],
+        edges: [],
+        needsReview: [],
+      }),
+      "utf-8",
+    );
+
+    assert.throws(
+      () => readContextFile(contextPath),
+      /unsupported context\.json version|Run 'ferret scan'/,
+    );
+  });
+
+  it("readContextFile fails with upgrade guidance on unknown schemaVersion", () => {
+    const tmpDir = makeTmpDir();
+    tmps.push(tmpDir);
+    const ferretDir = path.join(tmpDir, ".ferret");
+    fs.mkdirSync(ferretDir, { recursive: true });
+    const contextPath = path.join(ferretDir, "context.json");
+    fs.writeFileSync(
+      contextPath,
+      JSON.stringify({
+        version: "2.0",
+        schemaVersion: "9.0.0",
+        generated: new Date().toISOString(),
+        contracts: [],
+        edges: [],
+        needsReview: [],
+      }),
+      "utf-8",
+    );
+
+    assert.throws(
+      () => readContextFile(contextPath),
+      /unsupported context schemaVersion|Run 'ferret scan'/,
+    );
+  });
+
+  it("stable contracts appear in contracts array", async () => {
+    const tmpDir = makeTmpDir();
+    tmps.push(tmpDir);
+    const { store, contractId } = await makeStoreWithData(tmpDir);
+
+    await writeContext(store, tmpDir);
+
+    const ctx = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, ".ferret", "context.json"), "utf-8"),
+    ) as FerretContext;
+    const ids = ctx.contracts.map((c) => c.id);
+    assert.ok(ids.includes(contractId));
+
+    await store.close();
+  });
+
+  it("needs-review contracts appear in needsReview array", async () => {
+    const tmpDir = makeTmpDir();
+    tmps.push(tmpDir);
+    const { store, contractId2 } = await makeStoreWithData(tmpDir);
+
+    await writeContext(store, tmpDir);
+
+    const ctx = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, ".ferret", "context.json"), "utf-8"),
+    ) as FerretContext;
+    // contractId2 belongs to the needs-review node
+    assert.ok(ctx.needsReview.includes(contractId2));
+
+    await store.close();
+  });
+
+  it("edges correctly represent dependency relationships", async () => {
+    const tmpDir = makeTmpDir();
+    tmps.push(tmpDir);
+    const { store, contractId } = await makeStoreWithData(tmpDir);
+
+    await writeContext(store, tmpDir);
+
+    const ctx = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, ".ferret", "context.json"), "utf-8"),
+    ) as FerretContext;
+    const edge = ctx.edges.find((e) => e.to === contractId);
+    assert.notEqual(edge, undefined);
+    assert.equal(edge!.from, "contracts/search.contract.md");
+
+    await store.close();
+  });
+});

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