llmnav 0.5.1

package/src/agents.js

@@ -0,0 +1,127 @@
+/* llmnav/1 module
+id=llmnav.agent.install
+role=Install one managed navigation protocol into instruction files used by major coding agents.
+owns=agent instruction adapters|managed instruction blocks
+excludes=postinstall mutation|agent execution
+search=agent instructions|AGENTS.md integration|coding assistant setup
+rel=workflow>llmnav.search.query
+stability=architecture
+*/
+
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { assertNoSymlinkTraversal, atomicWrite, readText } from "./util.js";
+
+const START = "<!-- llmnav:start -->";
+const END = "<!-- llmnav:end -->";
+
+export const AGENT_PROTOCOL = `## LLMNav code navigation
+
+${START}
+Before broad grep, directory scans, or opening many source files, run \`npm exec -- llmnav query "<task>" --top 5\`.
+
+Resolve the selected semantic ID with \`npm exec -- llmnav show <id>\`. Use \`npm exec -- llmnav context <id> --depth 1 --budget 2500\` when related policy, workflow, fallback, migration, or test cards are needed.
+
+When the host supports structured tools, load the provider-neutral definitions from \`npm exec -- llmnav tools --json\`. Keep the repository root bound by the host rather than accepting it from model-generated tool input.
+
+Read generated cards and signatures before opening full symbol bodies. Treat paths, line numbers, signatures, imports, and hashes as generated data rather than source-of-truth annotations.
+
+Keep an existing LLMNav ID when a symbol or file is renamed or moved. Change \`role\`, \`invariant\`, \`effect\`, \`risk\`, and semantic \`rel\` values only when behavior or contracts change.
+
+Do not add hand-maintained \`calls\`, \`imports\`, \`references\`, \`implements\`, \`exports\`, or \`overrides\` relations. Do not put paths, line numbers, commit hashes, timestamps, callers, or current signatures in LLMNav source comments.
+
+After semantic changes, run \`npm exec -- llmnav format\`, \`npm exec -- llmnav check\`, and \`npm exec -- llmnav generate\`. Use broad text search only when LLMNav returns no credible candidate.
+${END}`;
+
+export async function installAgentInstructions(root, adapters = ["agents"]) {
+  const selected = normalizeAdapters(adapters);
+  const changed = [];
+  for (const adapter of selected) {
+    if (adapter === "agents") {
+      const target = path.join(root, "AGENTS.md");
+      await assertNoSymlinkTraversal(root, target, "AGENTS.md");
+      if (await upsertMarkdown(target, "# Repository instructions", AGENT_PROTOCOL)) {
+        changed.push("AGENTS.md");
+      }
+    } else if (adapter === "claude") {
+      const target = path.join(root, "CLAUDE.md");
+      await assertNoSymlinkTraversal(root, target, "CLAUDE.md");
+      if (await upsertMarkdown(target, "# Claude Code instructions", AGENT_PROTOCOL)) {
+        changed.push("CLAUDE.md");
+      }
+    } else if (adapter === "copilot") {
+      const target = path.join(root, ".github", "copilot-instructions.md");
+      await assertNoSymlinkTraversal(root, target, ".github/copilot-instructions.md");
+      if (await upsertMarkdown(target, "# GitHub Copilot instructions", AGENT_PROTOCOL)) {
+        changed.push(".github/copilot-instructions.md");
+      }
+    } else if (adapter === "cursor") {
+      const target = path.join(root, ".cursor", "rules", "llmnav.mdc");
+      await assertNoSymlinkTraversal(root, target, ".cursor/rules/llmnav.mdc");
+      const content = `---\ndescription: Use LLMNav before broad codebase exploration\nalwaysApply: true\n---\n\n${AGENT_PROTOCOL}\n`;
+      const existing = await readText(target, "");
+      if (existing !== content) {
+        await atomicWrite(target, content);
+        changed.push(".cursor/rules/llmnav.mdc");
+      }
+    }
+  }
+
+  const canonicalPath = path.join(root, ".llmnav", "AGENT_INSTRUCTIONS.md");
+  await assertNoSymlinkTraversal(root, canonicalPath, ".llmnav/AGENT_INSTRUCTIONS.md");
+  const canonical = `# LLMNav agent protocol\n\n${AGENT_PROTOCOL}\n`;
+  if ((await readText(canonicalPath, "")) !== canonical) {
+    await atomicWrite(canonicalPath, canonical);
+    changed.push(".llmnav/AGENT_INSTRUCTIONS.md");
+  }
+  return changed;
+}
+
+function normalizeAdapters(adapters) {
+  const values = adapters
+    .flatMap((value) => String(value).split(","))
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean);
+  const allowed = new Set(["all", "none", "agents", "claude", "copilot", "cursor"]);
+  const unknown = values.filter((value) => !allowed.has(value));
+  if (unknown.length > 0) throw adapterUsageError(`Unknown agent adapter(s): ${[...new Set(unknown)].join(", ")}.`);
+  if (values.includes("all")) return ["agents", "claude", "copilot", "cursor"];
+  if (values.includes("none")) {
+    if (values.length > 1) throw adapterUsageError("Agent adapter none cannot be combined with other adapters.");
+    return [];
+  }
+  return [...new Set(values)];
+}
+
+
+function adapterUsageError(message) {
+  const error = new Error(message);
+  error.exitCode = 2;
+  return error;
+}
+
+async function upsertMarkdown(filePath, title, block) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const existing = await readText(filePath, "");
+  let next;
+  const start = existing.indexOf(START);
+  const end = existing.indexOf(END);
+  if ((start >= 0) !== (end >= 0) || (start >= 0 && end < start)) {
+    throw new Error(`${filePath} contains an incomplete LLMNav managed block.`);
+  }
+  if (start >= 0 && existing.indexOf(START, start + START.length) >= 0) {
+    throw new Error(`${filePath} contains multiple LLMNav managed blocks.`);
+  }
+  if (start >= 0 && end >= start) {
+    const before = existing.slice(0, Math.max(0, existing.lastIndexOf("## LLMNav code navigation", start)));
+    const after = existing.slice(end + END.length).replace(/^\s+/u, "");
+    next = `${before.trimEnd()}${before.trim() ? "\n\n" : ""}${block}\n${after ? `\n${after.trimStart()}` : ""}`;
+  } else if (!existing.trim()) {
+    next = `${title}\n\n${block}\n`;
+  } else {
+    next = `${existing.trimEnd()}\n\n${block}\n`;
+  }
+  if (next === existing) return false;
+  await atomicWrite(filePath, next);
+  return true;
+}

