@untangle-code/chunker 0.0.0-stage → 0.1.0

package/src/prepared-text.ts

@@ -0,0 +1,118 @@
+/**
+ * Prepared text builder (spec.md §8.6).
+ *
+ * Dense text gets a metadata header (repository/ref/path/language/symbol/
+ * signature) followed by a blank line and the raw content — this header
+ * counts toward the chunk's token budget (architecture.md §14.4), which is
+ * why every function here is also usable standalone during chunk planning,
+ * before a `CodeChunkDraft` object exists.
+ *
+ * BM25 text is deliberately undecorated: raw code, path, symbol names and a
+ * light identifier extraction, with no natural-language framing, so a
+ * lexical index scores on the same surface a keyword search would use.
+ */
+import type { CodeChunkDraft } from "@untangle-code/domain";
+
+/** Header fields that are not part of a `CodeChunkDraft` (spec.md §8.6). */
+export interface PreparedTextContext {
+  /** Corresponds to `EmbeddingProfile.documentPrefix` (spec.md §5.7, §9). */
+  documentPrefix: string;
+  /** Human-readable repository label (`repo_label`), e.g. "untangle". */
+  repoLabel: string;
+  /** Human-readable ref name (`ref_name`), e.g. "main". */
+  refName: string;
+}
+
+/** The subset of chunk metadata the dense header needs. */
+export interface PreparedTextMeta {
+  filePath: string;
+  language: string;
+  symbolFqn?: string | undefined;
+  signature?: string | undefined;
+}
+
+function buildDenseHeader(ctx: PreparedTextContext, meta: PreparedTextMeta): string {
+  // Trailing "\n\n" reproduces the blank line spec.md §8.6 shows between the
+  // header's last line ("signature: ...") and "{content}" — a `join("\n")`
+  // over the header lines alone only yields a single trailing newline.
+  return (
+    [
+      ctx.documentPrefix,
+      `repository: ${ctx.repoLabel}`,
+      `ref: ${ctx.refName}`,
+      `path: ${meta.filePath}`,
+      `language: ${meta.language}`,
+      `symbol: ${meta.symbolFqn ?? ""}`,
+      `signature: ${meta.signature ?? ""}`,
+    ].join("\n") + "\n\n"
+  );
+}
+
+/** Builds the dense document text of spec.md §8.6 from loose metadata + content. */
+export function buildPreparedDenseText(
+  ctx: PreparedTextContext,
+  meta: PreparedTextMeta,
+  content: string,
+): string {
+  return buildDenseHeader(ctx, meta) + content;
+}
+
+/** Convenience wrapper of {@link buildPreparedDenseText} for an existing draft. */
+export function buildPreparedDenseTextForDraft(
+  ctx: PreparedTextContext,
+  draft: CodeChunkDraft,
+): string {
+  return buildPreparedDenseText(
+    ctx,
+    {
+      filePath: draft.filePath,
+      language: draft.language,
+      symbolFqn: draft.symbolFqn,
+      signature: draft.signature,
+    },
+    draft.content,
+  );
+}
+
+/** Identifier-shaped tokens: letters/digits/underscore/`$`, not starting with a digit. */
+const IDENTIFIER_PATTERN = /[A-Za-z_$][A-Za-z0-9_$]*/g;
+
+function extractIdentifiers(text: string): string[] {
+  const seen = new Set<string>();
+  for (const match of text.matchAll(IDENTIFIER_PATTERN)) {
+    seen.add(match[0]);
+  }
+  return [...seen];
+}
+
+/** The subset of chunk metadata the BM25 text needs. */
+export interface Bm25TextMeta {
+  filePath: string;
+  symbolName?: string | undefined;
+  symbolFqn?: string | undefined;
+}
+
+/**
+ * Builds the BM25 text of spec.md §8.6: raw code, path, symbol names and
+ * identifiers, without natural-language decoration.
+ */
+export function buildBm25Text(meta: Bm25TextMeta, content: string): string {
+  const parts = [meta.filePath];
+  if (meta.symbolFqn) {
+    parts.push(meta.symbolFqn);
+  }
+  if (meta.symbolName) {
+    parts.push(meta.symbolName);
+  }
+  parts.push(...extractIdentifiers(content));
+  parts.push(content);
+  return parts.join("\n");
+}
+
+/** Convenience wrapper of {@link buildBm25Text} for an existing draft. */
+export function buildBm25TextForDraft(draft: CodeChunkDraft): string {
+  return buildBm25Text(
+    { filePath: draft.filePath, symbolName: draft.symbolName, symbolFqn: draft.symbolFqn },
+    draft.content,
+  );
+}

