@alauda/doom 2.5.4 → 2.6.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 (94) hide show
  1. package/lib/cli/api.d.ts +2 -0
  2. package/lib/cli/api.js +147 -0
  3. package/lib/cli/helpers.d.ts +1 -7
  4. package/lib/cli/helpers.js +4 -41
  5. package/lib/cli/index.js +2 -0
  6. package/lib/cli/translate-agent.d.ts +81 -0
  7. package/lib/cli/translate-agent.js +450 -0
  8. package/lib/cli/translate-check.d.ts +17 -0
  9. package/lib/cli/translate-check.js +67 -0
  10. package/lib/cli/translate-checker.d.ts +58 -0
  11. package/lib/cli/translate-checker.js +112 -0
  12. package/lib/cli/translate-judge.d.ts +119 -0
  13. package/lib/cli/translate-judge.js +224 -0
  14. package/lib/cli/translate-limits.d.ts +43 -0
  15. package/lib/cli/translate-limits.js +55 -0
  16. package/lib/cli/translate-mask.d.ts +144 -0
  17. package/lib/cli/translate-mask.js +617 -0
  18. package/lib/cli/translate-models.d.ts +127 -0
  19. package/lib/cli/translate-models.js +189 -0
  20. package/lib/cli/translate-scratch.d.ts +142 -0
  21. package/lib/cli/translate-scratch.js +187 -0
  22. package/lib/cli/translate-terms.d.ts +22 -0
  23. package/lib/cli/translate-terms.js +33 -0
  24. package/lib/cli/translate.d.ts +15 -10
  25. package/lib/cli/translate.js +228 -185
  26. package/lib/eslint.js +22 -3
  27. package/lib/plugins/api/index.js +1 -1
  28. package/lib/plugins/api/types.d.ts +36 -1
  29. package/lib/plugins/global/components.d.ts +16 -0
  30. package/lib/plugins/global/components.js +16 -1
  31. package/lib/remark-lint/index.d.ts +20 -0
  32. package/lib/remark-lint/index.js +40 -0
  33. package/lib/remark-lint/no-unmatched-anchor.d.ts +10 -0
  34. package/lib/remark-lint/no-unmatched-anchor.js +19 -2
  35. package/lib/remark-lint/no-unopened-frontmatter.d.ts +2 -0
  36. package/lib/remark-lint/no-unopened-frontmatter.js +70 -0
  37. package/lib/remark-lint/no-unparsed-emphasis.d.ts +2 -0
  38. package/lib/remark-lint/no-unparsed-emphasis.js +53 -0
  39. package/lib/remark-lint/no-unresolved-api-ref.d.ts +40 -0
  40. package/lib/remark-lint/no-unresolved-api-ref.js +194 -0
  41. package/lib/remark-lint/rule-sets.d.ts +73 -0
  42. package/lib/remark-lint/rule-sets.js +114 -0
  43. package/lib/remark-lint/syntax-plugins.d.ts +32 -0
  44. package/lib/remark-lint/syntax-plugins.js +46 -0
  45. package/lib/remark-lint/translation-parity/component-multiset.d.ts +17 -0
  46. package/lib/remark-lint/translation-parity/component-multiset.js +35 -0
  47. package/lib/remark-lint/translation-parity/echoed-source.d.ts +2 -0
  48. package/lib/remark-lint/translation-parity/echoed-source.js +37 -0
  49. package/lib/remark-lint/translation-parity/frontmatter-preservation.d.ts +2 -0
  50. package/lib/remark-lint/translation-parity/frontmatter-preservation.js +36 -0
  51. package/lib/remark-lint/translation-parity/heading-sequence.d.ts +12 -0
  52. package/lib/remark-lint/translation-parity/heading-sequence.js +25 -0
  53. package/lib/remark-lint/translation-parity/index.d.ts +24 -0
  54. package/lib/remark-lint/translation-parity/index.js +24 -0
  55. package/lib/remark-lint/translation-parity/jsx-attribute-parity.d.ts +14 -0
  56. package/lib/remark-lint/translation-parity/jsx-attribute-parity.js +47 -0
  57. package/lib/remark-lint/translation-parity/length-ratio.d.ts +2 -0
  58. package/lib/remark-lint/translation-parity/length-ratio.js +49 -0
  59. package/lib/remark-lint/translation-parity/link-isomorphism.d.ts +34 -0
  60. package/lib/remark-lint/translation-parity/link-isomorphism.js +81 -0
  61. package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
  62. package/lib/remark-lint/translation-parity/shared.js +286 -0
  63. package/lib/remark-lint/translation-parity/terminology-adherence.d.ts +2 -0
  64. package/lib/remark-lint/translation-parity/terminology-adherence.js +67 -0
  65. package/lib/remark-lint/translation-parity/up-to-date.d.ts +11 -0
  66. package/lib/remark-lint/translation-parity/up-to-date.js +21 -0
  67. package/lib/remark-lint/translation-parity/url-residue.d.ts +3 -0
  68. package/lib/remark-lint/translation-parity/url-residue.js +67 -0
  69. package/lib/remarkrc.d.ts +1 -1
  70. package/lib/remarkrc.js +7 -34
  71. package/lib/runtime/api-paths.d.ts +20 -0
  72. package/lib/runtime/api-paths.js +29 -0
  73. package/lib/runtime/components/K8sAPI.d.ts +14 -1
  74. package/lib/runtime/components/K8sAPI.js +49 -10
  75. package/lib/runtime/components/K8sCrd.d.ts +1 -1
  76. package/lib/runtime/components/K8sPermissionTable.js +10 -5
  77. package/lib/runtime/components/OpenAPIPath.js +19 -2
  78. package/lib/runtime/components/_HeadingTitle.js +24 -6
  79. package/lib/runtime/components/_K8sAPIEndpoints.d.ts +8 -1
  80. package/lib/runtime/components/_K8sAPIEndpoints.js +27 -9
  81. package/lib/runtime/components/_K8sAPISchema.d.ts +9 -1
  82. package/lib/runtime/components/_K8sAPISchema.js +24 -6
  83. package/lib/runtime/components/_translation-policy.d.ts +23 -0
  84. package/lib/runtime/components/_translation-policy.js +32 -0
  85. package/lib/runtime/hooks/useTranslation.d.ts +1 -1
  86. package/lib/runtime/translation.d.ts +68 -0
  87. package/lib/runtime/translation.js +51 -0
  88. package/lib/runtime/utils.d.ts +24 -2
  89. package/lib/runtime/utils.js +87 -5
  90. package/lib/shared/constants.d.ts +9 -0
  91. package/lib/shared/constants.js +14 -0
  92. package/lib/types.d.ts +70 -0
  93. package/lib/utils/helpers.js +8 -2
  94. package/package.json +3 -1
