@specferret/core 0.1.3 → 0.1.4

package/dist/store/sqlite.js

@@ -33,48 +33,48 @@ export class SqliteStore {
         this.db = new Database(this.dbPath);
         this.db.exec("PRAGMA journal_mode = WAL;");
         this.db.exec("PRAGMA foreign_keys = ON;");
-        this.db.exec(`
-      CREATE TABLE IF NOT EXISTS ferret_nodes (
-        id TEXT PRIMARY KEY,
-        file_path TEXT NOT NULL,
-        hash TEXT NOT NULL,
-        status TEXT NOT NULL,
-        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
-      );
-
-      CREATE TABLE IF NOT EXISTS ferret_contracts (
-        id TEXT PRIMARY KEY,
-        node_id TEXT NOT NULL,
-        shape_hash TEXT NOT NULL,
-        shape_schema TEXT NOT NULL DEFAULT '{}',
-        type TEXT NOT NULL,
-        status TEXT NOT NULL,
-        FOREIGN KEY (node_id) REFERENCES ferret_nodes(id)
-      );
-
-      CREATE TABLE IF NOT EXISTS ferret_dependencies (
-        id TEXT PRIMARY KEY,
-        source_node_id TEXT NOT NULL,
-        target_contract_id TEXT NOT NULL,
-        FOREIGN KEY (source_node_id) REFERENCES ferret_nodes(id)
-      );
-
-      CREATE TABLE IF NOT EXISTS ferret_reconciliation_log (
-        id TEXT PRIMARY KEY,
-        node_id TEXT NOT NULL,
-        triggered_by TEXT NOT NULL,
-        resolved_by TEXT,
-        resolution_notes TEXT,
-        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-      );
-
-      CREATE TABLE IF NOT EXISTS ferret_placement_decisions (
-        id TEXT PRIMARY KEY,
-        node_id TEXT NOT NULL,
-        placed_by TEXT NOT NULL,
-        reasoning TEXT,
-        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-      );
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ferret_nodes (
+        id TEXT PRIMARY KEY,
+        file_path TEXT NOT NULL,
+        hash TEXT NOT NULL,
+        status TEXT NOT NULL,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      );
+
+      CREATE TABLE IF NOT EXISTS ferret_contracts (
+        id TEXT PRIMARY KEY,
+        node_id TEXT NOT NULL,
+        shape_hash TEXT NOT NULL,
+        shape_schema TEXT NOT NULL DEFAULT '{}',
+        type TEXT NOT NULL,
+        status TEXT NOT NULL,
+        FOREIGN KEY (node_id) REFERENCES ferret_nodes(id)
+      );
+
+      CREATE TABLE IF NOT EXISTS ferret_dependencies (
+        id TEXT PRIMARY KEY,
+        source_node_id TEXT NOT NULL,
+        target_contract_id TEXT NOT NULL,
+        FOREIGN KEY (source_node_id) REFERENCES ferret_nodes(id)
+      );
+
+      CREATE TABLE IF NOT EXISTS ferret_reconciliation_log (
+        id TEXT PRIMARY KEY,
+        node_id TEXT NOT NULL,
+        triggered_by TEXT NOT NULL,
+        resolved_by TEXT,
+        resolution_notes TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      );
+
+      CREATE TABLE IF NOT EXISTS ferret_placement_decisions (
+        id TEXT PRIMARY KEY,
+        node_id TEXT NOT NULL,
+        placed_by TEXT NOT NULL,
+        reasoning TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      );
     `);
         try {
             this.db.exec(`ALTER TABLE ferret_contracts ADD COLUMN shape_schema TEXT NOT NULL DEFAULT '{}';`);
@@ -92,44 +92,44 @@ export class SqliteStore {
         return row ?? null;
     }
     async upsertNode(node) {
-        this.db.prepare(`
-      INSERT INTO ferret_nodes (id, file_path, hash, status)
-      VALUES (?, ?, ?, ?)
-      ON CONFLICT(id) DO UPDATE SET
-        file_path = excluded.file_path,
-        hash = excluded.hash,
-        status = excluded.status,
-        updated_at = CURRENT_TIMESTAMP
+        this.db.prepare(`
+      INSERT INTO ferret_nodes (id, file_path, hash, status)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        file_path = excluded.file_path,
+        hash = excluded.hash,
+        status = excluded.status,
+        updated_at = CURRENT_TIMESTAMP
     `).run(node.id, node.file_path, node.hash, node.status);
     }
     async getAllContractIds() {
         return this.db.prepare("SELECT id FROM ferret_contracts").all().map((r) => r.id);
     }
     async upsertContract(contract) {
-        this.db.prepare(`
-      INSERT INTO ferret_contracts (id, node_id, shape_hash, shape_schema, type, status)
-      VALUES (?, ?, ?, ?, ?, ?)
-      ON CONFLICT(id) DO UPDATE SET
-        node_id = excluded.node_id,
-        shape_hash = excluded.shape_hash,
-        shape_schema = excluded.shape_schema,
-        type = excluded.type,
-        status = excluded.status
+        this.db.prepare(`
+      INSERT INTO ferret_contracts (id, node_id, shape_hash, shape_schema, type, status)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        node_id = excluded.node_id,
+        shape_hash = excluded.shape_hash,
+        shape_schema = excluded.shape_schema,
+        type = excluded.type,
+        status = excluded.status
     `).run(contract.id, contract.node_id, contract.shape_hash, contract.shape_schema, contract.type, contract.status);
     }
     async upsertDependency(dependency) {
-        this.db.prepare(`
-      INSERT INTO ferret_dependencies (id, source_node_id, target_contract_id)
-      VALUES (?, ?, ?)
-      ON CONFLICT(id) DO NOTHING
+        this.db.prepare(`
+      INSERT INTO ferret_dependencies (id, source_node_id, target_contract_id)
+      VALUES (?, ?, ?)
+      ON CONFLICT(id) DO NOTHING
     `).run(dependency.id, dependency.source_node_id, dependency.target_contract_id);
     }
     async replaceDependenciesForSourceNode(sourceNodeId, targetContractIds) {
         const uniqueTargets = [...new Set(targetContractIds)].sort();
         const deleteStatement = this.db.prepare("DELETE FROM ferret_dependencies WHERE source_node_id = ?");
-        const insertStatement = this.db.prepare(`
-      INSERT INTO ferret_dependencies (id, source_node_id, target_contract_id)
-      VALUES (?, ?, ?)
+        const insertStatement = this.db.prepare(`
+      INSERT INTO ferret_dependencies (id, source_node_id, target_contract_id)
+      VALUES (?, ?, ?)
     `);
         const transaction = this.db.transaction((sourceId) => {
             deleteStatement.run(sourceId);
@@ -159,18 +159,18 @@ export class SqliteStore {
         this.db.prepare("UPDATE ferret_nodes SET status = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?").run(status, nodeId);
     }
     async insertReconciliationLog(log) {
-        this.db.prepare(`
-      INSERT INTO ferret_reconciliation_log (id, node_id, triggered_by, resolved_by, resolution_notes)
-      VALUES (?, ?, ?, ?, ?)
+        this.db.prepare(`
+      INSERT INTO ferret_reconciliation_log (id, node_id, triggered_by, resolved_by, resolution_notes)
+      VALUES (?, ?, ?, ?, ?)
     `).run(log.id, log.node_id, log.triggered_by, log.resolved_by ?? null, log.resolution_notes ?? null);
     }
     async getReconciliationLogs() {
         return this.db.prepare("SELECT id, node_id, triggered_by, resolved_by, resolution_notes FROM ferret_reconciliation_log").all();
     }
     async insertPlacementDecision(decision) {
-        this.db.prepare(`
-      INSERT INTO ferret_placement_decisions (id, node_id, placed_by, reasoning)
-      VALUES (?, ?, ?, ?)
+        this.db.prepare(`
+      INSERT INTO ferret_placement_decisions (id, node_id, placed_by, reasoning)
+      VALUES (?, ?, ?, ?)
     `).run(decision.id, decision.node_id, decision.placed_by, decision.reasoning ?? null);
     }
     async getPlacementDecisions() {

package/package.json

@@ -1,44 +1,47 @@
-{
-  "name": "@specferret/core",
-  "version": "0.1.3",
-  "description": "SpecFerret core engine — spec drift detection.",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "bun": "./dist/index.js",
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "files": [
-    "dist/",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "bun ../../scripts/clean-dist.ts dist && tsc --project tsconfig.build.json",
-    "test": "bun test"
-  },
-  "dependencies": {
-    "ajv": "^8.12.0",
-    "ajv-formats": "^2.1.1",
-    "glob": "^13.0.6",
-    "gray-matter": "^4.0.3",
-    "zod": "^3.22.4"
-  },
-  "devDependencies": {
-    "@types/bun": "^1.3.11",
-    "typescript": "^6.0.2"
-  },
-  "engines": {
-    "bun": ">=1.0.0"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/BenGardiner123/spec-ferret.git"
-  },
-  "homepage": "https://specferret.dev"
-}
+{
+  "name": "@specferret/core",
+  "version": "0.1.4",
+  "description": "SpecFerret core engine — spec drift detection.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun ../../scripts/clean-dist.ts dist && tsc --project tsconfig.build.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^2.1.1",
+    "glob": "^13.0.6",
+    "gray-matter": "^4.0.3",
+    "tree-sitter": "^0.22.4",
+    "tree-sitter-typescript": "^0.23.2",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.11",
+    "typescript": "^6.0.2"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BenGardiner123/spec-ferret.git"
+  },
+  "homepage": "https://specferret.dev"
+}

package/src/config.ts

@@ -0,0 +1,48 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { findProjectRoot } from "./utils/paths.js";
+
+export interface FerretConfig {
+  specDir: string;
+  filePattern: string;
+  includes?: string[];
+  store: "sqlite" | "postgres";
+  importSuggestions?: {
+    enabled?: boolean;
+  };
+  codeContracts?: {
+    include: string[];
+    watchNodes?: string[];
+  };
+}
+
+export const DEFAULT_CONFIG: FerretConfig = {
+  specDir: "contracts/",
+  filePattern: "**/*.contract.md",
+  includes: ["**/*.contract.md"],
+  store: "sqlite",
+  importSuggestions: {
+    enabled: true,
+  },
+};
+
+/**
+ * Loads ferret.config.json from the project root.
+ * Falls back to DEFAULT_CONFIG if the file is not found.
+ */
+export function loadConfig(): FerretConfig {
+  const root = findProjectRoot();
+  const configPath = path.join(root, "ferret.config.json");
+
+  if (!fs.existsSync(configPath)) {
+    return { ...DEFAULT_CONFIG };
+  }
+
+  try {
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<FerretConfig>;
+    return { ...DEFAULT_CONFIG, ...parsed };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}

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