@equinor/fusion-framework-cli-plugin-ai-index 1.0.0

package/src/utils/ts-doc/extractors.ts

@@ -0,0 +1,246 @@
+import {
+  type SourceFile as ProjectSourceFile,
+  SyntaxKind,
+  Node,
+  type VariableStatement,
+  type ClassDeclaration,
+  type MethodDeclaration,
+  type PropertyDeclaration,
+} from 'ts-morph';
+
+import { generateChunkId } from '../generate-chunk-id.js';
+import type { TypescriptDocument, ParseTsDocOptions } from './types.js';
+import { nodeKinds } from './constants.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.
+ * @param sourceOverride - Optional source path override (for cases where source needs transformation).
+ * @returns A TypeScript document with metadata.
+ */
+const createTypescriptDocument = (
+  sourceFile: ProjectSourceFile,
+  pageContent: string,
+  tsKind: string,
+  tsName: string,
+  options?: ParseTsDocOptions,
+): TypescriptDocument => {
+  const source = sourceFile.getFilePath().replace(/^\/+/, '');
+  return {
+    id: generateChunkId(source),
+    pageContent,
+    metadata: {
+      source,
+      ...(options?.projectRoot && { rootPath: options.projectRoot }),
+      attributes: {
+        type: 'tsdoc',
+        ts_kind: tsKind,
+        ts_name: tsName,
+      },
+    },
+  };
+};
+
+/**
+ * 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.
+ */
+export const extractDocumentFromClassNode = (
+  classNode: ClassDeclaration,
+  sourceFile: ProjectSourceFile,
+  _options?: ParseTsDocOptions,
+): TypescriptDocument | null => {
+  // Find TSDoc comment (/** ... */)
+  const docCommentRange = classNode
+    .getLeadingCommentRanges()
+    .find((range) => range.getText().startsWith('/**'));
+
+  if (!docCommentRange) {
+    return null;
+  }
+
+  const docComment = docCommentRange.getText();
+  const className = classNode.getName() || 'AnonymousClass';
+
+  // Start with class TSDoc and declaration (without body)
+  const classSignature = `${classNode.getText({ includeJsDocComments: false }).split('{')[0].trim()} {`;
+  let pageContent = `${docComment}\n${classSignature}`;
+
+  // Add constructor with TSDoc if present
+  const constructorNode = classNode.getConstructors()[0]; // Get the first constructor (if any)
+  if (constructorNode) {
+    const constructorDocCommentRange = constructorNode
+      .getLeadingCommentRanges()
+      .find((range) => range.getText().startsWith('/**'));
+    if (constructorDocCommentRange) {
+      const constructorDocComment = constructorDocCommentRange.getText();
+      const constructorSignature = constructorNode
+        .getText({ includeJsDocComments: false })
+        .split('{')[0]
+        .trim();
+      pageContent += `\n  ${constructorDocComment}\n  ${constructorSignature}`;
+    }
+  }
+
+  // Add public methods and properties with TSDoc
+  const publicMembers = [
+    ...classNode.getMethods().filter((m) => m.hasModifier(SyntaxKind.PublicKeyword)),
+    ...classNode.getProperties().filter((p) => p.hasModifier(SyntaxKind.PublicKeyword)),
+  ];
+
+  publicMembers.forEach((member) => {
+    const memberDocCommentRange = member
+      .getLeadingCommentRanges()
+      .find((range) => range.getText().startsWith('/**'));
+    if (memberDocCommentRange) {
+      const memberDocComment = memberDocCommentRange.getText();
+      let memberSignature = '';
+      if (member.getKind() === SyntaxKind.MethodDeclaration) {
+        memberSignature = (member as MethodDeclaration)
+          .getText({ includeJsDocComments: false })
+          .split('{')[0]
+          .trim();
+      } else if (member.getKind() === SyntaxKind.PropertyDeclaration) {
+        memberSignature = (member as PropertyDeclaration)
+          .getText({ includeJsDocComments: false })
+          .trim();
+      }
+      pageContent += `\n  ${memberDocComment}\n  ${memberSignature}`;
+    }
+  });
+
+  pageContent += '\n}';
+
+  return createTypescriptDocument(
+    sourceFile,
+    pageContent,
+    classNode.getKindName(),
+    className,
+    _options,
+  );
+};
+
+/**
+ * Extracts a TSDoc document from a single node.
+ * @param node - The TypeScript node to process.
+ * @param sourceFile - The source file containing 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.
+ */
+export const extractDocumentFromNode = (
+  node: Node,
+  sourceFile: ProjectSourceFile,
+  options?: ParseTsDocOptions,
+  nodeOptions?: { skipKindCheck?: boolean },
+): TypescriptDocument | null => {
+  const kind = node.getKind();
+
+  // Skip if not in our target kinds unless skipKindCheck is true
+  if (!nodeOptions?.skipKindCheck && !nodeKinds.includes(kind)) {
+    return null;
+  }
+
+  // Handle ClassDeclaration separately
+  if (kind === SyntaxKind.ClassDeclaration) {
+    return extractDocumentFromClassNode(node as ClassDeclaration, sourceFile, options);
+  }
+
+  // Handle VariableStatement (e.g., `export const bundleApp = ...`)
+  if (kind === SyntaxKind.VariableStatement) {
+    const declaration = (node as VariableStatement)
+      .getDeclarations()
+      .find((d) => d.getKind() === SyntaxKind.VariableDeclaration);
+
+    if (!declaration) {
+      return null;
+    }
+
+    const initializer = declaration.getInitializer();
+    if (
+      !initializer ||
+      !(
+        initializer.getKind() === SyntaxKind.ArrowFunction ||
+        initializer.getKind() === SyntaxKind.FunctionExpression
+      )
+    ) {
+      return null;
+    }
+
+    // Get the TSDoc comment from the VariableStatement
+    const docCommentRange = node
+      .getLeadingCommentRanges()
+      .find((range) => range.getText().startsWith('/**'));
+
+    if (!docCommentRange) {
+      return null;
+    }
+
+    const nodeName = declaration.getName() || 'missing_name_of_node';
+    const docComment = docCommentRange.getText();
+
+    // Only include the TSDoc comment for functions/lambdas
+    return createTypescriptDocument(
+      sourceFile,
+      docComment,
+      initializer.getKindName(),
+      nodeName,
+      options,
+    );
+  }
+
+  // Get name if node has one
+  const nodeName = Node.hasName(node) ? node.getName() : 'missing_name_of_node';
+
+  // Find TSDoc comment (/** ... */)
+  const docCommentRange = node
+    .getLeadingCommentRanges()
+    .find((range) => range.getText().startsWith('/**'));
+
+  if (!docCommentRange) {
+    return null;
+  }
+
+  const docComment = docCommentRange.getText();
+  let pageContent = docComment;
+
+  // For interfaces and type aliases, include the full code
+  if (kind === SyntaxKind.InterfaceDeclaration || kind === SyntaxKind.TypeAliasDeclaration) {
+    pageContent = `${docComment}\n${node.getText()}`;
+  }
+  // For other nodes (e.g., FunctionDeclaration), include only TSDoc
+  else if (kind !== SyntaxKind.FunctionDeclaration) {
+    return null; // Skip unsupported kinds
+  }
+
+  return createTypescriptDocument(sourceFile, pageContent, node.getKindName(), nodeName, options);
+};
+
+/**
+ * Processes a TypeScript source file to extract TSDoc documents.
+ * @param sourceFile - The source file to process.
+ * @param options - Optional parsing configuration.
+ * @returns An array of TypeScript documents with TSDoc metadata.
+ */
+export const processSourceFile = (
+  sourceFile: ProjectSourceFile,
+  options?: ParseTsDocOptions,
+): TypescriptDocument[] => {
+  const documents: TypescriptDocument[] = [];
+
+  sourceFile.forEachDescendant((node) => {
+    const document = extractDocumentFromNode(node, sourceFile, options);
+    if (document) {
+      documents.push(document);
+    }
+  });
+
+  return documents;
+};

