@futdevpro/nts-dynamo 1.15.157 → 1.15.163

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

@@ -1,552 +0,0 @@
-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?.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?.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;
-  }
-}