@g3nomaly/analyze 0.0.0-stage → 0.1.0

package/dist/api/bundle-builder.d.ts

@@ -0,0 +1,75 @@
+import type { DocsBundle } from '../model';
+import { type FileLister, type Reporter, type RepositoryScanner, type Source, type TaskTreeSource } from '../scanner';
+import type { SemanticIndexer } from './embedding';
+import type { ScanOptions } from './scan';
+/** What a `BundleBuilder` works with. */
+export interface BundleBuilderServices {
+    readonly files: FileLister;
+    readonly scanner: RepositoryScanner;
+    /** Embeds the nodes for search by meaning. `null` leaves that search out of the bundle. */
+    readonly semantic: SemanticIndexer | null;
+    /** Recorded in the bundle as the tool that produced it. */
+    readonly generator: string;
+    /** Receives the problems that do not stop a scan, such as a config file that is not valid. */
+    readonly reporter: Reporter;
+}
+/** The directories of one scan, per section. */
+export interface ScanSources {
+    readonly skills: readonly Source[];
+    readonly docs: readonly Source[];
+    readonly code: readonly Source[];
+    /** The task-manager tree of the repository. Empty when the repository has none. */
+    readonly tasks: readonly TaskTreeSource[];
+}
+/**
+ * Scans a repository into a bundle, with the file lister, scanner and embedder it holds.
+ *
+ * `createBuilder` in `src/api/services.ts` creates one per scan. `createDocs` writes its bundle into a site,
+ * and `ScanLoader` hands it to the query functions. Both first call `sources` to list the files of the scan,
+ * then `build` to read them; `ScanLoader` skips `build` when its cache has a bundle for the same files.
+ *
+ * @example
+ * const builder = new BundleBuilder({ files, scanner, semantic: null, generator: GENERATOR, reporter });
+ * const bundle = await builder.build(await builder.sources(scan), 'harbor');
+ */
+export declare class BundleBuilder {
+    private readonly services;
+    /** Creates a builder from the file lister, the scanner, the embedder and the reporter to use. */
+    constructor(services: BundleBuilderServices);
+    /**
+     * Lists the files of a scan without reading them.
+     *
+     * @param options - The repository and the directories to read skills and docs from.
+     * @returns The directories of each section with their files, and the task tree of the repository.
+     * @throws {SourceError} When the repository or one of the directories does not exist.
+     */
+    sources(options: ScanOptions): Promise<ScanSources>;
+    /**
+     * Reads the files of a scan and links what they declare.
+     *
+     * @param sources - The directories of each section, from `sources`.
+     * @returns The bundle, with a semantic index when the builder has an embedder.
+     */
+    build(sources: ScanSources, title: string): Promise<DocsBundle>;
+    /**
+     * Finds the task-manager tree of a repository: the directory `skills.settings.filetreeRoot` of its
+     * `.g3n.config.json` names, `docs/task-manager` by default.
+     *
+     * @returns One tree with the files below its directory, or none when the directory does not exist.
+     */
+    private tasksIn;
+    /**
+     * Reads the directory of the task tree from the config of a repository, without writing it.
+     *
+     * @param repo - Absolute path of the repository.
+     * @returns The root-relative POSIX path of the tree. The default when the config is not valid.
+     */
+    private taskTreeDir;
+    /**
+     * Picks the directories one section is read from.
+     *
+     * @param directories - Absolute directories the caller passed. Empty means the repository.
+     * @returns The repository, or one source per directory.
+     */
+    private sourcesIn;
+}

package/dist/api/bundle-cache.d.ts