package/src/utils/ts-doc/index.ts

@@ -0,0 +1,5 @@
+// Re-export all types
+export type { TypescriptMetadata, TypescriptDocument, ParseTsDocOptions } from './types.js';
+
+// Re-export parser functions
+export { isTypescriptFile, parseTsDocSync, parseTsDocFromFileSync } from './parser.js';

package/src/utils/ts-doc/parser.ts

@@ -0,0 +1,51 @@
+import { assert } from 'node:console';
+import { readFileSync } from 'node:fs';
+import { Project } from 'ts-morph';
+
+import type { SourceFile } from '../types.js';
+import type { TypescriptDocument, ParseTsDocOptions } from './types.js';
+import { processSourceFile } from './extractors.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.
+ */
+export const isTypescriptFile = (filePath: string): boolean => {
+  return filePath.endsWith('.ts') || filePath.endsWith('.tsx');
+};
+
+/**
+ * Parses TSDoc from a string of TypeScript code.
+ * @param content - The TypeScript code content.
+ * @param options - Optional parsing configuration.
+ * @returns An array of TypeScript documents with TSDoc metadata.
+ */
+export const parseTsDocSync = (
+  content: string,
+  options?: ParseTsDocOptions,
+): TypescriptDocument[] => {
+  const project = new Project({ useInMemoryFileSystem: true });
+  const sourceFile = project.createSourceFile('temp.ts', content);
+  return processSourceFile(sourceFile, options);
+};
+
+/**
+ * Parses TSDoc from a TypeScript file by path.
+ * @param file - The source file object.
+ * @param options - Optional parsing configuration.
+ * @returns An array of TypeScript documents with TSDoc metadata.
+ * @throws If the file is not a TypeScript file.
+ */
+export const parseTsDocFromFileSync = (
+  file: SourceFile,
+  options?: ParseTsDocOptions,
+): TypescriptDocument[] => {
+  assert(isTypescriptFile(file.path), `File ${file.path} is not a TypeScript file`);
+  const project = new Project({ useInMemoryFileSystem: true });
+  const sourceFile = project.createSourceFile(
+    file.relativePath ?? file.path,
+    readFileSync(file.path, 'utf8'),
+  );
+  return processSourceFile(sourceFile, options);
+};

