@g3nomaly/analyze 0.1.5 → 0.1.7

package/dist/scanner/code/calls.d.ts

@@ -26,17 +26,40 @@ export interface RawCall {
     readonly qualifier: readonly string[];
 }
 /**
- * @brief Reads every call in a function body, each once, in the order they first appear.
+ * @brief A call or a passed value of a function body, with every line it is on.
  *
- * Calls inside a nested definition belong to that definition and are left out. Calls inside a lambda or a
- * closure belong to the function around it. A call through a variable the body declares itself keeps no
+ * @property lines - Lines of the file it is written on, in order, such as `[86, 112]` for a function called twice.
+ */
+export interface LocatedCall extends RawCall {
+    readonly lines: readonly number[];
+}
+/**
+ * @brief The calls in a function body, and the functions it passes on as values.
+ *
+ * @property calls - Every call, each once, in the order they first appear.
+ * @property passes - Every name the body hands on as a value without calling it, such as the callback in
+ *   `run(onDone)` or the entry of `{ add: addCommand }`, each once. A name the body binds itself is left out.
+ */
+export interface BodyReferences {
+    readonly calls: readonly LocatedCall[];
+    readonly passes: readonly LocatedCall[];
+}
+/**
+ * @brief Reads the calls of a function body, and the functions it passes on as values.
+ *
+ * Calls and values inside a nested definition belong to that definition and are left out. Those inside a lambda
+ * or a closure belong to the function around it. A call through a variable the body declares itself keeps no
  * variable, since that local may hide a parameter or field of the same name and its type is unknown.
  *
+ * A value counts when it is an argument of a call, an element of an array or a list, or the value of a key of an
+ * object or a dict, and names a function: `onDone`, `this.flush` or `Timer.once`. A name the body binds, as a
+ * local, a loop variable, a catch variable or a lambda parameter, never counts, since it is no function of the scan.
+ *
  * @param body - Body node of the function.
  * @param definitions - Ids of the definition nodes of the file.
- * @returns The calls the body makes.
+ * @returns The calls and the passed values of the body.
  */
