llmnav 0.5.1

package/src/graph-input.js

@@ -0,0 +1,157 @@
+/* llmnav/1 module
+id=llmnav.graph.import
+role=Load and validate optional generated definition and reference indexes without executing repository code.
+owns=graph import schema|input normalization|graph input diagnostics
+excludes=graph ranking|source mutation
+search=definition index import|reference index import|graph input validation
+rel=workflow>llmnav.index.generate
+stability=architecture
+*/
+
+import path from "node:path";
+import { ID_PATTERN, CROSS_REPO_ID_PATTERN } from "./spec.js";
+import { assertNoSymlinkTraversal, compareText, readText, sha256, toPosix } from "./util.js";
+import { diagnostic } from "./validator.js";
+
+export const GRAPH_INPUT_SCHEMA_VERSION = 1;
+
+export async function loadGraphInputs(root, config) {
+  const indexes = [];
+  const diagnostics = [];
+  for (const relativePath of [...config.graph.indexFiles].sort(compareText)) {
+    const file = toPosix(relativePath);
+    const absolutePath = path.join(root, file);
+    try {
+      await assertNoSymlinkTraversal(root, absolutePath, file);
+      const text = await readText(absolutePath, null);
+      if (text === null) throw new Error("file does not exist");
+      const parsed = JSON.parse(text);
+      indexes.push(normalizeGraphInput(parsed, file, sha256(text)));
+    } catch (error) {
+      diagnostics.push(
+        diagnostic(
+          "error",
+          "LNV014",
+          `Invalid graph index: ${error instanceof Error ? error.message : String(error)}`,
+          file,
+          1,
+        ),
+      );
+    }
+  }
+  return { indexes, diagnostics };
+}
+
+export function normalizeGraphInput(value, file = "<graph-index>", contentHash = null) {
+  assertObject(value, "graph index");
+  assertKeys(value, new Set(["schemaVersion", "repositoryId", "generator", "definitions", "references"]), "graph index");
+  if (value.schemaVersion !== GRAPH_INPUT_SCHEMA_VERSION) throw new Error("schemaVersion must be 1");
+  if (!/^[a-z][a-z0-9-]{0,63}$/u.test(value.repositoryId ?? "")) {
+    throw new Error("repositoryId must match ^[a-z][a-z0-9-]{0,63}$");
+  }
+  if (value.generator !== undefined && (typeof value.generator !== "string" || !value.generator.trim())) {
+    throw new Error("generator must be a non-empty string when present");
+  }
+  if (!Array.isArray(value.definitions)) throw new Error("definitions must be an array");
+  if (!Array.isArray(value.references)) throw new Error("references must be an array");
+
+  const definitions = value.definitions.map((item, index) => normalizeDefinition(item, index, value.repositoryId));
+  const definitionIds = new Set();
+  for (const definition of definitions) {
+    if (definitionIds.has(definition.id)) throw new Error(`definitions contains duplicate ID ${definition.id}`);
+    definitionIds.add(definition.id);
+  }
+  const references = value.references.map((item, index) => normalizeReference(item, index, value.repositoryId));
+  definitions.sort((left, right) => compareText(left.id, right.id));
+  references.sort(compareReferences);
+
+  return {
+    file: toPosix(file),
+    contentHash,
+    schemaVersion: GRAPH_INPUT_SCHEMA_VERSION,
+    repositoryId: value.repositoryId,
+    generator: value.generator?.trim() ?? null,
+    definitions,
+    references,
+  };
+}
+
+function normalizeDefinition(value, index, repositoryId) {
+  const name = `definitions[${index}]`;
+  assertObject(value, name);
+  assertKeys(value, new Set(["id", "symbol", "path", "line", "kind"]), name);
+  const id = normalizeSemanticKey(value.id, repositoryId, `${name}.id`);
+  if (typeof value.symbol !== "string" || !value.symbol.trim()) throw new Error(`${name}.symbol must be a non-empty string`);
+  const normalizedPath = normalizeSourcePath(value.path, `${name}.path`);
+  if (value.line !== undefined && (!Number.isInteger(value.line) || value.line < 1)) {
+    throw new Error(`${name}.line must be a positive integer when present`);
+  }
+  if (value.kind !== undefined && (typeof value.kind !== "string" || !value.kind.trim())) {
+    throw new Error(`${name}.kind must be a non-empty string when present`);
+  }
+  return {
+    id,
+    symbol: value.symbol.trim(),
+    path: normalizedPath,
+    line: value.line ?? null,
+    kind: value.kind?.trim() ?? null,
+  };
+}
+
+function normalizeReference(value, index, repositoryId) {
+  const name = `references[${index}]`;
+  assertObject(value, name);
+  assertKeys(value, new Set(["from", "to", "kind", "path", "line", "confidence"]), name);
+  const from = normalizeSemanticKey(value.from, repositoryId, `${name}.from`);
+  const to = normalizeSemanticKey(value.to, repositoryId, `${name}.to`);
+  if (typeof value.kind !== "string" || !/^[a-z][a-z0-9-]*$/u.test(value.kind)) {
+    throw new Error(`${name}.kind must be a controlled lower-case identifier`);
+  }
+  const normalizedPath = value.path === undefined ? null : normalizeSourcePath(value.path, `${name}.path`);
+  if (value.line !== undefined && (!Number.isInteger(value.line) || value.line < 1)) {
+    throw new Error(`${name}.line must be a positive integer when present`);
+  }
+  const confidence = value.confidence ?? 0.8;
+  if (typeof confidence !== "number" || !Number.isFinite(confidence) || confidence < 0 || confidence > 1) {
+    throw new Error(`${name}.confidence must be a number from 0 to 1`);
+  }
+  return {
+    from,
+    to,
+    kind: value.kind,
+    path: normalizedPath,
+    line: value.line ?? null,
+    confidence,
+  };
+}
+
+function normalizeSemanticKey(value, repositoryId, name) {
+  if (typeof value !== "string") throw new Error(`${name} must be a semantic ID`);
+  const normalized = value.trim();
+  if (ID_PATTERN.test(normalized)) return `${repositoryId}/${normalized}`;
+  if (CROSS_REPO_ID_PATTERN.test(normalized)) return normalized;
+  throw new Error(`${name} must be a local or repository-qualified semantic ID`);
+}
+
+function normalizeSourcePath(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${name} must be a non-empty relative path`);
+  if (value.includes("\\") || /^(?:[A-Za-z]:|\/|~\/)/u.test(value) || value.split("/").includes("..") || /\p{Cc}/u.test(value)) {
+    throw new Error(`${name} must be a safe forward-slash relative path`);
+  }
+  return toPosix(value);
+}
+
+function assertObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} must be an object`);
+}
+
+function assertKeys(value, allowed, name) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new Error(`${name} contains unknown property ${JSON.stringify(key)}`);
+  }
+}
+
+function compareReferences(left, right) {
+  return compareText(left.from, right.from) || compareText(left.to, right.to) || compareText(left.kind, right.kind) ||
+    compareText(left.path ?? "", right.path ?? "") || (left.line ?? 0) - (right.line ?? 0);
+}

