@g3nomaly/analyze 0.0.0-stage → 0.1.1

package/dist/retrieval/retriever.d.ts

@@ -0,0 +1,105 @@
+import type { NodeRef } from '../model';
+import { type Graph } from '../query';
+import { type ReferenceOptions } from './describe';
+import { type NodeFilter } from './filter';
+import type { NodeReport, NodeSummary, References } from './report';
+import { type Resolution } from './resolve';
+/** The search modes a caller can pick from, the default first. */
+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];
+/**
+ * @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;
+    readonly limit: number;
+    readonly filter: NodeFilter;
+}
+/**
+ * @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 {
+    readonly match: 'name' | 'text' | 'meaning';
+    readonly score: number | null;
+}
+/**
+ * @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 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;
+    private nameIndex;
+    /**
+     * @brief Creates a retriever for one bundle.
+     *
+     * @param graph - Graph of the bundle, from `new Graph(bundle)`.
+     */
+    constructor(graph: Graph);
+    /**
+     * @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;
+    /**
+     * @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[];
+    /**
+     * @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[];
+    /**
+     * @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.
+     * @returns The node, the candidates when several fit, or `missing`.
+     */
+    resolve(text: string, filter: NodeFilter): Resolution;
+    /**
+     * @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;
+    /**
+     * @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;
+    /**
+     * @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

@@ -0,0 +1,27 @@
+import { type NodeRef } from '../model';
+import { type Graph } from '../query';
+import type { NodeSummary } from './report';
+/**
+ * @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;
+/**
+ * @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;
+/**
+ * @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

@@ -0,0 +1,36 @@
+/**
+ * @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;
+/**
+ * @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;
+/**
+ * @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;
+/**
+ * @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;
+/**
+ * @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

@@ -0,0 +1,12 @@
+import type { DocStyle } from '../language';
+import { type ParsedDoc } from './types';
+export { cleanComments, cleanDocstring } from './clean';
+export type { ParsedDoc, ParsedTag, ParsedTagKind } from './types';
+/**
+ * @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

@@ -0,0 +1,8 @@
+import type { ParsedDoc } from './types';
+/**
+ * @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

@@ -0,0 +1,8 @@
+import type { ParsedDoc } from './types';
+/**
+ * @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

@@ -0,0 +1,19 @@
+import type { ParsedDoc } from './types';
+/**
+ * @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 {
+    readonly titledExamples?: boolean;
+    readonly braceLinks?: boolean;
+}
+/**
+ * @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

@@ -0,0 +1,33 @@
+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;
+/**
+ * @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;
+    readonly text: string;
+}
+/**
+ * @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 {
+    readonly description: string;
+    readonly tags: readonly ParsedTag[];
+    readonly example: string | null;
+}
+/** Result for a symbol with no doc comment. */
+export declare const EMPTY_DOC: ParsedDoc;

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

@@ -0,0 +1,8 @@
+import type { ParsedDoc } from './types';
+/**
+ * @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

@@ -0,0 +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.
+ *
+ * @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;
+    readonly args: readonly string[];
+    readonly hasConstructor: boolean;
+    readonly instantiable: boolean;
+}
+/**
+ * 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;
+    readonly args: readonly string[];
+    readonly parent: ParentTarget | null;
+    readonly isStatic: boolean;
+    readonly isAsync: boolean;
+    readonly instantiable: boolean;
+    readonly isConstructor: boolean;
+    readonly hasConstructor: boolean;
+    readonly returnsValue: boolean;
+    readonly returnType: string | null;
+    readonly importContext: ImportContext | null;
+}
+/**
+ * @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

@@ -0,0 +1,113 @@
+import { type SymbolKind } from '../../model';
+import type { Node, Query } from 'web-tree-sitter';
+import type { LanguageSpec } from './language';
+/**
+ * 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 {
+    readonly name: string;
+    readonly type: string | null;
+    defaultValue: string | null;
+    optional: boolean;
+    readonly argument: string;
+}
+/**
+ * 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[];
+    readonly comment: string | null;
+}
+/**
+ * @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;
+    readonly signature: string;
+    readonly modifiers: readonly string[];
+    readonly annotations: readonly string[];
+    readonly comment: string | null;
+    readonly parameters: readonly RawParameter[];
+    readonly fields: RawField[];
+    readonly returnType: string | null;
+    readonly typeParameters: readonly string[];
+    readonly heritage: string;
+    readonly isAsync: boolean;
+    readonly instantiable: boolean;
+    isStatic: boolean;
+    returnsValue: boolean;
+    readonly inferred: boolean;
+    readonly children: RawSymbol[];
+}
+/**
+ * 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[];
+    readonly packageName: string | null;
+}
+/**
+ * @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 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;
+    /**
+     * @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

@@ -0,0 +1,44 @@
+import { Parser, Query } from 'web-tree-sitter';
+import type { LanguageSpec } from './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;
+}
+/**
+ * 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 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;
+    private runtime;
+    private readonly grammars;
+    /**
+     * Stores the directory grammar paths resolve against. Nothing loads until the first `load`.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * @param spec - Language to load.
+     * @returns Parser and query for the language.
+     */
+    private create;
+}

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

