@equinor/fusion-framework-cli-plugin-ai-index 1.0.5 → 2.0.0

package/dist/types/config.d.ts

@@ -1,33 +1,74 @@
 import type { VectorStoreDocument } from '@equinor/fusion-framework-module-ai/lib';
 import type { FusionAIConfig } from '@equinor/fusion-framework-cli-plugin-ai-base';
 /**
- * Index-specific configuration for Fusion AI operations
+ * Index-specific configuration for Fusion AI document indexing operations.
+ *
+ * Controls which files are collected, how they are chunked, and what metadata
+ * is attached before being sent to the Azure AI Search vector store.
+ *
+ * @example
+ * ```ts
+ * const indexConfig: IndexConfig = {
+ *   patterns: ['src/\**\/*.ts', 'docs/\**\/*.md'],
+ *   ignore: ['dist/\**', 'node_modules/\**'],
+ *   metadata: { resolvePackage: true, resolveGit: true },
+ *   embedding: { chunkSize: 2000, chunkOverlap: 300 },
+ * };
+ * ```
  */
 export interface IndexConfig {
+    /** Azure Cognitive Search index name. Overridden by the `--azure-search-index-name` CLI flag. */
+    name?: string;
+    /** Azure OpenAI embedding deployment name. Overridden by the `--openai-embedding-deployment` CLI flag. */
+    model?: string;
     patterns?: string[];
-    /** Files will be processed as is, without any chunking or transformation */
+    /** Glob patterns for files that should be indexed as-is, without chunking or transformation. */
     rawPatterns?: string[];
-    /** Globby patterns to ignored, only used when providing paths to the command */
+    /** Glob patterns to ignore — only applied when file paths are provided to the command. */
     ignore?: string[];
-    /** Metadata processing configuration */
+    /** Respect `.gitignore` rules when globbing files. Defaults to `true`. Set to `false` for build-output directories that are gitignored. */
+    gitignore?: boolean;
+    /** Metadata processing configuration. */
     metadata?: {
-        /** Automatically resolve package information from source file paths */
+        /** Automatically resolve the nearest `package.json` and attach package name/version/keywords. */
         resolvePackage?: boolean;
+        /** Resolve git metadata (commit hash, date, permalink) for each source file. Defaults to `true`. */
         resolveGit?: boolean;
-        /** Custom metadata processors to transform metadata before embedding */
+        /**
+         * Custom callback to transform document attributes before embedding.
+         *
+         * @param metadata - The current attribute map for the document.
+         * @param document - The full vector-store document being processed.
+         * @returns The transformed attribute map.
+         */
         attributeProcessor?: (metadata: Record<string, unknown>, document: VectorStoreDocument) => Record<string, unknown>;
     };
-    /** Embedding generation configuration */
+    /** Embedding generation configuration. */
     embedding?: {
-        /** Size of text chunks for embedding */
+        /** Maximum token size of each text chunk sent for embedding generation. */
         chunkSize?: number;
-        /** Overlap between chunks */
+        /** Number of overlapping tokens between consecutive chunks. */
         chunkOverlap?: number;
     };
 }
 /**
- * Extended Fusion AI configuration with index-specific settings
+ * Fusion AI configuration extended with {@link IndexConfig | index-specific settings}.
+ *
+ * Used as the return type of `configureFusionAI()` when the `ai index add` or
+ * `ai index remove` commands are configured.
+ *
+ * @example
+ * ```ts
+ * import { configureFusionAI, type FusionAIConfigWithIndex } from '@equinor/fusion-framework-cli-plugin-ai-index';
+ *
+ * export default configureFusionAI((): FusionAIConfigWithIndex => ({
+ *   index: {
+ *     patterns: ['packages/\**\/*.ts', 'packages/\**\/*.md'],
+ *   },
+ * }));
+ * ```
  */
 export interface FusionAIConfigWithIndex extends FusionAIConfig {
+    /** Index-specific configuration for document collection, chunking, and metadata. */
     index?: IndexConfig;
 }