package/src/utils/ts-doc/types.ts

@@ -0,0 +1,26 @@
+import type {
+  VectorStoreDocument,
+  VectorStoreDocumentMetadata,
+} from '@equinor/fusion-framework-module-ai/lib';
+
+/**
+ * TypeScript document metadata
+ */
+export type TypescriptMetadata = VectorStoreDocumentMetadata<{
+  type: 'tsdoc';
+  ts_kind: string;
+  ts_name: string;
+}>;
+
+/**
+ * TypeScript document with TSDoc metadata
+ */
+export type TypescriptDocument = VectorStoreDocument<TypescriptMetadata>;
+
+/**
+ * Options for parsing TypeScript documents
+ */
+export interface ParseTsDocOptions {
+  /** The project root path for generating relative paths */
+  projectRoot?: string;
+}

package/src/utils/types.ts

@@ -0,0 +1,18 @@
+/**
+ * File change status in git
+ */
+export type FileStatus = 'new' | 'modified' | 'removed';
+
+/**
+ * Source file information for processing
+ */
+export type SourceFile = {
+  /** Absolute file path */
+  path: string;
+  /** Project root directory (git repository root) */
+  projectRoot?: string;
+  /** Relative path from project root */
+  relativePath?: string;
+  /** Git change status */
+  status: FileStatus;
+};

package/src/version.ts

@@ -0,0 +1,2 @@
+// Generated by genversion.
+export const version = '1.0.0';

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist/esm",
+    "rootDir": "src",
+    "declarationDir": "./dist/types",
+    "baseUrl": "."
+  },
+  "references": [
+    {
+      "path": "../ai-base"
+    },
+    {
+      "path": "../../modules/ai"
+    },
+    {
+      "path": "../../modules/module"
+    },
+    {
+      "path": "../../utils/imports"
+    }
+  ],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['**/*.test.ts', '**/dist/**', '**/node_modules/**'],
+    },
+  },
+});