package/src/graph.js

@@ -0,0 +1,403 @@
+/* llmnav/1 module
+id=llmnav.graph.generate
+role=Build deterministic repository graphs with content-addressed partitions and resolve qualified IDs across workspace nodes.
+owns=graph schema|edge normalization|local import resolution|workspace ID resolution|graph partition invalidation
+excludes=query scoring|workspace file discovery
+search=repository graph|cross repository ID|workspace resolution|edge provenance|graph confidence|incremental graph cache
+rel=workflow>llmnav.graph.import
+rel=workflow>llmnav.index.generate
+stability=architecture
+*/
+
+import path from "node:path";
+import { compareText, sha256, stableJson, stableStringify, toPosix } from "./util.js";
+
+export const GRAPH_SCHEMA_VERSION = 1;
+export const GRAPH_STATE_SCHEMA_VERSION = 1;
+const IMPORT_EXTENSIONS = Object.freeze([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".go", ".rs", ".py"]);
+
+export function buildRepositoryGraph(project, index) {
+  return buildRepositoryGraphIncremental(project, index).graph;
+}
+
+export function buildRepositoryGraphIncremental(project, index, previousState = null) {
+  const repositoryId = index.repositoryId;
+  const cardsByPath = groupCardsByPath(index.cards);
+  const resolutionHash = sha256(stableJson(
+    [...cardsByPath.entries()]
+      .sort(([left], [right]) => compareText(left, right))
+      .map(([file, cards]) => [file, cards.map((card) => card.id).sort(compareText)]),
+  ));
+  const previousPartitions = compatibleGraphState(previousState, repositoryId)
+    ? new Map(previousState.partitions.map((partition) => [partition.key, partition]))
+    : new Map();
+  const partitions = [];
+  let reusedPartitions = 0;
+  let rebuiltPartitions = 0;
+
+  for (const card of index.cards) {
+    const key = `card:${qualifyId(card.id, repositoryId)}`;
+    const inputHash = sha256(stableJson({
+      resolutionHash,
+      id: card.id,
+      role: card.role,
+      rel: card.rel ?? [],
+      imports: card.imports ?? [],
+      location: card.location,
+    }));
+    const previous = previousPartitions.get(key);
+    if (previous?.inputHash === inputHash) {
+      partitions.push(previous);
+      reusedPartitions += 1;
+    } else {
+      partitions.push(buildCardPartition(key, inputHash, card, repositoryId, cardsByPath));
+      rebuiltPartitions += 1;
+    }
+  }
+
+  for (const imported of project.graphInputs ?? []) {
+    const key = `input:${toPosix(imported.file)}`;
+    const inputHash = imported.contentHash || sha256(stableJson(imported));
+    const previous = previousPartitions.get(key);
+    if (previous?.inputHash === inputHash) {
+      partitions.push(previous);
+      reusedPartitions += 1;
+    } else {
+      partitions.push(buildImportedPartition(key, inputHash, imported, repositoryId));
+      rebuiltPartitions += 1;
+    }
+  }
+
+  partitions.sort((left, right) => compareText(left.key, right.key));
+  const nodes = new Map();
+  const edges = new Map();
+  for (const partition of partitions) {
+    for (const node of partition.nodes) mergeNode(nodes, node.key, node, repositoryId);
+    for (const edge of partition.edges) addEdge(edges, nodes, edge, repositoryId);
+  }
+
+  const serializedNodes = [...nodes.values()].map(finalizeNode).sort((left, right) => compareText(left.key, right.key));
+  const serializedEdges = [...edges.values()].sort(compareEdges);
+  const sourceHash = sha256(stableJson({ nodes: serializedNodes, edges: serializedEdges }));
+  const graph = {
+    schemaVersion: GRAPH_SCHEMA_VERSION,
+    repositoryId,
+    sourceHash,
+    nodes: serializedNodes,
+    edges: serializedEdges,
+    stats: {
+      nodeCount: serializedNodes.length,
+      edgeCount: serializedEdges.length,
+      unresolvedNodeCount: serializedNodes.filter((node) => node.unresolved).length,
+      importedIndexCount: project.graphInputs?.length ?? 0,
+    },
+  };
+  const state = {
+    schemaVersion: GRAPH_STATE_SCHEMA_VERSION,
+    repositoryId,
+    resolutionHash,
+    partitions,
+  };
+  return {
+    graph,
+    state,
+    stats: {
+      totalPartitions: partitions.length,
+      reusedPartitions,
+      rebuiltPartitions,
+      removedPartitions: [...previousPartitions.keys()].filter((key) => !partitions.some((item) => item.key === key)).length,
+    },
+  };
+}
+
+export function renderRepositoryGraph(graph) {
+  return stableStringify(graph);
+}
+
+export function renderGraphState(state) {
+  return stableStringify(state);
+}
+
+export function compatibleGraphState(state, repositoryId = undefined) {
+  const structurallyValid = Boolean(
+    state &&
+      state.schemaVersion === GRAPH_STATE_SCHEMA_VERSION &&
+      typeof state.repositoryId === "string" &&
+      typeof state.resolutionHash === "string" &&
+      Array.isArray(state.partitions) &&
+      state.partitions.every((partition) =>
+        partition &&
+        typeof partition.key === "string" &&
+        typeof partition.inputHash === "string" &&
+        typeof partition.outputHash === "string" &&
+        Array.isArray(partition.nodes) &&
+        Array.isArray(partition.edges) &&
+        partition.nodes.every((node) => node && typeof node.key === "string" && Array.isArray(node.definitions)) &&
+        partition.edges.every(isReusableEdge) &&
+        partition.outputHash === sha256(stableJson({ nodes: partition.nodes, edges: partition.edges }))
+      ) &&
+      (repositoryId === undefined || state.repositoryId === repositoryId),
+  );
+  if (!structurallyValid) return false;
+  return new Set(state.partitions.map((partition) => partition.key)).size === state.partitions.length;
+}
+
+export function isCompatibleRepositoryGraph(graph, repositoryId = undefined) {
+  return Boolean(
+    graph &&
+      graph.schemaVersion === GRAPH_SCHEMA_VERSION &&
+      typeof graph.repositoryId === "string" &&
+      typeof graph.sourceHash === "string" &&
+      Array.isArray(graph.nodes) &&
+      Array.isArray(graph.edges) &&
+      graph.edges.every((edge) =>
+        edge &&
+        typeof edge.id === "string" &&
+        typeof edge.from === "string" &&
+        typeof edge.to === "string" &&
+        typeof edge.kind === "string" &&
+        typeof edge.confidence === "number" &&
+        edge.confidence >= 0 &&
+        edge.confidence <= 1 &&
+        edge.provenance &&
+        typeof edge.provenance.type === "string"
+      ) &&
+      (repositoryId === undefined || graph.repositoryId === repositoryId),
+  );
+}
+
+export function resolveGraphNode(graph, id, localRepositoryId = graph?.repositoryId) {
+  if (!isCompatibleRepositoryGraph(graph)) return { state: "missing", id, candidates: [], node: null };
+  const value = String(id).trim();
+  const byKey = new Map(graph.nodes.map((node) => [node.key, node]));
+  if (value.includes("/")) {
+    const node = byKey.get(value) ?? null;
+    return node
+      ? { state: "resolved", id: value, candidates: [value], node }
+      : { state: "missing", id: value, candidates: [], node: null };
+  }
+  const localKey = `${localRepositoryId}/${value}`;
+  if (byKey.has(localKey)) return { state: "resolved", id: localKey, candidates: [localKey], node: byKey.get(localKey) };
+  const candidates = graph.nodes.filter((node) => node.semanticId === value).map((node) => node.key).sort(compareText);
+  if (candidates.length === 1) return { state: "resolved", id: candidates[0], candidates, node: byKey.get(candidates[0]) };
+  if (candidates.length > 1) return { state: "ambiguous", id: value, candidates, node: null };
+  return { state: "missing", id: value, candidates: [], node: null };
+}
+
+export function renderGraphNode(node) {
+  const lines = [`@${node.key}`];
+  if (node.role) lines.push(`role ${node.role}`);
+  if (node.external) lines.push("external true");
+  if (node.unresolved) lines.push("unresolved true");
+  for (const definition of node.definitions ?? []) {
+    const location = `${definition.path}${definition.line ? `:${definition.line}` : ""}`;
+    lines.push(`def ${definition.symbol} ${location}${definition.kind ? ` kind=${definition.kind}` : ""}`);
+  }
+  return lines.join("\n");
+}
+
+function buildCardPartition(partitionKey, inputHash, card, repositoryId, cardsByPath) {
+  const nodes = new Map();
+  const edges = new Map();
+  const key = qualifyId(card.id, repositoryId);
+  mergeNode(nodes, key, {
+    role: card.role,
+    location: card.location,
+    definitions: card.location?.symbol ? [{
+      symbol: card.location.symbol,
+      path: card.location.path,
+      line: card.location.declarationLine,
+      kind: card.location.kind,
+      provenance: { type: "llmnav-index", source: ".llmnav/cache/index.json", generator: null },
+    }] : [],
+  }, repositoryId);
+
+  for (const relation of card.rel ?? []) {
+    const separator = relation.indexOf(">");
+    if (separator <= 0) continue;
+    addEdge(edges, nodes, {
+      from: key,
+      to: qualifyId(relation.slice(separator + 1), repositoryId),
+      kind: relation.slice(0, separator),
+      confidence: 1,
+      provenance: {
+        type: "source-card",
+        source: card.location.path,
+        path: card.location.path,
+        line: card.location.startLine,
+        generator: null,
+      },
+    }, repositoryId);
+  }
+
+  for (const specifier of card.imports ?? []) {
+    for (const target of resolveLocalImport(card.location.path, specifier, cardsByPath)) {
+      addEdge(edges, nodes, {
+        from: key,
+        to: qualifyId(target.id, repositoryId),
+        kind: "imports",
+        confidence: 0.85,
+        provenance: {
+          type: "local-import",
+          source: card.location.path,
+          path: card.location.path,
+          line: card.location.declarationLine,
+          generator: "llmnav",
+        },
+      }, repositoryId);
+    }
+  }
+  return serializePartition(partitionKey, inputHash, nodes, edges);
+}
+
+function buildImportedPartition(partitionKey, inputHash, imported, repositoryId) {
+  const nodes = new Map();
+  const edges = new Map();
+  for (const definition of imported.definitions) {
+    mergeNode(nodes, definition.id, {
+      definitions: [{
+        symbol: definition.symbol,
+        path: definition.path,
+        line: definition.line,
+        kind: definition.kind,
+        provenance: {
+          type: "generated-index",
+          source: imported.file,
+          generator: imported.generator,
+        },
+      }],
+    }, repositoryId);
+  }
+  for (const reference of imported.references) {
+    addEdge(edges, nodes, {
+      from: reference.from,
+      to: reference.to,
+      kind: reference.kind,
+      confidence: reference.confidence,
+      provenance: {
+        type: "generated-index",
+        source: imported.file,
+        path: reference.path,
+        line: reference.line,
+        generator: imported.generator,
+      },
+    }, repositoryId);
+  }
+  return serializePartition(partitionKey, inputHash, nodes, edges);
+}
+
+function serializePartition(key, inputHash, nodes, edges) {
+  const serializedNodes = [...nodes.values()].sort((left, right) => compareText(left.key, right.key));
+  const serializedEdges = [...edges.values()].sort(compareEdges);
+  return {
+    key,
+    inputHash,
+    outputHash: sha256(stableJson({ nodes: serializedNodes, edges: serializedEdges })),
+    nodes: serializedNodes,
+    edges: serializedEdges,
+  };
+}
+
+function isReusableEdge(edge) {
+  return Boolean(
+    edge &&
+      typeof edge.from === "string" &&
+      typeof edge.to === "string" &&
+      typeof edge.kind === "string" &&
+      typeof edge.confidence === "number" &&
+      edge.confidence >= 0 &&
+      edge.confidence <= 1 &&
+      edge.provenance &&
+      typeof edge.provenance.type === "string" &&
+      typeof edge.provenance.source === "string",
+  );
+}
+
+function addEdge(edges, nodes, edge, localRepositoryId) {
+  mergeNode(nodes, edge.from, {}, localRepositoryId);
+  mergeNode(nodes, edge.to, {}, localRepositoryId);
+  const normalized = {
+    from: edge.from,
+    to: edge.to,
+    kind: edge.kind,
+    confidence: Number(edge.confidence),
+    provenance: {
+      type: edge.provenance.type,
+      source: toPosix(edge.provenance.source),
+      path: edge.provenance.path ? toPosix(edge.provenance.path) : null,
+      line: edge.provenance.line ?? null,
+      generator: edge.provenance.generator ?? null,
+    },
+  };
+  const identity = stableJson(normalized);
+  if (edges.has(identity)) return;
+  edges.set(identity, { id: sha256(identity), ...normalized });
+}
+
+function mergeNode(nodes, key, input, localRepositoryId) {
+  const separator = key.indexOf("/");
+  const repositoryId = separator >= 0 ? key.slice(0, separator) : localRepositoryId;
+  const semanticId = separator >= 0 ? key.slice(separator + 1) : key;
+  const current = nodes.get(key) ?? {
+    key,
+    repositoryId,
+    semanticId,
+    role: null,
+    location: null,
+    definitions: [],
+    external: repositoryId !== localRepositoryId,
+  };
+  if (input.role) current.role = input.role;
+  if (input.location) current.location = input.location;
+  current.definitions.push(...(input.definitions ?? []));
+  nodes.set(key, current);
+}
+
+function finalizeNode(node) {
+  const definitions = [...new Map(node.definitions.map((definition) => [stableJson(definition), definition])).values()]
+    .sort((left, right) => compareText(left.path, right.path) || (left.line ?? 0) - (right.line ?? 0) || compareText(left.symbol, right.symbol));
+  return {
+    ...node,
+    unresolved: !node.role && definitions.length === 0,
+    definitions,
+  };
+}
+
+function qualifyId(id, repositoryId) {
+  return String(id).includes("/") ? String(id) : `${repositoryId}/${id}`;
+}
+
+function groupCardsByPath(cards) {
+  const output = new Map();
+  for (const card of cards) {
+    const file = toPosix(card.location.path);
+    const records = output.get(file) ?? [];
+    records.push(card);
+    output.set(file, records);
+  }
+  return output;
+}
+
+function resolveLocalImport(sourcePath, specifier, cardsByPath) {
+  if (!specifier.startsWith(".")) return [];
+  const base = path.posix.normalize(path.posix.join(path.posix.dirname(toPosix(sourcePath)), specifier));
+  if (base.startsWith("../")) return [];
+  const candidates = new Set([base]);
+  const extension = path.posix.extname(base);
+  if (!extension) {
+    for (const item of IMPORT_EXTENSIONS) {
+      candidates.add(`${base}${item}`);
+      candidates.add(`${base}/index${item}`);
+    }
+  } else if ([".js", ".jsx", ".mjs", ".cjs"].includes(extension)) {
+    const stem = base.slice(0, -extension.length);
+    for (const item of [".ts", ".tsx", ".mts", ".cts"]) candidates.add(`${stem}${item}`);
+  }
+  return [...candidates].flatMap((candidate) => cardsByPath.get(candidate) ?? []);
+}
+
+function compareEdges(left, right) {
+  return compareText(left.from, right.from) || compareText(left.to, right.to) || compareText(left.kind, right.kind) ||
+    compareText(left.provenance.type, right.provenance.type) || compareText(left.provenance.source, right.provenance.source) ||
+    (left.provenance.line ?? 0) - (right.provenance.line ?? 0);
+}