@@ -0,0 +1,70 @@
+import type { DocsBundle } from '../model';
+import type { ScanSources } from './bundle-builder';
+import type { ScanOptions } from './scan';
+/** Keeps the bundle of one scan between runs. */
+export interface BundleCache {
+    /**
+     * Returns the kept bundle when it was built from the same files.
+     *
+     * @param fingerprint - Fingerprint of the files as they are now.
+     * @returns The bundle, or `null` when nothing is kept or a file changed.
+     */
+    read(fingerprint: string): Promise<DocsBundle | null>;
+    /**
+     * Keeps a bundle, in place of the one kept before.
+     *
+     * @param fingerprint - Fingerprint of the files the bundle was built from.
+     * @param bundle - The bundle to keep.
+     */
+    write(fingerprint: string, bundle: DocsBundle): Promise<void>;
+}
+/**
+ * Names the cache entry of a scan. Two scans share an entry when they read
+ * the same repository with the same options and the same version of the tool.
+ *
+ * @param generator - Name and version of the tool, such as `GENERATOR` in `src/api/services.ts`.
+ * @returns A file-name-safe key.
+ */
+export declare function cacheKey(scan: ScanOptions, generator: string): string;
+/**
+ * Fingerprints the files of a scan by path, size and modification time, and
+ * the directory of its task tree. The fingerprint changes when a file is
+ * added, removed or saved, and when the config moves the task tree.
+ *
+ * @param sources - The directories of the scan with their files.
+ * @returns 64 hex digits.
+ */
+export declare function fingerprintOf(sources: ScanSources): Promise<string>;
+/**
+ * Keeps a bundle in one file of a cache directory. The first line of the
+ * file is the fingerprint, the rest is the bundle as JSON.
+ *
+ * `openRetriever` creates one per query that scans a repository, in
+ * `analyze_out/cache` of that repository. The scan skips that directory, so
+ * a cache entry never changes the fingerprint of the next scan.
+ */
+export declare class FileBundleCache implements BundleCache {
+    private readonly directory;
+    private readonly file;
+    /**
+     * Creates the cache of one scan.
+     *
+     * @param directory - Cache directory. Created on the first write.
+     * @param key - Name of the entry, from `cacheKey`.
+     */
+    constructor(directory: string, key: string);
+    /**
+     * Reads the entry when its first line is the fingerprint.
+     *
+     * @param fingerprint - Fingerprint of the files as they are now.
+     * @returns The bundle, or `null` when the entry is missing, older or not readable.
+     */
+    read(fingerprint: string): Promise<DocsBundle | null>;
+    /**
+     * Writes the entry to a draft file and renames it into place.
+     *
+     * @param fingerprint - Fingerprint of the files the bundle was built from.
+     * @param bundle - The bundle to keep.
+     */
+    write(fingerprint: string, bundle: DocsBundle): Promise<void>;
+}

package/dist/api/bundle-loader.d.ts

@@ -0,0 +1,58 @@
+import { type DocsBundle } from '../model';
+import type { Reporter } from '../scanner';
+import type { BundleBuilder } from './bundle-builder';
+import { type BundleCache } from './bundle-cache';
+import type { ScanOptions } from './scan';
+/** Gets the bundle a query function reads. `loaderOf` in `src/api/source.ts` picks the implementation. */
+export interface BundleLoader {
+    /** Loads the bundle to query. */
+    load(): Promise<DocsBundle>;
+}
+/**
+ * Loads the bundle of a site that `createDocs` wrote, from the HTML file alone, without the repository the
+ * site was written from. `loaderOf` in `src/api/source.ts` creates one when a caller passes `from`
+ * (`--from` on the CLI); `openRetriever` loads it.
+ */
+export declare class SiteLoader implements BundleLoader {
+    private readonly file;
+    private readonly reporter;
+    /**
+     * Creates a loader for one site.
+     *
+     * @param file - Absolute path of the HTML file.
+     * @param reporter - Receives a warning when the site cannot be searched by meaning.
+     */
+    constructor(file: string, reporter: Reporter);
+    /**
+     * Reads the HTML file and takes the bundle out of it. Warns when its embeddings are of another format.
+     *
+     * @throws {SourceError} When the file is missing or is no analyze site.
+     */
+    load(): Promise<DocsBundle>;
+}
+/**
+ * Loads the bundle of a repository: from the cache when no file changed
+ * since the last scan, else from a new scan, which it then keeps.
+ *
+ * `loaderOf` in `src/api/source.ts` creates one when a caller passes no `from`; `openRetriever` loads it.
+ */
+export declare class ScanLoader implements BundleLoader {
+    private readonly builder;
+    private readonly scan;
+    private readonly cache;
+    private readonly reporter;
+    /**
+     * Creates a loader for one repository.
+     *
+     * @param cache - Keeps the bundle between runs. `null` scans every time.
+     * @param reporter - Receives a warning when the cache cannot be written.
+     */
+    constructor(builder: BundleBuilder, scan: ScanOptions, cache: BundleCache | null, reporter: Reporter);
+    /**
+     * Lists the files of the repository, then reads the cache or scans.
+     *
+     * @returns The bundle of the repository as it is now.
+     * @throws {SourceError} When the repository does not exist.
+     */
+    load(): Promise<DocsBundle>;
+}

