llmnav 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -6,6 +6,18 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [0.7.3] — 2026-08-14
+
+### Fixed
+
+* Resolved repository-local Go module imports for annotation audit fan-in and repository graph edges, grouped Go audit candidates by package, recognized `cmd/*/main.go` entrypoints, suppressed `_test.go` support files, and invalidated graph partitions when module resolution changes.
+
+## [0.7.2] — 2026-08-13
+
+### Added
+
+* Documented pre-1.0 stability classes, a one-minor and 90-day public API deprecation window, generated-format migration guarantees, and the limited security exception.
+
 ## [0.7.1] — 2026-08-13
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@ It adds compact, stable metadata to a small number of architectural and behavior
 
 LLMNav is not a documentation generator, an embedding database, or a reason to annotate every function. It is a zero-runtime-dependency Node.js CLI and ESM library for reducing broad repository scans, irrelevant context, stale hand-written links, repeated card tokenization, and avoidable cache invalidation.
 
-## What v0.6 provides
+## What v0.7 provides
 
 * The backward-compatible `llmnav/1` source comment specification
 * A parser and data-loss-resistant canonical formatter
@@ -36,6 +36,8 @@ LLMNav is not a documentation generator, an embedding database, or a reason to a
 
 The package supports Node.js 22 or newer, uses ESM, performs no network requests, and has no runtime dependencies.
 
+Public compatibility rules are documented in [Compatibility and deprecation policy](docs/compatibility.md). In short, `llmnav/1` source cards and the schemaVersion 1 primary index are stable contracts; disposable generated accelerators may be rebuilt, and documented CLI or library removals receive a replacement and a minimum one-minor/90-day deprecation window.
+
 ## Install
 
 ```sh

package/ROADMAP.md

@@ -89,7 +89,7 @@ The source grammar and generated formats will be declared stable only after use
 
 In progress:
 
-* Generated-format migration tooling is implemented for the current public formats; compatibility guarantees still need a documented support and deprecation policy.
+* Generated-format migration tooling and the public support and deprecation policy are implemented for the current formats.
 * A read-only cross-repository conformance matrix measures validation, retrieval, audit, repeatability, and cache freshness without averaging weak repositories away.
 * LLMNav, Workduck, Sairon, and AI BOM Generator currently pass repository-isolated conformance checks across JavaScript, TypeScript, Rust, Go, and Python.
 * The current evidence covers 4 repositories and 5 required languages with no held or failed repository, while 1.0 still requires sustained Windows and Linux verification and published benchmark methodology.

package/docs/api.md

@@ -306,3 +306,5 @@ The typed `llmnav/examples/provider-neutral-host.mjs` export composes these APIs
 ## Compatibility boundary
 
 The public API follows package semantic versioning. `index.json` schemaVersion 1 and `llmnav/1` source syntax remain compatible. Contract fingerprints are optional additive index fields. `search-index.json`, `file-state.json`, `graph-state.json`, transaction journals, and performance metrics retain their own schema or implementation versions.
+
+See [Compatibility and deprecation policy](compatibility.md) for the pre-1.0 stability classes, removal window, migration guarantees, and security exception.

package/docs/architecture.md

@@ -72,6 +72,8 @@ Generation compares the previous and current primary indexes to emit `affectedBo
 
 The read-only audit combines package entrypoints, public re-export reachability, generated structural boundaries, import fan-in, exported declaration counts, and source size. It lowers the priority of named utilities and low-fan-in export hubs, declaration files, non-production support paths, and pure re-export barrels. High-fan-in domain contract hubs do not receive the broad-utility penalty merely because they export many declarations. Every candidate retains its score inputs and deterministic repository-relative path.
 
