@intlayer/engine 9.0.0-canary.12

package/dist/esm/docReview/pipeline.mjs

@@ -0,0 +1,142 @@
+import { normalizeBlock } from "./normalizeBlock.mjs";
+import { fingerprintBlock } from "./fingerprintBlock.mjs";
+import { mapChangedLinesToBlocks } from "./mapChangedLinesToBlocks.mjs";
+import { alignBaseAndTargetBlocks } from "./alignBlocks.mjs";
+import { identifySegmentsToReview, mergeReviewedSegments } from "./rebuildDocument.mjs";
+import { segmentDocument, segmentSections } from "./segmentDocument.mjs";
+
+//#region src/docReview/pipeline.ts
+/** Fingerprint a list of already-segmented blocks (context = neighbours). */
+const fingerprintBlockList = (blocks) => {
+	return blocks.map(normalizeBlock).map((block, index, array) => fingerprintBlock(block, array[index - 1] ?? null, array[index + 1] ?? null));
+};
+/**
+* Re-segment a section's own text into fine blocks, shifting their relative line
+* numbers back to absolute document positions so changed-line mapping and the
+* review report keep reporting real file coordinates.
+*/
+const fingerprintSectionFineBlocks = (section) => {
+	const lineOffset = section.lineStart - 1;
+	return fingerprintBlockList(segmentDocument(section.content).map((block) => ({
+		...block,
+		lineStart: block.lineStart + lineOffset,
+		lineEnd: block.lineEnd + lineOffset
+	})));
+};
+/**
+* Build the block-aware alignment plan between a base document and its
+* translation, in two levels.
+*
+* 1. **Sections** (heading-anchored) are aligned first. Because a document and
+*    its translation share the same heading structure, this alignment is robust
+*    and never drops a section just because the prose was split into a different
+*    number of paragraphs.
+* 2. Only the sections **touched by a changed line** are then re-segmented into
+*    fine blocks (paragraphs, code fences) and aligned within the section, so a
+*    small edit re-translates only the affected paragraph(s) instead of the
+*    whole section. Within a changed section a target block with no base
+*    counterpart is **kept as-is** (reused) rather than deleted, so a translation
+*    that has extra paragraphs never loses content.
+*
+* Section-level insertions and deletions stay whole: a brand-new section is
+* translated as one unit, and a target section with no base counterpart is
+* reported as `delete` for visibility but never dropped by the merge (see
+* {@link mergeReviewedSegments}), so a review can never lose translated content.
+*
+* @param input - The base/target texts and optional changed lines.
+* @returns The (flattened) blocks, the plan, and the segments that need translation.
+*/
+const buildAlignmentPlan = ({ baseText, targetText, changedLines }) => {
+	const changedLineNumbers = Array.isArray(changedLines) ? changedLines : [];
+	const baseSections = fingerprintBlockList(segmentSections(baseText));
+	const targetSections = fingerprintBlockList(segmentSections(targetText));
+	const sectionAlignment = alignBaseAndTargetBlocks(baseSections, targetSections);
+	const changedSectionIndexes = mapChangedLinesToBlocks(baseSections, changedLineNumbers);
+	const baseBlocks = [];
+	const targetBlocks = [];
+	const actions = [];
+	const pushBaseBlock = (block) => baseBlocks.push(block) - 1;
+	const pushTargetBlock = (block) => targetBlocks.push(block) - 1;
+	for (const pair of sectionAlignment) {
+		if (pair.baseIndex === -1 && pair.targetIndex !== null) {
+			const targetIndex = pushTargetBlock(targetSections[pair.targetIndex]);
+			actions.push({
+				kind: "delete",
+				targetIndex
+			});
+			continue;
+		}
+		if (pair.baseIndex >= 0 && pair.targetIndex === null) {
+			const baseIndex = pushBaseBlock(baseSections[pair.baseIndex]);
+			actions.push({
+				kind: "insert_new",
+				baseIndex
+			});
+			continue;
+		}
+		if (pair.baseIndex < 0 || pair.targetIndex === null) continue;
+		const baseSection = baseSections[pair.baseIndex];
+		const targetSection = targetSections[pair.targetIndex];
+		if (!changedSectionIndexes.has(pair.baseIndex)) {
+			const baseIndex = pushBaseBlock(baseSection);
+			const targetIndex = pushTargetBlock(targetSection);
+			actions.push({
+				kind: "reuse",
+				baseIndex,
+				targetIndex
+			});
+			continue;
+		}
+		const baseFineBlocks = fingerprintSectionFineBlocks(baseSection);
+		const targetFineBlocks = fingerprintSectionFineBlocks(targetSection);
+		const fineAlignment = alignBaseAndTargetBlocks(baseFineBlocks, targetFineBlocks);
+		const changedFineIndexes = mapChangedLinesToBlocks(baseFineBlocks, changedLineNumbers);
+		for (const finePair of fineAlignment) {
+			if (finePair.baseIndex === -1 && finePair.targetIndex !== null) {
+				const targetIndex = pushTargetBlock(targetFineBlocks[finePair.targetIndex]);
+				actions.push({
+					kind: "reuse",
+					baseIndex: -1,
+					targetIndex
+				});
+				continue;
+			}
+			if (finePair.baseIndex >= 0 && finePair.targetIndex === null) {
+				const baseIndex = pushBaseBlock(baseFineBlocks[finePair.baseIndex]);
+				actions.push({
+					kind: "insert_new",
+					baseIndex
+				});
+				continue;
+			}
+			if (finePair.baseIndex < 0 || finePair.targetIndex === null) continue;
+			const baseIndex = pushBaseBlock(baseFineBlocks[finePair.baseIndex]);
+			const targetIndex = pushTargetBlock(targetFineBlocks[finePair.targetIndex]);
+			actions.push(changedFineIndexes.has(finePair.baseIndex) ? {
+				kind: "review",
+				baseIndex,
+				targetIndex
+			} : {
+				kind: "reuse",
+				baseIndex,
+				targetIndex
+			});
+		}
+	}
+	const plan = { actions };
+	const { segmentsToReview } = identifySegmentsToReview({
+		baseBlocks,
+		targetBlocks,
+		plan
+	});
+	return {
+		baseBlocks,
+		targetBlocks,
+		plan,
+		segmentsToReview
+	};
+};
+
+//#endregion
+export { buildAlignmentPlan, mergeReviewedSegments };
+//# sourceMappingURL=pipeline.mjs.map

