@equinor/fusion-framework-cli-plugin-ai-index 3.0.6 → 3.0.8

package/src/bin/execute-pipeline.ts

@@ -4,6 +4,9 @@ import type { Observable } from 'rxjs';
 
 /**
  * Executes the pipeline and tracks results.
+ *
+ * @param deleteRemovedFiles$ - Stream of file-deletion results, processed before additions.
+ * @param updateVectorStore$ - Stream of document-addition results.
  * @internal
  */
 export function executePipeline(
@@ -22,10 +25,12 @@ export function executePipeline(
     next: (result) => {
       // Track deleted files by relative path
       if (result.status === 'deleted') {
+        // Reduce each deleted file entry down to its relative path for reporting.
         indexingResults.deleted.push(...result.files.map((file) => file.relativePath));
       }
       // Track added documents with source and ID (one file can produce multiple IDs)
       else if (result.status === 'added') {
+        // Reduce each added document down to its source path and id for reporting.
         indexingResults.added.push(
           ...result.documents.map((document) => ({
             source: document.metadata.source,

package/src/bin/get-diff.ts

@@ -1,9 +1,12 @@
 import type { ChangedFile } from '../utils/git/index.js';
 import { getChangedFiles, getGitStatus } from '../utils/git/index.js';
-import type { CommandOptions } from '../embeddings-command.options.js';
+import type { CommandOptions } from '../command-options-schema.js';
 
 /**
  * Handles diff-based processing to get changed files from git.
+ *
+ * @param options - Command options controlling diff mode and base reference.
+ * @returns The list of changed files matching the configured patterns.
  * @internal
  */
 export async function getDiff(options: CommandOptions): Promise<ChangedFile[]> {
@@ -19,13 +22,16 @@ export async function getDiff(options: CommandOptions): Promise<ChangedFile[]> {
       baseRef: options.baseRef,
     });
 
+    // Bail out early when no changed files match the configured patterns.
     if (changedFiles.length === 0) {
       console.log('✅ No changed files match the provided patterns. Nothing to process.');
       process.exit(0);
     }
 
     console.log(`📝 Found ${changedFiles.length} changed files matching patterns`);
+    // Log each changed file's status when --debug is set.
     if (options.debug) {
+      // Print status/filepath pairs one at a time for readable debug output.
       for (const file of changedFiles) {
         console.debug(`[debug] ${file.status}: ${file.filepath}`);
       }

package/src/bin/types.ts

@@ -1,6 +1,6 @@
 import type { VectorStoreDocument } from '@equinor/fusion-framework-module-ai/lib';
 import type { ChangedFile } from '../utils/git/index.js';
-import type { CommandOptions } from '../embeddings-command.options.js';
+import type { CommandOptions } from '../command-options-schema.js';
 import type { FrameworkInstance } from '@equinor/fusion-framework-cli-plugin-ai-base';
 import type { FusionAIConfigWithIndex } from '../config.js';
 

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

@@ -4,7 +4,7 @@ import { loadFusionAIConfig, setupFramework } from '@equinor/fusion-framework-cl
 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 './embeddings-command.options.js';
+import { CommandOptionsSchema, type CommandOptions } from './command-options-schema.js';
 import type { FusionAIConfigWithIndex } from './config.js';
 
 /**
@@ -68,9 +68,11 @@ const _command = createCommand('add')
     );
     const indexConfig = config.index ?? {};
 
+    // Fall back to the configured index name only if the user didn't pass one explicitly
     if (indexConfig.name && !opts.indexName?.trim()) {
       thisCommand.setOptionValue('indexName', indexConfig.name);
     }
+    // Fall back to the configured embed model only if the user didn't pass one explicitly
     if (indexConfig.model && !opts.embedModel?.trim()) {
       thisCommand.setOptionValue('embedModel', indexConfig.model);
     }

package/src/config.ts

@@ -1,6 +1,6 @@
 import type { VectorStoreDocument } from '@equinor/fusion-framework-module-ai/lib';
 import type { FusionAIConfig } from '@equinor/fusion-framework-cli-plugin-ai-base';
-import type { IndexSchemaConfig } from './schema.js';
+import type { IndexSchemaConfig } from './define-index-schema.js';
 
 /**
  * Index-specific configuration for Fusion AI document indexing operations.

package/src/{create-command.ts → create-index-command.ts}

@@ -8,7 +8,7 @@ import {
 
 import type { FusionAIConfigWithIndex } from './config.js';
 import { zodToAzureFields } from './utils/zod-to-azure-fields.js';
-import { resolveEmbeddingDimensions } from './utils/embedding-dimensions.js';
+import { resolveEmbeddingDimensions } from './utils/resolve-embedding-dimensions.js';
 
 /**
  * CLI command: `ai index create`
@@ -47,6 +47,7 @@ const _command = createCommand('create')
     });
 
     const indexConfig = config.index;
+    // Config must define a schema via defineIndexSchema() before an index can be created
     if (!indexConfig?.schema) {
       console.error(
         '❌ No schema defined in config. Add a `schema` property to `index` using defineIndexSchema().',
@@ -57,6 +58,7 @@ const _command = createCommand('create')
     // Resolve index name from config
     const indexName = indexConfig.name;
 
+    // Index name is required to know where to create/update the schema
     if (!indexName) {
       console.error('❌ Index name is required. Set `name` in the index config.');
       process.exit(1);
@@ -67,10 +69,14 @@ const _command = createCommand('create')
 
     // Guard against schema fields that collide with reserved base-schema names
     const reservedFieldNames = ['id', 'content', 'content_vector', 'metadata'] as const;
-    const conflictingSchemaFields = schemaFields
-      .map((field) => field.name)
-      .filter((name) => reservedFieldNames.includes(name as (typeof reservedFieldNames)[number]));
-
+    // Extract field names to check them against the reserved list
+    const schemaFieldNames = schemaFields.map((field) => field.name);
+    // Isolate the names that collide with reserved base-schema fields
+    const conflictingSchemaFields = schemaFieldNames.filter((name) =>
+      reservedFieldNames.includes(name as (typeof reservedFieldNames)[number]),
+    );
+
+    // Fail fast so the user can rename the offending schema fields before creating the index
     if (conflictingSchemaFields.length > 0) {
       const conflicts = [...new Set(conflictingSchemaFields)].sort().join(', ');
       console.error(
@@ -156,6 +162,7 @@ const _command = createCommand('create')
       },
     ];
 
+    // Combine the base fields with any additional caller-supplied fields
     const fullSchema = {
       name: indexName,
       fields: [...baseFields, ...schemaFields],
@@ -170,6 +177,7 @@ const _command = createCommand('create')
       },
     };
 
+    // Dry-run mode previews the schema without contacting the AI service
     if (commandOptions.dryRun) {
       console.log('📋 Index schema preview (dry-run):');
       console.log(JSON.stringify(fullSchema, null, 2));
@@ -186,6 +194,7 @@ const _command = createCommand('create')
     const scopes = service.scopes ?? service.defaultScopes ?? [];
     const token = await framework.auth.acquireAccessToken({ request: { scopes } });
 
+    // Cannot call the AI service without a valid access token
     if (!token) {
       console.error('❌ Failed to acquire access token for the AI service.');
       process.exit(1);
@@ -201,6 +210,7 @@ const _command = createCommand('create')
       body: JSON.stringify(fullSchema),
     });
 
+    // Surface the service error response so the user can diagnose the failure
     if (!response.ok) {
       const body = await response.text();
       console.error(`❌ Index creation failed (${response.status} ${response.statusText})`);

package/src/delete-command.ts

@@ -4,7 +4,7 @@ import { loadFusionAIConfig, setupFramework } from '@equinor/fusion-framework-cl
 import { withOptions as withAiOptions } from '@equinor/fusion-framework-cli-plugin-ai-base/command-options';
 import type { FusionAIConfigWithIndex } from './config.js';
 
-import { DeleteOptionsSchema, type DeleteOptions } from './delete-command.options.js';
+import { DeleteOptionsSchema, type DeleteOptions } from './delete-options-schema.js';
 
 /**
  * Builds an OData filter expression from source paths and/or a raw filter.
@@ -19,8 +19,11 @@ import { DeleteOptionsSchema, type DeleteOptions } from './delete-command.option
  *   sources nor a raw filter were provided.
  */
 function buildFilter(sources: string[], rawFilter?: string): string | undefined {
+  // Source-path filters take precedence over a raw filter to avoid broad deletions
   if (sources.length > 0) {
-    return sources.map((s) => `metadata/source eq '${s}'`).join(' or ');
+    // Build one OData clause per source path before combining them
+    const sourceClauses = sources.map((s) => `metadata/source eq '${s}'`);
+    return sourceClauses.join(' or ');
   }
   return rawFilter;
 }
@@ -79,9 +82,11 @@ const _command = createCommand('remove')
     );
     const indexConfig = config.index ?? {};
 
+    // Fall back to the configured index name only if the user didn't pass one explicitly
     if (indexConfig.name && !opts.indexName?.trim()) {
       thisCommand.setOptionValue('indexName', indexConfig.name);
     }
+    // Fall back to the configured embed model only if the user didn't pass one explicitly
     if (indexConfig.model && !opts.embedModel?.trim()) {
       thisCommand.setOptionValue('embedModel', indexConfig.model);
     }
@@ -90,14 +95,17 @@ const _command = createCommand('remove')
     const options = await DeleteOptionsSchema.parseAsync(commandOptions);
     const filterExpression = buildFilter(sources, options.filter);
 
+    // Refuse to run an unbounded delete when neither sources nor a filter were given
     if (!filterExpression) {
       throw new Error(
         'Nothing to delete. Provide source file paths as arguments or pass a --filter expression.',
       );
     }
 
+    // Show the user exactly what will be targeted before deleting
     if (sources.length > 0) {
       console.log(`\nTargeting ${sources.length} source path(s):\n`);
+      // List each source path so the user can verify the target set
       for (const src of sources.sort()) {
         console.log(`  ${src}`);
       }
@@ -105,6 +113,7 @@ const _command = createCommand('remove')
       console.log(`\nFilter: ${filterExpression}`);
     }
 
+    // Dry-run mode previews the filter without deleting anything
     if (options.dryRun) {
       console.log('\n🔍 Dry run — no documents were deleted.');
       console.log(`  Would apply filter: ${filterExpression}`);

package/src/delete-index-command.ts

@@ -54,6 +54,7 @@ const _command = createCommand('delete')
   ) {
     const indexName = commandOptions.name?.trim();
 
+    // Cannot proceed without knowing which index to delete
     if (!indexName) {
       console.error('❌ Index name is required. Set `name` in the index config or pass --name.');
       process.exit(1);
@@ -73,6 +74,7 @@ const _command = createCommand('delete')
       });
       rl.close();
 
+      // Abort unless the user re-typed the exact index name
       if (answer.trim() !== indexName) {
         console.log('❌ Confirmation did not match. Aborting.');
         process.exit(1);
@@ -85,6 +87,7 @@ const _command = createCommand('delete')
     const scopes = service.scopes ?? service.defaultScopes ?? [];
     const token = await framework.auth.acquireAccessToken({ request: { scopes } });
 
+    // Cannot call the AI service without a valid access token
     if (!token) {
       console.error('❌ Failed to acquire access token for the AI service.');
       process.exit(1);
@@ -104,6 +107,7 @@ const _command = createCommand('delete')
       process.exit(1);
     }
 
+    // Surface the service error response so the user can diagnose the failure
     if (!response.ok) {
       const body = await response.text();
       console.error(`❌ Index deletion failed (${response.status} ${response.statusText})`);

package/src/embed-command.ts

@@ -33,12 +33,9 @@ export const embedCommand = withAiOptions(
       const vector = await embedder.embedQuery(text);
 
       console.log(`Dimensions: ${vector.length}`);
-      console.log(
-        `Vector (first 8): [${vector
-          .slice(0, 8)
-          .map((v) => v.toFixed(6))
-          .join(', ')}, ...]`,
-      );
+      // Format the first 8 vector components for a readable preview
+      const previewValues = vector.slice(0, 8).map((v) => v.toFixed(6));
+      console.log(`Vector (first 8): [${previewValues.join(', ')}, ...]`);
     }),
   { includeEmbedding: true },
 );

package/src/index.ts

@@ -1,15 +1,15 @@
 import type { Command } from 'commander';
 import { createCommand } from 'commander';
 import { registerAiPlugin as registerAiPluginBase } from '@equinor/fusion-framework-cli-plugin-ai-base';
-import { command as addCommand } from './embeddings-command.js';
+import { command as addCommand } from './command.js';
 import { deleteCommand as removeCommand } from './delete-command.js';
 import { searchCommand } from './search-command.js';
 import { embedCommand } from './embed-command.js';
-import { createIndexCommand } from './create-command.js';
+import { createIndexCommand } from './create-index-command.js';
 import { deleteIndexCommand } from './delete-index-command.js';
 
 export { FusionAIConfigWithIndex, IndexConfig } from './config.js';
-export { defineIndexSchema, IndexSchemaConfig } from './schema.js';
+export { defineIndexSchema, IndexSchemaConfig } from './define-index-schema.js';
 
 /**
  * Parent command for the `ai index` group.

package/src/search-command.ts

@@ -49,9 +49,12 @@ type CommandOptions = AiOptions & {
 const normalizeMetadata = (metadata: Record<string, unknown>): Record<string, unknown> => {
   const normalized = { ...metadata };
 
+  // Only Azure Search documents with an attributes array need flattening
   if (Array.isArray(normalized.attributes)) {
     const attributesObj: Record<string, unknown> = {};
+    // Convert each { key, value } pair into a flat map entry
     for (const attr of normalized.attributes) {
+      // Skip malformed attribute entries that don't match the expected shape
       if (
         typeof attr === 'object' &&
         attr !== null &&
@@ -66,6 +69,7 @@ const normalizeMetadata = (metadata: Record<string, unknown>): Record<string, un
         }
       }
     }
+    // Flatten the normalized attribute map back onto the parent object
     Object.assign(normalized, attributesObj);
     delete normalized.attributes;
   }
@@ -134,30 +138,36 @@ const _command = createCommand('search')
     );
     const indexConfig = config.index ?? {};
 
+    // Fall back to the configured index name only if the user didn't pass one explicitly
     if (indexConfig.name && !opts.indexName?.trim()) {
       thisCommand.setOptionValue('indexName', indexConfig.name);
     }
+    // Fall back to the configured embed model only if the user didn't pass one explicitly
     if (indexConfig.model && !opts.embedModel?.trim()) {
       thisCommand.setOptionValue('embedModel', indexConfig.model);
     }
   })
   .action(async (query: string, options: CommandOptions) => {
+    // Surface progress in verbose mode before the (potentially slow) framework setup
     if (options.verbose) {
       console.log('🔍 Initializing framework...');
     }
 
     const framework = await setupFramework(options);
 
+    // Cannot search without knowing which index to query
     if (!options.indexName) {
       throw new Error('Index name is required');
     }
 
+    // Print the resolved search parameters in verbose mode
     if (options.verbose) {
       console.log('✅ Framework initialized successfully');
       console.log(`📇 Index: ${options.indexName}`);
       console.log(`🔎 Searching for: "${query}"`);
       console.log(`📊 Limit: ${options.limit}`);
       console.log(`🔍 Search type: ${options.searchType}`);
+      // Only show the filter line when a filter was actually supplied
       if (options.filter) {
         console.log(`🔧 Filter: ${options.filter}`);
       }
@@ -185,14 +195,18 @@ const _command = createCommand('search')
       const retriever = vectorStoreService.asRetriever(retrieverOptions);
       const results = await retriever.invoke(query);
 
+      // Defensively validate the retriever response shape before iterating it
       if (!results || !Array.isArray(results)) {
         throw new Error(
           `Invalid search results: expected array but got ${results === null ? 'null' : typeof results}`,
         );
       }
 
+      // JSON output mode prints each document as a structured object
       if (options.json) {
+        // Emit one JSON entry per matching document
         for (const doc of results) {
+          // Raw mode preserves Azure Search's native metadata structure
           if (options.raw) {
             console.log(inspect(doc, { depth: null, colors: true }));
           } else {
@@ -205,6 +219,7 @@ const _command = createCommand('search')
           }
         }
       } else {
+        // Nothing further to render when the search returned no matches
         if (results.length === 0) {
           console.log('❌ No results found');
           return;
@@ -212,6 +227,7 @@ const _command = createCommand('search')
 
         console.log(`✅ Found ${results.length} result${results.length !== 1 ? 's' : ''}:\n`);
 
+        // Render each matched document as human-readable text
         results.forEach((doc: Document, index: number) => {
           const processedMetadata = options.raw
             ? (doc.metadata as Record<string, unknown>)
@@ -230,8 +246,10 @@ const _command = createCommand('search')
           );
           console.log(`Source: ${source}`);
 
+          // Only print extra metadata fields in verbose mode
           if (options.verbose) {
             const { source: _, score: __, ...otherMetadata } = metadata;
+            // Skip the empty-object noise when there's no extra metadata to show
             if (Object.keys(otherMetadata).length > 0) {
               console.log(`Metadata:`, JSON.stringify(otherMetadata, null, 2));
             }
@@ -240,6 +258,7 @@ const _command = createCommand('search')
 
           const content = doc.pageContent;
           const maxLength = 500;
+          // Truncate long content so terminal output stays readable
           if (content.length > maxLength) {
             console.log(`${content.substring(0, maxLength)}...`);
             console.log(`\n[Content truncated - ${content.length} characters total]`);
@@ -255,6 +274,7 @@ const _command = createCommand('search')
       console.error(
         `❌ Search failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
       );
+      // Print the stack trace in verbose mode to aid debugging
       if (options.verbose && error instanceof Error && error.stack) {
         console.error(error.stack);
       }

package/src/utils/git/{metadata.ts → extract-git-metadata.ts}

@@ -1,6 +1,6 @@
 import { relative } from 'node:path';
 import type { GitMetadata } from './types.js';
-import { getGit } from './git-client.js';
+import { getGit } from './get-git.js';
 
 /**
  * Generate a GitHub permalink for a file
@@ -16,6 +16,7 @@ const generateGithubPermalink = (
   slug?: string,
 ): string | undefined => {
   const githubMatch = gitRemoteUrl.match(/github\.com[:/]([^/]+)\/([^/.]+)(?:\.git)?$/);
+  // Only GitHub-hosted remotes can be turned into a permalink URL
   if (githubMatch) {
     const [, owner, repo] = githubMatch;
     return `https://github.com/${owner}/${repo}/blob/${slug ?? 'main'}/${filePath}`;
@@ -34,6 +35,7 @@ const generateGithubPermalink = (
  */
 export const extractGitMetadata = async (filePath: string): Promise<GitMetadata | undefined> => {
   const { git, gitRepoPath: gitRepoRoot } = getGit(filePath) ?? {};
+  // No metadata can be extracted outside of a git repository
   if (!git || !gitRepoRoot) {
     return undefined;
   }

package/src/utils/git/get-changed-files.ts

@@ -0,0 +1,93 @@
+import type { ChangedFile, FileChangeStatus, GitDiffOptions } from './types.js';
+import { resolveProjectRoot } from './resolve-project-root.js';
+import { getGit } from './get-git.js';
+
+/**
+ * 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;
+
+  // Skip git entirely when diff mode wasn't requested
+  if (!diff) {
+    return [];
+  }
+
+  const projectRoot = resolveProjectRoot(cwd);
+  // Diff mode requires a git repository to resolve the project root against
+  if (!projectRoot) {
+    throw new Error('Not in a git repository. Cannot use --diff option.');
+  }
+
+  const { git } = getGit(cwd) ?? {};
+  // Cannot proceed without a working git client
+  if (!git) {
+    throw new Error('Failed to initialize git client');
+  }
+
+  try {
+    // Get changes since baseRef with status (A=added, M=modified, D=deleted)
+    try {
+      const diffResult = await git.diff([`${baseRef}`, '--name-status']);
+      // Drop blank lines left by the trailing newline in git's output
+      const lines = diffResult.split('\n').filter((line) => line.trim() !== '');
+
+      const changedFiles: ChangedFile[] = [];
+
+      // Classify each changed line by its git status code
+      for (const line of lines) {
+        // Match status and file path
+        // Format: "A\tfile.ts" or "M\tfile.ts" or "D\tfile.ts"
+        // Also handle renames: "R100\told.ts\tnew.ts"
+        const renameMatch = line.match(/^R\d*\s+(.+?)\s+(.+)$/);
+        // Expand a detected rename into a removed old-path entry and a new-path entry
+        if (renameMatch) {
+          const [, oldFile, newFile] = renameMatch;
+          // Add both the removed old file and the new file
+          changedFiles.push({ filepath: `${projectRoot}/${oldFile}`, status: 'removed' });
+          changedFiles.push({ filepath: `${projectRoot}/${newFile}`, status: 'new' });
+          // Rename already handled above; skip the add/modify/delete matching below
+          continue;
+        }
+
+        const match = line.match(/^([AMD])\s+(.+)$/);
+        // Only lines matching the single-letter add/modify/delete status format are actionable
+        if (match) {
+          const [, gitStatus, file] = match;
+          const fullPath = `${projectRoot}/${file}`;
+
+          let status: FileChangeStatus;
+          // Map git's single-letter status codes to our ChangedFile status values
+          if (gitStatus === 'A') {
+            status = 'new';
+          } else if (gitStatus === 'M') {
+            status = 'modified';
+          } else if (gitStatus === 'D') {
+            status = 'removed';
+          } else {
+            // Skip unknown statuses (C=copied, etc.)
+            continue;
+          }
+
+          changedFiles.push({ filepath: fullPath, status });
+        }
+      }
+
+      return changedFiles;
+    } catch {
+      // Handle case where baseRef doesn't exist (e.g., first commit)
+      console.warn(`⚠️  Warning: Git reference '${baseRef}' not found. Processing all files.`);
+      return [];
+    }
+  } catch (error) {
+    throw new Error(`Git diff failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+};