+Go source is audited by package rather than by individual file. LLMNav reads repository-contained `go.mod` files without executing the Go toolchain, resolves matching full module imports, counts importing packages, treats `cmd/*/main.go` and other `package main` entrypoints as commands, and excludes `_test.go` files from production signals. One reviewed `module` card covers its Go package for audit purposes; a `file` card remains file-specific. An uncovered package produces one deterministic representative path instead of one candidate per file. The schema-version 1 summary counters continue to report exact annotated file placement, while the candidate list reports these package-level omissions.
+
 This analyzer deliberately stops before semantic generation. Structure can identify a file worth inspecting, but it cannot safely invent a durable ID, role, ownership statement, invariant, risk, or relation. Accepted boundaries become explicit source cards, path-specific coverage rules, and retrieval regression queries through normal review.
 
 ## Deterministic inverted index
@@ -107,6 +109,8 @@ Search treats lexical results as seeds and applies only a confidence-scaled one-
 
 The graph is also the explicit workspace resolution surface. Qualified IDs resolve by exact node key. Unqualified IDs prefer the local repository and resolve externally only when the semantic ID is unique across imported repositories. No directory discovery or network lookup occurs during resolution.
 
+For Go cards, repository-local full module imports resolve to cards in the imported package. Module cards are preferred when present so a package import does not create arbitrary symbol-level fan-out. The module resolver version and discovered module map participate in the graph resolution hash, so an upgraded resolver or changed `go.mod` rebuilds affected card partitions instead of reusing stale zero-edge state.
+
 `.llmnav/cache/graph-state.json` is a disposable schemaVersion 1 acceleration artifact. Content-addressed partitions isolate local cards and imported indexes. Partition keys and hashes include every graph-relevant dimension, and local path resolution changes invalidate all affected local-import decisions. Incompatible or malformed state is never partially trusted: generation rebuilds it from the current primary index and validated graph inputs.
 
 Graph state contains no timestamps, absolute paths, or filesystem identity. Incremental and forced-full builds must produce byte-identical graph and state bytes, and the transaction publishes both with the manifest.

package/docs/compatibility.md

@@ -0,0 +1,40 @@
+# Compatibility and deprecation policy
+
+This policy applies to LLMNav releases before 1.0 and defines which surfaces are durable enough for repositories and integrations to depend on.
+
+## Stability classes
+
+| Surface | Stability before 1.0 | Compatibility rule |
+| --- | --- | --- |
+| `llmnav/1` source cards | Stable protocol | Existing valid cards keep their meaning. A breaking grammar or semantic change requires a new protocol header such as `llmnav/2`; LLMNav will not reinterpret `llmnav/1` incompatibly. |
+| `.llmnav/cache/index.json` schemaVersion 1 | Stable primary generated contract | Additive optional fields are allowed. Removing or changing an existing field requires a new schema version and a migration path. |
+| CLI commands, flags, exit codes, JSON fields, ESM exports, and TypeScript declarations documented in this repository | SemVer public API | Compatible additions may ship in a minor release. Removal or incompatible behavior requires a minor release before 1.0, a documented replacement, and the deprecation window below. |
+| Diagnostic codes | Stable identifiers | A code may gain clearer wording, but its documented category and remediation meaning remain compatible. Retiring a code follows the deprecation window. |
+| Search ranking and performance | Behavioral contract | Determinism and published regression thresholds are protected. Exact scores or ordering may change in a minor release when benchmarks justify the change and the changelog explains it. |
+| `search-index.json`, `file-state.json`, `graph-state.json`, prompt bundles, shards, transaction journals, locks, and other generated accelerators | Disposable versioned formats | Consumers must not treat these as source truth. LLMNav may replace an incompatible format after `migrate --check`; it must rebuild or fail closed rather than silently misread it. |
+| Undocumented internals and test helpers | Unstable | They may change in any release. Importing source files outside the documented package exports is unsupported. |
+
+Package versions follow Semantic Versioning. Before 1.0, an incompatible change to a documented package API may use a minor version, while patches remain backward compatible. Protocol and generated-schema versions are independent from the npm package version.
+
+## Deprecation window
+
+For a documented CLI, JSON, ESM, or TypeScript surface:
+
+1. The introducing release documents the deprecated surface, its replacement, and any automated migration.
+2. The old surface remains functional for at least one subsequent minor release and for at least 90 days. Removal waits until both conditions are satisfied.
+3. `llmnav doctor`, `check`, or `migrate --check` reports a stable diagnostic when repository action is required. A warning must not silently become destructive behavior.
+4. The removal release records the change in `CHANGELOG.md` and `docs/migration.md`.
+
+Immediate removal is reserved for an actively exploitable security issue or behavior that can corrupt source or repository state. The security release must explain the exception and provide the safest available migration.
+
+## Upgrade guarantees
+
+* Canonical source cards and `.llmnav/ids.jsonl` remain the recovery authority; disposable caches do not.
+* `migrate --check` is read-only. `migrate --write` validates canonical source before mutation and publishes a complete recoverable cache transaction.
+* A supported upgrade path covers the latest release of the previous minor line to the current release. Skipping several minor lines may require running the newest migration tool directly, but must not require installing every intermediate package version.
+* Downgrade compatibility is not guaranteed for generated caches. Restore caches by regenerating them with the target version; never hand-edit generated schema versions.
+* Node.js runtime support follows the declared `engines` range. Dropping a supported Node.js major is an incompatible documented API change and follows the deprecation window unless that runtime is no longer receiving security updates.
+
+## 1.0 commitment
+
+At 1.0, incompatible changes to documented package APIs require a new major package version. The `llmnav/1` and primary-index rules above already apply and do not wait for 1.0. The remaining 1.0 gates are sustained cross-platform evidence, published benchmark methodology, and closure of high-severity parser or transaction ambiguity.

