llmnav 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -6,6 +6,18 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [0.7.4] — 2026-08-14
+
+### Fixed
+
+* Required npm provenance in package metadata, release validation, and the tag publication workflow so public Trusted Publisher releases fail closed if provenance is disabled.
+
+## [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

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/publishing.md

@@ -31,7 +31,7 @@ npm run release:check
 
 ## 3. Configure npm authentication
 
-The supplied release workflow uses GitHub's OIDC token through npm Trusted Publishers. The GitHub source repository is private, so the workflow explicitly disables provenance; npm accepts provenance only from public source repositories. If the repository becomes public, enable provenance in both `package.json` and the workflow after a successful release check. The same tag workflow creates an idempotent GitHub Release only after the npm registry check or publication succeeds.
+The supplied release workflow uses GitHub's OIDC token through npm Trusted Publishers. The public GitHub source repository enables provenance in both `package.json` and the workflow, and the release check fails if either surface disables it. The same tag workflow creates an idempotent GitHub Release only after the npm registry check or publication succeeds.
 
 The workflow references a GitHub environment named `npm`. Create that environment for release protection, or remove the `environment` line when no environment gate is desired.
 
@@ -55,14 +55,14 @@ Manual publication:
 
 ```sh
 npm login
-npm publish --provenance=false --access public
+npm publish --provenance --access public
 ```
 
 Automated publication:
 
 ```sh
-git tag v0.6.0
-git push origin v0.6.0
+git tag vX.Y.Z
+git push origin vX.Y.Z
 ```
 
 The release workflow rejects a tag that does not match `package.json`. If the exact version is already present in npm, the workflow succeeds only when the registry tarball integrity matches the tagged package; a mismatched package fails closed. It then reuses an existing GitHub Release for the tag or creates one with generated release notes. Registry, GitHub API, and Release creation errors other than an expected missing Release fail the workflow.

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.2",
+  "version": "0.7.4",
   "description": "A deterministic semantic navigation layer for LLM coding agents.",
   "type": "module",
   "bin": {
@@ -74,6 +74,6 @@
   "types": "./src/index.d.ts",
   "publishConfig": {
     "access": "public",
-    "provenance": false
+    "provenance": true
   }
 }

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.2";
+export const PACKAGE_VERSION = "0.7.4";
 export const SPEC_VERSION = "1";
 
 export const SCOPES = Object.freeze(["file", "module", "symbol"]);