@alauda/doom 2.5.3 → 2.6.0
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 +48 -5
- package/lib/plugins/api/index.js +1 -1
- package/lib/plugins/api/types.d.ts +36 -1
- package/lib/plugins/global/components.d.ts +18 -0
- package/lib/plugins/global/components.js +33 -0
- package/lib/plugins/global/index.js +2 -10
- 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 +13 -0
- 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 +75 -0
- package/lib/remark-lint/rule-sets.js +120 -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 +26 -0
- package/lib/remark-lint/translation-parity/link-isomorphism.js +45 -0
- package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
- package/lib/remark-lint/translation-parity/shared.js +282 -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 +2 -0
- package/lib/remark-lint/translation-parity/url-residue.js +46 -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,194 @@
|
|
|
1
|
+
import path from 'node:path';
|
|
2
|
+
import { glob } from 'tinyglobby';
|
|
3
|
+
import { lintRule } from 'unified-lint-rule';
|
|
4
|
+
import { visitParents } from 'unist-util-visit-parents';
|
|
5
|
+
import { resolveStaticConfig } from "../utils/helpers.js";
|
|
6
|
+
import { getConfig } from "./utils.js";
|
|
7
|
+
const GVK_EXTENSION = 'x-kubernetes-group-version-kind';
|
|
8
|
+
const hasGvk = (schema) => !!schema && typeof schema === 'object' && GVK_EXTENSION in schema;
|
|
9
|
+
let sourcesPromise;
|
|
10
|
+
const loadYamlOrJson = async (base, patterns) => {
|
|
11
|
+
if (!patterns?.length) {
|
|
12
|
+
return [];
|
|
13
|
+
}
|
|
14
|
+
const files = await glob(patterns, { cwd: base });
|
|
15
|
+
const out = [];
|
|
16
|
+
for (const file of files) {
|
|
17
|
+
try {
|
|
18
|
+
out.push(await resolveStaticConfig(path.resolve(base, file)));
|
|
19
|
+
}
|
|
20
|
+
catch {
|
|
21
|
+
// A file that fails to parse is a source problem of its own; skip it here
|
|
22
|
+
// so a single bad file does not blind the whole check.
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
return out;
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* Reads a Kubernetes source that may be either a single resource or a
|
|
29
|
+
* `kind: List` wrapper.
|
|
30
|
+
*
|
|
31
|
+
* The permission plugin unwraps `items` when it builds the runtime module, so a
|
|
32
|
+
* check that reads `metadata.name` off the wrapper finds nothing at all and
|
|
33
|
+
* then reports every reference as unresolved.
|
|
34
|
+
*/
|
|
35
|
+
export const unwrapK8sList = (doc) => {
|
|
36
|
+
if (!doc || typeof doc !== 'object') {
|
|
37
|
+
return [];
|
|
38
|
+
}
|
|
39
|
+
const { items } = doc;
|
|
40
|
+
return Array.isArray(items) ? items : [doc];
|
|
41
|
+
};
|
|
42
|
+
const loadSources = async () => {
|
|
43
|
+
const { config, configFilePath } = await getConfig();
|
|
44
|
+
const base = configFilePath ? path.dirname(configFilePath) : config.root;
|
|
45
|
+
const crdNames = new Set();
|
|
46
|
+
const schemaNames = new Set();
|
|
47
|
+
const schemaNamesWithGvk = new Set();
|
|
48
|
+
const pathNames = new Set();
|
|
49
|
+
const functionNames = new Set();
|
|
50
|
+
const crds = await loadYamlOrJson(base, config.api?.crds);
|
|
51
|
+
for (const crd of crds) {
|
|
52
|
+
if (crd?.metadata?.name) {
|
|
53
|
+
crdNames.add(crd.metadata.name);
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
const openapis = await loadYamlOrJson(base, config.api?.openapis);
|
|
57
|
+
for (const doc of openapis) {
|
|
58
|
+
if (!doc) {
|
|
59
|
+
continue;
|
|
60
|
+
}
|
|
61
|
+
const components = doc.components;
|
|
62
|
+
// swagger 2.0 sources carry schemas under `definitions`.
|
|
63
|
+
const definitions = doc.definitions;
|
|
64
|
+
for (const [key, schema] of [
|
|
65
|
+
...Object.entries(components?.schemas ?? {}),
|
|
66
|
+
...Object.entries(definitions ?? {}),
|
|
67
|
+
]) {
|
|
68
|
+
schemaNames.add(key);
|
|
69
|
+
if (hasGvk(schema)) {
|
|
70
|
+
schemaNamesWithGvk.add(key);
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
for (const key of Object.keys(doc.paths ?? {})) {
|
|
74
|
+
pathNames.add(key);
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
const functionResourceDocs = await loadYamlOrJson(base, config.permission?.functionresources);
|
|
78
|
+
for (const doc of functionResourceDocs) {
|
|
79
|
+
for (const fr of unwrapK8sList(doc)) {
|
|
80
|
+
if (fr.metadata?.name) {
|
|
81
|
+
functionNames.add(fr.metadata.name);
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
// A name defined in several sources counts as resolvable as long as *one* of
|
|
86
|
+
// them carries the extension — the runtime stops at the first source that
|
|
87
|
+
// resolves, so flagging the others would be a false positive.
|
|
88
|
+
const schemaNamesWithoutGvk = new Set([...schemaNames].filter((name) => !schemaNamesWithGvk.has(name)));
|
|
89
|
+
return {
|
|
90
|
+
crdNames,
|
|
91
|
+
schemaNames,
|
|
92
|
+
schemaNamesWithoutGvk,
|
|
93
|
+
pathNames,
|
|
94
|
+
functionNames,
|
|
95
|
+
};
|
|
96
|
+
};
|
|
97
|
+
/** Collect static string values from a JSX attribute (string, `{'x'}` or `{['a','b']}`). */
|
|
98
|
+
const staticStrings = (attr) => {
|
|
99
|
+
if (!attr) {
|
|
100
|
+
return [];
|
|
101
|
+
}
|
|
102
|
+
if (typeof attr.value === 'string') {
|
|
103
|
+
return [attr.value];
|
|
104
|
+
}
|
|
105
|
+
const estree = attr.value?.data?.estree;
|
|
106
|
+
const expr = estree?.body[0];
|
|
107
|
+
if (!expr || expr.type !== 'ExpressionStatement') {
|
|
108
|
+
return [];
|
|
109
|
+
}
|
|
110
|
+
const node = expr.expression;
|
|
111
|
+
if (node.type === 'Literal' && typeof node.value === 'string') {
|
|
112
|
+
return [node.value];
|
|
113
|
+
}
|
|
114
|
+
if (node.type === 'ArrayExpression') {
|
|
115
|
+
return node.elements.flatMap((el) => el && el.type === 'Literal' && typeof el.value === 'string'
|
|
116
|
+
? [el.value]
|
|
117
|
+
: []);
|
|
118
|
+
}
|
|
119
|
+
// Anything dynamic (a variable, a computed value) cannot be validated here.
|
|
120
|
+
return [];
|
|
121
|
+
};
|
|
122
|
+
const attrOf = (element, name) => element.attributes.find((attr) => attr.type === 'mdxJsxAttribute' && attr.name === name);
|
|
123
|
+
/**
|
|
124
|
+
* The rule's decision logic, separated from source loading so it can be
|
|
125
|
+
* exercised against hand-built {@link ApiSources} in tests.
|
|
126
|
+
*/
|
|
127
|
+
export const checkApiRefs = (root, sources, report) => {
|
|
128
|
+
const { crdNames, schemaNames, schemaNamesWithoutGvk, pathNames, functionNames, } = sources;
|
|
129
|
+
visitParents(root, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (element, parents) => {
|
|
130
|
+
const reportAt = (message, attr) => {
|
|
131
|
+
report(message, (attr ?? element).position, [...parents, element]);
|
|
132
|
+
};
|
|
133
|
+
switch (element.name) {
|
|
134
|
+
case 'K8sAPI':
|
|
135
|
+
case 'K8sCrd': {
|
|
136
|
+
const attr = attrOf(element, 'name');
|
|
137
|
+
const name = staticStrings(attr)[0];
|
|
138
|
+
if (!name) {
|
|
139
|
+
break;
|
|
140
|
+
}
|
|
141
|
+
if (!crdNames.has(name) && !schemaNames.has(name)) {
|
|
142
|
+
reportAt(`\`<${element.name}>\` references \`name="${name}"\`, which resolves to neither a CRD (\`api.crds\`) nor an OpenAPI schema (\`api.openapis\`). The page would render blank.`, attr);
|
|
143
|
+
break;
|
|
144
|
+
}
|
|
145
|
+
// The endpoint paths need a group/version/kind. It comes from the
|
|
146
|
+
// schema's `x-kubernetes-group-version-kind` extension, else from a
|
|
147
|
+
// CRD of the same name, else it has to be declared by the caller —
|
|
148
|
+
// aggregation-layer OpenAPI documents routinely ship without the
|
|
149
|
+
// extension. Without any of the three the endpoints section is
|
|
150
|
+
// dropped at render time, which a green build would otherwise hide.
|
|
151
|
+
if (schemaNamesWithoutGvk.has(name) &&
|
|
152
|
+
!crdNames.has(name) &&
|
|
153
|
+
// A spread (`{...props}`) can carry the props unseen; do not guess.
|
|
154
|
+
!element.attributes.some((attribute) => attribute.type === 'mdxJsxExpressionAttribute') &&
|
|
155
|
+
!(attrOf(element, 'apiVersion') && attrOf(element, 'apiKind'))) {
|
|
156
|
+
reportAt(`\`<${element.name} name="${name}">\` resolves to an OpenAPI schema without the \`${GVK_EXTENSION}\` extension, and no CRD defines it, so its group/version/kind cannot be derived. Pass explicit \`apiVersion\` and \`apiKind\` props (plus \`apiGroup\` for non-core groups, and \`plural\` if the plural is irregular), or the API endpoints section is omitted.`, attr);
|
|
157
|
+
}
|
|
158
|
+
break;
|
|
159
|
+
}
|
|
160
|
+
case 'OpenAPIRef': {
|
|
161
|
+
const attr = attrOf(element, 'schema');
|
|
162
|
+
const name = staticStrings(attr)[0];
|
|
163
|
+
if (name && !schemaNames.has(name)) {
|
|
164
|
+
reportAt(`\`<OpenAPIRef>\` references \`schema="${name}"\`, which is not defined in any \`api.openapis\` source.`, attr);
|
|
165
|
+
}
|
|
166
|
+
break;
|
|
167
|
+
}
|
|
168
|
+
case 'OpenAPIPath': {
|
|
169
|
+
const attr = attrOf(element, 'path');
|
|
170
|
+
for (const p of staticStrings(attr)) {
|
|
171
|
+
if (!pathNames.has(p)) {
|
|
172
|
+
reportAt(`\`<OpenAPIPath>\` references \`path\` \`${p}\`, which is not defined in any \`api.openapis\` source.`, attr);
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
break;
|
|
176
|
+
}
|
|
177
|
+
case 'K8sPermissionTable': {
|
|
178
|
+
const attr = attrOf(element, 'functions');
|
|
179
|
+
for (const fn of staticStrings(attr)) {
|
|
180
|
+
if (!functionNames.has(fn)) {
|
|
181
|
+
reportAt(`\`<K8sPermissionTable>\` references function \`${fn}\`, which is not a known FunctionResource (\`permission.functionresources\`). Its row would silently vanish.`, attr);
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
break;
|
|
185
|
+
}
|
|
186
|
+
default:
|
|
187
|
+
break;
|
|
188
|
+
}
|
|
189
|
+
});
|
|
190
|
+
};
|
|
191
|
+
export const noUnresolvedApiRef = lintRule('doom-lint:no-unresolved-api-ref', async (root, vfile) => {
|
|
192
|
+
const sources = await (sourcesPromise ??= loadSources());
|
|
193
|
+
checkApiRefs(root, sources, (message, place, ancestors) => vfile.message(message, { ancestors, place }));
|
|
194
|
+
});
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import type { Plugin } from 'unified';
|
|
2
|
+
/**
|
|
3
|
+
* The lint pipeline, in one place, so `doom lint` and the translator cannot
|
|
4
|
+
* drift apart.
|
|
5
|
+
*
|
|
6
|
+
* The translator checks its own output with the rules `doom lint` runs — that
|
|
7
|
+
* is the point of expressing translation checks as lint rules rather than as a
|
|
8
|
+
* second checking system. A rule anyone adds here starts guarding
|
|
9
|
+
* machine-translated documents on the same day, without anyone remembering to
|
|
10
|
+
* register it twice.
|
|
11
|
+
*/
|
|
12
|
+
type Rule = Plugin<[], never>;
|
|
13
|
+
/** Syntax plugins every rule needs before it can run. */
|
|
14
|
+
export declare const SYNTAX_PLUGINS: Rule[];
|
|
15
|
+
/**
|
|
16
|
+
* Rules that compare a translation with the source it was made from.
|
|
17
|
+
*
|
|
18
|
+
* Listed separately only so the ordering constraint below can be stated; they
|
|
19
|
+
* are members of {@link LINT_RULES} like every other rule.
|
|
20
|
+
*/
|
|
21
|
+
export declare const TRANSLATION_PARITY_RULES: Rule[];
|
|
22
|
+
/**
|
|
23
|
+
* Rules whose verdict depends on documents other than the one being linted: the
|
|
24
|
+
* site's route table, the generated API modules, the configured sibling sites,
|
|
25
|
+
* the headings of whatever a link points at.
|
|
26
|
+
*
|
|
27
|
+
* The translator skips these. Two things have to both hold before a rule
|
|
28
|
+
* belongs here:
|
|
29
|
+
*
|
|
30
|
+
* 1. **It reads a tree that is mid-write.** `checkDeadLinks` builds its route
|
|
31
|
+
* table by scanning the docs directory. During a translation run the target
|
|
32
|
+
* language directory is still being filled in, so a link to a page whose
|
|
33
|
+
* translation has not been written yet resolves to nothing — a red that says
|
|
34
|
+
* only "this file was translated before that one".
|
|
35
|
+
* 2. **The translator could not act on it anyway.** Link targets, `href`s,
|
|
36
|
+
* heading anchors and api references are masked before the model sees the
|
|
37
|
+
* document, so they come back byte-identical to the source by construction,
|
|
38
|
+
* and `link-isomorphism` proves that separately. A dead link in a
|
|
39
|
+
* translation is a dead link in the source, and it belongs to whoever lints
|
|
40
|
+
* the source.
|
|
41
|
+
*
|
|
42
|
+
* `no-unmatched-anchor` is here on evidence rather than on principle. The first
|
|
43
|
+
* real translation run failed `zh/install/installing.mdx` over an anchor in
|
|
44
|
+
* `install/prepare/download.mdx` — a *different* document, whose stale
|
|
45
|
+
* translation had lost the heading that carries it. Nothing about the document
|
|
46
|
+
* being translated was wrong, the link and its anchor were both masked, and no
|
|
47
|
+
* repair round could have changed the outcome. A red like that costs turns and
|
|
48
|
+
* then blames the wrong file.
|
|
49
|
+
*
|
|
50
|
+
* They all still run in `doom lint`, over a docs tree that is complete.
|
|
51
|
+
*/
|
|
52
|
+
export declare const ROUTE_DEPENDENT_RULES: Rule[];
|
|
53
|
+
/**
|
|
54
|
+
* Every rule, in the order they must run.
|
|
55
|
+
*
|
|
56
|
+
* Two orderings are load-bearing:
|
|
57
|
+
*
|
|
58
|
+
* - the two Chinese-typography rules before `chineseTypographyOnlyInChinese`,
|
|
59
|
+
* which drops their messages on documents that are not Chinese;
|
|
60
|
+
* - every pairwise rule before `checkDeadLinks`, which rewrites link urls in
|
|
61
|
+
* the tree as a side effect of asking rspress to resolve them. A pairwise
|
|
62
|
+
* rule running after it compares a rewritten translation against an
|
|
63
|
+
* unrewritten source and reports every link in the corpus.
|
|
64
|
+
*/
|
|
65
|
+
export declare const LINT_RULES: Rule[];
|
|
66
|
+
/**
|
|
67
|
+
* What the translator checks its output with: every rule except the ones that
|
|
68
|
+
* need a docs tree it is in the middle of writing.
|
|
69
|
+
*
|
|
70
|
+
* Derived by subtraction rather than by listing, so a rule added to
|
|
71
|
+
* {@link LINT_RULES} joins the translation loop automatically — and keeps its
|
|
72
|
+
* position, which some of the orderings above depend on.
|
|
73
|
+
*/
|
|
74
|
+
export declare const TRANSLATION_CHECK_RULES: Rule[];
|
|
75
|
+
export {};
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import remarkDirective from 'remark-directive';
|
|
2
|
+
import remarkFrontmatter from 'remark-frontmatter';
|
|
3
|
+
import remarkGfm from 'remark-gfm';
|
|
4
|
+
// @ts-expect-error -- https://github.com/ilyatitovich/remark-lint-code-block-split-list/issues/2
|
|
5
|
+
import remarkLintCodeBlockSplitList from 'remark-lint-code-block-split-list';
|
|
6
|
+
import remarkLintHeadingIncrement from 'remark-lint-heading-increment';
|
|
7
|
+
// @ts-expect-error -- https://github.com/laysent/remark-lint-plugins/issues/51
|
|
8
|
+
import remarkLintLintMatchPunctuation from 'remark-lint-match-punctuation';
|
|
9
|
+
// @ts-expect-error -- https://github.com/laysent/remark-lint-plugins/issues/51
|
|
10
|
+
import remarkLintNoChinesePunctuationInNumber from 'remark-lint-no-chinese-punctuation-in-number';
|
|
11
|
+
import remarkLintNoDuplicateHeadingsInSection from 'remark-lint-no-duplicate-headings-in-section';
|
|
12
|
+
import remarkLintNoHiddenTableCell from 'remark-lint-no-hidden-table-cell';
|
|
13
|
+
import { checkDeadLinks, chineseTypographyOnlyInChinese, headingAnchorFormat, noDeepHeading, noDeepList, noLegacyOSNames, noMultiOpenAPIPaths, noParagraphIndent, noUnmatchedAnchor, noUnopenedFrontmatter, noUnparsedEmphasis, noUnresolvedApiRef, site, tableSize, titleRequired, translationComponentMultiset, translationEchoedSource, translationFrontmatterPreservation, translationHeadingSequence, translationJsxAttributeParity, translationLengthRatio, translationLinkIsomorphism, translationUpToDate, translationUrlResidue, unitCase, } from "./index.js";
|
|
14
|
+
/** Syntax plugins every rule needs before it can run. */
|
|
15
|
+
export const SYNTAX_PLUGINS = [
|
|
16
|
+
remarkDirective,
|
|
17
|
+
remarkFrontmatter,
|
|
18
|
+
remarkGfm,
|
|
19
|
+
];
|
|
20
|
+
/**
|
|
21
|
+
* Rules that compare a translation with the source it was made from.
|
|
22
|
+
*
|
|
23
|
+
* Listed separately only so the ordering constraint below can be stated; they
|
|
24
|
+
* are members of {@link LINT_RULES} like every other rule.
|
|
25
|
+
*/
|
|
26
|
+
export const TRANSLATION_PARITY_RULES = [
|
|
27
|
+
// Whether the pair is comparable at all comes first: nothing after it means
|
|
28
|
+
// anything otherwise.
|
|
29
|
+
translationUpToDate,
|
|
30
|
+
translationComponentMultiset,
|
|
31
|
+
translationFrontmatterPreservation,
|
|
32
|
+
translationHeadingSequence,
|
|
33
|
+
translationJsxAttributeParity,
|
|
34
|
+
translationLengthRatio,
|
|
35
|
+
translationLinkIsomorphism,
|
|
36
|
+
translationEchoedSource,
|
|
37
|
+
translationUrlResidue,
|
|
38
|
+
];
|
|
39
|
+
/**
|
|
40
|
+
* Rules whose verdict depends on documents other than the one being linted: the
|
|
41
|
+
* site's route table, the generated API modules, the configured sibling sites,
|
|
42
|
+
* the headings of whatever a link points at.
|
|
43
|
+
*
|
|
44
|
+
* The translator skips these. Two things have to both hold before a rule
|
|
45
|
+
* belongs here:
|
|
46
|
+
*
|
|
47
|
+
* 1. **It reads a tree that is mid-write.** `checkDeadLinks` builds its route
|
|
48
|
+
* table by scanning the docs directory. During a translation run the target
|
|
49
|
+
* language directory is still being filled in, so a link to a page whose
|
|
50
|
+
* translation has not been written yet resolves to nothing — a red that says
|
|
51
|
+
* only "this file was translated before that one".
|
|
52
|
+
* 2. **The translator could not act on it anyway.** Link targets, `href`s,
|
|
53
|
+
* heading anchors and api references are masked before the model sees the
|
|
54
|
+
* document, so they come back byte-identical to the source by construction,
|
|
55
|
+
* and `link-isomorphism` proves that separately. A dead link in a
|
|
56
|
+
* translation is a dead link in the source, and it belongs to whoever lints
|
|
57
|
+
* the source.
|
|
58
|
+
*
|
|
59
|
+
* `no-unmatched-anchor` is here on evidence rather than on principle. The first
|
|
60
|
+
* real translation run failed `zh/install/installing.mdx` over an anchor in
|
|
61
|
+
* `install/prepare/download.mdx` — a *different* document, whose stale
|
|
62
|
+
* translation had lost the heading that carries it. Nothing about the document
|
|
63
|
+
* being translated was wrong, the link and its anchor were both masked, and no
|
|
64
|
+
* repair round could have changed the outcome. A red like that costs turns and
|
|
65
|
+
* then blames the wrong file.
|
|
66
|
+
*
|
|
67
|
+
* They all still run in `doom lint`, over a docs tree that is complete.
|
|
68
|
+
*/
|
|
69
|
+
export const ROUTE_DEPENDENT_RULES = [
|
|
70
|
+
checkDeadLinks,
|
|
71
|
+
noUnmatchedAnchor,
|
|
72
|
+
noUnresolvedApiRef,
|
|
73
|
+
site,
|
|
74
|
+
];
|
|
75
|
+
/**
|
|
76
|
+
* Every rule, in the order they must run.
|
|
77
|
+
*
|
|
78
|
+
* Two orderings are load-bearing:
|
|
79
|
+
*
|
|
80
|
+
* - the two Chinese-typography rules before `chineseTypographyOnlyInChinese`,
|
|
81
|
+
* which drops their messages on documents that are not Chinese;
|
|
82
|
+
* - every pairwise rule before `checkDeadLinks`, which rewrites link urls in
|
|
83
|
+
* the tree as a side effect of asking rspress to resolve them. A pairwise
|
|
84
|
+
* rule running after it compares a rewritten translation against an
|
|
85
|
+
* unrewritten source and reports every link in the corpus.
|
|
86
|
+
*/
|
|
87
|
+
export const LINT_RULES = [
|
|
88
|
+
remarkLintCodeBlockSplitList,
|
|
89
|
+
remarkLintHeadingIncrement,
|
|
90
|
+
remarkLintLintMatchPunctuation,
|
|
91
|
+
remarkLintNoChinesePunctuationInNumber,
|
|
92
|
+
remarkLintNoDuplicateHeadingsInSection,
|
|
93
|
+
remarkLintNoHiddenTableCell,
|
|
94
|
+
chineseTypographyOnlyInChinese,
|
|
95
|
+
...TRANSLATION_PARITY_RULES,
|
|
96
|
+
checkDeadLinks,
|
|
97
|
+
headingAnchorFormat,
|
|
98
|
+
noDeepHeading,
|
|
99
|
+
noDeepList,
|
|
100
|
+
noLegacyOSNames,
|
|
101
|
+
noMultiOpenAPIPaths,
|
|
102
|
+
noParagraphIndent,
|
|
103
|
+
noUnmatchedAnchor,
|
|
104
|
+
noUnopenedFrontmatter,
|
|
105
|
+
noUnparsedEmphasis,
|
|
106
|
+
noUnresolvedApiRef,
|
|
107
|
+
site,
|
|
108
|
+
tableSize,
|
|
109
|
+
titleRequired,
|
|
110
|
+
unitCase,
|
|
111
|
+
];
|
|
112
|
+
/**
|
|
113
|
+
* What the translator checks its output with: every rule except the ones that
|
|
114
|
+
* need a docs tree it is in the middle of writing.
|
|
115
|
+
*
|
|
116
|
+
* Derived by subtraction rather than by listing, so a rule added to
|
|
117
|
+
* {@link LINT_RULES} joins the translation loop automatically — and keeps its
|
|
118
|
+
* position, which some of the orderings above depend on.
|
|
119
|
+
*/
|
|
120
|
+
export const TRANSLATION_CHECK_RULES = LINT_RULES.filter((rule) => !ROUTE_DEPENDENT_RULES.includes(rule));
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { Root } from 'mdast';
|
|
2
|
+
/**
|
|
3
|
+
* A translation uses exactly the components its source uses.
|
|
4
|
+
*
|
|
5
|
+
* A component is a thing on the page — a term, a callout, a link to another
|
|
6
|
+
* site — not a turn of phrase, so translating a page never adds or removes one.
|
|
7
|
+
* When the count differs, something was dropped or invented; both of the
|
|
8
|
+
* content-loss defects that opened this work were caught this way, and by
|
|
9
|
+
* nothing else:
|
|
10
|
+
*
|
|
11
|
+
* - `zh/extend/cluster_plugin.mdx`: two bullets in English, one in Chinese —
|
|
12
|
+
* the sentence telling readers without Customer Portal access to contact
|
|
13
|
+
* support was simply gone, and it happened to contain a `<Term>`.
|
|
14
|
+
* - `ru/install/installing.mdx`: the product name dropped out of the opening
|
|
15
|
+
* sentence of the installation guide.
|
|
16
|
+
*/
|
|
17
|
+
export declare const translationComponentMultiset: import("unified-lint-rule").Plugin<Root, unknown>;
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { lintRule } from 'unified-lint-rule';
|
|
2
|
+
import { collectComponents, currentPair } from "./shared.js";
|
|
3
|
+
/**
|
|
4
|
+
* A translation uses exactly the components its source uses.
|
|
5
|
+
*
|
|
6
|
+
* A component is a thing on the page — a term, a callout, a link to another
|
|
7
|
+
* site — not a turn of phrase, so translating a page never adds or removes one.
|
|
8
|
+
* When the count differs, something was dropped or invented; both of the
|
|
9
|
+
* content-loss defects that opened this work were caught this way, and by
|
|
10
|
+
* nothing else:
|
|
11
|
+
*
|
|
12
|
+
* - `zh/extend/cluster_plugin.mdx`: two bullets in English, one in Chinese —
|
|
13
|
+
* the sentence telling readers without Customer Portal access to contact
|
|
14
|
+
* support was simply gone, and it happened to contain a `<Term>`.
|
|
15
|
+
* - `ru/install/installing.mdx`: the product name dropped out of the opening
|
|
16
|
+
* sentence of the installation guide.
|
|
17
|
+
*/
|
|
18
|
+
export const translationComponentMultiset = lintRule('doom-lint:translation-component-multiset', async (tree, vfile) => {
|
|
19
|
+
const pair = await currentPair(tree, vfile);
|
|
20
|
+
if (!pair) {
|
|
21
|
+
return;
|
|
22
|
+
}
|
|
23
|
+
const expected = collectComponents(pair.sourceTree);
|
|
24
|
+
const actual = collectComponents(tree);
|
|
25
|
+
for (const name of new Set([...expected.keys(), ...actual.keys()])) {
|
|
26
|
+
const want = expected.get(name) ?? 0;
|
|
27
|
+
const got = actual.get(name) ?? 0;
|
|
28
|
+
if (want === got) {
|
|
29
|
+
continue;
|
|
30
|
+
}
|
|
31
|
+
vfile.message(got < want
|
|
32
|
+
? `Translation dropped ${want - got} \`<${name}>\` (source has ${want}, this has ${got}) — content that was in the source is missing here.`
|
|
33
|
+
: `Translation invented ${got - want} \`<${name}>\` (source has ${want}, this has ${got}).`, tree);
|
|
34
|
+
}
|
|
35
|
+
});
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { lintRule } from 'unified-lint-rule';
|
|
2
|
+
import { collectProseText, currentPair } from "./shared.js";
|
|
3
|
+
/**
|
|
4
|
+
* A translation must not be the source.
|
|
5
|
+
*
|
|
6
|
+
* The failure is the model handing back what it was given: frontmatter title
|
|
7
|
+
* and description come out translated — those are produced separately — while
|
|
8
|
+
* the body is returned verbatim. Every structural check is satisfied by this,
|
|
9
|
+
* because structurally it *is* the source: same links, same components, same
|
|
10
|
+
* headings, same length.
|
|
11
|
+
*
|
|
12
|
+
* The test is prose identity rather than "how much of it looks Chinese".
|
|
13
|
+
* Sampling the script does not work: reference pages in this corpus run as low
|
|
14
|
+
* as 2% native characters and are perfectly good translations — they are mostly
|
|
15
|
+
* field names — so any threshold that catches an echo also condemns them.
|
|
16
|
+
* Identity has no threshold to get wrong, and on 1050 real pairs it selected
|
|
17
|
+
* exactly three documents, all three of them genuinely untranslated.
|
|
18
|
+
*
|
|
19
|
+
* What it deliberately does not catch is a *partly* echoed document. That needs
|
|
20
|
+
* a reader, not a comparison.
|
|
21
|
+
*/
|
|
22
|
+
const normalise = (text) => text.replace(/\s+/g, ' ').trim();
|
|
23
|
+
/** Below this, identity means the page is a heading and a component. */
|
|
24
|
+
const MIN_PROSE_CHARS = 200;
|
|
25
|
+
export const translationEchoedSource = lintRule('doom-lint:translation-echoed-source', async (tree, vfile) => {
|
|
26
|
+
const pair = await currentPair(tree, vfile);
|
|
27
|
+
if (!pair || pair.isCopyOnly) {
|
|
28
|
+
return;
|
|
29
|
+
}
|
|
30
|
+
const source = normalise(collectProseText(pair.sourceTree));
|
|
31
|
+
if (source.length < MIN_PROSE_CHARS) {
|
|
32
|
+
return;
|
|
33
|
+
}
|
|
34
|
+
if (normalise(collectProseText(tree)) === source) {
|
|
35
|
+
vfile.message(`Translation is the source: every word of prose came back unchanged in ${pair.sourceLang}. The model echoed the document instead of translating it.`, tree);
|
|
36
|
+
}
|
|
37
|
+
});
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { lintRule } from 'unified-lint-rule';
|
|
2
|
+
import { currentPair } from "./shared.js";
|
|
3
|
+
/**
|
|
4
|
+
* Frontmatter is configuration, not copy.
|
|
5
|
+
*
|
|
6
|
+
* `weight` orders the sidebar, `sourceSHA` pairs the document with its source,
|
|
7
|
+
* `i18n` and the rest steer the build. Only `title` and `description` are read
|
|
8
|
+
* by a human, and only those two are translated. Anything else that differs
|
|
9
|
+
* between a source and its translation changes how the site is built for one
|
|
10
|
+
* language and not the other.
|
|
11
|
+
*/
|
|
12
|
+
const TRANSLATED_KEYS = new Set(['title', 'description']);
|
|
13
|
+
// `sourceSHA` is written by the translator and `i18n` is deliberately dropped
|
|
14
|
+
// from the translation — neither is a divergence.
|
|
15
|
+
const TRANSLATOR_OWNED_KEYS = new Set(['sourceSHA', 'i18n']);
|
|
16
|
+
export const translationFrontmatterPreservation = lintRule('doom-lint:translation-frontmatter-preservation', async (tree, vfile) => {
|
|
17
|
+
const pair = await currentPair(tree, vfile);
|
|
18
|
+
if (!pair) {
|
|
19
|
+
return;
|
|
20
|
+
}
|
|
21
|
+
const keys = new Set([
|
|
22
|
+
...Object.keys(pair.sourceFrontmatter),
|
|
23
|
+
...Object.keys(pair.targetFrontmatter),
|
|
24
|
+
]);
|
|
25
|
+
for (const key of keys) {
|
|
26
|
+
if (TRANSLATED_KEYS.has(key) || TRANSLATOR_OWNED_KEYS.has(key)) {
|
|
27
|
+
continue;
|
|
28
|
+
}
|
|
29
|
+
const expected = JSON.stringify(pair.sourceFrontmatter[key] ?? null);
|
|
30
|
+
const actual = JSON.stringify(pair.targetFrontmatter[key] ?? null);
|
|
31
|
+
if (expected === actual) {
|
|
32
|
+
continue;
|
|
33
|
+
}
|
|
34
|
+
vfile.message(`Translation changed frontmatter \`${key}\`: source has ${expected}, this has ${actual}. Only \`title\` and \`description\` are translated.`, tree);
|
|
35
|
+
}
|
|
36
|
+
});
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { Root } from 'mdast';
|
|
2
|
+
/**
|
|
3
|
+
* A translation keeps its source's heading structure.
|
|
4
|
+
*
|
|
5
|
+
* Headings are the page's skeleton and its anchors: a lost or promoted heading
|
|
6
|
+
* silently changes the table of contents and breaks every link that pointed at
|
|
7
|
+
* it. Translating the text of a heading never changes its level.
|
|
8
|
+
*
|
|
9
|
+
* Honest caveat: this has never fired on real damage in this corpus (0 of 1764
|
|
10
|
+
* pairs). It is a regression guard, not a demonstrated detector.
|
|
11
|
+
*/
|
|
12
|
+
export declare const translationHeadingSequence: import("unified-lint-rule").Plugin<Root, unknown>;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { lintRule } from 'unified-lint-rule';
|
|
2
|
+
import { collectHeadingDepths, currentPair } from "./shared.js";
|
|
3
|
+
/**
|
|
4
|
+
* A translation keeps its source's heading structure.
|
|
5
|
+
*
|
|
6
|
+
* Headings are the page's skeleton and its anchors: a lost or promoted heading
|
|
7
|
+
* silently changes the table of contents and breaks every link that pointed at
|
|
8
|
+
* it. Translating the text of a heading never changes its level.
|
|
9
|
+
*
|
|
10
|
+
* Honest caveat: this has never fired on real damage in this corpus (0 of 1764
|
|
11
|
+
* pairs). It is a regression guard, not a demonstrated detector.
|
|
12
|
+
*/
|
|
13
|
+
export const translationHeadingSequence = lintRule('doom-lint:translation-heading-sequence', async (tree, vfile) => {
|
|
14
|
+
const pair = await currentPair(tree, vfile);
|
|
15
|
+
if (!pair) {
|
|
16
|
+
return;
|
|
17
|
+
}
|
|
18
|
+
const expected = collectHeadingDepths(pair.sourceTree);
|
|
19
|
+
const actual = collectHeadingDepths(tree);
|
|
20
|
+
if (expected.length === actual.length &&
|
|
21
|
+
expected.every((depth, index) => depth === actual[index])) {
|
|
22
|
+
return;
|
|
23
|
+
}
|
|
24
|
+
vfile.message(`Translation changed the heading structure: source is ${expected.join('-') || '(none)'}, this is ${actual.join('-') || '(none)'}.`, tree);
|
|
25
|
+
});
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Checks that compare a translation with the source it was made from.
|
|
3
|
+
*
|
|
4
|
+
* Ordinary lint rules read one document; these read two. That is the only thing
|
|
5
|
+
* that separates them, and it is why they live together: the pairing logic and
|
|
6
|
+
* the "say nothing when the pair is not trustworthy" discipline are shared, in
|
|
7
|
+
* `shared.ts`.
|
|
8
|
+
*
|
|
9
|
+
* They are ordinary lint rules in every other respect — same engine, same
|
|
10
|
+
* `<!-- lint disable -->` control, same editor integration — so a translation
|
|
11
|
+
* problem someone notices becomes a rule here, and hand-written documents get
|
|
12
|
+
* the benefit of it too. There is deliberately not a second checking system for
|
|
13
|
+
* translations.
|
|
14
|
+
*/
|
|
15
|
+
export * from './component-multiset.ts';
|
|
16
|
+
export * from './echoed-source.ts';
|
|
17
|
+
export * from './frontmatter-preservation.ts';
|
|
18
|
+
export * from './heading-sequence.ts';
|
|
19
|
+
export * from './jsx-attribute-parity.ts';
|
|
20
|
+
export * from './length-ratio.ts';
|
|
21
|
+
export * from './link-isomorphism.ts';
|
|
22
|
+
export * from './terminology-adherence.ts';
|
|
23
|
+
export * from './up-to-date.ts';
|
|
24
|
+
export * from './url-residue.ts';
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Checks that compare a translation with the source it was made from.
|
|
3
|
+
*
|
|
4
|
+
* Ordinary lint rules read one document; these read two. That is the only thing
|
|
5
|
+
* that separates them, and it is why they live together: the pairing logic and
|
|
6
|
+
* the "say nothing when the pair is not trustworthy" discipline are shared, in
|
|
7
|
+
* `shared.ts`.
|
|
8
|
+
*
|
|
9
|
+
* They are ordinary lint rules in every other respect — same engine, same
|
|
10
|
+
* `<!-- lint disable -->` control, same editor integration — so a translation
|
|
11
|
+
* problem someone notices becomes a rule here, and hand-written documents get
|
|
12
|
+
* the benefit of it too. There is deliberately not a second checking system for
|
|
13
|
+
* translations.
|
|
14
|
+
*/
|
|
15
|
+
export * from "./component-multiset.js";
|
|
16
|
+
export * from "./echoed-source.js";
|
|
17
|
+
export * from "./frontmatter-preservation.js";
|
|
18
|
+
export * from "./heading-sequence.js";
|
|
19
|
+
export * from "./jsx-attribute-parity.js";
|
|
20
|
+
export * from "./length-ratio.js";
|
|
21
|
+
export * from "./link-isomorphism.js";
|
|
22
|
+
export * from "./terminology-adherence.js";
|
|
23
|
+
export * from "./up-to-date.js";
|
|
24
|
+
export * from "./url-residue.js";
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { Root } from 'mdast';
|
|
2
|
+
/**
|
|
3
|
+
* Component attributes are identifiers, and identifiers survive translation
|
|
4
|
+
* unchanged.
|
|
5
|
+
*
|
|
6
|
+
* `<Term name="productShort" />`, `<K8sAPI name="backups.velero.io" />`,
|
|
7
|
+
* `<OpenAPIPath path="/v1/alerthistories" />` — none of these is prose, and a
|
|
8
|
+
* translation that changes one produces a page that renders wrong while the
|
|
9
|
+
* build stays green. The exceptions are declared in one place,
|
|
10
|
+
* `runtime/components/_translation-policy.ts`, and are the same list the
|
|
11
|
+
* translator's masking uses: what may be translated is exactly what is not
|
|
12
|
+
* protected.
|
|
13
|
+
*/
|
|
14
|
+
export declare const translationJsxAttributeParity: import("unified-lint-rule").Plugin<Root, unknown>;
|