@g3nomaly/analyze 0.1.3 → 0.1.5

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

@@ -0,0 +1,147 @@
+import type { Node } from 'web-tree-sitter';
+import type { NodeRef } from '../../model';
+/**
+ * @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.
+ *
+ * `from .models import Booking` is `['.models.Booking', '.models']`: `Booking` may be a module of its own.
+ */
+export type ImportRequest = readonly string[];
+/**
+ * @brief How a language names the files a file imports.
+ *
+ * Specs set it in `languages/`. `SymbolExtractor` calls `read` on each parsed file, and `CodePlanner` calls
+ * `resolve` once every source file of the scan is known.
+ */
+export interface ImportSyntax {
+    /**
+     * @brief Reads the imports of a parsed file, in file order.
+     *
+     * @param root - Root node of the parsed file.
+     * @returns One request per import, as the file writes it.
+     */
+    read(root: Node): ImportRequest[];
+    /**
+     * @brief Finds the file an import names.
+     *
+     * @param specifier - One path of an {@link ImportRequest}, such as `slam/pose.hpp` or `./store`.
+     * @param from - Display path of the importing file.
+     * @param files - Every source file of the scan.
+     * @returns Display path of the imported file, or `null` when the scan has none or the specifier is ambiguous.
+     */
+    resolve(specifier: string, from: string, files: SourceFileIndex): string | null;
+}
+/**
+ * @brief Every source file of a scan with its imports, so an import can find its file and a name can tell which
+ * files its file sees.
+ *
+ * A file **sees** itself and every file it imports, directly or through the files those import. Created per scan
+ * by `RepositoryScanner` in `scanner/scanner.ts`, which hands it the packages of the scan. `CodePlanner` in
+ * `planner.ts` adds each source file it plans; the {@link ImportSyntax} of each language, `SymbolPlanner` and
+ * `CallLinker` read it back once the graph is built.
+ *
+ * @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 resolved - Display paths each file imports, resolved on first use.
+ * @property seen - Display paths each file sees, computed on first use.
+ */
+export declare class SourceFileIndex {
+    private readonly entries;
+    private readonly byName;
+    private packages;
+    private readonly resolved;
+    private readonly seen;
+    /**
+     * @brief Adds a source file.
+     *
+     * @param path - Display path of the file.
+     * @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.
+     */
+    add(path: string, ref: NodeRef, syntax: ImportSyntax | null, requests: readonly ImportRequest[]): void;
+    /**
+     * @brief Tells the index where each package of the scan is, so an import of a package by name finds its files.
+     *
+     * @param packages - Each package by the display path of its directory, as `detectPackages` returns them.
+     */
+    usePackages(packages: ReadonlyMap<string, {
+        readonly packageName: string;
+    }>): void;
+    /**
+     * @brief Directory of the package with a name.
+     *
+     * @param name - Name its manifest gives, such as `@g3nomaly/core`.
+     * @returns Display path of its directory, `''` for the root, or `undefined` when the scan has no such package.
+     */
+    packageDirectory(name: string): string | undefined;
+    /**
+     * @brief Node of the source file at `path`.
+     *
+     * @param path - Display path of a file.
+     * @returns The node, or `undefined` when the scan has no source file there.
+     */
+    refOf(path: string): NodeRef | undefined;
+    /**
+     * @brief Tells whether the scan has a source file at `path`.
+     *
+     * @param path - Display path of a file.
+     */
+    has(path: string): boolean;
+    /**
+     * @brief The source files whose path is `tail` or ends with `/tail`, such as `libs/slam/include/slam/pose.hpp` for `slam/pose.hpp`.
+     *
+     * @param tail - Relative path, such as `slam/pose.hpp`.
+     * @returns Display paths of the matching files.
+     */
+    endingWith(tail: string): string[];
+    /**
+     * @brief The source files a file imports, each once. For each import the first path of its request that names a
+     * file of the scan counts.
+     *
+     * @param path - Display path of the importing file.
+     * @returns Display paths of the imported files, in the order the file imports them.
+     */
+    importsOf(path: string): readonly string[];
+    /**
+     * @brief Tells whether the scan reads the imports of a file, so what it sees is known.
+     *
+     * @param path - Display path of a file.
+     */
+    tracksImports(path: string): boolean;
+    /**
+     * @brief Tells whether a file sees another: it is that file, or imports it directly or through other files.
+     *
+     * @param from - Display path of the file a name is used in.
+     * @param to - Display path of the file a declaration is in.
+     * @returns True when `from` sees `to`, and always for a file whose imports the scan does not read.
+     */
+    sees(from: string, to: string): boolean;
+}
+/**
+ * @brief `#include "x.h"` and `#include <x.h>` of C and C++.
+ *
+ * An include resolves next to the including file first, then against every file whose path ends with it, such
+ * as `libs/slam/include/slam/pose.hpp` for `slam/pose.hpp`. When several end with it, the one closest to the
+ * including file wins. A header of a library outside the repository, such as `<vector>`, resolves to nothing.
+ */
+export declare const C_INCLUDES: ImportSyntax;
+/**
+ * @brief `import`, `export … from`, `import()` and `require()` of JavaScript and TypeScript.
+ *
+ * A relative specifier, such as `./store` or `../model/index.js`, resolves next to the importing file. A package of
+ * the scan, such as `@g3nomaly/core` or `@g3nomaly/core/config`, resolves below its directory or its `src`
+ * directory. A path alias such as `@/components/button` or `~/lib/api` resolves against every file whose path ends
+ * with what follows the alias, the closest winning. Each may leave out the extension, name a directory with an
+ * `index` file, or write `.js` for a `.ts` file. Any other package, such as `zod`, resolves to nothing.
+ */
+export declare const ECMASCRIPT_IMPORTS: ImportSyntax;
+/**
+ * @brief `import a.b` and `from .a import b` of Python.
+ *
+ * A relative module resolves against the directory of the importing file. An absolute one resolves against every
+ * file whose path ends with it, as `a/b.py` or `a/b/__init__.py`, the closest winning. `from a import b` tries
+ * the module `a.b` first, then `a`.
+ */
+export declare const PYTHON_IMPORTS: ImportSyntax;

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 { ImportSyntax } from './imports';
 /**
  * @brief Doc comment dialect, which decides how the scanner reads doc comments.
  *
@@ -116,6 +117,14 @@ export interface CallStyle {
  * @property splitQualifiedName - Splits a qualified name such as `Foo::bar` into owner and member.
  * @property declaredReturnType - Reads the return type when the `@return` capture cannot express it, such as a C pointer.
  * @property call - How the language spells a call.
+ * @property imports - How the language names the files a file imports. Without it a file of the language imports nothing.
+ * @property namespaceSeparator - Separator of a qualified type name, such as `::` in `geo::Point`. When set, a
+ *   qualified name only links to a declaration inside a namespace or type of that name.
+ * @property isPrivateFile - Answers whether the other files cannot see the types of a file, as for a C++ source file
+ *   next to its headers. Its functions stay visible unless `isInternal` says otherwise.
+ * @property isInternal - Answers whether a function is visible only in its own file, such as a `static` C function.
+ * @property implicitReceiver - Whether a bare call inside a method can call another method of its type, as `flush()`
+ *   means `this->flush()` in C++. Unset where a method needs `this.` or `self.`, as in JavaScript and Python.
  */
 export interface LanguageSpec {
     readonly id: string;
@@ -166,6 +175,11 @@ export interface LanguageSpec {
     returnsValue(facts: DefinitionFacts): boolean;
     readonly declaredReturnType?: (facts: DefinitionFacts) => string | null;
     readonly call: CallStyle;
+    readonly imports?: ImportSyntax;
+    readonly namespaceSeparator?: string;
+    readonly isPrivateFile?: (path: string) => boolean;
+    readonly isInternal?: (facts: DefinitionFacts) => boolean;
+    readonly implicitReceiver?: boolean;
 }
 /**
  * Language family of a spec.

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

@@ -7,6 +7,7 @@ import { type Reporter } from '../reporter';
 import type { SqlPlanner } from '../sql/planner';
 import type { SymbolExtractor } from './extract';
 import type { GrammarLoader } from './grammar';
+import type { SourceFileIndex } from './imports';
 import type { LanguageRegistry } from './languages';
 import type { SymbolPlanner } from './symbols';
 /**
@@ -22,7 +23,7 @@ export interface SourceFile {
     readonly displayPath: string;
 }
 /**
- * @brief Adds source files and their symbols to the graph.
+ * @brief Adds source files and their symbols to the graph, and an `imports` edge for each file a file imports.
  *
  * The SQL files of a repository are no code: `DatabasePlanner` adds them. A SQL file of a skill
  * that creates tables goes to the `SqlPlanner`.
@@ -34,7 +35,7 @@ export interface SourceFile {
  * `SkillPlanner` in `skills/planner.ts` calls `isSource` and `planFile`.
  *
  * @example
- * const code = new CodePlanner(graph, registry, grammars, extractor, symbols, files, sql, reporter);
+ * const code = new CodePlanner(graph, registry, grammars, extractor, symbols, sources, files, sql, reporter);
  * await code.planTree(sections.code, source);
  */
 export declare class CodePlanner {
@@ -43,6 +44,7 @@ export declare class CodePlanner {
     private readonly grammars;
     private readonly extractor;
     private readonly symbols;
+    private readonly sources;
     private readonly files;
     private readonly sql;
     private readonly reporter;
@@ -54,11 +56,12 @@ export declare class CodePlanner {
      * @param grammars - Loads the parser and query of a language spec.
      * @param extractor - Extracts the raw symbols from a parsed syntax tree.
      * @param symbols - Adds the symbols of a file below its source node.
+     * @param sources - Every source file of the scan, which the imports resolve against.
      * @param files - Reads the text of a file, to embed it in its node.
      * @param sql - Adds SQL files that create tables as databases.
      * @param reporter - Receives a warning for each file that cannot be read or parsed. Silent by default.
      */
-    constructor(graph: GraphBuilder, registry: LanguageRegistry, grammars: GrammarLoader, extractor: SymbolExtractor, symbols: SymbolPlanner, files: FileRenderer, sql: SqlPlanner, reporter?: Reporter);
+    constructor(graph: GraphBuilder, registry: LanguageRegistry, grammars: GrammarLoader, extractor: SymbolExtractor, symbols: SymbolPlanner, sources: SourceFileIndex, files: FileRenderer, sql: SqlPlanner, reporter?: Reporter);
     /**
      * @brief Tells whether a file is source code, whether or not the scanner can read its symbols.
      *
@@ -66,7 +69,7 @@ export declare class CodePlanner {
      */
     isSource(path: string): boolean;
     /**
-     * @brief Adds every file of `source` that declares a class or a function, in folders below `section`.
+     * @brief Adds every file of `source` that declares a class or a function or imports a file, in folders below `section`.
      *
      * Files in unsupported languages are skipped. JSON, TOML and YAML files go to `configs`, in the same
      * pass, so the tree stays in path order.
@@ -89,6 +92,8 @@ export declare class CodePlanner {
     /**
      * @brief Adds a `source` node for the file below `parent`, registers its display path, and plans its symbols.
      *
+     * Its imports resolve when the graph is built, once every source file of the scan is known.
+     *
      * @param parent - Node the file is added below.
      * @param file - File to add.
      * @param extracted - Symbols of the file, or `null` to add the file without symbols.
@@ -96,6 +101,13 @@ export declare class CodePlanner {
      * @returns Node of the file.
      */
     private add;
+    /**
+     * @brief Records an `imports` edge from a file to each file of the scan it imports.
+     *
+     * @param from - Node of the importing file.
+     * @param path - Display path of the importing file.
+     */
+    private linkImports;
     /**
      * @brief Reads the symbols of a file.
      *

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

@@ -3,6 +3,8 @@ import type { GraphBuilder } from '../graph/builder';
 import type { CodeHighlighter } from '../highlight';
 import type { ProseResolvers } from '../markdown/links';
 import type { MarkdownRenderer } from '../markdown/renderer';
+import type { CallLinker } from './calls';
+import type { SourceFileIndex } from './imports';
 import type { RawSymbol } from './extract';
 import { type LanguageSpec } from './language';
 import type { CallableIndex, TypeIndex, TypeLinker } from './types';
@@ -22,13 +24,13 @@ export interface FileContext {
  * @brief Adds the symbols of a file to the graph: one node per class or function,
  * with a child node per parameter and field.
  *
- * Type names in signatures become links to the types they name. Holds the graph, the renderers,
+ * Type names in signatures become links to the types they name, and calls in bodies become `calls` edges. Holds the graph, the renderers,
  * and the indexes and linkers it registers into and links through. Created per scan by
  * `RepositoryScanner` in `scanner/scanner.ts`; `CodePlanner` in `planner.ts` calls `plan` for
  * each file it extracts symbols from.
  *
  * @example
- * const symbols = new SymbolPlanner(graph, highlighter, markdown, types, callables, linker, resolvers);
+ * const symbols = new SymbolPlanner(graph, highlighter, markdown, types, callables, linker, calls, sources, resolvers);
  * symbols.plan(fileRef, { spec, path: 'src/app.ts', packageName: null }, extracted.symbols);
  */
 export declare class SymbolPlanner {
@@ -38,6 +40,8 @@ export declare class SymbolPlanner {
     private readonly types;
     private readonly callables;
     private readonly linker;
+    private readonly calls;
+    private readonly sources;
     private readonly resolvers;
     /**
      * Takes the graph and renderers it writes with, and the indexes and linkers that resolve names.
@@ -48,9 +52,11 @@ export declare class SymbolPlanner {
      * @param types - Index of type declarations, where each new type is registered.
      * @param callables - Index of functions and methods, where each new callable is registered.
      * @param linker - Links the type names of signatures to their declarations.
+     * @param calls - Links the calls in function bodies to the functions they reach.
+     * @param sources - Source files with their imports, which decide the files a name can refer to.
      * @param resolvers - Resolves the names in prose descriptions to links.
      */
-    constructor(graph: GraphBuilder, highlighter: CodeHighlighter, markdown: MarkdownRenderer, types: TypeIndex, callables: CallableIndex, linker: TypeLinker, resolvers: ProseResolvers);
+    constructor(graph: GraphBuilder, highlighter: CodeHighlighter, markdown: MarkdownRenderer, types: TypeIndex, callables: CallableIndex, linker: TypeLinker, calls: CallLinker, sources: SourceFileIndex, resolvers: ProseResolvers);
     /**
      * @brief Adds `symbols` and everything inside them below the file node `fileRef`.
      *
@@ -81,6 +87,16 @@ export declare class SymbolPlanner {
      * @returns Content of the symbol node.
      */
     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.
+     *
+     * @param symbol - The calling function.
+     * @param scope - Where the function sits in the file.
+     * @param typeScope - Scope that the names of the function resolve in.
+     * @param self - Node of the function, where the edges start.
+     */
+    private linkCalls;
     /**
      * @brief Builds the content of a parameter or field node: linked type, default, optional flag and rendered description.
      *

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

@@ -6,20 +6,45 @@ import type { GraphBuilder } from '../graph/builder';
  * @property path - Display path of the file the name is in. `null` for a name in prose, which has no file of its own.
  * @property family - Language family of the name. `null` matches every language.
  * @property typeParameters - Type parameters in scope, such as `T`. They are never linked.
+ * @property namespaceSeparator - Separator of a qualified name in this language, such as `::`, from the spec's
+ *   `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.
  */
 export interface TypeScope {
     readonly path: string | null;
     readonly family: string | null;
     readonly typeParameters: ReadonlySet<string>;
+    readonly namespaceSeparator?: string;
+    readonly sees?: (path: string) => boolean;
 }
 /** Scope of a name in a document: any language, no file. */
 export declare const PROSE_SCOPE: TypeScope;
+/**
+ * @brief One declaration of a name: its node, where it is, and who can see it.
+ *
+ * @property ref - Node of the declaration.
+ * @property path - Display path of the file that declares it.
+ * @property family - Language family of that file.
+ * @property owners - Names of the namespaces and types around it, outermost first, such as `['geo', 'Point']`.
+ * @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.
+ */
+export interface DeclarationSite {
+    readonly ref: NodeRef;
+    readonly path: string;
+    readonly family: string;
+    readonly owners: readonly string[];
+    readonly local: boolean;
+    readonly privateFile: boolean;
+}
 /**
  * @brief Every class, interface, struct, enum, trait and type alias of the scan, by name.
  *
  * Holds every declaration of each name. Created per scan by `RepositoryScanner` in
  * `scanner/scanner.ts`; `SymbolPlanner` in `symbols.ts` registers each type it adds,
- * and {@link TypeLinker} resolves names against it. Created with `new TypeIndex()`.
+ * and {@link TypeLinker} and `CallLinker` in `calls.ts` resolve names against it. Created with `new TypeIndex()`.
  *
  * @property byName - Declarations of each name.
  */
@@ -29,11 +54,9 @@ export declare class TypeIndex {
      * @brief Adds a type declaration under its name.
      *
      * @param name - Name the type is declared with.
-     * @param ref - Node of the declaration.
-     * @param path - Display path of the file that declares it.
-     * @param family - Language family of that file, from `familyOf`.
+     * @param site - Node, file and visibility of the declaration.
      */
-    register(name: string, ref: NodeRef, path: string, family: string): void;
+    register(name: string, site: DeclarationSite): void;
     /**
      * @brief The declaration a name refers to, or `null` when there is none or the name is ambiguous.
      *
@@ -41,20 +64,29 @@ export declare class TypeIndex {
      *
      * @param name - Identifier to resolve.
      * @param scope - Where the name is used.
+     * @param qualifier - Names written in front of it, outermost first. Empty for a bare name.
      * @returns The node of the declaration, or `null`.
      */
-    resolve(name: string, scope: TypeScope): NodeRef | null;
+    resolve(name: string, scope: TypeScope, qualifier?: readonly string[]): NodeRef | null;
+}
+/**
+ * @brief Where a function or method is declared, and whether it is a member of a type.
+ *
+ * @property member - Whether a type owns it, so only a call through that type or one of its instances reaches it.
+ */
+export interface CallableSite extends DeclarationSite {
+    readonly member: boolean;
 }
 /**
  * @brief Every function and method of the scan, by name and by `Owner.name`. Lets
- * prose refer to a function the way it refers to a type.
+ * prose refer to a function the way it refers to a type, and calls find what they call.
  *
  * Holds every declaration of each key. Created per scan by `RepositoryScanner` in
  * `scanner/scanner.ts`; `SymbolPlanner` in `symbols.ts` registers each function and
- * method it adds, and {@link TypeLinker.mention} resolves inline code against it.
- * Created with `new CallableIndex()`.
+ * method it adds, {@link TypeLinker.mention} resolves inline code against it, and `CallLinker`
+ * in `calls.ts` resolves calls. Created with `new CallableIndex()`.
  *
- * @property byName - Declarations of each key: the name, and `Owner.name` for a method.
+ * @property byName - Declarations of each key: the name, and `Owner.name` for a function with an owner.
  */
 export declare class CallableIndex {
     private readonly byName;
@@ -62,12 +94,9 @@ export declare class CallableIndex {
      * @brief Adds a function or method under its name and, when it has an owner, under `Owner.name`.
      *
      * @param name - Name the function is declared with.
-     * @param owner - Name of the type or namespace it is declared in, or `null`.
-     * @param ref - Node of the declaration.
-     * @param path - Display path of its file.
-     * @param family - Language family of its file, from `familyOf`.
+     * @param site - Node, file and visibility of the declaration. Its last owner, if any, is the `Owner` of the key.
      */
-    register(name: string, owner: string | null, ref: NodeRef, path: string, family: string): void;
+    register(name: string, site: CallableSite): void;
     /**
      * @brief The function a piece of inline code names.
      *
@@ -76,7 +105,34 @@ export declare class CallableIndex {
      * @returns The function, or `null` when the text names none or more than one.
      */
     resolve(text: string, scope: TypeScope): NodeRef | null;
+    /**
+     * @brief The function a call reaches.
+     *
+     * @param name - Name the call uses.
+     * @param scope - Where the call is.
+     * @param owner - The type or namespace the call goes through, or `null` for a call of a free function.
+     * @param qualifier - Names written in front of `owner`, outermost first, which the declaration's owners must end with.
+     * @returns The function, or `null` when the call reaches none of the scan or the name is ambiguous.
+     */
+    resolveCall(name: string, scope: TypeScope, owner: string | null, qualifier?: readonly string[]): NodeRef | null;
 }
+/**
+ * @brief Counts the leading directories two file paths have in common.
+ *
+ * @param a - POSIX path of a file.
+ * @param b - POSIX path of a file.
+ * @returns Number of leading directories the two paths share.
+ */
+export declare function sharedDirectories(a: string, b: string): number;
+/**
+ * @brief The names written in front of the name at `index`, each followed by `separator`, outermost first.
+ *
+ * @param text - Source text, such as `const geo::Point&`.
+ * @param index - Offset of the name in `text`.
+ * @param separator - Separator of a qualified name, such as `::`.
+ * @returns The qualifier, such as `['geo']`, or `[]` for a bare name.
+ */
+export declare function qualifierBefore(text: string, index: number, separator: string): string[];
 /**
  * @brief Turns type names in source text into links between nodes, and records each link as an edge.
  *
@@ -104,7 +160,9 @@ export declare class TypeLinker {
     /**
      * @brief Links every known type name in `text`, such as `Booking` in `Promise<Booking>`.
      *
-     * Records one `relation` edge from `from` to each type it finds.
+     * Records one `relation` edge from `from` to each type it finds. Where the scope has a namespace separator, a
+     * qualified name such as `Eigen::Quaterniond` only links to a declaration inside `Eigen`, and the qualifier
+     * itself is no type name.
      *
      * @param text - Source text to scan for names.
      * @param from - Node the text belongs to. The edges start here.
@@ -116,7 +174,8 @@ export declare class TypeLinker {
     /**
      * @brief The type or function that inline code names, and an edge to it.
      *
-     * @param text - Inline code, such as `Booking` or `choose_route()`.
+     * @param text - Inline code, such as `Booking`, `geo::Point` or `choose_route()`. A qualified type name only
+     *   names a type declared inside what qualifies it.
      * @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.

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

@@ -34,7 +34,8 @@ export type ContentSource<K extends NodeType> = (self: NodeRef) => ContentOf<K>
  * @property folders - Folder nodes by `parent/name`.
  * @property files - File nodes by normalized path.
  * @property packages - Packages by display path of their directory, set by `markPackages`.
- * @property packageSections - Sections whose folders become `package` nodes where a package sits.
+ * @property packageSections - Sections whose folders become `package` nodes where a package sits, most preferred first.
+ * @property packageNodes - Every `package` node `folder` created, with the display path of its directory and the rank of its section in `packageSections`.
  * @example
  * const graph = new GraphBuilder();
  */
@@ -45,7 +46,8 @@ export declare class GraphBuilder {
     private readonly folders;
     private readonly files;
     private packages;
-    private readonly packageSections;
+    private packageSections;
+    private readonly packageNodes;
     /**
      * @brief Adds a node. Kinds without content of their own, such as folders, take no `content`.
      *
@@ -57,7 +59,10 @@ export declare class GraphBuilder {
     /**
      * @brief Makes `folder` create a `package` node instead of a folder for every package directory below the given sections.
      *
-     * @param sections - Sections whose `folder` paths are display paths of the repository, such as the code and docs sections.
+     * One directory stays one package: when it is a package below several of the sections, `build` keeps the
+     * `package` node of the first of them and turns the others into plain folders.
+     *
+     * @param sections - Sections whose `folder` paths are display paths of the repository, most preferred first, such as the code and then the docs section.
      * @param packages - Packages by display path of their directory, as `detectPackages` returns them.
      */
     markPackages(sections: readonly NodeRef[], packages: ReadonlyMap<string, PackageInfo>): void;
@@ -65,6 +70,7 @@ export declare class GraphBuilder {
      * @brief Finds the folder at `directory` below `parent`, creating it and its ancestors on first use.
      *
      * Below a section passed to `markPackages`, a directory that holds a package becomes a `package` node.
+     * `build` keeps one of them per directory.
      *
      * @param parent - Node the directory is below.
      * @param directory - Slash-separated path, such as `docs/guides`. `''` names `parent` itself.
@@ -110,5 +116,10 @@ export declare class GraphBuilder {
         nodes: GraphNode[];
         edges: Edge[];
     }>;
+    /**
+     * @brief Turns every `package` node of a directory into a plain folder, except the one in the most preferred
+     * section passed to `markPackages`. A folder has the same route as a package, so links made before stay valid.
+     */
+    private keepOnePackagePerDirectory;
 }
 export {};

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

@@ -0,0 +1,17 @@
+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.
+ *
+ * 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
+ * in order, so one scan gives one split.
+ *
+ * @param nodes - Every node of the scan, in `NodeRef` order.
+ * @param edges - Every edge of the scan.
+ * @returns The community of each node and the label of each community, the largest first.
+ */
+export declare function detectCommunities(nodes: readonly GraphNode[], edges: readonly Edge[]): CommunityIndex;

package/dist/scanner/ignore.d.ts

@@ -1,6 +1,6 @@
 /** Name of the file at the root of a repository that lists what analyze skips. */
 export declare const IGNORE_FILE = ".analyzeignore";
-/** Lines of the `.analyzeignore` that analyze writes when a repository has none. */
+/** The patterns analyze skips when a repository has no `.analyzeignore`, in the format of that file. */
 export declare const DEFAULT_IGNORE_LINES: readonly string[];
 /**
  * @brief Turns the lines of an ignore file into globs that `Bun.Glob` matches against root-relative paths.
@@ -14,12 +14,10 @@ export declare const DEFAULT_IGNORE_LINES: readonly string[];
  */
 export declare function ignoreGlobs(text: string): string[];
 /**
- * @brief Reads the `.analyzeignore` of a repository, and writes one with {@link DEFAULT_IGNORE_LINES} when it has none.
+ * @brief Reads the `.analyzeignore` of a repository. Without one, the built-in {@link DEFAULT_IGNORE_LINES} apply.
+ * A file replaces the built-in list rather than adding to it. Nothing is written.
  *
  * @param repo - Absolute path of the repository.
- * @returns The globs of the file, and whether this call created the file.
+ * @returns The globs of the file, or of the built-in list when the repository has no file.
  */
-export declare function loadIgnoreFile(repo: string): {
-    globs: string[];
-    created: boolean;
-};
+export declare function loadIgnoreFile(repo: string): string[];

package/dist/scanner/index.d.ts

@@ -1,10 +1,12 @@
+export { CallLinker, type CallContext, type CallVia, type RawCall, readCalls } 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';
 export type { CallStyle, DocStyle, LanguageSpec } from './code/language';
 export { LANGUAGES, LanguageRegistry } from './code/languages';
 export { CodePlanner, type SourceFile } from './code/planner';
 export { type FileContext, SymbolPlanner } from './code/symbols';
-export { CallableIndex, PROSE_SCOPE, TypeIndex, TypeLinker, type TypeScope } from './code/types';
+export { CallableIndex, type CallableSite, type DeclarationSite, PROSE_SCOPE, TypeIndex, TypeLinker, type TypeScope, } from './code/types';
 export { FileRenderer, type RenderedFile } from './content';
 export { type ParsedDecision, type ParsedDecisions, parseDecisions } from './decisions/parse';
 export { DecisionPlanner } from './decisions/planner';
@@ -16,6 +18,7 @@ export { type ParsedGlossary, type ParsedTerm, parseGlossary } from './glossary/
 export { GlossaryPlanner } from './glossary/planner';
 export { type TermFinder, TermIndex, TermLinker, type TermMatch } from './glossary/terms';
 export { type ContentOf, type ContentSource, GraphBuilder, type IdentityOf } from './graph/builder';
+export { detectCommunities } from './graph/communities';
 export { type CodeHighlighter, ShikiHighlighter } from './highlight';
 export { type LinkOrigin, ProseResolvers } from './markdown/links';
 export { joinLines, type MarkdownLine, outlineLines, plainText } from './markdown/outline';

package/dist/scanner/markdown/outline.d.ts

@@ -22,6 +22,8 @@ export declare function outlineLines(markdown: string): MarkdownLine[];
 /**
  * @brief Removes inline markdown markers from a short text such as a heading.
  *
+ * A code span keeps its text as it is. An `_` inside a word, as in `add_library`, is no emphasis and stays.
+ *
  * @param markdown - Inline markdown, for example `**Lane** (_route_)`.
  * @returns The text a reader sees, for example `Lane (route)`.
  */

package/dist/scanner/packages.d.ts

@@ -22,6 +22,12 @@ export interface PackageInfo {
  * A directory with several manifests is read by the first reader in `READERS` that understands one. The root
  * directory of a source is left out: it is the repository itself.
  *
+ * A `vcpkg.json` marks a package wherever it is. A `CMakeLists.txt` marks one only when it builds a package of
+ * its own: it calls `project(`, or a command whose name holds `library` or `executable` (such as `add_library` or a
+ * `g3n_add_library` macro), or its directory has an `include/` folder. In a `src`, `test`, `tests`, `cmake` or
+ * `examples` directory of a package only `project(` counts, so the CMake files a package pulls in with
+ * `add_subdirectory` do not make packages of their own. {@link readCMake} has the details.
+ *
  * @param sources - Directories with their files, such as the code sources of a scan.
  * @returns Packages by display path of their directory, such as `packages/core`.
  */

package/dist/scanner/scanner.d.ts

@@ -60,7 +60,7 @@ export declare class RepositoryScanner {
      * code, database and tasks, in that order.
      *
      * @param input - The directories of each section.
-     * @returns The nodes and edges of the bundle, without its meta and semantic index.
+     * @returns The nodes, edges and communities of the bundle, without its meta and semantic index.
      */
-    scan(input: ScanInput): Promise<Pick<DocsBundle, 'nodes' | 'edges'>>;
+    scan(input: ScanInput): Promise<Required<Pick<DocsBundle, 'nodes' | 'edges' | 'communities'>>>;
 }