llmnav 0.5.1

package/examples/provider-neutral-host.mjs

@@ -0,0 +1,40 @@
+import {
+  executeAgentOperation,
+  createProjectSession,
+  getAgentToolDefinitions,
+  loadPromptPrefixBundle,
+} from "llmnav";
+
+export async function createLlmnavHost(root) {
+  let bundle = await loadPromptPrefixBundle(root);
+  let session = await createProjectSession(root);
+  const host = {
+    toolDefinitions: getAgentToolDefinitions(),
+    basePromptPartitions: selectPromptPartitions(bundle),
+    selectPromptPartitions(moduleIds = []) {
+      return selectPromptPartitions(bundle, moduleIds);
+    },
+    execute(call) {
+      return executeAgentOperation(root, call.name, call.input ?? {}, { session });
+    },
+    async refresh() {
+      [bundle, session] = await Promise.all([
+        loadPromptPrefixBundle(root),
+        createProjectSession(root),
+      ]);
+      host.basePromptPartitions = selectPromptPartitions(bundle);
+      return host;
+    },
+  };
+  return host;
+}
+
+export function selectPromptPartitions(bundle, moduleIds = []) {
+  const requested = new Set(moduleIds.map((id) => id.startsWith("module:") ? id : `module:${id}`));
+  const available = new Set(bundle.assembly.modulePartitionIds);
+  const missing = [...requested].filter((id) => !available.has(id)).sort();
+  if (missing.length > 0) throw new Error(`Unknown prompt module partition(s): ${missing.join(", ")}.`);
+  return bundle.partitions.filter((partition) =>
+    bundle.assembly.basePartitionIds.includes(partition.id) || requested.has(partition.id),
+  );
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "llmnav",
+  "version": "0.5.1",
+  "description": "A deterministic semantic navigation layer for LLM coding agents.",
+  "type": "module",
+  "bin": {
+    "llmnav": "bin/llmnav.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./spec": {
+      "types": "./src/spec.d.ts",
+      "import": "./src/spec.js"
+    },
+    "./examples/provider-neutral-host.mjs": {
+      "types": "./examples/provider-neutral-host.d.mts",
+      "import": "./examples/provider-neutral-host.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "schema",
+    "docs",
+    "examples/provider-neutral-host.mjs",
+    "examples/provider-neutral-host.d.mts",
+    "README.md",
+    "CHANGELOG.md",
+    "ROADMAP.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage",
+    "lint": "node ./scripts/lint-repo.js",
+    "check": "npm run lint && npm test && node ./bin/llmnav.js check --root . && node ./bin/llmnav.js generate --root . --full --check",
+    "pack:check": "npm pack --dry-run",
+    "release:check": "node ./scripts/release-check.js",
+    "prepublishOnly": "npm run check && npm run release:check && npm run pack:check",
+    "release:tag": "node ./scripts/verify-tag.js",
+    "test:performance": "node --test tests/performance.test.js",
+    "benchmark:v0.2": "node ./benchmarks/run-v0.2.js",
+    "smoke:pack": "node ./scripts/pack-smoke.js"
+  },
+  "keywords": [
+    "llm",
+    "coding-agent",
+    "code-navigation",
+    "semantic-search",
+    "repository-map",
+    "ai",
+    "cli",
+    "lint"
+  ],
+  "author": "제로디",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0disoft/llmnav.git"
+  },
+  "bugs": {
+    "url": "https://github.com/0disoft/llmnav/issues"
+  },
+  "homepage": "https://github.com/0disoft/llmnav#readme",
+  "sideEffects": false,
+  "types": "./src/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/schema/config.schema.json

@@ -0,0 +1,296 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://llmnav.dev/schema/config.schema.json",
+  "title": "LLMNav configuration",
+  "type": "object",
+  "required": [
+    "version",
+    "repositoryId",
+    "sourceRoots",
+    "includeExtensions"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "repositoryId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,63}$"
+    },
+    "sourceRoots": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^(?!/|[A-Za-z]:|.*(?:^|/)\\.\\.(?:/|$))(?:\\.|[^\\\\]+)$"
+      },
+      "uniqueItems": true
+    },
+    "includeExtensions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^\\."
+      },
+      "uniqueItems": true
+    },
+    "excludeDirectories": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "excludeFiles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "coverageRules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "match"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "match": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string"
+            },
+            "uniqueItems": true
+          },
+          "scope": {
+            "enum": [
+              "file",
+              "module",
+              "symbol"
+            ]
+          },
+          "requiredFields": {
+            "type": "array",
+            "items": {
+              "enum": [
+                "id",
+                "role",
+                "owns",
+                "excludes",
+                "search",
+                "invariant",
+                "effect",
+                "risk",
+                "rel",
+                "stability"
+              ]
+            },
+            "uniqueItems": true
+          }
+        }
+      }
+    },
+    "graph": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "indexFiles": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?!/|[A-Za-z]:|.*(?:^|/)\\.\\.(?:/|$))[^\\\\]+$"
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "lint": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxRoleLength": {
+          "type": "integer",
+          "minimum": 40
+        },
+        "maxSearchTerms": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "minSearchTerms": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "maxInvariants": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "maxEffects": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "maxRelations": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "maxBlockBytes": {
+          "type": "object",
+          "properties": {
+            "file": {
+              "type": "integer",
+              "minimum": 100
+            },
+            "module": {
+              "type": "integer",
+              "minimum": 100
+            },
+            "symbol": {
+              "type": "integer",
+              "minimum": 100
+            }
+          }
+        },
+        "maxSemanticRatio": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "minimumSourceBytesForRatio": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "searchTermSaturation": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "minimumCardsForSaturation": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "genericSearchTerms": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "vagueRoleWords": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "strictRisks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "additionalEffects": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9.-]*$"
+          },
+          "uniqueItems": true
+        },
+        "additionalRisks": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9.-]*$"
+          },
+          "uniqueItems": true
+        },
+        "additionalRelations": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "uniqueItems": true
+        },
+        "requireCanonicalOrder": {
+          "type": "boolean"
+        },
+        "requireCanonicalFormatting": {
+          "type": "boolean"
+        }
+      }
+    },
+    "generation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "cacheDirectory": {
+          "type": "string",
+          "pattern": "^\\.llmnav/(?!.*(?:^|/)\\.\\.(?:/|$))[^\\\\]+$"
+        },
+        "moduleDepth": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 6
+        },
+        "searchShardSize": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "repositoryCatalogStabilities": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "architecture",
+              "contract",
+              "implementation"
+            ]
+          },
+          "uniqueItems": true
+        },
+        "moduleCatalogStabilities": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "architecture",
+              "contract",
+              "implementation"
+            ]
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "evaluation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "queryFile": {
+          "type": "string",
+          "pattern": "^(?!/|[A-Za-z]:|.*(?:^|/)\\.\\.(?:/|$))[^\\\\]+$"
+        },
+        "minimumRecallAt1": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "minimumRecallAt5": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        }
+      }
+    }
+  }
+}

