@specferret/core 0.1.3 → 0.1.4

package/src/reconciler/index.ts

@@ -0,0 +1,445 @@
+import {
+  DBStore,
+  FerretNode,
+  FerretContract,
+  FerretDependency,
+} from "../store/types.js";
+import {
+  ImportSuggestion,
+  suggestMissingImports,
+} from "./import-suggestions.js";
+
+export interface UnresolvedImportViolation {
+  contractId: string;
+  filePath: string;
+  importPath: string;
+  expectedTargetId: string;
+  transitiveChain?: string[];
+}
+
+export interface SelfImportViolation {
+  contractId: string;
+  filePath: string;
+  importPath: string;
+}
+
+export interface CircularImportViolation {
+  contractId: string;
+  filePath: string;
+  importPath: string;
+  cycle: string[];
+}
+
+export interface OrphanedContractViolation {
+  contractId: string;
+  filePath: string;
+  unresolvedImports: string[];
+  remediationHint: string;
+}
+
+export interface ImportIntegrityReport {
+  unresolvedImports: UnresolvedImportViolation[];
+  selfImports: SelfImportViolation[];
+  circularImports: CircularImportViolation[];
+  orphanedContracts: OrphanedContractViolation[];
+}
+
+export interface ReconcileReport {
+  consistent: boolean;
+  flagged: Array<{
+    nodeId: string;
+    filePath: string;
+    triggeredByContractId: string;
+    impact: "direct" | "transitive";
+    depth: number;
+  }>;
+  integrityViolations: ImportIntegrityReport;
+  importSuggestions: ImportSuggestion[];
+  timestamp: string;
+}
+
+/**
+ * The Reconciler engine (Phase 3).
+ * It calculates the downstream impact of graph shape changes. Since resolving recursive graphs
+ * can be heavily database dependent, we execute an Application-level Breadth-First Search (BFS)
+ * to maintain 100% parity across SQLite and PostgreSQL effortlessly and stay extremely fast.
+ */
+export class Reconciler {
+  constructor(private store: DBStore) {}
+
+  /**
+   * Identifies completely unhandled ripples and propagates them up to 10 hops (S011)
+   */
+  async reconcile(): Promise<ReconcileReport> {
+    const nodes = await this.store.getNodes();
+    const contracts = await this.store.getContracts();
+    const dependencies = await this.store.getDependencies();
+
+    const integrityViolations = this.validateImportIntegrity(
+      nodes,
+      contracts,
+      dependencies,
+    );
+    const hasIntegrityViolations =
+      integrityViolations.unresolvedImports.length > 0 ||
+      integrityViolations.selfImports.length > 0 ||
+      integrityViolations.circularImports.length > 0;
+
+    if (hasIntegrityViolations) {
+      return {
+        consistent: false,
+        flagged: [],
+        integrityViolations,
+        importSuggestions: [],
+        timestamp: new Date().toISOString(),
+      };
+    }
+
+    const importSuggestions = suggestMissingImports(
+      nodes,
+      contracts,
+      dependencies,
+    );
+
+    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+    const contractMap = new Map(contracts.map((c) => [c.id, c]));
+
+    // 1. Identify "changed/trigger" contracts.
+    // In our simplified engine approach, any contract attached to a Node that is "needs-review"
+    // acts as a signal for propagation, OR any specifically updated shapes.
+    // For this prototype implementation, we'll traverse starting from specifically flagged nodes.
+    const triggerContracts = contracts.filter((c) => {
+      const parentNode = nodeMap.get(c.node_id);
+      return parentNode && parentNode.status === "needs-review";
+    });
+
+    const flaggedNodes: ReconcileReport["flagged"] = [];
+
+    // BFS Queue: [contractId, depth]
+    // S011 explicitly mandates capping transitive impact at 10 hops.
+    const queue: Array<[string, number]> = triggerContracts.map((c) => [
+      c.id,
+      1,
+    ]);
+    const visitedContracts = new Set<string>();
+
+    while (queue.length > 0) {
+      const [contractId, depth] = queue.shift()!;
+      if (visitedContracts.has(contractId) || depth > 10) continue;
+      visitedContracts.add(contractId);
+
+      // Find nodes that import this contract
+      const dependentEdges = dependencies.filter(
+        (d) => d.target_contract_id === contractId,
+      );
+
+      for (const edge of dependentEdges) {
+        const dependentNodeId = edge.source_node_id;
+        const dependentNode = nodeMap.get(dependentNodeId);
+
+        if (!dependentNode) continue;
+
+        // Skip nodes that are already reviewing or roadmap, per S011 instructions.
+        if (
+          dependentNode.status === "needs-review" ||
+          dependentNode.status === "roadmap"
+        ) {
+          continue;
+        }
+
+        // Flag the node natively
+        await this.store.updateNodeStatus(dependentNode.id, "needs-review");
+        dependentNode.status = "needs-review"; // Update internal ref mapping
+
+        flaggedNodes.push({
+          nodeId: dependentNode.id,
+          filePath: dependentNode.file_path,
+          triggeredByContractId: contractId,
+          impact: depth === 1 ? "direct" : "transitive",
+          depth,
+        });
+
+        // Enqueue cascading contracts exported by the now-flagged dependent node
+        const cascadingContracts = contracts.filter(
+          (c) => c.node_id === dependentNode.id,
+        );
+        for (const cContract of cascadingContracts) {
+          queue.push([cContract.id, depth + 1]);
+        }
+      }
+    }
+
+    // S012: graph is consistent when no nodes need review and all nodes are stable or roadmap.
+    // Roadmap nodes are planned-but-not-yet-built and are an acceptable stable state.
+    return {
+      consistent:
+        flaggedNodes.length === 0 &&
+        nodes.every((n) => n.status === "stable" || n.status === "roadmap"),
+      flagged: flaggedNodes,
+      integrityViolations,
+      importSuggestions,
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  private validateImportIntegrity(
+    nodes: FerretNode[],
+    contracts: FerretContract[],
+    dependencies: FerretDependency[],
+  ): ImportIntegrityReport {
+    const nodeById = new Map(nodes.map((node) => [node.id, node]));
+    const contractById = new Map(
+      contracts.map((contract) => [contract.id, contract]),
+    );
+    const contractsByNodeId = new Map<string, FerretContract[]>();
+
+    for (const contract of contracts) {
+      const existing = contractsByNodeId.get(contract.node_id) ?? [];
+      existing.push(contract);
+      contractsByNodeId.set(contract.node_id, existing);
+    }
+
+    const dependencyKeys = new Set<string>();
+    const uniqueDependencies = dependencies.filter((dependency) => {
+      const key = `${dependency.source_node_id}->${dependency.target_contract_id}`;
+      if (dependencyKeys.has(key)) {
+        return false;
+      }
+      dependencyKeys.add(key);
+      return true;
+    });
+
+    const unresolvedImports: UnresolvedImportViolation[] = [];
+    const selfImports: SelfImportViolation[] = [];
+    const adjacency = new Map<string, Set<string>>();
+    const importsBySourceContractId = new Map<string, string[]>();
+
+    for (const contract of contracts) {
+      adjacency.set(contract.id, new Set<string>());
+    }
+
+    for (const dependency of uniqueDependencies) {
+      const sourceNode = nodeById.get(dependency.source_node_id);
+      const sourceContracts =
+        contractsByNodeId.get(dependency.source_node_id) ?? [];
+      const targetContract = contractById.get(dependency.target_contract_id);
+
+      if (!sourceNode || sourceContracts.length === 0) {
+        continue;
+      }
+
+      for (const sourceContract of sourceContracts) {
+        const existing = importsBySourceContractId.get(sourceContract.id) ?? [];
+        existing.push(dependency.target_contract_id);
+        importsBySourceContractId.set(sourceContract.id, existing);
+      }
+
+      if (!targetContract) {
+        for (const sourceContract of sourceContracts) {
+          unresolvedImports.push({
+            contractId: sourceContract.id,
+            filePath: sourceNode.file_path,
+            importPath: dependency.target_contract_id,
+            expectedTargetId: dependency.target_contract_id,
+          });
+        }
+        continue;
+      }
+
+      const selfImportingContracts = sourceContracts.filter(
+        (sourceContract) => sourceContract.id === dependency.target_contract_id,
+      );
+      for (const sourceContract of selfImportingContracts) {
+        selfImports.push({
+          contractId: sourceContract.id,
+          filePath: sourceNode.file_path,
+          importPath: dependency.target_contract_id,
+        });
+      }
+
+      for (const sourceContract of sourceContracts) {
+        if (sourceContract.id === dependency.target_contract_id) {
+          continue;
+        }
+        adjacency.get(sourceContract.id)?.add(dependency.target_contract_id);
+      }
+    }
+
+    const circularImports = this.findCircularImports(
+      adjacency,
+      contractById,
+      nodeById,
+    );
+
+    const reverseAdjacency = buildReverseAdjacency(adjacency);
+    for (const violation of unresolvedImports) {
+      const upstreamChain = this.findTransitiveChainToContract(
+        violation.contractId,
+        reverseAdjacency,
+      );
+      if (upstreamChain.length > 1) {
+        violation.transitiveChain = [...upstreamChain, violation.expectedTargetId];
+      }
+    }
+
+    const orphanedContracts: OrphanedContractViolation[] = [];
+    for (const contract of contracts) {
+      const imports = importsBySourceContractId.get(contract.id) ?? [];
+      if (imports.length === 0) {
+        continue;
+      }
+
+      const validResolvedCount = imports.filter((targetId) => {
+        if (targetId === contract.id) {
+          return false;
+        }
+        return contractById.has(targetId);
+      }).length;
+
+      const unresolvedForContract = imports.filter(
+        (targetId) => !contractById.has(targetId),
+      );
+
+      if (validResolvedCount === 0 && unresolvedForContract.length > 0) {
+        const sourceNode = nodeById.get(contract.node_id);
+        orphanedContracts.push({
+          contractId: contract.id,
+          filePath: sourceNode?.file_path ?? contract.id,
+          unresolvedImports: [...new Set(unresolvedForContract)].sort(),
+          remediationHint:
+            "Add or restore the expected target contract(s), or remove stale imports.",
+        });
+      }
+    }
+
+    return {
+      unresolvedImports,
+      selfImports,
+      circularImports,
+      orphanedContracts: orphanedContracts.sort((left, right) =>
+        left.contractId.localeCompare(right.contractId),
+      ),
+    };
+  }
+
+  private findTransitiveChainToContract(
+    contractId: string,
+    reverseAdjacency: Map<string, Set<string>>,
+  ): string[] {
+    const visit = (currentId: string, seen: Set<string>): string[] => {
+      const parents = [...(reverseAdjacency.get(currentId) ?? [])]
+        .filter((parentId) => !seen.has(parentId))
+        .sort();
+      if (parents.length === 0) {
+        return [currentId];
+      }
+
+      let bestPath = [currentId];
+      for (const parentId of parents) {
+        const nextSeen = new Set(seen);
+        nextSeen.add(parentId);
+        const parentPath = visit(parentId, nextSeen);
+        const candidate = [...parentPath, currentId];
+        if (
+          candidate.length > bestPath.length ||
+          (candidate.length === bestPath.length &&
+            candidate.join("->") < bestPath.join("->"))
+        ) {
+          bestPath = candidate;
+        }
+      }
+
+      return bestPath;
+    };
+
+    return visit(contractId, new Set([contractId]));
+  }
+
+  private findCircularImports(
+    adjacency: Map<string, Set<string>>,
+    contractById: Map<string, FerretContract>,
+    nodeById: Map<string, FerretNode>,
+  ): CircularImportViolation[] {
+    const visited = new Set<string>();
+    const path: string[] = [];
+    const cycleMap = new Map<string, CircularImportViolation>();
+    const contractIds = [...adjacency.keys()].sort();
+
+    const visit = (contractId: string): void => {
+      visited.add(contractId);
+      path.push(contractId);
+
+      const neighbors = [...(adjacency.get(contractId) ?? [])].sort();
+      for (const neighborId of neighbors) {
+        const existingIndex = path.indexOf(neighborId);
+        if (existingIndex !== -1) {
+          const cycle = [...path.slice(existingIndex), neighborId];
+          const key = canonicalizeCycle(cycle);
+          if (!cycleMap.has(key)) {
+            const sourceContractId = cycle[0];
+            const sourceContract = contractById.get(sourceContractId);
+            const sourceNode = sourceContract
+              ? nodeById.get(sourceContract.node_id)
+              : undefined;
+            cycleMap.set(key, {
+              contractId: sourceContractId,
+              filePath: sourceNode?.file_path ?? sourceContractId,
+              importPath: cycle.join(" -> "),
+              cycle,
+            });
+          }
+          continue;
+        }
+
+        if (!visited.has(neighborId)) {
+          visit(neighborId);
+        }
+      }
+
+      path.pop();
+    };
+
+    for (const contractId of contractIds) {
+      if (!visited.has(contractId)) {
+        visit(contractId);
+      }
+    }
+
+    return [...cycleMap.values()].sort((left, right) =>
+      left.importPath.localeCompare(right.importPath),
+    );
+  }
+}
+
+function buildReverseAdjacency(
+  adjacency: Map<string, Set<string>>,
+): Map<string, Set<string>> {
+  const reverse = new Map<string, Set<string>>();
+
+  for (const [sourceId, targets] of adjacency) {
+    if (!reverse.has(sourceId)) {
+      reverse.set(sourceId, new Set<string>());
+    }
+    for (const targetId of targets) {
+      const parents = reverse.get(targetId) ?? new Set<string>();
+      parents.add(sourceId);
+      reverse.set(targetId, parents);
+    }
+  }
+
+  return reverse;
+}
+
+function canonicalizeCycle(cycle: string[]): string {
+  const ring = cycle.slice(0, -1);
+  if (ring.length === 0) {
+    return "";
+  }
+
+  const rotations = ring.map((_, index) => {
+    const rotated = [...ring.slice(index), ...ring.slice(0, index)];
+    return `${rotated.join("->")}->${rotated[0]}`;
+  });
+
+  return rotations.sort()[0];
+}

package/src/store/factory.ts

@@ -0,0 +1,54 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { DBStore } from "./types.js";
+import { SqliteStore } from "./sqlite.js";
+import { PostgresStore } from "./postgres.js";
+import { loadConfig } from "../config.js";
+import { findProjectRoot } from "../utils/paths.js";
+
+/**
+ * Evaluates the current environment and configuration (handling overrides from the CI pipeline, S005)
+ * and returns the correct initialized database engine.
+ */
+export async function getStore(): Promise<DBStore> {
+  // S005: If FERRET_DATABASE_URL is set in the environment, use PostgreSQL without prompts.
+  const envUrl = process.env.FERRET_DATABASE_URL;
+  if (envUrl) {
+    const store = new PostgresStore(envUrl);
+    // In production we should ensure init() was run by `ferret init`, but we do it gracefully here
+    // or rely on the user to run init. If this was just the runner, it shouldn't recreate tables.
+    // For now we assume the caller handles init if necessary, or we just return the instantiated store.
+    return store;
+  }
+
+  // At this point FERRET_DATABASE_URL is NOT set in the environment (we returned early above if it was).
+  // If the config explicitly opts into postgres, that means the user ran `ferret upgrade --postgres`
+  // which writes FERRET_DATABASE_URL to .env, but that .env has not been loaded into the environment.
+  // Fail fast with a clear error rather than silently falling through to SQLite.
+  try {
+    const config = await loadConfig();
+    if (config.store === "postgres") {
+      console.error("FATAL: ferret.config.json sets store to postgres but FERRET_DATABASE_URL is not set. Source your .env file or set the variable in your environment.");
+      process.exit(1);
+    }
+  } catch {
+    // Suppress config missing errors and fallback to logic
+  }
+
+  // S005: If FERRET_DATABASE_URL is not set, and config is missing / local, fall back to SQLite
+  // Check if .ferret/graph.db exists relative to the discovered project root
+  const dbPath = path.join(findProjectRoot(), ".ferret", "graph.db");
+  try {
+    await fs.access(dbPath);
+    return new SqliteStore(); // Implicit fallback to SQLite
+  } catch (err) {
+    // CI Mode checking: 
+    if (process.env.FERRET_CI === "true") {
+      console.error("FATAL: FERRET_CI is true, but no database configuration found.");
+      process.exit(1);
+    }
+    
+    // SQLite by default
+    return new SqliteStore();
+  }
+}

package/src/store/postgres.ts

@@ -0,0 +1,84 @@
+// Sprint 2 roadmap — Postgres support not yet implemented.
+// This stub exists so factory.ts compiles.
+// Do not use this in production until Sprint 2 is complete.
+
+import type {
+  DBStore,
+  FerretNode,
+  FerretContract,
+  FerretDependency,
+  FerretReconciliationLog,
+  FerretPlacementDecision,
+  NodeStatus,
+} from "./types.js";
+
+export class PostgresStore implements DBStore {
+  constructor(private connectionString: string) {}
+
+  private notImplemented(): never {
+    throw new Error(
+      "PostgresStore: Postgres support is Sprint 2 roadmap. " +
+        'Set FERRET_DATABASE_URL to use Postgres, or remove the store: "postgres" config to use SQLite.',
+    );
+  }
+
+  async init(): Promise<void> {
+    this.notImplemented();
+  }
+  async close(): Promise<void> {
+    this.notImplemented();
+  }
+  async getNodeByFilePath(_filePath: string): Promise<FerretNode | null> {
+    this.notImplemented();
+  }
+  async upsertNode(_node: FerretNode): Promise<void> {
+    this.notImplemented();
+  }
+  async getAllContractIds(): Promise<string[]> {
+    this.notImplemented();
+  }
+  async upsertContract(_contract: FerretContract): Promise<void> {
+    this.notImplemented();
+  }
+  async upsertDependency(_dependency: FerretDependency): Promise<void> {
+    this.notImplemented();
+  }
+  async replaceDependenciesForSourceNode(
+    _sourceNodeId: string,
+    _targetNodeIds: string[],
+  ): Promise<void> {
+    this.notImplemented();
+  }
+  async getNodes(): Promise<FerretNode[]> {
+    this.notImplemented();
+  }
+  async getNodesByStatus(_status: NodeStatus): Promise<FerretNode[]> {
+    this.notImplemented();
+  }
+  async getContracts(): Promise<FerretContract[]> {
+    this.notImplemented();
+  }
+  async getContract(_id: string): Promise<FerretContract | null> {
+    this.notImplemented();
+  }
+  async getDependencies(): Promise<FerretDependency[]> {
+    this.notImplemented();
+  }
+  async updateNodeStatus(_nodeId: string, _status: NodeStatus): Promise<void> {
+    this.notImplemented();
+  }
+  async insertReconciliationLog(_log: FerretReconciliationLog): Promise<void> {
+    this.notImplemented();
+  }
+  async getReconciliationLogs(): Promise<FerretReconciliationLog[]> {
+    this.notImplemented();
+  }
+  async insertPlacementDecision(
+    _decision: FerretPlacementDecision,
+  ): Promise<void> {
+    this.notImplemented();
+  }
+  async getPlacementDecisions(): Promise<FerretPlacementDecision[]> {
+    this.notImplemented();
+  }
+}