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

package/src/{command.ts → embeddings-command.ts}

@@ -1,16 +1,16 @@
-import { createCommand, createOption } from 'commander';
+import { type Command, createCommand, createOption } from 'commander';
 
 import { loadFusionAIConfig, setupFramework } from '@equinor/fusion-framework-cli-plugin-ai-base';
 import { withOptions as withAiOptions } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
 
 import { embed } from './bin/embed.js';
-import { CommandOptionsSchema, type CommandOptions } from './command.options.js';
+import { CommandOptionsSchema, type CommandOptions } from './embeddings-command.options.js';
 import type { FusionAIConfigWithIndex } from './config.js';
 
 /**
- * CLI command: `ai embeddings`
+ * CLI command: `ai index add`
  *
- * Document embedding utilities for Large Language Model processing.
+ * Add documents to the AI search index via embedding generation.
  *
  * Features:
  * - Markdown/MDX document chunking with frontmatter extraction
@@ -21,7 +21,7 @@ import type { FusionAIConfigWithIndex } from './config.js';
  * - Configurable file patterns via fusion-ai.config.ts
  *
  * Usage:
- *   $ ffc ai embeddings [options] [glob-patterns...]
+ *   $ ffc ai index add [options] [glob-patterns...]
  *
  * Arguments:
  *   glob-patterns          Glob patterns to match files (optional when using --diff)
@@ -34,24 +34,15 @@ import type { FusionAIConfigWithIndex } from './config.js';
  *   --base-ref <ref>       Git reference to compare against (default: HEAD~1)
  *   --clean                Delete all existing documents from the vector store before processing
  *
- * AI Options (required):
- *   --openai-api-key <key>              Azure OpenAI API key (or AZURE_OPENAI_API_KEY env var)
- *   --openai-api-version <version>      Azure OpenAI API version (default: 2024-02-15-preview)
- *   --openai-instance <name>            Azure OpenAI instance name (or AZURE_OPENAI_INSTANCE_NAME env var)
- *   --openai-embedding-deployment <name> Azure OpenAI embedding deployment name (or AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME env var)
- *   --azure-search-endpoint <url>       Azure Search endpoint URL (or AZURE_SEARCH_ENDPOINT env var)
- *   --azure-search-api-key <key>        Azure Search API key (or AZURE_SEARCH_API_KEY env var)
- *   --azure-search-index-name <name>    Azure Search index name (or AZURE_SEARCH_INDEX_NAME env var)
- *
  * Examples:
- *   $ ffc ai embeddings --dry-run ./src
- *   $ ffc ai embeddings "*.ts" "*.md" "*.mdx"
- *   $ ffc ai embeddings --diff
- *   $ ffc ai embeddings --diff --base-ref origin/main
- *   $ ffc ai embeddings --clean "*.ts"
+ *   $ ffc ai index add --dry-run ./src
+ *   $ ffc ai index add "*.ts" "*.md" "*.mdx"
+ *   $ ffc ai index add --diff
+ *   $ ffc ai index add --diff --base-ref origin/main
+ *   $ ffc ai index add --clean "*.ts"
  */
-const _command = createCommand('embeddings')
-  .description('Document embedding utilities for Large Language Model processing')
+const _command = createCommand('add')
+  .description('Add documents to the AI search index via embedding generation')
   .addOption(
     createOption('--dry-run', 'Show what would be processed without actually doing it').default(
       false,
@@ -67,16 +58,35 @@ const _command = createCommand('embeddings')
     ).default(false),
   )
   .argument('[glob-patterns...]', 'Glob patterns to match files (optional when using --diff)')