package/dist/esm/docReview/pipeline.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.mjs","names":[],"sources":["../../../src/docReview/pipeline.ts"],"sourcesContent":["import { alignBaseAndTargetBlocks } from './alignBlocks';\nimport { fingerprintBlock } from './fingerprintBlock';\nimport { mapChangedLinesToBlocks } from './mapChangedLinesToBlocks';\nimport { normalizeBlock } from './normalizeBlock';\nimport {\n  identifySegmentsToReview,\n  mergeReviewedSegments,\n  type SegmentToReview,\n} from './rebuildDocument';\nimport { segmentDocument, segmentSections } from './segmentDocument';\nimport type { Block, FingerprintedBlock, PlannedAction } from './types';\n\nexport type BuildAlignmentPlanInput = {\n  /** The base (source) document, used as the translation reference. */\n  baseText: string;\n  /** The existing target (translated) document, possibly empty. */\n  targetText: string;\n  /** 1-based line numbers that changed in the base document, when known. */\n  changedLines: number[] | undefined;\n};\n\nexport type BuildAlignmentPlanOutput = {\n  baseBlocks: FingerprintedBlock[];\n  targetBlocks: FingerprintedBlock[];\n  plan: AlignmentPlan;\n  segmentsToReview: SegmentToReview[];\n};\n\n/** Fingerprint a list of already-segmented blocks (context = neighbours). */\nconst fingerprintBlockList = (blocks: Block[]): FingerprintedBlock[] => {\n  const normalized = blocks.map(normalizeBlock);\n\n  return normalized.map((block, index, array) =>\n    fingerprintBlock(block, array[index - 1] ?? null, array[index + 1] ?? null)\n  );\n};\n\n/**\n * Re-segment a section's own text into fine blocks, shifting their relative line\n * numbers back to absolute document positions so changed-line mapping and the\n * review report keep reporting real file coordinates.\n */\nconst fingerprintSectionFineBlocks = (section: Block): FingerprintedBlock[] => {\n  const lineOffset = section.lineStart - 1;\n\n  const fineBlocks = segmentDocument(section.content).map(\n    (block): Block => ({\n      ...block,\n      lineStart: block.lineStart + lineOffset,\n      lineEnd: block.lineEnd + lineOffset,\n    })\n  );\n\n  return fingerprintBlockList(fineBlocks);\n};\n\n/**\n * Build the block-aware alignment plan between a base document and its\n * translation, in two levels.\n *\n * 1. **Sections** (heading-anchored) are aligned first. Because a document and\n *    its translation share the same heading structure, this alignment is robust\n *    and never drops a section just because the prose was split into a different\n *    number of paragraphs.\n * 2. Only the sections **touched by a changed line** are then re-segmented into\n *    fine blocks (paragraphs, code fences) and aligned within the section, so a\n *    small edit re-translates only the affected paragraph(s) instead of the\n *    whole section. Within a changed section a target block with no base\n *    counterpart is **kept as-is** (reused) rather than deleted, so a translation\n *    that has extra paragraphs never loses content.\n *\n * Section-level insertions and deletions stay whole: a brand-new section is\n * translated as one unit, and a target section with no base counterpart is\n * reported as `delete` for visibility but never dropped by the merge (see\n * {@link mergeReviewedSegments}), so a review can never lose translated content.\n *\n * @param input - The base/target texts and optional changed lines.\n * @returns The (flattened) blocks, the plan, and the segments that need translation.\n */\nexport const buildAlignmentPlan = ({\n  baseText,\n  targetText,\n  changedLines,\n}: BuildAlignmentPlanInput): BuildAlignmentPlanOutput => {\n  const changedLineNumbers = Array.isArray(changedLines) ? changedLines : [];\n\n  const baseSections = fingerprintBlockList(segmentSections(baseText));\n  const targetSections = fingerprintBlockList(segmentSections(targetText));\n\n  const sectionAlignment = alignBaseAndTargetBlocks(\n    baseSections,\n    targetSections\n  );\n  const changedSectionIndexes = mapChangedLinesToBlocks(\n    baseSections,\n    changedLineNumbers\n  );\n\n  // Flattened blocks the plan refers to by index. Reused/deleted/inserted\n  // sections contribute their whole-section block; changed sections contribute\n  // their fine sub-blocks.\n  const baseBlocks: FingerprintedBlock[] = [];\n  const targetBlocks: FingerprintedBlock[] = [];\n  const actions: PlannedAction[] = [];\n\n  const pushBaseBlock = (block: FingerprintedBlock): number =>\n    baseBlocks.push(block) - 1;\n  const pushTargetBlock = (block: FingerprintedBlock): number =>\n    targetBlocks.push(block) - 1;\n\n  for (const pair of sectionAlignment) {\n    // Section present only in the target → reported as `delete` for visibility,\n    // but kept verbatim by the merge (the aligner may simply have failed to\n    // follow a reordered section), never silently dropped.\n    if (pair.baseIndex === -1 && pair.targetIndex !== null) {\n      const targetIndex = pushTargetBlock(targetSections[pair.targetIndex]!);\n      actions.push({ kind: 'delete', targetIndex });\n      continue;\n    }\n\n    // Section present only in the base → brand new, translate as one unit.\n    if (pair.baseIndex >= 0 && pair.targetIndex === null) {\n      const baseIndex = pushBaseBlock(baseSections[pair.baseIndex]!);\n      actions.push({ kind: 'insert_new', baseIndex });\n      continue;\n    }\n\n    if (pair.baseIndex < 0 || pair.targetIndex === null) continue;\n\n    const baseSection = baseSections[pair.baseIndex]!;\n    const targetSection = targetSections[pair.targetIndex]!;\n\n    // Unchanged section → reuse the existing translation verbatim.\n    if (!changedSectionIndexes.has(pair.baseIndex)) {\n      const baseIndex = pushBaseBlock(baseSection);\n      const targetIndex = pushTargetBlock(targetSection);\n      actions.push({ kind: 'reuse', baseIndex, targetIndex });\n      continue;\n    }\n\n    // Changed section → align its fine blocks and review only what changed.\n    const baseFineBlocks = fingerprintSectionFineBlocks(baseSection);\n    const targetFineBlocks = fingerprintSectionFineBlocks(targetSection);\n    const fineAlignment = alignBaseAndTargetBlocks(\n      baseFineBlocks,\n      targetFineBlocks\n    );\n    const changedFineIndexes = mapChangedLinesToBlocks(\n      baseFineBlocks,\n      changedLineNumbers\n    );\n\n    for (const finePair of fineAlignment) {\n      // Target-only fine block: keep it (no data loss), do not delete.\n      if (finePair.baseIndex === -1 && finePair.targetIndex !== null) {\n        const targetIndex = pushTargetBlock(\n          targetFineBlocks[finePair.targetIndex]!\n        );\n        actions.push({ kind: 'reuse', baseIndex: -1, targetIndex });\n        continue;\n      }\n\n      // Base-only fine block: a new paragraph inside the section, translate it.\n      if (finePair.baseIndex >= 0 && finePair.targetIndex === null) {\n        const baseIndex = pushBaseBlock(baseFineBlocks[finePair.baseIndex]!);\n        actions.push({ kind: 'insert_new', baseIndex });\n        continue;\n      }\n\n      if (finePair.baseIndex < 0 || finePair.targetIndex === null) continue;\n\n      const baseIndex = pushBaseBlock(baseFineBlocks[finePair.baseIndex]!);\n      const targetIndex = pushTargetBlock(\n        targetFineBlocks[finePair.targetIndex]!\n      );\n\n      actions.push(\n        changedFineIndexes.has(finePair.baseIndex)\n          ? { kind: 'review', baseIndex, targetIndex }\n          : { kind: 'reuse', baseIndex, targetIndex }\n      );\n    }\n  }\n\n  const plan = { actions };\n\n  const { segmentsToReview } = identifySegmentsToReview({\n    baseBlocks,\n    targetBlocks,\n    plan,\n  });\n\n  return { baseBlocks, targetBlocks, plan, segmentsToReview };\n};\n\nexport type { SegmentToReview };\nexport { mergeReviewedSegments };\n"],"mappings":"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"}

package/dist/esm/docReview/planActions.mjs

@@ -0,0 +1,56 @@
+//#region src/docReview/planActions.ts
+/**
+* Turn raw alignment pairs into an ordered list of merge actions.
+*
+* A block aligned in both documents is reused when its base counterpart is not
+* marked as changed, and reviewed otherwise. Blocks present only in the base are
+* inserted, blocks present only in the target are deleted.
+*
+* @param alignment - The alignment pairs produced by the aligner.
+* @param changedBaseBlockIndexes - Indexes of base blocks reported as changed.
+* @returns The plan of actions to merge the documents.
+*/
+const planAlignmentActions = (alignment, changedBaseBlockIndexes) => {
+	const actions = [];
+	const seenTarget = /* @__PURE__ */ new Set();
+	alignment.forEach((pair) => {
+		const baseIndex = pair.baseIndex;
+		const targetIndex = pair.targetIndex;
+		if (baseIndex === -1 && targetIndex !== null) {
+			if (!seenTarget.has(targetIndex)) {
+				actions.push({
+					kind: "delete",
+					targetIndex
+				});
+				seenTarget.add(targetIndex);
+			}
+			return;
+		}
+		if (baseIndex >= 0 && targetIndex === null) {
+			actions.push({
+				kind: "insert_new",
+				baseIndex
+			});
+			return;
+		}
+		if (baseIndex >= 0 && targetIndex !== null) {
+			if (!changedBaseBlockIndexes.has(baseIndex)) actions.push({
+				kind: "reuse",
+				baseIndex,
+				targetIndex
+			});
+			else actions.push({
+				kind: "review",
+				baseIndex,
+				targetIndex
+			});
+			seenTarget.add(targetIndex);
+			return;
+		}
+	});
+	return { actions };
+};
+
+//#endregion
+export { planAlignmentActions };
+//# sourceMappingURL=planActions.mjs.map

package/dist/esm/docReview/planActions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"planActions.mjs","names":[],"sources":["../../../src/docReview/planActions.ts"],"sourcesContent":["import type { AlignmentPair, AlignmentPlan, PlannedAction } from './types';\n\n/**\n * Turn raw alignment pairs into an ordered list of merge actions.\n *\n * A block aligned in both documents is reused when its base counterpart is not\n * marked as changed, and reviewed otherwise. Blocks present only in the base are\n * inserted, blocks present only in the target are deleted.\n *\n * @param alignment - The alignment pairs produced by the aligner.\n * @param changedBaseBlockIndexes - Indexes of base blocks reported as changed.\n * @returns The plan of actions to merge the documents.\n */\nexport const planAlignmentActions = (\n  alignment: AlignmentPair[],\n  changedBaseBlockIndexes: Set<number>\n): AlignmentPlan => {\n  const actions: PlannedAction[] = [];\n  const seenTarget = new Set<number>();\n\n  alignment.forEach((pair) => {\n    const baseIndex = pair.baseIndex;\n    const targetIndex = pair.targetIndex;\n\n    // Case 1: Deletion (Exists in target, not in base)\n    if (baseIndex === -1 && targetIndex !== null) {\n      if (!seenTarget.has(targetIndex)) {\n        actions.push({ kind: 'delete', targetIndex });\n        seenTarget.add(targetIndex);\n      }\n      return;\n    }\n\n    // Case 2: New Insertion (Exists in base, not in target)\n    if (baseIndex >= 0 && targetIndex === null) {\n      actions.push({ kind: 'insert_new', baseIndex });\n      return;\n    }\n\n    // Case 3: Alignment (Exists in both)\n    if (baseIndex >= 0 && targetIndex !== null) {\n      const isChanged = changedBaseBlockIndexes.has(baseIndex);\n\n      // If the block is NOT marked as changed, we REUSE it. We assume the existing\n      // translation is correct because the source hasn't been touched. We ignore\n      // 'similarityScore' here because base vs target text will always have low\n      // similarity.\n      if (!isChanged) {\n        actions.push({ kind: 'reuse', baseIndex, targetIndex });\n      } else {\n        // If the block IS changed, we Review it.\n        actions.push({ kind: 'review', baseIndex, targetIndex });\n      }\n\n      seenTarget.add(targetIndex);\n      return;\n    }\n  });\n\n  return { actions };\n};\n"],"mappings":";;;;;;;;;;;;AAaA,MAAa,wBACX,WACA,4BACkB;CAClB,MAAM,UAA2B,EAAE;CACnC,MAAM,6BAAa,IAAI,KAAa;AAEpC,WAAU,SAAS,SAAS;EAC1B,MAAM,YAAY,KAAK;EACvB,MAAM,cAAc,KAAK;AAGzB,MAAI,cAAc,MAAM,gBAAgB,MAAM;AAC5C,OAAI,CAAC,WAAW,IAAI,YAAY,EAAE;AAChC,YAAQ,KAAK;KAAE,MAAM;KAAU;KAAa,CAAC;AAC7C,eAAW,IAAI,YAAY;;AAE7B;;AAIF,MAAI,aAAa,KAAK,gBAAgB,MAAM;AAC1C,WAAQ,KAAK;IAAE,MAAM;IAAc;IAAW,CAAC;AAC/C;;AAIF,MAAI,aAAa,KAAK,gBAAgB,MAAM;AAO1C,OAAI,CANc,wBAAwB,IAAI,UAMhC,CACZ,SAAQ,KAAK;IAAE,MAAM;IAAS;IAAW;IAAa,CAAC;OAGvD,SAAQ,KAAK;IAAE,MAAM;IAAU;IAAW;IAAa,CAAC;AAG1D,cAAW,IAAI,YAAY;AAC3B;;GAEF;AAEF,QAAO,EAAE,SAAS"}

