forge-server 0.1.0

package/src/pipeline/state-machine.ts

@@ -0,0 +1,199 @@
+// Pipeline state machine: transition table, validation, and cycle tracking.
+//
+// Design notes:
+// - The Phase type from types.ts uses the forge-graph-rag naming convention
+//   ('idle', 'interview', 'requirements', 'architecture', 'design', 'qa_strategy',
+//   'implementation', 'inspection', 'knowledge_collection', 'completed').
+// - PipelineTier determines which edges are legal.
+// - Cycle edges (inspection -> implementation, requirements -> architecture) are
+//   separate from the forward table so callers can track iteration counts.
+
+import type { Phase, PipelineTier } from '../util/types.js';
+
+// ---------------------------------------------------------------------------
+// Transition table: maps each (Phase, PipelineTier) pair to the set of phases
+// that may legally be transitioned to.
+// ---------------------------------------------------------------------------
+
+// For 'full' and 'abbreviated' tiers we share the same edge set — abbreviated
+// is full minus the interview/requirements/design/qa phases, so we model it as
+// a separate entry below.
+const FULL_FORWARD_TRANSITIONS: Readonly<Record<Phase, readonly Phase[]>> = {
+  idle:                 ['interview'],
+  interview:            ['architecture'],
+  requirements:         ['architecture'],
+  architecture:         ['design', 'qa_strategy', 'implementation'],
+  design:               ['qa_strategy', 'implementation'],
+  qa_strategy:          ['implementation'],
+  implementation:       ['inspection'],
+  inspection:           ['knowledge_collection', 'implementation'],
+  knowledge_collection: ['completed'],
+  completed:            [],
+};
+
+// Bug-fix (abbreviated) pipeline: idle -> architecture -> implementation ->
+// inspection -> (completed | implementation). No interview/requirements/design/qa.
+const BUG_FIX_FORWARD_TRANSITIONS: Readonly<Record<Phase, readonly Phase[]>> = {
+  idle:                 ['architecture'],
+  interview:            [],
+  requirements:         ['architecture'],
+  architecture:         ['implementation'],
+  design:               [],
+  qa_strategy:          [],
+  implementation:       ['inspection'],
+  inspection:           ['implementation', 'completed'],
+  knowledge_collection: [],
+  completed:            [],
+};
+
+// Trivial: idle -> completed directly.
+const TRIVIAL_FORWARD_TRANSITIONS: Readonly<Record<Phase, readonly Phase[]>> = {
+  idle:                 ['completed'],
+  interview:            [],
+  requirements:         [],
+  architecture:         [],
+  design:               [],
+  qa_strategy:          [],
+  implementation:       [],
+  inspection:           [],
+  knowledge_collection: [],
+  completed:            [],
+};
+
+// Internal lookup by tier.
+function getTable(tier: PipelineTier): Readonly<Record<Phase, readonly Phase[]>> {
+  switch (tier) {
+    case 'full':
+      return FULL_FORWARD_TRANSITIONS;
+    case 'abbreviated':
+      return BUG_FIX_FORWARD_TRANSITIONS;
+    case 'trivial':
+      return TRIVIAL_FORWARD_TRANSITIONS;
+    default: {
+      // Exhaustiveness guard — TypeScript will catch unhandled tiers at
+      // compile time, but the runtime guard prevents silent misbehaviour.
+      const _exhaustive: never = tier;
+      throw new Error(`Unknown PipelineTier: ${_exhaustive}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true when the requested phase transition is legal for the given tier.
+ *
+ * Rules:
+ *  - A phase may always transition to itself (idempotent re-start is handled
+ *    at the engine layer, but the state machine permits it).
+ *  - Otherwise the transition must appear in the table for the given tier.
+ *
+ * Note: cycle limit enforcement is NOT done here — call `canCycle()` in
+ * addition when the engine detects a backward edge.
+ */
+export function isValidTransition(
+  from: Phase,
+  to: Phase,
+  tier: PipelineTier,
+): boolean {
+  if (from === to) {
+    // Re-entering the same phase is permitted (e.g., retrying a failed start).
+    return true;
+  }
+  const table = getTable(tier);
+  const legalTargets = table[from];
+  return legalTargets !== undefined && (legalTargets as readonly Phase[]).includes(to);
+}
+
+/**
+ * Returns the set of phases that are legal next steps from `phase` for the
+ * given tier. This is used to populate `available_transitions` in API
+ * responses so callers know what actions are currently available.
+ */
+export function getAvailableTransitions(phase: Phase, tier: PipelineTier): Phase[] {
+  const table = getTable(tier);
+  return [...(table[phase] ?? [])];
+}
+
+// ---------------------------------------------------------------------------
+// Cycle limits
+// ---------------------------------------------------------------------------
+
+/**
+ * Maximum number of times each backward edge may be traversed before the
+ * engine forces a forward skip.
+ *
+ * Key format: '<from>_to_<to>'.
+ */
+export const MAX_CYCLES: Readonly<Record<string, number>> = {
+  inspection_to_implementation: 3,
+  requirements_to_architecture: 2,
+};
+
+/**
+ * Returns true if the backward (cycle) edge from -> to may be traversed given
+ * the current number of times it has already been traversed for this project.
+ *
+ * When the limit is exceeded the engine should force-advance to the next
+ * forward phase instead of looping.
+ *
+ * For transitions that are not tracked as cycles (i.e., not in MAX_CYCLES),
+ * this returns true unconditionally — those are ordinary forward transitions
+ * and cycle tracking does not apply.
+ */
+export function canCycle(
+  from: Phase,
+  to: Phase,
+  currentCycleCount: number,
+): boolean {
+  const key = `${from}_to_${to}`;
+  const max = MAX_CYCLES[key];
+  if (max === undefined) {
+    // Not a tracked cycle edge — no limit applies.
+    return true;
+  }
+  return currentCycleCount < max;
+}
+
+/**
+ * Derives the cycle key used in the engine's cycle-count map for a given
+ * backward transition pair.
+ *
+ * Returns null when the pair is not a recognised cycle edge.
+ */
+export function getCycleKey(from: Phase, to: Phase): string | null {
+  const key = `${from}_to_${to}`;
+  return key in MAX_CYCLES ? key : null;
+}
+
+/**
+ * Determines whether a transition is a backward (cycle) edge, as opposed to a
+ * forward progression edge. This is needed by the engine to know when to
+ * increment the cycle counter.
+ *
+ * A transition is considered a cycle when:
+ *  - The `to` phase appears earlier in the canonical phase order than `from`.
+ *  - AND the key is present in MAX_CYCLES (meaning it is a recognised loop).
+ */
+export function isCycleTransition(from: Phase, to: Phase): boolean {
+  return getCycleKey(from, to) !== null;
+}
+
+/**
+ * Returns the phase the engine should force-advance to when a cycle limit is
+ * exceeded.
+ *
+ * Per the architecture spec:
+ *  - inspection -> implementation exceeded: force to knowledge_collection
+ *  - requirements -> architecture exceeded: force to implementation
+ */
+export function getForcedAdvancePhase(from: Phase, to: Phase): Phase | null {
+  const key = `${from}_to_${to}`;
+  const forced: Record<string, Phase> = {
+    inspection_to_implementation: 'knowledge_collection',
+    requirements_to_architecture: 'implementation',
+  };
+  return forced[key] ?? null;
+}

package/src/query/graph-queries.ts

@@ -0,0 +1,262 @@
+/**
+ * Cypher query templates for FalkorDB graph operations.
+ * Centralizes all graph query patterns used by tools.
+ */
+
+// ============================================================
+// Index Creation Queries
+// ============================================================
+
+export const INDEX_QUERIES = [
+  'CREATE INDEX ON :File(path, repo_id)',
+  'CREATE INDEX ON :Function(name, repo_id)',
+  'CREATE INDEX ON :Class(name, repo_id)',
+  'CREATE INDEX ON :Interface(name, repo_id)',
+  'CREATE INDEX ON :Module(name, repo_id)',
+  'CREATE INDEX ON :Observation(id)',
+  'CREATE INDEX ON :Observation(session_id)',
+] as const;
+
+// ============================================================
+// Node Count Queries
+// ============================================================
+
+export const QUERY_TOTAL_NODES = 'MATCH (n) RETURN count(n) as cnt';
+export const QUERY_TOTAL_EDGES = 'MATCH ()-[r]->() RETURN count(r) as cnt';
+
+export const QUERY_NODES_BY_LABEL = (label: string) =>
+  `MATCH (n:${label}) RETURN count(n) as cnt`;
+
+// ============================================================
+// File Queries
+// ============================================================
+
+/**
+ * Get all entities contained in a file.
+ */
+export const QUERY_FILE_ENTITIES = (filePath: string, repoId: string) => `
+  MATCH (f:File {path: "${esc(filePath)}", repo_id: "${esc(repoId)}"})-[:CONTAINS]->(s)
+  RETURN s, labels(s) as label
+`;
+
+/**
+ * Get all files in a repo.
+ */
+export const QUERY_REPO_FILES = (repoId: string) => `
+  MATCH (f:File {repo_id: "${esc(repoId)}"})
+  RETURN f.path as path, f.content_hash as hash, f.last_indexed as indexed_at
+`;
+
+/**
+ * Get files in a directory.
+ */
+export const QUERY_DIRECTORY_FILES = (dirPath: string, repoId: string) => `
+  MATCH (f:File {repo_id: "${esc(repoId)}"})
+  WHERE f.path STARTS WITH "${esc(dirPath)}"
+  RETURN f.path as path, f.language as language
+`;
+
+// ============================================================
+// Impact Graph Queries
+// ============================================================
+
+/**
+ * Inbound: who calls/imports/uses this symbol?
+ */
+export const QUERY_INBOUND_IMPACT = (symbolName: string, repoId: string, depth: number) => `
+  MATCH (center {name: "${esc(symbolName)}", repo_id: "${esc(repoId)}"})
+  MATCH path = (caller)-[r*1..${depth}]->(center)
+  RETURN caller, r, length(path) as depth
+  LIMIT 50
+`;
+
+/**
+ * Outbound: what does this symbol depend on?
+ */
+export const QUERY_OUTBOUND_IMPACT = (symbolName: string, repoId: string, depth: number) => `
+  MATCH (center {name: "${esc(symbolName)}", repo_id: "${esc(repoId)}"})
+  MATCH path = (center)-[r*1..${depth}]->(dep)
+  RETURN dep, r, length(path) as depth
+  LIMIT 50
+`;
+
+// ============================================================
+// Logic Flow Queries
+// ============================================================
+
+/**
+ * Shortest path between two symbols in the call graph.
+ */
+export const QUERY_SHORTEST_PATH = (fromSymbol: string, toSymbol: string, repoId: string, maxDepth: number) => `
+  MATCH (a {name: "${esc(fromSymbol)}", repo_id: "${esc(repoId)}"}),
+        (b {name: "${esc(toSymbol)}", repo_id: "${esc(repoId)}"})
+  MATCH path = shortestPath((a)-[*..${maxDepth}]->(b))
+  RETURN path
+  LIMIT 3
+`;
+
+// ============================================================
+// Graph Neighbor Queries (for hybrid search boost)
+// ============================================================
+
+/**
+ * Get graph neighbors of a file (imports, tests, co-modified).
+ * Used to boost vector search results with graph connectivity.
+ */
+export const QUERY_FILE_NEIGHBORS = (filePath: string, repoId: string, depth: number) => `
+  MATCH (f:File {path: "${esc(filePath)}", repo_id: "${esc(repoId)}"})
+  MATCH (f)-[r*1..${depth}]-(neighbor:File)
+  RETURN neighbor.path as path, type(r[0]) as rel_type, length(r) as depth
+  LIMIT 20
+`;
+
+/**
+ * Get import graph for a file.
+ */
+export const QUERY_FILE_IMPORTS = (filePath: string, repoId: string) => `
+  MATCH (f:File {path: "${esc(filePath)}", repo_id: "${esc(repoId)}"})-[:IMPORTS]->(dep:File)
+  RETURN dep.path as path
+`;
+
+/**
+ * Get test files for a source file.
+ */
+export const QUERY_FILE_TESTS = (filePath: string, repoId: string) => `
+  MATCH (test:File)-[:TESTS]->(src:File {path: "${esc(filePath)}", repo_id: "${esc(repoId)}"})
+  RETURN test.path as path
+`;
+
+// ============================================================
+// Observation Queries
+// ============================================================
+
+/**
+ * Create or update an Observation node.
+ */
+export const UPSERT_OBSERVATION = (
+  id: string,
+  content: string,
+  sessionId: string,
+  importance: number
+) => `
+  MERGE (o:Observation {id: "${esc(id)}"})
+  SET o.content = "${esc(content)}",
+      o.session_id = "${esc(sessionId)}",
+      o.importance = ${importance},
+      o.is_stale = false,
+      o.created_at = ${Date.now()}
+`;
+
+/**
+ * Link an observation to a code symbol via REFERENCES edge.
+ */
+export const LINK_OBSERVATION_TO_SYMBOL = (observationId: string, symbolName: string, repoId: string) => `
+  MATCH (o:Observation {id: "${esc(observationId)}"})
+  MATCH (s {name: "${esc(symbolName)}", repo_id: "${esc(repoId)}"})
+  MERGE (o)-[:REFERENCES]->(s)
+`;
+
+/**
+ * Get recent observations by session.
+ */
+export const QUERY_SESSION_OBSERVATIONS = (sessionId: string, limit: number) => `
+  MATCH (o:Observation {session_id: "${esc(sessionId)}"})
+  RETURN o ORDER BY o.created_at DESC LIMIT ${limit}
+`;
+
+/**
+ * Mark observations as stale when a symbol changes.
+ */
+export const MARK_SYMBOL_OBSERVATIONS_STALE = (symbolName: string, repoId: string) => `
+  MATCH (o:Observation)-[:REFERENCES]->(s {name: "${esc(symbolName)}", repo_id: "${esc(repoId)}"})
+  SET o.is_stale = true
+`;
+
+// ============================================================
+// File Hotspot Queries (Phase 3 - git enrichment)
+// ============================================================
+
+/**
+ * Get top files by commit_count (change hotspots) for a repo.
+ * Requires File nodes to have commit_count property set by git enrichment.
+ */
+export const QUERY_FILE_HOTSPOTS = (repoId: string, limit: number = 100) => `
+  MATCH (f:File {repo_id: "${esc(repoId)}"})
+  WHERE f.commit_count IS NOT NULL AND f.commit_count > 0
+  RETURN f.path as path, f.commit_count as commit_count, f.stability_score as stability_score, f.change_velocity as change_velocity
+  ORDER BY f.commit_count DESC
+  LIMIT ${limit}
+`;
+
+/**
+ * Get git stats for a single file.
+ */
+export const QUERY_FILE_STATS = (filePath: string, repoId: string) => `
+  MATCH (f:File {path: "${esc(filePath)}", repo_id: "${esc(repoId)}"})
+  RETURN f.path as path, f.commit_count as commit_count, f.stability_score as stability_score, f.change_velocity as change_velocity, f.last_commit_hash as last_commit_hash, f.last_commit_ts as last_commit_ts
+`;
+
+// ============================================================
+// Co-modification Queries
+// ============================================================
+
+/**
+ * Upsert a co-modification relationship between two files.
+ */
+export const UPSERT_CO_MODIFIED = (fileA: string, fileB: string, repoId: string, count: number, lastCommit: string) => `
+  MATCH (a:File {path: "${esc(fileA)}", repo_id: "${esc(repoId)}"})
+  MATCH (b:File {path: "${esc(fileB)}", repo_id: "${esc(repoId)}"})
+  MERGE (a)-[r:CO_MODIFIED]-(b)
+  SET r.count = ${count}, r.last_commit = "${esc(lastCommit)}"
+`;
+
+// ============================================================
+// CALLS Edge Queries
+// ============================================================
+
+/**
+ * Upsert a CALLS relationship between two functions.
+ * Uses MERGE to avoid duplicate edges.
+ */
+export const UPSERT_CALLS = (
+  callerName: string,
+  callerFilePath: string,
+  calleeName: string,
+  calleeFilePath: string,
+  repoId: string,
+  callCount: number
+) => `
+  MATCH (caller:Function {name: "${esc(callerName)}", file_path: "${esc(callerFilePath)}", repo_id: "${esc(repoId)}"})
+  MATCH (callee:Function {name: "${esc(calleeName)}", file_path: "${esc(calleeFilePath)}", repo_id: "${esc(repoId)}"})
+  MERGE (caller)-[r:CALLS]->(callee)
+  SET r.call_count = ${callCount}
+`;
+
+// ============================================================
+// TESTS Edge Queries
+// ============================================================
+
+/**
+ * Upsert a TESTS relationship from a test file to its source file.
+ */
+export const UPSERT_TESTS = (testFilePath: string, sourceFilePath: string, repoId: string) => `
+  MATCH (test:File {path: "${esc(testFilePath)}", repo_id: "${esc(repoId)}"})
+  MATCH (src:File {path: "${esc(sourceFilePath)}", repo_id: "${esc(repoId)}"})
+  MERGE (test)-[:TESTS]->(src)
+`;
+
+// ============================================================
+// Utility
+// ============================================================
+
+/**
+ * Escape a string for safe embedding in Cypher queries.
+ * FalkorDB uses double-quoted strings.
+ */
+function esc(s: string): string {
+  return s
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '');
+}