@@ -0,0 +1,617 @@
1
+ import { visit } from 'unist-util-visit';
2
+ import { isTranslatableJsxAttr } from "../runtime/components/_translation-policy.js";
3
+ const PLACEHOLDER_PREFIX = '__DOOM_TR_';
4
+ const placeholderOf = (kind, index) => `${PLACEHOLDER_PREFIX}${kind}_${index}__`;
5
+ /**
6
+ * Matches any placeholder. Case-insensitive on purpose: remark lower-cases
7
+ * reference identifiers when the translated document is parsed back, so
8
+ * `REFID`/`FNID` placeholders return in a different case than they left in.
9
+ */
10
+ const PLACEHOLDER_PATTERN = /__DOOM_TR_[A-Z]+_\d+__/gi;
11
+ /**
12
+ * Matches a placeholder even after markdown has chewed on it.
13
+ *
14
+ * A placeholder that ends up in a prose text position does not survive intact:
15
+ * the leading `__` is strong emphasis, so `__DOOM_TR_LINK_7__` parses into a
16
+ * `strong` node wrapping `DOOM_TR_LINK_7`, and the stringifier escapes it back
17
+ * out as `\_\_DOOM\_TR\_LINK\_7\_\_`. Either way the exact token is gone from
18
+ * the tree — which is why hallucinated placeholders are hunted in the raw
19
+ * response text (with escapes stripped) rather than in the parsed AST.
20
+ */
21
+ const LOOSE_PLACEHOLDER_PATTERN = /_{0,2}DOOM_TR_([A-Z]+)_(\d+)_{0,2}/gi;
22
+ /** Every placeholder-ish token in a raw document, in canonical lower case. */
23
+ const collectLoosePlaceholders = (content) => {
24
+ const tokens = new Set();
25
+ for (const match of content
26
+ .replace(/\\/g, '')
27
+ .matchAll(LOOSE_PLACEHOLDER_PATTERN)) {
28
+ tokens.add(placeholderOf(match[1].toUpperCase(), +match[2]).toLowerCase());
29
+ }
30
+ return tokens;
31
+ };
32
+ const matchesPlaceholder = (value) => {
33
+ PLACEHOLDER_PATTERN.lastIndex = 0;
34
+ return PLACEHOLDER_PATTERN.test(value);
35
+ };
36
+ const isExactPlaceholder = (value) => {
37
+ const trimmed = value.trim();
38
+ PLACEHOLDER_PATTERN.lastIndex = 0;
39
+ const match = PLACEHOLDER_PATTERN.exec(trimmed);
40
+ return match?.[0] === trimmed ? trimmed : undefined;
41
+ };
42
+ const describeFinding = (finding) => {
43
+ const where = finding.placeholder ? ` ${finding.placeholder}` : '';
44
+ switch (finding.code) {
45
+ case 'missing-placeholder':
46
+ return `missing-placeholder${where}: the translation dropped this ${finding.kind} (expected ${finding.expected}, found ${finding.actual})${finding.detail ? ` — ${finding.detail}` : ''}`;
47
+ case 'duplicate-placeholder':
48
+ return `duplicate-placeholder${where}: the translation repeated this ${finding.kind} (expected ${finding.expected}, found ${finding.actual})${finding.detail ? ` — ${finding.detail}` : ''}`;
49
+ case 'unregistered-placeholder':
50
+ return `unregistered-placeholder${where}: the translation invented a placeholder that was never issued`;
51
+ case 'unrestored-placeholder':
52
+ return `unrestored-placeholder${where}: the placeholder ended up in a node kind it was not issued for${finding.detail ? ` — ${finding.detail}` : ''}`;
53
+ case 'unparseable-output':
54
+ return `unparseable-output: ${finding.detail ?? 'unknown parse error'}`;
55
+ case 'source-contains-placeholder':
56
+ return `source-contains-placeholder${where}: the source document already contains a reserved token`;
57
+ }
58
+ };
59
+ /**
60
+ * Raised when the masked round trip does not hold. This is check `A1` of the
61
+ * translation gate: it is not advisory, and it must never be swallowed — a
62
+ * translation that fails it is structurally damaged.
63
+ */
64
+ export class MaskIntegrityError extends Error {
65
+ findings;
66
+ file;
67
+ constructor(findings, file) {
68
+ super(`Translation mask integrity check failed${file ? ` for ${file}` : ''}:\n${findings
69
+ .map((finding) => ` - ${describeFinding(finding)}`)
70
+ .join('\n')}`);
71
+ this.findings = findings;
72
+ this.file = file;
73
+ this.name = 'MaskIntegrityError';
74
+ }
75
+ }
76
+ const isNodeLike = (value) => !!value && typeof value === 'object';
77
+ /**
78
+ * Walks every object in a tree, skipping `position` (source offsets) and `data`
79
+ * (derived, e.g. the estree of an MDX expression — counting it would count the
80
+ * same placeholder twice).
81
+ */
82
+ const walkNodes = (value, onNode) => {
83
+ if (Array.isArray(value)) {
84
+ for (const item of value) {
85
+ walkNodes(item, onNode);
86
+ }
87
+ return;
88
+ }
89
+ if (!isNodeLike(value)) {
90
+ return;
91
+ }
92
+ onNode(value);
93
+ for (const [key, child] of Object.entries(value)) {
94
+ if (key === 'position' || key === 'data') {
95
+ continue;
96
+ }
97
+ if (child && typeof child === 'object') {
98
+ walkNodes(child, onNode);
99
+ }
100
+ }
101
+ };
102
+ /** Counts every placeholder occurrence held in a string field of the tree. */
103
+ const collectPlaceholderCounts = (tree) => {
104
+ const counts = new Map();
105
+ walkNodes(tree, (node) => {
106
+ for (const [key, value] of Object.entries(node)) {
107
+ // `label` is only the raw spelling of `identifier` — remark fills it back
108
+ // in when the document is re-parsed, and counting both would report every
109
+ // reference twice.
110
+ if (key === 'type' || key === 'label' || typeof value !== 'string') {
111
+ continue;
112
+ }
113
+ PLACEHOLDER_PATTERN.lastIndex = 0;
114
+ for (const match of value.matchAll(PLACEHOLDER_PATTERN)) {
115
+ const token = match[0].toLowerCase();
116
+ counts.set(token, (counts.get(token) ?? 0) + 1);
117
+ }
118
+ }
119
+ });
120
+ return counts;
121
+ };
122
+ /**
123
+ * Refuses to mask a document that already speaks the placeholder language.
124
+ *
125
+ * Matching loosely matters here: a reserved token sitting in prose comes back
126
+ * from the model in its markdown-mangled form, which would then be reported as
127
+ * a placeholder the model invented — a false red that no amount of retrying
128
+ * could clear.
129
+ */
130
+ const assertSourceHasNoPlaceholders = (tree) => {
131
+ const found = new Set();
132
+ walkNodes(tree, (node) => {
133
+ for (const [key, value] of Object.entries(node)) {
134
+ if (key === 'type' || typeof value !== 'string') {
135
+ continue;
136
+ }
137
+ for (const token of collectLoosePlaceholders(value)) {
138
+ found.add(token);
139
+ }
140
+ }
141
+ });
142
+ if (found.size > 0) {
143
+ throw new MaskIntegrityError([...found].map((placeholder) => ({
144
+ code: 'source-contains-placeholder',
145
+ placeholder,
146
+ })));
147
+ }
148
+ };
149
+ const AUTOLINK_PREFIXES = ['', 'http://', 'https://', 'mailto:', 'tel:'];
150
+ /**
151
+ * A bare URL in prose. GFM parses `https://…`, `www.…` and `a@b.com` into a
152
+ * `link` whose only child is the URL text itself, so there is nothing in it to
153
+ * translate — masking the node whole also removes the model's habit of
154
+ * rewriting it into `[url](url)`.
155
+ */
156
+ const isAutolinkLiteral = (node) => {
157
+ if (node.children.length !== 1) {
158
+ return false;
159
+ }
160
+ const [child] = node.children;
161
+ if (child.type !== 'text' || !child.value) {
162
+ return false;
163
+ }
164
+ return AUTOLINK_PREFIXES.some((prefix) => node.url === `${prefix}${child.value}`);
165
+ };
166
+ const HEADING_ANCHOR_PATTERN = /\{#[^}\s]+\}\s*$/;
167
+ const HTML_ATTR_PATTERN = /\b(href|src)(\s*=\s*)(["'])(.*?)\3/gi;
168
+ /**
169
+ * Replaces every value a translation model must not author with a placeholder,
170
+ * in place, and returns the table needed to put them back.
171
+ *
172
+ * Masking works on **AST nodes only**. It never pattern-matches inside a prose
173
+ * text node: that is the one way this could swallow content that should have
174
+ * been translated, and it is ruled out structurally rather than by care.
175
+ * Anything only recognisable as a text pattern (a bare domain with no scheme,
176
+ * say) is deliberately left alone and covered by a check instead — a check that
177
+ * misfires costs one finding to review, whereas a mask that misfires hides
178
+ * prose from the reader.
179
+ */
180
+ export const maskAst = (tree) => {
181
+ assertSourceHasNoPlaceholders(tree);
182
+ const entries = [];
183
+ const counters = new Map();
184
+ const nextPlaceholder = (kind) => {
185
+ const index = counters.get(kind) ?? 0;
186
+ counters.set(kind, index + 1);
187
+ return placeholderOf(kind, index);
188
+ };
189
+ const push = (entry) => {
190
+ entries.push(entry);
191
+ return entry.placeholder;
192
+ };
193
+ // Reference and footnote labels are shared linkage keys: the definition and
194
+ // every use must keep matching, so they share one placeholder and record how
195
+ // many times it is expected back.
196
+ const sharedLabels = new Map();
197
+ const shareLabel = (kind, identifier, label) => {
198
+ const key = `${kind}:${identifier.toLowerCase()}`;
199
+ const existing = sharedLabels.get(key);
200
+ if (existing) {
201
+ existing.occurrences++;
202
+ return existing.placeholder;
203
+ }
204
+ const entry = {
205
+ kind,
206
+ placeholder: nextPlaceholder(kind),
207
+ occurrences: 1,
208
+ identifier,
209
+ label,
210
+ };
211
+ sharedLabels.set(key, entry);
212
+ entries.push(entry);
213
+ return entry.placeholder;
214
+ };
215
+ // 1. Heading anchors, before inline code: the anchor is carried by an
216
+ // `inlineCode` node, which must not then be masked again as inline code.
217
+ visit(tree, 'heading', (heading) => {
218
+ const last = heading.children.at(-1);
219
+ if (last?.type !== 'text') {
220
+ return;
221
+ }
222
+ const match = HEADING_ANCHOR_PATTERN.exec(last.value);
223
+ if (!match) {
224
+ return;
225
+ }
226
+ const placeholder = push({
227
+ kind: 'ANCHOR',
228
+ placeholder: placeholderOf('ANCHOR', counters.get('ANCHOR') ?? 0),
229
+ occurrences: 1,
230
+ value: match[0],
231
+ });
232
+ counters.set('ANCHOR', (counters.get('ANCHOR') ?? 0) + 1);
233
+ last.value = last.value.slice(0, match.index);
234
+ const carrier = { type: 'inlineCode', value: placeholder };
235
+ if (last.value === '') {
236
+ heading.children[heading.children.length - 1] = carrier;
237
+ }
238
+ else {
239
+ heading.children.push(carrier);
240
+ }
241
+ });
242
+ // 2. Links: a bare URL is masked whole, a written link keeps its text.
243
+ visit(tree, 'link', (node, index, parent) => {
244
+ if (parent && index != null && isAutolinkLiteral(node)) {
245
+ const placeholder = push({
246
+ kind: 'URL',
247
+ placeholder: nextPlaceholder('URL'),
248
+ occurrences: 1,
249
+ node: { ...node },
250
+ });
251
+ parent.children[index] = { type: 'inlineCode', value: placeholder };
252
+ // Continue after the replacement so the carrier is not masked again.
253
+ return index + 1;
254
+ }
255
+ node.url = push({
256
+ kind: 'LINK',
257
+ placeholder: nextPlaceholder('LINK'),
258
+ occurrences: 1,
259
+ url: node.url,
260
+ });
261
+ });
262
+ visit(tree, 'image', (node) => {
263
+ node.url = push({
264
+ kind: 'IMG',
265
+ placeholder: nextPlaceholder('IMG'),
266
+ occurrences: 1,
267
+ url: node.url,
268
+ });
269
+ });
270
+ // 3. Reference-style links and footnotes.
271
+ visit(tree, 'definition', (node) => {
272
+ node.url = push({
273
+ kind: 'DEF',
274
+ placeholder: nextPlaceholder('DEF'),
275
+ occurrences: 1,
276
+ url: node.url,
277
+ });
278
+ const placeholder = shareLabel('REFID', node.identifier, node.label);
279
+ node.identifier = placeholder;
280
+ // Only the identifier carries the token: setting the label too would put the
281
+ // same placeholder in the tree twice and break the occurrence count.
282
+ delete node.label;
283
+ });
284
+ visit(tree, ['imageReference', 'linkReference'], (node_) => {
285
+ const node = node_;
286
+ const placeholder = shareLabel('REFID', node.identifier, node.label);
287
+ node.identifier = placeholder;
288
+ // Only the identifier carries the token: setting the label too would put the
289
+ // same placeholder in the tree twice and break the occurrence count.
290
+ delete node.label;
291
+ });
292
+ visit(tree, ['footnoteDefinition', 'footnoteReference'], (node_) => {
293
+ const node = node_;
294
+ const placeholder = shareLabel('FNID', node.identifier, node.label);
295
+ node.identifier = placeholder;
296
+ // Only the identifier carries the token: setting the label too would put the
297
+ // same placeholder in the tree twice and break the occurrence count.
298
+ delete node.label;
299
+ });
300
+ // 4. JSX attributes: mask by default, translate only what is declared prose.
301
+ visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node_) => {
302
+ const node = node_;
303
+ for (const attr of node.attributes) {
304
+ if (attr.type === 'mdxJsxExpressionAttribute') {
305
+ const placeholder = push({
306
+ kind: 'JSXATTR',
307
+ placeholder: nextPlaceholder('JSXATTR'),
308
+ occurrences: 1,
309
+ attrKind: 'spread',
310
+ value: attr.value,
311
+ });
312
+ attr.value = placeholder;
313
+ delete attr.data;
314
+ continue;
315
+ }
316
+ if (attr.value == null) {
317
+ // A boolean attribute — `<Foo bar />` — has no value to protect.
318
+ continue;
319
+ }
320
+ if (typeof attr.value === 'string') {
321
+ if (isTranslatableJsxAttr(node.name, attr.name)) {
322
+ continue;
323
+ }
324
+ attr.value = push({
325
+ kind: 'JSXATTR',
326
+ placeholder: nextPlaceholder('JSXATTR'),
327
+ occurrences: 1,
328
+ attrKind: 'string',
329
+ value: attr.value,
330
+ });
331
+ continue;
332
+ }
333
+ const placeholder = push({
334
+ kind: 'JSXATTR',
335
+ placeholder: nextPlaceholder('JSXATTR'),
336
+ occurrences: 1,
337
+ attrKind: 'expression',
338
+ value: attr.value,
339
+ });
340
+ attr.value = {
341
+ type: 'mdxJsxAttributeValueExpression',
342
+ value: placeholder,
343
+ };
344
+ }
345
+ });
346
+ // 5. Raw HTML: the value is markup, not prose, so its `href`/`src` are read
347
+ // with attribute syntax rather than by pattern-matching prose.
348
+ visit(tree, 'html', (node) => {
349
+ node.value = node.value.replace(HTML_ATTR_PATTERN, (_match, name, equals, quote, value) => {
350
+ const placeholder = push({
351
+ kind: 'HTMLATTR',
352
+ placeholder: nextPlaceholder('HTMLATTR'),
353
+ occurrences: 1,
354
+ value,
355
+ });
356
+ return `${name}${equals}${quote}${placeholder}${quote}`;
357
+ });
358
+ });
359
+ // 6. Code. No length floor: a short block is as unsafe to retranslate as a
360
+ // long one, and an over-masked comment stays readable English.
361
+ visit(tree, 'code', (node) => {
362
+ const placeholder = push({
363
+ kind: 'CODE',
364
+ placeholder: nextPlaceholder('CODE'),
365
+ occurrences: 1,
366
+ node: { ...node },
367
+ });
368
+ node.value = placeholder;
369
+ delete node.lang;
370
+ delete node.meta;
371
+ });
372
+ // 7. Inline code, last: the anchor and autolink carriers are inline code too.
373
+ visit(tree, 'inlineCode', (node) => {
374
+ if (matchesPlaceholder(node.value)) {
375
+ return;
376
+ }
377
+ node.value = push({
378
+ kind: 'ICODE',
379
+ placeholder: nextPlaceholder('ICODE'),
380
+ occurrences: 1,
381
+ value: node.value,
382
+ });
383
+ });
384
+ // 8. MDX expressions, including the comments the docs rely on
385
+ // (`{/* cspell:disable-next-line */}` must survive translation).
386
+ visit(tree, ['mdxFlowExpression', 'mdxTextExpression'], (node_) => {
387
+ const node = node_;
388
+ node.value = push({
389
+ kind: 'EXPR',
390
+ placeholder: nextPlaceholder('EXPR'),
391
+ occurrences: 1,
392
+ value: node.value,
393
+ });
394
+ delete node.data;
395
+ });
396
+ return entries;
397
+ };
398
+ const restoreEntries = (tree, entries) => {
399
+ const byPlaceholder = new Map();
400
+ for (const entry of entries) {
401
+ byPlaceholder.set(entry.placeholder.toLowerCase(), entry);
402
+ }
403
+ const lookup = (value, kind) => {
404
+ const token = isExactPlaceholder(value);
405
+ if (!token) {
406
+ return;
407
+ }
408
+ const entry = byPlaceholder.get(token.toLowerCase());
409
+ return entry?.kind === kind ? entry : undefined;
410
+ };
411
+ visit(tree, 'link', (node) => {
412
+ const entry = lookup(node.url, 'LINK');
413
+ if (entry?.kind === 'LINK') {
414
+ node.url = entry.url;
415
+ }
416
+ });
417
+ visit(tree, 'image', (node) => {
418
+ const entry = lookup(node.url, 'IMG');
419
+ if (entry?.kind === 'IMG') {
420
+ node.url = entry.url;
421
+ }
422
+ });
423
+ visit(tree, 'definition', (node) => {
424
+ const urlEntry = lookup(node.url, 'DEF');
425
+ if (urlEntry?.kind === 'DEF') {
426
+ node.url = urlEntry.url;
427
+ }
428
+ });
429
+ visit(tree, [
430
+ 'definition',
431
+ 'footnoteDefinition',
432
+ 'footnoteReference',
433
+ 'imageReference',
434
+ 'linkReference',
435
+ ], (node_) => {
436
+ const node = node_;
437
+ const entry = lookup(node.identifier, 'REFID') ?? lookup(node.identifier, 'FNID');
438
+ if (entry?.kind === 'REFID' || entry?.kind === 'FNID') {
439
+ node.identifier = entry.identifier;
440
+ node.label = entry.label ?? entry.identifier;
441
+ }
442
+ });
443
+ visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node_) => {
444
+ const node = node_;
445
+ for (const attr of node.attributes) {
446
+ if (attr.type === 'mdxJsxExpressionAttribute') {
447
+ const entry = lookup(attr.value, 'JSXATTR');
448
+ if (entry?.kind === 'JSXATTR' && typeof entry.value === 'string') {
449
+ attr.value = entry.value;
450
+ delete attr.data;
451
+ }
452
+ continue;
453
+ }
454
+ if (typeof attr.value === 'string') {
455
+ const entry = lookup(attr.value, 'JSXATTR');
456
+ if (entry?.kind === 'JSXATTR' && typeof entry.value === 'string') {
457
+ attr.value = entry.value;
458
+ }
459
+ continue;
460
+ }
461
+ if (attr.value?.type === 'mdxJsxAttributeValueExpression') {
462
+ const entry = lookup(attr.value.value, 'JSXATTR');
463
+ if (entry?.kind === 'JSXATTR' && typeof entry.value !== 'string') {
464
+ attr.value = entry.value;
465
+ }
466
+ }
467
+ }
468
+ });
469
+ visit(tree, 'html', (node) => {
470
+ node.value = node.value.replace(PLACEHOLDER_PATTERN, (token) => {
471
+ const entry = byPlaceholder.get(token.toLowerCase());
472
+ return entry?.kind === 'HTMLATTR' ? entry.value : token;
473
+ });
474
+ });
475
+ visit(tree, 'code', (node) => {
476
+ const entry = lookup(node.value, 'CODE');
477
+ if (entry?.kind === 'CODE') {
478
+ Object.assign(node, entry.node);
479
+ }
480
+ });
481
+ visit(tree, ['mdxFlowExpression', 'mdxTextExpression'], (node_) => {
482
+ const node = node_;
483
+ const entry = lookup(node.value, 'EXPR');
484
+ if (entry?.kind === 'EXPR') {
485
+ node.value = entry.value;
486
+ delete node.data;
487
+ }
488
+ });
489
+ // Inline code carries three kinds: real inline code, a masked bare URL, and a
490
+ // masked heading anchor. The latter two are put back as the nodes they came
491
+ // from, so the carrier must be replaced rather than rewritten.
492
+ visit(tree, 'inlineCode', (node, index, parent) => {
493
+ const token = isExactPlaceholder(node.value);
494
+ if (!token) {
495
+ return;
496
+ }
497
+ const entry = byPlaceholder.get(token.toLowerCase());
498
+ if (!entry) {
499
+ return;
500
+ }
501
+ if (entry.kind === 'ICODE') {
502
+ node.value = entry.value;
503
+ return;
504
+ }
505
+ if (!parent || index == null) {
506
+ return;
507
+ }
508
+ if (entry.kind === 'URL') {
509
+ parent.children[index] = entry.node;
510
+ return index + 1;
511
+ }
512
+ if (entry.kind === 'ANCHOR') {
513
+ parent.children[index] = { type: 'text', value: entry.value };
514
+ return index + 1;
515
+ }
516
+ });
517
+ };
518
+ /**
519
+ * Puts the masked values back and proves the round trip held.
520
+ *
521
+ * Three assertions, all of them free:
522
+ *
523
+ * 1. every placeholder comes back exactly as often as it went out — fewer means
524
+ * the model deleted the node, more means it copied it;
525
+ * 2. no placeholder-shaped token appears that was never issued;
526
+ * 3. the restored document still parses.
527
+ *
528
+ * Any failure throws {@link MaskIntegrityError} with the offending placeholders
529
+ * named. There is deliberately no lenient path: a document that fails here is
530
+ * damaged, and shipping it is how the damage became invisible in the first
531
+ * place.
532
+ */
533
+ export const restoreMaskedContent = (translatedContent, entries, processor) => {
534
+ let tree;
535
+ try {
536
+ tree = processor.parse(translatedContent);
537
+ }
538
+ catch (error) {
539
+ throw new MaskIntegrityError([
540
+ {
541
+ code: 'unparseable-output',
542
+ detail: `the model's output is not valid markdown/MDX: ${error instanceof Error ? error.message : String(error)}`,
543
+ },
544
+ ]);
545
+ }
546
+ const findings = [];
547
+ const counts = collectPlaceholderCounts(tree);
548
+ for (const entry of entries) {
549
+ const token = entry.placeholder.toLowerCase();
550
+ const actual = counts.get(token) ?? 0;
551
+ counts.delete(token);
552
+ if (actual === entry.occurrences) {
553
+ continue;
554
+ }
555
+ findings.push({
556
+ code: actual < entry.occurrences
557
+ ? 'missing-placeholder'
558
+ : 'duplicate-placeholder',
559
+ placeholder: entry.placeholder,
560
+ kind: entry.kind,
561
+ expected: entry.occurrences,
562
+ actual,
563
+ detail: describeEntry(entry),
564
+ });
565
+ }
566
+ const registered = new Set(entries.map((entry) => entry.placeholder.toLowerCase()));
567
+ for (const token of collectLoosePlaceholders(translatedContent)) {
568
+ if (!registered.has(token)) {
569
+ findings.push({ code: 'unregistered-placeholder', placeholder: token });
570
+ }
571
+ }
572
+ if (findings.length > 0) {
573
+ throw new MaskIntegrityError(findings);
574
+ }
575
+ restoreEntries(tree, entries);
576
+ const restored = processor.stringify(tree);
577
+ try {
578
+ processor.parse(restored);
579
+ }
580
+ catch (error) {
581
+ throw new MaskIntegrityError([
582
+ {
583
+ code: 'unparseable-output',
584
+ detail: `the restored document does not parse: ${error instanceof Error ? error.message : String(error)}`,
585
+ },
586
+ ]);
587
+ }
588
+ const leftovers = collectLoosePlaceholders(restored);
589
+ if (leftovers.size > 0) {
590
+ throw new MaskIntegrityError([...leftovers].map((placeholder) => ({
591
+ code: 'unrestored-placeholder',
592
+ placeholder,
593
+ detail: 'the model moved it into a node kind it was not issued for',
594
+ })));
595
+ }
596
+ return restored;
597
+ };
598
+ const describeEntry = (entry) => {
599
+ const preview = (value) => value.length > 60 ? `${value.slice(0, 57)}…` : value;
600
+ switch (entry.kind) {
601
+ case 'DEF':
602
+ case 'IMG':
603
+ case 'LINK':
604
+ return preview(entry.url);
605
+ case 'FNID':
606
+ case 'REFID':
607
+ return preview(entry.identifier);
608
+ case 'CODE':
609
+ return preview(entry.node.value);
610
+ case 'URL':
611
+ return preview(entry.node.url);
612
+ case 'JSXATTR':
613
+ return preview(typeof entry.value === 'string' ? entry.value : entry.value.value);
614
+ default:
615
+ return preview(entry.value);
616
+ }
617
+ };