package/dist/api/create-docs.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+declare const createDocsSchema: z.ZodPipe<z.ZodObject<{
+    onWarning: z.ZodOptional<z.ZodCustom<import("./options").WarningHandler, import("./options").WarningHandler>>;
+    repo: z.ZodOptional<z.ZodString>;
+    skillDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    docDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    excludes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    embeddings: z.ZodOptional<z.ZodBoolean>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodTransform<{
+    scan: import("./scan").ScanOptions;
+    title: string;
+    reporter: import("../scanner").Reporter;
+}, {
+    onWarning?: import("./options").WarningHandler | undefined;
+    repo?: string | undefined;
+    skillDirs?: readonly string[] | undefined;
+    docDirs?: readonly string[] | undefined;
+    excludes?: readonly string[] | undefined;
+    embeddings?: boolean | undefined;
+    title?: string | undefined;
+}>>;
+/** Options of `createDocs`: what to scan and the title of the site. */
+export type CreateDocsOptions = z.input<typeof createDocsSchema>;
+/** Where `createDocs` wrote the site and what the site holds. */
+export interface CreateDocsResult {
+    /** Absolute path of the site: `analyze_out/index.html` in the repository. */
+    readonly out: string;
+    readonly bytes: number;
+    readonly skills: number;
+    readonly docs: number;
+    readonly files: number;
+    readonly symbols: number;
+    /** Glossary terms. */
+    readonly terms: number;
+    readonly decisions: number;
+    /** Operations of OpenAPI documents. */
+    readonly operations: number;
+    /** Definitions of JSON Schemas and of OpenAPI documents. */
+    readonly definitions: number;
+    /** SQL files that create tables. */
+    readonly schemas: number;
+    /** Tables of those files. */
+    readonly tables: number;
+    /** Directories of SQL files that create no table. */
+    readonly catalogs: number;
+    /** Queries and statements of those directories. */
+    readonly queries: number;
+    /** Plans of the task tree. */
+    readonly plans: number;
+    /** Tasks of the task tree. */
+    readonly tasks: number;
+    /** Tasks with the status `completed`. */
+    readonly completedTasks: number;
+    /** Links between nodes: type references, mentions and the like. */
+    readonly links: number;
+    /** Nodes that search by meaning can find, and the model that embedded them. `null` without embeddings. */
+    readonly embedded: {
+        readonly nodes: number;
+        readonly model: string;
+    } | null;
+}
+/**
+ * Scans a repository and writes its documentation site to `analyze_out/index.html` in the repository.
+ *
+ * @param options - What to scan and the title. Default: the working directory.
+ * @returns Where the site was written and what it holds.
+ * @throws {OptionsError} When the options are not valid.
+ * @throws {SourceError} When the repository or one of the directories does not exist.
+ */
+export declare function createDocs(options?: CreateDocsOptions): Promise<CreateDocsResult>;
+export {};

package/dist/api/embedding.d.ts

@@ -0,0 +1,32 @@
+import type { GraphNode, SemanticIndex } from '../model';
+/** Adds search by meaning to a bundle. `BundleBuilder.build` calls it when the scan has embeddings. */
+export interface SemanticIndexer {
+    /**
+     * Embeds the searchable nodes of a scan.
+     *
+     * @returns The index for `DocsBundle.semantic`.
+     */
+    index(nodes: readonly GraphNode[]): Promise<SemanticIndex>;
+}
+/**
+ * Embeds nodes with the model that ships with the package. Holds the word table of the model, read on first
+ * use from two files: `vectors.bin` and `vocab.txt` in `build/embedding/` when run from source, or beside the
+ * bundle when built.
+ *
+ * `shippedModel` in `src/api/services.ts` imports this module on first use and creates one for each scan with
+ * embeddings, with its own directory as `baseDir`.
+ */
+export declare class ShippedModelIndexer implements SemanticIndexer {
+    private readonly baseDir;
+    private table;
+    /**
+     * Creates an indexer that has not read the model yet.
+     *
+     * @param baseDir - Absolute directory that relative paths of the bundled model files resolve against.
+     */
+    constructor(baseDir: string);
+    /** Reads the model on the first call, then embeds the searchable nodes into an index for `DocsBundle.semantic`. */
+    index(nodes: readonly GraphNode[]): Promise<SemanticIndex>;
+    /** Reads the two files of the model and unpacks the four-bit vectors into a word table. */
+    private load;
+}

package/dist/api/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Options a caller passed that do not form a valid call. Holds one issue per problem.
+ * Thrown by `parseOptions` in `src/api/options.ts`; `src/cli/index.ts` prints the usage and exits with 2 for it.
+ */
+export declare class OptionsError extends Error {
+    readonly issues: readonly string[];
+    readonly name = "OptionsError";
+    /**
+     * Creates the error from what is wrong.
+     *
+     * @param issues - One line per problem: the option and what is wrong with it.
+     */
+    constructor(issues: readonly string[]);
+}
+/**
+ * A query that cannot be answered, such as one for a node that does not exist. Thrown by `src/api/target.ts`
+ * and `src/api/search.ts`; the CLI exits with 1 for it.
+ */
+export declare class QueryError extends Error {
+    readonly name = "QueryError";
+}
+/**
+ * A repository, a directory or a site file that is missing or cannot be read. Thrown by the bundle builder,
+ * loader and site reader in `src/api/`; the CLI exits with 1 for it.
+ */
+export declare class SourceError extends Error {
+    readonly name = "SourceError";
+}

package/dist/api/list.d.ts

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import type { NodeFilter, NodeSummary, Retriever } from '../retrieval';
+declare const listSchema: z.ZodPipe<z.ZodObject<{
+    onWarning: z.ZodOptional<z.ZodCustom<import("./options").WarningHandler, import("./options").WarningHandler>>;
+    kinds: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        agent: "agent";
+        api: "api";
+        asset: "asset";
+        catalog: "catalog";
+        class: "class";
+        database: "database";
+        decision: "decision";
+        decisions: "decisions";
+        definition: "definition";
+        document: "document";
+        enum: "enum";
+        field: "field";
+        folder: "folder";
+        function: "function";
+        glossary: "glossary";
+        hook: "hook";
+        interface: "interface";
+        json: "json";
+        method: "method";
+        namespace: "namespace";
+        operation: "operation";
+        parameter: "parameter";
+        phase: "phase";
+        plan: "plan";
+        query: "query";
+        reference: "reference";
+        schema: "schema";
+        section: "section";
+        skill: "skill";
+        source: "source";
+        struct: "struct";
+        table: "table";
+        task: "task";
+        term: "term";
+        trait: "trait";
+        type: "type";
+    }>>>>;
+    section: z.ZodOptional<z.ZodEnum<{
+        code: "code";
+        database: "database";
+        docs: "docs";
+        skills: "skills";
+        tasks: "tasks";
+    }>>;
+    repo: z.ZodOptional<z.ZodString>;
+    skillDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    docDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    excludes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    embeddings: z.ZodOptional<z.ZodBoolean>;
+    from: z.ZodOptional<z.ZodString>;
+    cache: z.ZodOptional<z.ZodBoolean>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodTransform<{
+    source: import("./source").BundleSource;
+    reporter: import("../scanner").Reporter;
+    request: {
+        filter: NodeFilter;
+        limit: number | null;
+    };
+}, {
+    onWarning?: import("./options").WarningHandler | undefined;
+    kinds?: readonly ("agent" | "api" | "asset" | "catalog" | "class" | "database" | "decision" | "decisions" | "definition" | "document" | "enum" | "field" | "folder" | "function" | "glossary" | "hook" | "interface" | "json" | "method" | "namespace" | "operation" | "parameter" | "phase" | "plan" | "query" | "reference" | "schema" | "section" | "skill" | "source" | "struct" | "table" | "task" | "term" | "trait" | "type")[] | undefined;
+    section?: "code" | "database" | "docs" | "skills" | "tasks" | undefined;
+    repo?: string | undefined;
+    skillDirs?: readonly string[] | undefined;
+    docDirs?: readonly string[] | undefined;
+    excludes?: readonly string[] | undefined;
+    embeddings?: boolean | undefined;
+    from?: string | undefined;
+    cache?: boolean | undefined;
+    limit?: number | undefined;
+}>>;
+/** Options of `list`: the filter, the limit, and the bundle to list. */
+export type ListOptions = z.input<typeof listSchema>;
+/** One `list` on a loaded bundle. */
+export interface ListRequest {
+    readonly filter: NodeFilter;
+    /** Most rows. `null` lists everything. */
+    readonly limit: number | null;
+}
+/** What `list` finds. The CLI prints it with `list --json`. */
+export interface ListResult {
+    readonly nodes: readonly NodeSummary[];
+}
+/**
+ * Lists the pages and entries of a loaded bundle.
+ *
+ * @param request - The filter and the limit.
+ * @returns The nodes, in the order of the navigation.
+ */
+export declare function listIn(retriever: Retriever, request: ListRequest): ListResult;
+/**
+ * Lists pages and entries.
+ *
+ * @param options - The filter, the limit, and the repository or site to list. Default: every node of the working directory.
+ * @returns The nodes, in the order of the navigation.
+ * @throws {OptionsError} When the options are not valid.
+ * @throws {SourceError} When the repository or the site cannot be read.
+ */
+export declare function list(options?: ListOptions): Promise<ListResult>;
+export {};

package/dist/api/options.d.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import type { NodeFilter } from '../retrieval';
+import { type Reporter } from '../scanner';
+/** Receives problems that do not stop a call, such as a scan that could not be cached. */
+export type WarningHandler = (message: string) => void;
+/** The option every function takes to hear about warnings. Without it, warnings are dropped. */
+export declare const warningShape: {
+    onWarning: z.ZodOptional<z.ZodCustom<WarningHandler, WarningHandler>>;
+};
+/** The options that narrow the nodes a query looks at. */
+export declare const filterShape: {
+    /** Only nodes of these kinds. Empty or absent keeps every kind. */
+    kinds: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        agent: "agent";
+        api: "api";
+        asset: "asset";
+        catalog: "catalog";
+        class: "class";
+        database: "database";
+        decision: "decision";
+        decisions: "decisions";
+        definition: "definition";
+        document: "document";
+        enum: "enum";
+        field: "field";
+        folder: "folder";
+        function: "function";
+        glossary: "glossary";
+        hook: "hook";
+        interface: "interface";
+        json: "json";
+        method: "method";
+        namespace: "namespace";
+        operation: "operation";
+        parameter: "parameter";
+        phase: "phase";
+        plan: "plan";
+        query: "query";
+        reference: "reference";
+        schema: "schema";
+        section: "section";
+        skill: "skill";
+        source: "source";
+        struct: "struct";
+        table: "table";
+        task: "task";
+        term: "term";
+        trait: "trait";
+        type: "type";
+    }>>>>;
+    /** Only nodes of this section. */
+    section: z.ZodOptional<z.ZodEnum<{
+        code: "code";
+        database: "database";
+        docs: "docs";
+        skills: "skills";
+        tasks: "tasks";
+    }>>;
+};
+/** The filter options after validation. */
+type FilterFields = z.output<z.ZodObject<typeof filterShape>>;
+/**
+ * Turns validated filter options into the filter the retriever takes.
+ *
+ * @returns The filter. Absent options keep every node.
+ */
+export declare function filterOf(fields: FilterFields): NodeFilter;
+/** Turns the warning option into the reporter the services take: one that hands each warning to the handler, or drops it. */
+export declare function reporterOf(onWarning: WarningHandler | undefined): Reporter;
+/**
+ * Validates the options a caller passed against the schema of a function.
+ *
+ * @param schema - The schema of the options, with its transform.
+ * @returns The options after the transform.
+ * @throws {OptionsError} When the options do not fit the schema. Its `issues` name each problem.
+ */
+export declare function parseOptions<Schema extends z.ZodType>(schema: Schema, input: unknown): z.output<Schema>;
+export {};

