@futdevpro/nts-dynamo 1.15.56 → 1.15.58

package/src/_modules/ai/_modules/document-ai/_collections/dai-code-chunking.util.ts

@@ -0,0 +1,520 @@
+import * as ts from 'typescript';
+import { DyFM_Log } from '@futdevpro/fsm-dynamo';
+import { DyNTS_DAI_CodeChunk, DyNTS_DAI_CodeChunkType } from '../_models/interfaces/dai-code-chunk.interface';
+
+/** A kód-chunker méret-paraméterei (a FAM/CCAP konstansokkal egyező default-ok). */
+export interface DyNTS_DAI_CodeChunking_Options {
+  /** Max chunk-méret karakterben (e fölött sliding-window sub-split). Default: 1500. */
+  maxChunkSize?: number;
+  /** Overlap karakterben a nagy-node sliding-window-ban. Default: 100. */
+  overlap?: number;
+  /** Minimum chunk-méret (ennél kisebb chunk-ot eldobunk a zaj ellen). Default: 50. */
+  minChunkSize?: number;
+}
+
+/** Belső, normalizált méret-konfiguráció (a default-ok feloldása után). */
+interface DyNTS_DAI_CodeChunking_Sizing {
+  maxChunkSize: number;
+  overlap: number;
+  minChunkSize: number;
+}
+
+/**
+ * Belső, AST-ből kinyert szemantikus blokk (a chunkká alakítás előtti közbenső reprezentáció).
+ */
+interface DyNTS_DAI_CodeBlock {
+  /** A node forrás-szövege (JSDoc + dekorátorok kezdetétől a node végéig). */
+  text: string;
+  /** A chunk szemantikus típusa. */
+  chunkType: DyNTS_DAI_CodeChunkType;
+  /** A symbol-lánc szegmensei (pl. `['class:Foo', 'method:bar']`). */
+  symbolSegments: string[];
+  /** A legbelső symbol neve, ha van. */
+  symbolName?: string;
+  /** Karakter-kezdőpozíció a forrásban (0-alapú, inkluzív; JSDoc-ot is tartalmazza). */
+  charStart: number;
+  /** Karakter-végpozíció a forrásban (0-alapú, exkluzív). */
+  charEnd: number;
+}
+
+/**
+ * `DyNTS_DAI_CodeChunking_Util` (BFR-AM-005) — **AST-pontos** TypeScript/JavaScript kód-chunker
+ * a TypeScript Compiler API-val (`ts.createSourceFile`). A FAM `FAM_TsChunker_Util` regex/brace-depth
+ * workaround-jának **bedrock-szintű, durable** változata: a `{`/`}` számolás helyett a valódi
+ * szintaxisfát járja be, így string-literálban / template-literálban / comment-ben lévő zárójelek
+ * NEM tévesztik meg.
+ *
+ * **Chunkolási stratégia (top-level node-onként, egy chunk per szemantikus egység):**
+ * - **import-group** — az összes egymást követő top-level `import` / `export ... from` egy chunkba
+ *   (a köztük lévő üres sorokkal együtt).
+ * - **class** — ha belefér a `maxChunkSize`-ba, az egész osztály egy chunk (dekorátorok + JSDoc-cal);
+ *   ha NEM fér bele, **metódusonként** bomlik (osztály-fej + minden metódus külön chunk, a
+ *   `class:Foo > method:bar` symbol-lánccal).
+ * - **interface / enum / type-alias / standalone function / top-level const(=>fn/value)** — egy chunk
+ *   per deklaráció.
+ * - **nagy node** (a fentiek közül bármelyik, ami a metódus-bontás UTÁN is `maxChunkSize` fölötti) →
+ *   karakter-alapú **sliding-window** sub-split (örökölt `chunkType` + symbol-lánc, `subChunkIndex`-szel).
+ * - **tiny / parse-degenerált tartalom** → egyetlen `fallback` chunk (a teljes forrás), hogy soha
+ *   ne vesszen el tartalom.
+ *
+ * A JSDoc + `@Decorator` MINDIG a következő node-dal együtt marad (a `node.getStart(sf, true)` a
+ * leading-JSDoc elejétől indul, a `ts.getDecorators` a node része).
+ *
+ * **headingPath = kód-symbol-lánc** (a markdown-chunker heading-láncának kód-megfelelője):
+ * `symbolPath` = a szegmensek ` > `-rel összefűzve.
+ */
+export class DyNTS_DAI_CodeChunking_Util {
+
+  /** A FAM/CCAP-egyeztetett default méret-konstansok. */
+  private static readonly DEFAULT_MAX_CHUNK_SIZE: number = 1500;
+  private static readonly DEFAULT_OVERLAP: number = 100;
+  private static readonly DEFAULT_MIN_CHUNK_SIZE: number = 50;
+
+  /**
+   * Egy TS/JS forrás chunkolása szemantikus blokkok mentén a TS Compiler API AST-jával.
+   * Üres / whitespace-only tartalom → üres lista. A `maxChunkSize` fölötti node-ok sliding-window-ra
+   * bomlanak; a degenerált (parse-hiba / 0 blokk) esetet egyetlen `fallback` chunk fedi.
+   *
+   * @param code - A forráskód.
+   * @param opts - Méret-paraméterek (default 1500/100/50).
+   * @returns A szemantikus kód-chunkok listája (0-alapú `chunkIndex`-szel).
+   */
+  static chunkTs(code: string, opts?: DyNTS_DAI_CodeChunking_Options): DyNTS_DAI_CodeChunk[] {
+    if (!code || !code.trim()) {
+      return [];
+    }
+
+    const sizing: DyNTS_DAI_CodeChunking_Sizing = this.resolveSizing(opts);
+
+    let blocks: DyNTS_DAI_CodeBlock[] = [];
+    try {
+      const sourceFile: ts.SourceFile = ts.createSourceFile(
+        'chunk-input.ts',
+        code,
+        ts.ScriptTarget.Latest,
+        /* setParentNodes */ true,
+        ts.ScriptKind.TSX
+      );
+      blocks = this.identifyBlocks(sourceFile, code, sizing);
+    } catch (error) {
+      // Parse-hiba (degenerált forrás) → a tiny-fallback veszi át lentebb.
+      DyFM_Log.warn('DyNTS_DAI_CodeChunking_Util.chunkTs: AST parse failed, using fallback chunk', {
+        error: (error as Error)?.message,
+      });
+      blocks = [];
+    }
+
+    // Tiny / degenerált esetek: ha nincs azonosított blokk, vagy a teljes forrás kicsi → egyetlen
+    // fallback chunk (soha ne vesszen el tartalom).
+    if (!blocks.length) {
+      return this.buildFallbackChunks(code, sizing);
+    }
+
+    // A sor-pozíciókhoz a teljes forrás sortörés-offszetjei (egyszer számolva).
+    const lineStartOffsets: number[] = this.computeLineStartOffsets(code);
+
+    const chunks: DyNTS_DAI_CodeChunk[] = [];
+    for (const block of blocks) {
+      // Zaj-szűrés: CSAK a névtelen `generic` blokkokat dobjuk a minChunkSize alatt. A nevesített
+      // szemantikus deklarációk (type-alias / rövid function / class-fej / metódus / interface /
+      // enum / variable) MINDIG saját chunkot kapnak, méretüktől függetlenül — egy `type Id = string`
+      // teljes értékű egység. Az import-csoport sosem esik ki.
+      if (block.chunkType === 'generic' && block.text.trim().length < sizing.minChunkSize) {
+        continue;
+      }
+
+      if (block.text.length <= sizing.maxChunkSize) {
+        chunks.push(this.blockToChunk(block, chunks.length, lineStartOffsets));
+        continue;
+      }
+
+      // Túl nagy node → karakter-alapú sliding-window sub-split (örökölt symbol-lánc + chunkType).
+      this.splitLargeBlock(block, sizing, chunks, lineStartOffsets);
+    }
+
+    // Ha minden blokk kiesett a minChunkSize-szűrőn (pl. sok apró egysoros), essünk vissza a
+    // fallback-re, hogy ne adjunk vissza üres listát nem-üres bemenetre.
+    if (!chunks.length) {
+      return this.buildFallbackChunks(code, sizing);
+    }
+
+    return chunks;
+  }
+
+  /**
+   * Dispatcher: a `filename` kiterjesztése alapján a `.ts/.tsx/.js/.jsx/.mts/.cts/.mjs/.cjs`
+   * forrásokat az AST-chunkerre (`chunkTs`), minden mást (pl. `.md`) az adott formátum nyers
+   * sliding-fallback-jére irányít. A markdown-specifikus chunkolás a `DyNTS_DAI_DocChunking_Util`
+   * felelőssége (page-modell + parent-hierarchia kell hozzá), ezért azt itt NEM hívjuk —
+   * additív marad. Nem-kód input → `fallback` chunk a tartalom megőrzéséhez.
+   *
+   * @param content - A fájl tartalma.
+   * @param filename - A fájlnév (a kiterjesztés-alapú routinghoz).
+   * @param opts - Méret-paraméterek.
+   */
+  static chunk(content: string, filename: string, opts?: DyNTS_DAI_CodeChunking_Options): DyNTS_DAI_CodeChunk[] {
+    if (this.isTsLike(filename)) {
+      return this.chunkTs(content, opts);
+    }
+    // Nem-kód (pl. .md / .txt / ismeretlen): nyers fallback chunkok — a tartalmat megőrizzük,
+    // de NEM próbáljuk szemantikusan darabolni (a markdown-darabolás külön util-é).
+    if (!content || !content.trim()) {
+      return [];
+    }
+    return this.buildFallbackChunks(content, this.resolveSizing(opts));
+  }
+
+  /** `true`, ha a fájlnév TS/JS-szerű (a `chunkTs` AST-parsere tudja kezelni). */
+  private static isTsLike(filename: string): boolean {
+    return /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/i.test(filename || '');
+  }
+
+  /** A default-ok feloldása (1500/100/50) + sanity-clamp. */
+  private static resolveSizing(opts?: DyNTS_DAI_CodeChunking_Options): DyNTS_DAI_CodeChunking_Sizing {
+    const maxChunkSize: number = Math.max(1, opts?.maxChunkSize ?? this.DEFAULT_MAX_CHUNK_SIZE);
+    const overlap: number = Math.max(0, Math.min(opts?.overlap ?? this.DEFAULT_OVERLAP, maxChunkSize - 1));
+    const minChunkSize: number = Math.max(0, opts?.minChunkSize ?? this.DEFAULT_MIN_CHUNK_SIZE);
+    return { maxChunkSize: maxChunkSize, overlap: overlap, minChunkSize: minChunkSize };
+  }
+
+  /**
+   * AST-bejárás: a `SourceFile` top-level statement-jeit szemantikus blokkokká alakítja. Az
+   * egymást követő import-okat egy `imports` blokkba vonja össze. A `maxChunkSize` fölötti
+   * osztályt metódusonként bontja.
+   */
+  private static identifyBlocks(
+    sourceFile: ts.SourceFile,
+    code: string,
+    sizing: DyNTS_DAI_CodeChunking_Sizing
+  ): DyNTS_DAI_CodeBlock[] {
+    const blocks: DyNTS_DAI_CodeBlock[] = [];
+
+    // -- Import-csoport összevonás --
+    let importStart: number = -1;
+    let importEnd: number = -1;
+
+    const flushImports: () => void = () => {
+      if (importStart < 0) {
+        return;
+      }
+      const text: string = code.substring(importStart, importEnd);
+      if (text.trim().length) {
+        blocks.push({
+          text: text,
+          chunkType: 'imports',
+          symbolSegments: [],
+          symbolName: undefined,
+          charStart: importStart,
+          charEnd: importEnd,
+        });
+      }
+      importStart = -1;
+      importEnd = -1;
+    };
+
+    for (const statement of sourceFile.statements) {
+      if (this.isImportLike(statement)) {
+        const start: number = statement.getStart(sourceFile, /* includeJsDocComment */ true);
+        if (importStart < 0) {
+          importStart = start;
+        }
+        importEnd = statement.getEnd();
+        continue;
+      }
+
+      // Más jött → import-csoport lezárása.
+      flushImports();
+
+      const detected: { chunkType: DyNTS_DAI_CodeChunkType; name?: string } = this.detectDeclaration(statement);
+      const start: number = statement.getStart(sourceFile, /* includeJsDocComment */ true);
+      const end: number = statement.getEnd();
+      const text: string = code.substring(start, end);
+      const symbolSegments: string[] = detected.name ? [`${detected.chunkType}:${detected.name}`] : [];
+
+      // Nagy osztály → metódusonkénti bontás (osztály-fej + metódusok).
+      if (ts.isClassDeclaration(statement) && text.length > sizing.maxChunkSize) {
+        this.splitClassByMethods(statement, sourceFile, code, detected.name, blocks);
+        continue;
+      }
+
+      blocks.push({
+        text: text,
+        chunkType: detected.chunkType,
+        symbolSegments: symbolSegments,
+        symbolName: detected.name,
+        charStart: start,
+        charEnd: end,
+      });
+    }
+
+    // Maradék import-csoport (ha a fájl import-tal végződik).
+    flushImports();
+
+    return blocks;
+  }
+
+  /** `true`, ha a statement import / re-export (`export ... from`) — az import-csoporthoz. */
+  private static isImportLike(statement: ts.Statement): boolean {
+    if (ts.isImportDeclaration(statement) || ts.isImportEqualsDeclaration(statement)) {
+      return true;
+    }
+    // `export { ... } from '...'` / `export * from '...'` — csak ha van moduleSpecifier.
+    if (ts.isExportDeclaration(statement) && !!statement.moduleSpecifier) {
+      return true;
+    }
+    return false;
+  }
+
+  /** Egy top-level statement → szemantikus chunk-típus + symbol-név. */
+  private static detectDeclaration(statement: ts.Statement): { chunkType: DyNTS_DAI_CodeChunkType; name?: string } {
+    if (ts.isClassDeclaration(statement)) {
+      return { chunkType: 'class', name: statement.name?.getText() };
+    }
+    if (ts.isInterfaceDeclaration(statement)) {
+      return { chunkType: 'interface', name: statement.name.getText() };
+    }
+    if (ts.isEnumDeclaration(statement)) {
+      return { chunkType: 'enum', name: statement.name.getText() };
+    }
+    if (ts.isTypeAliasDeclaration(statement)) {
+      return { chunkType: 'type', name: statement.name.getText() };
+    }
+    if (ts.isFunctionDeclaration(statement)) {
+      return { chunkType: 'function', name: statement.name?.getText() };
+    }
+    if (ts.isVariableStatement(statement)) {
+      const firstDecl: ts.VariableDeclaration | undefined = statement.declarationList.declarations[0];
+      const name: string | undefined = firstDecl && ts.isIdentifier(firstDecl.name)
+        ? firstDecl.name.getText()
+        : undefined;
+      // Ha a const egy függvény/arrow → 'function', egyébként 'variable'.
+      const initializer: ts.Expression | undefined = firstDecl?.initializer;
+      const isFn: boolean = !!initializer
+        && (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer));
+      return { chunkType: isFn ? 'function' : 'variable', name: name };
+    }
+    return { chunkType: 'generic', name: undefined };
+  }
+
+  /**
+   * Nagy osztály metódusonkénti bontása. Az első chunk az osztály-fej (a class-kulcsszótól az első
+   * tag előttig, dekorátorok + JSDoc-cal), majd minden metódus / property-deklaráció külön chunk a
+   * `class:Foo > method:bar` symbol-lánccal.
+   */
+  private static splitClassByMethods(
+    classDecl: ts.ClassDeclaration,
+    sourceFile: ts.SourceFile,
+    code: string,
+    className: string | undefined,
+    blocks: DyNTS_DAI_CodeBlock[]
+  ): void {
+    const classSegment: string = `class:${className ?? 'anonymous'}`;
+    const classStart: number = classDecl.getStart(sourceFile, /* includeJsDocComment */ true);
+
+    const members: ts.ClassElement[] = [...classDecl.members];
+
+    // Osztály-fej: a class kezdetétől az első tag kezdetéig (dekorátorok/JSDoc + `class X {`-rész).
+    const headerEnd: number = members.length
+      ? members[0].getStart(sourceFile, /* includeJsDocComment */ true)
+      : classDecl.getEnd();
+    const headerText: string = code.substring(classStart, headerEnd);
+    if (headerText.trim().length) {
+      blocks.push({
+        text: headerText,
+        chunkType: 'class',
+        symbolSegments: [classSegment],
+        symbolName: className,
+        charStart: classStart,
+        charEnd: headerEnd,
+      });
+    }
+
+    // Tagonkénti chunk (metódus / accessor / property).
+    for (const member of members) {
+      const memberStart: number = member.getStart(sourceFile, /* includeJsDocComment */ true);
+      const memberEnd: number = member.getEnd();
+      const memberText: string = code.substring(memberStart, memberEnd);
+      if (!memberText.trim().length) {
+        continue;
+      }
+
+      const memberName: string | undefined = member.name && ts.isIdentifier(member.name)
+        ? member.name.getText()
+        : (member.name ? member.name.getText() : undefined);
+      const memberKind: DyNTS_DAI_CodeChunkType = this.classMemberKind(member);
+      const memberSegment: string = memberName
+        ? `${memberKind}:${memberName}`
+        : memberKind;
+
+      blocks.push({
+        text: memberText,
+        chunkType: memberKind,
+        symbolSegments: [classSegment, memberSegment],
+        symbolName: memberName,
+        charStart: memberStart,
+        charEnd: memberEnd,
+      });
+    }
+  }
+
+  /** Egy osztály-tag → chunk-típus (metódus/accessor → 'method', mező → 'variable'). */
+  private static classMemberKind(member: ts.ClassElement): DyNTS_DAI_CodeChunkType {
+    if (
+      ts.isMethodDeclaration(member)
+      || ts.isConstructorDeclaration(member)
+      || ts.isGetAccessorDeclaration(member)
+      || ts.isSetAccessorDeclaration(member)
+    ) {
+      return 'method';
+    }
+    return 'variable';
+  }
+
+  /** Egy belső blokk → `DyNTS_DAI_CodeChunk` (pozíció + symbol-lánc kiszámolásával). */
+  private static blockToChunk(
+    block: DyNTS_DAI_CodeBlock,
+    chunkIndex: number,
+    lineStartOffsets: number[]
+  ): DyNTS_DAI_CodeChunk {
+    const lineStart: number = this.lineOfOffset(block.charStart, lineStartOffsets);
+    const lineEnd: number = this.lineOfOffset(Math.max(block.charStart, block.charEnd - 1), lineStartOffsets);
+    return {
+      content: block.text,
+      chunkType: block.chunkType,
+      symbolPath: block.symbolSegments.join(' > '),
+      symbolSegments: block.symbolSegments,
+      symbolName: block.symbolName,
+      lineStart: lineStart,
+      lineEnd: lineEnd,
+      charStart: block.charStart,
+      charEnd: block.charEnd,
+      chunkIndex: chunkIndex,
+    };
+  }
+
+  /**
+   * Túl nagy blokk karakter-alapú sliding-window sub-splitje (örökölt chunkType + symbol-lánc).
+   * Az átfedés (`overlap`) karakter-szinten, a `minChunkSize` alatti farok-chunkokat kihagyja.
+   */
+  private static splitLargeBlock(
+    block: DyNTS_DAI_CodeBlock,
+    sizing: DyNTS_DAI_CodeChunking_Sizing,
+    out: DyNTS_DAI_CodeChunk[],
+    lineStartOffsets: number[]
+  ): void {
+    const text: string = block.text;
+    const step: number = Math.max(1, sizing.maxChunkSize - sizing.overlap);
+    let subChunkIndex: number = 0;
+
+    for (let start: number = 0; start < text.length; start += step) {
+      const end: number = Math.min(start + sizing.maxChunkSize, text.length);
+      const slice: string = text.substring(start, end);
+
+      // A nagyon kicsi farok-chunkot (az utolsó, ami már nem éri el a minChunkSize-t) kihagyjuk,
+      // de csak ha NEM ez az egyetlen chunk.
+      if (slice.trim().length < sizing.minChunkSize && subChunkIndex > 0) {
+        break;
+      }
+
+      const absoluteCharStart: number = block.charStart + start;
+      const absoluteCharEnd: number = block.charStart + end;
+      const lineStart: number = this.lineOfOffset(absoluteCharStart, lineStartOffsets);
+      const lineEnd: number = this.lineOfOffset(Math.max(absoluteCharStart, absoluteCharEnd - 1), lineStartOffsets);
+
+      out.push({
+        content: slice,
+        chunkType: block.chunkType,
+        symbolPath: block.symbolSegments.join(' > '),
+        symbolSegments: block.symbolSegments,
+        symbolName: block.symbolName,
+        lineStart: lineStart,
+        lineEnd: lineEnd,
+        charStart: absoluteCharStart,
+        charEnd: absoluteCharEnd,
+        chunkIndex: out.length,
+        subChunkIndex: subChunkIndex,
+      });
+      subChunkIndex++;
+
+      if (end >= text.length) {
+        break;
+      }
+    }
+  }
+
+  /**
+   * Tiny / degenerált fallback: a teljes tartalmat egy (vagy nagy bemenetnél sliding) chunkba teszi.
+   * Soha nem ad vissza üres listát nem-üres bemenetre — a tartalom megőrzése a cél.
+   */
+  private static buildFallbackChunks(content: string, sizing: DyNTS_DAI_CodeChunking_Sizing): DyNTS_DAI_CodeChunk[] {
+    const trimmed: string = content.trim();
+    if (!trimmed) {
+      return [];
+    }
+
+    const lineStartOffsets: number[] = this.computeLineStartOffsets(content);
+
+    // Kis tartalom → egyetlen fallback chunk.
+    if (content.length <= sizing.maxChunkSize) {
+      const lineEnd: number = this.lineOfOffset(Math.max(0, content.length - 1), lineStartOffsets);
+      return [{
+        content: content,
+        chunkType: 'fallback',
+        symbolPath: '',
+        symbolSegments: [],
+        symbolName: undefined,
+        lineStart: 1,
+        lineEnd: lineEnd,
+        charStart: 0,
+        charEnd: content.length,
+        chunkIndex: 0,
+      }];
+    }
+
+    // Nagy, de nem-parse-olható tartalom → sliding-window fallback.
+    const fallbackBlock: DyNTS_DAI_CodeBlock = {
+      text: content,
+      chunkType: 'fallback',
+      symbolSegments: [],
+      symbolName: undefined,
+      charStart: 0,
+      charEnd: content.length,
+    };
+    const out: DyNTS_DAI_CodeChunk[] = [];
+    this.splitLargeBlock(fallbackBlock, sizing, out, lineStartOffsets);
+    return out;
+  }
+
+  /**
+   * A forrás minden sorának kezdő karakter-offszetje (0-alapú). A `lineStartOffsets[i]` az `i`-edik
+   * (0-alapú) sor első karakterének abszolút pozíciója — bináris kereséssel gyors `offset → sor`
+   * konverziót ad a chunkokhoz.
+   */
+  private static computeLineStartOffsets(source: string): number[] {
+    const offsets: number[] = [0];
+    for (let i: number = 0; i < source.length; i++) {
+      if (source[i] === '\n') {
+        offsets.push(i + 1);
+      }
+    }
+    return offsets;
+  }
+
+  /**
+   * Egy abszolút karakter-offszet → 1-alapú sorszám a forrásban (bináris keresés a
+   * `lineStartOffsets`-ben). A sor-mezők így a forrás VALÓDI soraira mutatnak (nem chunk-relatív).
+   */
+  private static lineOfOffset(offset: number, lineStartOffsets: number[]): number {
+    let lo: number = 0;
+    let hi: number = lineStartOffsets.length - 1;
+    while (lo < hi) {
+      const mid: number = (lo + hi + 1) >> 1;
+      if (lineStartOffsets[mid] <= offset) {
+        lo = mid;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    return lo + 1;
+  }
+}