package/dist/esm/docReview/rebuildDocument.mjs

@@ -0,0 +1,62 @@
+//#region src/docReview/rebuildDocument.ts
+/**
+* Analyze the alignment plan and return only the segments that need
+* review/translation. Does not generate output text - that is done by
+* {@link mergeReviewedSegments} once the translations are available.
+*
+* @param input - The base/target blocks and the alignment plan.
+* @returns The list of segments that require translation.
+*/
+const identifySegmentsToReview = ({ baseBlocks, targetBlocks, plan }) => {
+	const segmentsToReview = [];
+	plan.actions.forEach((action, actionIndex) => {
+		if (action.kind === "review") {
+			const baseBlock = baseBlocks[action.baseIndex];
+			const targetBlockText = action.targetIndex !== null ? targetBlocks[action.targetIndex].content : null;
+			segmentsToReview.push({
+				baseBlock,
+				targetBlockText,
+				actionIndex
+			});
+		} else if (action.kind === "insert_new") {
+			const baseBlock = baseBlocks[action.baseIndex];
+			segmentsToReview.push({
+				baseBlock,
+				targetBlockText: null,
+				actionIndex
+			});
+		}
+	});
+	return { segmentsToReview };
+};
+/**
+* Merge reviewed translations back into the final document following the
+* alignment plan, reusing untouched target blocks as-is.
+*
+* @param plan - The alignment plan.
+* @param targetBlocks - Blocks of the existing target document.
+* @param reviewedSegments - Map of action index to its reviewed translation.
+* @returns The rebuilt target document.
+*/
+const mergeReviewedSegments = (plan, targetBlocks, reviewedSegments) => {
+	const outputParts = [];
+	plan.actions.forEach((action, actionIndex) => {
+		if (action.kind === "reuse") outputParts.push(targetBlocks[action.targetIndex].content);
+		else if (action.kind === "review" || action.kind === "insert_new") {
+			const reviewedContent = reviewedSegments.get(actionIndex);
+			if (reviewedContent !== void 0) outputParts.push(reviewedContent);
+			else if (action.kind === "review" && action.targetIndex !== null) outputParts.push(targetBlocks[action.targetIndex].content);
+			else outputParts.push("\n");
+		} else if (action.kind === "delete") {
+			const reviewedContent = reviewedSegments.get(actionIndex);
+			if (reviewedContent !== void 0) {
+				if (reviewedContent) outputParts.push(reviewedContent);
+			} else outputParts.push(targetBlocks[action.targetIndex].content);
+		}
+	});
+	return outputParts.join("");
+};
+
+//#endregion
+export { identifySegmentsToReview, mergeReviewedSegments };
+//# sourceMappingURL=rebuildDocument.mjs.map

