@specferret/core 0.1.3 → 0.2.0

package/src/store/sqlite.test.ts

@@ -0,0 +1,328 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'bun:test';
+import { SqliteStore } from './sqlite.js';
+import type { FerretNode, FerretContract } from './types.js';
+import { randomUUID } from 'node:crypto';
+
+// Use in-memory SQLite for all tests — fast, isolated, no disk cleanup needed
+function makeStore() {
+  return new SqliteStore(':memory:');
+}
+
+function makeNode(overrides: Partial<FerretNode> = {}): FerretNode {
+  return {
+    id: randomUUID(),
+    file_path: 'contracts/test.contract.md',
+    hash: 'abc123',
+    status: 'stable',
+    ...overrides,
+  };
+}
+
+function makeContract(nodeId: string, overrides: Partial<FerretContract> = {}): FerretContract {
+  return {
+    id: `api.GET/test-${randomUUID()}`,
+    node_id: nodeId,
+    shape_hash: 'sha256hashvalue',
+    shape_schema: JSON.stringify({
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    }),
+    type: 'api',
+    status: 'stable',
+    ...overrides,
+  };
+}
+
+describe('SqliteStore — Task 1: shape_schema field', () => {
+  it('upserts a contract with shape_schema field', async () => {
+    const store = makeStore();
+    await store.init();
+
+    const node = makeNode();
+    await store.upsertNode(node);
+
+    const contract = makeContract(node.id, {
+      shape_schema: JSON.stringify({
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      }),
+    });
+    await store.upsertContract(contract);
+
+    const all = await store.getContracts();
+    assert.equal(all.length, 1);
+    assert.equal(all[0].shape_schema, contract.shape_schema);
+
+    await store.close();
+  });
+
+  it('retrieves a contract with shape_schema field intact', async () => {
+    const store = makeStore();
+    await store.init();
+
+    const node = makeNode();
+    await store.upsertNode(node);
+
+    const schema = {
+      type: 'object',
+      properties: { email: { type: 'string', format: 'email' } },
+      required: ['email'],
+    };
+    const contract = makeContract(node.id, {
+      shape_schema: JSON.stringify(schema),
+    });
+    await store.upsertContract(contract);
+
+    const retrieved = await store.getContract(contract.id);
+    assert.notEqual(retrieved, null);
+    assert.equal(retrieved!.shape_schema, JSON.stringify(schema));
+    assert.deepEqual(JSON.parse(retrieved!.shape_schema), schema);
+
+    await store.close();
+  });
+
+  it('upserts (updates) a contract — shape_schema is overwritten correctly', async () => {
+    const store = makeStore();
+    await store.init();
+
+    const node = makeNode();
+    await store.upsertNode(node);
+
+    const contract = makeContract(node.id, {
+      shape_schema: JSON.stringify({ type: 'string' }),
+    });
+    await store.upsertContract(contract);
+
+    const updatedSchema = JSON.stringify({
+      type: 'object',
+      properties: { id: { type: 'string' } },
+    });
+    await store.upsertContract({ ...contract, shape_schema: updatedSchema });
+
+    const retrieved = await store.getContract(contract.id);
+    assert.equal(retrieved!.shape_schema, updatedSchema);
+
+    await store.close();
+  });
+
+  it('migration: ALTER TABLE runs cleanly on an existing database that lacks shape_schema', async () => {
+    // Simulate a pre-migration DB by manually creating the table without shape_schema
+    // then calling init() which should run the migration without throwing
+    const store = makeStore();
+    // init() contains the migration; calling it twice should be idempotent
+    await store.init();
+    await store.init(); // second call must not throw
+    await store.close();
+  });
+
+  it('shape_schema defaults to empty JSON object string when not set explicitly', async () => {
+    const store = makeStore();
+    await store.init();
+
+    const node = makeNode();
+    await store.upsertNode(node);
+
+    // shape_schema has DEFAULT '{}' in the schema; pass it explicitly to match interface
+    const contract = makeContract(node.id, { shape_schema: '{}' });
+    await store.upsertContract(contract);
+
+    const retrieved = await store.getContract(contract.id);
+    assert.equal(retrieved!.shape_schema, '{}');
+
+    await store.close();
+  });
+});
+
+describe('SqliteStore — existing store functionality still passes', () => {
+  it('upserts and retrieves a node by file path', async () => {
+    const store = makeStore();
+    await store.init();
+
+    const node = makeNode({ file_path: 'contracts/auth.contract.md' });
+    await store.upsertNode(node);
+
+    const retrieved = await store.getNodeByFilePath('contracts/auth.contract.md');
+    assert.notEqual(retrieved, null);
+    assert.equal(retrieved!.id, node.id);
+    assert.equal(retrieved!.hash, node.hash);
+
+    await store.close();
+  });
+
+  it('returns null for unknown file path', async () => {
+    const store = makeStore();
+    await store.init();
+    const result = await store.getNodeByFilePath('contracts/nonexistent.contract.md');
+    assert.equal(result, null);
+    await store.close();
+  });
+
+  it('getAllContractIds returns all contract IDs', async () => {
+    const store = makeStore();
+    await store.init();
+
+    const node = makeNode();
+    await store.upsertNode(node);
+    const c1 = makeContract(node.id, { id: 'api.GET/one' });
+    const c2 = makeContract(node.id, { id: 'api.GET/two' });
+    await store.upsertContract(c1);
+    await store.upsertContract(c2);
+
+    const ids = await store.getAllContractIds();
+    assert.ok(ids.includes('api.GET/one'));
+    assert.ok(ids.includes('api.GET/two'));
+
+    await store.close();
+  });
+
+  it('updateNodeStatus changes node status', async () => {
+    const store = makeStore();
+    await store.init();
+
+    const node = makeNode({ status: 'stable' });
+    await store.upsertNode(node);
+    await store.updateNodeStatus(node.id, 'needs-review');
+
+    const nodes = await store.getNodesByStatus('needs-review');
+    assert.equal(
+      nodes.some((n) => n.id === node.id),
+      true,
+    );
+
+    await store.close();
+  });
+
+  it('upsertDependency and getDependencies work correctly', async () => {
+    const store = makeStore();
+    await store.init();
+
+    const nodeA = makeNode({
+      id: 'node-a',
+      file_path: 'contracts/a.contract.md',
+    });
+    const nodeB = makeNode({
+      id: 'node-b',
+      file_path: 'contracts/b.contract.md',
+    });
+    await store.upsertNode(nodeA);
+    await store.upsertNode(nodeB);
+
+    const contract = makeContract(nodeA.id, { id: 'api.GET/shared' });
+    await store.upsertContract(contract);
+
+    await store.upsertDependency({
+      id: randomUUID(),
+      source_node_id: nodeB.id,
+      target_contract_id: contract.id,
+    });
+
+    const deps = await store.getDependencies();
+    assert.equal(
+      deps.some((d) => d.source_node_id === nodeB.id && d.target_contract_id === contract.id),
+      true,
+    );
+
+    await store.close();
+  });
+
+  it('replaceDependenciesForSourceNode replaces stale edges and deduplicates targets', async () => {
+    const store = makeStore();
+    await store.init();
+
+    const nodeA = makeNode({
+      id: 'node-a',
+      file_path: 'contracts/a.contract.md',
+    });
+    await store.upsertNode(nodeA);
+
+    await store.replaceDependenciesForSourceNode(nodeA.id, ['api.GET/one', 'api.GET/one', 'api.GET/two']);
+
+    let deps = await store.getDependencies();
+    assert.equal(deps.length, 2);
+    assert.deepEqual(deps.map((dependency) => dependency.target_contract_id).sort(), ['api.GET/one', 'api.GET/two']);
+
+    await store.replaceDependenciesForSourceNode(nodeA.id, ['api.GET/two']);
+
+    deps = await store.getDependencies();
+    assert.equal(deps.length, 1);
+    assert.equal(deps[0].target_contract_id, 'api.GET/two');
+
+    await store.close();
+  });
+});
+
+describe('SqliteStore — S50: code_source_file and code_source_symbol', () => {
+  it('persists code_source_file and code_source_symbol when provided', async () => {
+    const store = makeStore();
+    await store.init();
+
+    const node = makeNode();
+    await store.upsertNode(node);
+
+    const contract = makeContract(node.id, {
+      code_source_file: 'src/auth/jwt.ts',
+      code_source_symbol: 'JwtPayload',
+    });
+    await store.upsertContract(contract);
+
+    const retrieved = await store.getContract(contract.id);
+    assert.equal(retrieved!.code_source_file, 'src/auth/jwt.ts');
+    assert.equal(retrieved!.code_source_symbol, 'JwtPayload');
+
+    await store.close();
+  });
+
+  it('stores null when code_source_file and code_source_symbol are absent', async () => {
+    const store = makeStore();
+    await store.init();
+
+    const node = makeNode();
+    await store.upsertNode(node);
+
+    const contract = makeContract(node.id);
+    await store.upsertContract(contract);
+
+    const retrieved = await store.getContract(contract.id);
+    // SQLite returns null for missing TEXT columns
+    assert.ok(retrieved!.code_source_file == null);
+    assert.ok(retrieved!.code_source_symbol == null);
+
+    await store.close();
+  });
+
+  it('overwrites code_source_file on upsert', async () => {
+    const store = makeStore();
+    await store.init();
+
+    const node = makeNode();
+    await store.upsertNode(node);
+
+    const contract = makeContract(node.id, {
+      code_source_file: 'src/old.ts',
+      code_source_symbol: 'OldSymbol',
+    });
+    await store.upsertContract(contract);
+
+    await store.upsertContract({
+      ...contract,
+      code_source_file: 'src/new.ts',
+      code_source_symbol: 'NewSymbol',
+    });
+
+    const retrieved = await store.getContract(contract.id);
+    assert.equal(retrieved!.code_source_file, 'src/new.ts');
+    assert.equal(retrieved!.code_source_symbol, 'NewSymbol');
+
+    await store.close();
+  });
+
+  it('migration for code_source columns is idempotent (double init does not throw)', async () => {
+    const store = makeStore();
+    await store.init();
+    await store.init();
+    await store.close();
+  });
+});