package/src/agent-protocol.js

@@ -0,0 +1,117 @@
+/* llmnav/1 module
+id=llmnav.agent.protocol
+role=Execute bounded repository navigation operations through one provider-neutral result envelope.
+owns=operation validation|operation dispatch|provider-neutral result envelope
+excludes=provider SDK transport|repository discovery|source mutation
+search=agent tool schema|provider neutral tools|tool dispatcher|agent operation protocol
+rel=workflow>llmnav.search.query
+rel=workflow>llmnav.rules.validate
+stability=contract
+*/
+
+import { loadGraphInputs } from "./graph-input.js";
+import { scanProject } from "./project.js";
+import { buildContext, queryProject, showProjectCard } from "./search.js";
+import { countDiagnostics, validateProject } from "./validator.js";
+import { getAgentToolDefinitions } from "./agent-tools.js";
+
+export { AGENT_TOOL_SCHEMA_VERSION, getAgentToolDefinitions } from "./agent-tools.js";
+export const AGENT_OPERATION_SCHEMA_VERSION = 1;
+
+const DEFINITIONS = getAgentToolDefinitions();
+
+const OPERATIONS = new Map([
+  ["llmnav_query", "query"],
+  ["llmnav_show", "show"],
+  ["llmnav_context", "context"],
+  ["llmnav_check", "check"],
+]);
+
+export async function executeAgentOperation(root, name, input = {}, options = {}) {
+  const canonicalName = String(name);
+  const operation = OPERATIONS.get(canonicalName);
+  if (!operation) return failure("unknown", "LNVAP001", `Unknown agent operation ${JSON.stringify(name)}.`);
+  const definition = DEFINITIONS.find((item) => item.name === canonicalName);
+  const validationError = validateInput(definition.inputSchema, input);
+  if (validationError) return failure(operation, "LNVAP002", validationError);
+
+  try {
+    if (operation === "query") {
+      return success(operation, options.session
+        ? options.session.query(input.task.trim(), { top: input.top ?? 5 })
+        : await queryProject(root, input.task.trim(), { top: input.top ?? 5 }));
+    }
+    if (operation === "show") {
+      const result = options.session
+        ? options.session.show(input.id.trim())
+        : await showProjectCard(root, input.id.trim());
+      if (!result.card && !result.node) return failure(operation, "LNVAP404", `Unknown or inactive semantic ID ${input.id}.`, result);
+      return success(operation, result);
+    }
+    if (operation === "context") {
+      const contextOptions = {
+        depth: input.depth ?? 1,
+        budget: input.budget ?? 2500,
+        maxEdges: input.maxEdges ?? 24,
+      };
+      return success(operation, options.session
+        ? options.session.context(input.id.trim(), contextOptions)
+        : await buildContext(root, input.id.trim(), contextOptions));
+    }
+    const project = await scanProject(root, { paths: input.paths ?? [] });
+    const graphInputs = await loadGraphInputs(root, project.config);
+    const diagnostics = [...validateProject(project), ...graphInputs.diagnostics].sort(compareDiagnostics);
+    const counts = countDiagnostics(diagnostics);
+    return {
+      schemaVersion: AGENT_OPERATION_SCHEMA_VERSION,
+      operation,
+      ok: counts.error === 0,
+      data: { counts, diagnostics, cardCount: project.records.length },
+      error: null,
+    };
+  } catch (error) {
+    return failure(operation, "LNVAP500", error instanceof Error ? error.message : String(error));
+  }
+}
+
+function validateInput(schema, input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return "Operation input must be an object.";
+  const keys = Object.keys(input).sort();
+  const unknown = keys.filter((key) => !Object.hasOwn(schema.properties, key));
+  if (unknown.length > 0) return `Unknown input field(s): ${unknown.join(", ")}.`;
+  const missing = schema.required.filter((key) => input[key] === undefined);
+  if (missing.length > 0) return `Missing required input field(s): ${missing.join(", ")}.`;
+  for (const key of keys) {
+    const error = validateProperty(key, input[key], schema.properties[key]);
+    if (error) return error;
+  }
+  return null;
+}
+
+function validateProperty(key, value, schema) {
+  if (schema.type === "string") {
+    if (typeof value !== "string" || value.trim().length < (schema.minLength ?? 0)) return `Input field ${key} must be a non-empty string.`;
+  } else if (schema.type === "integer") {
+    if (!Number.isInteger(value) || value < schema.minimum || value > schema.maximum) {
+      return `Input field ${key} must be an integer from ${schema.minimum} to ${schema.maximum}.`;
+    }
+  } else if (schema.type === "array") {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.length < schema.items.minLength)) {
+      return `Input field ${key} must be an array of non-empty strings.`;
+    }
+  }
+  return null;
+}
+
+function success(operation, data) {
+  return { schemaVersion: AGENT_OPERATION_SCHEMA_VERSION, operation, ok: true, data, error: null };
+}
+
+function failure(operation, code, message, data = null) {
+  return { schemaVersion: AGENT_OPERATION_SCHEMA_VERSION, operation, ok: false, data, error: { code, message } };
+}
+
+function compareDiagnostics(left, right) {
+  return left.file.localeCompare(right.file, "en") || left.line - right.line || left.column - right.column ||
+    left.code.localeCompare(right.code, "en") || left.message.localeCompare(right.message, "en");
+}

