@g3nomaly/analyze 0.1.6 → 0.1.7

package/dist/retrieval/summary.d.ts

@@ -17,6 +17,14 @@ export declare function nodeId(graph: Graph, node: NodeRef): string;
  * @returns The id without the file, `#/` or slashes around it, with percent escapes decoded.
  */
 export declare function normalizeId(text: string): string;
+/**
+ * @brief Finds the path on disk that belongs to a node.
+ *
+ * @param graph - Graph the node belongs to.
+ * @param node - The node to look up.
+ * @returns The path of the node itself, else of the file it is in. `null` for a section or a folder.
+ */
+export declare function pathOf(graph: Graph, node: NodeRef): string | null;
 /**
  * @brief Describes a node in one row: what a search hit, a list row and a reference show.
  *

package/dist/retrieval/walk.d.ts

@@ -1,8 +1,12 @@
-import type { EdgeKind, NodeRef } from '../model';
+import { type EdgeKind, type NodeRef } from '../model';
 import type { Graph } from '../query';
 import type { Reference } from './report';
 /** Most references a walk lists without a limit. */
 export declare const DEFAULT_WALK_LIMIT = 50;
+/** Levels a walk can follow links at: between pages and entries, or between the files that hold them. */
+export declare const WALK_LEVELS: readonly ['entries', 'files'];
+/** A level a walk follows links at. */
+export type WalkLevel = (typeof WALK_LEVELS)[number];
 /**
  * @brief How far a walk of the references of a node goes.
  *
@@ -10,12 +14,15 @@ export declare const DEFAULT_WALK_LIMIT = 50;
  * @property kinds - Edge kinds to follow. Empty follows every kind.
  * @property depth - Hops to follow from the node. 1 lists its own references.
  * @property limit - Most references to list, both directions and every hop together.
+ * @property level - `entries` follows the stored links. `files` follows them between the files that hold their
+ *   ends, as the file level of the graph page draws them, and starts at the file of the node.
  */
 export interface WalkOptions {
     readonly direction: 'in' | 'out' | 'both';
     readonly kinds: readonly EdgeKind[];
     readonly depth: number;
     readonly limit: number;
+    readonly level: WalkLevel;
 }
 /**
  * @brief A reference with the references of its node one hop further, in the same direction.
@@ -56,11 +63,15 @@ export declare function walkReferences(graph: Graph, start: NodeRef, options: Wa
 /**
  * @brief Finds the shortest chain of edges from one node to another, following edges the way they point.
  *
+ * Of the chains that are equally short, the one with the fewest `mentions` steps wins, so a link a description makes
+ * only stands in for code where code offers no chain as short.
+ *
  * @param graph - Graph both nodes belong to.
  * @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 The references from `from` to `to`, in order, each to the next node of the chain. Empty when `from` is
  *   `to`. `null` when no chain leads there.
  */
-export declare function shortestPath(graph: Graph, from: NodeRef, to: NodeRef, kinds: readonly EdgeKind[]): Reference[] | null;
+export declare function shortestPath(graph: Graph, from: NodeRef, to: NodeRef, kinds: readonly EdgeKind[], includeMentions?: boolean): Reference[] | null;

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

@@ -25,6 +25,14 @@ export interface RawCall {
     readonly via: CallVia;
     readonly qualifier: readonly string[];
 }
+/**
+ * @brief A call or a passed value of a function body, with every line it is on.
+ *
+ * @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.
  *
@@ -33,8 +41,8 @@ export interface RawCall {
  *   `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 RawCall[];
-    readonly passes: readonly RawCall[];
+    readonly calls: readonly LocatedCall[];
+    readonly passes: readonly LocatedCall[];
 }
 /**
  * @brief Reads the calls of a function body, and the functions it passes on as values.
@@ -129,7 +137,7 @@ export declare class CallLinker {
      * @param context - Where the function is.
      * @param kind - `calls` for calls, `passes` for values passed on.
      */
-    link(from: NodeRef, calls: readonly RawCall[], context: CallContext, kind: 'calls' | 'passes'): void;
+    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.
      *

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

@@ -2,12 +2,30 @@ 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.
  *
@@ -54,6 +72,7 @@ export interface ImportSyntax {
  * @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;
@@ -62,6 +81,7 @@ export declare class SourceFileIndex {
     private entryPoints;
     private readonly resolved;
     private readonly seen;
+    private readonly declarations;
     /**
      * @brief Adds a source file.
      *
@@ -117,6 +137,14 @@ export declare class SourceFileIndex {
      * @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`.
      *
@@ -145,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/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.

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/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/index.d.ts

@@ -1,4 +1,4 @@
-export { type BodyReferences, CallLinker, type CallContext, type CallVia, type RawCall, readReferences } 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/package.json

@@ -1,6 +1,6 @@
 {
   "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",