package/dist/api/refs.d.ts

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+import type { NodeFilter, NodeSummary, ReferenceOptions, References, Retriever } from '../retrieval';
+declare const refsSchema: z.ZodPipe<z.ZodObject<{
+    onWarning: z.ZodOptional<z.ZodCustom<import("./options").WarningHandler, import("./options").WarningHandler>>;
+    kinds: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        agent: "agent";
+        api: "api";
+        asset: "asset";
+        catalog: "catalog";
+        class: "class";
+        database: "database";
+        decision: "decision";
+        decisions: "decisions";
+        definition: "definition";
+        document: "document";
+        enum: "enum";
+        field: "field";
+        folder: "folder";
+        function: "function";
+        glossary: "glossary";
+        hook: "hook";
+        interface: "interface";
+        json: "json";
+        method: "method";
+        namespace: "namespace";
+        operation: "operation";
+        parameter: "parameter";
+        phase: "phase";
+        plan: "plan";
+        query: "query";
+        reference: "reference";
+        schema: "schema";
+        section: "section";
+        skill: "skill";
+        source: "source";
+        struct: "struct";
+        table: "table";
+        task: "task";
+        term: "term";
+        trait: "trait";
+        type: "type";
+    }>>>>;
+    section: z.ZodOptional<z.ZodEnum<{
+        code: "code";
+        database: "database";
+        docs: "docs";
+        skills: "skills";
+        tasks: "tasks";
+    }>>;
+    repo: z.ZodOptional<z.ZodString>;
+    skillDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    docDirs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    excludes: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    embeddings: z.ZodOptional<z.ZodBoolean>;
+    from: z.ZodOptional<z.ZodString>;
+    cache: z.ZodOptional<z.ZodBoolean>;
+    target: z.ZodString;
+    incoming: z.ZodOptional<z.ZodBoolean>;
+    outgoing: z.ZodOptional<z.ZodBoolean>;
+    edges: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        affects: "affects";
+        depends: "depends";
+        extends: "extends";
+        mentions: "mentions";
+        names: "names";
+        reads: "reads";
+        references: "references";
+        returns: "returns";
+        throws: "throws";
+        type: "type";
+        uses: "uses";
+        writes: "writes";
+    }>>>>;
+}, z.core.$strict>, z.ZodTransform<{
+    source: import("./source").BundleSource;
+    reporter: import("../scanner").Reporter;
+    request: {
+        target: string;
+        filter: NodeFilter;
+        references: {
+            direction: "both" | "in" | "out";
+            kinds: readonly ("affects" | "depends" | "extends" | "mentions" | "names" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[];
+        };
+    };
+}, {
+    onWarning?: import("./options").WarningHandler | undefined;
+    kinds?: readonly ("agent" | "api" | "asset" | "catalog" | "class" | "database" | "decision" | "decisions" | "definition" | "document" | "enum" | "field" | "folder" | "function" | "glossary" | "hook" | "interface" | "json" | "method" | "namespace" | "operation" | "parameter" | "phase" | "plan" | "query" | "reference" | "schema" | "section" | "skill" | "source" | "struct" | "table" | "task" | "term" | "trait" | "type")[] | undefined;
+    section?: "code" | "database" | "docs" | "skills" | "tasks" | undefined;
+    repo?: string | undefined;
+    skillDirs?: readonly string[] | undefined;
+    docDirs?: readonly string[] | undefined;
+    excludes?: readonly string[] | undefined;
+    embeddings?: boolean | undefined;
+    from?: string | undefined;
+    cache?: boolean | undefined;
+    target: string;
+    incoming?: boolean | undefined;
+    outgoing?: boolean | undefined;
+    edges?: readonly ("affects" | "depends" | "extends" | "mentions" | "names" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[] | undefined;
+}>>;
+/** Options of `refs`: the node, which links to follow, and the bundle to read. */
+export type RefsOptions = z.input<typeof refsSchema>;
+/** One `refs` on a loaded bundle. */
+export interface RefsRequest {
+    /** Id, path or name of the node. */
+    readonly target: string;
+    readonly filter: NodeFilter;
+    readonly references: ReferenceOptions;
+}
+/** What `refs` finds. The CLI prints it with `refs --json`. */
+export interface RefsResult extends References {
+    /** The node the references are of. */
+    readonly node: NodeSummary;
+}
+/**
+ * Lists the references of one node of a loaded bundle.
+ *
+ * @param request - The node, the filter that narrows a name, and the references to keep.
+ * @returns The node with what it links to and what links to it.
+ * @throws {QueryError} When no node fits the target, or several do.
+ */
+export declare function refsIn(retriever: Retriever, request: RefsRequest): RefsResult;
+/**
+ * Lists what a node links to and what links to it.
+ *
+ * @param options - The node, which links to follow, and the repository or site to read.
+ * @returns The node with its references.
+ * @throws {OptionsError} When the options are not valid.
+ * @throws {SourceError} When the repository or the site cannot be read.
+ * @throws {QueryError} When no node fits the target, or several do.
+ */
+export declare function refs(options: RefsOptions): Promise<RefsResult>;
+export {};