-export declare function readCalls(body: Node, definitions: ReadonlySet<number>): RawCall[];
+export declare function readReferences(body: Node, definitions: ReadonlySet<number>): BodyReferences;
 /**
  * @brief What a call can be resolved with: where it is, the names around its function, and the declared types
  * of the variables it can go through.
@@ -55,7 +78,8 @@ export interface CallContext {
     readonly implicitReceiver: boolean;
 }
 /**
- * @brief Turns the calls of a function into `calls` edges to the functions of the scan they reach.
+ * @brief Turns the calls of a function into `calls` edges, and the functions it passes on into `passes` edges, to
+ * the functions of the scan they reach.
  *
  * A call only links when it names one function its file sees: one in the same file or in a file it imports, directly
  * or not. For a language whose imports the scan does not read, a bare call only reaches a free function of the same
@@ -63,13 +87,14 @@ export interface CallContext {
  * the declared type of the parameter or field it goes through, else a static method of a type of that name; a call
  * through any other expression links nowhere, since its type is unknown.
  *
- * Holds the indexes it resolves against, the graph it adds edges to, and the fields of each type. Created per scan
+ * Holds the indexes it resolves against, the graph it adds edges to, the fields of each type, and the getters and
+ * setters, which a value never hands on. Created per scan
  * by `RepositoryScanner` in `scanner/scanner.ts`; `SymbolPlanner` in `symbols.ts` registers the fields of each type
  * and links the calls of each function once every declaration is known.
  *
  * @example
  * const calls = new CallLinker(types, callables, sources, graph);
- * calls.link(functionRef, rawSymbol.calls, { scope, owners: ['geo'], variables: new Map() });
+ * calls.link(functionRef, rawSymbol.calls, { scope, owners: ['geo'], variables: new Map() }, 'calls');
  */
 export declare class CallLinker {
     private readonly types;
@@ -77,6 +102,7 @@ export declare class CallLinker {
     private readonly sources;
     private readonly graph;
     private readonly fields;
+    private readonly accessors;
     /**
      * Takes the indexes the calls resolve against and the graph the edges are added to.
      *
@@ -102,13 +128,22 @@ export declare class CallLinker {
      */
     fieldsAround(context: Pick<CallContext, 'scope' | 'owners'>): ReadonlyMap<string, string>;
     /**
-     * @brief Records a `calls` edge from `from` to each function its calls reach.
+     * @brief Records an edge from `from` to each function its calls or its passed values reach.
+     *
+     * A passed value resolves the way a call of the same name would.
      *
-     * @param from - Node of the calling function.
-     * @param calls - The calls in its body.
+     * @param from - Node of the function.
+     * @param calls - The calls in its body, or the values it passes on.
      * @param context - Where the function is.
+     * @param kind - `calls` for calls, `passes` for values passed on.
+     */
+    link(from: NodeRef, calls: readonly LocatedCall[], context: CallContext, kind: 'calls' | 'passes'): void;
+    /**
+     * @brief Records that a method is a getter or a setter, which a value names without handing it on.
+     *
+     * @param method - Node of the getter or setter.
      */
-    link(from: NodeRef, calls: readonly RawCall[], context: CallContext): void;
+    registerAccessor(method: NodeRef): void;
     /**
      * @brief The function one call reaches.
      *

package/dist/scanner/code/exports.d.ts

@@ -0,0 +1,70 @@
+import type { Node } from 'web-tree-sitter';
+import type { SourceFileIndex } from './imports';
+/**
+ * @brief One name an `export { … } from` statement hands on.
+ *
+ * @property name - Name the other file exports it under, such as `hashFile`.
+ * @property as - Name this file exports it under: the same name, or the alias of `name as alias`.
+ */
+export interface ReexportedName {
+    readonly name: string;
+    readonly as: string;
+}
+/**
+ * @brief One `export … from` statement.
+ *
+ * @property specifier - The file it names, as written, such as `./hash`.
+ * @property names - The names it hands on, or `null` for `export * from`, which hands on every name.
+ */
+export interface Reexport {
+    readonly specifier: string;
+    readonly names: readonly ReexportedName[] | null;
+}
+/**
+ * @brief What a file exports by name. A default export is left out.
+ *
+ * @property declared - What the file declares and exports itself, each with the name it is exported under:
+ *   `export function load()`, `export { load }` or `export { load as start }`.
+ * @property reexports - The `export … from` statements of the file in file order, and each `export { name }` of a name
+ *   the file imports, which hands that name on from the file it came from.
+ */
+export interface FileExports {
+    readonly declared: readonly ReexportedName[];
+    readonly reexports: readonly Reexport[];
+}
+/**
+ * @brief How code outside a package imports a symbol: by the package name, or one of its subpaths, and the name the
+ * entry file there exports.
+ *
+ * @property specifier - What the import names: the package, such as `@g3nomaly/skills`, or a subpath of it, such as
+ *   `@g3nomaly/core/hash`.
+ * @property name - Name the entry file exports the symbol under, such as `hashFile`.
+ */
+export interface PackageImport {
+    readonly specifier: string;
+    readonly name: string;
+}
+/** The exports of a file that exports nothing by name, or whose language has no exports. */
+export declare const NO_EXPORTS: FileExports;
+/**
+ * @brief Reads the exports of a JavaScript or TypeScript file.
+ *
+ * @param root - Root node of the parsed file.
+ * @returns The names it declares and exports, and the names it hands on from other files. `export default` and
+ *   `export * as name from` are left out, since neither exports a name of the other file.
+ */
+export declare function readEcmascriptExports(root: Node): FileExports;
+/**
+ * @brief Finds how code outside a package imports a symbol: through the first entry point of the package the file is
+ * in whose entry file exports the symbol, itself or through `export … from` statements.
+ *
+ * The entry points are the package name and the subpaths its manifest lists. The entry file of one is the file an
+ * import of it resolves to, such as `packages/core/src/hash/index.ts` for `@g3nomaly/core/hash`.
+ *
+ * @param sources - The source files and packages of the scan.
+ * @param path - Display path of the file that declares the symbol.
+ * @param name - Name the file declares the symbol under.
+ * @returns The specifier and the name the entry exports, or `null` when the file is in no package of the scan or
+ *   no entry file exports the symbol.
+ */
+export declare function packageImportOf(sources: SourceFileIndex, path: string, name: string): PackageImport | null;

package/dist/scanner/code/extract.d.ts

@@ -1,6 +1,7 @@
 import { type SymbolKind } from '../../model';
 import type { Node, Query } from 'web-tree-sitter';
-import { type RawCall } from './calls';
+import { type BodyReferences } from './calls';
+import { type FileExports } from './exports';
 import type { ImportRequest } from './imports';
 import type { LanguageSpec } from './language';
 /**
@@ -41,6 +42,8 @@ export interface RawField {
  * @brief One definition as found in the syntax tree, before rendering.
  *
  * @property kind - Kind of the symbol, such as `function`, `method`, `class` or `enum`.
+ * @property line - Line of the file where the declaration starts.
+ * @property endLine - Line of the file where the declaration ends.
  * @property signature - Declaration head. Empty when `inferred`.
  * @property modifiers - Keywords in front of the name, such as `export` or `static`.
  * @property comment - Cleaned doc comment text, or `null`.
@@ -54,13 +57,16 @@ export interface RawField {
  * @property returnsValue - True when a call to the symbol yields a value.
  * @property inferred - True for an owner type that is not declared in this file.
  * @property internal - True for a function only its own file can call, as the spec's `isInternal` decides.
+ * @property accessor - True for a getter or a setter, such as `get size()` or a Python `@property`. Reading it runs it.
  * @property calls - For a function or method: the calls in its body, each once.
+ * @property passes - For a function or method: the names its body passes on as values, each once.
  * @property children - Members nested under this symbol.
  */
-export interface RawSymbol {
+export interface RawSymbol extends BodyReferences {
     kind: SymbolKind;
     readonly name: string;
     readonly line: number;
+    readonly endLine: number;
     readonly signature: string;
     readonly modifiers: readonly string[];
     readonly annotations: readonly string[];
@@ -76,7 +82,7 @@ export interface RawSymbol {
     returnsValue: boolean;
     readonly inferred: boolean;
     readonly internal: boolean;
-    readonly calls: readonly RawCall[];
+    readonly accessor: boolean;
     readonly children: RawSymbol[];
 }
 /**
@@ -85,11 +91,13 @@ export interface RawSymbol {
  * @property symbols - Top-level symbols of the file, each with its members nested under it.
  * @property packageName - Package or namespace the file declares, or `null` when the language has none.
  * @property imports - The files the file imports, as it writes them. Empty for a language without `imports`.
+ * @property exports - The names the file exports. Empty for a language whose imports do not read exports.
  */
 export interface ExtractedFile {
     readonly symbols: RawSymbol[];
     readonly packageName: string | null;
     readonly imports: readonly ImportRequest[];
+    readonly exports: FileExports;
 }
 /**
  * @brief Turns a parsed file into a tree of {@link RawSymbol}s, driven by a {@link LanguageSpec}.

package/dist/scanner/code/imports.d.ts

@@ -1,12 +1,31 @@
 import type { Node } from 'web-tree-sitter';
 import type { NodeRef } from '../../model';
+import { type FileExports } from './exports';
 /**
- * @brief One import of a file: the paths it can stand for, most specific first. The first one that names a
- * file of the scan wins.
+ * @brief One way to read an import: the path it names, and what it takes from that file.
  *
- * `from .models import Booking` is `['.models.Booking', '.models']`: `Booking` may be a module of its own.
+ * @property specifier - The path as written, such as `./store`, `slam/pose.hpp` or `.models`.
+ * @property whole - Whether it takes the file as a whole: `import './x'`, `import * as x`, a default import,
+ *   `export * from`, `require('./x')`, an `#include`, or Python's `import a.b`.
+ * @property names - Names it takes from the file, as that file exports them: `['load']` for
+ *   `import { load as start } from './x'` or `export { load } from './x'`.
  */
-export type ImportRequest = readonly string[];
+export interface ImportTarget {
+    readonly specifier: string;
+    readonly whole: boolean;
+    readonly names: readonly string[];
+}
+/**
+ * @brief One import of a file: the ways it can be read, and the line it is on.
+ *
+ * @property targets - The ways to read it, most specific first. The first whose path names a file of the scan wins.
+ *   `from .models import Booking` gives the module `.models.Booking` as a whole, then the name `Booking` of `.models`.
+ * @property line - Line of the file the import starts on.
+ */
+export interface ImportRequest {
+    readonly targets: readonly ImportTarget[];
+    readonly line: number;
+}
 /**
  * @brief How a language names the files a file imports.
  *
@@ -21,6 +40,13 @@ export interface ImportSyntax {
      * @returns One request per import, as the file writes it.
      */
     read(root: Node): ImportRequest[];
+    /**
+     * @brief Reads the names a parsed file exports, for a language whose packages export names from an entry file.
+     *
+     * @param root - Root node of the parsed file.
+     * @returns The names it declares and exports, and the files it re-exports from.
+     */
+    readExports?(root: Node): FileExports;
     /**
      * @brief Finds the file an import names.
      *
@@ -43,15 +69,19 @@ export interface ImportSyntax {
  * @property entries - Each file by display path.
  * @property byName - Display paths of the files with each file name.
  * @property packages - Directory of each package of the scan, by the name its manifest gives.
+ * @property entryPoints - The subpaths each package is imported by, by the name its manifest gives.
  * @property resolved - Display paths each file imports, resolved on first use.
  * @property seen - Display paths each file sees, computed on first use.
+ * @property declarations - Node of each top-level declaration of each file, by display path and then by name.
  */
 export declare class SourceFileIndex {
     private readonly entries;
     private readonly byName;
     private packages;
+    private entryPoints;
     private readonly resolved;
     private readonly seen;
+    private readonly declarations;
     /**
      * @brief Adds a source file.
      *
@@ -59,8 +89,9 @@ export declare class SourceFileIndex {
      * @param ref - Node of the file.
      * @param syntax - How its language names imports, or `null` when its imports are not read.
      * @param requests - Its imports, as the file writes them.
+     * @param exports - The names it exports, from `readExports` of its language.
      */
-    add(path: string, ref: NodeRef, syntax: ImportSyntax | null, requests: readonly ImportRequest[]): void;
+    add(path: string, ref: NodeRef, syntax: ImportSyntax | null, requests: readonly ImportRequest[], exports: FileExports): void;
     /**
      * @brief Tells the index where each package of the scan is, so an import of a package by name finds its files.
      *
@@ -68,7 +99,15 @@ export declare class SourceFileIndex {
      */
     usePackages(packages: ReadonlyMap<string, {
         readonly packageName: string;
+        readonly entryPoints: readonly string[];
     }>): void;
+    /**
+     * @brief The subpaths a package is imported by.
+     *
+     * @param name - Name its manifest gives, such as `@g3nomaly/core`.
+     * @returns `''` for the name itself, then subpaths such as `hash`. `['']` for a package the scan does not have.
+     */
+    entryPointsOf(name: string): readonly string[];
     /**
      * @brief Directory of the package with a name.
      *
@@ -76,6 +115,36 @@ export declare class SourceFileIndex {
      * @returns Display path of its directory, `''` for the root, or `undefined` when the scan has no such package.
      */
     packageDirectory(name: string): string | undefined;
+    /**
+     * @brief Names the package a file is in: the package of the scan whose directory holds it most closely.
+     *
+     * @param path - Display path of a file.
+     * @returns The name its manifest gives, such as `@g3nomaly/core`, or `null` when no package holds the file.
+     */
+    packageOf(path: string): string | null;
+    /**
+     * @brief Finds the file one import of a file names, with the import syntax of that file's language.
+     *
+     * @param specifier - The import as written, such as `./hash` or `@g3nomaly/core`.
+     * @param from - Display path of the importing file.
+     * @returns Display path of the file, or `null` when the scan has none or the file's imports are not read.
+     */
+    resolveImport(specifier: string, from: string): string | null;
+    /**
+     * @brief The names a file exports.
+     *
+     * @param path - Display path of a file.
+     * @returns Its exports, empty for a file the scan does not have.
+     */
+    exportsOf(path: string): FileExports;
+    /**
+     * @brief Tells whether other files can import a name a file declares.
+     *
+     * @param path - Display path of the file.
+     * @param name - Name the file declares, such as `hashFile`.
+     * @returns True when the file exports the name, and always for a file whose exports the scan does not read.
+     */
+    exportsName(path: string, name: string): boolean;
     /**
      * @brief Node of the source file at `path`.
      *
@@ -104,6 +173,43 @@ export declare class SourceFileIndex {
      * @returns Display paths of the imported files, in the order the file imports them.
      */
     importsOf(path: string): readonly string[];
+    /**
+     * @brief What the imports of a file link to, each with the lines of the imports. An import of a whole file links
+     * to the file. An import by name links to the declaration of each name, through any `export … from` files in
+     * between, and to the file it names for a name that is no declaration of the scan, such as a constant.
+     *
+     * @param path - Display path of the importing file.
+     * @returns Each node the file imports, once, with the lines of the imports that reach it, in file order.
+     */
+    importLinksOf(path: string): {
+        readonly to: NodeRef;
+        readonly lines: readonly number[];
+    }[];
+    /**
+     * @brief Each import of a file that names a file of the scan, with that file and the way of reading it that won.
+     *
+     * @param path - Normalized display path of the importing file.
+     * @returns Every such import in file order.
+     */
+    private resolvedRequests;
+    /**
+     * @brief Records a top-level declaration of a file, so an import of its name can reach its node. The first
+     * declaration of a name wins, as for the overloads of one function.
+     *
+     * @param path - Display path of the file.
+     * @param name - Name it is declared with, such as `hashFile`.
+     * @param ref - Node of the declaration.
+     */
+    declare(path: string, name: string, ref: NodeRef): void;
+    /**
+     * @brief The declaration a file hands out under a name: its own, or one it re-exports from another file.
+     *
+     * @param path - Display path of the file.
+     * @param name - Name the file exports, such as `recordedHashes`.
+     * @param visited - Files already followed, so a cycle of re-exports ends.
+     * @returns Node of the declaration, or `null` when the file exports no declaration of the scan under the name.
+     */
+    private declarationOf;
     /**
      * @brief Tells whether the scan reads the imports of a file, so what it sees is known.
      *

package/dist/scanner/code/language.d.ts

@@ -1,5 +1,6 @@
 import type { SymbolKind } from '../../model';
 import type { Node } from 'web-tree-sitter';
+import type { PackageImport } from './exports';
 import type { ImportSyntax } from './imports';
 /**
  * @brief Doc comment dialect, which decides how the scanner reads doc comments.
@@ -35,6 +36,8 @@ export interface DefinitionFacts {
  * @property kind - Kind of that outermost symbol.
  * @property modifiers - Keywords in front of the name, such as `export` or `default`.
  * @property packageName - Package or namespace the file declares with a statement, e.g. `a.b` for Java's `package a.b;`, or `null`.
+ * @property packageImport - For a symbol the entry file of its package exports, the package name and the name it is
+ *   exported under, as code outside the package imports it. `null` when no package of the scan exports it.
  */
 export interface ImportContext {
     readonly filePath: string;
@@ -42,6 +45,7 @@ export interface ImportContext {
     readonly kind: SymbolKind;
     readonly modifiers: readonly string[];
     readonly packageName: string | null;
+    readonly packageImport: PackageImport | null;
 }
 /**
  * How a language spells a call. Drives generated examples.

package/dist/scanner/code/planner.d.ts

@@ -102,7 +102,8 @@ export declare class CodePlanner {
      */
     private add;
     /**
-     * @brief Records an `imports` edge from a file to each file of the scan it imports.
+     * @brief Records an `imports` edge from a file to each file it imports as a whole and to each declaration it
+     * imports by name, with the lines of its imports.
      *
      * @param from - Node of the importing file.
      * @param path - Display path of the importing file.

package/dist/scanner/code/symbols.d.ts

@@ -73,6 +73,14 @@ export declare class SymbolPlanner {
      * @param scope - Where the symbol sits in the file.
      */
     private planSymbol;
+    /**
+     * @brief Tells whether a name in a file can mean a declaration: only a test file reaches into test files, and only
+     * the package of a declaration reaches one it does not export.
+     *
+     * @param from - Display path of the file the name is in.
+     * @param declaration - Declaration the name may mean.
+     */
+    private admits;
     /**
      * @brief Builds the content of a symbol node: highlighted signature, rendered description,
      * return value, tags and example.
@@ -88,8 +96,8 @@ export declare class SymbolPlanner {
      */
     private symbolContent;
     /**
-     * @brief Records the `calls` edges of a function, with its parameters and the fields of its type as the
-     * variables a call can go through.
+     * @brief Records the `calls` and `passes` edges of a function, with its parameters and the fields of its type as
+     * the variables a call can go through. A parameter passed on by name is a value, never a function of the scan.
      *
      * @param symbol - The calling function.
      * @param scope - Where the function sits in the file.

package/dist/scanner/code/types.d.ts

@@ -10,6 +10,11 @@ import type { GraphBuilder } from '../graph/builder';
  *   `namespaceSeparator`. Unset where a qualifier may be a module or a variable, which says nothing about the declaration.
  * @property sees - Tells whether the file of the name sees a file, through what it imports. Unset where every file
  *   counts, as for prose.
+ * @property admits - Tells whether the name can mean the declaration it resolves to, whether the file sees it or
+ *   not: one that another package does not export, or a test helper outside the tests, it cannot. Unset where every
+ *   declaration can, as for prose.
+ * @property locals - Names the symbol of a description declares itself, its parameters and fields. Inline code with
+ *   one of these names means that one, so it never links. Unset outside descriptions.
  */
 export interface TypeScope {
     readonly path: string | null;
@@ -17,6 +22,8 @@ export interface TypeScope {
     readonly typeParameters: ReadonlySet<string>;
     readonly namespaceSeparator?: string;
     readonly sees?: (path: string) => boolean;
+    readonly admits?: (declaration: DeclarationSite) => boolean;
+    readonly locals?: ReadonlySet<string>;
 }
 /** Scope of a name in a document: any language, no file. */
 export declare const PROSE_SCOPE: TypeScope;
@@ -30,6 +37,8 @@ export declare const PROSE_SCOPE: TypeScope;
  * @property local - Whether only its own file can see it, as a type in a C++ source file or a `static` C function.
  * @property privateFile - Whether its file is one the other files cannot see, such as a C++ source file. A
  *   declaration there that has a twin in a header is the definition of that twin.
+ * @property exported - Whether other files can import it: its file exports its outermost name, or its language has
+ *   no exports the scan reads.
  */
 export interface DeclarationSite {
     readonly ref: NodeRef;
@@ -38,6 +47,7 @@ export interface DeclarationSite {
     readonly owners: readonly string[];
     readonly local: boolean;
     readonly privateFile: boolean;
+    readonly exported: boolean;
 }
 /**
  * @brief Every class, interface, struct, enum, trait and type alias of the scan, by name.
@@ -100,6 +110,9 @@ export declare class CallableIndex {
     /**
      * @brief The function a piece of inline code names.
      *
+     * A bare name names a method only in the file of that method. Elsewhere a method is named with its owner, as
+     * `Invoice.add`.
+     *
      * @param text - Inline code, such as `choose_route()` or `Invoice.add`.
      * @param scope - Where the code is used.
      * @returns The function, or `null` when the text names none or more than one.
@@ -179,7 +192,8 @@ export declare class TypeLinker {
      * @param from - Node the code is written in. The edge starts here.
      * @param scope - Where the code is used.
      * @param relation - Kind of edge to record, `mentions` by default.
-     * @returns The node the code names, or `null` when it names none, more than one, or `from` itself.
+     * @returns The node the code names, or `null` when it names none, more than one, a parameter or field of the
+     *   symbol it describes, or `from` itself.
      */
     mention(text: string, from: NodeRef, scope: TypeScope, relation?: EdgeKind): NodeRef | null;
 }

package/dist/scanner/files.d.ts

@@ -58,7 +58,9 @@ export declare class RepoFileLister implements FileLister {
      */
     private isExcluded;
     /**
-     * @brief Lists the tracked and untracked files git does not ignore.
+     * @brief Lists the tracked and untracked files git does not ignore, without symlinks and files whose real path
+     * leaves `root`. A path missing from disk stays in the list. Turns off `core.fsmonitor`, so the repository's
+     * config cannot make git run a command.
      *
      * @param root - Absolute directory.
      * @returns Root-relative paths, or `null` when `root` is not in a git work tree or git fails.

package/dist/scanner/graph/builder.d.ts

@@ -100,13 +100,15 @@ export declare class GraphBuilder {
      */
     href(ref: NodeRef, fragment?: string): string;
     /**
-     * @brief Records an edge. The same edge recorded twice is kept once.
+     * @brief Records an edge. The same edge recorded twice is kept once, with the lines of both.
      *
      * @param from - Node the edge starts at.
      * @param kind - Relation the edge expresses.
      * @param to - Node the edge ends at.
+     * @param lines - Lines of the file of `from` where the link is made, such as those of a call. Empty when the link
+     *   has no line of its own.
      */
-    link(from: NodeRef, kind: EdgeKind, to: NodeRef): void;
+    link(from: NodeRef, kind: EdgeKind, to: NodeRef, lines?: readonly number[]): void;
     /**
      * @brief Runs the content source of every node and returns the finished graph.
      *

package/dist/scanner/graph/communities.d.ts

@@ -3,8 +3,9 @@ import type { CommunityIndex, Edge, GraphNode } from '../../model';
  * @brief Splits the nodes of a scan into communities: groups whose nodes link to each other more than to the rest.
  *
  * Every page and entry is one unit: a file, a class, a function, a term, a table. A parameter or field counts
- * as the entry it belongs to. A section, folder or package belongs to no community. Every edge between two
- * units links them, and so does each unit with the unit it is in, such as a method with its class.
+ * as the entry it belongs to. A section, folder or package belongs to no community, and nor does a unit that would
+ * be alone in one. Every edge between two units links them, and so does each unit with the unit it is in, such as a
+ * method with its class.
  *
  * The split maximises modularity with the Louvain method: nodes move to the community of a neighbour while
  * that raises modularity, then each community becomes one node and the next level starts. It walks the nodes

package/dist/scanner/index.d.ts

@@ -1,4 +1,4 @@
-export { CallLinker, type CallContext, type CallVia, type RawCall, readCalls } from './code/calls';
+export { type BodyReferences, CallLinker, type CallContext, type CallVia, type LocatedCall, type RawCall, readReferences } from './code/calls';
 export { type ExtractedFile, type RawField, type RawParameter, type RawSymbol, SymbolExtractor } from './code/extract';
 export { GrammarLoader } from './code/grammar';
 export { C_INCLUDES, ECMASCRIPT_IMPORTS, type ImportRequest, type ImportSyntax, PYTHON_IMPORTS, SourceFileIndex, } from './code/imports';

package/dist/scanner/packages.d.ts

@@ -8,6 +8,9 @@ import type { Source } from './files';
  * @property manifest - Display path of the manifest that marks the package, such as `packages/core/package.json`.
  * @property version - Version the manifest gives, or `null`.
  * @property description - Description the manifest gives, or `''`.
+ * @property entryPoints - The subpaths code outside the package imports it by, `''` for the package name itself,
+ *   such as `['', 'hash']` for `@g3nomaly/core` and `@g3nomaly/core/hash`. The `exports` of a `package.json` lists
+ *   them; any other manifest has `['']`.
  */
 export interface PackageInfo {
     readonly packageName: string;
@@ -15,6 +18,7 @@ export interface PackageInfo {
     readonly manifest: string;
     readonly version: string | null;
     readonly description: string;
+    readonly entryPoints: readonly string[];
 }
 /**
  * @brief Finds the packages of a set of sources: every directory below a root with a manifest that one of the readers understands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3nomaly/analyze",
-  "version": "0.1.5",
+  "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",
@@ -40,7 +40,7 @@
     "docs": "bun run build && bun dist/cli.js create_docs"
   },
   "dependencies": {
-    "@g3nomaly/core": "^0.3.6",
+    "@g3nomaly/core": "^0.3.7",
     "@t3-oss/env-core": "^0.13.11",
     "hast-util-to-string": "^3.0.1",
     "rehype-parse": "^9.0.1",
@@ -58,7 +58,7 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@g3nomaly/ui": "^0.3.7",
+    "@g3nomaly/ui": "^0.3.8",
     "@tanstack/react-router": "^1.170.41",
     "@tanstack/react-store": "^0.11.2",
     "@tree-sitter-grammars/tree-sitter-kotlin": "^1.1.0",