@g3nomaly/analyze 0.1.0 → 0.1.2

package/dist/retrieval/retriever.d.ts

@@ -8,62 +8,72 @@ import { type Resolution } from './resolve';
 export declare const SEARCH_MODES: readonly ['both', 'name', 'meaning'];
 /** How a search matches: `name` by the words of a name or a description, `meaning` by the embedding model, `both` by words first and then by meaning. */
 export type SearchMode = (typeof SEARCH_MODES)[number];
-/** How one search is run. */
+/**
+ * @brief How one search is run.
+ *
+ * @property mode - How the search matches: `name`, `meaning` or `both`.
+ * @property limit - Most hits to return, both ways of matching together.
+ * @property filter - Narrows the nodes that count, such as to one kind.
+ */
 export interface SearchOptions {
     readonly mode: SearchMode;
-    /** Most hits to return, both ways of matching together. */
     readonly limit: number;
     readonly filter: NodeFilter;
 }
-/** One result of a search. */
+/**
+ * @brief One result of a search: a node summary with how it matched.
+ *
+ * @property match - `name`: every word of the query is in the name or the path of the node. `text`: at least one word is only in its description. `meaning`: the node is close to the query in the embedding model.
+ * @property score - From 0 to 1 for a match by meaning. `null` for a match by words.
+ */
 export interface SearchHit extends NodeSummary {
-    /**
-     * `name`: every word of the query is in the name or the path of the node.
-     * `text`: at least one word is only in its description.
-     * `meaning`: the node is close to the query in the embedding model.
-     */
     readonly match: 'name' | 'text' | 'meaning';
-    /** From 0 to 1 for a match by meaning. `null` for a match by words. */
     readonly score: number | null;
 }
 /**
- * Answers queries on one bundle: search, list, look up, describe.
+ * @brief Answers queries on one bundle: search, list, look up, describe.
  *
  * Holds the graph of the bundle and, after the first search by name, the
- * search index. `openRetriever` in `api/source.ts` creates one per request;
- * `listIn`, `searchIn`, `showIn` and `refsIn` in `api/` each call one method.
- * Every answer is plain data with ids, so a caller can print it, serialize it
- * or feed an id into the next call.
+ * search index. `openRetriever` in `api/source.ts` creates one per request from
+ * a `Graph`; `listIn`, `searchIn`, `showIn` and `refsIn` in `api/` each call one
+ * method. Create one with `new Retriever(new Graph(bundle))`. Every answer is
+ * plain data with ids, so a caller can print it, serialize it or feed an id into
+ * the next call.
  */
 export declare class Retriever {
     private readonly graph;
-    /** Built on the first search by name. */
     private nameIndex;
-    /** Creates a retriever for one bundle. */
+    /**
+     * @brief Creates a retriever for one bundle.
+     *
+     * @param graph - Graph of the bundle, from `new Graph(bundle)`.
+     */
     constructor(graph: Graph);
     /**
-     * Names the embedding model that searches by meaning.
+     * @brief Names the embedding model that searches by meaning.
      *
      * @returns The name, or `null` when the bundle was built without embeddings.
      */
     get model(): string | null;
     /**
-     * Finds pages and entries for a query. Matches by words come first, in the
+     * @brief Finds pages and entries for a query. Matches by words come first, in the
      * order the site lists them. Matches by meaning follow, best first.
      *
      * @param query - Words of a name, or a query in plain language.
+     * @param options - How the search runs: its mode, its limit and its filter.
      * @returns The hits, each once.
      */
     search(query: string, options: SearchOptions): SearchHit[];
     /**
-     * Lists pages and entries in display order.
+     * @brief Lists pages and entries in display order.
      *
+     * @param filter - Narrows the nodes listed.
      * @param limit - Most rows to return. `null` returns all of them.
      * @returns One row per node.
      */
     list(filter: NodeFilter, limit: number | null): NodeSummary[];
     /**
-     * Finds the node a caller means by an id, a file path or a name.
+     * @brief Finds the node a caller means by an id, a file path or a name.
      *
      * @param text - What the caller wrote.
      * @param filter - Narrows the nodes that count, to tell two nodes with one name apart.
@@ -71,23 +81,24 @@ export declare class Retriever {
      */
     resolve(text: string, filter: NodeFilter): Resolution;
     /**
-     * Describes a node in one row.
+     * @brief Describes a node in one row.
      *
      * @param node - A page or an entry.
      * @returns Its id, kind, title, place on disk and summary.
      */
     summarize(node: NodeRef): NodeSummary;
     /**
-     * Builds the full report of a node.
+     * @brief Builds the full report of a node.
      *
      * @param node - A page or an entry.
      * @returns Everything its page shows, with texts as markdown.
      */
     describe(node: NodeRef): NodeReport;
     /**
-     * Lists the edges of a node.
+     * @brief Lists the edges of a node.
      *
      * @param node - A page or an entry.
+     * @param options - Which edges to keep, by direction and kind.
      * @returns What the node links to and what links to it.
      */
     references(node: NodeRef, options?: ReferenceOptions): References;

package/dist/retrieval/summary.d.ts

@@ -2,23 +2,26 @@ import { type NodeRef } from '../model';
 import { type Graph } from '../query';
 import type { NodeSummary } from './report';
 /**
- * Builds the id of a node: its route as the address of its page spells it,
+ * @brief Builds the id of a node: its route as the address of its page spells it,
  * without the leading `#/`.
  *
+ * @param graph - Graph the node belongs to.
  * @param node - The node. A parameter or a field has the id of its symbol.
  * @returns The id, such as `docs/glossary.md#term:lane`.
  */
 export declare function nodeId(graph: Graph, node: NodeRef): string;
 /**
- * Reduces an id, an address copied from the browser or an href of the site to an id.
+ * @brief Reduces an id, an address copied from the browser or an href of the site to an id.
  *
  * @param text - What the caller wrote, such as `#/code/src/app.ts#symbol:App.run` or `file:///site/docs.html#/code/src/app.ts`.
  * @returns The id without the file, `#/` or slashes around it, with percent escapes decoded.
  */
 export declare function normalizeId(text: string): string;
 /**
- * Describes a node in one row: what a search hit, a list row and a reference show.
+ * @brief Describes a node in one row: what a search hit, a list row and a reference show.
  *
+ * @param graph - Graph the node belongs to.
  * @param node - The node. A parameter or a field is not listed on its own, so pass its symbol.
+ * @returns The row of the node.
  */
 export declare function summarize(graph: Graph, node: NodeRef): NodeSummary;

package/dist/scanner/code/doc/clean.d.ts

@@ -1,10 +1,36 @@
-/** Strips comment markers from the text of consecutive comment nodes. */
+/**
+ * @brief Strips comment markers from the text of consecutive comment nodes.
+ *
+ * @param comments - Raw text of each comment node, markers included.
+ * @returns The text of the comments, without the lines that configure tools such as `eslint-disable`.
+ */
 export declare function cleanComments(comments: readonly string[]): string;
-/** Content of a Python string literal used as a docstring, laid out like `inspect.cleandoc`. */
+/**
+ * @brief Strips the quotes of a Python string literal and lays out its lines like `inspect.cleandoc`.
+ *
+ * @param literal - Source text of the string literal, quotes included.
+ * @returns The docstring text.
+ */
 export declare function cleanDocstring(literal: string): string;
-/** Text of the first fenced code block, or `null`. */
+/**
+ * @brief Finds the text of the first fenced code block.
+ *
+ * @param markdown - Markdown to search.
+ * @returns The block without its fences, or `null` when there is none.
+ */
 export declare function firstFencedBlock(markdown: string): string | null;
-/** Applies `transform` to every line outside fenced code blocks. */
+/**
+ * @brief Applies `transform` to every line outside fenced code blocks.
+ *
+ * @param markdown - Markdown to rewrite.
+ * @param transform - Maps one prose line to its new text.
+ * @returns The markdown with the prose lines transformed. Fenced lines stay as they are.
+ */
 export declare function mapProseLines(markdown: string, transform: (line: string) => string): string;
-/** Turns markdown headings into bold lines, so a description never outranks its symbol title. */
+/**
+ * @brief Turns markdown headings into bold lines, so a description never outranks its symbol title.
+ *
+ * @param markdown - Markdown of a description.
+ * @returns The markdown with bold lines in place of its headings.
+ */
 export declare function demoteHeadings(markdown: string): string;

package/dist/scanner/code/doc/index.d.ts

@@ -2,5 +2,11 @@ import type { DocStyle } from '../language';
 import { type ParsedDoc } from './types';
 export { cleanComments, cleanDocstring } from './clean';
 export type { ParsedDoc, ParsedTag, ParsedTagKind } from './types';
-/** Parses cleaned doc comment text in the given dialect. */
+/**
+ * @brief Parses cleaned doc comment text in the given dialect.
+ *
+ * @param style - Dialect the comment is written in.
+ * @param text - Comment text without its markers, or `null` when the symbol has no comment.
+ * @returns The parsed doc, with its headings demoted. `EMPTY_DOC` for an empty or missing comment.
+ */
 export declare function parseDoc(style: DocStyle, text: string | null): ParsedDoc;

package/dist/scanner/code/doc/markdown.d.ts

@@ -1,3 +1,8 @@
 import type { ParsedDoc } from './types';
-/** Parses a markdown doc comment (rustdoc, godoc). An "Examples" section becomes the example. */
+/**
+ * @brief Parses a markdown doc comment (rustdoc, godoc). An "Examples" section becomes the example.
+ *
+ * @param text - Markdown doc comment text, cleaned of its markers.
+ * @returns The parsed doc.
+ */
 export declare function parseMarkdownDoc(text: string): ParsedDoc;

package/dist/scanner/code/doc/python.d.ts

@@ -1,3 +1,8 @@
 import type { ParsedDoc } from './types';
-/** Parses a docstring in Google, NumPy or reST layout. */
+/**
+ * @brief Parses a docstring in Google, NumPy or reST layout.
+ *
+ * @param text - Docstring content, cleaned of its quotes.
+ * @returns The description, the tags and the example.
+ */
 export declare function parsePythonDoc(text: string): ParsedDoc;

package/dist/scanner/code/doc/tagged.d.ts

@@ -1,10 +1,19 @@
 import type { ParsedDoc } from './types';
-/** Dialect switches for `parseTagged`. */
+/**
+ * @brief Dialect switches for `parseTagged`.
+ *
+ * @property titledExamples - YARD puts an example title on the `@example` line.
+ * @property braceLinks - YARD links to code with braces, as in `{Label.parse}` and `{#render}`.
+ */
 export interface TaggedOptions {
-    /** YARD puts an example title on the `@example` line. */
     readonly titledExamples?: boolean;
-    /** YARD links to code with braces, as in `{Label.parse}` and `{#render}`. */
     readonly braceLinks?: boolean;
 }
-/** Parses a doc comment written with `@tag` lines. */
+/**
+ * @brief Parses a doc comment written with `@tag` lines.
+ *
+ * @param text - Doc comment text, cleaned of its markers.
+ * @param options - Dialect switches. Empty for the tagged dialect, `{ titledExamples, braceLinks }` for YARD.
+ * @returns The description, the tags and the example.
+ */
 export declare function parseTagged(text: string, options?: TaggedOptions): ParsedDoc;

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

@@ -1,21 +1,32 @@
 import type { DocTagKind } from '../../../model';
 /** Tag kinds a parser emits. The planner folds the first three into parameters, return value and fields. */
 export type ParsedTagKind = 'param' | 'returns' | 'field' | DocTagKind;
-/** One tag of a parsed doc comment, such as a parameter or a return value. */
+/**
+ * @brief One tag of a parsed doc comment, such as a parameter or a return value.
+ *
+ * @property kind - Kind of the tag.
+ * @property label - Label of an `other` tag, as the comment writes it.
+ * @property name - Name of the parameter, field or exception the tag is about.
+ * @property type - Type as the comment writes it, when it writes one.
+ * @property text - Markdown.
+ */
 export interface ParsedTag {
     readonly kind: ParsedTagKind;
     readonly label?: string;
     readonly name?: string;
     readonly type?: string;
-    /** Markdown. */
     readonly text: string;
 }
-/** A doc comment parsed into description, tags and example, the same for every dialect. */
+/**
+ * @brief A doc comment parsed into description, tags and example, the same for every dialect.
+ *
+ * @property description - Markdown.
+ * @property tags - Tags in the order the comment writes them.
+ * @property example - Example source code, when the comment documents one.
+ */
 export interface ParsedDoc {
-    /** Markdown. */
     readonly description: string;
     readonly tags: readonly ParsedTag[];
-    /** Example source code, when the comment documents one. */
     readonly example: string | null;
 }
 /** Result for a symbol with no doc comment. */

package/dist/scanner/code/doc/xml.d.ts

@@ -1,3 +1,8 @@
 import type { ParsedDoc } from './types';
-/** Parses C# XML documentation comments. Text without XML elements is the description. */
+/**
+ * @brief Parses C# XML documentation comments. Text without XML elements is the description.
+ *
+ * @param text - Doc comment text, with its XML elements.
+ * @returns The description, the tags and the example.
+ */
 export declare function parseXmlDoc(text: string): ParsedDoc;

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

@@ -1,36 +1,57 @@
 import { type SymbolKind } from '../../model';
 import type { CallStyle, ImportContext } from './language';
-/** What a generated example needs to know about the type a method belongs to. */
+/**
+ * What a generated example needs to know about the type a method belongs to.
+ *
+ * @property kind - Kind of the owning type, such as `class` or `struct`.
+ * @property name - Name of the owning type.
+ * @property args - Constructor argument expressions of the type, receivers excluded.
+ * @property hasConstructor - True when the scanner found a constructor for the type.
+ * @property instantiable - False when the type is abstract or a singleton.
+ */
 export interface ParentTarget {
     readonly kind: SymbolKind;
     readonly name: string;
-    /** Constructor arguments of the type. */
     readonly args: readonly string[];
     readonly hasConstructor: boolean;
     readonly instantiable: boolean;
 }
-/** The symbol a generated example calls or constructs, with what decides how. */
+/**
+ * The symbol a generated example calls or constructs, with what decides how.
+ *
+ * @property kind - Kind of the symbol, such as `function`, `method`, `class` or `struct`.
+ * @property name - Name of the symbol.
+ * @property args - Argument expressions, receivers excluded.
+ * @property parent - Type or namespace the symbol belongs to, or `null` for a top-level symbol.
+ * @property isStatic - True when the symbol is called on its type rather than on an instance.
+ * @property isAsync - True when the call must be awaited.
+ * @property instantiable - For types: false when abstract or a singleton.
+ * @property isConstructor - True when the symbol is a constructor of `parent`.
+ * @property hasConstructor - For types: whether a constructor was found.
+ * @property returnsValue - True when the call yields a value that the example binds to a variable.
+ * @property returnType - Declared return type, or `null` when none is declared.
+ * @property importContext - What to import, or `null` when the symbol needs no import or none can be derived.
+ */
 export interface CallTarget {
     readonly kind: SymbolKind;
     readonly name: string;
-    /** Argument expressions, receivers excluded. */
     readonly args: readonly string[];
     readonly parent: ParentTarget | null;
     readonly isStatic: boolean;
     readonly isAsync: boolean;
-    /** For types: false when abstract or a singleton. */
     readonly instantiable: boolean;
     readonly isConstructor: boolean;
-    /** For types: whether a constructor was found. */
     readonly hasConstructor: boolean;
     readonly returnsValue: boolean;
     readonly returnType: string | null;
-    /** What to import, or `null` when the symbol needs no import or none can be derived. */
     readonly importContext: ImportContext | null;
 }
 /**
- * Builds a usage example from a signature: an import where the language
- * allows one, the instance a method needs, then the call.
- * Returns `null` for symbols that are not called.
+ * @brief Builds a usage example from a signature: an import where the language allows one,
+ * the instance a method needs, then the call.
+ *
+ * @param style - Call syntax of the target's language.
+ * @param target - Symbol the example uses.
+ * @returns Example source, or `null` for symbols that are not called.
  */
 export declare function buildExample(style: CallStyle, target: CallTarget): string | null;

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

@@ -1,78 +1,113 @@
 import { type SymbolKind } from '../../model';
 import type { Node, Query } from 'web-tree-sitter';
 import type { LanguageSpec } from './language';
-/** One parameter as declared. */
+/**
+ * One parameter as declared.
+ *
+ * @property name - Name with its variadic marker, such as `...rest` or `*args`.
+ * @property type - Declared type text, or `null` when the language or declaration has none.
+ * @property defaultValue - Default value text, truncated, or `null` when there is none.
+ * @property optional - True when the parameter may be left out of a call.
+ * @property argument - Expression a generated call passes for this parameter.
+ */
 export interface RawParameter {
-    /** Name with its variadic marker, such as `...rest` or `*args`. */
     readonly name: string;
     readonly type: string | null;
     defaultValue: string | null;
     optional: boolean;
-    /** Expression a generated call passes for this parameter. */
     readonly argument: string;
 }
-/** A field, property or enum member as declared. */
+/**
+ * A field, property or enum member as declared.
+ *
+ * @property name - Name of the field.
+ * @property type - Declared type text, or `null` when none is declared.
+ * @property defaultValue - Initial value text, truncated, or `null` when there is none.
+ * @property optional - True when the field is nullable or optional.
+ * @property annotations - Decorator, attribute and annotation texts on the field.
+ * @property comment - Cleaned doc comment text, or `null`.
+ */
 export interface RawField {
     readonly name: string;
     readonly type: string | null;
     readonly defaultValue: string | null;
     readonly optional: boolean;
     readonly annotations: readonly string[];
-    /** Cleaned doc comment text, or `null`. */
     readonly comment: string | null;
 }
-/** One definition as found in the syntax tree, before rendering. */
+/**
+ * @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 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`.
+ * @property parameters - Parameters as declared, with the receiver left out.
+ * @property fields - Fields, properties and enum members declared on this type.
+ * @property returnType - Declared return type text, or `null`.
+ * @property typeParameters - Names the declaration introduces as type parameters, such as `T`. They never name a real type.
+ * @property heritage - For a type: the text after its name that lists what it extends or is composed of. `''` otherwise.
+ * @property instantiable - False for abstract classes and singletons.
+ * @property isStatic - True for a method called on its type rather than on an instance.
+ * @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 children - Members nested under this symbol.
+ */
 export interface RawSymbol {
     kind: SymbolKind;
     readonly name: string;
     readonly line: number;
-    /** Declaration head. Empty when `inferred`. */
     readonly signature: string;
-    /** Keywords in front of the name, such as `export` or `static`. */
     readonly modifiers: readonly string[];
     readonly annotations: readonly string[];
-    /** Cleaned doc comment text, or `null`. */
     readonly comment: string | null;
-    /** Receivers excluded. */
     readonly parameters: readonly RawParameter[];
     readonly fields: RawField[];
     readonly returnType: string | null;
-    /** Names the declaration introduces as type parameters, such as `T`. They never name a real type. */
     readonly typeParameters: readonly string[];
-    /** For a type: the text after its name that lists what it extends or is composed of. `''` otherwise. */
     readonly heritage: string;
     readonly isAsync: boolean;
-    /** False for abstract classes and singletons. */
     readonly instantiable: boolean;
     isStatic: boolean;
     returnsValue: boolean;
-    /** True for an owner type that is not declared in this file. */
     readonly inferred: boolean;
     readonly children: RawSymbol[];
 }
-/** Symbols and package name extracted from one source file. */
+/**
+ * Symbols and package name extracted from one source file.
+ *
+ * @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.
+ */
 export interface ExtractedFile {
     readonly symbols: RawSymbol[];
-    /** Package or namespace the file declares, when the language has one. */
     readonly packageName: string | null;
 }
 /**
- * Turns a parsed file into a tree of {@link RawSymbol}s, driven by a {@link LanguageSpec}.
+ * @brief Turns a parsed file into a tree of {@link RawSymbol}s, driven by a {@link LanguageSpec}.
  *
- * Holds no state, so one instance serves every file. Created by `RepositoryScanner`
- * in `scanner/scanner.ts` and passed to `CodePlanner` in `planner.ts`, which calls
- * {@link SymbolExtractor.extract} once per parsed file.
+ * Holds no state, so one instance serves every file. Created with `new SymbolExtractor()` by
+ * `RepositoryScanner` in `scanner/scanner.ts` and passed to `CodePlanner` in `planner.ts`, which
+ * calls {@link SymbolExtractor.extract} once per parsed file.
  */
 export declare class SymbolExtractor {
     /**
      * Runs the language's tags query over the tree and builds the symbol tree from its matches.
      *
+     * @param root - Root node of the parsed tree.
+     * @param query - Compiled tags query of the language.
+     * @param spec - Language spec that drives the extraction.
      * @param source - Full text of the file the tree was parsed from; node offsets index into it.
+     * @returns Symbols of the file and its declared package name.
      */
     extract(root: Node, query: Query, spec: LanguageSpec, source: string): ExtractedFile;
     /**
-     * Merges the query matches into one definition per node (per name for fields), sorted by
+     * @brief Merges the query matches into one definition per node (per name for fields), sorted by
      * position with outer nodes first, and picks up the declared package name.
+     *
+     * @param root - Root node of the parsed tree.
+     * @param query - Compiled tags query of the language.
+     * @returns Merged definitions, and the package name or `null` when none is declared.
      */
     private collect;
 }

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

@@ -1,6 +1,11 @@
 import { Parser, Query } from 'web-tree-sitter';
 import type { LanguageSpec } from './language';
-/** Parser and compiled tags query for one language. */
+/**
+ * Parser and compiled tags query for one language.
+ *
+ * @property parser - Tree-sitter parser set to the language.
+ * @property query - Tags query compiled against the language.
+ */
 export interface LoadedGrammar {
     readonly parser: Parser;
     readonly query: Query;
@@ -9,8 +14,8 @@ export interface LoadedGrammar {
  * Loads tree-sitter grammars on first use and keeps one parser and compiled query per language.
  *
  * Holds the tree-sitter runtime init promise and one pending {@link LoadedGrammar} per
- * language id. Created by `RepositoryScanner` in `scanner/scanner.ts`; `CodePlanner` in
- * `planner.ts` loads a grammar for each file it parses.
+ * language id. Created with `new GrammarLoader(baseDir)` by `RepositoryScanner` in
+ * `scanner/scanner.ts`; `CodePlanner` in `planner.ts` calls `load` for each file it parses.
  */
 export declare class GrammarLoader {
     private readonly baseDir;
@@ -22,8 +27,18 @@ export declare class GrammarLoader {
      * @param baseDir - Absolute directory that relative grammar paths resolve against.
      */
     constructor(baseDir: string);
-    /** Returns the cached grammar of the spec's language, loading it on the first call. */
+    /**
+     * Returns the cached grammar of the spec's language, loading it on the first call.
+     *
+     * @param spec - Language whose grammar is needed.
+     * @returns Parser and query for the language, resolved once the grammar is loaded.
+     */
     load(spec: LanguageSpec): Promise<LoadedGrammar>;
-    /** Initialises the tree-sitter runtime once, then loads the grammar `.wasm` and compiles the query. */
+    /**
+     * Initialises the tree-sitter runtime once, then loads the grammar `.wasm` and compiles the query.
+     *
+     * @param spec - Language to load.
+     * @returns Parser and query for the language.
+     */
     private create;
 }