@remnic/coding-graph 9.3.759

package/src/index.ts

@@ -0,0 +1,384 @@
+/**
+ * @remnic/coding-graph — symbol-extraction engine + SQLite knowledge-graph
+ * store for codebase memory.
+ *
+ * À-la-carte optional companion of @remnic/core (CLAUDE.md rule 57).
+ *
+ * This package unifies two PR1 surfaces:
+ *   - The web-tree-sitter engine scaffold (#1551 step 1): the package and
+ *     its build wiring exist; the engine public surface is declared and
+ *     the placeholder factory throws a tagged
+ *     `CodingGraphError("not_implemented", …)`. The real backend lands in
+ *     #1551 PR2.
+ *   - The SQLite knowledge-graph store (#1552 PR1): versioned schema + the
+ *     write pipeline (upsert/drop file batches, node-id derivation,
+ *     dangling-edge accounting). Traversal, search, dead-code, and the
+ *     openCypher subset land in #1552 PR2/PR3.
+ *
+ * Type-source direction:
+ *   The contract types (CodingGraphEngine, FileIR, etc.) and the
+ *   TIER_1_LANGUAGES / CODING_GRAPH_ENGINE_VERSION constants live in
+ *   @remnic/core (packages/remnic-core/src/coding/coding-graph-types.ts,
+ *   re-exported from the main index). This package imports them and
+ *   implements against them; it does NOT redefine them. That keeps a
+ *   single source of truth so updating the engine version in one place
+ *   keeps every consumer in lockstep (Cursor Bugbot low-severity on
+ *   PR #1588 round 2: "ENGINE_VERSION duplicated not imported").
+ *
+ *   @remnic/coding-graph declares @remnic/core as both `peerDependencies`
+ *   and `devDependencies: "workspace:*"` in its package.json, so the
+ *   pnpm workspace link exists and the `import from "@remnic/core"`
+ *   below resolves in development.
+ *
+ *   The store modules (graph-schema, graph-store, row-types) are local to
+ *   this package; they import `openBetterSqlite3` from
+ *   `@remnic/core/runtime/better-sqlite` so the native-binding lifecycle
+ *   is paid for once there (rule 23/38: do not invent a new pattern).
+ *
+ * IR-type re-export policy:
+ *   graph-store.ts imports the core IR contract types (`FileIR`,
+ *   `SymbolIR`, etc.) from `@remnic/core/coding/coding-graph-types`
+ *   and re-exports them so existing `import { type FileIR } from
+ *   "./graph-store.js"` call-sites continue to resolve. The store
+ *   does NOT redefine these types — it derives from the core contract
+ *   so PR2 callers can pass `ParseResult.ir` directly
+ *   (chatgpt-codex-connector P2: 'Derive store FileIR from the core
+ *   parser contract'). At the package root, `FileIR`/`SymbolIR`
+ *   resolve to the @remnic/core contract types re-exported below;
+ *   the store-specific `StoreFileIR` (FileIR + edges extension) and
+ *   `EdgeIR` are re-exported from the root via graph-store.
+ */
+
+import {
+  CODING_GRAPH_ENGINE_VERSION,
+  TIER_1_LANGUAGES,
+  type CodingGraphEngine,
+  type CodingGraphErrorCode,
+  type CodingGraphLanguage,
+  type CreateCodingGraphEngineOptions,
+  type FileIR,
+  type ParseFileInput,
+  type ParseResult,
+  type SymbolIR,
+} from "@remnic/core";
+
+// ---------------------------------------------------------------------------
+// Engine version — single source of truth lives in @remnic/core as
+// `CODING_GRAPH_ENGINE_VERSION`. We re-export it under the conventional
+// `ENGINE_VERSION` name (the dynamic-import loader in @remnic/core
+// validates the shape using this field name) AND keep the core alias
+// available so any consumer that wants the local name or the core
+// name gets the same value. Updating the constant in core propagates
+// here automatically.
+// ---------------------------------------------------------------------------
+
+/** Public engine version. Imported from @remnic/core (single source of truth). */
+export const ENGINE_VERSION = CODING_GRAPH_ENGINE_VERSION;
+
+/** Core-alias re-export so callers can use either name. */
+export { CODING_GRAPH_ENGINE_VERSION };
+
+// ---------------------------------------------------------------------------
+// Tier-1 language list re-export. The list itself lives in @remnic/core
+// (single source of truth) so consumers that reach the optional package
+// via the loader get the same shape they would get from core directly.
+// ---------------------------------------------------------------------------
+export { TIER_1_LANGUAGES };
+export type { CodingGraphLanguage };
+
+// ---------------------------------------------------------------------------
+// Tagged error — `code` is the load-bearing signal for programmatic
+// detection (see PR2 contract).
+// ---------------------------------------------------------------------------
+
+export type { CodingGraphErrorCode } from "@remnic/core";
+
+/**
+ * Thrown by `createCodingGraphEngine` while the real implementation is
+ * being landed. It is *not* a generic Error — the `code` field is the
+ * load-bearing signal for programmatic detection (see PR2 contract).
+ */
+export class CodingGraphError extends Error {
+  readonly code: CodingGraphErrorCode;
+  readonly engineVersion: string;
+
+  constructor(
+    code: CodingGraphErrorCode,
+    message: string,
+    engineVersion: string = ENGINE_VERSION,
+  ) {
+    super(message);
+    this.name = "CodingGraphError";
+    this.code = code;
+    this.engineVersion = engineVersion;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Engine implementation (PR2): WASM tree-sitter parser + tier-1 extractors.
+// Delegates to ./engine/engine.js which wires the ParserBackend, per-language
+// .scm queries, and the FileIR emitter.
+// ---------------------------------------------------------------------------
+
+export { createCodingGraphEngine } from "./engine/engine.js";
+
+// Backwards-compat: re-export the engine module's internal types for any
+// consumer that reached into the implementation.
+export type { ParserBackend } from "./engine/parser-backend.js";
+export { WasmTreeSitterBackend } from "./engine/parser-backend.js";
+
+// ---------------------------------------------------------------------------
+// Re-export the contract types so the public surface is stable whether a
+// consumer reaches into @remnic/coding-graph or @remnic/core. `export type`
+// guarantees these are erased at runtime — no double-emit.
+// ---------------------------------------------------------------------------
+
+export type {
+  CodingGraphEngine,
+  CreateCodingGraphEngineOptions,
+  FileIR,
+  ParseFileInput,
+  ParseResult,
+  SymbolIR,
+};
+
+// ---------------------------------------------------------------------------
+// SQLite knowledge-graph store (#1552 PR1 + PR2): versioned schema, write
+// pipeline, and PR2 read primitives (traverse / searchGraph / schemaStats /
+// deadCode / snippetFor). Re-exported from the package root so consumers
+// can import `import { GraphStore } from "@remnic/coding-graph"` (the
+// subpath exports `./graph-schema` and `./graph-store` remain available
+// for callers that want only one half). Only non-colliding store types
+// are re-exported here — see the file header's IR-type policy note.
+// ---------------------------------------------------------------------------
+
+export {
+  CODING_GRAPH_SCHEMA_VERSION,
+  EDGE_PROVENANCE_VALUES,
+  applyCodingGraphSchema,
+  readSchemaVersion,
+  isEdgeProvenance,
+  type EdgeProvenance,
+} from "./graph-schema.js";
+
+export {
+  GraphStore,
+  nodeIdFor,
+  DEFAULT_TRAVERSE_PATHS_MAX,
+  MAX_TRAVERSE_PATHS_HOPS,
+  DEAD_CODE_EXCLUSION,
+  type ByteSpan,
+  type DeadCodeHit,
+  type DeadCodeResult,
+  type EdgeIR,
+  type ExportIR,
+  type GraphStoreFailure,
+  type GraphStoreFailureCode,
+  type GraphStoreOptions,
+  type ImportIR,
+  type NodeIdInput,
+  type SchemaStats,
+  type SchemaStatsResult,
+  type SearchHit,
+  type SearchQuery,
+  type SearchResult,
+  type SnippetFailureCode,
+  type SnippetQuery,
+  type SnippetResult,
+  type SnippetSuccess,
+  type StoreFileIR,
+  type SymbolKind,
+  type TraverseDirection,
+  type TraverseHit,
+  type TraverseQuery,
+  type TraversePathHit,
+  type TraversePathsQuery,
+  type TraversePathsResult,
+  type TraverseResult,
+  type ReadCoChangeEdge,
+  type ReadCoChangesResult,
+  type ReadFileHashesResult,
+  type ReadMetaResult,
+  type UpsertBatchResult,
+  type UpsertEdgesResult,
+  type UpsertEdgesSuccess,
+  type UpsertResult,
+  type UpsertSuccess,
+} from "./graph-store.js";
+// ---------------------------------------------------------------------------
+// PR3 (issue #1553): incremental git-based reindex, detect_changes + blast
+// radius, co-change mining, and index-status reporting. Re-exported from
+// the package root so consumers can import them alongside the store.
+// ---------------------------------------------------------------------------
+
+export {
+  planReindex,
+  executeReindex,
+  readLastIndexedHead,
+  readFileHashes,
+  hashContent,
+  META_KEY_LAST_HEAD,
+  META_KEY_PENDING_PARSE_FAILURES,
+  type ParseFileFn,
+  type ReadFileFn,
+  type ReindexGitFacts,
+  type ReindexPlan,
+  type ReindexResult,
+  type ReindexState,
+} from "./reindex.js";
+
+export {
+  classifyRisk,
+  computeBlastRadius,
+  findDirectlyAffectedSymbols,
+  byteSpanToLines,
+  rangesOverlap,
+  BLAST_RADIUS_EDGE_TYPES,
+  FAN_IN_ESCALATION_THRESHOLD,
+  DEFAULT_BLAST_RADIUS_DEPTH,
+  type AffectedSymbol,
+  type BlastRadiusResult,
+  type DetectChangesResult,
+  type RiskLevel,
+} from "./detect-changes.js";
+
+export {
+  mineCoChangeEdges,
+  mineAndStoreCoChanges,
+  DEFAULT_CO_CHANGE_CONFIG,
+  type CoChangeConfig,
+  type CoChangeEdge,
+  type MineCoChangesResult,
+} from "./co-change.js";
+
+export {
+  getIndexStatus,
+  type IndexStatus,
+  type IndexStatusMode,
+} from "./index-status.js";
+
+export {
+  defaultCodingGitInvoker,
+  parseNameStatus,
+  parseHunks,
+  parseLogFiles,
+  type CodingGitInvoker,
+  type DiffHunk,
+  type GitFailure,
+  type LogFilesEntry,
+  type NameStatusEntry,
+} from "./git-invoker.js";
+
+// ---------------------------------------------------------------------------
+// PR3 (issue #1552): openCypher read-subset — parser + executor. Re-exported
+// from the package root so consumers can `import { executeCypher } from
+// "@remnic/coding-graph"` (the subpath export `./cypher` remains for callers
+// that want only this layer).
+// ---------------------------------------------------------------------------
+
+export {
+  executeCypher,
+  executeAst,
+  parseCypher,
+  VALID_CYPHER_LABELS,
+  type CypherAst,
+  type CypherFailure,
+  type CypherFailureCode,
+  type CypherNodeValue,
+  type CypherParseResult,
+  type CypherResult,
+  type CypherRow,
+  type CypherScalar,
+  type CypherSuccess,
+  type CypherValue,
+} from "./cypher/query-parser.js";
+// ---------------------------------------------------------------------------
+// PR (issue #1555): Phase B type resolution — LSP client layer over
+// installed language servers. Minimal JSON-RPC-over-stdio client, server
+// registry, resolution pass, and status surfacing. All behind
+// `codingGraph.lsp.enabled` (default false — rule 30/48).
+// ---------------------------------------------------------------------------
+
+export {
+  LspClient,
+  pathToUri,
+  uriToPath,
+  type LspClientOptions,
+} from "./lsp/client.js";
+
+export {
+  LspFrameDecoder,
+  encodeLspFrame,
+  type FrameDecodeError,
+  type FrameDecodeErrorKind,
+  type FrameDecodeResult,
+} from "./lsp/framing.js";
+
+export {
+  DEFAULT_LSP_CONFIG,
+  DEFAULT_LSP_MAX_REQUESTS_PER_RUN,
+  DEFAULT_LSP_TIMEOUT_MS,
+  parseLspConfig,
+  readLspEnabledEnv,
+  type LspConfig,
+  type LspConfigParseResult,
+  type LspServerLaunchSpec,
+  type LspServerOverrides,
+} from "./lsp/config.js";
+
+export {
+  lspDegradation,
+  type LspBackend,
+  type LspDegradation,
+  type LspDegradationCode,
+  type LspResult,
+} from "./lsp/degradation.js";
+
+export {
+  executeLspResolution,
+  mapLocationToNode,
+  planLspUpgrades,
+  type EdgeUpgrade,
+  type LspBudget,
+  type NodeLocator,
+  type PlanResult,
+  type PlannedLspRequest,
+  type ResolutionResult,
+  type ResolveOptions,
+  type UnresolvedCallSite,
+} from "./lsp/resolution.js";
+
+export {
+  formatLspStatusLine,
+  getLspStatus,
+  resolutionResultToStatusMaps,
+  type LspStatusEntry,
+  type LspStatusInput,
+} from "./lsp/status.js";
+export {
+  buildLineOffsetMap,
+  byteOffsetToPosition,
+  positionToByteOffset,
+  type LineOffsetMap,
+} from "./lsp/byte-position.js";
+
+export type {
+  LspInitializeParams,
+  LspInitializeResult,
+  LspLocation,
+  LspPosition,
+  LspRange,
+  LspServerCapabilities,
+  LspTextDocumentItem,
+  LspTextDocumentPositionParams,
+} from "./lsp/types.js";
+
+
+// ---------------------------------------------------------------------------
+// Semantic layer (issue #1556): symbol embeddings, SIMILAR_TO near-clone
+// edges, and semantic_query. OFF by default (SemanticConfig.enabled = false).
+// The layer builds on @remnic/core's host embedding provider + fallback —
+// no new embedding stack. See ./semantic/index.ts for the full surface.
+// ---------------------------------------------------------------------------
+
+export * from "./semantic/index.js";

package/src/lsp/byte-position.ts

@@ -0,0 +1,173 @@
+/**
+ * Byte-offset ↔ LSP position conversion.
+ *
+ * LSP positions are zero-based {line, character} where `character` is a
+ * UTF-16 code-unit offset within the line (LSP 3.17 §3.17). The coding-
+ * graph store uses UTF-8 byte spans. This module converts between the two.
+ *
+ * A {@link LineOffsetMap} pre-computes the UTF-8 BYTE offset of each line
+ * start, making both directions O(log n) via binary search for the line,
+ * then O(line length) for the character within the line.
+ */
+
+/**
+ * Pre-computed line-start byte offsets for a single file. Built once per
+ * file from its content; reused for all position conversions in that file.
+ *
+ * `lineStarts[i]` = UTF-8 byte offset of the first character on line `i`.
+ * Line 0 always starts at byte 0.
+ */
+export interface LineOffsetMap {
+  readonly lineStarts: readonly number[];
+}
+
+/**
+ * Compute the UTF-8 byte length of a single UTF-16 code unit or a
+ * surrogate pair. Surrogate pairs encode to 4 bytes (U+10000-U+10FFFF).
+ */
+function utf8ByteLength(code: number, nextCode: number): number {
+  if (code >= 0xd800 && code <= 0xdbff && nextCode >= 0xdc00 && nextCode <= 0xdfff) {
+    return 4;
+  }
+  if (code < 0x80) return 1;
+  if (code < 0x800) return 2;
+  return 3;
+}
+
+/** True if this code unit is the high half of a surrogate pair. */
+function isHighSurrogate(code: number, nextCode: number): boolean {
+  return code >= 0xd800 && code <= 0xdbff && nextCode >= 0xdc00 && nextCode <= 0xdfff;
+}
+
+/**
+ * Build a line-offset map from file content (as a UTF-8 string or Buffer).
+ * Records UTF-8 BYTE offsets — not UTF-16 string indices — because
+ * Content-Length and the store's span_start/span_end count bytes.
+ * Handles `\n`, `\r\n`, and `\r` line endings.
+ */
+export function buildLineOffsetMap(content: string | Buffer): LineOffsetMap {
+  const text = typeof content === "string" ? content : content.toString("utf8");
+  const lineStarts = [0];
+  let byteOffset = 0;
+
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    const nextCode = i + 1 < text.length ? text.charCodeAt(i + 1) : 0;
+
+    if (code === 0x0d && nextCode === 0x0a) {
+      // \r\n — 2 bytes, advance past \n.
+      byteOffset += 2;
+      lineStarts.push(byteOffset);
+      i++;
+    } else if (code === 0x0a || code === 0x0d) {
+      byteOffset += 1;
+      lineStarts.push(byteOffset);
+    } else {
+      byteOffset += utf8ByteLength(code, nextCode);
+      if (isHighSurrogate(code, nextCode)) i++;
+    }
+  }
+  return { lineStarts };
+}
+
+/**
+ * Convert a UTF-8 byte offset to an LSP position {line, character}.
+ * `character` is a UTF-16 code-unit count from the line start (surrogates
+ * count as 2, matching LSP §3.17).
+ */
+export function byteOffsetToPosition(
+  content: string,
+  byteOffset: number,
+  map: LineOffsetMap,
+): { line: number; character: number } {
+  const lineIdx = binarySearchLine(map.lineStarts, byteOffset);
+  const lineByteStart = map.lineStarts[lineIdx];
+
+  // Find the string index where the line starts (byte offset == lineByteStart).
+  let strIdx = 0;
+  let byteAccum = 0;
+  for (strIdx = 0; strIdx < content.length; strIdx++) {
+    if (byteAccum >= lineByteStart) break;
+    const code = content.charCodeAt(strIdx);
+    const nextCode = strIdx + 1 < content.length ? content.charCodeAt(strIdx + 1) : 0;
+    byteAccum += utf8ByteLength(code, nextCode);
+    if (isHighSurrogate(code, nextCode)) strIdx++;
+  }
+
+  // Walk from the line start to byteOffset, counting UTF-16 code units.
+  let charCount = 0;
+  let currentByte = lineByteStart;
+  for (let i = strIdx; i < content.length; i++) {
+    if (currentByte >= byteOffset) break;
+    const code = content.charCodeAt(i);
+    const nextCode = i + 1 < content.length ? content.charCodeAt(i + 1) : 0;
+    currentByte += utf8ByteLength(code, nextCode);
+    if (isHighSurrogate(code, nextCode)) {
+      charCount += 2;
+      i++;
+    } else {
+      charCount++;
+    }
+  }
+
+  return { line: lineIdx, character: charCount };
+}
+
+/**
+ * Convert an LSP position {line, character} to a UTF-8 byte offset.
+ * `character` is a UTF-16 code-unit count from the line start.
+ */
+export function positionToByteOffset(
+  content: string,
+  position: { line: number; character: number },
+  map: LineOffsetMap,
+): number {
+  const lineIdx = Math.min(position.line, map.lineStarts.length - 1);
+  const lineByteStart = map.lineStarts[lineIdx];
+
+  // Find the string index where the line starts (byte offset == lineByteStart).
+  let strIdx = 0;
+  let byteAccum = 0;
+  for (strIdx = 0; strIdx < content.length; strIdx++) {
+    if (byteAccum >= lineByteStart) break;
+    const code = content.charCodeAt(strIdx);
+    const nextCode = strIdx + 1 < content.length ? content.charCodeAt(strIdx + 1) : 0;
+    byteAccum += utf8ByteLength(code, nextCode);
+    if (isHighSurrogate(code, nextCode)) strIdx++;
+  }
+
+  // Walk from the line start, counting UTF-16 code units until position.character.
+  let charCount = 0;
+  let byteOffset = lineByteStart;
+  for (let i = strIdx; i < content.length && charCount < position.character; i++) {
+    const code = content.charCodeAt(i);
+    const nextCode = i + 1 < content.length ? content.charCodeAt(i + 1) : 0;
+    byteOffset += utf8ByteLength(code, nextCode);
+    if (isHighSurrogate(code, nextCode)) {
+      charCount += 2;
+      i++;
+    } else {
+      charCount++;
+    }
+  }
+
+  return byteOffset;
+}
+
+/**
+ * Binary search for the last lineStart that is <= byteOffset.
+ * Returns the line index (0-based).
+ */
+function binarySearchLine(lineStarts: readonly number[], byteOffset: number): number {
+  let lo = 0;
+  let hi = lineStarts.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (lineStarts[mid] <= byteOffset) {
+      lo = mid;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return lo;
+}