package/src/boundaries.js

@@ -0,0 +1,50 @@
+/* llmnav/1 module
+id=llmnav.structure.boundaries
+role=Detect route, event, schema, migration, and command boundaries from generated local evidence.
+owns=boundary kinds|confidence assignment|boundary evidence
+excludes=framework execution|source annotations
+search=boundary detection|route schema migration|command event
+rel=workflow>llmnav.index.generate
+stability=architecture
+*/
+
+import path from "node:path";
+import { compareText, toPosix } from "./util.js";
+
+export const BOUNDARY_KINDS = Object.freeze(["command", "event", "migration", "route", "schema"]);
+
+export function detectBoundaries(record) {
+  const relativePath = toPosix(record.relativePath).toLowerCase();
+  const basename = path.posix.basename(relativePath);
+  const effects = record.card.effect ?? [];
+  const risks = record.card.risk ?? [];
+  const boundaries = new Map();
+  const add = (kind, confidence, evidence) => {
+    const current = boundaries.get(kind);
+    const evidences = new Set([...(current?.evidence ?? []), evidence]);
+    boundaries.set(kind, {
+      kind,
+      confidence: current?.confidence === "high" || confidence === "high" ? "high" : "medium",
+      evidence: [...evidences].sort(compareText),
+    });
+  };
+
+  if (/(?:^|\/)(?:routes?|api)(?:\/|$)/u.test(relativePath) || /(?:^|\/)route\.[^.]+$/u.test(relativePath)) {
+    add("route", "high", "path");
+  }
+  if (effects.some((effect) => /^event\.(?:emit|consume)\(/u.test(effect))) add("event", "high", "effect");
+  else if (/(?:^|\/)(?:events?|consumers?)(?:\/|$)/u.test(relativePath)) add("event", "medium", "path");
+
+  if (/(?:^|\/)(?:schemas?|contracts?)(?:\/|$)/u.test(relativePath) ||
+      /(?:schema\.(?:json|ya?ml)|\.(?:proto|graphql|gql))$/u.test(relativePath)) {
+    add("schema", "high", "path");
+  }
+  if (risks.includes("migration") || /(?:^|\/)(?:migrations?|migrate)(?:\/|$)/u.test(relativePath)) {
+    add("migration", "high", risks.includes("migration") ? "risk" : "path");
+  }
+  if (/(?:^|\/)(?:commands?|cli|bin)(?:\/|$)/u.test(relativePath) || /(?:command|cmd)\.[^.]+$/u.test(basename)) {
+    add("command", "high", "path");
+  }
+
+  return [...boundaries.values()].sort((left, right) => compareText(left.kind, right.kind));
+}

package/src/changes.js

@@ -0,0 +1,168 @@
+/* llmnav/1 module
+id=llmnav.index.changes
+role=Describe changed cards, affected boundaries, and generated catalogs as stable machine-readable records.
+owns=card diff|boundary impact report|catalog impact report|change ordering
+excludes=source mutation|cache commit
+search=changed cards|affected boundary|affected catalog|generation report
+rel=workflow>llmnav.index.generate
+stability=architecture
+*/
+
+import { compareText, toPosix } from "./util.js";
+
+const HASH_DIMENSIONS = Object.freeze(["semantic", "structure", "body"]);
+
+export function compareCardIndexes(previousIndex, currentIndex) {
+  const previous = new Map((previousIndex?.cards ?? []).map((card) => [card.id, card]));
+  const current = new Map((currentIndex?.cards ?? []).map((card) => [card.id, card]));
+  const ids = [...new Set([...previous.keys(), ...current.keys()])].sort(compareText);
+  const changes = [];
+
+  for (const id of ids) {
+    const before = previous.get(id);
+    const after = current.get(id);
+    if (!before) {
+      changes.push({
+        id,
+        change: "added",
+        dimensions: [...HASH_DIMENSIONS],
+        previous: null,
+        current: cardSnapshot(after),
+      });
+      continue;
+    }
+    if (!after) {
+      changes.push({
+        id,
+        change: "removed",
+        dimensions: [...HASH_DIMENSIONS],
+        previous: cardSnapshot(before),
+        current: null,
+      });
+      continue;
+    }
+    const dimensions = HASH_DIMENSIONS.filter((dimension) => before.hashes?.[dimension] !== after.hashes?.[dimension]);
+    if (dimensions.length === 0) continue;
+    changes.push({
+      id,
+      change: "modified",
+      dimensions,
+      previous: cardSnapshot(before),
+      current: cardSnapshot(after),
+    });
+  }
+  return changes;
+}
+
+export function describeAffectedCatalogs(changedFiles, cacheDirectory, config, previousIndex, currentIndex) {
+  const cacheRoot = toPosix(cacheDirectory).replace(/\/+$/u, "");
+  const known = new Map([
+    [`${cacheRoot}/repo-core.txt`, { kind: "repository", id: "repository" }],
+    [`${cacheRoot}/agent-context.md`, { kind: "agent-context", id: "agent-context" }],
+    [`${cacheRoot}/prompt-prefix.json`, { kind: "prompt-prefix", id: "prompt-prefix" }],
+  ]);
+  for (const index of [previousIndex, currentIndex]) {
+    for (const module of buildModuleCatalogMetadata(index?.cards ?? [], config)) {
+      known.set(module.file, { kind: "module", id: module.id });
+    }
+  }
+
+  return [...new Set(changedFiles.map(toPosix))]
+    .filter((file) => known.has(file))
+    .sort(compareText)
+    .map((file) => ({ file, ...known.get(file) }));
+}
+
+export function describeAffectedBoundaries(changedCards, config, previousIndex, currentIndex) {
+  const previous = new Map((previousIndex?.cards ?? []).map((card) => [card.id, card]));
+  const current = new Map((currentIndex?.cards ?? []).map((card) => [card.id, card]));
+  const allCards = [...previous.values(), ...current.values()];
+
+  return changedCards.map((change) => {
+    const before = previous.get(change.id);
+    const after = current.get(change.id);
+    const selected = after ?? before;
+    const boundaryRecords = new Map();
+    for (const card of [before, after]) {
+      for (const boundary of card?.boundaries ?? []) {
+        const key = `${boundary.kind}:${boundary.confidence}:${(boundary.evidence ?? []).join(",")}`;
+        boundaryRecords.set(key, boundary);
+      }
+    }
+    const relatedIds = relationTargets(before, after);
+    const dependentIds = [...new Set(
+      allCards
+        .filter((card) => (card.rel ?? []).some((relation) => relationTarget(relation) === change.id))
+        .map((card) => card.id),
+    )].sort(compareText);
+
+    return {
+      id: change.id,
+      change: change.change,
+      dimensions: [...change.dimensions],
+      modules: selected?.id ? [moduleIdForCard(selected.id, config.generation.moduleDepth)] : [],
+      boundaries: [...boundaryRecords.values()].sort((left, right) => compareText(left.kind, right.kind)),
+      relatedIds,
+      dependentIds,
+    };
+  });
+}
+
+export function buildModuleCatalogMetadata(cards, config) {
+  const groups = new Map();
+  for (const card of cards) {
+    if (!config.generation.moduleCatalogStabilities.includes(card.stability)) continue;
+    const id = moduleIdForCard(card.id, config.generation.moduleDepth);
+    const count = groups.get(id) ?? 0;
+    groups.set(id, count + 1);
+  }
+  const cacheRoot = toPosix(config.generation.cacheDirectory).replace(/\/+$/u, "");
+  return [...groups.entries()]
+    .sort(([left], [right]) => compareText(left, right))
+    .map(([id, cardsCount]) => ({
+      id,
+      file: `${cacheRoot}/modules/${safeModuleName(id)}.txt`,
+      cards: cardsCount,
+    }));
+}
+
+export function moduleIdForCard(id, depth) {
+  const segments = String(id).split(".");
+  return segments.slice(0, Math.min(Math.max(depth, 1), segments.length)).join(".");
+}
+
+export function safeModuleName(id) {
+  return String(id).replace(/[^a-z0-9.-]/gu, "-");
+}
+
+function cardSnapshot(card) {
+  return {
+    stability: card?.stability ?? null,
+    module: card?.id ? card.id.split(".").slice(0, 2).join(".") : null,
+    location: card?.location
+      ? {
+          path: card.location.path,
+          symbol: card.location.symbol ?? null,
+          declarationLine: card.location.declarationLine ?? null,
+        }
+      : null,
+    hashes: card?.hashes
+      ? {
+          semantic: card.hashes.semantic,
+          structure: card.hashes.structure,
+          body: card.hashes.body,
+        }
+      : null,
+  };
+}
+
+function relationTargets(...cards) {
+  return [...new Set(
+    cards.flatMap((card) => (card?.rel ?? []).map(relationTarget).filter(Boolean)),
+  )].sort(compareText);
+}
+
+function relationTarget(relation) {
+  const separator = String(relation).indexOf(">");
+  return separator >= 0 ? String(relation).slice(separator + 1) : null;
+}