@g3nomaly/analyze 0.1.6 → 0.1.7

package/dist/cli.js

@@ -967,7 +967,13 @@ function endsWith(owners, qualifier) {
   const offset = owners.length - qualifier.length;
   return qualifier.every((name, index) => owners[offset + index] === name);
 }
-function pick(declarations, scope, qualifier = []) {
+function pick(declarations, scope, qualifier = [], accepts = () => true) {
+  const winner = choose(declarations, scope, qualifier);
+  if (winner === null || !accepts(winner) || scope.admits !== undefined && !scope.admits(winner))
+    return null;
+  return winner.ref;
+}
+function choose(declarations, scope, qualifier) {
   const { path } = scope;
   const visible = declarations.filter((declaration) => (scope.family === null || declaration.family === scope.family) && !(declaration.local && path !== null && declaration.path !== path) && (scope.sees === undefined || declaration.path === path || scope.sees(declaration.path)) && endsWith(declaration.owners, qualifier));
   const shared = new Set(visible.flatMap((declaration) => declaration.privateFile ? [] : [declaration.owners.join("\x00")]));
@@ -977,14 +983,14 @@ function pick(declarations, scope, qualifier = []) {
     return null;
   const [sameFile, otherInFile] = path === null ? [] : candidates.filter((declaration) => declaration.path === path);
   if (sameFile)
-    return otherInFile ? null : sameFile.ref;
+    return otherInFile ? null : sameFile;
   if (!second)
-    return first.ref;
+    return first;
   if (path === null)
     return null;
   const ranked = candidates.map((declaration) => ({ declaration, shared: sharedDirectories(declaration.path, path) })).sort((a, b) => b.shared - a.shared);
   const [best, runnerUp] = ranked;
-  return best && runnerUp && best.shared > runnerUp.shared ? best.declaration.ref : null;
+  return best && runnerUp && best.shared > runnerUp.shared ? best.declaration : null;
 }
 
 class TypeIndex {
@@ -1020,7 +1026,8 @@ class CallableIndex {
     if (!CALLABLE_NAME.test(text))
       return null;
     const key = text.replace(/\(\)$/, "").replace(/::|#/g, ".");
-    return pick(this.byName.get(key) ?? [], scope);
+    const bare = !key.includes(".");
+    return pick(this.byName.get(key) ?? [], scope, [], (site) => !bare || !site.member || site.path === scope.path);
   }
   resolveCall(name, scope, owner, qualifier = []) {
     if (owner === null) {
@@ -1080,7 +1087,7 @@ class TypeLinker {
     return { text, links };
   }
   mention(text, from, scope, relation = "mentions") {
-    if (scope.typeParameters.has(text))
+    if (scope.typeParameters.has(text) || scope.locals?.has(text))
       return null;
     const anywhere = { ...scope, sees: undefined };
     const qualified = QUALIFIED_NAME.test(text) ? text.split(/::|\./) : null;
@@ -1155,6 +1162,14 @@ var BINDING_TYPES = new Set([
   "lambda_literal",
   "closure_expression"
 ]);
+function sight(found, call, node) {
+  const line = node.startPosition.row + 1;
+  const known = found.get(keyOf(call));
+  if (!known)
+    found.set(keyOf(call), { call, lines: [line] });
+  else if (!known.lines.includes(line))
+    known.lines.push(line);
+}
 function readReferences(body, definitions) {
   const calls = new Map;
   const passes = new Map;
@@ -1167,12 +1182,12 @@ function readReferences(body, definitions) {
     if (CALL_TYPES.has(node.type)) {
       const call = callOf(node);
       if (call)
-        calls.set(keyOf(call), call);
+        sight(calls, call, node);
     }
     for (const value of valuesOf(node)) {
       const passed = passedOf(value);
       if (passed)
-        passes.set(keyOf(passed), passed);
+        sight(passes, passed, value);
     }
     const declared = LOCAL_DECLARATIONS[node.type];
     if (declared) {
@@ -1193,8 +1208,12 @@ function readReferences(body, definitions) {
     }
   }
   return {
-    calls: [...calls.values()].map((call) => call.via === "member" && call.qualifier.some((name) => locals.has(name)) ? { ...call, qualifier: [] } : call),
-    passes: [...passes.values()].filter((value) => !bindsName(bound, value))
+    calls: [...calls.values()].map(({ call, lines }) => ({
+      ...call,
+      qualifier: call.via === "member" && call.qualifier.some((name) => locals.has(name)) ? [] : call.qualifier,
+      lines: lines.sort((a, b) => a - b)
+    })),
+    passes: [...passes.values()].filter(({ call }) => !bindsName(bound, call)).map(({ call, lines }) => ({ ...call, lines: lines.sort((a, b) => a - b) }))
   };
 }
 function bindsName(bound, value) {
@@ -1335,7 +1354,7 @@ class CallLinker {
       const target = this.resolve(call, context);
       if (target === null || target === from || kind === "passes" && this.accessors.has(target))
         continue;
-      this.graph.link(from, kind, target);
+      this.graph.link(from, kind, target, call.lines);
     }
   }
   registerAccessor(method) {
@@ -2706,6 +2725,7 @@ class SourceFileIndex {
   entryPoints = new Map;
   resolved = new Map;
   seen = new Map;
+  declarations = new Map;
   add(path, ref, syntax, requests, exports) {
     const normalized = posix3.normalize(path);
     this.entries.set(normalized, { ref, syntax, requests, exports });
@@ -2739,6 +2759,12 @@ class SourceFileIndex {
   exportsOf(path) {
     return this.entries.get(posix3.normalize(path))?.exports ?? NO_EXPORTS;
   }
+  exportsName(path, name) {
+    const entry = this.entries.get(posix3.normalize(path));
+    if (entry?.syntax?.readExports === undefined)
+      return true;
+    return entry.exports.declared.some((declared) => declared.name === name);
+  }
   refOf(path) {
     return this.entries.get(posix3.normalize(path))?.ref;
   }
@@ -2755,17 +2781,72 @@ class SourceFileIndex {
     const known = this.resolved.get(normalized);
     if (known)
       return known;
-    const entry = this.entries.get(normalized);
     const imported = new Set;
-    for (const request of entry?.syntax ? entry.requests : []) {
-      const target = request.map((specifier) => entry?.syntax?.resolve(specifier, normalized, this) ?? null).find((found) => found !== null);
-      if (target && target !== normalized)
-        imported.add(target);
-    }
+    for (const { file } of this.resolvedRequests(normalized))
+      if (file !== normalized)
+        imported.add(file);
     const result = [...imported];
     this.resolved.set(normalized, result);
     return result;
   }
+  importLinksOf(path) {
+    const normalized = posix3.normalize(path);
+    const links = new Map;
+    const add = (to, line) => {
+      if (to !== undefined)
+        links.set(to, [...links.get(to) ?? [], line]);
+    };
+    for (const { file, target, line } of this.resolvedRequests(normalized)) {
+      if (file === normalized)
+        continue;
+      const fileRef = this.refOf(file);
+      if (target.whole)
+        add(fileRef, line);
+      for (const name of target.names)
+        add(this.declarationOf(file, name, new Set) ?? fileRef, line);
+    }
+    return [...links].map(([to, lines]) => ({ to, lines: [...new Set(lines)] }));
+  }
+  resolvedRequests(path) {
+    const entry = this.entries.get(path);
+    const syntax = entry?.syntax;
+    if (!syntax)
+      return [];
+    return entry.requests.flatMap(({ targets, line }) => {
+      for (const target of targets) {
+        const file = syntax.resolve(target.specifier, path, this);
+        if (file !== null)
+          return [{ file, target, line }];
+      }
+      return [];
+    });
+  }
+  declare(path, name, ref) {
+    const normalized = posix3.normalize(path);
+    const names = this.declarations.get(normalized) ?? new Map;
+    if (!names.has(name))
+      names.set(name, ref);
+    this.declarations.set(normalized, names);
+  }
+  declarationOf(path, name, visited) {
+    if (visited.has(path))
+      return null;
+    visited.add(path);
+    const { declared, reexports } = this.exportsOf(path);
+    const local = declared.find((entry) => entry.as === name);
+    if (local)
+      return this.declarations.get(path)?.get(local.name) ?? null;
+    for (const { specifier, names } of reexports) {
+      const handed = names === null ? name : names.find((entry) => entry.as === name)?.name;
+      if (handed === undefined)
+        continue;
+      const target = this.resolveImport(specifier, path);
+      const found = target === null ? null : this.declarationOf(target, handed, visited);
+      if (found !== null)
+        return found;
+    }
+    return this.entries.get(path)?.syntax?.readExports === undefined ? this.declarations.get(path)?.get(name) ?? null : null;
+  }
   tracksImports(path) {
     return (this.entries.get(posix3.normalize(path))?.syntax ?? null) !== null;
   }
@@ -2811,7 +2892,7 @@ var C_INCLUDES = {
     if (!path)
       return [];
     const text = path.type === "system_lib_string" ? path.text.slice(1, -1) : path.text.replace(/^"|"$/g, "");
-    return text ? [[text]] : [];
+    return text ? [{ targets: [{ specifier: text, whole: true, names: [] }], line: include.startPosition.row + 1 }] : [];
   }),
   resolve: (specifier, from, files) => {
     const local = besides(from, specifier);
@@ -2832,7 +2913,7 @@ var ECMASCRIPT_IMPORTS = {
       const source = node.type === "call_expression" ? dynamicSource(node) : node.childForFieldName("source") ?? requireClause(node)?.childForFieldName("source") ?? null;
       const text = source?.namedChildren.find((child) => child?.type === "string_fragment")?.text;
       if (text)
-        requests.push([text]);
+        requests.push({ targets: [{ specifier: text, ...takenFrom(node) }], line: node.startPosition.row + 1 });
     }
     return requests;
   },
@@ -2877,6 +2958,20 @@ function packageBases(specifier, files) {
   const rest = segments.slice(nameLength).join("/") || "index";
   return [posix3.join(directory, "src", rest), posix3.join(directory, rest)];
 }
+function takenFrom(statement) {
+  if (statement.type === "call_expression" || requireClause(statement) !== null)
+    return { whole: true, names: [] };
+  const clause = statement.namedChildren.find((child) => child?.type === "import_clause" || child?.type === "export_clause");
+  if (!clause)
+    return { whole: true, names: [] };
+  const specifier = clause.type === "import_clause" ? "import_specifier" : "export_specifier";
+  const names = clause.descendantsOfType(specifier).flatMap((entry) => {
+    const name = entry?.childForFieldName("name")?.text;
+    return name === undefined ? [] : [name];
+  });
+  const whole = clause.namedChildren.some((child) => child?.type === "identifier" || child?.type === "namespace_import");
+  return { whole, names };
+}
 function requireClause(statement) {
   return statement.namedChildren.find((child) => child?.type === "import_require_clause") ?? null;
 }
@@ -2897,15 +2992,22 @@ var PYTHON_IMPORTS = {
         const dotted = name?.type === "aliased_import" ? name.childForFieldName("name") : name;
         return dotted ? [dotted.text] : [];
       });
+      const line = node.startPosition.row + 1;
       if (node.type === "import_statement") {
-        requests.push(...names.map((name) => [name]));
+        requests.push(...names.map((name) => ({ targets: [{ specifier: name, whole: true, names: [] }], line })));
         continue;
       }
       const module = node.childForFieldName("module_name")?.text;
       if (!module)
         continue;
       const separator = module.endsWith(".") ? "" : ".";
-      requests.push(...names.length > 0 ? names.map((name) => [`${module}${separator}${name}`, module]) : [[module]]);
+      requests.push(...names.length > 0 ? names.map((name) => ({
+        targets: [
+          { specifier: `${module}${separator}${name}`, whole: true, names: [] },
+          { specifier: module, whole: false, names: [name] }
+        ],
+        line
+      })) : [{ targets: [{ specifier: module, whole: true, names: [] }], line }]);
     }
     return requests;
   },
@@ -3954,11 +4056,8 @@ class CodePlanner {
     return ref;
   }
   linkImports(from, path) {
-    for (const target of this.sources.importsOf(path)) {
-      const ref = this.sources.refOf(target);
-      if (ref !== undefined)
-        this.graph.link(from, "imports", ref);
-    }
+    for (const { to, lines } of this.sources.importLinksOf(path))
+      this.graph.link(from, "imports", to, lines);
   }
   async extract(file) {
     if (!this.registry.supports(file.path))
@@ -4064,6 +4163,7 @@ function terminate(style, statement) {
 
 // src/scanner/code/symbols.ts
 var CONSTRUCTIBLE2 = new Set(["class", "struct"]);
+var TEST_FILE = /(?:^|\/)(?:tests?|__tests__)\/|[._]test\.\w+$|\.spec\.\w+$|(?:^|\/)test_[^/]*\.py$/;
 
 class SymbolPlanner {
   graph;
@@ -4109,16 +4209,23 @@ class SymbolPlanner {
     const isConstructor = scope.parent !== null && spec.constructorNames(scope.parent.name).includes(symbol.name);
     const ownerDoc = isConstructor ? parseDoc(spec.docStyle, scope.parent?.comment ?? "") : null;
     const family = familyOf(spec);
+    const parameters = plannedParameters(symbol, doc, ownerDoc);
+    const fields = plannedFields(symbol, doc, spec);
     const typeScope = {
       path: file.path,
       family,
       typeParameters: new Set([...scope.typeParameters, ...symbol.typeParameters]),
       namespaceSeparator: spec.namespaceSeparator,
-      sees: (path) => this.sources.sees(file.path, path)
+      sees: (path) => this.sources.sees(file.path, path),
+      admits: (declaration) => this.admits(file.path, declaration),
+      locals: new Set([...parameters, ...fields].map((declaration) => declaration.name))
     };
     const ref = this.graph.add(symbol.kind, { name: symbol.name, parent: scope.parentRef, anchor }, (self) => this.symbolContent(symbol, doc, scope, typeScope, self));
     const privateFile = spec.isPrivateFile?.(file.path) ?? false;
-    const site = { ref, path: file.path, family, owners: scope.owners, privateFile };
+    const exported = this.sources.exportsName(file.path, scope.owners[0] ?? symbol.name);
+    const site = { ref, path: file.path, family, owners: scope.owners, privateFile, exported };
+    if (scope.parent === null)
+      this.sources.declare(file.path, symbol.name, ref);
     if (TYPE_KINDS.has(symbol.kind) && !symbol.inferred) {
       const outOfLine = scope.parent !== null && scope.parent.inferred && TYPE_KINDS.has(scope.parent.kind);
       this.types.register(symbol.name, { ...site, local: privateFile && !outOfLine });
@@ -4130,10 +4237,10 @@ class SymbolPlanner {
       if (symbol.accessor)
         this.calls.registerAccessor(ref);
     }
-    for (const parameter of plannedParameters(symbol, doc, ownerDoc)) {
+    for (const parameter of parameters) {
       this.graph.add("parameter", { name: parameter.name, parent: ref }, (self) => this.declarationContent(parameter, self, file, typeScope));
     }
-    for (const field of plannedFields(symbol, doc, spec)) {
+    for (const field of fields) {
       this.graph.add("field", { name: field.name, parent: ref }, async (self) => ({
         ...await this.declarationContent(field, self, file, typeScope),
         annotations: field.annotations
@@ -4152,6 +4259,11 @@ class SymbolPlanner {
     for (const child of symbol.children)
       this.planSymbol(child, inner);
   }
+  admits(from, declaration) {
+    if (TEST_FILE.test(declaration.path) && !TEST_FILE.test(from))
+      return false;
+    return declaration.exported || this.sources.packageOf(declaration.path) === this.sources.packageOf(from);
+  }
   async symbolContent(symbol, doc, scope, typeScope, self) {
     const { spec } = scope.file;
     if (symbol.heritage)
@@ -4953,8 +5065,10 @@ class GraphBuilder {
     const route = routeOf(this.identities, ref);
     return hrefOf(fragment ? { path: route.path, hash: fragment } : route);
   }
-  link(from, kind, to) {
-    this.edges.set(`${from}:${kind}:${to}`, [from, kind, to]);
+  link(from, kind, to, lines = []) {
+    const key = `${from}:${kind}:${to}`;
+    const merged = [...new Set([...this.edges.get(key)?.[3] ?? [], ...lines])].sort((a, b) => a - b);
+    this.edges.set(key, merged.length > 0 ? [from, kind, to, merged] : [from, kind, to]);
   }
   async build() {
     this.keepOnePackagePerDirectory();
@@ -8257,7 +8371,7 @@ async function prepareOutputDir(repo) {
 // package.json
 var package_default = {
   name: "@g3nomaly/analyze",
-  version: "0.1.6",
+  version: "0.1.7",
   description: "Turns a repository into one offline HTML documentation site, and queries the same linked model from the terminal and from hooks.",
   keywords: [
     "documentation",
@@ -9410,19 +9524,51 @@ function stepsOf(graph, node, direction, kinds) {
   const members = graph.children(node).filter((child) => isDeclarationKind(graph.node(child).kind));
   const edges = [node, ...members].flatMap((end) => direction === "out" ? graph.edgesFrom(end) : graph.edgesTo(end)).filter((edge) => kinds.length === 0 || kinds.includes(edge[1]));
   const end = direction === "out" ? 2 : 0;
-  const seen = new Set;
-  return edges.flatMap((edge) => {
+  const steps = new Map;
+  for (const edge of edges) {
     const { owner } = ownerOf(graph, edge[end]);
     const via = edge[1] === "type" ? ownerOf(graph, edge[0]).via : null;
     const key = `${edge[1]} ${owner} ${via ?? ""}`;
-    if (seen.has(key))
-      return [];
-    seen.add(key);
-    return [{ relation: edge[1], node: owner, via }];
-  });
+    const known = steps.get(key);
+    const lines = [...new Set([...known?.lines ?? [], ...edge[3] ?? []])].sort((a, b) => a - b);
+    steps.set(key, { relation: edge[1], node: owner, via, source: known?.source ?? edge[0], lines });
+  }
+  return [...steps.values()];
+}
+function fileOf(graph, node) {
+  for (const ref of [node, ...graph.ancestors(node).reverse()]) {
+    const value = graph.node(ref);
+    if (value.kind === "source" || isFileNode(value))
+      return ref;
+  }
+  return node;
+}
+function fileStepsOf(graph, file, direction, kinds) {
+  const end = direction === "out" ? 2 : 0;
+  const steps = new Map;
+  for (const inner of [file, ...graph.descendants(file)]) {
+    for (const edge of direction === "out" ? graph.edgesFrom(inner) : graph.edgesTo(inner)) {
+      if (kinds.length > 0 && !kinds.includes(edge[1]))
+        continue;
+      const other = fileOf(graph, edge[end]);
+      if (other === file)
+        continue;
+      const key = `${edge[1]} ${other}`;
+      const known = steps.get(key);
+      const lines = [...new Set([...known?.lines ?? [], ...edge[3] ?? []])].sort((a, b) => a - b);
+      steps.set(key, { relation: edge[1], node: other, via: null, source: known?.source ?? edge[0], lines });
+    }
+  }
+  return [...steps.values()];
 }
 function referenceOf(graph, step) {
-  return { relation: step.relation, node: summarize(graph, step.node), via: step.via };
+  const path = step.lines.length > 0 ? pathOf(graph, step.source) : null;
+  return {
+    relation: step.relation,
+    node: summarize(graph, step.node),
+    via: step.via,
+    location: path === null ? null : { path, lines: step.lines }
+  };
 }
 function referencesOf(graph, node, options) {
   const { direction, kinds } = options;
@@ -9520,7 +9666,9 @@ function describeNode(graph, node) {
   };
 }
 // src/retrieval/walk.ts
+init_model();
 var DEFAULT_WALK_LIMIT = 50;
+var WALK_LEVELS = ["entries", "files"];
 function walkReferences(graph, start, options) {
   const directions = ["out", "in"].filter((direction) => options.direction === "both" || options.direction === direction).map((direction) => {
     const root = [];
@@ -9529,7 +9677,7 @@ function walkReferences(graph, start, options) {
   let left = options.limit;
   let omitted = 0;
   for (let hop = 1;hop <= options.depth; hop++) {
-    const candidates = directions.map((walk) => walk.frontier.flatMap(({ node, into }) => stepsOf(graph, node, walk.direction, options.kinds).map((step) => ({ step, into }))));
+    const candidates = directions.map((walk) => walk.frontier.flatMap(({ node, into }) => (options.level === "files" ? fileStepsOf : stepsOf)(graph, node, walk.direction, options.kinds).map((step) => ({ step, into }))));
     const frontiers = directions.map(() => []);
     const longest = Math.max(0, ...candidates.map((list) => list.length));
     for (let index = 0;index < longest; index++) {
@@ -9563,19 +9711,27 @@ function walkReferences(graph, start, options) {
     omitted
   };
 }
-function shortestPath(graph, from, to, kinds) {
-  const reached = new Map([[from, null]]);
+function shortestPath(graph, from, to, kinds, includeMentions = false) {
+  const follows = kinds.length > 0 || includeMentions ? kinds : EDGE_KINDS.filter((kind) => kind !== "mentions");
+  const reached = new Map([
+    [from, null]
+  ]);
   for (let frontier = [from];frontier.length > 0 && !reached.has(to); ) {
-    const next = [];
+    const hop = new Map;
     for (const node of frontier) {
-      for (const step of stepsOf(graph, node, "out", kinds)) {
+      const before = reached.get(node)?.mentions ?? 0;
+      for (const step of stepsOf(graph, node, "out", follows)) {
         if (reached.has(step.node))
           continue;
-        reached.set(step.node, { previous: node, step });
-        next.push(step.node);
+        const mentions = before + (step.relation === "mentions" ? 1 : 0);
+        const known = hop.get(step.node);
+        if (known === undefined || mentions < known.mentions)
+          hop.set(step.node, { previous: node, step, mentions });
       }
     }
-    frontier = next;
+    for (const [node, way] of hop)
+      reached.set(node, way);
+    frontier = [...hop.keys()];
   }
   if (!reached.has(to))
     return null;
@@ -9970,8 +10126,11 @@ class Retriever {
   walk(node, options) {
     return walkReferences(this.graph, node, options);
   }
-  path(from, to, kinds) {
-    return shortestPath(this.graph, from, to, kinds);
+  fileOf(node) {
+    return fileOf(this.graph, node);
+  }
+  path(from, to, kinds, includeMentions = false) {
+    return shortestPath(this.graph, from, to, kinds, includeMentions);
   }
   exportGraph(options) {
     return exportGraph(this.graph, options);
@@ -10287,9 +10446,15 @@ ${wrap2(ALL_NODE_KINDS.join(", "), 21)}
   --outgoing         refs: only what the node links to.
   --depth <n>        refs: hops to follow from the node. Default: 1.
   --edge <kind>      refs, path, graph: only edges of this kind, from the list below. Repeatable.
+                     path follows every kind but mentions when no --edge is given.
+  --include-mentions path: also follow mentions, the links descriptions make. Of equally
+                     short chains, the one with the fewest mentions still wins.
   --level <level>    graph: ${either(EXPORT_LEVELS)}. Default: ${DEFAULT_EXPORT_LEVEL}. packages and
                      communities sum the edges between packages or communities; files, entries
                      and all are the levels of the graph page of the site.
+                     refs: ${either(WALK_LEVELS)}. Default: entries. files lists the links between
+                     the file of the node and other files, as the files level of the graph page
+                     draws them.
 
 Environment: ANALYZE_REPO, ANALYZE_TITLE, ANALYZE_OUT, ANALYZE_SKILLS, ANALYZE_DOCS,
 ANALYZE_EXCLUDE, ANALYZE_EMBEDDINGS (on or off) and ANALYZE_FROM set the same options. A
@@ -10312,7 +10477,8 @@ var FLAG_COMMANDS = {
   outgoing: ["refs"],
   depth: ["refs"],
   edge: ["refs", "path", "graph"],
-  level: ["graph"]
+  "include-mentions": ["path"],
+  level: ["graph", "refs"]
 };
 var SCAN_FLAGS = ["repo", "skills", "docs", "exclude", "no-embeddings", "no-cache"];
 function expandHome(path) {
@@ -10419,7 +10585,7 @@ function parseInvocation(argv, env, cwd) {
       throw new UsageError("path takes two nodes. Run: g3n-analyze path <from> <to>, with quotes around a name with spaces.");
     }
     const [start = "", end = ""] = words;
-    return { ...base, kind: "path", start, end, edges };
+    return { ...base, kind: "path", start, end, edges, includeMentions: values["include-mentions"] === true };
   }
   if (text.length === 0)
     throw new UsageError(`Missing node. Run: g3n-analyze ${command} <node>`);
@@ -10435,7 +10601,8 @@ function parseInvocation(argv, env, cwd) {
       direction: values.incoming ? "in" : values.outgoing ? "out" : "both",
       kinds: edges,
       depth: countOf(values.depth, "depth") ?? 1,
-      limit: countOf(values.limit, "limit") ?? DEFAULT_WALK_LIMIT
+      limit: countOf(values.limit, "limit") ?? DEFAULT_WALK_LIMIT,
+      level: values.level === undefined ? "entries" : oneOf(values.level, WALK_LEVELS, "level")
     }
   };
 }
@@ -10475,6 +10642,7 @@ function parse(argv) {
       depth: { type: "string" },
       edge: { type: "string", multiple: true },
       level: { type: "string" },
+      "include-mentions": { type: "boolean" },
       help: { type: "boolean", short: "h" },
       version: { type: "boolean", short: "v" }
     }
@@ -10536,16 +10704,23 @@ var pathSchema = z11.strictObject({
   ...warningShape,
   start: z11.string().trim().min(1),
   end: z11.string().trim().min(1),
-  edges: z11.array(z11.enum(EDGE_KINDS)).readonly().optional()
+  edges: z11.array(z11.enum(EDGE_KINDS)).readonly().optional(),
+  includeMentions: z11.boolean().optional()
 }).superRefine(checkSource).transform((fields) => ({
   source: sourceOf(fields),
   reporter: reporterOf(fields.onWarning),
-  request: { start: fields.start, end: fields.end, filter: filterOf(fields), kinds: fields.edges ?? [] }
+  request: {
+    start: fields.start,
+    end: fields.end,
+    filter: filterOf(fields),
+    kinds: fields.edges ?? [],
+    includeMentions: fields.includeMentions ?? false
+  }
 }));
 function pathIn(retriever, request) {
   const start = nodeOf(retriever, request.start, request.filter);
   const end = nodeOf(retriever, request.end, request.filter);
-  const steps = retriever.path(start, end, request.kinds);
+  const steps = retriever.path(start, end, request.kinds, request.includeMentions);
   if (steps === null) {
     const edges = request.kinds.length > 0 ? ` along ${request.kinds.join(", ")} edges` : "";
     throw new QueryError(`No path from "${request.start}" to "${request.end}"${edges}. A path follows edges the way they point, so try the other order.`);
@@ -10569,7 +10744,8 @@ var refsSchema = z12.strictObject({
   outgoing: z12.boolean().optional(),
   edges: z12.array(z12.enum(EDGE_KINDS)).readonly().optional(),
   depth: z12.number().int().positive().optional(),
-  limit: z12.number().int().positive().optional()
+  limit: z12.number().int().positive().optional(),
+  level: z12.enum(WALK_LEVELS).optional()
 }).superRefine(checkSource).refine((fields) => !(fields.incoming && fields.outgoing), {
   message: "incoming and outgoing exclude each other",
   path: ["outgoing"]
@@ -10583,12 +10759,14 @@ var refsSchema = z12.strictObject({
       direction: fields.incoming ? "in" : fields.outgoing ? "out" : "both",
       kinds: fields.edges ?? [],
       depth: fields.depth ?? 1,
-      limit: fields.limit ?? DEFAULT_WALK_LIMIT
+      limit: fields.limit ?? DEFAULT_WALK_LIMIT,
+      level: fields.level ?? "entries"
     }
   }
 }));
 function refsIn(retriever, request) {
-  const node = nodeOf(retriever, request.target, request.filter);
+  const target = nodeOf(retriever, request.target, request.filter);
+  const node = request.walk.level === "files" ? retriever.fileOf(target) : target;
   return { node: retriever.summarize(node), ...retriever.walk(node, request.walk) };
 }
 async function refs(options) {
@@ -10618,6 +10796,7 @@ async function show(options) {
 
 // src/cli/render-text.ts
 init_model();
+import { posix as posix26 } from "path";
 function placeOf(node) {
   if (node.path === null)
     return "";
@@ -10650,8 +10829,13 @@ function summaryLine(node) {
   return node.summary ? `${head}: ${node.summary}` : head;
 }
 function referenceLine(reference) {
-  const { relation, via, node } = reference;
-  return `- ${relation}${via === null ? "" : ` via \`${via}\``}: ${labelOf(node)} (\`${node.id}\`)`;
+  const { node } = reference;
+  return `- ${relationText(reference)}: ${labelOf(node)} (\`${node.id}\`)`;
+}
+function relationText({ relation, via, location }) {
+  const through = via === null ? "" : ` via \`${via}\``;
+  const at = location === null ? "" : ` (${posix26.basename(location.path)}:${location.lines.join(", ")})`;
+  return `${relation}${through}${at}`;
 }
 function section(title, lines) {
   return lines.length === 0 ? [] : [`## ${title}`, lines.join(`
@@ -10671,15 +10855,22 @@ function referenceSections(references) {
     ...section(`Linked from (${references.linkedFrom.length})`, references.linkedFrom.map(referenceLine))
   ];
 }
-function walkLines(reference, depth) {
-  return [`${"  ".repeat(depth)}${referenceLine(reference)}`, ...reference.next.flatMap((next) => walkLines(next, depth + 1))];
-}
-function walkSize(reference) {
-  return 1 + reference.next.reduce((sum, next) => sum + walkSize(next), 0);
+function listLines(references, depth) {
+  const byNode = new Map;
+  for (const reference of references)
+    byNode.set(reference.node.id, [...byNode.get(reference.node.id) ?? [], reference]);
+  return [...byNode.values()].flatMap((group) => {
+    const [first] = group;
+    if (!first)
+      return [];
+    const relations = group.map(relationText).join(", ");
+    const line = `${"  ".repeat(depth)}- ${relations}: ${labelOf(first.node)} (\`${first.node.id}\`)`;
+    return [line, ...listLines(group.flatMap((reference) => reference.next), depth + 1)];
+  });
 }
 function walkSection(title, references) {
-  const count = references.reduce((sum, reference) => sum + walkSize(reference), 0);
-  return section(`${title} (${count})`, references.flatMap((reference) => walkLines(reference, 0)));
+  const lines = listLines(references, 0);
+  return section(`${title} (${lines.length})`, lines);
 }
 function contentText(content) {
   return content.map(({ mediaType, schema }) => schema === null ? mediaType : `${mediaType}: \`${schema}\``).join(", ");
@@ -10806,7 +10997,7 @@ function renderPath(result) {
   const title = `# path ${labelOf(start)} -> ${labelOf(end)} (${steps.length} ${steps.length === 1 ? "step" : "steps"})`;
   const lines = [
     `${labelOf(start)} (\`${start.id}\`)`,
-    ...steps.map(({ relation, via, node }) => `  -${relation}${via === null ? "" : ` via \`${via}\``}-> ${labelOf(node)} (\`${node.id}\`)`)
+    ...steps.map((step) => `  -${relationText(step)}-> ${labelOf(step.node)} (\`${step.node.id}\`)`)
   ];
   return [title, lines.join(`
 `)].join(`
@@ -10911,13 +11102,13 @@ async function runQuery(invocation, onWarning) {
       const { target, walk } = invocation;
       const incoming = walk.direction === "in";
       const outgoing = walk.direction === "out";
-      const { depth, limit } = walk;
-      const result = await refs({ ...common, target, incoming, outgoing, edges: walk.kinds, depth, limit });
+      const { depth, limit, level } = walk;
+      const result = await refs({ ...common, target, incoming, outgoing, edges: walk.kinds, depth, limit, level });
       return outputOf({ kind: "refs", result });
     }
     case "path": {
-      const { start, end, edges } = invocation;
-      return outputOf({ kind: "path", result: await path2({ ...common, start, end, edges }) });
+      const { start, end, edges, includeMentions } = invocation;
+      return outputOf({ kind: "path", result: await path2({ ...common, start, end, edges, includeMentions }) });
     }
     case "list":
       return outputOf({ kind: "list", result: await list2({ ...common, limit: invocation.limit ?? undefined }) });