llmnav 0.5.1

package/src/registry.js

@@ -0,0 +1,107 @@
+import path from "node:path";
+import { ID_PATTERN } from "./spec.js";
+import { atomicWrite, parseJsonLines, readText } from "./util.js";
+
+const REGISTRY_STATES = new Set(["active", "redirect", "replaced", "retired"]);
+const REGISTRY_KEYS = new Set(["id", "state", "to", "by"]);
+
+export async function loadRegistry(root) {
+  const registryPath = path.join(root, ".llmnav", "ids.jsonl");
+  const text = await readText(registryPath, "");
+  const parsed = parseJsonLines(text, registryPath);
+  const byId = new Map();
+  const errors = [...parsed.errors];
+
+  for (const record of parsed.records) {
+    if (!record || typeof record !== "object" || Array.isArray(record)) {
+      errors.push(`${registryPath}: registry records must be JSON objects`);
+      continue;
+    }
+    for (const key of Object.keys(record)) {
+      if (!REGISTRY_KEYS.has(key)) errors.push(`${registryPath}: registry record contains unknown property ${JSON.stringify(key)}`);
+    }
+    if (typeof record.id !== "string" || !ID_PATTERN.test(record.id)) {
+      errors.push(`${registryPath}: registry records require a valid local semantic id`);
+      continue;
+    }
+    if (byId.has(record.id)) errors.push(`${registryPath}: duplicate registry id ${record.id}`);
+    byId.set(record.id, record);
+
+    if (!REGISTRY_STATES.has(record.state)) {
+      errors.push(`${registryPath}: registry id ${record.id} has invalid state ${JSON.stringify(record.state)}`);
+      continue;
+    }
+    if (record.state === "active" || record.state === "retired") {
+      if (record.to !== undefined || record.by !== undefined) {
+        errors.push(`${registryPath}: ${record.state} registry id ${record.id} must not declare to or by`);
+      }
+    } else if (record.state === "redirect") {
+      if (typeof record.to !== "string" || !ID_PATTERN.test(record.to)) {
+        errors.push(`${registryPath}: redirect registry id ${record.id} requires a valid to id`);
+      }
+      if (record.by !== undefined) errors.push(`${registryPath}: redirect registry id ${record.id} must not declare by`);
+    } else if (record.state === "replaced") {
+      if (!Array.isArray(record.by) || record.by.length === 0) {
+        errors.push(`${registryPath}: replaced registry id ${record.id} requires a non-empty by array`);
+      } else {
+        const seen = new Set();
+        for (const target of record.by) {
+          if (typeof target !== "string" || !ID_PATTERN.test(target)) {
+            errors.push(`${registryPath}: replaced registry id ${record.id} contains an invalid replacement id`);
+            continue;
+          }
+          if (seen.has(target)) errors.push(`${registryPath}: replaced registry id ${record.id} repeats replacement ${target}`);
+          seen.add(target);
+        }
+      }
+      if (record.to !== undefined) errors.push(`${registryPath}: replaced registry id ${record.id} must not declare to`);
+    }
+  }
+  return { registryPath, records: [...byId.values()], byId, errors };
+}
+
+export async function ensureActiveIds(root, registry, ids) {
+  const { records, changed } = mergeActiveIds(registry, ids);
+  if (changed) await atomicWrite(registry.registryPath, renderRegistryRecords(records));
+  return { records, changed };
+}
+
+export function mergeActiveIds(registry, ids) {
+  const records = [...registry.records];
+  const known = new Set(records.map((record) => record.id));
+  let changed = false;
+  for (const id of ids) {
+    if (known.has(id)) continue;
+    records.push({ id, state: "active" });
+    known.add(id);
+    changed = true;
+  }
+  return { records, changed };
+}
+
+export function renderRegistryRecords(records) {
+  const content = records.map((record) => JSON.stringify(record)).join("\n");
+  return content ? `${content}\n` : "";
+}
+
+export function resolveRegistryId(registry, id) {
+  return resolveRegistryPath(registry, id, []);
+}
+
+function resolveRegistryPath(registry, current, path) {
+  const cycleIndex = path.indexOf(current);
+  if (cycleIndex >= 0) return { id: current, state: "cycle", chain: [...path.slice(cycleIndex), current] };
+  const chain = [...path, current];
+  const record = registry.byId.get(current);
+  if (!record) return { id: current, state: "unknown", chain };
+  if (record.state === "active") return { id: current, state: "active", chain };
+  if (record.state === "redirect" && record.to) return resolveRegistryPath(registry, record.to, chain);
+  if (record.state === "replaced" && Array.isArray(record.by)) {
+    if (record.by.length === 1) return resolveRegistryPath(registry, record.by[0], chain);
+    const outcomes = record.by.map((target) => resolveRegistryPath(registry, target, chain));
+    const cycle = outcomes.find((outcome) => outcome.state === "cycle");
+    if (cycle) return cycle;
+    return { id: current, state: "ambiguous", chain, candidates: [...record.by] };
+  }
+  return { id: current, state: record.state ?? "unknown", chain };
+}

package/src/sarif.js

