@alauda/doom 2.6.1 → 2.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/lib/cli/translate-call.d.ts +85 -0
  2. package/lib/cli/translate-call.js +162 -0
  3. package/lib/cli/translate-checker.d.ts +8 -0
  4. package/lib/cli/translate-diagnose.d.ts +45 -0
  5. package/lib/cli/translate-diagnose.js +118 -0
  6. package/lib/cli/translate-judge.d.ts +28 -3
  7. package/lib/cli/translate-judge.js +40 -7
  8. package/lib/cli/translate-mask.d.ts +13 -0
  9. package/lib/cli/translate-mask.js +19 -5
  10. package/lib/cli/translate-pipeline.d.ts +156 -0
  11. package/lib/cli/translate-pipeline.js +501 -0
  12. package/lib/cli/translate-repair-agent.d.ts +69 -0
  13. package/lib/cli/translate-repair-agent.js +241 -0
  14. package/lib/cli/translate-scratch.d.ts +9 -1
  15. package/lib/cli/translate-scratch.js +2 -2
  16. package/lib/cli/translate-segment-cache.d.ts +90 -0
  17. package/lib/cli/translate-segment-cache.js +301 -0
  18. package/lib/cli/translate-segment-check.d.ts +42 -0
  19. package/lib/cli/translate-segment-check.js +288 -0
  20. package/lib/cli/translate-segment.d.ts +307 -0
  21. package/lib/cli/translate-segment.js +625 -0
  22. package/lib/cli/translate.d.ts +14 -4
  23. package/lib/cli/translate.js +232 -52
  24. package/lib/remark-lint/no-unopened-frontmatter.js +5 -1
  25. package/lib/remark-lint/no-unparsed-emphasis.d.ts +13 -0
  26. package/lib/remark-lint/no-unparsed-emphasis.js +30 -5
  27. package/lib/remark-lint/translation-parity/frontmatter-preservation.js +5 -3
  28. package/lib/runtime/hooks/useTranslation.d.ts +1 -1
  29. package/lib/types.d.ts +101 -6
  30. package/package.json +1 -1
  31. package/lib/cli/translate-agent.d.ts +0 -81
  32. package/lib/cli/translate-agent.js +0 -450
