@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,301 @@
1
+ import { isTranslatableJsxAttr } from "../runtime/components/_translation-policy.js";
2
+ import { countPlaceholders, maskAst, } from "./translate-mask.js";
3
+ import { definitionContext, parseWithDefinitions, resolveAttributeNode, resolvePlacement, } from "./translate-segment.js";
4
+ /**
5
+ * One record, as one short string.
6
+ *
7
+ * `<sha> <start>-<end>` at the top level, `<sha> <path>/<start>-<end>` inside a
8
+ * container, `<sha> <path>:attrs` for a tag's own words. Compact because it
9
+ * lives in every translated document's frontmatter, and readable because the
10
+ * first thing anyone does with an unexpected diff is read it.
11
+ */
12
+ export const encodeRecord = ({ sha, address }) => {
13
+ const container = address.container.join('/');
14
+ if (address.kind === 'attributes') {
15
+ return `${sha} ${container}:attrs`;
16
+ }
17
+ const range = `${address.start}-${address.end}`;
18
+ return `${sha} ${container ? `${container}/${range}` : range}`;
19
+ };
20
+ export const decodeRecord = (entry) => {
21
+ const [sha, locator] = entry.trim().split(/\s+/u);
22
+ if (!sha || !locator || !/^[0-9a-f]{12}$/u.test(sha)) {
23
+ return undefined;
24
+ }
25
+ if (locator.endsWith(':attrs')) {
26
+ const path = locator.slice(0, -':attrs'.length);
27
+ const container = parsePath(path);
28
+ return container && container.length > 0
29
+ ? { sha, address: { kind: 'attributes', container } }
30
+ : undefined;
31
+ }
32
+ const cut = locator.lastIndexOf('/');
33
+ const path = cut < 0 ? '' : locator.slice(0, cut);
34
+ const range = cut < 0 ? locator : locator.slice(cut + 1);
35
+ const match = /^(\d+)-(\d+)$/u.exec(range);
36
+ const container = parsePath(path);
37
+ if (!match || !container) {
38
+ return undefined;
39
+ }
40
+ const start = Number(match[1]);
41
+ const end = Number(match[2]);
42
+ return end < start
43
+ ? undefined
44
+ : { sha, address: { kind: 'blocks', container, start, end } };
45
+ };
46
+ const parsePath = (path) => {
47
+ if (path === '') {
48
+ return [];
49
+ }
50
+ const parts = path.split('/').map(Number);
51
+ return parts.every((part) => Number.isInteger(part) && part >= 0)
52
+ ? parts
53
+ : undefined;
54
+ };
55
+ export const encodeCacheRecord = (plan, records) => records.length === 0
56
+ ? undefined
57
+ : { v: plan.version, cap: plan.cap, segs: records.map(encodeRecord) };
58
+ /**
59
+ * Which of this document's segments can be taken from the previous translation.
60
+ *
61
+ * The two hash sequences are matched with a longest-common-subsequence, so a
62
+ * segment inserted in the middle of a page shifts nothing after it and two
63
+ * identical segments cannot swap places. Every match is then verified, and only
64
+ * what survives is offered.
65
+ */
66
+ export const matchCachedSegments = ({ plan, maskEntries, processor, record, previousBody, }) => {
67
+ const reuse = new Map();
68
+ if (!record) {
69
+ return { reuse, reason: 'the previous translation has no segment record' };
70
+ }
71
+ if (record.v !== plan.version) {
72
+ return {
73
+ reuse,
74
+ reason: `the previous translation was cut by segmenter v${record.v}, this run is v${plan.version}`,
75
+ };
76
+ }
77
+ if (record.cap !== plan.cap) {
78
+ return {
79
+ reuse,
80
+ reason: `the previous translation was cut at ${record.cap} characters, this run cuts at ${plan.cap}`,
81
+ };
82
+ }
83
+ const previousRecords = record.segs
84
+ .map(decodeRecord)
85
+ .filter((entry) => !!entry);
86
+ if (previousRecords.length !== record.segs.length) {
87
+ return { reuse, reason: 'the previous segment record is malformed' };
88
+ }
89
+ let tree;
90
+ try {
91
+ tree = processor.parse(previousBody);
92
+ }
93
+ catch {
94
+ return { reuse, reason: 'the previous translation does not parse' };
95
+ }
96
+ const entriesByToken = new Map(maskEntries.map((entry) => [entry.placeholder.toLowerCase(), entry]));
97
+ // Computed once for the document, not once per segment: it walks the whole
98
+ // previous translation, and every segment is asked about the same one.
99
+ const context = definitionContext(tree, processor);
100
+ for (const [index, previousIndex] of alignBySha(plan.segments.map((segment) => segment.sha), previousRecords.map((entry) => entry.sha))) {
101
+ const segment = plan.segments[index];
102
+ const candidate = extract({
103
+ tree,
104
+ address: previousRecords[previousIndex].address,
105
+ processor,
106
+ context,
107
+ });
108
+ if (candidate == null) {
109
+ continue;
110
+ }
111
+ const remasked = remask({
112
+ candidate,
113
+ segment,
114
+ entriesByToken,
115
+ processor,
116
+ });
117
+ if (remasked != null) {
118
+ reuse.set(index, remasked);
119
+ }
120
+ }
121
+ return { reuse };
122
+ };
123
+ /**
124
+ * The longest run of segments, in order, whose hashes agree.
125
+ *
126
+ * A plain two-pointer walk loses alignment for the rest of the page the moment
127
+ * one segment is inserted or removed. This is the standard subsequence instead:
128
+ * pairs never cross, so two identical segments cannot be matched to each
129
+ * other's positions, and an edit only costs the segment it touched.
130
+ */
131
+ export const alignBySha = (current, previous) => {
132
+ const rows = current.length;
133
+ const columns = previous.length;
134
+ const lengths = Array.from({ length: rows + 1 }, () => Array.from({ length: columns + 1 }, () => 0));
135
+ for (let row = rows - 1; row >= 0; row--) {
136
+ for (let column = columns - 1; column >= 0; column--) {
137
+ lengths[row][column] =
138
+ current[row] === previous[column]
139
+ ? lengths[row + 1][column + 1] + 1
140
+ : Math.max(lengths[row + 1][column], lengths[row][column + 1]);
141
+ }
142
+ }
143
+ const pairs = [];
144
+ let row = 0;
145
+ let column = 0;
146
+ while (row < rows && column < columns) {
147
+ if (current[row] === previous[column]) {
148
+ pairs.push([row, column]);
149
+ row++;
150
+ column++;
151
+ }
152
+ else if (lengths[row + 1][column] >= lengths[row][column + 1]) {
153
+ row++;
154
+ }
155
+ else {
156
+ column++;
157
+ }
158
+ }
159
+ return pairs;
160
+ };
161
+ /** The previous translation of one segment, as it sits on disk: restored, not masked. */
162
+ const extract = ({ tree, address, processor, context, }) => {
163
+ if (address.kind === 'attributes') {
164
+ const node = resolveAttributeNode(tree, address);
165
+ if (!node) {
166
+ return undefined;
167
+ }
168
+ const attrs = node.attributes.filter((attr) => attr.type === 'mdxJsxAttribute' &&
169
+ typeof attr.value === 'string' &&
170
+ isTranslatableJsxAttr(node.name, attr.name));
171
+ return attrs.length === 0
172
+ ? undefined
173
+ : {
174
+ type: 'root',
175
+ children: [
176
+ {
177
+ type: 'mdxJsxFlowElement',
178
+ name: node.name,
179
+ attributes: attrs.map((attr) => ({ ...attr })),
180
+ children: [],
181
+ },
182
+ ],
183
+ };
184
+ }
185
+ const resolved = resolvePlacement(tree, address);
186
+ if (!resolved) {
187
+ return undefined;
188
+ }
189
+ // Re-parsed rather than reused: masking mutates, and the tree these nodes
190
+ // came from is the caller's.
191
+ try {
192
+ return {
193
+ type: 'root',
194
+ children: parseWithDefinitions(processor.stringify({ type: 'root', children: resolved.nodes }), context, processor),
195
+ };
196
+ }
197
+ catch {
198
+ return undefined;
199
+ }
200
+ };
201
+ /**
202
+ * Puts this document's placeholders back into a translation that has none.
203
+ *
204
+ * The candidate is masked with {@link maskAst}, which numbers from zero for
205
+ * whatever it is given; those numbers mean nothing here. What does mean
206
+ * something is *what* was masked, so each candidate entry is matched to a
207
+ * segment entry of the same kind holding the same value, and the candidate's
208
+ * tokens are rewritten accordingly — in one pass, so a token that is both a
209
+ * source and a target of the rewrite cannot be replaced twice.
210
+ *
211
+ * Anything that does not line up exactly returns nothing, and the segment is
212
+ * translated again. That covers a hand-edited translation, a stale record, a
213
+ * link somebody fixed by hand in the target language — every way a cache entry
214
+ * can be quietly wrong.
215
+ */
216
+ const remask = ({ candidate, segment, entriesByToken, processor, }) => {
217
+ const wanted = [...segment.expected.keys()]
218
+ .map((token) => entriesByToken.get(token))
219
+ .filter((entry) => !!entry);
220
+ if (wanted.length !== segment.expected.size) {
221
+ return undefined;
222
+ }
223
+ let candidateEntries;
224
+ let masked;
225
+ try {
226
+ candidateEntries = maskAst(candidate);
227
+ masked = processor.stringify(candidate);
228
+ }
229
+ catch {
230
+ // Includes the case where the previous translation already contains a
231
+ // reserved token, which is not something to paper over.
232
+ return undefined;
233
+ }
234
+ const available = new Map();
235
+ for (const entry of wanted) {
236
+ const key = valueKey(entry);
237
+ const list = available.get(key);
238
+ if (list) {
239
+ list.push(entry.placeholder);
240
+ }
241
+ else {
242
+ available.set(key, [entry.placeholder]);
243
+ }
244
+ }
245
+ const rewrite = new Map();
246
+ for (const entry of candidateEntries) {
247
+ const list = available.get(valueKey(entry));
248
+ const replacement = list?.shift();
249
+ if (!replacement) {
250
+ // The translation holds something this segment's source does not — it has
251
+ // been edited, or the record points somewhere else entirely.
252
+ return undefined;
253
+ }
254
+ rewrite.set(entry.placeholder.toLowerCase(), replacement);
255
+ }
256
+ for (const list of available.values()) {
257
+ if (list.length > 0) {
258
+ return undefined;
259
+ }
260
+ }
261
+ const remasked = masked.replace(/__DOOM_TR_[A-Z]+_\d+__/giu, (token) => {
262
+ return rewrite.get(token.toLowerCase()) ?? token;
263
+ });
264
+ // The last word is the same measurement the segment check would make.
265
+ const counts = countPlaceholders(remasked);
266
+ if (counts.size !== segment.expected.size) {
267
+ return undefined;
268
+ }
269
+ for (const [token, expected] of segment.expected) {
270
+ if (counts.get(token) !== expected) {
271
+ return undefined;
272
+ }
273
+ }
274
+ return remasked;
275
+ };
276
+ /** What a mask entry actually protects, as a comparable string. */
277
+ const valueKey = (entry) => {
278
+ switch (entry.kind) {
279
+ case 'DEF':
280
+ case 'IMG':
281
+ case 'LINK': {
282
+ return `${entry.kind}\0${entry.url}`;
283
+ }
284
+ case 'FNID':
285
+ case 'REFID': {
286
+ return `${entry.kind}\0${entry.identifier.toLowerCase()}`;
287
+ }
288
+ case 'CODE': {
289
+ return `CODE\0${entry.node.lang ?? ''}\0${entry.node.meta ?? ''}\0${entry.node.value}`;
290
+ }
291
+ case 'URL': {
292
+ return `URL\0${entry.node.url}`;
293
+ }
294
+ case 'JSXATTR': {
295
+ return `JSXATTR\0${entry.attrKind}\0${typeof entry.value === 'string' ? entry.value : entry.value.value}`;
296
+ }
297
+ default: {
298
+ return `${entry.kind}\0${entry.value}`;
299
+ }
300
+ }
301
+ };
@@ -0,0 +1,42 @@
1
+ import type { TranslationFinding } from './translate-checker.ts';
2
+ import type { Judge } from './translate-judge.ts';
3
+ import { type MaskProcessor } from './translate-mask.ts';
4
+ import { type Segment } from './translate-segment.ts';
5
+ import type { TermPair } from './translate-terms.ts';
6
+ export interface CheckSegmentOptions {
7
+ segment: Segment;
8
+ /** What the model returned for it. */
9
+ translation: string;
10
+ processor: MaskProcessor;
11
+ /**
12
+ * Every placeholder the document issued.
13
+ *
14
+ * Lets a token that belongs to a *different* segment be reported as what it
15
+ * is — content dragged in from a neighbour — rather than as an invented one.
16
+ * The two have different causes and different fixes.
17
+ */
18
+ documentTokens?: ReadonlySet<string>;
19
+ /** The semantic check. Absent in tests that are about control flow. */
20
+ judge?: Judge;
21
+ /**
22
+ * Whether this segment is one piece of a longer page.
23
+ *
24
+ * It decides which prompt the reviewer gets, and the two differ in what
25
+ * counts as an omission: a fragment has no beginning and no end, so a missing
26
+ * introduction or a section that runs past the cut is a property of the cut
27
+ * rather than of the translation, and the fragment prompt says so.
28
+ *
29
+ * That relaxation is right for a piece and wrong for a whole page. Half of
30
+ * this corpus is one segment, and on those pages the segment reviewer is the
31
+ * *only* blocking semantic check there is — the whole-page one is advisory
32
+ * and is not even asked when there is a single segment, because it would be
33
+ * reading the same text twice. Telling it "this is a fragment" there would
34
+ * quietly excuse exactly the defect it exists to catch: a how-to whose last
35
+ * section, "what to do next", never made it into the translation.
36
+ */
37
+ fragment?: boolean;
38
+ sourceLanguage: string;
39
+ targetLanguage: string;
40
+ terms?: readonly TermPair[];
41
+ }
42
+ export declare const checkSegment: ({ segment, translation, processor, documentTokens, judge, fragment, sourceLanguage, targetLanguage, terms, }: CheckSegmentOptions) => Promise<TranslationFinding[]>;
@@ -0,0 +1,288 @@
1
+ import { visit } from 'unist-util-visit';
2
+ import { explainUnparsedEmphasis, findUnparsedEmphasis, } from "../remark-lint/no-unparsed-emphasis.js";
3
+ import { collectComponents, collectHeadingDepths, } from "../remark-lint/translation-parity/shared.js";
4
+ import { countPlaceholders } from "./translate-mask.js";
5
+ import { parseAttributeElement } from "./translate-segment.js";
6
+ /**
7
+ * Whether one translated segment is good enough to freeze.
8
+ *
9
+ * This is the gate the whole design rests on. A segment that passes here is
10
+ * never touched again — not by a retry, not by a repair agent, not by a later
11
+ * assembly round — so everything that was right stays right. The incident this
12
+ * replaced had no such gate: a document one problem away from finished was
13
+ * handed back to a model that rewrote it whole, and 870 correct placeholders
14
+ * became 1000 problems with no way back.
15
+ *
16
+ * Four layers, cheapest first, and a failing layer stops the ones after it.
17
+ * Three of the four are free; only the last one costs a model call, and it is
18
+ * not spent on a segment the free ones have already faulted.
19
+ *
20
+ * The same function is what a repair agent calls to see its own work, so "the
21
+ * agent is checked against the rules it checks itself with" is true because
22
+ * there is one function, not because two of them were kept in step.
23
+ */
24
+ /** How much of a mismatched segment to quote back. Enough to act on, not enough to drown in. */
25
+ const PREVIEW = 80;
26
+ const preview = (value) => value.length > PREVIEW ? `${value.slice(0, PREVIEW - 1)}…` : value;
27
+ export const checkSegment = async ({ segment, translation, processor, documentTokens, judge, fragment = false, sourceLanguage, targetLanguage, terms, }) => {
28
+ if (translation.trim() === '') {
29
+ return [
30
+ {
31
+ rule: 'doom-translate:nothing-written',
32
+ reason: 'The model returned nothing for this segment.',
33
+ },
34
+ ];
35
+ }
36
+ // ------------------------------------------------------------ 1. it parses
37
+ if (segment.address.kind === 'attributes') {
38
+ return checkAttributes(segment, translation, processor);
39
+ }
40
+ let tree;
41
+ try {
42
+ tree = processor.parse(translation);
43
+ }
44
+ catch (error) {
45
+ return [
46
+ {
47
+ rule: 'doom-translate:segment-unparseable',
48
+ reason: `This segment's translation is not valid markdown/MDX: ${error instanceof Error ? error.message : String(error)}`,
49
+ },
50
+ ];
51
+ }
52
+ // --------------------------------------------------- 2. the placeholders
53
+ const findings = placeholderFindings(segment, translation, documentTokens);
54
+ if (findings.length > 0) {
55
+ return findings;
56
+ }
57
+ // ----------------------------------------------------- 3. the structure
58
+ findings.push(...structureFindings(segment, tree, processor));
59
+ if (findings.length > 0) {
60
+ return findings;
61
+ }
62
+ // --------------------------------------------------------- 4. the meaning
63
+ if (judge) {
64
+ findings.push(...(await judge.review({
65
+ // The masked pair, as everywhere else: a finding that quoted an
66
+ // unmasked link target would put that target back in the model's reach,
67
+ // which is the one thing masking exists to prevent.
68
+ sourceText: segment.text,
69
+ translationText: translation,
70
+ sourceLanguage,
71
+ targetLanguage,
72
+ terms,
73
+ fragment,
74
+ })));
75
+ }
76
+ return findings;
77
+ };
78
+ /**
79
+ * Every placeholder back, exactly as often as it went out.
80
+ *
81
+ * Pure string counting — no restore, no tree walk, nothing to configure — which
82
+ * is why it can run on every attempt of every segment without thinking about
83
+ * cost. It is also where the failure that ended the incident is now caught: in
84
+ * a few kilobytes, against a table of a few dozen tokens, instead of in 78 KB
85
+ * against 871.
86
+ */
87
+ const placeholderFindings = (segment, translation, documentTokens) => {
88
+ const found = countPlaceholders(translation);
89
+ const findings = [];
90
+ for (const [token, expected] of segment.expected) {
91
+ const actual = found.get(token) ?? 0;
92
+ found.delete(token);
93
+ if (actual === expected) {
94
+ continue;
95
+ }
96
+ findings.push({
97
+ rule: actual < expected
98
+ ? 'doom-translate:missing-placeholder'
99
+ : 'doom-translate:duplicate-placeholder',
100
+ reason: actual < expected
101
+ ? `\`${token.toUpperCase()}\` is not in this segment's translation${expected > 1 ? ` as often as it should be (expected ${expected}, found ${actual})` : ''}. It stands for content you must reproduce exactly — a link target, some code, an identifier. Either it has not been translated yet, or it was dropped.`
102
+ : `\`${token.toUpperCase()}\` appears ${actual} times but must appear ${expected}.`,
103
+ });
104
+ }
105
+ for (const [token, actual] of found) {
106
+ const fromElsewhere = documentTokens?.has(token) ?? false;
107
+ findings.push({
108
+ rule: fromElsewhere
109
+ ? 'doom-translate:out-of-segment-placeholder'
110
+ : 'doom-translate:unregistered-placeholder',
111
+ reason: fromElsewhere
112
+ ? `\`${token.toUpperCase()}\` belongs to a different part of the document and appears here ${actual} time(s). Translate only the segment you were given; do not carry text in from anywhere else.`
113
+ : `\`${token.toUpperCase()}\` was never issued — do not invent placeholders.`,
114
+ });
115
+ }
116
+ return findings;
117
+ };
118
+ const ANCHOR_CARRIER = /^__DOOM_TR_ANCHOR_\d+__$/iu;
119
+ /**
120
+ * The anchor carrier a heading ends with, if it ends with one.
121
+ *
122
+ * `maskAst` puts a heading's `{#id}` into an `inlineCode` carrier appended as
123
+ * the heading's last child, because that is the only place the id exists:
124
+ * `HEADING_ANCHOR_PATTERN` is anchored to the end of the heading, so `{#id}`
125
+ * anywhere else is literal text.
126
+ */
127
+ const trailingAnchor = (heading) => {
128
+ const last = heading.children.at(-1);
129
+ return last?.type === 'inlineCode' && ANCHOR_CARRIER.test(last.value)
130
+ ? last.value
131
+ : undefined;
132
+ };
133
+ const collectTrailingAnchors = (tree) => {
134
+ const anchors = [];
135
+ visit(tree, 'heading', (node) => {
136
+ anchors.push(trailingAnchor(node));
137
+ });
138
+ return anchors;
139
+ };
140
+ /**
141
+ * The skeleton is the source's, not the model's.
142
+ *
143
+ * Headings and components are structure rather than prose: translating a page
144
+ * never changes a heading's level and never adds or removes a component. Both
145
+ * are already checked over the whole document by `translation-heading-sequence`
146
+ * and `translation-component-multiset` — this runs the *same* collectors, one
147
+ * segment at a time.
148
+ *
149
+ * That is not a duplicate of those rules, it is where they become actionable.
150
+ * Every pairwise rule reports against the document as a whole, with no line
151
+ * number to route by, so a finding from one of them at assembly time names a
152
+ * defect but not a place. Checked per segment, the same defect arrives with the
153
+ * segment attached, inside a blast radius of a few kilobytes, and can simply be
154
+ * retranslated. When one of those rules does fire at assembly time afterwards,
155
+ * it means something assembly itself did — which is worth failing loudly for
156
+ * rather than retrying blindly.
157
+ */
158
+ const structureFindings = (segment, tree, processor) => {
159
+ let source;
160
+ try {
161
+ source = processor.parse(segment.text);
162
+ }
163
+ catch {
164
+ // The segment came from a parsed tree, so this cannot normally happen; if
165
+ // it somehow does, it is not the translation's fault.
166
+ return [];
167
+ }
168
+ const findings = [];
169
+ const expectedDepths = collectHeadingDepths(source);
170
+ const actualDepths = collectHeadingDepths(tree);
171
+ if (expectedDepths.length !== actualDepths.length ||
172
+ expectedDepths.some((depth, index) => depth !== actualDepths[index])) {
173
+ findings.push({
174
+ rule: 'doom-translate:segment-heading-sequence',
175
+ reason: `This segment's headings changed: the source is ${expectedDepths.join('-') || '(none)'}, the translation is ${actualDepths.join('-') || '(none)'}. Translate the text of a heading; never its level, and never add or drop one.`,
176
+ });
177
+ }
178
+ const expectedComponents = collectComponents(source);
179
+ const actualComponents = collectComponents(tree);
180
+ for (const name of new Set([
181
+ ...expectedComponents.keys(),
182
+ ...actualComponents.keys(),
183
+ ])) {
184
+ const want = expectedComponents.get(name) ?? 0;
185
+ const got = actualComponents.get(name) ?? 0;
186
+ if (want === got) {
187
+ continue;
188
+ }
189
+ findings.push({
190
+ rule: 'doom-translate:segment-component-multiset',
191
+ reason: got < want
192
+ ? `This segment's translation dropped ${want - got} \`<${name}>\` (the source has ${want}, the translation has ${got}) — content that was in the source is missing.`
193
+ : `This segment's translation invented ${got - want} \`<${name}>\` (the source has ${want}, the translation has ${got}).`,
194
+ });
195
+ }
196
+ // Only meaningful while the headings still correspond one to one; when they
197
+ // do not, the sequence finding above already says so and pairing by index
198
+ // would invent a second, misleading one.
199
+ if (expectedDepths.length === actualDepths.length) {
200
+ const expectedAnchors = collectTrailingAnchors(source);
201
+ const actualAnchors = collectTrailingAnchors(tree);
202
+ expectedAnchors.forEach((placeholder, index) => {
203
+ if (!placeholder || actualAnchors[index] === placeholder) {
204
+ return;
205
+ }
206
+ findings.push({
207
+ rule: 'doom-translate:segment-heading-anchor-moved',
208
+ reason: `This segment's translation moved \`${placeholder}\` out of the end of its heading. A heading's \`{#id}\` is an id only as the last thing in the heading; anywhere else it is literal text, so the heading would render the id as visible punctuation and be given a generated one instead. Word order may change; keep the anchor last.`,
209
+ });
210
+ });
211
+ }
212
+ // Emphasis the translation broke.
213
+ //
214
+ // `**` reaching a text node means the delimiters were printed instead of
215
+ // read, and the usual cause is a target language that does not space the way
216
+ // the source did: `**Note:** text` is bold, and the Chinese it becomes,
217
+ // `**注意:**文本`, is not — the closing run is preceded by punctuation and
218
+ // followed by a letter, which CommonMark refuses to close on. The page then
219
+ // shows the asterisks, and nothing else notices: it parses, every link
220
+ // resolves, every component is present.
221
+ //
222
+ // `no-unparsed-emphasis` already catches this over the whole document. It is
223
+ // here for the same reason the heading and component collectors are (see this
224
+ // function's own note): checked per segment it arrives with the segment
225
+ // attached and can simply be retranslated, with three attempts and a repair
226
+ // agent behind it, instead of sharing the two rounds the assembled page gets.
227
+ //
228
+ // Only what the translation introduced. A source that shows literal asterisks
229
+ // on purpose is the author's business, and its translation should keep them.
230
+ if (!firstUnparsedEmphasis(source)) {
231
+ const broken = firstUnparsedEmphasis(tree);
232
+ if (broken) {
233
+ findings.push({
234
+ rule: 'doom-translate:segment-unparsed-emphasis',
235
+ reason: `${explainUnparsedEmphasis(broken.delimiter, broken.window)} The source segment has none, so this one came from the translation. Put the punctuation outside the emphasis — \`**注意**:文本\` — or leave a space after the closing \`**\`.`,
236
+ });
237
+ }
238
+ }
239
+ return findings;
240
+ };
241
+ /**
242
+ * The first `**` a segment prints instead of reading, if there is one.
243
+ *
244
+ * Masked text, so the `__` half of the rule is off: a masked segment is full of
245
+ * `__DOOM_TR_ICODE_0__`, and `**` never appears inside a placeholder.
246
+ */
247
+ const firstUnparsedEmphasis = (tree) => {
248
+ let found;
249
+ visit(tree, 'text', (node) => {
250
+ found ??= findUnparsedEmphasis(node.value, { maskedText: true });
251
+ });
252
+ return found;
253
+ };
254
+ /**
255
+ * A tag's prose, checked as the tag it has to become.
256
+ *
257
+ * An attribute segment is one JSX element carrying the words on a tag — a
258
+ * `<Tab label>` inside a container too large to send whole. It goes back into
259
+ * the document as attribute values, so what matters is that it is still one
260
+ * element and still has the same attributes; a model that answered with a
261
+ * sentence instead would otherwise leave that label silently untranslated.
262
+ */
263
+ const checkAttributes = (segment, translation, processor) => {
264
+ const expected = parseAttributeElement(segment.text, processor);
265
+ const actual = parseAttributeElement(translation, processor);
266
+ if (!actual) {
267
+ return [
268
+ {
269
+ rule: 'doom-translate:segment-attributes',
270
+ reason: `Answer with the element itself and nothing else, exactly as it was given — \`${preview(segment.text.trim())}\` — translating only the attribute values.`,
271
+ },
272
+ ];
273
+ }
274
+ const names = (element) => element.attributes
275
+ .map((attr) => (attr.type === 'mdxJsxAttribute' ? attr.name : '...'))
276
+ .sort();
277
+ const want = expected ? names(expected) : [];
278
+ const got = names(actual);
279
+ if (actual.name !== expected?.name || want.join() !== got.join()) {
280
+ return [
281
+ {
282
+ rule: 'doom-translate:segment-attributes',
283
+ reason: `The element must stay \`<${expected?.name ?? ''}>\` with the attributes ${want.map((name) => `\`${name}\``).join(', ')}; the translation has \`<${actual.name ?? ''}>\` with ${got.map((name) => `\`${name}\``).join(', ') || '(none)'}. Translate the values, not the names.`,
284
+ },
285
+ ];
286
+ }
287
+ return [];
288
+ };