@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.
- package/lib/cli/translate-call.d.ts +85 -0
- package/lib/cli/translate-call.js +162 -0
- package/lib/cli/translate-checker.d.ts +8 -0
- package/lib/cli/translate-diagnose.d.ts +45 -0
- package/lib/cli/translate-diagnose.js +118 -0
- package/lib/cli/translate-judge.d.ts +28 -3
- package/lib/cli/translate-judge.js +40 -7
- package/lib/cli/translate-mask.d.ts +13 -0
- package/lib/cli/translate-mask.js +19 -5
- package/lib/cli/translate-pipeline.d.ts +156 -0
- package/lib/cli/translate-pipeline.js +501 -0
- package/lib/cli/translate-repair-agent.d.ts +69 -0
- package/lib/cli/translate-repair-agent.js +241 -0
- package/lib/cli/translate-scratch.d.ts +9 -1
- package/lib/cli/translate-scratch.js +2 -2
- package/lib/cli/translate-segment-cache.d.ts +90 -0
- package/lib/cli/translate-segment-cache.js +301 -0
- package/lib/cli/translate-segment-check.d.ts +42 -0
- package/lib/cli/translate-segment-check.js +288 -0
- package/lib/cli/translate-segment.d.ts +307 -0
- package/lib/cli/translate-segment.js +625 -0
- package/lib/cli/translate.d.ts +14 -4
- package/lib/cli/translate.js +232 -52
- package/lib/remark-lint/no-unopened-frontmatter.js +5 -1
- package/lib/remark-lint/no-unparsed-emphasis.d.ts +13 -0
- package/lib/remark-lint/no-unparsed-emphasis.js +30 -5
- package/lib/remark-lint/translation-parity/frontmatter-preservation.js +5 -3
- package/lib/runtime/hooks/useTranslation.d.ts +1 -1
- package/lib/types.d.ts +101 -6
- package/package.json +1 -1
- package/lib/cli/translate-agent.d.ts +0 -81
- package/lib/cli/translate-agent.js +0 -450
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import type { Model, Models, ThinkingLevel } from '@earendil-works/pi-ai';
|
|
2
|
+
import type { SegmentRepairer } from './translate-pipeline.ts';
|
|
3
|
+
/**
|
|
4
|
+
* The last resort for one segment, and the only place a model is left to work
|
|
5
|
+
* on its own.
|
|
6
|
+
*
|
|
7
|
+
* Autonomy is deployed where it wins. Translating a segment, counting
|
|
8
|
+
* placeholders, cutting a document and putting it back together are jobs with
|
|
9
|
+
* one right answer, and giving them to an agent only adds variance — so they
|
|
10
|
+
* are code. Working out why a particular paragraph keeps failing a particular
|
|
11
|
+
* check, and making a surgical change to fix it, is open-ended, and that is
|
|
12
|
+
* what an agent is for. This is that, and nothing else.
|
|
13
|
+
*
|
|
14
|
+
* What makes it safe is not the prompt. **The tools are `read`, `edit` and
|
|
15
|
+
* `check`.** There is no `write` and no `append`, so "do not rewrite the whole
|
|
16
|
+
* thing" is not advice it might ignore under pressure: nothing here takes a
|
|
17
|
+
* replacement for the file. Be exact about how far that goes — `edit` asks only
|
|
18
|
+
* that its `oldText` occur once, so quoting the entire file back and handing
|
|
19
|
+
* over a new one is still a rewrite the tool would accept. What stands in the
|
|
20
|
+
* way is the price: every byte of the segment has to be reproduced exactly to
|
|
21
|
+
* match, and a model that could do that reliably would not have needed
|
|
22
|
+
* repairing. The guarantee is economic, not syntactic — but it is the
|
|
23
|
+
* difference between a rewrite being the cheapest thing to reach for and being
|
|
24
|
+
* the most expensive. That distinction is the entire lesson of the incident
|
|
25
|
+
* this design came from: the previous agent was *told* to prefer targeted
|
|
26
|
+
* edits, had `write` in its hands — one call, no quoting, no cost — and
|
|
27
|
+
* replaced a translation that was one problem from finished with one that had a
|
|
28
|
+
* thousand.
|
|
29
|
+
*
|
|
30
|
+
* And it works inside a segment. Even a repair that goes as badly as possible
|
|
31
|
+
* can only damage a few kilobytes that were already failing, it has to pass the
|
|
32
|
+
* same acceptance check as any other attempt, and the segment's best accepted
|
|
33
|
+
* version is untouched while it works.
|
|
34
|
+
*/
|
|
35
|
+
/** Turns before it is stopped. A segment's size has an upper bound, so a fixed number is meaningful. */
|
|
36
|
+
export declare const DEFAULT_REPAIR_MAX_TURNS = 40;
|
|
37
|
+
/** Reasoning for the repair path. Rare and hard, which is what reasoning is for. */
|
|
38
|
+
export declare const DEFAULT_REPAIR_REASONING_EFFORT: ThinkingLevel;
|
|
39
|
+
export interface CreateRepairAgentOptions {
|
|
40
|
+
models: Models;
|
|
41
|
+
model: Model<'openai-completions'>;
|
|
42
|
+
reasoningEffort?: ThinkingLevel;
|
|
43
|
+
/** Directory scratch directories are created under. */
|
|
44
|
+
scratchDir: string;
|
|
45
|
+
/** `.mdx` or `.md`, so the agent sees the flavour it is editing. */
|
|
46
|
+
extension: string;
|
|
47
|
+
maxTurns?: number;
|
|
48
|
+
/** Applied to every model call, so repairs count against the same budget. */
|
|
49
|
+
limit: <T>(run: () => Promise<T>) => Promise<T>;
|
|
50
|
+
maxModelRetries?: number;
|
|
51
|
+
modelRetryDelayMs?: number;
|
|
52
|
+
onProgress?: (message: string) => void;
|
|
53
|
+
}
|
|
54
|
+
export declare const createRepairAgent: ({ models, model, reasoningEffort, scratchDir, extension, maxTurns, limit, maxModelRetries, modelRetryDelayMs, onProgress, }: CreateRepairAgentOptions) => SegmentRepairer;
|
|
55
|
+
/**
|
|
56
|
+
* The only tools a repair agent has.
|
|
57
|
+
*
|
|
58
|
+
* Exported so a test can assert on it. `write` and `append` are absent on
|
|
59
|
+
* purpose, and the reason is worth stating where someone adding a tool will
|
|
60
|
+
* read it: with `write` in its hands, the previous agent replaced a translation
|
|
61
|
+
* that was one finding from finished with one that had a thousand. Nothing
|
|
62
|
+
* about that was against its instructions in spirit; it simply had the means.
|
|
63
|
+
*
|
|
64
|
+
* Adding a tool that takes whole-file content puts those means back. `edit`
|
|
65
|
+
* does not, in any practical sense — a rewrite through it costs an exact
|
|
66
|
+
* byte-for-byte quotation of the file — but that is a matter of price rather
|
|
67
|
+
* than of syntax, so a cheaper route to the same thing would undo it.
|
|
68
|
+
*/
|
|
69
|
+
export declare const REPAIR_TOOL_NAMES: readonly ["read", "edit", "check"];
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
import { blockingFindings } from "./translate-checker.js";
|
|
2
|
+
import { SCRATCH_SOURCE, SCRATCH_TRANSLATION, createScratch, loadPi, } from "./translate-scratch.js";
|
|
3
|
+
/**
|
|
4
|
+
* The last resort for one segment, and the only place a model is left to work
|
|
5
|
+
* on its own.
|
|
6
|
+
*
|
|
7
|
+
* Autonomy is deployed where it wins. Translating a segment, counting
|
|
8
|
+
* placeholders, cutting a document and putting it back together are jobs with
|
|
9
|
+
* one right answer, and giving them to an agent only adds variance — so they
|
|
10
|
+
* are code. Working out why a particular paragraph keeps failing a particular
|
|
11
|
+
* check, and making a surgical change to fix it, is open-ended, and that is
|
|
12
|
+
* what an agent is for. This is that, and nothing else.
|
|
13
|
+
*
|
|
14
|
+
* What makes it safe is not the prompt. **The tools are `read`, `edit` and
|
|
15
|
+
* `check`.** There is no `write` and no `append`, so "do not rewrite the whole
|
|
16
|
+
* thing" is not advice it might ignore under pressure: nothing here takes a
|
|
17
|
+
* replacement for the file. Be exact about how far that goes — `edit` asks only
|
|
18
|
+
* that its `oldText` occur once, so quoting the entire file back and handing
|
|
19
|
+
* over a new one is still a rewrite the tool would accept. What stands in the
|
|
20
|
+
* way is the price: every byte of the segment has to be reproduced exactly to
|
|
21
|
+
* match, and a model that could do that reliably would not have needed
|
|
22
|
+
* repairing. The guarantee is economic, not syntactic — but it is the
|
|
23
|
+
* difference between a rewrite being the cheapest thing to reach for and being
|
|
24
|
+
* the most expensive. That distinction is the entire lesson of the incident
|
|
25
|
+
* this design came from: the previous agent was *told* to prefer targeted
|
|
26
|
+
* edits, had `write` in its hands — one call, no quoting, no cost — and
|
|
27
|
+
* replaced a translation that was one problem from finished with one that had a
|
|
28
|
+
* thousand.
|
|
29
|
+
*
|
|
30
|
+
* And it works inside a segment. Even a repair that goes as badly as possible
|
|
31
|
+
* can only damage a few kilobytes that were already failing, it has to pass the
|
|
32
|
+
* same acceptance check as any other attempt, and the segment's best accepted
|
|
33
|
+
* version is untouched while it works.
|
|
34
|
+
*/
|
|
35
|
+
/** Turns before it is stopped. A segment's size has an upper bound, so a fixed number is meaningful. */
|
|
36
|
+
export const DEFAULT_REPAIR_MAX_TURNS = 40;
|
|
37
|
+
/** Reasoning for the repair path. Rare and hard, which is what reasoning is for. */
|
|
38
|
+
export const DEFAULT_REPAIR_REASONING_EFFORT = 'high';
|
|
39
|
+
const MODEL_MAX_RETRIES = 5;
|
|
40
|
+
const MODEL_RETRY_DELAY_MS = 3_000;
|
|
41
|
+
const renderFindings = (findings) => findings
|
|
42
|
+
.map((finding) => `- ${finding.rule}${finding.line ? ` (line ${finding.line})` : ''}: ${finding.reason}`)
|
|
43
|
+
.join('\n');
|
|
44
|
+
export const createRepairAgent = ({ models, model, reasoningEffort = DEFAULT_REPAIR_REASONING_EFFORT, scratchDir, extension, maxTurns = DEFAULT_REPAIR_MAX_TURNS, limit, maxModelRetries = MODEL_MAX_RETRIES, modelRetryDelayMs = MODEL_RETRY_DELAY_MS, onProgress, }) => ({
|
|
45
|
+
async repair({ segment, draft, history, check }) {
|
|
46
|
+
const [pi] = await Promise.all([loadPi()]);
|
|
47
|
+
const { createReadTool, createEditTool, runAgentLoop } = pi.core;
|
|
48
|
+
// Taken from the scratch directory's own names rather than written out
|
|
49
|
+
// again: the prompt tells the agent these files exist, and an agent that
|
|
50
|
+
// reads a name that is not there gets `not_found` and no explanation.
|
|
51
|
+
const sourceName = `${SCRATCH_SOURCE}${extension}`;
|
|
52
|
+
const translationName = `${SCRATCH_TRANSLATION}${extension}`;
|
|
53
|
+
const scratch = await createScratch({
|
|
54
|
+
parentDir: scratchDir,
|
|
55
|
+
label: `repair-${segment.index}`,
|
|
56
|
+
maskedSource: segment.text,
|
|
57
|
+
extension,
|
|
58
|
+
draft,
|
|
59
|
+
});
|
|
60
|
+
try {
|
|
61
|
+
const toolContext = { env: scratch.env };
|
|
62
|
+
const bind = (tool) => ({
|
|
63
|
+
...tool,
|
|
64
|
+
execute: (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate, toolContext),
|
|
65
|
+
});
|
|
66
|
+
const textResult = (text, details) => ({
|
|
67
|
+
content: [{ type: 'text', text }],
|
|
68
|
+
details,
|
|
69
|
+
});
|
|
70
|
+
let latest = draft;
|
|
71
|
+
/**
|
|
72
|
+
* The agent's view of its own work — the same function that decides
|
|
73
|
+
* whether any other attempt is accepted.
|
|
74
|
+
*
|
|
75
|
+
* It returns findings and nothing else, never the restored text: the
|
|
76
|
+
* restored form holds the real link targets and identifiers, and handing
|
|
77
|
+
* those back would put in the model's context exactly what masking took
|
|
78
|
+
* out of it.
|
|
79
|
+
*/
|
|
80
|
+
const checkTool = {
|
|
81
|
+
label: 'Check',
|
|
82
|
+
name: 'check',
|
|
83
|
+
description: 'Compare your translation of this segment with its source and list what is wrong. Reports nothing when it is correct.',
|
|
84
|
+
parameters: (await import('@earendil-works/pi-ai')).Type.Object({}),
|
|
85
|
+
execute: async () => {
|
|
86
|
+
latest = await scratch.readTranslation();
|
|
87
|
+
const findings = await check(latest);
|
|
88
|
+
if (blockingFindings(findings).length === 0) {
|
|
89
|
+
return textResult('No problems found. This segment is correct.', undefined);
|
|
90
|
+
}
|
|
91
|
+
return textResult(`${findings.length} problem(s):\n${renderFindings(findings)}`, undefined);
|
|
92
|
+
},
|
|
93
|
+
};
|
|
94
|
+
// `read` and `edit`. Deliberately no `write` and no `append`: the one
|
|
95
|
+
// thing this agent must not be able to do is replace the file, and the
|
|
96
|
+
// way to guarantee that is to not give it the means.
|
|
97
|
+
const tools = [
|
|
98
|
+
bind(createReadTool()),
|
|
99
|
+
bind(createEditTool()),
|
|
100
|
+
checkTool,
|
|
101
|
+
];
|
|
102
|
+
const systemPrompt = [
|
|
103
|
+
'You are fixing the translation of ONE SEGMENT of a documentation page. It is a few kilobytes; you can hold all of it at once.',
|
|
104
|
+
'',
|
|
105
|
+
'## Your working directory',
|
|
106
|
+
'',
|
|
107
|
+
'It is everything you can reach. There is no other file, and no shell.',
|
|
108
|
+
'',
|
|
109
|
+
`- \`${sourceName}\` — the segment's prepared source.`,
|
|
110
|
+
`- \`${translationName}\` — its translation, as it stands. It is close: repeated attempts have already got most of it right.`,
|
|
111
|
+
'',
|
|
112
|
+
'## How to work',
|
|
113
|
+
'',
|
|
114
|
+
`1. \`check\` to see exactly what is wrong.`,
|
|
115
|
+
`2. \`edit\` \`${translationName}\` to fix precisely that, and nothing else.`,
|
|
116
|
+
`3. \`check\` again.`,
|
|
117
|
+
'',
|
|
118
|
+
'You can only change this file by editing parts of it. There is no tool that replaces it, and that is deliberate: most of this translation is already correct, and the failure this design exists to prevent is a rewrite that throws away what was right in order to fix what was not.',
|
|
119
|
+
'',
|
|
120
|
+
'## Placeholders',
|
|
121
|
+
'',
|
|
122
|
+
'Tokens shaped like `__DOOM_TR_LINK_3__` stand for content nobody may author — link targets, code, identifiers. Each one must appear exactly as often as it does in the source. Never translate, renumber, remove, duplicate or invent one.',
|
|
123
|
+
'',
|
|
124
|
+
'## When you are finished',
|
|
125
|
+
'',
|
|
126
|
+
'You are finished when `check` reports nothing. Saying so yourself does not end the task: the same check runs again when you stop.',
|
|
127
|
+
].join('\n');
|
|
128
|
+
const initialPrompt = {
|
|
129
|
+
role: 'user',
|
|
130
|
+
content: [
|
|
131
|
+
`Fix \`${translationName}\` so that \`check\` reports nothing.`,
|
|
132
|
+
'',
|
|
133
|
+
`This is the segment's source:`,
|
|
134
|
+
'',
|
|
135
|
+
'<<<SOURCE',
|
|
136
|
+
segment.text,
|
|
137
|
+
'SOURCE',
|
|
138
|
+
'',
|
|
139
|
+
`This is the translation as it stands:`,
|
|
140
|
+
'',
|
|
141
|
+
'<<<TRANSLATION',
|
|
142
|
+
draft || '(empty)',
|
|
143
|
+
'TRANSLATION',
|
|
144
|
+
'',
|
|
145
|
+
history.length > 0
|
|
146
|
+
? `Previous attempts were rejected for these reasons, oldest first:\n\n${history
|
|
147
|
+
.map((findings, round) => `Attempt ${round + 1}:\n${renderFindings(findings)}`)
|
|
148
|
+
.join('\n\n')}`
|
|
149
|
+
: '',
|
|
150
|
+
].join('\n'),
|
|
151
|
+
timestamp: Date.now(),
|
|
152
|
+
};
|
|
153
|
+
let turns = 0;
|
|
154
|
+
const failure = {};
|
|
155
|
+
const clearFailure = () => {
|
|
156
|
+
failure.message = undefined;
|
|
157
|
+
};
|
|
158
|
+
const streamFn = (streamModel, context, streamOptions) => limit(() => Promise.resolve(models.streamSimple(streamModel, context, streamOptions)));
|
|
159
|
+
const config = {
|
|
160
|
+
model,
|
|
161
|
+
reasoning: reasoningEffort,
|
|
162
|
+
// The caller's number, not the default: a caller that asked for no
|
|
163
|
+
// retries — a test, or a run that would rather fail than wait — was
|
|
164
|
+
// still getting five inside pi.
|
|
165
|
+
maxRetries: maxModelRetries,
|
|
166
|
+
convertToLlm: (messages) => messages,
|
|
167
|
+
shouldStopAfterTurn: () => ++turns >= maxTurns,
|
|
168
|
+
// pi's "the agent would stop here" hook. Returning anything puts it back
|
|
169
|
+
// to work, so the agent finishes exactly when the harness's own check
|
|
170
|
+
// finds nothing — it never sees this call and cannot route around it.
|
|
171
|
+
getFollowUpMessages: async () => {
|
|
172
|
+
latest = await scratch.readTranslation();
|
|
173
|
+
const findings = await check(latest);
|
|
174
|
+
const blocking = blockingFindings(findings);
|
|
175
|
+
if (blocking.length === 0) {
|
|
176
|
+
return [];
|
|
177
|
+
}
|
|
178
|
+
return [
|
|
179
|
+
{
|
|
180
|
+
role: 'user',
|
|
181
|
+
content: `Not yet — ${blocking.length} problem(s) remain:\n\n${renderFindings(findings)}\n\nFix them in \`${translationName}\` with \`edit\`, then \`check\` again.`,
|
|
182
|
+
timestamp: Date.now(),
|
|
183
|
+
},
|
|
184
|
+
];
|
|
185
|
+
},
|
|
186
|
+
};
|
|
187
|
+
const watchForStreamFailure = (event) => {
|
|
188
|
+
if (event.type === 'turn_end' &&
|
|
189
|
+
'stopReason' in event.message &&
|
|
190
|
+
(event.message.stopReason === 'error' ||
|
|
191
|
+
event.message.stopReason === 'aborted')) {
|
|
192
|
+
failure.message =
|
|
193
|
+
('errorMessage' in event.message
|
|
194
|
+
? event.message.errorMessage
|
|
195
|
+
: undefined) ?? event.message.stopReason;
|
|
196
|
+
}
|
|
197
|
+
};
|
|
198
|
+
for (let attempt = 0;; attempt++) {
|
|
199
|
+
clearFailure();
|
|
200
|
+
const prompt = attempt === 0
|
|
201
|
+
? initialPrompt
|
|
202
|
+
: {
|
|
203
|
+
role: 'user',
|
|
204
|
+
content: `Carry on fixing \`${translationName}\`. \`read\` it first to see where you got to, then \`check\`.`,
|
|
205
|
+
timestamp: Date.now(),
|
|
206
|
+
};
|
|
207
|
+
await runAgentLoop([prompt], { systemPrompt, messages: [], tools }, config, watchForStreamFailure, undefined, streamFn);
|
|
208
|
+
if (!failure.message) {
|
|
209
|
+
break;
|
|
210
|
+
}
|
|
211
|
+
if (attempt >= maxModelRetries || turns >= maxTurns) {
|
|
212
|
+
// A refusal is not a repair that failed. It costs the segment its
|
|
213
|
+
// escalation, and the document fails with the findings it already
|
|
214
|
+
// had, rather than the run dying on someone else's rate limit.
|
|
215
|
+
onProgress?.(`repairing segment ${segment.index + 1} gave up: ${failure.message}`);
|
|
216
|
+
return undefined;
|
|
217
|
+
}
|
|
218
|
+
await new Promise((resolve) => globalThis.setTimeout(resolve, modelRetryDelayMs * 2 ** attempt));
|
|
219
|
+
}
|
|
220
|
+
return await scratch.readTranslation();
|
|
221
|
+
}
|
|
222
|
+
finally {
|
|
223
|
+
await scratch.dispose();
|
|
224
|
+
}
|
|
225
|
+
},
|
|
226
|
+
});
|
|
227
|
+
/**
|
|
228
|
+
* The only tools a repair agent has.
|
|
229
|
+
*
|
|
230
|
+
* Exported so a test can assert on it. `write` and `append` are absent on
|
|
231
|
+
* purpose, and the reason is worth stating where someone adding a tool will
|
|
232
|
+
* read it: with `write` in its hands, the previous agent replaced a translation
|
|
233
|
+
* that was one finding from finished with one that had a thousand. Nothing
|
|
234
|
+
* about that was against its instructions in spirit; it simply had the means.
|
|
235
|
+
*
|
|
236
|
+
* Adding a tool that takes whole-file content puts those means back. `edit`
|
|
237
|
+
* does not, in any practical sense — a rewrite through it costs an exact
|
|
238
|
+
* byte-for-byte quotation of the file — but that is a matter of price rather
|
|
239
|
+
* than of syntax, so a cheaper route to the same thing would undo it.
|
|
240
|
+
*/
|
|
241
|
+
export const REPAIR_TOOL_NAMES = ['read', 'edit', 'check'];
|
|
@@ -138,5 +138,13 @@ export interface CreateScratchOptions {
|
|
|
138
138
|
maskedSource: string;
|
|
139
139
|
/** `.mdx` or `.md`; kept so the agent sees the extension it is writing for. */
|
|
140
140
|
extension: string;
|
|
141
|
+
/**
|
|
142
|
+
* What the translation file starts as.
|
|
143
|
+
*
|
|
144
|
+
* Empty for a translation being written from nothing; the best rejected
|
|
145
|
+
* attempt when a repair agent is being asked to fix one rather than to
|
|
146
|
+
* produce one.
|
|
147
|
+
*/
|
|
148
|
+
draft?: string;
|
|
141
149
|
}
|
|
142
|
-
export declare const createScratch: ({ parentDir, label, maskedSource, extension, }: CreateScratchOptions) => Promise<Scratch>;
|
|
150
|
+
export declare const createScratch: ({ parentDir, label, maskedSource, extension, draft, }: CreateScratchOptions) => Promise<Scratch>;
|
|
@@ -163,14 +163,14 @@ export class JailedExecutionEnv {
|
|
|
163
163
|
/** Where the two documents live inside a scratch directory. */
|
|
164
164
|
export const SCRATCH_SOURCE = 'source';
|
|
165
165
|
export const SCRATCH_TRANSLATION = 'translation';
|
|
166
|
-
export const createScratch = async ({ parentDir, label, maskedSource, extension, }) => {
|
|
166
|
+
export const createScratch = async ({ parentDir, label, maskedSource, extension, draft = '', }) => {
|
|
167
167
|
const pi = await loadPi();
|
|
168
168
|
await fs.mkdir(parentDir, { recursive: true });
|
|
169
169
|
const root = await fs.mkdtemp(path.join(parentDir, `${label}-`));
|
|
170
170
|
const sourcePath = path.join(root, `${SCRATCH_SOURCE}${extension}`);
|
|
171
171
|
const translationPath = path.join(root, `${SCRATCH_TRANSLATION}${extension}`);
|
|
172
172
|
await fs.writeFile(sourcePath, maskedSource);
|
|
173
|
-
await fs.writeFile(translationPath,
|
|
173
|
+
await fs.writeFile(translationPath, draft);
|
|
174
174
|
const env = new JailedExecutionEnv({
|
|
175
175
|
root,
|
|
176
176
|
inner: new pi.NodeExecutionEnv({ cwd: root }),
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import { type MaskEntry, type MaskProcessor } from './translate-mask.ts';
|
|
2
|
+
import { type SegmentPlan, type SegmentRecord } from './translate-segment.ts';
|
|
3
|
+
/**
|
|
4
|
+
* Reusing the segments whose source did not change.
|
|
5
|
+
*
|
|
6
|
+
* `sourceSHA` already skips a document nobody touched. This is the layer below
|
|
7
|
+
* it: when a document *has* changed, only the segments that changed are
|
|
8
|
+
* retranslated. The edit that set off the incident this work came from was one
|
|
9
|
+
* line — `+1/-1` — and it cost a full retranslation of 3122 lines. Under this
|
|
10
|
+
* it costs one segment.
|
|
11
|
+
*
|
|
12
|
+
* Two things make that safe to do.
|
|
13
|
+
*
|
|
14
|
+
* **The previous translation is on disk with its real content, not its masked
|
|
15
|
+
* content.** A reusable segment has to be masked again to be comparable, and it
|
|
16
|
+
* cannot simply be re-masked with fresh numbering — the numbers would be the
|
|
17
|
+
* translation's, not the current source's. So each masked value in the
|
|
18
|
+
* candidate is matched *by value* against the mask entries the current source
|
|
19
|
+
* issued for that segment, and the candidate's tokens are rewritten to the
|
|
20
|
+
* source's. This is done by running the same {@link maskAst} the rest of the
|
|
21
|
+
* pipeline runs, so there is no second opinion about what counts as maskable.
|
|
22
|
+
*
|
|
23
|
+
* **Nothing is trusted because it was written down.** A record says where a
|
|
24
|
+
* segment went; it does not say the file still holds it. Somebody may have
|
|
25
|
+
* edited the translation by hand, a merge may have moved things, the record may
|
|
26
|
+
* simply be stale. So every candidate has to survive the match above and come
|
|
27
|
+
* out with exactly the placeholders the current source expects — and anything
|
|
28
|
+
* that does not is retranslated rather than reused. A cache entry that cannot
|
|
29
|
+
* be verified for free is worth nothing, because the failure it causes looks
|
|
30
|
+
* exactly like a translation defect.
|
|
31
|
+
*/
|
|
32
|
+
/** The `i18nSegments` block, as it is written into a translation's frontmatter. */
|
|
33
|
+
export interface SegmentCacheRecord {
|
|
34
|
+
/** `SEGMENTER_VERSION` the cut was made under. */
|
|
35
|
+
v: number;
|
|
36
|
+
/** The cap it was made under. */
|
|
37
|
+
cap: number;
|
|
38
|
+
/** One entry per reusable segment. */
|
|
39
|
+
segs: string[];
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* One record, as one short string.
|
|
43
|
+
*
|
|
44
|
+
* `<sha> <start>-<end>` at the top level, `<sha> <path>/<start>-<end>` inside a
|
|
45
|
+
* container, `<sha> <path>:attrs` for a tag's own words. Compact because it
|
|
46
|
+
* lives in every translated document's frontmatter, and readable because the
|
|
47
|
+
* first thing anyone does with an unexpected diff is read it.
|
|
48
|
+
*/
|
|
49
|
+
export declare const encodeRecord: ({ sha, address }: SegmentRecord) => string;
|
|
50
|
+
export declare const decodeRecord: (entry: string) => SegmentRecord | undefined;
|
|
51
|
+
export declare const encodeCacheRecord: (plan: Pick<SegmentPlan, "version" | "cap">, records: readonly SegmentRecord[]) => SegmentCacheRecord | undefined;
|
|
52
|
+
export interface MatchCachedSegmentsOptions {
|
|
53
|
+
plan: SegmentPlan;
|
|
54
|
+
maskEntries: readonly MaskEntry[];
|
|
55
|
+
processor: MaskProcessor;
|
|
56
|
+
/** Its `i18nSegments`, as parsed out of that frontmatter. */
|
|
57
|
+
record: SegmentCacheRecord | undefined;
|
|
58
|
+
/**
|
|
59
|
+
* The body of the previous translation — everything after the frontmatter.
|
|
60
|
+
*
|
|
61
|
+
* The body rather than the file, because that is the coordinate system the
|
|
62
|
+
* records were written in: `compose` rewrites frontmatter on the way out, so
|
|
63
|
+
* counting it as block 0 would put every address off by one.
|
|
64
|
+
*/
|
|
65
|
+
previousBody: string;
|
|
66
|
+
}
|
|
67
|
+
export interface CachedSegments {
|
|
68
|
+
/** Masked translations, by segment index, ready to freeze. */
|
|
69
|
+
reuse: Map<number, string>;
|
|
70
|
+
/** Why nothing was reused, when nothing was. For the log. */
|
|
71
|
+
reason?: string;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Which of this document's segments can be taken from the previous translation.
|
|
75
|
+
*
|
|
76
|
+
* The two hash sequences are matched with a longest-common-subsequence, so a
|
|
77
|
+
* segment inserted in the middle of a page shifts nothing after it and two
|
|
78
|
+
* identical segments cannot swap places. Every match is then verified, and only
|
|
79
|
+
* what survives is offered.
|
|
80
|
+
*/
|
|
81
|
+
export declare const matchCachedSegments: ({ plan, maskEntries, processor, record, previousBody, }: MatchCachedSegmentsOptions) => CachedSegments;
|
|
82
|
+
/**
|
|
83
|
+
* The longest run of segments, in order, whose hashes agree.
|
|
84
|
+
*
|
|
85
|
+
* A plain two-pointer walk loses alignment for the rest of the page the moment
|
|
86
|
+
* one segment is inserted or removed. This is the standard subsequence instead:
|
|
87
|
+
* pairs never cross, so two identical segments cannot be matched to each
|
|
88
|
+
* other's positions, and an edit only costs the segment it touched.
|
|
89
|
+
*/
|
|
90
|
+
export declare const alignBySha: (current: readonly string[], previous: readonly string[]) => Array<[number, number]>;
|