package/src/split.ts

@@ -0,0 +1,164 @@
+/**
+ * Region splitting mechanics shared by the AST strategy (spec.md §8.3 steps
+ * 6-8) and reused defensively by the fallback strategies:
+ *
+ * 1. `flattenToAtoms` — recursive AST-block splitting (step 6) plus
+ *    statement grouping (step 7): descends into `AstRegion.children` only as
+ *    far as needed, filling any gap between/around children with a raw
+ *    "leftover text" atom so the atom list always covers the parent range
+ *    exactly, then greedily re-merges adjacent atoms under the token budget.
+ * 2. `splitByTokenBoundary` — safe token/byte-boundary splitting (step 8):
+ *    the last resort for a single atom that is still too large on its own
+ *    (e.g. one enormous statement with no further AST structure).
+ */
+import type { AstRegion, SourceRange } from "@untangle-code/domain";
+
+import { rangeForByteSpan, safeUtf8Boundary, sliceBytes } from "./byte-text.js";
+import {
+  type BuildContext,
+  contentOf,
+  estimateTokensWithHeader,
+  type HeaderMeta,
+} from "./context.js";
+
+type Header = Pick<HeaderMeta, "symbolFqn" | "signature">;
+
+function fits(ctx: BuildContext, range: SourceRange, header: Header): boolean {
+  return (
+    estimateTokensWithHeader(ctx, contentOf(ctx, range), header) <= ctx.config.maxTokensPerChunk
+  );
+}
+
+function merge(a: SourceRange, b: SourceRange): SourceRange {
+  return { startLine: a.startLine, endLine: b.endLine, startByte: a.startByte, endByte: b.endByte };
+}
+
+/** Greedily merges adjacent (contiguous, ordered) atoms while staying under budget. */
+export function groupAtomsByBudget(
+  ctx: BuildContext,
+  atoms: readonly SourceRange[],
+  header: Header,
+): SourceRange[] {
+  if (atoms.length === 0) {
+    return [];
+  }
+  const result: SourceRange[] = [];
+  let current = atoms[0]!;
+  for (let i = 1; i < atoms.length; i += 1) {
+    const next = atoms[i]!;
+    const merged = merge(current, next);
+    if (fits(ctx, merged, header)) {
+      current = merged;
+    } else {
+      result.push(current);
+      current = next;
+    }
+  }
+  result.push(current);
+  return result;
+}
+
+/**
+ * Recursively splits `node` into an ordered, gap-free list of ranges that
+ * together cover `node.range` exactly. A node that already fits the budget
+ * is returned whole. A node with no further AST structure that still does
+ * not fit is returned whole too — {@link splitByTokenBoundary} handles it.
+ */
+export function flattenToAtoms(ctx: BuildContext, node: AstRegion, header: Header): SourceRange[] {
+  if (fits(ctx, node.range, header)) {
+    return [node.range];
+  }
+  if (node.splittable && node.children && node.children.length > 0) {
+    const children = [...node.children].sort((a, b) => a.range.startByte - b.range.startByte);
+    const atoms: SourceRange[] = [];
+    let cursor = node.range.startByte;
+    for (const child of children) {
+      if (child.range.startByte > cursor) {
+        atoms.push(rangeForByteSpan(ctx.lineIndex, cursor, child.range.startByte));
+      }
+      atoms.push(...flattenToAtoms(ctx, child, header));
+      cursor = Math.max(cursor, child.range.endByte);
+    }
+    if (cursor < node.range.endByte) {
+      atoms.push(rangeForByteSpan(ctx.lineIndex, cursor, node.range.endByte));
+    }
+    return groupAtomsByBudget(ctx, atoms, header);
+  }
+  return [node.range];
+}
+
+/** How far back (bytes) to look for a newline to split on instead of a hard cut. */
+const NEWLINE_LOOKBACK_BYTES = 120;
+
+function findBudgetEnd(ctx: BuildContext, start: number, maxEnd: number, header: Header): number {
+  const wholeRange = rangeForByteSpan(ctx.lineIndex, start, maxEnd);
+  if (fits(ctx, wholeRange, header)) {
+    return maxEnd;
+  }
+  let lo = start + 1;
+  let hi = maxEnd;
+  // Guard: even one byte does not fit under an absurdly small budget — make
+  // forced minimal progress rather than looping forever.
+  if (!fits(ctx, rangeForByteSpan(ctx.lineIndex, start, lo), header)) {
+    return lo;
+  }
+  while (lo < hi) {
+    const mid = lo + Math.ceil((hi - lo) / 2);
+    if (fits(ctx, rangeForByteSpan(ctx.lineIndex, start, mid), header)) {
+      lo = mid;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return lo;
+}
+
+function preferNewlineBoundary(buffer: Buffer, start: number, end: number): number {
+  const lookbackFloor = Math.max(start, end - NEWLINE_LOOKBACK_BYTES);
+  // Do not shrink the piece by more than half just for a nicer boundary.
+  const minAcceptable = Math.max(start + 1, start + Math.floor((end - start) / 2));
+  for (let i = end - 1; i >= lookbackFloor; i -= 1) {
+    if (buffer[i] === 0x0a && i + 1 >= minAcceptable) {
+      return i + 1;
+    }
+  }
+  return end;
+}
+
+/**
+ * Splits `range` into an ordered, gap-free, non-overlapping list of ranges,
+ * each within the token budget, at safe UTF-8 boundaries (architecture.md
+ * §14.4). Last-resort splitter: used only on atoms `flattenToAtoms` could
+ * not shrink through AST structure.
+ */
+export function splitByTokenBoundary(
+  ctx: BuildContext,
+  range: SourceRange,
+  header: Header,
+): SourceRange[] {
+  const pieces: SourceRange[] = [];
+  let cursor = range.startByte;
+  while (cursor < range.endByte) {
+    let end = findBudgetEnd(ctx, cursor, range.endByte, header);
+    if (end > cursor + 1) {
+      end = preferNewlineBoundary(ctx.lineIndex.buffer, cursor, end);
+    }
+    end = safeUtf8Boundary(ctx.lineIndex.buffer, end);
+    if (end <= cursor) {
+      // Never emit an empty piece or fail to progress: force one byte, then
+      // walk forward off any continuation byte it landed on.
+      end = cursor + 1;
+      while (end < range.endByte && (ctx.lineIndex.buffer[end]! & 0b1100_0000) === 0b1000_0000) {
+        end += 1;
+      }
+    }
+    pieces.push(rangeForByteSpan(ctx.lineIndex, cursor, end));
+    cursor = end;
+  }
+  return pieces;
+}
+
+/** Re-exported for strategies that need a raw byte slice without going through an `AstRegion`. */
+export function sliceRange(ctx: BuildContext, range: SourceRange): string {
+  return sliceBytes(ctx.lineIndex, range.startByte, range.endByte);
+}

package/src/strategies/line-fallback-strategy.ts

@@ -0,0 +1,108 @@
+/**
+ * Line fallback strategy (spec.md §8.3 step 9): used whole-file when parsing
+ * failed or produced no usable regions. Splits the file into fixed-size,
+ * overlapping line windows so a retrieval hit still carries some
+ * surrounding context despite the missing AST structure. Any individual
+ * window that is still too large for the token budget (e.g. one very long
+ * line) is defensively re-split at a safe byte boundary.
+ */
+import type { SourceRange } from "@untangle-code/domain";
+
+import { rangeForByteSpan } from "../byte-text.js";
+import {
+  type BuildContext,
+  contentOf,
+  emitChunk,
+  estimateTokensWithHeader,
+  type HeaderMeta,
+} from "../context.js";
+import { chunkedEntry } from "../coverage.js";
+import { splitByTokenBoundary } from "../split.js";
+
+import type { StrategyResult } from "./ast-chunk-strategy.js";
+
+const NO_HEADER: Pick<HeaderMeta, "symbolFqn" | "signature"> = { signature: "fallback_lines" };
+
+/**
+ * Computes the ordered, overlapping line windows covering `[1, totalLines]`.
+ * `step = linesPerChunk - overlapLines` (clamped to at least 1 to guarantee
+ * termination); the last window is extended to the final line.
+ */
+function computeLineWindows(
+  totalLines: number,
+  linesPerChunk: number,
+  overlapLines: number,
+): [number, number][] {
+  const chunkSize = Math.max(1, linesPerChunk);
+  const overlap = Math.min(Math.max(0, overlapLines), chunkSize - 1);
+  const step = Math.max(1, chunkSize - overlap);
+  const windows: [number, number][] = [];
+  let start = 1;
+  while (start <= totalLines) {
+    const end = Math.min(totalLines, start + chunkSize - 1);
+    windows.push([start, end]);
+    if (end >= totalLines) {
+      break;
+    }
+    start += step;
+  }
+  return windows;
+}
+
+export function runLineFallbackStrategy(ctx: BuildContext): StrategyResult {
+  const result: StrategyResult = { drafts: [], coverage: [] };
+  const totalLines = ctx.lineIndex.lineStarts.length;
+  const windows = computeLineWindows(
+    totalLines,
+    ctx.config.lineFallback.linesPerChunk,
+    ctx.config.lineFallback.overlapLines,
+  );
+
+  for (const [startLine, endLine] of windows) {
+    const startByte = ctx.lineIndex.lineStarts[startLine - 1]!;
+    const endByte =
+      endLine < totalLines ? ctx.lineIndex.lineStarts[endLine]! : ctx.lineIndex.buffer.length;
+    if (endByte <= startByte) {
+      // Degenerate trailing "line" produced when the file ends in a newline
+      // (an empty line index entry with nothing after it) — zero bytes, so
+      // there is nothing to cover and nothing to chunk.
+      continue;
+    }
+    const range: SourceRange = { startLine, endLine, startByte, endByte };
+    const content = contentOf(ctx, range);
+    if (estimateTokensWithHeader(ctx, content, NO_HEADER) <= ctx.config.maxTokensPerChunk) {
+      const draft = emitChunk(ctx, {
+        range,
+        content,
+        scopeId: ctx.identity.fileId,
+        chunkKind: "fallback_lines",
+        header: {
+          signature: "fallback_lines",
+          metricsScope: "chunk",
+          metricsScopeId: ctx.identity.fileId,
+        },
+      });
+      result.drafts.push(draft);
+      result.coverage.push(chunkedEntry(draft.range, draft.chunkId));
+    } else {
+      for (const piece of splitByTokenBoundary(ctx, range, NO_HEADER)) {
+        const pieceContent = contentOf(ctx, piece);
+        const rangeWithLines = rangeForByteSpan(ctx.lineIndex, piece.startByte, piece.endByte);
+        const draft = emitChunk(ctx, {
+          range: rangeWithLines,
+          content: pieceContent,
+          scopeId: ctx.identity.fileId,
+          chunkKind: "fallback_lines",
+          header: {
+            signature: "fallback_lines",
+            metricsScope: "chunk",
+            metricsScopeId: ctx.identity.fileId,
+          },
+        });
+        result.drafts.push(draft);
+        result.coverage.push(chunkedEntry(draft.range, draft.chunkId));
+      }
+    }
+  }
+  return result;
+}

package/src/strategies/minified-strategy.ts

@@ -0,0 +1,49 @@
+/**
+ * Minified strategy (spec.md §8.3 step 10): the file is treated as one
+ * opaque blob and split purely at safe token/byte boundaries — there is no
+ * useful AST structure to lean on, by definition of "minified" here.
+ */
+import { rangeForByteSpan, safeUtf8Boundary } from "../byte-text.js";
+import { type BuildContext, contentOf, emitChunk, type HeaderMeta } from "../context.js";
+import { chunkedEntry } from "../coverage.js";
+import { splitByTokenBoundary } from "../split.js";
+
+import type { StrategyResult } from "./ast-chunk-strategy.js";
+
+const HEADER: Pick<HeaderMeta, "symbolFqn" | "signature"> = { signature: "minified_fragment" };
+
+export function runMinifiedStrategy(ctx: BuildContext): StrategyResult {
+  const result: StrategyResult = { drafts: [], coverage: [] };
+  const pieces = splitByTokenBoundary(ctx, ctx.fileRange, HEADER);
+  const overlapBytes = Math.max(0, ctx.config.minifiedStrategy.overlapBytes);
+
+  pieces.forEach((piece, index) => {
+    // Configurable trailing overlap: pull this piece's start back into the
+    // previous piece's territory for retrieval context. Never before the
+    // file start, and never a UTF-8-unsafe cut (architecture.md §14.4).
+    // Coverage stays gap-free either way — overlaps are allowed.
+    let startByte = piece.startByte;
+    if (index > 0 && overlapBytes > 0) {
+      startByte = safeUtf8Boundary(
+        ctx.lineIndex.buffer,
+        Math.max(ctx.fileRange.startByte, piece.startByte - overlapBytes),
+      );
+    }
+    const range = rangeForByteSpan(ctx.lineIndex, startByte, piece.endByte);
+    const content = contentOf(ctx, range);
+    const draft = emitChunk(ctx, {
+      range,
+      content,
+      scopeId: ctx.identity.fileId,
+      chunkKind: "minified_fragment",
+      header: {
+        signature: "minified_fragment",
+        metricsScope: "chunk",
+        metricsScopeId: ctx.identity.fileId,
+      },
+    });
+    result.drafts.push(draft);
+    result.coverage.push(chunkedEntry(draft.range, draft.chunkId));
+  });
+  return result;
+}

package/src/token-estimator.ts

@@ -0,0 +1,48 @@
+/**
+ * Conservative, offline token estimator (architecture.md §14.4).
+ *
+ * There is no network tokenizer call here on purpose (spec.md §24 privacy,
+ * and the chunker must run fully offline). The estimate is deliberately
+ * biased to OVER-estimate real BPE-style tokenizer counts rather than
+ * under-estimate: real code tokenizers average roughly 3.3-4.5 characters
+ * per token (identifiers and keywords tokenize efficiently; whitespace and
+ * punctuation less so). Dividing by a lower `charsPerToken` than that
+ * average guarantees the estimate is usually >= the true count, so a chunk
+ * that "fits the budget" here also fits the embedding model's real budget —
+ * the failure mode of under-estimating (silently truncated embeddings) is
+ * far worse than over-fragmenting slightly.
+ */
+
+export interface TokenEstimatorConfig {
+  /** Conservative average characters per token; lower over-estimates. */
+  charsPerToken: number;
+  /** Per-line overhead (in tokens) added for newline/indentation noise. */
+  perLineOverheadTokens: number;
+}
+
+/** Untangle decision: 3 chars/token (vs. the ~4 real average) plus a small per-line overhead. */
+export const DEFAULT_TOKEN_ESTIMATOR_CONFIG: TokenEstimatorConfig = {
+  charsPerToken: 3,
+  perLineOverheadTokens: 0.25,
+};
+
+/**
+ * Estimates the token count of `text`. Pure function of its inputs; never
+ * touches the network or a real tokenizer vocabulary.
+ */
+export function estimateTokens(
+  text: string,
+  config: TokenEstimatorConfig = DEFAULT_TOKEN_ESTIMATOR_CONFIG,
+): number {
+  if (text.length === 0) {
+    return 0;
+  }
+  let lineCount = 1;
+  for (let i = 0; i < text.length; i += 1) {
+    if (text.charCodeAt(i) === 10) {
+      lineCount += 1;
+    }
+  }
+  const raw = text.length / config.charsPerToken + lineCount * config.perLineOverheadTokens;
+  return Math.max(1, Math.ceil(raw));
+}

package/src/types.ts

@@ -0,0 +1,138 @@
+/**
+ * Chunker-local configuration and input/output contracts.
+ *
+ * These types are additive to `@untangle-code/domain` — they configure how
+ * this package turns `AstRegion`/`ExtractedSymbol`/`ParseResult` into
+ * `CodeChunkDraft`s, but never redefine a domain contract.
+ */
+import type {
+  AstRegion,
+  CodeChunkDraft,
+  CoverageEntry,
+  ExtractedSymbol,
+  ParseQuality,
+  ParseResult,
+} from "@untangle-code/domain";
+
+import type { MinifiedDetectionConfig } from "./minified-detection.js";
+import type { PreparedTextContext } from "./prepared-text.js";
+import type { TokenEstimatorConfig } from "./token-estimator.js";
+
+/** Line-window fallback config for parse failures (spec.md §8.3 step 9). */
+export interface LineFallbackConfig {
+  /** Target number of source lines per fallback chunk before overlap. */
+  linesPerChunk: number;
+  /** Number of trailing lines repeated at the start of the next chunk. */
+  overlapLines: number;
+}
+
+/** Configurable overlap for the minified strategy (spec.md §8.3 step 10). */
+export interface MinifiedStrategyConfig {
+  /** Bytes of trailing context repeated at the start of the next fragment. */
+  overlapBytes: number;
+}
+
+/** Full chunker configuration; every field has a documented default. */
+export interface ChunkerConfig {
+  /** Chunk identity version input (spec.md §5.6). Defaults to `CHUNKER_VERSION`. */
+  chunkerVersion: string;
+  /** Stamped onto every draft as provenance (architecture.md §2.3). */
+  parserVersion: string;
+  /** Conservative token budget per chunk, header included (architecture.md §14.4). */
+  maxTokensPerChunk: number;
+  tokenEstimator: TokenEstimatorConfig;
+  preparedText: PreparedTextContext;
+  minifiedDetection: MinifiedDetectionConfig;
+  lineFallback: LineFallbackConfig;
+  minifiedStrategy: MinifiedStrategyConfig;
+}
+
+/** User-supplied overrides; every field optional except the prepared-text header. */
+export type ChunkerConfigInput = Partial<Omit<ChunkerConfig, "preparedText">> & {
+  preparedText: PreparedTextContext;
+};
+
+/** Minimal identity of the file being chunked (a slice of domain `SourceFile`). */
+export interface ChunkFileIdentity {
+  workspaceId: string;
+  repoId: string;
+  refId: string;
+  fileId: string;
+  /** "/"-normalized path relative to the repository root. */
+  filePath: string;
+  languageId: string;
+}
+
+/** Input to {@link chunkFile} (see `src/chunker.ts`). */
+export interface ChunkFileParams {
+  identity: ChunkFileIdentity;
+  /** Full UTF-8 decoded file content (spec.md §7). */
+  content: string;
+  parseResult: ParseResult;
+  /** `adapter.extractChunks(ast)` output; empty when `parseResult.ast` is null. */
+  regions: AstRegion[];
+  /** `adapter.extractSymbols(ast)` output; empty when `parseResult.ast` is null. */
+  symbols: ExtractedSymbol[];
+  /**
+   * Overrides minified auto-detection when the caller already knows (e.g. a
+   * `.min.js` scanner classification). Leave unset to auto-detect.
+   */
+  isMinified?: boolean;
+  config: ChunkerConfigInput;
+}
+
+/**
+ * Warum der Chunker unterhalb der AST-Strategie geblieben ist (E4, WP-165).
+ *
+ * Geschlossene Menge, damit die Gruende zaehlbar bleiben; die freie
+ * Erlaeuterung steht in `detail`, nicht im Grund. Bewusst PAKETLOKAL und nicht
+ * als `SkipReason` aus `@untangle-code/domain`: dessen geschlossener Katalog
+ * kennt keinen Grund fuer "der Parser war erfolgreich, lieferte aber keine
+ * Regionen", und `parse_failed` waere dafuer schlicht falsch. Dieselbe
+ * Entscheidung hat `@untangle-code/context-artifacts` fuer seinen
+ * `ArtifactSkipReason` getroffen.
+ */
+export const CHUNK_DEGRADATION_REASONS = [
+  /** Der Parser ist gescheitert; es gab keinen Baum, an dem entlang zu schneiden waere. */
+  "parse_failed",
+  /** Der Parser meldete Erfolg, der Sprachadapter lieferte aber keine Regionen. */
+  "ast_regions_missing",
+  /** Der Inhalt ist minifiziert; Byte-Fenster statt Symbolstruktur (spec.md §8.3 Schritt 10). */
+  "minified_content",
+] as const;
+
+export type ChunkDegradationReason = (typeof CHUNK_DEGRADATION_REASONS)[number];
+
+/**
+ * Eine Abstufung: der Chunker hat die Datei zwar lueckenlos erfasst, aber OHNE
+ * die Symbolstruktur, die die AST-Strategie geliefert haette.
+ *
+ * Ohne diesen Eintrag ist genau das unsichtbar. Die Byte-Abdeckung ist
+ * vollstaendig (`assertLosslessCoverage` ist zufrieden), `parseQuality` kann
+ * `"complete"` lauten -- und trotzdem hat kein einziger Chunk eine
+ * Symbolzuordnung. Ein Aufrufer, der `parseQuality` liest, haelt das Ergebnis
+ * fuer strukturell analysiert. Das ist die Fehlerklasse "Vollstaendigkeit
+ * behauptet, Teilbaum verworfen" in ihrer unauffaelligsten Form, deshalb steht
+ * sie hier als eigener, benannter Befund im Ergebnis.
+ */
+export interface ChunkDegradation {
+  reason: ChunkDegradationReason;
+  /** Welche Strategie stattdessen lief. */
+  strategy: "line_fallback" | "minified";
+  /** Menschenlesbare Begruendung; MUSS nicht leer sein (E4). */
+  detail: string;
+}
+
+/** Output of {@link chunkFile}. */
+export interface ChunkFileResult {
+  drafts: CodeChunkDraft[];
+  coverage: CoverageEntry[];
+  /** Which of the three strategies (spec.md §8.3) produced `drafts`. */
+  strategy: "ast" | "line_fallback" | "minified";
+  parseQuality: ParseQuality;
+  /**
+   * Leer, wenn die AST-Strategie lief. Sonst genau ein Eintrag mit dem Grund
+   * (E4: keine stillschweigende Abstufung) -- siehe {@link ChunkDegradation}.
+   */
+  degradations: ChunkDegradation[];
+}