@equinor/fusion-framework-cli-plugin-ai-index 3.0.5 → 3.0.7

package/dist/types/bin/apply-schema.d.ts

@@ -1,6 +1,6 @@
 import type { Observable } from 'rxjs';
 import type { VectorStoreDocument } from '@equinor/fusion-framework-module-ai/lib';
-import type { IndexSchemaConfig } from '../schema.js';
+import type { IndexSchemaConfig } from '../define-index-schema.js';
 /**
  * Creates an RxJS operator that resolves promoted schema fields for each
  * document and separates them from the generic `attributes` bag.

package/dist/types/config.d.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/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 import type { Command } from 'commander';
 export { FusionAIConfigWithIndex, IndexConfig } from './config.js';
-export { defineIndexSchema, IndexSchemaConfig } from './schema.js';
+export { defineIndexSchema, IndexSchemaConfig } from './define-index-schema.js';
 /**
  * Registers the `ai index` command with the Fusion Framework CLI.
  *

package/dist/types/utils/git/get-changed-files.d.ts

@@ -0,0 +1,13 @@
+import type { ChangedFile, GitDiffOptions } from './types.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 declare const getChangedFiles: (options: GitDiffOptions) => Promise<ChangedFile[]>;

package/dist/types/utils/git/get-file-status.d.ts

@@ -0,0 +1,13 @@
+import type { ChangedFile } from './types.js';
+/**
+ * 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[]>;

package/dist/types/utils/git/{git-client.d.ts → get-git.d.ts}

@@ -1,14 +1,4 @@
 import { type SimpleGit } from 'simple-git';
-/**
- * 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;
 /**
  * Returns a cached `SimpleGit` instance scoped to the repository that
  * contains `filePath`.

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

@@ -1,5 +1,8 @@
 export type { GitMetadata, GitDiffOptions, FileChangeStatus, ChangedFile, } from './types.js';
-export { resolveProjectRoot, getGit } from './git-client.js';
-export { extractGitMetadata } from './metadata.js';
-export { getChangedFiles, getFileStatus, isFileChanged } from './file-changes.js';
-export { getGitStatus } from './status.js';
+export { resolveProjectRoot } from './resolve-project-root.js';
+export { getGit } from './get-git.js';
+export { extractGitMetadata } from './extract-git-metadata.js';
+export { getChangedFiles } from './get-changed-files.js';
+export { getFileStatus } from './get-file-status.js';
+export { isFileChanged } from './is-file-changed.js';
+export { getGitStatus } from './get-git-status.js';

package/dist/types/utils/git/is-file-changed.d.ts

@@ -0,0 +1,12 @@
+import type { ChangedFile } from './types.js';
+/**
+ * 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/resolve-project-root.d.ts

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

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

@@ -1,2 +1,4 @@
 export type { MarkdownMetadata, MarkdownDocument } from './types.js';
-export { isMarkdownFile, parseMarkdown, parseMarkdownFile } from './parser.js';
+export { isMarkdownFile } from './is-markdown-file.js';
+export { parseMarkdown } from './parse-markdown.js';
+export { parseMarkdownFile } from './parse-markdown-file.js';

package/dist/types/utils/markdown/is-markdown-file.d.ts

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

package/dist/types/utils/markdown/parse-markdown-file.d.ts

@@ -0,0 +1,14 @@
+import type { SourceFile } from '../types.js';
+import type { MarkdownDocument } from './types.js';
+/**
+ * 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/parse-markdown.d.ts

@@ -0,0 +1,14 @@
+import type { MarkdownDocument } from './types.js';
+/**
+ * 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>[]>;

package/dist/types/utils/ts-doc/create-typescript-document.d.ts

@@ -0,0 +1,12 @@
+import type { SourceFile as ProjectSourceFile } from 'ts-morph';
+import type { TypescriptDocument, ParseTsDocOptions } from './types.js';
+/**
+ * Creates a TypescriptDocument from the given parameters.
+ * @param sourceFile - The source file containing the node.
+ * @param pageContent - The content of the document.
+ * @param tsKind - The TypeScript node kind name.
+ * @param tsName - The name of the TypeScript node.
+ * @param options - Optional parsing configuration.
+ * @returns A TypeScript document with metadata.
+ */
+export declare const createTypescriptDocument: (sourceFile: ProjectSourceFile, pageContent: string, tsKind: string, tsName: string, options?: ParseTsDocOptions) => TypescriptDocument;

package/dist/types/utils/ts-doc/extract-document-from-class-node.d.ts

