@g3nomaly/analyze 0.1.6 → 0.1.7

package/dist/index.js

@@ -963,7 +963,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")]));
@@ -973,14 +979,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 {
@@ -1016,7 +1022,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) {
@@ -1076,7 +1083,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;
@@ -1151,6 +1158,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;
@@ -1163,12 +1178,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) {
@@ -1189,8 +1204,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) {
@@ -1331,7 +1350,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) {
@@ -2702,6 +2721,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 });
@@ -2735,6 +2755,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;
   }
@@ -2751,17 +2777,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;
   }
@@ -2807,7 +2888,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);
@@ -2828,7 +2909,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;
   },
@@ -2873,6 +2954,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;
 }
@@ -2893,15 +2988,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;
   },
@@ -3950,11 +4052,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))
@@ -4060,6 +4159,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;
@@ -4105,16 +4205,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 });
@@ -4126,10 +4233,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
@@ -4148,6 +4255,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)
@@ -4949,8 +5061,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();
@@ -8253,7 +8367,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",
@@ -9376,19 +9490,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;
@@ -9486,7 +9632,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 = [];
@@ -9495,7 +9643,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++) {
@@ -9529,19 +9677,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;
@@ -9936,8 +10092,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);
@@ -10191,16 +10350,23 @@ var pathSchema = z9.strictObject({
   ...warningShape,
   start: z9.string().trim().min(1),
   end: z9.string().trim().min(1),
-  edges: z9.array(z9.enum(EDGE_KINDS)).readonly().optional()
+  edges: z9.array(z9.enum(EDGE_KINDS)).readonly().optional(),
+  includeMentions: z9.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.`);
@@ -10223,7 +10389,8 @@ var refsSchema = z10.strictObject({
   outgoing: z10.boolean().optional(),
   edges: z10.array(z10.enum(EDGE_KINDS)).readonly().optional(),
   depth: z10.number().int().positive().optional(),
-  limit: z10.number().int().positive().optional()
+  limit: z10.number().int().positive().optional(),
+  level: z10.enum(WALK_LEVELS).optional()
 }).superRefine(checkSource).refine((fields) => !(fields.incoming && fields.outgoing), {
   message: "incoming and outgoing exclude each other",
   path: ["outgoing"]
@@ -10237,12 +10404,14 @@ var refsSchema = z10.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) {

package/dist/model/index.d.ts

@@ -661,8 +661,12 @@ export type DescribedNode = SymbolNode | OperationNode | DefinitionNode | TableN
  * @returns True for a symbol, an operation, a definition, a table and a query.
  */
 export declare function isDescribedNode(node: GraphNode): node is DescribedNode;
-/** A relation other than `parent` between two nodes, such as a parameter that has a class as its type. */
-export type Edge = readonly [from: NodeRef, kind: EdgeKind, to: NodeRef];
+/**
+ * A relation other than `parent` between two nodes, such as a parameter that has a class as its type. `lines` are
+ * the lines of the file of `from` where the link is made, in order, such as those of a call or an import. An edge
+ * with no line of its own leaves them out.
+ */
+export type Edge = readonly [from: NodeRef, kind: EdgeKind, to: NodeRef, lines?: readonly number[]];
 /**
  * What the bundle says about its own making.
  *

package/dist/retrieval/describe.d.ts

@@ -20,11 +20,16 @@ export declare const ALL_REFERENCES: ReferenceOptions;
  * @property relation - Kind of the edge.
  * @property node - The page or entry at the other end. A parameter or field there counts as its symbol.
  * @property via - For a `type` edge, the name of the parameter or field of the node it starts at, else `null`.
+ * @property source - Node the edge starts at, whose file holds `lines`.
+ * @property lines - Lines where the link is made, of every edge the step stands for, in order. Empty when the
+ *   edges record none.
  */
 export interface Step {
     readonly relation: EdgeKind;
     readonly node: NodeRef;
     readonly via: string | null;
+    readonly source: NodeRef;
+    readonly lines: readonly number[];
 }
 /**
  * @brief Lists the edges of a node in one direction, each once. The edges of its parameters and fields count as its
@@ -37,12 +42,34 @@ export interface Step {
  * @returns The steps in edge order.
  */
 export declare function stepsOf(graph: Graph, node: NodeRef, direction: 'in' | 'out', kinds: readonly EdgeKind[]): Step[];
+/**
+ * @brief Finds the file a node is in: the node itself when it is a file or a source file, else its closest such
+ * ancestor.
+ *
+ * @param graph - Graph the node belongs to.
+ * @param node - Any node.
+ * @returns The file, or the node itself when no file holds it, as for a folder or a package.
+ */
+export declare function fileOf(graph: Graph, node: NodeRef): NodeRef;
+/**
+ * @brief Lists the links of a file to other files in one direction, as the file level of the graph page draws
+ * them: every edge of the file and of the entries in it counts for the file, and every edge to another file or an
+ * entry in it counts for that file. Edges inside the file are left out. Nothing is stored for these links.
+ *
+ * @param graph - Graph the file belongs to.
+ * @param file - A file, as `fileOf` gives it.
+ * @param direction - `out` for what the file links to, `in` for what links to it.
+ * @param kinds - Edge kinds to keep. Empty keeps every kind.
+ * @returns One step per other file and edge kind, with the lines of every edge it stands for.
+ */
+export declare function fileStepsOf(graph: Graph, file: NodeRef, direction: 'in' | 'out', kinds: readonly EdgeKind[]): Step[];
 /**
  * @brief Turns a step into the reference a report shows.
  *
  * @param graph - Graph the step belongs to.
  * @param step - The step.
- * @returns The relation, the summary of the other node, and the parameter or field it runs through.
+ * @returns The relation, the summary of the other node, the parameter or field it runs through, and where the link
+ *   is made.
  */
 export declare function referenceOf(graph: Graph, step: Step): Reference;
 /**

package/dist/retrieval/index.d.ts

@@ -1,5 +1,5 @@
-export { ALL_REFERENCES, describeNode, type ReferenceOptions, referencesOf } from './describe';
-export { DEFAULT_WALK_LIMIT, shortestPath, type Walk, type WalkOptions, type WalkReference, walkReferences } from './walk';
+export { ALL_REFERENCES, describeNode, fileOf, type ReferenceOptions, referencesOf } from './describe';
+export { DEFAULT_WALK_LIMIT, shortestPath, WALK_LEVELS, type Walk, type WalkLevel, type WalkOptions, type WalkReference, walkReferences, } from './walk';
 export { NO_FILTER, type NodeFilter, nodeTest, resultOf, resultsOf } from './filter';
 export { COMMUNITY_MEMBERS, type CommunityMember, EXPORT_LEVELS, type ExportEdge, type ExportLevel, type ExportNode, type GraphExport, type GraphExportOptions, exportGraph, } from './graph-export';
 export { codeBlock, htmlToMarkdown } from './markdown';

package/dist/retrieval/report.d.ts

@@ -189,11 +189,18 @@ export interface TagReport {
  * @property relation - Kind of the edge.
  * @property node - The node at the other end. For a parameter or a field, the symbol that declares it.
  * @property via - Name of the parameter or field the edge starts at, when it does not start at a page or an entry.
+ * @property location - Where the link is made: the file of the node the edge starts at and the lines in it, e.g.
+ *   `{ path: "packages/core/src/cli/commands/add.ts", lines: [86] }` for a call. `null` when the edge records no
+ *   lines.
  */
 export interface Reference {
     readonly relation: EdgeKind;
     readonly node: NodeSummary;
     readonly via: string | null;
+    readonly location: {
+        readonly path: string;
+        readonly lines: readonly number[];
+    } | null;
 }
 /**
  * @brief Both directions of the edges of a node.

package/dist/retrieval/retriever.d.ts

@@ -165,15 +165,23 @@ export declare class Retriever {
      * @returns What the node links to and what links to it, each with its next hop, and how many the limit left out.
      */
     walk(node: NodeRef, options: WalkOptions): Walk;
+    /**
+     * @brief Finds the file a node is in.
+     *
+     * @param node - Any node.
+     * @returns The node itself when it is a file, else its closest file ancestor, else the node.
+     */
+    fileOf(node: NodeRef): NodeRef;
     /**
      * @brief Finds the shortest chain of edges from one node to another, following edges the way they point.
      *
      * @param from - The node the chain starts at.
      * @param to - The node the chain ends at.
-     * @param kinds - Edge kinds to follow. Empty follows every kind.
+     * @param kinds - Edge kinds to follow. Empty follows every kind but `mentions`, unless `includeMentions` is set.
+     * @param includeMentions - Whether an empty `kinds` follows `mentions` too.
      * @returns Each reference of the chain in order, or `null` when no chain leads from `from` to `to`.
      */
-    path(from: NodeRef, to: NodeRef, kinds: readonly EdgeKind[]): Reference[] | null;
+    path(from: NodeRef, to: NodeRef, kinds: readonly EdgeKind[], includeMentions?: boolean): Reference[] | null;
     /**
      * @brief Exports one level of the bundle as nodes and edges.
      *