package/dist/esm/docReview/rebuildDocument.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebuildDocument.mjs","names":[],"sources":["../../../src/docReview/rebuildDocument.ts"],"sourcesContent":["import type { AlignmentPlan, FingerprintedBlock } from './types';\n\n/**\n * A block that needs to be translated or re-translated by an external consumer\n * (an AI client, a human, or an agent).\n */\nexport type SegmentToReview = {\n  /** The base block to translate. */\n  baseBlock: FingerprintedBlock;\n  /** Existing target translation, or `null` when the block is new. */\n  targetBlockText: string | null;\n  /** Index of the originating action within {@link AlignmentPlan.actions}. */\n  actionIndex: number;\n};\n\nexport type RebuildInput = {\n  baseBlocks: FingerprintedBlock[];\n  targetBlocks: FingerprintedBlock[];\n  plan: AlignmentPlan;\n};\n\nexport type RebuildResult = {\n  segmentsToReview: SegmentToReview[];\n};\n\n/**\n * Analyze the alignment plan and return only the segments that need\n * review/translation. Does not generate output text - that is done by\n * {@link mergeReviewedSegments} once the translations are available.\n *\n * @param input - The base/target blocks and the alignment plan.\n * @returns The list of segments that require translation.\n */\nexport const identifySegmentsToReview = ({\n  baseBlocks,\n  targetBlocks,\n  plan,\n}: RebuildInput): RebuildResult => {\n  const segmentsToReview: SegmentToReview[] = [];\n\n  plan.actions.forEach((action, actionIndex) => {\n    if (action.kind === 'review') {\n      const baseBlock = baseBlocks[action.baseIndex];\n      const targetBlockText =\n        action.targetIndex !== null\n          ? targetBlocks[action.targetIndex].content\n          : null;\n\n      segmentsToReview.push({ baseBlock, targetBlockText, actionIndex });\n    } else if (action.kind === 'insert_new') {\n      const baseBlock = baseBlocks[action.baseIndex];\n\n      segmentsToReview.push({\n        baseBlock,\n        targetBlockText: null,\n        actionIndex,\n      });\n    }\n  });\n\n  return { segmentsToReview };\n};\n\n/**\n * Merge reviewed translations back into the final document following the\n * alignment plan, reusing untouched target blocks as-is.\n *\n * @param plan - The alignment plan.\n * @param targetBlocks - Blocks of the existing target document.\n * @param reviewedSegments - Map of action index to its reviewed translation.\n * @returns The rebuilt target document.\n */\nexport const mergeReviewedSegments = (\n  plan: AlignmentPlan,\n  targetBlocks: FingerprintedBlock[],\n  reviewedSegments: Map<number, string>\n): string => {\n  const outputParts: string[] = [];\n\n  plan.actions.forEach((action, actionIndex) => {\n    if (action.kind === 'reuse') {\n      outputParts.push(targetBlocks[action.targetIndex].content);\n    } else if (action.kind === 'review' || action.kind === 'insert_new') {\n      const reviewedContent = reviewedSegments.get(actionIndex);\n\n      if (reviewedContent !== undefined) {\n        outputParts.push(reviewedContent);\n      } else {\n        // Fallback: if review failed, use existing or blank\n        if (action.kind === 'review' && action.targetIndex !== null) {\n          outputParts.push(targetBlocks[action.targetIndex].content);\n        } else {\n          outputParts.push('\\n');\n        }\n      }\n    } else if (action.kind === 'delete') {\n      const reviewedContent = reviewedSegments.get(actionIndex);\n      if (reviewedContent !== undefined) {\n        // Caller explicitly resolved this block: empty string = actually delete,\n        // non-empty string = replacement content.\n        if (reviewedContent) outputParts.push(reviewedContent);\n      } else {\n        // Default: keep verbatim. A target block with no base counterpart may\n        // just be a section the aligner could not follow (reordering, split\n        // prose) — keeping it prevents accidental data loss in log/read-only mode.\n        outputParts.push(targetBlocks[action.targetIndex].content);\n      }\n    }\n  });\n\n  return outputParts.join('');\n};\n"],"mappings":";;;;;;;;;AAiCA,MAAa,4BAA4B,EACvC,YACA,cACA,WACiC;CACjC,MAAM,mBAAsC,EAAE;AAE9C,MAAK,QAAQ,SAAS,QAAQ,gBAAgB;AAC5C,MAAI,OAAO,SAAS,UAAU;GAC5B,MAAM,YAAY,WAAW,OAAO;GACpC,MAAM,kBACJ,OAAO,gBAAgB,OACnB,aAAa,OAAO,aAAa,UACjC;AAEN,oBAAiB,KAAK;IAAE;IAAW;IAAiB;IAAa,CAAC;aACzD,OAAO,SAAS,cAAc;GACvC,MAAM,YAAY,WAAW,OAAO;AAEpC,oBAAiB,KAAK;IACpB;IACA,iBAAiB;IACjB;IACD,CAAC;;GAEJ;AAEF,QAAO,EAAE,kBAAkB;;;;;;;;;;;AAY7B,MAAa,yBACX,MACA,cACA,qBACW;CACX,MAAM,cAAwB,EAAE;AAEhC,MAAK,QAAQ,SAAS,QAAQ,gBAAgB;AAC5C,MAAI,OAAO,SAAS,QAClB,aAAY,KAAK,aAAa,OAAO,aAAa,QAAQ;WACjD,OAAO,SAAS,YAAY,OAAO,SAAS,cAAc;GACnE,MAAM,kBAAkB,iBAAiB,IAAI,YAAY;AAEzD,OAAI,oBAAoB,OACtB,aAAY,KAAK,gBAAgB;YAG7B,OAAO,SAAS,YAAY,OAAO,gBAAgB,KACrD,aAAY,KAAK,aAAa,OAAO,aAAa,QAAQ;OAE1D,aAAY,KAAK,KAAK;aAGjB,OAAO,SAAS,UAAU;GACnC,MAAM,kBAAkB,iBAAiB,IAAI,YAAY;AACzD,OAAI,oBAAoB,QAGtB;QAAI,gBAAiB,aAAY,KAAK,gBAAgB;SAKtD,aAAY,KAAK,aAAa,OAAO,aAAa,QAAQ;;GAG9D;AAEF,QAAO,YAAY,KAAK,GAAG"}

package/dist/esm/docReview/reviewReport.mjs

@@ -0,0 +1,196 @@
+import { buildAlignmentPlan } from "./pipeline.mjs";
+import { colorize, colorizeNumber } from "@intlayer/config/logger";
+import * as ANSIColors from "@intlayer/config/colors";
+
+//#region src/docReview/reviewReport.ts
+/**
+* Compare a base markdown document with its translation and report only the
+* blocks that need attention, with their line ranges and content.
+*
+* Reusable across the CLI (`doc review --log`), the backend (comparing two
+* translation contents stored in database), and agents that generate the
+* missing translations.
+*
+* @param input - The base/target texts and optional changed lines.
+* @returns The divergent blocks and a per-action summary.
+*/
+const buildReviewReport = ({ baseText, targetText, changedLines }) => {
+	const { baseBlocks, targetBlocks, plan } = buildAlignmentPlan({
+		baseText,
+		targetText,
+		changedLines
+	});
+	const summary = {
+		reuse: 0,
+		review: 0,
+		insertNew: 0,
+		delete: 0
+	};
+	const blocks = [];
+	for (const [actionIndex, action] of plan.actions.entries()) {
+		if (action.kind === "reuse") {
+			summary.reuse += 1;
+			continue;
+		}
+		if (action.kind === "review") {
+			summary.review += 1;
+			const baseBlock = baseBlocks[action.baseIndex];
+			if (!baseBlock) continue;
+			const targetBlock = action.targetIndex !== null ? targetBlocks[action.targetIndex] : null;
+			blocks.push({
+				action: "review",
+				baseLineRange: {
+					start: baseBlock.lineStart,
+					end: baseBlock.lineEnd
+				},
+				targetLineRange: targetBlock ? {
+					start: targetBlock.lineStart,
+					end: targetBlock.lineEnd
+				} : void 0,
+				baseContent: baseBlock.content,
+				targetContent: targetBlock?.content
+			});
+			continue;
+		}
+		if (action.kind === "insert_new") {
+			summary.insertNew += 1;
+			const baseBlock = baseBlocks[action.baseIndex];
+			if (!baseBlock) continue;
+			let insertAfterLine;
+			for (let prevIndex = actionIndex - 1; prevIndex >= 0; prevIndex--) {
+				const prevAction = plan.actions[prevIndex];
+				if (!prevAction) continue;
+				let targetIdx = null;
+				if (prevAction.kind === "reuse") targetIdx = prevAction.targetIndex;
+				else if (prevAction.kind === "review" && prevAction.targetIndex !== null) targetIdx = prevAction.targetIndex;
+				else if (prevAction.kind === "delete") targetIdx = prevAction.targetIndex;
+				if (targetIdx !== null) {
+					const prevTargetBlock = targetBlocks[targetIdx];
+					if (prevTargetBlock) {
+						insertAfterLine = prevTargetBlock.lineEnd + 1;
+						break;
+					}
+				}
+			}
+			blocks.push({
+				action: "insert_new",
+				baseLineRange: {
+					start: baseBlock.lineStart,
+					end: baseBlock.lineEnd
+				},
+				targetLineRange: insertAfterLine !== void 0 ? {
+					start: insertAfterLine,
+					end: insertAfterLine
+				} : void 0,
+				baseContent: baseBlock.content
+			});
+			continue;
+		}
+		if (action.kind === "delete") {
+			summary.delete += 1;
+			const targetBlock = targetBlocks[action.targetIndex];
+			if (!targetBlock) continue;
+			blocks.push({
+				action: "delete",
+				targetLineRange: {
+					start: targetBlock.lineStart,
+					end: targetBlock.lineEnd
+				},
+				targetContent: targetBlock.content
+			});
+		}
+	}
+	return {
+		blocks,
+		summary
+	};
+};
+/** Render a line range as a blue colored string, or an orange dash when absent. */
+const colorizeLineRange = (range) => {
+	if (!range) return colorize("—", ANSIColors.ORANGE);
+	return colorize(range.start === range.end ? `L${range.start}` : `L${range.start}-${range.end}`, ANSIColors.BLUE);
+};
+/**
+* Colorize a count with green when zero (nothing to do) and a caller-supplied
+* non-zero color (orange for warnings, red for destructive actions).
+*/
+const colorizeCount = (count, nonZeroColor) => colorizeNumber(count, {
+	zero: ANSIColors.GREEN,
+	one: nonZeroColor,
+	two: nonZeroColor,
+	few: nonZeroColor,
+	many: nonZeroColor,
+	other: nonZeroColor
+});
+/**
+* Render a {@link ReviewReport} as a human and agent readable log.
+*
+* Each divergent block is printed with its action, the base/target line ranges,
+* the base content to translate, and the existing translation to update.
+*
+* @param report - The report to format.
+* @param options - Optional labels for the base and target locales.
+* @returns A multi-line string describing every block that needs attention.
+*/
+const formatReviewReport = (report, options) => {
+	const baseLabel = options?.baseLabel ?? "base";
+	const targetLabel = options?.targetLabel ?? "target";
+	const { summary, blocks } = report;
+	const header = [
+		colorize("Review report: ", ANSIColors.ORANGE),
+		colorizeCount(blocks.length, ANSIColors.ORANGE),
+		colorize(" block(s) need attention (review=", ANSIColors.ORANGE),
+		colorizeCount(summary.review, ANSIColors.ORANGE),
+		colorize(", new=", ANSIColors.ORANGE),
+		colorizeCount(summary.insertNew, ANSIColors.ORANGE),
+		colorize(", delete=", ANSIColors.ORANGE),
+		colorizeCount(summary.delete, ANSIColors.RED),
+		colorize(", reuse=", ANSIColors.ORANGE),
+		colorizeNumber(summary.reuse),
+		colorize(").", ANSIColors.ORANGE)
+	].join("");
+	if (blocks.length === 0) return `${header}\n${colorize("No changes needed.", ANSIColors.GREEN)}`;
+	const sections = blocks.map((block, index) => {
+		const lines = [];
+		const blockHeader = [
+			colorize("--- Block ", ANSIColors.ORANGE),
+			colorizeNumber(index + 1),
+			colorize("/", ANSIColors.ORANGE),
+			colorizeNumber(blocks.length),
+			colorize(` [${block.action}] `, ANSIColors.ORANGE),
+			baseLabel,
+			colorize(" ", ANSIColors.ORANGE),
+			colorizeLineRange(block.baseLineRange),
+			colorize(" → ", ANSIColors.ORANGE),
+			targetLabel,
+			colorize(" ", ANSIColors.ORANGE),
+			colorizeLineRange(block.targetLineRange),
+			colorize(" ---", ANSIColors.ORANGE)
+		].join("");
+		lines.push(blockHeader);
+		if (block.baseContent !== void 0) {
+			lines.push(colorize(`[${baseLabel}]`, ANSIColors.BEIGE));
+			lines.push(colorize(block.baseContent.trimEnd(), ANSIColors.GREY));
+		}
+		if (block.targetContent !== void 0) {
+			lines.push(colorize(`[${targetLabel}]`, ANSIColors.BEIGE));
+			lines.push(colorize(block.targetContent.trimEnd(), ANSIColors.GREY));
+		} else if (block.action === "insert_new") {
+			lines.push(colorize(`[${targetLabel}]`, ANSIColors.BEIGE));
+			lines.push(colorize("(missing — to be translated)", ANSIColors.ORANGE));
+		}
+		return lines.join("\n");
+	});
+	const editingNote = colorize("Tip: start editing from the last block — working bottom-up keeps earlier line numbers accurate.", ANSIColors.GREY);
+	return [
+		header,
+		"",
+		...sections,
+		"",
+		editingNote
+	].join("\n");
+};
+
+//#endregion
+export { buildReviewReport, formatReviewReport };
+//# sourceMappingURL=reviewReport.mjs.map

package/dist/esm/docReview/reviewReport.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"reviewReport.mjs","names":[],"sources":["../../../src/docReview/reviewReport.ts"],"sourcesContent":["import * as ANSIColors from '@intlayer/config/colors';\nimport { colorize, colorizeNumber } from '@intlayer/config/logger';\nimport { buildAlignmentPlan } from './pipeline';\n\n/**\n * The kind of change detected for a block when reviewing a translation against\n * its base document.\n *\n * - `review`: the base block changed and its translation must be updated.\n * - `insert_new`: the base block has no translation yet and must be added.\n * - `delete`: the target block no longer exists in the base and should be removed.\n */\nexport type ReviewBlockAction = 'review' | 'insert_new' | 'delete';\n\n/** A 1-based, inclusive line range within a document. */\nexport type LineRange = {\n  start: number;\n  end: number;\n};\n\n/**\n * A single block that diverges between the base document and its translation.\n *\n * This is the unit an external translator (AI client, human, or agent) needs to\n * act on: it carries the base content to translate, the existing translation to\n * update, and where each lives so the change can be located in the file.\n */\nexport type ReviewReportBlock = {\n  /** What should happen to this block. */\n  action: ReviewBlockAction;\n  /** Line range of the block in the base document (omitted for pure deletions). */\n  baseLineRange?: LineRange;\n  /** Line range of the block in the target document (omitted for new insertions). */\n  targetLineRange?: LineRange;\n  /** Raw markdown of the base block (omitted for pure deletions). */\n  baseContent?: string;\n  /** Existing translation of the block (omitted for new insertions). */\n  targetContent?: string;\n};\n\nexport type ReviewReportSummary = {\n  /** Number of blocks reused as-is (unchanged translation). */\n  reuse: number;\n  /** Number of blocks whose translation must be updated. */\n  review: number;\n  /** Number of blocks missing a translation. */\n  insertNew: number;\n  /** Number of stale target blocks to delete. */\n  delete: number;\n};\n\nexport type ReviewReport = {\n  /** Only the blocks that diverge (review, insert_new, delete). */\n  blocks: ReviewReportBlock[];\n  /** Counts per action over the whole document, including reused blocks. */\n  summary: ReviewReportSummary;\n};\n\nexport type BuildReviewReportInput = {\n  /** The base (source) document, used as the translation reference. */\n  baseText: string;\n  /** The existing target (translated) document, possibly empty. */\n  targetText: string;\n  /**\n   * 1-based line numbers that changed in the base document. When omitted, only\n   * inserted and deleted blocks are reported (no aligned block is flagged for\n   * review since there is no way to know which ones changed).\n   */\n  changedLines?: number[];\n};\n\n/**\n * Compare a base markdown document with its translation and report only the\n * blocks that need attention, with their line ranges and content.\n *\n * Reusable across the CLI (`doc review --log`), the backend (comparing two\n * translation contents stored in database), and agents that generate the\n * missing translations.\n *\n * @param input - The base/target texts and optional changed lines.\n * @returns The divergent blocks and a per-action summary.\n */\nexport const buildReviewReport = ({\n  baseText,\n  targetText,\n  changedLines,\n}: BuildReviewReportInput): ReviewReport => {\n  const { baseBlocks, targetBlocks, plan } = buildAlignmentPlan({\n    baseText,\n    targetText,\n    changedLines,\n  });\n\n  const summary: ReviewReportSummary = {\n    reuse: 0,\n    review: 0,\n    insertNew: 0,\n    delete: 0,\n  };\n\n  const blocks: ReviewReportBlock[] = [];\n\n  for (const [actionIndex, action] of plan.actions.entries()) {\n    if (action.kind === 'reuse') {\n      summary.reuse += 1;\n      continue;\n    }\n\n    if (action.kind === 'review') {\n      summary.review += 1;\n      const baseBlock = baseBlocks[action.baseIndex];\n\n      if (!baseBlock) continue;\n\n      const targetBlock =\n        action.targetIndex !== null ? targetBlocks[action.targetIndex] : null;\n\n      blocks.push({\n        action: 'review',\n        baseLineRange: { start: baseBlock.lineStart, end: baseBlock.lineEnd },\n        targetLineRange: targetBlock\n          ? { start: targetBlock.lineStart, end: targetBlock.lineEnd }\n          : undefined,\n        baseContent: baseBlock.content,\n        targetContent: targetBlock?.content,\n      });\n      continue;\n    }\n\n    if (action.kind === 'insert_new') {\n      summary.insertNew += 1;\n      const baseBlock = baseBlocks[action.baseIndex];\n\n      if (!baseBlock) continue;\n\n      // Find the target line after which the new block should be inserted:\n      // scan backwards for the last action that produced a target block.\n      let insertAfterLine: number | undefined;\n      for (let prevIndex = actionIndex - 1; prevIndex >= 0; prevIndex--) {\n        const prevAction = plan.actions[prevIndex];\n        if (!prevAction) continue;\n\n        let targetIdx: number | null = null;\n        if (prevAction.kind === 'reuse') targetIdx = prevAction.targetIndex;\n        else if (\n          prevAction.kind === 'review' &&\n          prevAction.targetIndex !== null\n        )\n          targetIdx = prevAction.targetIndex;\n        else if (prevAction.kind === 'delete')\n          targetIdx = prevAction.targetIndex;\n\n        if (targetIdx !== null) {\n          const prevTargetBlock = targetBlocks[targetIdx];\n          if (prevTargetBlock) {\n            insertAfterLine = prevTargetBlock.lineEnd + 1;\n            break;\n          }\n        }\n      }\n\n      blocks.push({\n        action: 'insert_new',\n        baseLineRange: { start: baseBlock.lineStart, end: baseBlock.lineEnd },\n        targetLineRange:\n          insertAfterLine !== undefined\n            ? { start: insertAfterLine, end: insertAfterLine }\n            : undefined,\n        baseContent: baseBlock.content,\n      });\n      continue;\n    }\n\n    if (action.kind === 'delete') {\n      summary.delete += 1;\n      const targetBlock = targetBlocks[action.targetIndex];\n\n      if (!targetBlock) continue;\n\n      blocks.push({\n        action: 'delete',\n        targetLineRange: {\n          start: targetBlock.lineStart,\n          end: targetBlock.lineEnd,\n        },\n        targetContent: targetBlock.content,\n      });\n    }\n  }\n\n  return { blocks, summary };\n};\n\n/** Render a line range as a blue colored string, or an orange dash when absent. */\nconst colorizeLineRange = (range?: LineRange): string => {\n  if (!range) return colorize('—', ANSIColors.ORANGE);\n  const rangeStr =\n    range.start === range.end\n      ? `L${range.start}`\n      : `L${range.start}-${range.end}`;\n  return colorize(rangeStr, ANSIColors.BLUE);\n};\n\n/**\n * Colorize a count with green when zero (nothing to do) and a caller-supplied\n * non-zero color (orange for warnings, red for destructive actions).\n */\nconst colorizeCount = (\n  count: number,\n  nonZeroColor: (typeof ANSIColors)[keyof typeof ANSIColors]\n): string =>\n  colorizeNumber(count, {\n    zero: ANSIColors.GREEN,\n    one: nonZeroColor,\n    two: nonZeroColor,\n    few: nonZeroColor,\n    many: nonZeroColor,\n    other: nonZeroColor,\n  });\n\n/**\n * Render a {@link ReviewReport} as a human and agent readable log.\n *\n * Each divergent block is printed with its action, the base/target line ranges,\n * the base content to translate, and the existing translation to update.\n *\n * @param report - The report to format.\n * @param options - Optional labels for the base and target locales.\n * @returns A multi-line string describing every block that needs attention.\n */\nexport const formatReviewReport = (\n  report: ReviewReport,\n  options?: { baseLabel?: string; targetLabel?: string }\n): string => {\n  const baseLabel = options?.baseLabel ?? 'base';\n  const targetLabel = options?.targetLabel ?? 'target';\n\n  const { summary, blocks } = report;\n\n  // Build the summary header piece-by-piece so each count uses its own color.\n  const header = [\n    colorize('Review report: ', ANSIColors.ORANGE),\n    colorizeCount(blocks.length, ANSIColors.ORANGE),\n    colorize(' block(s) need attention (review=', ANSIColors.ORANGE),\n    colorizeCount(summary.review, ANSIColors.ORANGE),\n    colorize(', new=', ANSIColors.ORANGE),\n    colorizeCount(summary.insertNew, ANSIColors.ORANGE),\n    colorize(', delete=', ANSIColors.ORANGE),\n    colorizeCount(summary.delete, ANSIColors.RED),\n    colorize(', reuse=', ANSIColors.ORANGE),\n    colorizeNumber(summary.reuse),\n    colorize(').', ANSIColors.ORANGE),\n  ].join('');\n\n  if (blocks.length === 0) {\n    return `${header}\\n${colorize('No changes needed.', ANSIColors.GREEN)}`;\n  }\n\n  const sections = blocks.map((block, index) => {\n    const lines: string[] = [];\n\n    // Block header: each token colored individually.\n    const blockHeader = [\n      colorize('--- Block ', ANSIColors.ORANGE),\n      colorizeNumber(index + 1),\n      colorize('/', ANSIColors.ORANGE),\n      colorizeNumber(blocks.length),\n      colorize(` [${block.action}] `, ANSIColors.ORANGE),\n      baseLabel,\n      colorize(' ', ANSIColors.ORANGE),\n      colorizeLineRange(block.baseLineRange),\n      colorize(' → ', ANSIColors.ORANGE),\n      targetLabel,\n      colorize(' ', ANSIColors.ORANGE),\n      colorizeLineRange(block.targetLineRange),\n      colorize(' ---', ANSIColors.ORANGE),\n    ].join('');\n\n    lines.push(blockHeader);\n\n    if (block.baseContent !== undefined) {\n      lines.push(colorize(`[${baseLabel}]`, ANSIColors.BEIGE));\n      lines.push(colorize(block.baseContent.trimEnd(), ANSIColors.GREY));\n    }\n\n    if (block.targetContent !== undefined) {\n      lines.push(colorize(`[${targetLabel}]`, ANSIColors.BEIGE));\n      lines.push(colorize(block.targetContent.trimEnd(), ANSIColors.GREY));\n    } else if (block.action === 'insert_new') {\n      lines.push(colorize(`[${targetLabel}]`, ANSIColors.BEIGE));\n      lines.push(colorize('(missing — to be translated)', ANSIColors.ORANGE));\n    }\n\n    return lines.join('\\n');\n  });\n\n  const editingNote = colorize(\n    'Tip: start editing from the last block — working bottom-up keeps earlier line numbers accurate.',\n    ANSIColors.GREY\n  );\n\n  return [header, '', ...sections, '', editingNote].join('\\n');\n};\n"],"mappings":"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"}

package/dist/esm/docReview/segmentDocument.mjs

@@ -0,0 +1,131 @@
+//#region src/docReview/segmentDocument.ts
+const isBlankLine = (line) => line.trim().length === 0;
+const isFencedCodeDelimiter = (line) => /^\s*```/.test(line);
+const isHeading = (line) => /^\s*#{1,6}\s+/.test(line);
+const isFrontmatterDelimiter = (line) => /^\s*---\s*$/.test(line);
+/**
+* Split a markdown document into fine-grained blocks.
+*
+* Boundaries are drawn at headings, blank lines (paragraph breaks) and fenced
+* code blocks, while frontmatter and the inside of code fences are kept intact.
+* Each blank-line run is appended to the block that precedes it, so the blocks
+* form an exact partition of the document: concatenating every `content` (in
+* order) yields the original text unchanged. This is what lets the block-aware
+* review re-translate only the paragraphs/snippets that actually changed instead
+* of the whole heading section.
+*
+* @param text - The full markdown document.
+* @returns The ordered list of blocks with their 1-based line ranges.
+*/
+const segmentDocument = (text) => {
+	const lines = text.split("\n");
+	const lineCount = lines.length;
+	const units = [];
+	let index = 0;
+	while (index < lineCount) {
+		const currentLine = lines[index];
+		if (isBlankLine(currentLine)) {
+			index += 1;
+			continue;
+		}
+		if (units.length === 0 && isFrontmatterDelimiter(currentLine)) {
+			const startIndex = index;
+			index += 1;
+			while (index < lineCount && !isFrontmatterDelimiter(lines[index])) index += 1;
+			if (index < lineCount) index += 1;
+			units.push({
+				type: "unknown",
+				startIndex,
+				endIndex: index - 1
+			});
+			continue;
+		}
+		if (isFencedCodeDelimiter(currentLine)) {
+			const startIndex = index;
+			index += 1;
+			while (index < lineCount && !isFencedCodeDelimiter(lines[index])) index += 1;
+			if (index < lineCount) index += 1;
+			units.push({
+				type: "code_block",
+				startIndex,
+				endIndex: index - 1
+			});
+			continue;
+		}
+		if (isHeading(currentLine)) {
+			units.push({
+				type: "heading",
+				startIndex: index,
+				endIndex: index
+			});
+			index += 1;
+			continue;
+		}
+		const startIndex = index;
+		while (index < lineCount && !isBlankLine(lines[index]) && !isHeading(lines[index]) && !isFencedCodeDelimiter(lines[index])) index += 1;
+		units.push({
+			type: "paragraph",
+			startIndex,
+			endIndex: index - 1
+		});
+	}
+	if (units.length === 0) return [];
+	return units.map((unit, unitIndex) => {
+		const blockStartIndex = unitIndex === 0 ? 0 : unit.startIndex;
+		const blockEndIndex = unitIndex === units.length - 1 ? lineCount - 1 : units[unitIndex + 1].startIndex - 1;
+		const blockLines = lines.slice(blockStartIndex, blockEndIndex + 1);
+		const content = blockEndIndex < lineCount - 1 ? `${blockLines.join("\n")}\n` : blockLines.join("\n");
+		return {
+			type: unit.type,
+			content,
+			lineStart: blockStartIndex + 1,
+			lineEnd: blockEndIndex + 1
+		};
+	});
+};
+/**
+* Split a markdown document into coarse, heading-anchored sections.
+*
+* Built by grouping the fine blocks of {@link segmentDocument}: frontmatter and
+* each heading open a new section, and the following non-heading blocks are
+* folded into it. Because it only concatenates adjacent fine blocks, the result
+* is still an exact partition of the document (sections concatenate back to the
+* source unchanged).
+*
+* Sections are the robust alignment unit between a base document and its
+* translation — both share the same heading structure, so they align almost
+* perfectly and a translation that splits its prose into a different number of
+* paragraphs never causes a section to be dropped. Fine-grained review happens
+* within a section once it is known to have changed.
+*
+* @param text - The full markdown document.
+* @returns The ordered list of sections with their 1-based line ranges.
+*/
+const segmentSections = (text) => {
+	const fineBlocks = segmentDocument(text);
+	const sections = [];
+	let currentBlocks = [];
+	const flushSection = () => {
+		if (currentBlocks.length === 0) return;
+		const [firstBlock] = currentBlocks;
+		const lastBlock = currentBlocks[currentBlocks.length - 1];
+		sections.push({
+			type: firstBlock.type,
+			content: currentBlocks.map((block) => block.content).join(""),
+			lineStart: firstBlock.lineStart,
+			lineEnd: lastBlock.lineEnd
+		});
+		currentBlocks = [];
+	};
+	for (const block of fineBlocks) {
+		if (block.type === "heading" || block.type === "unknown" && sections.length === 0) flushSection();
+		currentBlocks.push(block);
+		if (block.type === "unknown" && sections.length === 0) flushSection();
+	}
+	flushSection();
+	return sections;
+};
+
+//#endregion
+export { segmentDocument, segmentSections };
+//# sourceMappingURL=segmentDocument.mjs.map