@@ -0,0 +1,15 @@
+import { type SourceFile as ProjectSourceFile, type ClassDeclaration } from 'ts-morph';
+import type { TypescriptDocument, ParseTsDocOptions } from './types.js';
+/**
+ * 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;

package/dist/types/utils/ts-doc/extract-document-from-node.d.ts

@@ -0,0 +1,20 @@
+import { type SourceFile as ProjectSourceFile, Node } from 'ts-morph';
+import type { TypescriptDocument, ParseTsDocOptions } from './types.js';
+/**
+ * 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 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;

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

@@ -1,2 +1,4 @@
 export type { TypescriptMetadata, TypescriptDocument, ParseTsDocOptions } from './types.js';
-export { isTypescriptFile, parseTsDocSync, parseTsDocFromFileSync } from './parser.js';
+export { isTypescriptFile } from './is-typescript-file.js';
+export { parseTsDocSync } from './parse-ts-doc-sync.js';
+export { parseTsDocFromFileSync } from './parse-ts-doc-from-file-sync.js';

package/dist/types/utils/ts-doc/is-typescript-file.d.ts

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

package/dist/types/utils/ts-doc/parse-ts-doc-from-file-sync.d.ts

@@ -0,0 +1,14 @@
+import type { SourceFile } from '../types.js';
+import type { ParseTsDocOptions, TypescriptDocument } from './types.js';
+/**
+ * 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 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[];

package/dist/types/utils/ts-doc/parse-ts-doc-sync.d.ts

@@ -0,0 +1,12 @@
+import type { ParseTsDocOptions, TypescriptDocument } from './types.js';
+/**
+ * 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 Array of extracted TypeScript documents with TSDoc metadata.
+ */
+export declare const parseTsDocSync: (content: string, options?: ParseTsDocOptions) => TypescriptDocument[];

package/dist/types/utils/ts-doc/process-source-file.d.ts

@@ -0,0 +1,11 @@
+import type { SourceFile as ProjectSourceFile } from 'ts-morph';
+import type { TypescriptDocument, ParseTsDocOptions } from './types.js';
+/**
+ * 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 Array of extracted documents (one per documented declaration).
+ */
+export declare const processSourceFile: (sourceFile: ProjectSourceFile, options?: ParseTsDocOptions) => TypescriptDocument[];

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.0.5";
+export declare const version = "3.0.7";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-cli-plugin-ai-index",
-  "version": "3.0.5",
+  "version": "3.0.7",
   "description": "AI indexing plugin for Fusion Framework CLI providing document embedding and chunking utilities",
   "main": "dist/esm/index.js",
   "type": "module",
@@ -53,18 +53,18 @@
     "tree-sitter-typescript": "^0.23.2",
     "ts-morph": "^28.0.0",
     "zod": "^4.4.3",
