@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.
- package/lib/cli/api.d.ts +2 -0
- package/lib/cli/api.js +147 -0
- package/lib/cli/helpers.d.ts +1 -7
- package/lib/cli/helpers.js +4 -41
- package/lib/cli/index.js +2 -0
- package/lib/cli/translate-agent.d.ts +81 -0
- package/lib/cli/translate-agent.js +450 -0
- package/lib/cli/translate-check.d.ts +17 -0
- package/lib/cli/translate-check.js +67 -0
- package/lib/cli/translate-checker.d.ts +58 -0
- package/lib/cli/translate-checker.js +112 -0
- package/lib/cli/translate-judge.d.ts +119 -0
- package/lib/cli/translate-judge.js +224 -0
- package/lib/cli/translate-limits.d.ts +43 -0
- package/lib/cli/translate-limits.js +55 -0
- package/lib/cli/translate-mask.d.ts +144 -0
- package/lib/cli/translate-mask.js +617 -0
- package/lib/cli/translate-models.d.ts +127 -0
- package/lib/cli/translate-models.js +189 -0
- package/lib/cli/translate-scratch.d.ts +142 -0
- package/lib/cli/translate-scratch.js +187 -0
- package/lib/cli/translate-terms.d.ts +22 -0
- package/lib/cli/translate-terms.js +33 -0
- package/lib/cli/translate.d.ts +15 -10
- package/lib/cli/translate.js +228 -185
- package/lib/eslint.js +22 -3
- package/lib/plugins/api/index.js +1 -1
- package/lib/plugins/api/types.d.ts +36 -1
- package/lib/plugins/global/components.d.ts +16 -0
- package/lib/plugins/global/components.js +16 -1
- package/lib/remark-lint/index.d.ts +20 -0
- package/lib/remark-lint/index.js +40 -0
- package/lib/remark-lint/no-unmatched-anchor.d.ts +10 -0
- package/lib/remark-lint/no-unmatched-anchor.js +19 -2
- package/lib/remark-lint/no-unopened-frontmatter.d.ts +2 -0
- package/lib/remark-lint/no-unopened-frontmatter.js +70 -0
- package/lib/remark-lint/no-unparsed-emphasis.d.ts +2 -0
- package/lib/remark-lint/no-unparsed-emphasis.js +53 -0
- package/lib/remark-lint/no-unresolved-api-ref.d.ts +40 -0
- package/lib/remark-lint/no-unresolved-api-ref.js +194 -0
- package/lib/remark-lint/rule-sets.d.ts +73 -0
- package/lib/remark-lint/rule-sets.js +114 -0
- package/lib/remark-lint/syntax-plugins.d.ts +32 -0
- package/lib/remark-lint/syntax-plugins.js +46 -0
- package/lib/remark-lint/translation-parity/component-multiset.d.ts +17 -0
- package/lib/remark-lint/translation-parity/component-multiset.js +35 -0
- package/lib/remark-lint/translation-parity/echoed-source.d.ts +2 -0
- package/lib/remark-lint/translation-parity/echoed-source.js +37 -0
- package/lib/remark-lint/translation-parity/frontmatter-preservation.d.ts +2 -0
- package/lib/remark-lint/translation-parity/frontmatter-preservation.js +36 -0
- package/lib/remark-lint/translation-parity/heading-sequence.d.ts +12 -0
- package/lib/remark-lint/translation-parity/heading-sequence.js +25 -0
- package/lib/remark-lint/translation-parity/index.d.ts +24 -0
- package/lib/remark-lint/translation-parity/index.js +24 -0
- package/lib/remark-lint/translation-parity/jsx-attribute-parity.d.ts +14 -0
- package/lib/remark-lint/translation-parity/jsx-attribute-parity.js +47 -0
- package/lib/remark-lint/translation-parity/length-ratio.d.ts +2 -0
- package/lib/remark-lint/translation-parity/length-ratio.js +49 -0
- package/lib/remark-lint/translation-parity/link-isomorphism.d.ts +34 -0
- package/lib/remark-lint/translation-parity/link-isomorphism.js +81 -0
- package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
- package/lib/remark-lint/translation-parity/shared.js +286 -0
- package/lib/remark-lint/translation-parity/terminology-adherence.d.ts +2 -0
- package/lib/remark-lint/translation-parity/terminology-adherence.js +67 -0
- package/lib/remark-lint/translation-parity/up-to-date.d.ts +11 -0
- package/lib/remark-lint/translation-parity/up-to-date.js +21 -0
- package/lib/remark-lint/translation-parity/url-residue.d.ts +3 -0
- package/lib/remark-lint/translation-parity/url-residue.js +67 -0
- package/lib/remarkrc.d.ts +1 -1
- package/lib/remarkrc.js +7 -34
- package/lib/runtime/api-paths.d.ts +20 -0
- package/lib/runtime/api-paths.js +29 -0
- package/lib/runtime/components/K8sAPI.d.ts +14 -1
- package/lib/runtime/components/K8sAPI.js +49 -10
- package/lib/runtime/components/K8sCrd.d.ts +1 -1
- package/lib/runtime/components/K8sPermissionTable.js +10 -5
- package/lib/runtime/components/OpenAPIPath.js +19 -2
- package/lib/runtime/components/_HeadingTitle.js +24 -6
- package/lib/runtime/components/_K8sAPIEndpoints.d.ts +8 -1
- package/lib/runtime/components/_K8sAPIEndpoints.js +27 -9
- package/lib/runtime/components/_K8sAPISchema.d.ts +9 -1
- package/lib/runtime/components/_K8sAPISchema.js +24 -6
- package/lib/runtime/components/_translation-policy.d.ts +23 -0
- package/lib/runtime/components/_translation-policy.js +32 -0
- package/lib/runtime/hooks/useTranslation.d.ts +1 -1
- package/lib/runtime/translation.d.ts +68 -0
- package/lib/runtime/translation.js +51 -0
- package/lib/runtime/utils.d.ts +24 -2
- package/lib/runtime/utils.js +87 -5
- package/lib/shared/constants.d.ts +9 -0
- package/lib/shared/constants.js +14 -0
- package/lib/types.d.ts +70 -0
- package/lib/utils/helpers.js +8 -2
- 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
|
+
};
|