-  .action(async (patterns: string[], commandOptions: CommandOptions) => {
-    const options = await CommandOptionsSchema.parseAsync(commandOptions);
+  .action(async function (this: Command, patterns: string[], commandOptions: CommandOptions) {
+    // Load configuration before validation so config values can fill gaps
+    const preOptions = commandOptions as Record<string, unknown>;
+    const config = await loadFusionAIConfig<FusionAIConfigWithIndex>(
+      (preOptions.config as string) ?? 'fusion-ai.config',
+      { baseDir: process.cwd() },
+    );
+    const indexConfig = config.index ?? {};
 
-    // Load configuration
-    const config = await loadFusionAIConfig<FusionAIConfigWithIndex>(options.config, {
-      baseDir: process.cwd(),
-    });
+    // Config file values override env-var defaults but not explicit CLI flags.
+    // Commander merges env vars before the action runs, so we use
+    // getOptionValueSource to distinguish "user passed --flag" from "came from env".
+    const parentCommand = this.parent ?? this;
+    if (indexConfig.name) {
+      const source = parentCommand.getOptionValueSource('azureSearchIndexName');
+      if (source !== 'cli') {
+        preOptions.azureSearchIndexName = indexConfig.name;
+      }
+    }
+    if (indexConfig.model) {
+      const source = parentCommand.getOptionValueSource('openaiEmbeddingDeployment');
+      if (source !== 'cli') {
+        preOptions.openaiEmbeddingDeployment = indexConfig.model;
+      }
+    }
+
+    const options = await CommandOptionsSchema.parseAsync(preOptions);
 
     // CLI args take precedence over config patterns
-    const indexConfig = config.index ?? {};
     const allowedFilePatterns = indexConfig.patterns ?? ['**/*.ts', '**/*.md', '**/*.mdx'];
     const filePatterns = patterns.length ? patterns : allowedFilePatterns;
 
@@ -92,6 +102,14 @@ const _command = createCommand('embeddings')
     });
   });
 