-    "@equinor/fusion-framework-cli-plugin-ai-base": "4.0.4",
-    "@equinor/fusion-framework-module": "6.1.0",
-    "@equinor/fusion-framework-module-ai": "6.0.0",
-    "@equinor/fusion-imports": "2.0.0"
+    "@equinor/fusion-framework-cli-plugin-ai-base": "4.0.6",
+    "@equinor/fusion-framework-module": "6.1.1",
+    "@equinor/fusion-imports": "2.0.1",
+    "@equinor/fusion-framework-module-ai": "6.0.2"
   },
   "peerDependencies": {
-    "@equinor/fusion-framework-cli": "^15.1.3"
+    "@equinor/fusion-framework-cli": "^15.2.1"
   },
   "devDependencies": {
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.0",
-    "@equinor/fusion-framework-cli": "^15.1.3"
+    "@equinor/fusion-framework-cli": "^15.2.1"
   },
   "scripts": {
     "build": "tsc -b",

package/src/bin/apply-metadata.ts

@@ -3,7 +3,7 @@ import { from, mergeMap, map, tap, toArray } from 'rxjs';
 import type { Observable } from 'rxjs';
 import type { VectorStoreDocument } from '@equinor/fusion-framework-module-ai/lib';
 import { extractGitMetadata } from '../utils/git/index.js';
-import { resolvePackage } from '../utils/package-resolver.js';
+import { resolvePackage } from '../utils/resolve-package.js';
 import type { DocumentEntry } from './types.js';
 import type { FusionAIConfigWithIndex } from '../config.js';
 
@@ -12,6 +12,11 @@ export type MetadataProgressCallback = (source: string) => void;
 
 /**
  * Creates a stream that applies metadata to documents.
+ *
+ * @param document$ - Stream of document entries to enrich with metadata.
+ * @param indexConfig - Index configuration controlling git/package metadata resolution.
+ * @param onProgress - Optional callback invoked after each document is enriched.
+ * @returns A stream emitting enriched documents grouped by source entry.
  * @internal
  */
 export function applyMetadata(
@@ -32,62 +37,69 @@ export function applyMetadata(
    */
   const ENTRY_CONCURRENCY = 20;
 
-  return document$.pipe(
-    mergeMap((entry) => {
-      return from(entry.documents).pipe(
-        // Extract git metadata concurrently (capped to limit parallel git processes)
-        mergeMap(async (document): Promise<VectorStoreDocument> => {
-          const rootPath = document.metadata.rootPath ?? process.cwd();
-          const sourcePath = path.join(rootPath, document.metadata.source);
-          const gitMetadata =
-            document.metadata.source && indexConfig?.metadata?.resolveGit !== false
-              ? await extractGitMetadata(sourcePath)
-              : {};
+  return (
+    document$
+      // Enrich each document entry with git/package metadata and re-batch the results
+      .pipe(
+        mergeMap((entry) => {
+          // Extract git metadata concurrently (capped to limit parallel git processes)
+          return from(entry.documents).pipe(
+            mergeMap(async (document): Promise<VectorStoreDocument> => {
+              const rootPath = document.metadata.rootPath ?? process.cwd();
+              const sourcePath = path.join(rootPath, document.metadata.source);
+              const gitMetadata =
+                document.metadata.source && indexConfig?.metadata?.resolveGit !== false
+                  ? await extractGitMetadata(sourcePath)
+                  : {};
 
-          // Resolve package information if enabled
-          let packageMetadata = {};
-          if (shouldResolvePackage && document.metadata.source) {
-            packageMetadata = await resolvePackage(sourcePath)
-              .then((pkg) => {
-                return {
-                  pkg_name: pkg?.name,
-                  pkg_version: pkg?.version,
-                  pkg_keywords: pkg?.keywords,
-                };
-              })
-              .catch(() => ({}));
-          }
-          return {
-            ...document,
-            metadata: {
-              ...document.metadata,
-              attributes: {
-                ...document.metadata.attributes,
-                ...gitMetadata,
-                ...packageMetadata,
-              },
-            },
-          };
-        }, GIT_CONCURRENCY),
-        // Notify caller after each document is enriched
-        tap((document) => onProgress?.(document.metadata.source)),
-        // Apply custom attribute processor from config
-        map((document: VectorStoreDocument) => {
-          const attributeProcessor =
-            indexConfig?.metadata?.attributeProcessor ||
-            ((attributes: Record<string, unknown>, _document: VectorStoreDocument) => attributes);
-          const attributes = attributeProcessor(document.metadata.attributes ?? {}, document);
-          return {
-            ...document,
-            metadata: {
-              ...document.metadata,
-              attributes,
-            },
-          };
-        }),
-        // Group back by file for batch deletion in next step
-        toArray(),
-      );
-    }, ENTRY_CONCURRENCY),
+              // Resolve package information if enabled
+              let packageMetadata = {};
+              // Only attempt package resolution when explicitly enabled and a source path is present.
+              if (shouldResolvePackage && document.metadata.source) {
+                packageMetadata = await resolvePackage(sourcePath)
+                  .then((pkg) => {
+                    return {
+                      pkg_name: pkg?.name,
+                      pkg_version: pkg?.version,
+                      pkg_keywords: pkg?.keywords,
+                    };
+                  })
+                  .catch(() => ({}));
+              }
+              // Merge git and package metadata into the document's existing attributes
+              return {
+                ...document,
+                metadata: {
+                  ...document.metadata,
+                  attributes: {
+                    ...document.metadata.attributes,
+                    ...gitMetadata,
+                    ...packageMetadata,
+                  },
+                },
+              };
+            }, GIT_CONCURRENCY),
+            // Notify caller after each document is enriched
+            tap((document) => onProgress?.(document.metadata.source)),
+            // Apply custom attribute processor from config
+            map((document: VectorStoreDocument) => {
+              const attributeProcessor =
+                indexConfig?.metadata?.attributeProcessor ||
+                ((attributes: Record<string, unknown>, _document: VectorStoreDocument) =>
+                  attributes);
+              const attributes = attributeProcessor(document.metadata.attributes ?? {}, document);
+              return {
+                ...document,
+                metadata: {
+                  ...document.metadata,
+                  attributes,
+                },
+              };
+            }),
+            // Group back by file for batch deletion in next step
+            toArray(),
+          );
+        }, ENTRY_CONCURRENCY),
+      )
   );
 }

package/src/bin/apply-schema.test.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import { of, lastValueFrom } from 'rxjs';
 import type { VectorStoreDocument } from '@equinor/fusion-framework-module-ai/lib';
 
-import { defineIndexSchema } from '../schema.js';
+import { defineIndexSchema } from '../define-index-schema.js';
 import { applySchema } from './apply-schema.js';
 
 /** Helper to create a minimal VectorStoreDocument for testing. */
@@ -140,6 +140,7 @@ describe('applySchema', () => {
       prepareAttributes: (attrs, doc) => {
         // Type-safe: attrs.tags is string[] | undefined
         attrs.tags ??= [];
+        // Only tag documents that live under a package directory
         if (doc.metadata.source.includes('packages/')) {
           attrs.tags.push('package');
         }

package/src/bin/apply-schema.ts

@@ -1,7 +1,7 @@
 import { map } from 'rxjs';
 import type { Observable } from 'rxjs';
 import type { VectorStoreDocument } from '@equinor/fusion-framework-module-ai/lib';
-import type { IndexSchemaConfig } from '../schema.js';
+import type { IndexSchemaConfig } from '../define-index-schema.js';
 
 /**
  * Creates an RxJS operator that resolves promoted schema fields for each
@@ -32,12 +32,15 @@ export function applySchema(
 
   const promotedKeys = new Set(Object.keys(schema.shape.shape as Record<string, unknown>));
 
+  // Resolve and validate promoted schema fields for each document batch
   return document$.pipe(
     map((documents) =>
+      // Process each document in the batch individually
       documents.map((document) => {
         // Run typed attribute processor before schema resolution so the
         // resolver receives fully enriched attributes
         let enrichedDocument = document;
+        // Only run the attribute processor when the schema declares one
         if (schema.prepareAttributes) {
           const enrichedAttributes = schema.prepareAttributes(
             (document.metadata.attributes ?? {}) as Record<string, unknown>,
@@ -66,7 +69,9 @@ export function applySchema(
           unknown
         >;
         const remainingAttributes: Record<string, unknown> = {};
+        // Copy over only attributes that were not promoted to schema fields
         for (const [key, value] of Object.entries(currentAttributes)) {
+          // Skip keys already promoted to schemaFields to avoid duplication
           if (!promotedKeys.has(key)) {
             remainingAttributes[key] = value;
           }

package/src/bin/{delete-removed-files.ts → create-delete-removed-files-stream.ts}

@@ -2,10 +2,15 @@ import { map, mergeMap, toArray, filter } from 'rxjs';
 import type { Observable } from 'rxjs';
 import type { FrameworkInstance } from '@equinor/fusion-framework-cli-plugin-ai-base';
 import type { ProcessedFile, DeleteRemovedFilesResult } from './types.js';
-import type { CommandOptions } from '../embeddings-command.options.js';
+import type { CommandOptions } from '../command-options-schema.js';
 
 /**
  * Creates a stream that deletes removed files from the vector store.
+ *
+ * @param removedFiles$ - Stream of files detected as removed from the source tree.
+ * @param framework - Framework instance used to access the configured vector store.
+ * @param options - Command options controlling target index and dry-run behavior.
+ * @returns A stream emitting the result of each batch deletion.
  * @internal
  */
 export function createDeleteRemovedFilesStream(
@@ -13,25 +18,31 @@ export function createDeleteRemovedFilesStream(
   framework: FrameworkInstance,
   options: CommandOptions,
 ): Observable<DeleteRemovedFilesResult> {
+  // Batch removed files, then build a single OData filter for deletion
   return removedFiles$.pipe(
     toArray(),
     map((files) => {
+      // Nothing to delete when there are no removed files
       if (files.length === 0) {
         return { files: [], filterExpression: null };
       }
       // Build OData filter: "metadata/source eq 'path1' or metadata/source eq 'path2'"
+      // Escape each removed file into an OData equality clause
       const filterExpression = files
         .map((file) => `metadata/source eq '${file.relativePath}'`)
         .join(' or ');
       return { files, filterExpression };
     }),
     mergeMap(async ({ files, filterExpression }) => {
+      // Skip the deletion call entirely when there is nothing to remove
       if (files.length === 0) {
         return undefined;
       }
+      // Log each removed file for visibility before deleting
       for (const file of files) {
         console.log('Removing entry from vector store', file.relativePath);
       }
+      // Skip the actual vector store mutation when running in dry-run mode
       if (!options.dryRun) {
         const vectorStoreService = framework.ai.useIndex(options.indexName);
         // Single batch deletion - one file can produce multiple document chunks