package/dist/types/delete-command.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Configured Commander command for the `ai index remove` subcommand.
+ *
+ * This constant is the fully-configured {@link Command} instance with all
+ * AI-specific options (embedding deployment, Azure Search credentials) applied
+ * via `withAiOptions`. It is registered with the CLI automatically by
+ * {@link registerAiPlugin}.
+ */
+export declare const deleteCommand: import("commander").Command;

package/dist/types/delete-command.options.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+/**
+ * Zod schema for validating options of the `ai index remove` command.
+ *
+ * Extends the base AI options schema ({@link AiOptionsSchema}) to require
+ * Azure Search credentials and the embedding deployment (needed to initialise
+ * the vector store service for document removal).
+ *
+ * @example
+ * ```ts
+ * const validated = await DeleteOptionsSchema.parseAsync(rawOptions);
+ * // validated.dryRun, validated.filter, validated.azureSearchEndpoint, etc.
+ * ```
+ */
+export declare const DeleteOptionsSchema: z.ZodObject<{
+    openaiApiKey: z.ZodString;
+    openaiApiVersion: z.ZodString;
+    openaiInstance: z.ZodString;
+    openaiChatDeployment: z.ZodOptional<z.ZodString>;
+    openaiEmbeddingDeployment: z.ZodString;
+    azureSearchEndpoint: z.ZodString;
+    azureSearchApiKey: z.ZodString;
+    azureSearchIndexName: z.ZodString;
+    dryRun: z.ZodBoolean;
+    filter: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Validated options for the `ai index remove` command.
+ *
+ * Inferred from {@link DeleteOptionsSchema}.
+ */
+export type DeleteOptions = z.infer<typeof DeleteOptionsSchema>;

package/dist/types/embeddings-command.d.ts

@@ -0,0 +1,11 @@
+import { type Command } from 'commander';
+/**
+ * Configured Commander command for the `ai index add` subcommand.
+ *
+ * This constant is the fully-configured {@link Command} instance with all
+ * AI-specific options (embedding deployment, Azure Search credentials) applied
+ * via `withAiOptions`. It is registered with the CLI automatically by
+ * {@link registerAiPlugin}.
+ */
+export declare const command: Command;
+export default command;

package/dist/types/embeddings-command.options.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * Zod schema for validating command options for the `ai index add` command.
+ *
+ * Extends the base AI options schema ({@link AiOptionsSchema}) with
+ * add-specific options such as `--dry-run`, `--diff`, `--config`,
+ * `--base-ref`, and `--clean`.
+ *
+ * Azure Search and embedding options that are optional in the base schema
+ * become **required** because the add command always writes to a
+ * vector store.
+ *
+ * @example
+ * ```ts
+ * const validated = await CommandOptionsSchema.parseAsync(rawOptions);
+ * // validated.dryRun, validated.azureSearchEndpoint, etc.
+ * ```
+ */
+export declare const CommandOptionsSchema: z.ZodObject<{
+    openaiApiKey: z.ZodString;
+    openaiApiVersion: z.ZodString;
+    openaiInstance: z.ZodString;
+    openaiChatDeployment: z.ZodOptional<z.ZodString>;
+    openaiEmbeddingDeployment: z.ZodString;
+    azureSearchEndpoint: z.ZodString;
+    azureSearchApiKey: z.ZodString;
+    azureSearchIndexName: z.ZodString;
+    dryRun: z.ZodBoolean;
+    config: z.ZodString;
+    diff: z.ZodBoolean;
+    baseRef: z.ZodOptional<z.ZodString>;
+    clean: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * Validated options for the `ai index add` command.
+ *
+ * Inferred from {@link CommandOptionsSchema} and used as the single
+ * source of truth for option types throughout the add/embeddings pipeline.
+ */
+export type CommandOptions = z.infer<typeof CommandOptionsSchema>;

package/dist/types/index.d.ts

@@ -1,8 +1,25 @@
 import type { Command } from 'commander';
 export { FusionAIConfigWithIndex, IndexConfig } from './config.js';
 /**
- * Registers the AI index plugin command with the CLI program
- * @param program - The Commander program instance to register commands with
+ * Registers the `ai index` command with the Fusion Framework CLI.
+ *
+ * Adds a single `index` command under `ai` with subcommands for indexing,
+ * searching, and removing documents in the Azure AI Search vector store.
+ *
+ * @param program - The root Commander {@link Command} instance to attach to.
+ *
+ * @example
+ * ```ts
+ * import { Command } from 'commander';
+ * import { registerAiPlugin } from '@equinor/fusion-framework-cli-plugin-ai-index';
+ *
+ * const program = new Command();
+ * registerAiPlugin(program);
+ * program.parse();
+ * // ffc ai index add [glob-patterns...]
+ * // ffc ai index search <query>
+ * // ffc ai index remove [source-paths...]
+ * ```
  */
 export declare function registerAiPlugin(program: Command): void;
 export default registerAiPlugin;

package/dist/types/search-command.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Configured Commander command for the `ai index search` subcommand.
+ *
+ * Fully-configured {@link Command} instance with all AI-specific options
+ * (embedding deployment, Azure Search credentials) applied via `withAiOptions`.
+ */
+export declare const searchCommand: import("commander").Command;
+export default searchCommand;

package/dist/types/utils/generate-chunk-id.d.ts

@@ -1,8 +1,20 @@
 /**
- * Generates a unique identifier for a document chunk based on file path
- * Creates a deterministic, URL-safe hash from the file path for validation and checks
- * @param filePath - The file path to generate an ID from
- * @param chunkIndex - Optional chunk index to append for multi-chunk documents
- * @returns A base64-encoded hash of the file path, optionally suffixed with chunk index
+ * Generates a deterministic, URL-safe identifier for a document chunk.
+ *
+ * The identifier is a Base64-encoded hash of the file path with all
+ * non-alphanumeric characters stripped, making it safe for use as an
+ * Azure AI Search document key.
+ *
+ * @param filePath - The relative file path to hash.
+ * @param chunkIndex - Optional zero-based chunk index appended to distinguish
+ *   multiple chunks originating from the same file.
+ * @returns A stable, alphanumeric document ID string.
+ *
+ * @example
+ * ```ts
+ * generateChunkId('packages/cli/src/index.ts');        // 'cGFja2FnZXMvY2xpL3NyYy9pbmRleC50cw'
+ * generateChunkId('packages/cli/src/index.ts', 0);     // 'cGFja2FnZXMvY2xpL3NyYy9pbmRleC50cw-0'
+ * generateChunkId('packages/cli/src/index.ts', 3);     // 'cGFja2FnZXMvY2xpL3NyYy9pbmRleC50cw-3'
+ * ```
  */
 export declare const generateChunkId: (filePath: string, chunkIndex?: number) => string;

package/dist/types/utils/git/file-changes.d.ts

@@ -1,21 +1,36 @@
 import type { ChangedFile, GitDiffOptions } from './types.js';
 /**
- * Get list of changed files using git diff with status
- * @param options - Git diff configuration options
- * @returns Array of changed files with their status
+ * Returns a list of files changed between `baseRef` and HEAD.
+ *
+ * Parses the output of `git diff --name-status` to classify each file as
+ * `'new'`, `'modified'`, or `'removed'`. Renames are expanded into a
+ * `'removed'` entry for the old path and a `'new'` entry for the new path.
+ *
+ * @param options - Configuration controlling the diff reference and working directory.
+ * @returns Array of changed files with their status.
+ * @throws {Error} If the working directory is not inside a git repository.
  */
 export declare const getChangedFiles: (options: GitDiffOptions) => Promise<ChangedFile[]>;
 /**
- * Determine the git status of a file, including handling renames
- * Returns an array of ChangedFile objects - if the file was renamed, returns both old and new paths
- * @param filePath - Absolute file path to check
- * @returns Promise resolving to array of changed files (1 or 2 items if renamed)
+ * Determines the git change status of a single file.
+ *
+ * Checks tracked status, porcelain output, and rename/copy detection to
+ * produce one or two {@link ChangedFile} entries (two when a rename is
+ * detected — one `'removed'` for the old path and one `'new'` for the
+ * current path).
+ *
+ * @param filePath - Absolute path to the file to inspect.
+ * @returns Array with one or two changed-file entries.
  */
 export declare const getFileStatus: (filePath: string) => Promise<ChangedFile[]>;
 /**
- * Check if a file path matches any of the changed files
- * @param filePath - File path to check
- * @param changedFiles - Array of changed file objects
- * @returns True if file has changed
+ * Checks whether a file path appears in a list of changed files.
+ *
+ * When the changed-files list is empty (no diff filtering active), every
+ * file is considered changed so that all files are processed.
+ *
+ * @param filePath - Absolute file path to look up.
+ * @param changedFiles - Array of {@link ChangedFile} entries to search.
+ * @returns `true` if the file has changed or if diff filtering is disabled.
  */
 export declare const isFileChanged: (filePath: string, changedFiles: ChangedFile[]) => boolean;

package/dist/types/utils/git/git-client.d.ts

@@ -1,15 +1,24 @@
 import { type SimpleGit } from 'simple-git';
 /**
- * Resolve the project root (git repository root) for a given file path
- * @param filePath - File path to resolve from
- * @returns Project root path or undefined if not in a git repository
+ * Resolves the git repository root for a given file path.
+ *
+ * Walks up the directory tree looking for a `.git` directory or file
+ * (to support worktrees) and returns the enclosing directory.
+ *
+ * @param filePath - Absolute file or directory path to resolve from.
+ * @returns Absolute path to the repository root, or `undefined` if not inside a git repo.
  */
 export declare const resolveProjectRoot: (filePath: string) => string | undefined;
 /**
- * Get or create a SimpleGit instance for a given file path
- * Uses caching to avoid creating multiple instances for the same repository
- * @param filePath - File path to get git instance for
- * @returns Git instance and repository path, or undefined if not in a git repository
+ * Returns a cached `SimpleGit` instance scoped to the repository that
+ * contains `filePath`.
+ *
+ * Instances are cached by repository root to avoid repeatedly spawning
+ * new git processes for the same repo.
+ *
+ * @param filePath - Absolute file path to locate the repository for.
+ * @returns An object containing the git client and the repository root path,
+ *   or `undefined` when `filePath` is not inside a git repository.
  */
 export declare const getGit: (filePath: string) => {
     git: SimpleGit | undefined;

package/dist/types/utils/git/metadata.d.ts

@@ -1,7 +1,11 @@
 import type { GitMetadata } from './types.js';
 /**
- * Extract git metadata for a file
- * @param filePath - Absolute file path
- * @returns Git metadata or undefined if not in a git repository
+ * Extracts git metadata for a single source file.
+ *
+ * Resolves the latest commit hash, commit date, and a GitHub permalink
+ * (when the remote is a GitHub URL) by inspecting `git log` output.
+ *
+ * @param filePath - Absolute path to the file.
+ * @returns Git metadata, or `undefined` if the file is not inside a git repository.
  */
 export declare const extractGitMetadata: (filePath: string) => Promise<GitMetadata | undefined>;

package/dist/types/utils/git/status.d.ts

@@ -1,7 +1,13 @@
 /**
- * Get git status information for debugging
- * @param cwd - Working directory
- * @returns Git status information
+ * Retrieves a summary of the current git working-tree status.
+ *
+ * Returns the current branch name, abbreviated HEAD commit, and counts of
+ * staged / unstaged changes. Useful for informational output in CLI commands.
+ *
+ * @param cwd - Working directory for git operations. Defaults to `process.cwd()`.
+ * @returns An object with branch, commit, and file-change counts.
+ * @throws {Error} If the working directory is not inside a git repository or
+ *   the git client cannot be initialised.
  */
 export declare const getGitStatus: (cwd?: string) => Promise<{
     branch: string;

package/dist/types/utils/git/types.d.ts

@@ -1,33 +1,39 @@
 /**
- * Git metadata extracted from repository
+ * Git metadata extracted from the repository for a single source file.
+ *
+ * Attached to vector-store documents as part of `metadata.attributes`.
  */
 export type GitMetadata = Partial<{
+    /** Remote origin URL of the git repository. */
     git_remote_url: string;
+    /** Short SHA of the most recent commit that touched the file. */
     git_commit_hash: string;
+    /** ISO-8601 date string of the most recent commit that touched the file. */
     git_commit_date: string;
+    /** GitHub permalink to the file on the default branch. */
     git_link: string;
 }>;
 /**
- * Git diff options for filtering changed files
+ * Configuration for retrieving changed files via `git diff`.
  */
 export interface GitDiffOptions {
-    /** Enable diff-based file filtering */
+    /** When `true`, enable diff-based file filtering. */
     diff: boolean;
-    /** Git reference to compare against (default: HEAD~1) */
+    /** Git reference to compare against (e.g. `'HEAD~1'`, `'origin/main'`). Defaults to `'HEAD~1'`. */
     baseRef?: string;
-    /** Working directory for git operations */
+    /** Working directory for git operations. Defaults to `process.cwd()`. */
     cwd?: string;
 }
 /**
- * File change status
+ * Possible change statuses reported by git.
  */
 export type FileChangeStatus = 'new' | 'modified' | 'removed';
 /**
- * Changed file information
+ * Describes a single file that has changed according to git.
  */
 export interface ChangedFile {
-    /** Absolute file path */
+    /** Absolute file-system path to the changed file. */
     filepath: string;
-    /** Change status: new, modified, or removed */
+    /** How the file was changed: added, modified, or deleted. */
     status: FileChangeStatus;
 }

package/dist/types/utils/markdown/parser.d.ts

@@ -1,21 +1,34 @@
 import type { SourceFile } from '../types.js';
 import type { MarkdownDocument } from './types.js';
 /**
- * Check if a file is a markdown or MDX file
- * @param filePath - File path to check
- * @returns True if file has .md or .mdx extension
+ * Checks whether a file path has a Markdown (`.md`) or MDX (`.mdx`) extension.
+ *
+ * @param filePath - Absolute or relative file path.
+ * @returns `true` when the extension is `.md` or `.mdx`.
  */
 export declare const isMarkdownFile: (filePath: string) => boolean;
 /**
- * Parse markdown or MDX content into document chunks
- * @param content - Markdown or MDX content string
- * @param source - Source file path
- * @returns Array of markdown documents
+ * Parses Markdown or MDX content into chunked vector-store documents.
+ *
+ * Extracts YAML frontmatter via `gray-matter`, splits the body using
+ * {@link RecursiveCharacterTextSplitter}, and returns one
+ * {@link MarkdownDocument} per valid chunk.
+ *
+ * @template T - Additional frontmatter attributes.
+ * @param content - Raw Markdown / MDX string.
+ * @param source - Relative source file path used as the document key.
+ * @returns Array of chunked Markdown documents.
  */
 export declare const parseMarkdown: <T extends Record<string, unknown> = Record<string, unknown>>(content: string, source: string) => Promise<MarkdownDocument<T>[]>;
 /**
- * Parse a markdown or MDX file into document chunks
- * @param file - Source file object
- * @returns Array of markdown documents with root path metadata
+ * Reads a Markdown or MDX file from disk and parses it into chunked documents.
+ *
+ * Delegates to {@link parseMarkdown} after reading the file content, then
+ * enriches each resulting document with the `rootPath` from the source file.
+ *
+ * @template T - Additional frontmatter attributes.
+ * @param file - Source file descriptor with path and optional project root.
+ * @returns Array of Markdown documents with root-path metadata.
+ * @throws {AssertionError} If the file does not have a `.md` or `.mdx` extension.
  */
 export declare const parseMarkdownFile: <T extends Record<string, unknown> = Record<string, unknown>>(file: SourceFile) => Promise<MarkdownDocument<T>[]>;

package/dist/types/utils/markdown/types.d.ts

@@ -1,11 +1,22 @@
 import type { VectorStoreDocument, VectorStoreDocumentMetadata } from '@equinor/fusion-framework-module-ai/lib';
 /**
- * Markdown document metadata
+ * Metadata shape for documents generated from Markdown / MDX files.
+ *
+ * Extends the base vector-store metadata with a `'markdown'` type discriminator
+ * and any frontmatter key-value pairs (prefixed with `md_`).
+ *
+ * @template T - Additional frontmatter attributes.
  */
 export type MarkdownMetadata<T extends Record<string, unknown> = Record<string, unknown>> = VectorStoreDocumentMetadata<T & {
+    /** Discriminator identifying the document as extracted from Markdown. */
     type: 'markdown';
 }>;
 /**
- * Markdown document
+ * A vector-store document originating from a Markdown or MDX file.
+ *
+ * Contains a text chunk of the markdown content together with
+ * {@link MarkdownMetadata}.
+ *
+ * @template T - Additional frontmatter attributes.
  */
 export type MarkdownDocument<T extends Record<string, unknown> = Record<string, unknown>> = VectorStoreDocument<MarkdownMetadata<T>>;

package/dist/types/utils/package-resolver.d.ts

@@ -1,14 +1,17 @@
 import { type PackageJson } from 'read-package-up';
 /**
- * Resolves which package a file path belongs to.
- * First checks the cache map, then uses read-package-up if no match found.
+ * Resolves the nearest `package.json` for a given file path.
  *
- * @param filePath - Absolute or relative file path (e.g., '/path/to/packages/cli/src/index.ts')
- * @returns Package.json if found, undefined otherwise
+ * Uses an in-memory cache keyed by the package’s directory to avoid
+ * redundant file-system lookups when many files share the same package.
+ *
+ * @param filePath - Absolute path to a source file.
+ * @returns The parsed `PackageJson` if found, or `undefined`.
  *
  * @example
  * ```ts
- * const packageJson = await resolvePackage('/path/to/packages/cli/src/index.ts');
+ * const pkg = await resolvePackage('/repo/packages/cli/src/index.ts');
+ * console.log(pkg?.name); // '@equinor/fusion-framework-cli'
  * ```
  */
 export declare function resolvePackage(filePath: string): Promise<PackageJson | undefined>;

package/dist/types/utils/ts-doc/constants.d.ts

@@ -1,5 +1,8 @@
 import { SyntaxKind } from 'ts-morph';
 /**
- * Supported TSDoc node kinds for top-level processing
+ * Top-level TypeScript syntax kinds that the TSDoc extractor inspects.
+ *
+ * Only nodes matching one of these kinds are considered for document
+ * extraction; all other descendants are skipped.
  */
 export declare const nodeKinds: SyntaxKind[];

package/dist/types/utils/ts-doc/extractors.d.ts

@@ -1,28 +1,42 @@
 import { type SourceFile as ProjectSourceFile, Node, type ClassDeclaration } from 'ts-morph';
 import type { TypescriptDocument, ParseTsDocOptions } from './types.js';
 /**
- * Extracts a TSDoc document from a class node, including TSDoc, constructor, and public member signatures.
- * @param classNode - The ClassDeclaration node to process.
- * @param sourceFile - The source file containing the node.
- * @param options - Optional parsing configuration.
- * @returns A TypeScript document with TSDoc and class interface, or null if no TSDoc is found.
+ * Extracts a vector-store document from a TypeScript class declaration.
+ *
+ * Collects the class-level TSDoc comment, constructor signature (if documented),
+ * and all public members with TSDoc into a single document whose `pageContent`
+ * mirrors a minimal class interface.
+ *
+ * @param classNode - The `ts-morph` {@link ClassDeclaration} node to inspect.
+ * @param sourceFile - The project source file that contains the class.
+ * @param _options - Optional parsing configuration.
+ * @returns A {@link TypescriptDocument}, or `null` when the class has no TSDoc.
  */
 export declare const extractDocumentFromClassNode: (classNode: ClassDeclaration, sourceFile: ProjectSourceFile, _options?: ParseTsDocOptions) => TypescriptDocument | null;
 /**
- * Extracts a TSDoc document from a single node.
- * @param node - The TypeScript node to process.
- * @param sourceFile - The source file containing the node.
+ * Extracts a vector-store document from a single TypeScript AST node.
+ *
+ * Handles function declarations, variable statements (arrow / function
+ * expressions), interfaces, type aliases, enums, and classes. Delegates
+ * to {@link extractDocumentFromClassNode} for class declarations.
+ *
+ * @param node - The `ts-morph` AST node to inspect.
+ * @param sourceFile - The project source file that contains the node.
  * @param options - Optional parsing configuration.
- * @param nodeOptions - Optional node-specific configuration (e.g., skipKindCheck for VariableStatement).
- * @returns A TypeScript document with TSDoc metadata, or null if no TSDoc is found.
+ * @param nodeOptions - Optional flags (e.g. `skipKindCheck`) to override default
+ *   kind filtering.
+ * @returns A {@link TypescriptDocument}, or `null` when the node has no TSDoc or
+ *   is not a supported kind.
  */
 export declare const extractDocumentFromNode: (node: Node, sourceFile: ProjectSourceFile, options?: ParseTsDocOptions, nodeOptions?: {
     skipKindCheck?: boolean;
 }) => TypescriptDocument | null;
 /**
- * Processes a TypeScript source file to extract TSDoc documents.
- * @param sourceFile - The source file to process.
+ * Walks a TypeScript source file and extracts a {@link TypescriptDocument}
+ * for every top-level declaration that carries a TSDoc comment.
+ *
+ * @param sourceFile - The `ts-morph` source file to traverse.
  * @param options - Optional parsing configuration.
- * @returns An array of TypeScript documents with TSDoc metadata.
+ * @returns Array of extracted documents (one per documented declaration).
  */
 export declare const processSourceFile: (sourceFile: ProjectSourceFile, options?: ParseTsDocOptions) => TypescriptDocument[];

package/dist/types/utils/ts-doc/parser.d.ts

@@ -1,23 +1,32 @@
 import type { SourceFile } from '../types.js';
 import type { TypescriptDocument, ParseTsDocOptions } from './types.js';
 /**
- * Checks if a file is a TypeScript or TSX file based on its extension.
- * @param filePath - The path to the file.
- * @returns True if the file ends with .ts or .tsx, false otherwise.
+ * Checks whether a file path has a TypeScript (`.ts`) or TSX (`.tsx`) extension.
+ *
+ * @param filePath - Absolute or relative file path.
+ * @returns `true` if the file extension is `.ts` or `.tsx`.
  */
 export declare const isTypescriptFile: (filePath: string) => boolean;
 /**
- * Parses TSDoc from a string of TypeScript code.
- * @param content - The TypeScript code content.
+ * Parses TSDoc comments from an in-memory TypeScript code string.
+ *
+ * Creates a temporary `ts-morph` project, analyses the source, and returns
+ * one {@link TypescriptDocument} per documented top-level declaration.
+ *
+ * @param content - TypeScript source code to parse.
  * @param options - Optional parsing configuration.
- * @returns An array of TypeScript documents with TSDoc metadata.
+ * @returns Array of extracted TypeScript documents with TSDoc metadata.
  */
 export declare const parseTsDocSync: (content: string, options?: ParseTsDocOptions) => TypescriptDocument[];
 /**
- * Parses TSDoc from a TypeScript file by path.
- * @param file - The source file object.
+ * Parses TSDoc comments from a TypeScript file on disk.
+ *
+ * Reads the file synchronously, creates a `ts-morph` project, and returns
+ * one {@link TypescriptDocument} per documented top-level declaration.
+ *
+ * @param file - Source file descriptor with path and optional project root.
  * @param options - Optional parsing configuration.
- * @returns An array of TypeScript documents with TSDoc metadata.
- * @throws If the file is not a TypeScript file.
+ * @returns Array of extracted TypeScript documents.
+ * @throws {AssertionError} If the file does not have a `.ts` or `.tsx` extension.
  */
 export declare const parseTsDocFromFileSync: (file: SourceFile, options?: ParseTsDocOptions) => TypescriptDocument[];