@@ -0,0 +1,70 @@
+/* llmnav/1 module
+id=llmnav.diagnostics.sarif
+role=Serialize deterministic LLMNav diagnostics as a SARIF 2.1.0 result log.
+owns=SARIF schema mapping|diagnostic rule table|artifact locations
+excludes=diagnostic discovery|file writes
+search=SARIF output|code scanning diagnostics|static analysis report
+rel=workflow>llmnav.rules.validate
+stability=contract
+*/
+
+import { compareText, toPosix } from "./util.js";
+import { PACKAGE_VERSION } from "./spec.js";
+
+export const SARIF_VERSION = "2.1.0";
+export const SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+
+export function diagnosticsToSarif(diagnostics) {
+  const sorted = [...diagnostics].sort(compareDiagnostics);
+  const rules = [...new Map(sorted.map((item) => [item.code, item])).values()]
+    .sort((left, right) => compareText(left.code, right.code))
+    .map((item) => ({
+      id: item.code,
+      name: item.code,
+      shortDescription: { text: `LLMNav diagnostic ${item.code}` },
+      defaultConfiguration: { level: sarifLevel(item.severity) },
+    }));
+
+  return {
+    $schema: SARIF_SCHEMA,
+    version: SARIF_VERSION,
+    runs: [{
+      tool: {
+        driver: {
+          name: "LLMNav",
+          semanticVersion: PACKAGE_VERSION,
+          informationUri: "https://github.com/0disoft/llmnav",
+          rules,
+        },
+      },
+      results: sorted.map((item) => ({
+        ruleId: item.code,
+        level: sarifLevel(item.severity),
+        message: { text: item.message },
+        locations: [{
+          physicalLocation: {
+            artifactLocation: { uri: toPosix(item.file).split("/").map(encodeURIComponent).join("/") },
+            region: {
+              startLine: Math.max(1, item.line),
+              startColumn: Math.max(1, item.column),
+            },
+          },
+        }],
+      })),
+    }],
+  };
+}
+
+function sarifLevel(severity) {
+  if (severity === "error") return "error";
+  if (severity === "warning") return "warning";
+  return "note";
+}
+
+function compareDiagnostics(left, right) {
+  return compareText(left.file, right.file) ||
+    left.line - right.line ||
+    left.column - right.column ||
+    compareText(left.code, right.code) ||
+    compareText(left.message, right.message);
+}

package/src/search-shards.js

@@ -0,0 +1,75 @@
+/* llmnav/1 module
+id=llmnav.index.search-shards
+role=Split a compact search index into deterministic card-range artifacts without retokenizing documents.
+owns=search shard schema|card range partitioning|shard manifest
+excludes=query ranking|source parsing
+search=search index sharding|monorepo search artifacts|card range shard
+rel=workflow>llmnav.index.inverted
+rel=workflow>llmnav.index.generate
+stability=architecture
+*/
+
+import { searchCardSetHash } from "./inverted-index.js";
+import { sha256, stableStringify } from "./util.js";
+
+export const SEARCH_SHARD_SCHEMA_VERSION = 1;
+export const SEARCH_SHARD_ENCODING = "card-range-v1";
+
+export function buildSearchShards(index, searchIndex, shardSize) {
+  if (!Number.isInteger(shardSize) || shardSize < 0) throw new Error("search shard size must be a non-negative integer");
+  if (shardSize === 0 || searchIndex.cardIds.length <= shardSize) {
+    return { manifest: null, shards: new Map() };
+  }
+
+  const cardsById = new Map(index.cards.map((card) => [card.id, card]));
+  const shards = new Map();
+  const records = [];
+  for (let start = 0, ordinal = 0; start < searchIndex.cardIds.length; start += shardSize, ordinal += 1) {
+    const end = Math.min(start + shardSize, searchIndex.cardIds.length);
+    const cardIds = searchIndex.cardIds.slice(start, end);
+    const cards = cardIds.map((id) => cardsById.get(id)).filter(Boolean);
+    const tokens = [];
+    const postings = [];
+    for (const [tokenIndex, token] of searchIndex.tokens.entries()) {
+      const selected = (searchIndex.postings[tokenIndex] ?? [])
+        .filter(([cardIndex]) => cardIndex >= start && cardIndex < end)
+        .map(([cardIndex, vector]) => [cardIndex - start, vector]);
+      if (selected.length === 0) continue;
+      tokens.push(token);
+      postings.push(selected);
+    }
+    const shard = {
+      ...searchIndex,
+      cardSetHash: searchCardSetHash(cards),
+      documentCount: cardIds.length,
+      cardIds,
+      tokens,
+      documents: searchIndex.documents.slice(start, end),
+      postings,
+    };
+    const file = `search-shards/${String(ordinal).padStart(4, "0")}.json`;
+    const content = stableStringify(shard);
+    shards.set(file, content);
+    records.push({
+      file,
+      firstId: cardIds[0],
+      lastId: cardIds.at(-1),
+      cardCount: cardIds.length,
+      cardSetHash: shard.cardSetHash,
+      sha256: sha256(content),
+    });
+  }
+
+  return {
+    manifest: {
+      schemaVersion: SEARCH_SHARD_SCHEMA_VERSION,
+      encoding: SEARCH_SHARD_ENCODING,
+      repositoryId: index.repositoryId,
+      sourceCardSetHash: searchIndex.cardSetHash,
+      shardSize,
+      shardCount: records.length,
+      shards: records,
+    },
+    shards,
+  };
+}