package/src/agent-tools.js

@@ -0,0 +1,61 @@
+/* llmnav/1 module
+id=llmnav.agent.tool-schema
+role=Publish stable provider-neutral tool definitions without loading repository execution code.
+owns=agent tool names|tool input schemas|tool order
+excludes=operation execution|provider SDK transport|repository scope
+search=agent tool definitions|tool JSON schema|stable tool prefix|provider neutral schema
+rel=workflow>llmnav.agent.protocol
+stability=contract
+*/
+
+export const AGENT_TOOL_SCHEMA_VERSION = 1;
+
+const DEFINITIONS = [
+  tool("llmnav_query", "Find the most relevant semantic cards for a coding task.", {
+    task: stringProperty("Task language to search for."),
+    top: integerProperty("Maximum results.", 1, 100, 5),
+  }, ["task"]),
+  tool("llmnav_show", "Resolve one local or qualified workspace semantic ID.", {
+    id: stringProperty("Semantic ID or repository-qualified semantic ID."),
+  }, ["id"]),
+  tool("llmnav_context", "Build bounded semantic and graph context around one ID.", {
+    id: stringProperty("Semantic ID or repository-qualified semantic ID."),
+    depth: integerProperty("Maximum graph traversal depth.", 0, 8, 1),
+    budget: integerProperty("Approximate token budget.", 128, 100000, 2500),
+    maxEdges: integerProperty("Maximum graph edges to inspect and pack.", 0, 1000, 24),
+  }, ["id"]),
+  tool("llmnav_check", "Validate semantic cards and configured graph inputs without mutation.", {
+    paths: {
+      type: "array",
+      description: "Optional repository-relative paths to validate.",
+      items: { type: "string", minLength: 1 },
+      default: [],
+    },
+  }),
+];
+
+export function getAgentToolDefinitions() {
+  return structuredClone(DEFINITIONS);
+}
+
+function tool(name, description, properties, required = []) {
+  return {
+    schemaVersion: AGENT_TOOL_SCHEMA_VERSION,
+    name,
+    description,
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties,
+      required,
+    },
+  };
+}
+
+function stringProperty(description) {
+  return { type: "string", minLength: 1, description };
+}
+
+function integerProperty(description, minimum, maximum, defaultValue) {
+  return { type: "integer", minimum, maximum, default: defaultValue, description };
+}