@@ -0,0 +1,156 @@
1
+ import type { Root } from 'mdast';
2
+ import type { SegmentTranslator } from './translate-call.ts';
3
+ import { type TranslationChecker, type TranslationFinding } from './translate-checker.ts';
4
+ import type { Judge } from './translate-judge.ts';
5
+ import { MaskIntegrityError, type MaskEntry, type MaskProcessor } from './translate-mask.ts';
6
+ import type { SegmentCacheRecord } from './translate-segment-cache.ts';
7
+ import { type Segment, type SegmentRecord } from './translate-segment.ts';
8
+ import type { TermPair } from './translate-terms.ts';
9
+ /**
10
+ * Translating one document, a segment at a time.
11
+ *
12
+ * The shape of this file is the whole proposal in one place: cut the document
13
+ * up, translate each piece on its own, **freeze what passes**, ask again only
14
+ * for what did not, put the pieces back, and check the result as a whole.
15
+ *
16
+ * The freezing is the part that matters. In the design this replaces, the unit
17
+ * of work, of acceptance and of retry were all "the document", while the unit
18
+ * of failure was one placeholder out of 871 — so every retry put everything
19
+ * that was already right back at risk, and one of them took a translation that
20
+ * was one problem from done and turned it into a thousand. Here, a segment that
21
+ * passes is never touched again by anything: not a retry, not a repair, not a
22
+ * later assembly round. Work only ever accumulates.
23
+ */
24
+ /** How many times a segment is asked for before it is escalated. */
25
+ export declare const DEFAULT_MAX_SEGMENT_ATTEMPTS = 3;
26
+ /**
27
+ * How many times the assembled document may send segments back.
28
+ *
29
+ * Raised from 2 on 2026-09-03. At 2, the only rule that ever fired here in
30
+ * production — `no-unparsed-emphasis`, 22 send-backs out of 22 across four
31
+ * builds of `immutable-infra-docs` — failed three of six documents by running
32
+ * out of rounds, and a document that fails discards every other document's
33
+ * accepted work in the same run. The model does fix it; it does not always fix
34
+ * it twice in a row.
35
+ *
36
+ * This is the backstop, not the fix: that rule is now also checked per segment,
37
+ * where it gets three attempts and a repair agent before it ever reaches here.
38
+ */
39
+ export declare const DEFAULT_MAX_ASSEMBLY_ROUNDS = 4;
40
+ export type SegmentStatus = 'translated' | 'cached' | 'repaired' | 'failed';
41
+ export interface SegmentOutcome {
42
+ index: number;
43
+ status: SegmentStatus;
44
+ label: Segment['label'];
45
+ /** Model calls spent asking for this segment, across every round. */
46
+ attempts: number;
47
+ /** What was wrong on each rejected attempt, oldest first. For the diagnosis. */
48
+ history: TranslationFinding[][];
49
+ /** What was still wrong when it was given up on. */
50
+ findings: TranslationFinding[];
51
+ }
52
+ export type DocumentFailure =
53
+ /** A single block too large to send and impossible to divide. */
54
+ {
55
+ kind: 'unsplittable-block';
56
+ detail: string;
57
+ }
58
+ /** One or more segments never passed. */
59
+ | {
60
+ kind: 'segment';
61
+ segments: readonly number[];
62
+ }
63
+ /** The assembled document failed a whole-document rule that was routed back and still failed. */
64
+ | {
65
+ kind: 'assembly';
66
+ }
67
+ /** The assembled document failed a rule nothing could attribute to a segment. */
68
+ | {
69
+ kind: 'unlocatable';
70
+ };
71
+ export interface TranslateDocumentResult {
72
+ /** The finished document, when it passed. */
73
+ document?: string;
74
+ /**
75
+ * What was still wrong when the run ended.
76
+ *
77
+ * `document` is set exactly when none of these block. A passing document can
78
+ * still carry advisory findings — readability notes, and the whole-document
79
+ * review — which are worth printing and not worth failing a build over.
80
+ */
81
+ findings: TranslationFinding[];
82
+ failure?: DocumentFailure;
83
+ outcomes: SegmentOutcome[];
84
+ assemblyRounds: number;
85
+ /** Where each segment landed, for the next run's cache. Only when it passed. */
86
+ records?: SegmentRecord[];
87
+ }
88
+ /** A last resort for a segment repeated attempts could not fix. */
89
+ export interface SegmentRepairer {
90
+ repair(request: {
91
+ segment: Segment;
92
+ /** The best rejected attempt — the one with the fewest blocking findings. */
93
+ draft: string;
94
+ history: readonly TranslationFinding[][];
95
+ /**
96
+ * The acceptance check for this segment, so the agent sees exactly the
97
+ * verdict that will decide its work.
98
+ *
99
+ * Handed in rather than rebuilt: an agent checking itself against anything
100
+ * but the real gate would pass its own check and then be rejected, which is
101
+ * a loop with no exit.
102
+ */
103
+ check: (translation: string) => Promise<TranslationFinding[]>;
104
+ }): Promise<string | undefined>;
105
+ }
106
+ export interface TranslateDocumentOptions {
107
+ /** The masked tree. Segments address it, assembly rebuilds it. */
108
+ tree: Root;
109
+ /** The masked source as text, for the whole-document review. */
110
+ maskedSource: string;
111
+ maskEntries: readonly MaskEntry[];
112
+ processor: MaskProcessor;
113
+ /** Merges a restored translation with the frontmatter it will be written with. */
114
+ compose: (restored: string, cache?: SegmentCacheRecord) => string;
115
+ /** Absolute path the translation will be written to. */
116
+ targetPath: string;
117
+ /** Path of the source, relative to the docs root — for logs only. */
118
+ sourceLabel: string;
119
+ /** Language names, as the reviewer is told them — `English`, not `en`. */
120
+ sourceLanguage: string;
121
+ targetLanguage: string;
122
+ translator: SegmentTranslator;
123
+ checker: TranslationChecker;
124
+ /** Reads each segment against its source. */
125
+ segmentJudge?: Judge;
126
+ /** Reads the assembled document. Advisory only — it never fails a build. */
127
+ documentJudge?: Judge;
128
+ terms?: readonly TermPair[];
129
+ segmentCap?: number;
130
+ segmentHardCap?: number;
131
+ segmentFloor?: number;
132
+ maxSegmentAttempts?: number;
133
+ maxAssemblyRounds?: number;
134
+ contextTail?: number;
135
+ repairer?: SegmentRepairer;
136
+ /**
137
+ * The translation already on disk, for reusing the segments that did not
138
+ * change. Absent on a first translation, and when `--force` is given.
139
+ *
140
+ * What may be reused is decided in `translate-segment-cache.ts`, which
141
+ * verifies every candidate against this document's own mask table before
142
+ * offering it.
143
+ */
144
+ previous?: {
145
+ body: string;
146
+ record?: SegmentCacheRecord;
147
+ };
148
+ onProgress?: (message: string) => void;
149
+ }
150
+ /**
151
+ * A mask finding, said in the vocabulary the rest of the pipeline speaks.
152
+ *
153
+ * Exported because the repair agent reports the same things.
154
+ */
155
+ export declare const maskFindingToTranslationFinding: (finding: MaskIntegrityError["findings"][number]) => TranslationFinding;
156
+ export declare const translateDocument: (options: TranslateDocumentOptions) => Promise<TranslateDocumentResult>;
@@ -0,0 +1,501 @@
1
+ import { renderOutline, tailOf } from "./translate-call.js";
2
+ import { blockingFindings, } from "./translate-checker.js";
3
+ import { MaskIntegrityError, restoreMaskedContent, } from "./translate-mask.js";
4
+ import { encodeCacheRecord, matchCachedSegments, } from "./translate-segment-cache.js";
5
+ import { checkSegment } from "./translate-segment-check.js";
6
+ import { UnsplittableBlockError, assemble, documentOutline, planSegments, resolveAttributeNode, resolvePlacement, } from "./translate-segment.js";
7
+ /**
8
+ * Translating one document, a segment at a time.
9
+ *
10
+ * The shape of this file is the whole proposal in one place: cut the document
11
+ * up, translate each piece on its own, **freeze what passes**, ask again only
12
+ * for what did not, put the pieces back, and check the result as a whole.
13
+ *
14
+ * The freezing is the part that matters. In the design this replaces, the unit
15
+ * of work, of acceptance and of retry were all "the document", while the unit
16
+ * of failure was one placeholder out of 871 — so every retry put everything
17
+ * that was already right back at risk, and one of them took a translation that
18
+ * was one problem from done and turned it into a thousand. Here, a segment that
19
+ * passes is never touched again by anything: not a retry, not a repair, not a
20
+ * later assembly round. Work only ever accumulates.
21
+ */
22
+ /** How many times a segment is asked for before it is escalated. */
23
+ export const DEFAULT_MAX_SEGMENT_ATTEMPTS = 3;
24
+ /**
25
+ * How many times the assembled document may send segments back.
26
+ *
27
+ * Raised from 2 on 2026-09-03. At 2, the only rule that ever fired here in
28
+ * production — `no-unparsed-emphasis`, 22 send-backs out of 22 across four
29
+ * builds of `immutable-infra-docs` — failed three of six documents by running
30
+ * out of rounds, and a document that fails discards every other document's
31
+ * accepted work in the same run. The model does fix it; it does not always fix
32
+ * it twice in a row.
33
+ *
34
+ * This is the backstop, not the fix: that rule is now also checked per segment,
35
+ * where it gets three attempts and a repair agent before it ever reaches here.
36
+ */
37
+ export const DEFAULT_MAX_ASSEMBLY_ROUNDS = 4;
38
+ /**
39
+ * A mask finding, said in the vocabulary the rest of the pipeline speaks.
40
+ *
41
+ * Exported because the repair agent reports the same things.
42
+ */
43
+ export const maskFindingToTranslationFinding = (finding) => ({
44
+ rule: `doom-translate:${finding.code}`,
45
+ reason: finding.code === 'missing-placeholder'
46
+ ? `\`${finding.placeholder}\` is not in the translation. It stands for a ${finding.kind}${finding.detail ? ` (${finding.detail})` : ''}. Either that part has not been translated yet, or it was dropped.`
47
+ : finding.code === 'duplicate-placeholder'
48
+ ? `\`${finding.placeholder}\` appears ${finding.actual} times but must appear ${finding.expected}.`
49
+ : finding.code === 'unregistered-placeholder'
50
+ ? `\`${finding.placeholder}\` was never issued — do not invent placeholders.`
51
+ : finding.code === 'unrestored-placeholder'
52
+ ? `\`${finding.placeholder}\` ended up somewhere it does not belong${finding.detail ? ` — ${finding.detail}` : ''}.`
53
+ : (finding.detail ??
54
+ `the placeholder round trip failed (${finding.code})`),
55
+ placeholder: finding.placeholder,
56
+ });
57
+ export const translateDocument = async (options) => {
58
+ const { tree, maskedSource, maskEntries, processor, compose, targetPath, sourceLabel, sourceLanguage, targetLanguage, translator, checker, segmentJudge, documentJudge, terms, segmentCap, segmentHardCap, segmentFloor, maxSegmentAttempts = DEFAULT_MAX_SEGMENT_ATTEMPTS, maxAssemblyRounds = DEFAULT_MAX_ASSEMBLY_ROUNDS, contextTail, repairer, previous, onProgress, } = options;
59
+ let plan;
60
+ try {
61
+ plan = planSegments({
62
+ tree,
63
+ processor,
64
+ cap: segmentCap,
65
+ hardCap: segmentHardCap,
66
+ floor: segmentFloor,
67
+ });
68
+ }
69
+ catch (error) {
70
+ if (error instanceof UnsplittableBlockError) {
71
+ // Not a translation failure: nothing a model could have done differently.
72
+ // The document has to change.
73
+ return {
74
+ findings: [
75
+ { rule: 'doom-translate:unsplittable-block', reason: error.message },
76
+ ],
77
+ failure: { kind: 'unsplittable-block', detail: error.message },
78
+ outcomes: [],
79
+ assemblyRounds: 0,
80
+ };
81
+ }
82
+ throw error;
83
+ }
84
+ const { reuse, reason: noReuse } = previous
85
+ ? matchCachedSegments({
86
+ plan,
87
+ maskEntries,
88
+ processor,
89
+ previousBody: previous.body,
90
+ record: previous.record,
91
+ })
92
+ : { reuse: new Map(), reason: undefined };
93
+ if (previous && reuse.size === 0 && noReuse) {
94
+ onProgress?.(`${sourceLabel}: nothing reused — ${noReuse}`);
95
+ }
96
+ const documentTokens = new Set(maskEntries.map((entry) => entry.placeholder.toLowerCase()));
97
+ /**
98
+ * Whether the reviewer is looking at a piece of a page or at the page.
99
+ *
100
+ * A one-segment document is not a fragment, and must not be reviewed as one:
101
+ * the fragment prompt stops counting a missing beginning or end as an
102
+ * omission, and on a page that *is* the segment those are the omissions.
103
+ * Half of this corpus is a single segment, and there the segment reviewer is
104
+ * the only blocking semantic check there is.
105
+ */
106
+ const fragment = plan.segments.length > 1;
107
+ /**
108
+ * The page's headings, with the segment's own section marked.
109
+ *
110
+ * Rendered per segment rather than once: the list is the same, but the mark
111
+ * is what makes it useful — the prompt tells the model this is "so you know
112
+ * where the segment sits", and an unmarked list does not say that.
113
+ */
114
+ const headings = documentOutline(tree);
115
+ const outlines = new Map();
116
+ const outlineFor = (segment) => {
117
+ let rendered = outlines.get(segment.index);
118
+ if (rendered == null) {
119
+ rendered = renderOutline(headings, segment.label.headingLine);
120
+ outlines.set(segment.index, rendered);
121
+ }
122
+ return rendered;
123
+ };
124
+ /** The accepted translation of each segment. Only ever written on a pass. */
125
+ const frozen = [];
126
+ /** The least-bad rejected attempt, for a repairer to start from. */
127
+ const best = [];
128
+ const outcomes = plan.segments.map((segment) => ({
129
+ index: segment.index,
130
+ status: 'failed',
131
+ label: segment.label,
132
+ attempts: 0,
133
+ history: [],
134
+ findings: [],
135
+ }));
136
+ /**
137
+ * The non-blocking notes each segment came back with, by segment.
138
+ *
139
+ * Kept per segment and replaced rather than appended to, because a segment
140
+ * can be worked on more than once — a later assembly round can send it back
141
+ * — and a note from the attempt that was superseded is not a note about the
142
+ * document that shipped. Appending printed the same readability remark twice
143
+ * for every segment that was ever revisited.
144
+ */
145
+ const advisoryBySegment = [];
146
+ /** Notes about the assembled page, which belong to no segment. */
147
+ const documentAdvisory = [];
148
+ const advisory = () => [...advisoryBySegment.flat(), ...documentAdvisory];
149
+ const previousTail = (segment) => {
150
+ if (contextTail === 0) {
151
+ return undefined;
152
+ }
153
+ const before = frozen[segment.index - 1];
154
+ return before == null ? undefined : tailOf(before, contextTail);
155
+ };
156
+ /**
157
+ * One pass at a segment: ask, check, and freeze only on a pass.
158
+ *
159
+ * The ratchet lives in this function and nowhere else — `frozen` is assigned
160
+ * exactly once here, on the branch where nothing blocks. Every other outcome
161
+ * leaves whatever was already accepted alone, which is what makes "the
162
+ * document uses the version of each segment that passed" true by
163
+ * construction rather than by care.
164
+ */
165
+ const workOn = async (segment, sentBack) => {
166
+ const outcome = outcomes[segment.index];
167
+ let retry = sentBack?.length
168
+ ? { previous: frozen[segment.index] ?? '', findings: sentBack }
169
+ : undefined;
170
+ for (let attempt = 1; attempt <= maxSegmentAttempts; attempt++) {
171
+ outcome.attempts++;
172
+ const translation = await translator.translate({
173
+ segment,
174
+ outline: outlineFor(segment),
175
+ previousTail: previousTail(segment),
176
+ attempt,
177
+ retry,
178
+ });
179
+ const findings = await checkSegment({
180
+ segment,
181
+ translation,
182
+ processor,
183
+ documentTokens,
184
+ judge: segmentJudge,
185
+ fragment,
186
+ sourceLanguage,
187
+ targetLanguage,
188
+ terms,
189
+ });
190
+ const blocking = blockingFindings(findings);
191
+ if (blocking.length === 0) {
192
+ frozen[segment.index] = translation;
193
+ outcome.status = 'translated';
194
+ outcome.findings = [];
195
+ advisoryBySegment[segment.index] = findings;
196
+ return true;
197
+ }
198
+ outcome.history.push(findings);
199
+ const previousBest = best[segment.index];
200
+ if (!previousBest || blocking.length < previousBest.blocking) {
201
+ best[segment.index] = { text: translation, blocking: blocking.length };
202
+ }
203
+ retry = { previous: translation, findings };
204
+ onProgress?.(`${sourceLabel} [segment ${segment.index + 1}/${plan.segments.length}${describe(segment)}] attempt ${attempt} rejected: ${summarise(blocking)}`);
205
+ }
206
+ if (repairer) {
207
+ const draft = best[segment.index]?.text ?? '';
208
+ onProgress?.(`${sourceLabel} [segment ${segment.index + 1}/${plan.segments.length}${describe(segment)}] escalating to the repair agent`);
209
+ const repaired = await repairer.repair({
210
+ segment,
211
+ draft,
212
+ history: outcome.history,
213
+ check: (translation) => checkSegment({
214
+ segment,
215
+ translation,
216
+ processor,
217
+ documentTokens,
218
+ judge: segmentJudge,
219
+ fragment,
220
+ sourceLanguage,
221
+ targetLanguage,
222
+ terms,
223
+ }),
224
+ });
225
+ if (repaired != null) {
226
+ const findings = await checkSegment({
227
+ segment,
228
+ translation: repaired,
229
+ processor,
230
+ documentTokens,
231
+ judge: segmentJudge,
232
+ fragment,
233
+ sourceLanguage,
234
+ targetLanguage,
235
+ terms,
236
+ });
237
+ if (blockingFindings(findings).length === 0) {
238
+ frozen[segment.index] = repaired;
239
+ outcome.status = 'repaired';
240
+ outcome.findings = [];
241
+ advisoryBySegment[segment.index] = findings;
242
+ onProgress?.(`${sourceLabel} [segment ${segment.index + 1}/${plan.segments.length}${describe(segment)}] repaired`);
243
+ return true;
244
+ }
245
+ outcome.history.push(findings);
246
+ }
247
+ }
248
+ // Nothing passed. Whatever was frozen before — from an earlier round —
249
+ // stays frozen: a failed attempt never costs a segment its best accepted
250
+ // version.
251
+ outcome.findings = outcome.history.at(-1) ?? [];
252
+ if (frozen[segment.index] == null) {
253
+ outcome.status = 'failed';
254
+ return false;
255
+ }
256
+ return true;
257
+ };
258
+ // ------------------------------------------------ every segment, in order
259
+ for (const segment of plan.segments) {
260
+ const reused = reuse.get(segment.index);
261
+ if (reused != null) {
262
+ frozen[segment.index] = reused;
263
+ outcomes[segment.index].status = 'cached';
264
+ continue;
265
+ }
266
+ await workOn(segment);
267
+ }
268
+ if (reuse.size > 0) {
269
+ onProgress?.(`${sourceLabel}: reused ${reuse.size} of ${plan.segments.length} segment(s) from the previous translation`);
270
+ }
271
+ const unfinished = plan.segments.filter((segment) => frozen[segment.index] == null);
272
+ if (unfinished.length > 0) {
273
+ for (const segment of unfinished) {
274
+ onProgress?.(`${sourceLabel} [segment ${segment.index + 1}/${plan.segments.length}${describe(segment)}] gave up after ${outcomes[segment.index].attempts} attempt(s)`);
275
+ }
276
+ return {
277
+ findings: unfinished.flatMap((segment) => outcomes[segment.index].findings),
278
+ failure: {
279
+ kind: 'segment',
280
+ segments: unfinished.map((segment) => segment.index),
281
+ },
282
+ outcomes,
283
+ assemblyRounds: 0,
284
+ };
285
+ }
286
+ // ------------------------------------------------------------- assembling
287
+ let assemblyRounds = 0;
288
+ for (;;) {
289
+ const assembled = assemble({
290
+ tree,
291
+ plan,
292
+ processor,
293
+ translations: frozen,
294
+ });
295
+ let restored;
296
+ let findings = [];
297
+ try {
298
+ restored = restoreMaskedContent(assembled.text, maskEntries, processor);
299
+ }
300
+ catch (error) {
301
+ if (!(error instanceof MaskIntegrityError)) {
302
+ throw error;
303
+ }
304
+ findings = error.findings.map(maskFindingToTranslationFinding);
305
+ }
306
+ const document = restored == null
307
+ ? undefined
308
+ : compose(restored, encodeCacheRecord(plan, assembled.records));
309
+ if (document != null) {
310
+ findings = await checker.check(targetPath, document);
311
+ }
312
+ const blocking = blockingFindings(findings);
313
+ if (blocking.length === 0 && document != null) {
314
+ if (documentJudge && plan.segments.length > 1) {
315
+ // Advisory, always: this reads the whole page for the things a segment
316
+ // cannot see — a term that drifted between sections, a join that reads
317
+ // badly — and those are worth telling someone about and not worth
318
+ // failing a build over. A page that is one segment has already been
319
+ // read by exactly this check, so it is not read twice.
320
+ const whole = await documentJudge.review({
321
+ sourceText: maskedSource,
322
+ translationText: assembled.text,
323
+ sourceLanguage,
324
+ targetLanguage,
325
+ terms,
326
+ });
327
+ documentAdvisory.push(...whole.map((finding) => ({ ...finding, blocking: false })));
328
+ }
329
+ return {
330
+ document,
331
+ findings: [...findings, ...advisory()],
332
+ outcomes,
333
+ assemblyRounds,
334
+ records: assembled.records,
335
+ };
336
+ }
337
+ if (assemblyRounds >= maxAssemblyRounds) {
338
+ return {
339
+ findings: [...blocking, ...advisory()],
340
+ failure: { kind: 'assembly' },
341
+ outcomes,
342
+ assemblyRounds,
343
+ };
344
+ }
345
+ const routed = route({
346
+ findings: blocking,
347
+ plan,
348
+ placements: assembled.placements,
349
+ document,
350
+ processor,
351
+ });
352
+ if (routed.size === 0) {
353
+ // Deliberately not "redo every segment": that is the whole-document blast
354
+ // radius this design exists to remove. A finding nobody can attribute is
355
+ // reported as it is, which is already an order of magnitude better than
356
+ // the 873 undifferentiated problems this replaced.
357
+ return {
358
+ findings: [...blocking, ...advisory()],
359
+ failure: { kind: 'unlocatable' },
360
+ outcomes,
361
+ assemblyRounds,
362
+ };
363
+ }
364
+ assemblyRounds++;
365
+ for (const [index, sentBack] of routed) {
366
+ const segment = plan.segments[index];
367
+ onProgress?.(`${sourceLabel} [segment ${index + 1}/${plan.segments.length}${describe(segment)}] sent back by the assembled document: ${summarise(sentBack)}`);
368
+ await workOn(segment, sentBack);
369
+ }
370
+ }
371
+ };
372
+ const describe = (segment) => segment.label.heading ? ` ‹${segment.label.heading}›` : '';
373
+ const summarise = (findings) => findings
374
+ .slice(0, 3)
375
+ .map((finding) => finding.rule)
376
+ .join(', ') + (findings.length > 3 ? `, +${findings.length - 3} more` : '');
377
+ /**
378
+ * Rules that compare the translation with its source across the whole tree.
379
+ *
380
+ * Every one of them reports on the root node, so `line` is 1 no matter where
381
+ * the defect is. Treating that 1 as a location is how a page without
382
+ * frontmatter used to send its first segment back for something that segment
383
+ * had nothing to do with.
384
+ */
385
+ const PAIRWISE_RULE_PREFIX = 'doom-lint:translation-';
386
+ /**
387
+ * Which segment each whole-document finding belongs to.
388
+ *
389
+ * Two routes, because the findings arrive in two shapes:
390
+ *
391
+ * - **a placeholder** names its segments exactly — the token belongs to those
392
+ * segments' tables and no others. This is the important one: it covers every
393
+ * way the masked round trip can fail. Reference and footnote labels
394
+ * (`REFID`/`FNID`) are shared linkage keys, so a definition and its uses can
395
+ * sit in different segments; all of them are asked again, because which one
396
+ * dropped the label is exactly what the finding does not say;
397
+ * - **a line number** is looked up in the composed document, whose block
398
+ * structure is the one assembly recorded. When several segments' spans
399
+ * contain the line — a drilled container's tag segment covers every line of
400
+ * its children — the **narrowest** one is the owner. A child is always
401
+ * narrower than the container it sits in.
402
+ *
403
+ * The pairwise rules — `translation-component-multiset`,
404
+ * `translation-heading-sequence` and the rest — report against the document as
405
+ * a whole and always land on line 1, which is not a location: on a page with
406
+ * frontmatter that line belongs to nobody, and on a page without one it belongs
407
+ * to the first segment by accident. So they are recognised by name and never
408
+ * routed by line, which is what makes the same defect fail the same way on both
409
+ * kinds of page. That is also why the same comparisons are made per segment
410
+ * during acceptance, where they arrive with a segment attached. One of them
411
+ * firing *here*, after every segment passed the same comparison, means assembly
412
+ * itself did something — and that is worth failing loudly for rather than
413
+ * retrying blindly.
414
+ */
415
+ const route = ({ findings, plan, placements, document, processor, }) => {
416
+ const routed = new Map();
417
+ const add = (index, finding) => {
418
+ const list = routed.get(index);
419
+ if (list) {
420
+ list.push(finding);
421
+ }
422
+ else {
423
+ routed.set(index, [finding]);
424
+ }
425
+ };
426
+ const byPlaceholder = new Map();
427
+ for (const segment of plan.segments) {
428
+ for (const token of segment.expected.keys()) {
429
+ const owners = byPlaceholder.get(token);
430
+ if (owners) {
431
+ owners.push(segment.index);
432
+ }
433
+ else {
434
+ byPlaceholder.set(token, [segment.index]);
435
+ }
436
+ }
437
+ }
438
+ const spans = document ? lineSpans(document, placements, processor) : [];
439
+ for (const finding of findings) {
440
+ const token = finding.placeholder?.toLowerCase();
441
+ const owners = token ? byPlaceholder.get(token) : undefined;
442
+ if (owners?.length) {
443
+ for (const owner of owners) {
444
+ add(owner, finding);
445
+ }
446
+ continue;
447
+ }
448
+ if (finding.line == null ||
449
+ finding.line <= 0 ||
450
+ finding.rule.startsWith(PAIRWISE_RULE_PREFIX)) {
451
+ continue;
452
+ }
453
+ const line = finding.line;
454
+ let owner;
455
+ for (const span of spans) {
456
+ if (line < span.start || line > span.end) {
457
+ continue;
458
+ }
459
+ if (!owner || span.end - span.start < owner.end - owner.start) {
460
+ owner = span;
461
+ }
462
+ }
463
+ if (owner) {
464
+ add(owner.segment, finding);
465
+ }
466
+ }
467
+ return routed;
468
+ };
469
+ /** Which lines of the composed document each segment occupies. */
470
+ const lineSpans = (document, placements, processor) => {
471
+ let tree;
472
+ try {
473
+ tree = processor.parse(document);
474
+ }
475
+ catch {
476
+ return [];
477
+ }
478
+ const shift = tree.children[0]?.type === 'yaml' ? 1 : 0;
479
+ const spans = [];
480
+ for (const { segment, address } of placements) {
481
+ if (address.kind === 'attributes') {
482
+ const node = resolveAttributeNode(tree, address, shift);
483
+ const position = node?.position;
484
+ if (position) {
485
+ spans.push({
486
+ segment,
487
+ start: position.start.line,
488
+ end: position.end.line,
489
+ });
490
+ }
491
+ continue;
492
+ }
493
+ const resolved = resolvePlacement(tree, address, shift);
494
+ const first = resolved?.nodes.at(0)?.position?.start.line;
495
+ const last = resolved?.nodes.at(-1)?.position?.end.line;
496
+ if (first != null && last != null) {
497
+ spans.push({ segment, start: first, end: last });
498
+ }
499
+ }
500
+ return spans;
501
+ };