@cleocode/contracts 2026.4.100 → 2026.4.101

package/src/nexus-query-ops.ts

@@ -0,0 +1,100 @@
+/**
+ * Nexus SQLite Recursive CTE Query Operations - Contract Layer
+ *
+ * Defines types for parameterized CTE execution against nexus.db.
+ * Contracts for the query DSL and template alias system.
+ *
+ * @task T1057
+ * @epic T1042
+ */
+
+/**
+ * Result of a recursive CTE query against nexus.db.
+ * Returns rows as generic Record[] and metadata about the query.
+ */
+export interface NexusCteResult {
+  /**
+   * Whether the query executed successfully.
+   */
+  success: boolean;
+
+  /**
+   * Query result rows. Empty array if no results.
+   */
+  rows: Array<Record<string, unknown>>;
+
+  /**
+   * Total number of rows returned.
+   */
+  row_count: number;
+
+  /**
+   * Query execution time in milliseconds.
+   */
+  execution_time_ms: number;
+
+  /**
+   * If success is false, error message describing the parse/execution failure.
+   * e.g. "CTE syntax error: ...", "Parameter mismatch: ..."
+   */
+  error?: string;
+}
+
+/**
+ * Parameters for CTE execution.
+ * Supports positional (?) and named (:name) parameter binding.
+ */
+export type NexusCteParams = (string | number | null)[];
+
+/**
+ * Named template alias for common CTE patterns.
+ * Compiles to parameterized CTE before execution.
+ */
+export type NexusCteAlias =
+  | 'callers-of'
+  | 'callees-of'
+  | 'co-changed'
+  | 'co-cited'
+  | 'path-between'
+  | 'community-members';
+
+/**
+ * Represents a compiled CTE template ready for execution.
+ * Internal: generated by compileCteAlias().
+ */
+export interface NexusCtePlaceholder {
+  /**
+   * The CTE SQL string with parameter placeholders.
+   */
+  cte: string;
+
+  /**
+   * Human-readable description of what this CTE queries.
+   */
+  description: string;
+
+  /**
+   * Expected parameter count for this template.
+   */
+  paramCount: number;
+
+  /**
+   * Parameter names for documentation.
+   */
+  paramNames: string[];
+}
+
+/**
+ * Formatted markdown table of query results.
+ */
+export interface NexusCteMarkdownTable {
+  /**
+   * Markdown-formatted table string.
+   */
+  markdown: string;
+
+  /**
+   * Number of rows in the table.
+   */
+  row_count: number;
+}

package/src/nexus-route-ops.ts

@@ -0,0 +1,134 @@
+/**
+ * Route and API shape analysis contracts for NEXUS.
+ *
+ * Routes are first-class nodes in the code graph (kind: 'route').
+ * This module defines the query results for route mapping and shape checking.
+ *
+ * @task T1064 — Route-Map and Shape-Check Commands
+ */
+
+/**
+ * A single route handler entry from `route-map`.
+ *
+ * Maps a route node to its handler functions and downstream dependencies.
+ */
+export interface RouteMapEntry {
+  /** Route node ID (format: `<filePath>::<routeName>`). */
+  routeId: string;
+
+  /** Route handler function symbol ID. */
+  handlerId: string;
+
+  /** Human-readable handler name. */
+  handlerName: string;
+
+  /** File path of the handler (relative to project root). */
+  handlerFile: string;
+
+  /** Source language (typescript, python, etc.). */
+  language: string;
+
+  /** Route metadata from metaJson (method, path, etc.). */
+  routeMeta: {
+    /** HTTP method (GET, POST, PUT, DELETE, PATCH). */
+    method?: string;
+
+    /** Route path pattern (e.g., `/api/v1/tasks`). */
+    path?: string;
+
+    /** Additional metadata fields. */
+    [key: string]: unknown;
+  };
+
+  /** Symbols/modules fetched by this handler (external dependencies). */
+  fetchedDeps: Array<{
+    /** Dependency target symbol or module name. */
+    target: string;
+
+    /** Relation type (fetches, imports, calls). */
+    relationType: string;
+
+    /** Confidence score [0..1]. */
+    confidence: number;
+  }>;
+
+  /** Count of downstream callers of this handler. */
+  callerCount: number;
+}
+
+/**
+ * Result of `route-map` command — all routes with handlers and deps.
+ */
+export interface RouteMapResult {
+  /** Project ID the routes belong to. */
+  projectId: string;
+
+  /** All routes with their handlers and dependencies. */
+  routes: RouteMapEntry[];
+
+  /** Count of route nodes analyzed. */
+  routeCount: number;
+
+  /** Count of handler functions found. */
+  handlerCount: number;
+
+  /** External dependencies (distinct modules/specs fetched). */
+  distinctDeps: string[];
+}
+
+/**
+ * Shape compatibility verdict from `shape-check`.
+ */
+export type ShapeCheckStatus = 'compatible' | 'incompatible' | 'partial' | 'unknown';
+
+/**
+ * A single caller of a route handler and its expected response shape.
+ */
+export interface ShapeCheckCaller {
+  /** Caller symbol ID. */
+  callerId: string;
+
+  /** Caller name. */
+  callerName: string;
+
+  /** File path of the caller. */
+  callerFile: string;
+
+  /** Inferred expected response shape (from return type or usage). */
+  expectedShape: string;
+
+  /** Compatibility status versus the route's declared shape. */
+  status: ShapeCheckStatus;
+
+  /** Human-readable diagnosis. */
+  diagnosis: string;
+}
+
+/**
+ * Result of `shape-check` command — route's shape vs all callers.
+ */
+export interface ShapeCheckResult {
+  /** Route symbol ID being checked. */
+  routeId: string;
+
+  /** Route handler symbol ID. */
+  handlerId: string;
+
+  /** Declared response shape from meta_json or return type. */
+  declaredShape: string;
+
+  /** All callers and their expected shapes. */
+  callers: ShapeCheckCaller[];
+
+  /** Count of compatible callers. */
+  compatibleCount: number;
+
+  /** Count of incompatible callers. */
+  incompatibleCount: number;
+
+  /** Overall compatibility status. */
+  overallStatus: ShapeCheckStatus;
+
+  /** Recommendation. */
+  recommendation: string;
+}