package/src/store/sqlite.ts

@@ -0,0 +1,231 @@
+import { Database } from 'bun:sqlite';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { findProjectRoot } from '../utils/paths.js';
+import type { DBStore, FerretNode, FerretContract, FerretDependency, FerretReconciliationLog, FerretPlacementDecision, NodeStatus } from './types.js';
+
+export class SqliteStore implements DBStore {
+  private db: Database | null = null;
+  private dbPath: string;
+
+  constructor(customPath?: string) {
+    const root = findProjectRoot();
+    const defaultPath = path.join(root, '.ferret', 'graph.db');
+    this.dbPath = customPath === ':memory:' ? ':memory:' : customPath ? path.resolve(root, customPath) : defaultPath;
+  }
+
+  async init(): Promise<void> {
+    if (this.db) return;
+
+    if (this.dbPath !== ':memory:') {
+      const ferretDir = path.dirname(this.dbPath);
+      if (!fs.existsSync(ferretDir)) {
+        fs.mkdirSync(ferretDir, { recursive: true });
+      }
+      const gitignorePath = path.join(ferretDir, '.gitignore');
+      try {
+        fs.writeFileSync(gitignorePath, '*\n!.gitignore\n!context.json\n', 'utf-8');
+      } catch {}
+    }
+
+    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
+      );
+    `);
+
+    try {
+      this.db.exec(`ALTER TABLE ferret_contracts ADD COLUMN shape_schema TEXT NOT NULL DEFAULT '{}';`);
+    } catch {}
+
+    try {
+      this.db.exec(`ALTER TABLE ferret_contracts ADD COLUMN code_source_file TEXT;`);
+    } catch {}
+
+    try {
+      this.db.exec(`ALTER TABLE ferret_contracts ADD COLUMN code_source_symbol TEXT;`);
+    } catch {}
+  }
+
+  async close(): Promise<void> {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+  }
+
+  async getNodeByFilePath(filePath: string): Promise<FerretNode | null> {
+    const row = this.db!.prepare('SELECT * FROM ferret_nodes WHERE file_path = ?').get(filePath) as any;
+    return row ?? null;
+  }
+
+  async upsertNode(node: FerretNode): Promise<void> {
+    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(): Promise<string[]> {
+    return (this.db!.prepare('SELECT id FROM ferret_contracts').all() as any[]).map((r) => r.id);
+  }
+
+  async upsertContract(contract: FerretContract): Promise<void> {
+    this.db!.prepare(
+      `
+      INSERT INTO ferret_contracts (id, node_id, shape_hash, shape_schema, type, status, code_source_file, code_source_symbol)
+      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,
+        code_source_file = excluded.code_source_file,
+        code_source_symbol = excluded.code_source_symbol
+    `,
+    ).run(
+      contract.id,
+      contract.node_id,
+      contract.shape_hash,
+      contract.shape_schema,
+      contract.type,
+      contract.status,
+      contract.code_source_file ?? null,
+      contract.code_source_symbol ?? null,
+    );
+  }
+
+  async upsertDependency(dependency: FerretDependency): Promise<void> {
+    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: string, targetContractIds: string[]): Promise<void> {
+    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 transaction = this.db!.transaction((sourceId: string) => {
+      deleteStatement.run(sourceId);
+      for (const targetId of uniqueTargets) {
+        insertStatement.run(randomUUID(), sourceId, targetId);
+      }
+    });
+
+    transaction(sourceNodeId);
+  }
+
+  async getNodes(): Promise<FerretNode[]> {
+    return this.db!.prepare('SELECT * FROM ferret_nodes').all() as unknown as FerretNode[];
+  }
+
+  async getNodesByStatus(status: NodeStatus): Promise<FerretNode[]> {
+    return this.db!.prepare('SELECT * FROM ferret_nodes WHERE status = ?').all(status) as unknown as FerretNode[];
+  }
+
+  async getContracts(): Promise<FerretContract[]> {
+    return this.db!.prepare('SELECT * FROM ferret_contracts').all() as unknown as FerretContract[];
+  }
+
+  async getContract(id: string): Promise<FerretContract | null> {
+    const row = this.db!.prepare('SELECT * FROM ferret_contracts WHERE id = ?').get(id) as any;
+    return row ?? null;
+  }
+
+  async getDependencies(): Promise<FerretDependency[]> {
+    return this.db!.prepare('SELECT * FROM ferret_dependencies').all() as unknown as FerretDependency[];
+  }
+
+  async updateNodeStatus(nodeId: string, status: NodeStatus): Promise<void> {
+    this.db!.prepare('UPDATE ferret_nodes SET status = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run(status, nodeId);
+  }
+
+  async insertReconciliationLog(log: FerretReconciliationLog): Promise<void> {
+    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(): Promise<FerretReconciliationLog[]> {
+    return this.db!.prepare(
+      'SELECT id, node_id, triggered_by, resolved_by, resolution_notes FROM ferret_reconciliation_log',
+    ).all() as unknown as FerretReconciliationLog[];
+  }
+
+  async insertPlacementDecision(decision: FerretPlacementDecision): Promise<void> {
+    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(): Promise<FerretPlacementDecision[]> {
+    return this.db!.prepare('SELECT id, node_id, placed_by, reasoning FROM ferret_placement_decisions').all() as unknown as FerretPlacementDecision[];
+  }
+}

package/src/store/types.ts

@@ -0,0 +1,101 @@
+export type NodeStatus = 'stable' | 'needs-review' | 'roadmap' | 'blocked';
+export type ContractStatus = 'stable' | 'roadmap' | 'needs-review';
+
+export interface FerretNode {
+  id: string;
+  file_path: string;
+  hash: string;
+  status: NodeStatus;
+  updated_at?: string | Date; // Dependent on SQLite (string) vs Postgres (Date) nuances, keep flexible for mapping.
+}
+
+export interface FerretContract {
+  id: string;
+  node_id: string;
+  shape_hash: string;
+  shape_schema: string;
+  type: string;
+  status: ContractStatus;
+  /** Path to the TypeScript file this contract was generated from (code-first contracts only). */
+  code_source_file?: string;
+  /** TypeScript symbol name this contract was generated from (code-first contracts only). */
+  code_source_symbol?: string;
+}
+
+export interface FerretDependency {
+  id: string;
+  source_node_id: string;
+  target_contract_id: string;
+}
+
+export interface FerretReconciliationLog {
+  id: string;
+  node_id: string;
+  triggered_by: string;
+  resolved_by?: string;
+  resolution_notes?: string;
+}
+
+export interface FerretPlacementDecision {
+  id: string;
+  node_id: string;
+  placed_by: string;
+  reasoning?: string;
+}
+
+export interface FerretMigrationSnapshot {
+  nodes: FerretNode[];
+  contracts: FerretContract[];
+  dependencies: FerretDependency[];
+  reconciliationLogs: FerretReconciliationLog[];
+  placementDecisions: FerretPlacementDecision[];
+}
+
+/**
+ * The standard contract for our Data Access Layer (DAL).
+ * All implementers (SQLite, Postgres) MUST satisfy this completely so the CLI
+ * can remain ignorant to the underlying storage type.
+ */
+export interface DBStore {
+  /** Core initialisation & teardown */
+  init(): Promise<void>;
+  close(): Promise<void>;
+
+  /** Retrieves a node based on its unique file path relative to specDir */
+  getNodeByFilePath(filePath: string): Promise<FerretNode | null>;
+
+  /** Upserts a node based on its ID */
+  upsertNode(node: FerretNode): Promise<void>;
+
+  /** Retrieves all existing contract IDs for LLM context injection */
+  getAllContractIds(): Promise<string[]>;
+
+  /** Upserts an extracted contract */
+  upsertContract(contract: FerretContract): Promise<void>;
+
+  /** Creates a dependency edge between a Node and a Contract */
+  upsertDependency(dependency: FerretDependency): Promise<void>;
+
+  /** Replaces all dependency edges for a source node with the provided targets */
+  replaceDependenciesForSourceNode(sourceNodeId: string, targetContractIds: string[]): Promise<void>;
+
+  /** Full graph retrieval methods for the Reconciler engine */
+  getNodes(): Promise<FerretNode[]>;
+  getNodesByStatus(status: NodeStatus): Promise<FerretNode[]>;
+  getContracts(): Promise<FerretContract[]>;
+  getContract(id: string): Promise<FerretContract | null>;
+  getDependencies(): Promise<FerretDependency[]>;
+
+  /** Update helper for the Reconciler to safely flag nodes */
+  updateNodeStatus(nodeId: string, status: NodeStatus): Promise<void>;
+
+  /** Records review actions against flagged nodes S013 */
+  insertReconciliationLog(log: FerretReconciliationLog): Promise<void>;
+
+  getReconciliationLogs(): Promise<FerretReconciliationLog[]>;
+
+  /** Tracks feature placement decisions S016 */
+  insertPlacementDecision(decision: FerretPlacementDecision): Promise<void>;
+
+  getPlacementDecisions(): Promise<FerretPlacementDecision[]>;
+}

package/src/utils/paths.ts

@@ -0,0 +1,24 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Walks up from cwd looking for .ferret/ or ferret.config.json.
+ * Falls back to cwd if neither is found.
+ */
+export function findProjectRoot(startDir: string = process.cwd()): string {
+  let current = path.resolve(startDir);
+
+  for (let i = 0; i < 20; i++) {
+    if (
+      fs.existsSync(path.join(current, '.ferret')) ||
+      fs.existsSync(path.join(current, 'ferret.config.json'))
+    ) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break; // filesystem root
+    current = parent;
+  }
+
+  return path.resolve(startDir);
+}