@@ -0,0 +1,183 @@
+import type { SymbolKind } from '../../model';
+import type { Node } from 'web-tree-sitter';
+/**
+ * @brief Doc comment dialect, which decides how the scanner reads doc comments.
+ *
+ * - `tagged`: `@param`-style tags (JSDoc, Javadoc, Doxygen, PHPDoc, KDoc, Scaladoc).
+ * - `yard`: `tagged`, with the title of an `@example` on the tag line.
+ * - `markdown`: free markdown with headed sections (rustdoc, godoc).
+ * - `python`: docstrings in Google, NumPy or reST layout.
+ * - `xml`: C# XML documentation.
+ */
+export type DocStyle = 'tagged' | 'yard' | 'markdown' | 'python' | 'xml';
+/**
+ * What a language spec can inspect when it classifies one definition.
+ *
+ * @property node - Tree-sitter node of the definition.
+ * @property signature - Declaration head, without the body.
+ * @property annotations - Decorator, attribute and annotation texts in front of the definition.
+ * @property returnType - Declared return type text, e.g. `number`, or `null` when the grammar exposes none.
+ * @property hasReceiver - True when the parameter list starts with a receiver such as `self`.
+ */
+export interface DefinitionFacts {
+    readonly node: Node;
+    readonly signature: string;
+    readonly annotations: readonly string[];
+    readonly returnType: string | null;
+    readonly hasReceiver: boolean;
+}
+/**
+ * What an import hook knows about the symbol an example uses.
+ *
+ * @property filePath - Root-relative path of the file that declares the symbol.
+ * @property name - Outermost symbol around the one the example uses: the class of a method, or the function itself.
+ * @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`.
+ */
+export interface ImportContext {
+    readonly filePath: string;
+    readonly name: string;
+    readonly kind: SymbolKind;
+    readonly modifiers: readonly string[];
+    readonly packageName: string | null;
+}
+/**
+ * How a language spells a call. Drives generated examples.
+ *
+ * @property terminator - Statement terminator, `';'` or `''`.
+ * @property variableCase - Case of generated variable names.
+ * @property variablePrefix - Prefix of variable names, `'$'` in PHP.
+ * @property memberAccess - Operator between an instance and its member, e.g. `.` or `->`.
+ * @property staticAccess - Operator between a type and its static member, e.g. `::`.
+ * @property namespaceAccess - Separator between a namespace and its member, or `null` when members are called unqualified.
+ */
+export interface CallStyle {
+    readonly terminator: string;
+    readonly variableCase: 'camel' | 'snake';
+    readonly variablePrefix?: string;
+    readonly memberAccess: string;
+    readonly staticAccess: string;
+    readonly namespaceAccess: string | null;
+    /** Binds the value of `expression` to `variable`. */
+    declare(variable: string, expression: string, returnType: string | null): string;
+    /**
+     * @brief Statement that creates an instance of `type` named `variable`.
+     *
+     * @param hasConstructor - False when the scanner found no constructor in the file.
+     * @returns The statement, or `null` when the language cannot build the type without a constructor.
+     */
+    construct(type: string, args: string, variable: string, hasConstructor: boolean): string | null;
+    /** Wraps an expression that must be awaited. */
+    await?(expression: string): string;
+    /**
+     * Rewrites one argument, for languages with named arguments.
+     *
+     * @param parameter - Declaration node of the parameter the argument fills.
+     */
+    argument?(name: string, parameter: Node): string;
+    /**
+     * Line that brings the symbol into scope.
+     *
+     * @param context - What the import needs to know about the symbol.
+     * @returns The import line, or `null` when it cannot be derived.
+     */
+    importLine?(context: ImportContext): string | null;
+}
+/**
+ * @brief Everything the scanner needs to support one language.
+ *
+ * Adding a language means adding one spec and listing it in `languages/index.ts`.
+ *
+ * @property id - Unique language id, e.g. `typescript`.
+ * @property label - Display name of the language, e.g. `TypeScript`.
+ * @property family - Languages whose types can refer to each other, such as TypeScript and JavaScript. A type name never links across families. Defaults to `id`.
+ * @property extensions - File extensions the language claims, e.g. `.ts`.
+ * @property accepts - For an extension several languages share, such as `.h`: answers whether this source is in this language. Specs are tried in registry order.
+ * @property grammarPath - Path of the tree-sitter grammar `.wasm`.
+ * @property highlight - shiki language id.
+ * @property query - Tree-sitter query. Captures `@definition.<kind>` on the definition node, `@name`, and optionally `@params`, `@body`, `@return`, `@owner`, `@type`, `@value`, `@receiver`, `@package`. `@owner` names the type a method declared outside it belongs to. `@definition.field` marks a field, property or enum member. With `@receiver` (Python's `self.x = ...`) the field belongs to the type around the enclosing method.
+ * @property typeSyntax - Where a declaration puts its type: `prefix` as in `int count`, `suffix` as in `count: int`, `none` for languages without declared types.
+ * @property annotationLabel - What the language calls its annotations, for example `Decorators`.
+ * @property docStyle - Dialect of the doc comments.
+ * @property docSource - Where documentation lives: `leading-comment` above the definition, or `docstring`, the first string of the body.
+ * @property commentTypes - Node types of comments.
+ * @property isDocComment - Restricts which leading comments count as documentation.
+ * @property annotationTypes - Node types of decorators, attributes and annotations.
+ * @property wrapperTypes - Parent node types that wrap a definition, such as `export_statement`.
+ * @property localScopeTypes - Node types whose descendants are local, such as closures.
+ * @property hoistedCommentParents - Parents whose leading comment documents their first child.
+ * @property receiverTypes - Parameter node types that are receivers.
+ * @property receiverNames - Parameter names that are receivers.
+ * @property skippedParamTypes - Parameter node types that never appear in a call.
+ * @property paramTypes - When set, only these node types inside a parameter list are parameters.
+ * @property isInstantiable - Answers from a declaration head whether the type can be constructed. Abstract types are excluded already.
+ * @property inferredOwnerKind - Kind given to an owner type that is not declared in the same file.
+ * @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.
+ */
+export interface LanguageSpec {
+    readonly id: string;
+    readonly label: string;
+    readonly family?: string;
+    readonly extensions: readonly string[];
+    readonly accepts?: (source: string) => boolean;
+    readonly grammarPath: string;
+    readonly highlight: string;
+    readonly query: string;
+    readonly typeSyntax: 'prefix' | 'suffix' | 'none';
+    readonly annotationLabel: string;
+    readonly docStyle: DocStyle;
+    readonly docSource: 'leading-comment' | 'docstring';
+    readonly commentTypes: readonly string[];
+    readonly isDocComment?: (text: string) => boolean;
+    readonly annotationTypes: readonly string[];
+    readonly wrapperTypes: readonly string[];
+    readonly localScopeTypes: readonly string[];
+    readonly hoistedCommentParents?: readonly string[];
+    readonly receiverTypes?: readonly string[];
+    readonly receiverNames?: readonly string[];
+    readonly skippedParamTypes?: readonly string[];
+    readonly paramTypes?: readonly string[];
+    readonly isInstantiable?: (signature: string) => boolean;
+    readonly inferredOwnerKind?: SymbolKind;
+    readonly splitQualifiedName?: (name: string) => {
+        owner: string;
+        name: string;
+    } | null;
+    /**
+     * Names a constructor can have inside a class called `className`.
+     *
+     * @param className - Name of the class the constructor belongs to.
+     */
+    constructorNames(className: string): readonly string[];
+    /**
+     * True when the definition is called on its type rather than on an instance.
+     *
+     * @param facts - What the spec can inspect about the definition.
+     */
+    isStatic(facts: DefinitionFacts): boolean;
+    /**
+     * True when a call to the definition yields a value, so a generated example binds it to a variable.
+     *
+     * @param facts - What the spec can inspect about the definition.
+     */
+    returnsValue(facts: DefinitionFacts): boolean;
+    readonly declaredReturnType?: (facts: DefinitionFacts) => string | null;
+    readonly call: CallStyle;
+}
+/**
+ * Language family of a spec.
+ *
+ * @param spec - Spec to read.
+ * @returns Its `family`, or its `id` when it sets none.
+ */
+export declare function familyOf(spec: LanguageSpec): string;
+/**
+ * Decides from a declared return type whether a call yields a value.
+ *
+ * @param returnType - Declared return type text, or `null` when the declaration has none.
+ * @param implicit - Answer for declarations without a return type.
+ */
+export declare function returnsValueFrom(returnType: string | null, implicit: boolean): boolean;