+/**
+ * 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 const command = withAiOptions(_command, {
   includeEmbedding: true,
   includeSearch: true,

package/src/index.ts

@@ -1,15 +1,49 @@
 import type { Command } from 'commander';
+import { createCommand } from 'commander';
 import { registerAiPlugin as registerAiPluginBase } from '@equinor/fusion-framework-cli-plugin-ai-base';
-import { command as embeddingsCommand } from './command.js';
+import { command as addCommand } from './embeddings-command.js';
+import { deleteCommand as removeCommand } from './delete-command.js';
+import { searchCommand } from './search-command.js';
 
 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
+ * Parent command for the `ai index` group.
+ *
+ * Owns three subcommands:
+ * - `add`    — index documents into the Azure AI Search vector store.
+ * - `remove` — remove documents from the vector store.
+ * - `search` — query the vector store for indexed documents.
+ */
+const indexCommand = createCommand('index')
+  .description('Manage the AI search index (add, search, remove)')
+  .addCommand(addCommand)
+  .addCommand(removeCommand)
+  .addCommand(searchCommand);
+
+/**
+ * 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 function registerAiPlugin(program: Command): void {
-  registerAiPluginBase(program, embeddingsCommand);
+  registerAiPluginBase(program, indexCommand);
 }
 
 export default registerAiPlugin;

package/src/search-command.ts

@@ -0,0 +1,259 @@
+import { createCommand, createOption } from 'commander';
+import type { Document } from '@langchain/core/documents';
+import { inspect } from 'node:util';
+
+import { setupFramework } from '@equinor/fusion-framework-cli-plugin-ai-base';
+import {
+  withOptions as withAiOptions,
+  type AiOptions,
+} from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
+import type { RetrieverOptions } from '@equinor/fusion-framework-module-ai/lib';
+
+/**
+ * Resolved option values for the `ai index search` CLI command.
+ *
+ * Extends {@link AiOptions} with search-specific flags such as result limits,
+ * output format toggles, filter expressions, and search-type selection.
+ */
+type CommandOptions = AiOptions & {
+  /** Maximum number of search results to return (default `10`). */
+  limit: number;
+  /** When `true`, print diagnostic details such as index name and metadata. */
+  verbose: boolean;
+  /** Optional OData filter expression applied to document metadata before ranking. */
+  filter?: string;
+  /** When `true`, emit results as JSON objects instead of human-readable text. */
+  json: boolean;
+  /** When `true`, output the raw Azure Search metadata without flattening attributes. */
+  raw: boolean;
+  /** Search algorithm: `'similarity'` for cosine similarity or `'mmr'` for Maximum Marginal Relevance diversity re-ranking. */
+  searchType: 'mmr' | 'similarity';
+};
+
+/**
+ * Flatten Azure Cognitive Search metadata attributes into a plain object.
+ *
+ * Azure Search stores custom metadata as an array of `{ key, value }` pairs
+ * under an `attributes` property. This helper converts that array into a flat
+ * key-value map so consumers can access attributes directly
+ * (e.g. `metadata.source` instead of iterating the attributes array).
+ *
+ * JSON-encoded attribute values are transparently parsed; plain strings are
+ * kept as-is.
+ *
+ * @param metadata - Raw metadata record from an Azure Search document.
+ * @returns A shallow copy of `metadata` with the `attributes` array replaced by
+ *   its flattened key-value entries.
+ */
+const normalizeMetadata = (metadata: Record<string, unknown>): Record<string, unknown> => {
+  const normalized = { ...metadata };
+
+  if (Array.isArray(normalized.attributes)) {
+    const attributesObj: Record<string, unknown> = {};
+    for (const attr of normalized.attributes) {
+      if (
+        typeof attr === 'object' &&
+        attr !== null &&
+        'key' in attr &&
+        'value' in attr &&
+        typeof attr.key === 'string'
+      ) {
+        try {
+          attributesObj[attr.key] = JSON.parse(attr.value as string);
+        } catch {
+          attributesObj[attr.key] = attr.value;
+        }
+      }
+    }
+    Object.assign(normalized, attributesObj);
+    delete normalized.attributes;
+  }
+
+  return normalized;
+};
+
+/**
+ * Commander subcommand: **`ai index search`**
+ *
+ * Performs semantic vector-store search against an Azure Cognitive Search index
+ * and displays the matching documents. Use this command to validate that
+ * embeddings are indexed correctly, to explore the retrieval corpus, or to
+ * test OData filter expressions.
+ *
+ * Supports two search algorithms:
+ * - **`similarity`** (default) — pure cosine-similarity ranking.
+ * - **`mmr`** — Maximum Marginal Relevance, which re-ranks results to increase
+ *   diversity while staying relevant.
+ *
+ * Results can be output as human-readable text (default) or as JSON objects
+ * (`--json`). The `--raw` flag preserves Azure Search's native metadata
+ * structure; without it, metadata attributes are flattened by
+ * {@link normalizeMetadata}.
+ *
+ * @example
+ * ```sh
+ * # Basic similarity search
+ * ffc ai index search "how to configure modules"
+ *
+ * # Limit results and use MMR for diversity
+ * ffc ai index search "authentication" --limit 5 --search-type mmr
+ *
+ * # Filter by package name
+ * ffc ai index search "hooks" --filter "metadata/attributes/any(a: a/key eq 'pkg_name' and a/value eq '@equinor/fusion-framework-react')" --json
+ *
+ * # Verbose output with raw Azure metadata
+ * ffc ai index search "API reference" --verbose --raw
+ * ```
+ */
+const _command = createCommand('search')
+  .description('Search the vector store to validate embeddings and retrieve relevant documents')
+  .addOption(
+    createOption('--limit <number>', 'Maximum number of results to return')
+      .default(10)
+      .argParser(parseInt),
+  )
+  .addOption(
+    createOption('--search-type <type>', 'Search type: mmr or similarity')
+      .choices(['mmr', 'similarity'])
+      .default('similarity'),
+  )
+  .addOption(
+    createOption('--filter <expression>', 'OData filter expression for metadata filtering'),
+  )
+  .addOption(createOption('--json', 'Output results as JSON').default(false))
+  .addOption(createOption('--raw', 'Output raw metadata without normalization').default(false))
+  .addOption(createOption('--verbose', 'Enable verbose output').default(false))
+  .argument('<query>', 'Search query string')
+  .action(async (query: string, options: CommandOptions) => {
+    if (options.verbose) {
+      console.log('🔍 Initializing framework...');
+    }
+
+    const framework = await setupFramework(options);
+
+    if (!options.azureSearchIndexName) {
+      throw new Error('Azure Search index name is required');
+    }
+
+    if (options.verbose) {
+      console.log('✅ Framework initialized successfully');
+      console.log(`📇 Index: ${options.azureSearchIndexName}`);
+      console.log(`🔎 Searching for: "${query}"`);
+      console.log(`📊 Limit: ${options.limit}`);
+      console.log(`🔍 Search type: ${options.searchType}`);
+      if (options.filter) {
+        console.log(`🔧 Filter: ${options.filter}`);
+      }
+      console.log('');
+    }
+
+    const vectorStoreService = framework.ai.getService('search', options.azureSearchIndexName);
+
+    try {
+      const filter = options.filter ? { filterExpression: options.filter } : undefined;
+
+      const retrieverOptions: RetrieverOptions =
+        options.searchType === 'mmr'
+          ? {
+              k: options.limit,
+              searchType: 'mmr',
+              ...(filter && { filter: filter as Record<string, unknown> }),
+            }
+          : {
+              k: options.limit,
+              searchType: 'similarity',
+              ...(filter && { filter: filter as Record<string, unknown> }),
+            };
+
+      const retriever = vectorStoreService.asRetriever(retrieverOptions);
+      const results = await retriever.invoke(query);
+
+      if (!results || !Array.isArray(results)) {
+        throw new Error(
+          `Invalid search results: expected array but got ${results === null ? 'null' : typeof results}`,
+        );
+      }
+
+      if (options.json) {
+        for (const doc of results) {
+          if (options.raw) {
+            console.log(inspect(doc, { depth: null, colors: true }));
+          } else {
+            const metadata = normalizeMetadata(doc.metadata as Record<string, unknown>);
+            console.log({
+              content: doc.pageContent,
+              metadata,
+              score: (metadata as { score?: number })?.score,
+            });
+          }
+        }
+      } else {
+        if (results.length === 0) {
+          console.log('❌ No results found');
+          return;
+        }
+
+        console.log(`✅ Found ${results.length} result${results.length !== 1 ? 's' : ''}:\n`);
+
+        results.forEach((doc: Document, index: number) => {
+          const processedMetadata = options.raw
+            ? (doc.metadata as Record<string, unknown>)
+            : normalizeMetadata(doc.metadata as Record<string, unknown>);
+          const metadata = processedMetadata as {
+            source?: string;
+            score?: number;
+            [key: string]: unknown;
+          };
+          const score = metadata.score;
+          const source = metadata.source || 'Unknown source';
+
+          console.log(`${'─'.repeat(80)}`);
+          console.log(
+            `Result ${index + 1}${score !== undefined ? ` (Score: ${score.toFixed(4)})` : ''}`,
+          );
+          console.log(`Source: ${source}`);
+
+          if (options.verbose) {
+            const { source: _, score: __, ...otherMetadata } = metadata;
+            if (Object.keys(otherMetadata).length > 0) {
+              console.log(`Metadata:`, JSON.stringify(otherMetadata, null, 2));
+            }
+          }
+          console.log('');
+
+          const content = doc.pageContent;
+          const maxLength = 500;
+          if (content.length > maxLength) {
+            console.log(`${content.substring(0, maxLength)}...`);
+            console.log(`\n[Content truncated - ${content.length} characters total]`);
+          } else {
+            console.log(content);
+          }
+          console.log('');
+        });
+
+        console.log(`${'─'.repeat(80)}`);
+      }
+    } catch (error) {
+      console.error(
+        `❌ Search failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      if (options.verbose && error instanceof Error && error.stack) {
+        console.error(error.stack);
+      }
+      process.exit(1);
+    }
+  });
+
+/**
+ * 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 const searchCommand = withAiOptions(_command, {
+  includeEmbedding: true,
+  includeSearch: true,
+});
+
+export default searchCommand;

package/src/utils/generate-chunk-id.ts

@@ -1,9 +1,21 @@
 /**
- * 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 const generateChunkId = (filePath: string, chunkIndex?: number): string => {
   // Convert file path to base64 and remove non-alphanumeric characters

package/src/utils/git/file-changes.ts

@@ -3,9 +3,15 @@ import type { ChangedFile, FileChangeStatus, GitDiffOptions } from './types.js';
 import { resolveProjectRoot, getGit } from './git-client.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 const getChangedFiles = async (options: GitDiffOptions): Promise<ChangedFile[]> => {
   const { diff, baseRef = 'HEAD~1', cwd = process.cwd() } = options;
@@ -78,10 +84,15 @@ export const getChangedFiles = async (options: GitDiffOptions): Promise<ChangedF
 };
 
 /**
- * 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 const getFileStatus = async (filePath: string): Promise<ChangedFile[]> => {
   const { git, gitRepoPath } = getGit(filePath) ?? {};
@@ -199,10 +210,14 @@ export const getFileStatus = async (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 const isFileChanged = (filePath: string, changedFiles: ChangedFile[]): boolean => {
   if (changedFiles.length === 0) {

package/src/utils/git/git-client.ts

@@ -6,9 +6,13 @@ import { existsSync } from 'node:fs';
 const gitCache = new Map<string, SimpleGit>();
 
 /**
- * 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 const resolveProjectRoot = (filePath: string): string | undefined => {
   // if we are in the root of the git repository, return the root
@@ -21,10 +25,15 @@ export 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 const getGit = (
   filePath: string,

package/src/utils/git/metadata.ts

@@ -24,9 +24,13 @@ const generateGithubPermalink = (
 };
 
 /**
- * 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 const extractGitMetadata = async (filePath: string): Promise<GitMetadata | undefined> => {
   const { git, gitRepoPath: gitRepoRoot } = getGit(filePath) ?? {};

package/src/utils/git/status.ts

@@ -1,9 +1,15 @@
 import { resolveProjectRoot, getGit } from './git-client.js';
 
 /**
- * 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 const getGitStatus = async (
   cwd: string = process.cwd(),

package/src/utils/git/types.ts

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