package/docs/quickstart.md

@@ -21,6 +21,8 @@ npx llmnav audit
 
 Start with high and medium candidates. The audit explains whether a file is a package entrypoint, public API, generated structural boundary, or high fan-in module. Narrow source signals also identify versioned schema literals, persistent dotted JSON filename protocols, and Tauri invoke adapters. It does not write source or invent card contents. Declaration files and common non-production or low-fan-in utility shapes are suppressed so the result is a review queue, not a demand to annotate every file.
 
+In Go repositories, candidates represent packages. Full imports below a repository-contained `go.mod` contribute package fan-in, `cmd/*/main.go` is treated as a command entrypoint, and `_test.go` files do not create separate production candidates. Put one `module` card on a durable package representative; do not repeat the same package role on every Go file.
+
 After accepting a candidate, write its durable meaning by inspecting the source, add a narrow `coverageRules` entry for that exact boundary, and add a real task-language query to `.llmnav/eval/queries.jsonl`. Use `npx llmnav audit --fail-on high` in CI only after the initial review.
 
 ## Annotate a module boundary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llmnav",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "A deterministic semantic navigation layer for LLM coding agents.",
   "type": "module",
   "bin": {

package/src/audit.js

@@ -11,6 +11,7 @@ stability=contract
 
 import path from "node:path";
 import { detectBoundaries } from "./boundaries.js";
+import { moduleKeyForFile, resolveGoImportModule } from "./module-resolution.js";
 import { scanProject } from "./project.js";
 import { compareText, readJsonSafe, toPosix } from "./util.js";
 
@@ -23,7 +24,7 @@ const SOURCE_EXTENSIONS = Object.freeze([
   ".ts", ".tsx", ".vue",
 ]);
 const UTILITY_NAME_PATTERN = /^(?:common|helpers?|shared|utils?)$/u;
-const NON_PRODUCTION_PATH_PATTERN = /(?:^|\/)(?:__tests__|benchmarks?|fixtures?|tests?)(?:\/|$)|\.(?:spec|test)\.[^/]+$/u;
+const NON_PRODUCTION_PATH_PATTERN = /(?:^|\/)(?:__tests__|benchmarks?|fixtures?|testdata|tests?)(?:\/|$)|\.(?:spec|test)\.[^/]+$|_test\.go$/u;
 const LARGE_SOURCE_BYTES = 12_000;
 
 export async function auditProject(root) {
@@ -31,44 +32,68 @@ export async function auditProject(root) {
   const fileByPath = new Map(
     project.fileRecords.map((record) => [toPosix(record.relativePath), record]),
   );
-  const moduleCardPaths = new Set(
+  const cardedFilePaths = new Set(
     project.records
       .filter((record) => record.card.scope === "file" || record.card.scope === "module")
       .map((record) => toPosix(record.relativePath)),
   );
-  const importsByPath = new Map();
-  const importedBy = new Map([...fileByPath.keys()].map((file) => [file, new Set()]));
-  for (const [file, record] of fileByPath) {
-    const resolved = record.imports
-      .map((specifier) => resolveLocalSpecifier(file, specifier, fileByPath))
-      .filter(Boolean);
-    const unique = [...new Set(resolved)].sort(compareText);
-    importsByPath.set(file, unique);
-    for (const target of unique) importedBy.get(target)?.add(file);
+  const exactCardPaths = new Set(
+    project.records
+      .filter((record) => record.card.scope === "file")
+      .map((record) => toPosix(record.relativePath)),
+  );
+  const coveredModules = new Set(
+    project.records
+      .filter((record) => record.card.scope === "module")
+      .map((record) => moduleKeyForFile(record.relativePath)),
+  );
+  const filesByModule = groupFilesByModule(fileByPath);
+  const moduleKeys = new Set(filesByModule.keys());
+  const importedBy = new Map([...moduleKeys].map((key) => [key, new Set()]));
+  for (const [sourceKey, files] of filesByModule) {
+    const targets = new Set();
+    for (const [file, record] of files) {
+      for (const specifier of record.imports) {
+        const target = resolveImportedModule(file, specifier, fileByPath, project.moduleResolution, moduleKeys);
+        if (target) targets.add(target);
+      }
+    }
+    for (const target of targets) importedBy.get(target)?.add(sourceKey);
   }
 
   const entrypoints = await collectWorkspacePackageEntrypoints(root, fileByPath);
+  collectGoEntrypoints(fileByPath, entrypoints);
   const publicApiPaths = collectPublicApiPaths(entrypoints, fileByPath);
   const candidates = [];
 
-  for (const [file, record] of [...fileByPath.entries()].sort(([left], [right]) => compareText(left, right))) {
-    if (moduleCardPaths.has(file)) continue;
-    if (/\.d\.[cm]?ts$/u.test(file)) continue;
-    const boundaries = detectBoundaries({
-      relativePath: file,
+  for (const [moduleKey, files] of [...filesByModule.entries()].sort(([left], [right]) => compareText(left, right))) {
+    if (coveredModules.has(moduleKey)) continue;
+    const selectableFiles = files.filter(([file]) => !exactCardPaths.has(file) && !/\.d\.[cm]?ts$/u.test(file));
+    if (selectableFiles.length === 0) continue;
+    const productionFiles = selectableFiles.filter(([file]) => !NON_PRODUCTION_PATH_PATTERN.test(file));
+    const analyzedFiles = productionFiles.length > 0 ? productionFiles : selectableFiles;
+    const file = selectRepresentativeFile(analyzedFiles, entrypoints);
+    const record = fileByPath.get(file);
+    const boundaries = [...new Set(analyzedFiles.flatMap(([candidate, item]) => detectBoundaries({
+      relativePath: candidate,
       card: { effect: [], risk: [] },
-      source: record.source ?? "",
-    }).map((boundary) => boundary.kind);
-    const exportedDeclarations = countExportedDeclarations(record.source ?? "", file);
-    const entrypoint = entrypoints.has(file);
-    const publicApi = publicApiPaths.has(file) && !entrypoint;
-    const importers = importedBy.get(file)?.size ?? 0;
-    const reexportBarrel = isReexportBarrel(record.source ?? "", file);
-    const basename = path.posix.basename(file, path.posix.extname(file)).toLowerCase();
+      source: item.source ?? "",
+    }).map((boundary) => boundary.kind)))].sort(compareText);
+    const exportedDeclarations = analyzedFiles.reduce(
+      (sum, [candidate, item]) => sum + countExportedDeclarations(item.source ?? "", candidate),
+      0,
+    );
+    const entrypoint = analyzedFiles.some(([candidate]) => entrypoints.has(candidate));
+    const publicApi = analyzedFiles.some(([candidate]) => publicApiPaths.has(candidate) && !entrypoints.has(candidate));
+    const importers = importedBy.get(moduleKey)?.size ?? 0;
+    const reexportBarrel = analyzedFiles.length === 1 && isReexportBarrel(record.source ?? "", file);
+    const isGoModule = moduleKey.startsWith("go:");
+    const moduleName = isGoModule ? moduleKey.slice(3) : file;
+    const basename = path.posix.basename(moduleName, path.posix.extname(moduleName)).toLowerCase();
     const broadUtility = UTILITY_NAME_PATTERN.test(basename) ||
-      (exportedDeclarations >= 10 && importers <= 1 && !entrypoint && !publicApi && boundaries.length === 0);
-    const nonProduction = NON_PRODUCTION_PATH_PATTERN.test(file);
-    const largeSource = record.sourceBytes >= LARGE_SOURCE_BYTES;
+      (!isGoModule && exportedDeclarations >= 10 && importers <= 1 && !entrypoint && !publicApi && boundaries.length === 0);
+    const nonProduction = productionFiles.length === 0;
+    const largeSource = analyzedFiles.reduce((sum, [, item]) => sum + item.sourceBytes, 0) >= LARGE_SOURCE_BYTES;
     const hasSignal = entrypoint || publicApi || boundaries.length > 0 || importers > 0 || exportedDeclarations > 0 || largeSource;
     if (!hasSignal) continue;
 
@@ -139,8 +164,8 @@ export async function auditProject(root) {
     compareText(left.path, right.path));
   const summary = {
     analyzedFiles: fileByPath.size,
-    cardedFiles: moduleCardPaths.size,
-    filesWithoutModuleCards: fileByPath.size - moduleCardPaths.size,
+    cardedFiles: cardedFilePaths.size,
+    filesWithoutModuleCards: fileByPath.size - cardedFilePaths.size,
     candidates: candidates.length,
     high: candidates.filter((candidate) => candidate.priority === "high").length,
     medium: candidates.filter((candidate) => candidate.priority === "medium").length,
@@ -155,6 +180,46 @@ export async function auditProject(root) {
   };
 }
 
+function groupFilesByModule(fileByPath) {
+  const output = new Map();
+  for (const [file, record] of fileByPath) {
+    const key = moduleKeyForFile(file);
+    const files = output.get(key) ?? [];
+    files.push([file, record]);
+    output.set(key, files);
+  }
+  for (const files of output.values()) files.sort(([left], [right]) => compareText(left, right));
+  return output;
+}
+
+function resolveImportedModule(file, specifier, fileByPath, moduleResolution, moduleKeys) {
+  const goTarget = resolveGoImportModule(file, specifier, moduleResolution, moduleKeys);
+  if (goTarget) return goTarget;
+  const target = resolveLocalSpecifier(file, specifier, fileByPath);
+  return target ? moduleKeyForFile(target) : null;
+}
+
+function collectGoEntrypoints(fileByPath, entrypoints) {
+  for (const [file, record] of fileByPath) {
+    if (!file.endsWith(".go") || path.posix.basename(file) !== "main.go") continue;
+    if (/^\s*package\s+main\b/mu.test(record.source ?? "")) entrypoints.add(file);
+  }
+}
+
+function selectRepresentativeFile(files, entrypoints) {
+  return [...files].sort(([leftPath, left], [rightPath, right]) =>
+    representativeScore(rightPath, right, entrypoints) - representativeScore(leftPath, left, entrypoints) ||
+    compareText(leftPath, rightPath))[0][0];
+}
+
+function representativeScore(file, record, entrypoints) {
+  let score = entrypoints.has(file) ? 100_000 : 0;
+  if (path.posix.basename(file) === "doc.go") score += 50_000;
+  score += countExportedDeclarations(record.source ?? "", file) * 1_000;
+  score += Math.min(999, Math.floor(record.sourceBytes / 100));
+  return score;
+}
+
 export function auditHasFindings(result, minimumPriority = "none") {
   if (minimumPriority === "none") return false;
   if (!AUDIT_PRIORITIES.includes(minimumPriority)) {

package/src/boundaries.js

@@ -50,7 +50,8 @@ export function detectBoundaries(record) {
   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)) {
+  if (/(?:^|\/)(?:cmd|commands?|cli|bin)(?:\/|$)/u.test(relativePath) || /(?:command|cmd)\.[^.]+$/u.test(basename) ||
+      (basename === "main.go" && /^\s*package\s+main\b/mu.test(source))) {
     add("command", "high", "path");
   }
   if (/\.rs$/u.test(relativePath) && /#\[tauri::command\]|tauri::generate_handler!/u.test(source)) {

package/src/graph.js

@@ -10,6 +10,12 @@ stability=architecture
 */
 
 import path from "node:path";
+import {
+  compatibleModuleResolution,
+  MODULE_RESOLVER_VERSION,
+  moduleKeyForFile,
+  resolveGoImportModule,
+} from "./module-resolution.js";
 import { compareText, sha256, stableJson, stableStringify, toPosix } from "./util.js";
 
 export const GRAPH_SCHEMA_VERSION = 1;
@@ -23,11 +29,15 @@ export function buildRepositoryGraph(project, index) {
 export function buildRepositoryGraphIncremental(project, index, previousState = null) {
   const repositoryId = index.repositoryId;
   const cardsByPath = groupCardsByPath(index.cards);
-  const resolutionHash = sha256(stableJson(
-    [...cardsByPath.entries()]
+  const cardsByModule = groupCardsByModule(index.cards);
+  const moduleResolution = compatibleModuleResolution(project.moduleResolution);
+  const resolutionHash = sha256(stableJson({
+    resolverVersion: MODULE_RESOLVER_VERSION,
+    moduleResolution,
+    cardsByPath: [...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();
@@ -50,7 +60,7 @@ export function buildRepositoryGraphIncremental(project, index, previousState =
       partitions.push(previous);
       reusedPartitions += 1;
     } else {
-      partitions.push(buildCardPartition(key, inputHash, card, repositoryId, cardsByPath));
+      partitions.push(buildCardPartition(key, inputHash, card, repositoryId, cardsByPath, cardsByModule, moduleResolution));
       rebuiltPartitions += 1;
     }
   }
@@ -196,7 +206,7 @@ export function renderGraphNode(node) {
   return lines.join("\n");
 }
 
-function buildCardPartition(partitionKey, inputHash, card, repositoryId, cardsByPath) {
+function buildCardPartition(partitionKey, inputHash, card, repositoryId, cardsByPath, cardsByModule, moduleResolution) {
   const nodes = new Map();
   const edges = new Map();
   const key = qualifyId(card.id, repositoryId);
@@ -231,7 +241,7 @@ function buildCardPartition(partitionKey, inputHash, card, repositoryId, cardsBy
   }
 
   for (const specifier of card.imports ?? []) {
-    for (const target of resolveLocalImport(card.location.path, specifier, cardsByPath)) {
+    for (const target of resolveLocalImport(card.location.path, specifier, cardsByPath, cardsByModule, moduleResolution)) {
       addEdge(edges, nodes, {
         from: key,
         to: qualifyId(target.id, repositoryId),
@@ -378,7 +388,25 @@ function groupCardsByPath(cards) {
   return output;
 }
 
-function resolveLocalImport(sourcePath, specifier, cardsByPath) {
+function groupCardsByModule(cards) {
+  const output = new Map();
+  for (const card of cards) {
+    const key = moduleKeyForFile(card.location.path);
+    const records = output.get(key) ?? [];
+    records.push(card);
+    output.set(key, records);
+  }
+  for (const records of output.values()) records.sort((left, right) => compareText(left.id, right.id));
+  return output;
+}
+
+function resolveLocalImport(sourcePath, specifier, cardsByPath, cardsByModule, moduleResolution) {
+  const goTarget = resolveGoImportModule(sourcePath, specifier, moduleResolution, new Set(cardsByModule.keys()));
+  if (goTarget) {
+    const cards = cardsByModule.get(goTarget) ?? [];
+    const moduleCards = cards.filter((card) => card.scope === "module");
+    return moduleCards.length > 0 ? moduleCards : cards;
+  }
   if (!specifier.startsWith(".")) return [];
   const base = path.posix.normalize(path.posix.join(path.posix.dirname(toPosix(sourcePath)), specifier));
   if (base.startsWith("../")) return [];

package/src/incremental.js

@@ -15,6 +15,7 @@ import { createDeclarationScanContext, findAttachedDeclaration, extractImports }
 import { collectSourceFiles } from "./files.js";
 import { parseLlmnavBlocks } from "./parser.js";
 import { loadRegistry } from "./registry.js";
+import { loadModuleResolution } from "./module-resolution.js";
 import {
   assertNoSymlinkTraversal,
   atomicWrite,
@@ -119,6 +120,7 @@ export async function scanProjectIncremental(root, options = {}) {
     files: Object.fromEntries(Object.entries(nextHintFiles).sort(([left], [right]) => compareText(left, right))),
   };
   const registry = await loadRegistry(root);
+  const moduleResolution = await loadModuleResolution(root, fileRecords);
   const project = {
     root,
     config,
@@ -127,6 +129,7 @@ export async function scanProjectIncremental(root, options = {}) {
     fileRecords,
     records,
     registry,
+    moduleResolution,
     sourceBytes,
     semanticBytes,
     incremental: stats,

package/src/index.d.ts

@@ -371,6 +371,11 @@ export interface ProjectRecord {
   declaration: Declaration | null;
 }
 
+export interface ModuleResolution {
+  schemaVersion: 1;
+  goModules: Array<{ directory: string; modulePath: string }>;
+}
+
 export interface ScannedProject {
   root: string;
   config: LlmnavConfig;
@@ -381,6 +386,7 @@ export interface ScannedProject {
   registry: Registry;
   sourceBytes: number;
   semanticBytes: number;
+  moduleResolution?: ModuleResolution;
   graphInputs?: GraphInputIndex[];
 }
 

package/src/module-resolution.js

@@ -0,0 +1,106 @@
+/* llmnav/1 module
+id=llmnav.structure.modules
+role=Resolve repository-contained language modules without executing project toolchains or following metadata symlinks.
+owns=language module identity|Go module discovery|Go package import resolution
+excludes=dependency installation|external module lookup|semantic card generation
+search=Go module import|package boundary|local module resolution
+invariant=Module resolution reads only regular repository-contained metadata files and never executes a language toolchain.
+rel=workflow>llmnav.project.scan
+rel=workflow>llmnav.graph.generate
+stability=architecture
+*/
+
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { compareText, toPosix } from "./util.js";
+
+export const MODULE_RESOLUTION_SCHEMA_VERSION = 1;
+export const MODULE_RESOLVER_VERSION = 1;
+
+export async function loadModuleResolution(root, fileRecords = []) {
+  const directories = new Set([""]);
+  for (const record of fileRecords) {
+    const file = toPosix(record.relativePath ?? "");
+    if (!file.endsWith(".go")) continue;
+    let directory = path.posix.dirname(file);
+    while (directory !== "." && directory !== "") {
+      directories.add(directory);
+      const parent = path.posix.dirname(directory);
+      if (parent === directory || parent === ".") break;
+      directory = parent;
+    }
+  }
+
+  const goModules = [];
+  for (const directory of [...directories].sort(compareDirectories)) {
+    const relativeFile = directory ? `${directory}/go.mod` : "go.mod";
+    const absoluteFile = path.join(root, ...relativeFile.split("/"));
+    let details;
+    try {
+      details = await lstat(absoluteFile);
+    } catch (error) {
+      if (error && typeof error === "object" && error.code === "ENOENT") continue;
+      throw error;
+    }
+    if (details.isSymbolicLink()) throw new Error(`Go module file ${JSON.stringify(relativeFile)} is a symbolic link.`);
+    if (!details.isFile()) continue;
+    const modulePath = parseGoModulePath(await readFile(absoluteFile, "utf8"));
+    if (modulePath) goModules.push({ directory, modulePath });
+  }
+  goModules.sort((left, right) => compareText(left.directory, right.directory) || compareText(left.modulePath, right.modulePath));
+  return {
+    schemaVersion: MODULE_RESOLUTION_SCHEMA_VERSION,
+    goModules,
+  };
+}
+
+export function parseGoModulePath(source) {
+  for (const line of String(source).split(/\r?\n/u)) {
+    const match = /^\s*module\s+([^\s]+)\s*(?:\/\/.*)?$/u.exec(line);
+    if (!match) continue;
+    const value = match[1];
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("`") && value.endsWith("`"))) {
+      return value.slice(1, -1).trim() || null;
+    }
+    return value.trim() || null;
+  }
+  return null;
+}
+
+export function moduleKeyForFile(file) {
+  const normalized = toPosix(file);
+  if (path.posix.extname(normalized).toLowerCase() !== ".go") return `file:${normalized}`;
+  const directory = path.posix.dirname(normalized);
+  return `go:${directory === "." ? "." : directory}`;
+}
+
+export function resolveGoImportModule(sourcePath, specifier, resolution, availableModuleKeys = null) {
+  if (path.posix.extname(toPosix(sourcePath)).toLowerCase() !== ".go") return null;
+  const modules = compatibleModuleResolution(resolution).goModules
+    .filter((item) => specifier === item.modulePath || specifier.startsWith(`${item.modulePath}/`))
+    .sort((left, right) => right.modulePath.length - left.modulePath.length || compareText(left.modulePath, right.modulePath));
+  const selected = modules[0];
+  if (!selected) return null;
+  const suffix = specifier === selected.modulePath ? "" : specifier.slice(selected.modulePath.length + 1);
+  const directory = path.posix.normalize(path.posix.join(selected.directory || ".", suffix || "."));
+  if (directory === ".." || directory.startsWith("../")) return null;
+  const key = `go:${directory}`;
+  if (availableModuleKeys && !availableModuleKeys.has(key)) return null;
+  return key;
+}
+
+export function compatibleModuleResolution(value) {
+  if (!value || value.schemaVersion !== MODULE_RESOLUTION_SCHEMA_VERSION || !Array.isArray(value.goModules)) {
+    return { schemaVersion: MODULE_RESOLUTION_SCHEMA_VERSION, goModules: [] };
+  }
+  const goModules = value.goModules
+    .filter((item) => item && typeof item.directory === "string" && typeof item.modulePath === "string" && item.modulePath)
+    .map((item) => ({ directory: toPosix(item.directory), modulePath: item.modulePath }))
+    .sort((left, right) => compareText(left.directory, right.directory) || compareText(left.modulePath, right.modulePath));
+  return { schemaVersion: MODULE_RESOLUTION_SCHEMA_VERSION, goModules };
+}
+
+function compareDirectories(left, right) {
+  const depth = left.split("/").filter(Boolean).length - right.split("/").filter(Boolean).length;
+  return depth || compareText(left, right);
+}

package/src/project.js

@@ -16,6 +16,7 @@ import { createDeclarationScanContext, findAttachedDeclaration, extractImports }
 import { collectSourceFiles } from "./files.js";
 import { parseLlmnavBlocks } from "./parser.js";
 import { loadRegistry } from "./registry.js";
+import { loadModuleResolution } from "./module-resolution.js";
 import { relativePosix, sha256 } from "./util.js";
 
 export async function scanProject(root, options = {}) {
@@ -64,6 +65,7 @@ export async function scanProject(root, options = {}) {
   }
 
   const registry = await loadRegistry(root);
+  const moduleResolution = await loadModuleResolution(root, fileRecords);
   return {
     root,
     config,
@@ -72,6 +74,7 @@ export async function scanProject(root, options = {}) {
     fileRecords,
     records,
     registry,
+    moduleResolution,
     sourceBytes,
     semanticBytes,
   };

package/src/spec.js

@@ -10,7 +10,7 @@ rel=workflow>llmnav.rules.validate
 stability=contract
 */
 
-export const PACKAGE_VERSION = "0.7.1";
+export const PACKAGE_VERSION = "0.7.3";
 export const SPEC_VERSION = "1";
 
 export const SCOPES = Object.freeze(["file", "module", "symbol"]);