package/src/nexus-tasks-bridge-ops.ts

@@ -0,0 +1,71 @@
+/**
+ * Types for TASKS → NEXUS bridge operations.
+ *
+ * Enables querying which tasks touched which symbols (T1067).
+ * Supports forward lookup (task → symbols) and reverse lookup (symbol → tasks).
+ *
+ * @task T1067
+ * @epic T1042
+ */
+
+/**
+ * A single task reference in a symbol context.
+ * Used by getTasksForSymbol() reverse-lookup queries.
+ */
+export interface TaskReference {
+  /** Task ID (e.g., 'T001'). */
+  taskId: string;
+  /** Display label for the task. */
+  label: string;
+  /** Edge weight (confidence) that this task touched the symbol. */
+  weight: number;
+  /** Human-readable match strategy used ('git-log-file', 'file-symbol-match', etc.). */
+  matchStrategy: string;
+}
+
+/**
+ * A single symbol reference in a task context.
+ * Used by getSymbolsForTask() forward-lookup queries.
+ */
+export interface SymbolReference {
+  /** Nexus node ID (format: '<filePath>::<name>' or '<filePath>'). */
+  nexusNodeId: string;
+  /** Display label for the symbol (file path or function name). */
+  label: string;
+  /** Symbol kind ('function', 'class', 'file', etc.). */
+  kind: string;
+  /** File path where this symbol is defined. */
+  filePath: string | null;
+  /** Edge weight (confidence) that the task touched this symbol. */
+  weight: number;
+  /** Human-readable match strategy used ('git-log-file', 'file-symbol-match', etc.). */
+  matchStrategy: string;
+}
+
+/**
+ * Result from linkTaskToSymbols() operation.
+ */
+export interface LinkTaskResult {
+  /** Number of task_touches_symbol edges created or found. */
+  linked: number;
+  /** Task ID that was linked. */
+  taskId: string;
+  /** Number of files processed from task.files_json. */
+  filesProcessed: number;
+  /** Number of symbols found in those files. */
+  symbolsFound: number;
+}
+
+/**
+ * Result from runGitLogTaskLinker() git-log sweep operation.
+ */
+export interface GitLogLinkerResult {
+  /** Total number of task_touches_symbol edges created or found across all tasks. */
+  linked: number;
+  /** Commits processed from git log since --since. */
+  commitsProcessed: number;
+  /** Unique task IDs extracted from commit messages. */
+  tasksFound: number;
+  /** Last commit hash processed (stored for idempotency). */
+  lastCommitHash: string | null;
+}

package/src/nexus-wiki-ops.ts

@@ -0,0 +1,53 @@
+/**
+ * Nexus Wiki Index Operations - Contract Layer
+ *
+ * Defines types for generating a community-grouped wiki index
+ * from the nexus code graph.
+ *
+ * @task T1060
+ * @epic T1042
+ */
+
+/**
+ * Statistics for a single community in the wiki index.
+ */
+export interface CommunityWikiStats {
+  /** Community node ID (e.g. "community:42") */
+  communityId: string;
+  /** Number of symbols in this community */
+  memberCount: number;
+}
+
+/**
+ * Result of wiki index generation.
+ */
+export interface NexusWikiResult {
+  /** Whether generation succeeded */
+  success: boolean;
+  /** Output directory where files were written */
+  outputDir: string;
+  /** Number of communities processed */
+  communityCount: number;
+  /** Total number of files written (community files + overview) */
+  fileCount: number;
+  /** Stats per community */
+  communities: CommunityWikiStats[];
+  /** Error message if success is false */
+  error?: string;
+}
+
+/**
+ * Symbol metadata as it appears in the wiki index.
+ */
+export interface WikiSymbolRow {
+  /** Symbol name */
+  name: string;
+  /** Symbol kind (function, class, interface, etc.) */
+  kind: string;
+  /** File path relative to project root */
+  filePath: string | null;
+  /** Number of symbols that call this symbol */
+  callerCount: number;
+  /** Number of symbols this symbol calls */
+  calleeCount: number;
+}