@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.
Files changed (93) hide show
  1. package/lib/cli/api.d.ts +2 -0
  2. package/lib/cli/api.js +147 -0
  3. package/lib/cli/helpers.d.ts +1 -7
  4. package/lib/cli/helpers.js +4 -41
  5. package/lib/cli/index.js +2 -0
  6. package/lib/cli/translate-agent.d.ts +81 -0
  7. package/lib/cli/translate-agent.js +450 -0
  8. package/lib/cli/translate-check.d.ts +17 -0
  9. package/lib/cli/translate-check.js +67 -0
  10. package/lib/cli/translate-checker.d.ts +58 -0
  11. package/lib/cli/translate-checker.js +112 -0
  12. package/lib/cli/translate-judge.d.ts +119 -0
  13. package/lib/cli/translate-judge.js +224 -0
  14. package/lib/cli/translate-limits.d.ts +43 -0
  15. package/lib/cli/translate-limits.js +55 -0
  16. package/lib/cli/translate-mask.d.ts +144 -0
  17. package/lib/cli/translate-mask.js +617 -0
  18. package/lib/cli/translate-models.d.ts +127 -0
  19. package/lib/cli/translate-models.js +189 -0
  20. package/lib/cli/translate-scratch.d.ts +142 -0
  21. package/lib/cli/translate-scratch.js +187 -0
  22. package/lib/cli/translate-terms.d.ts +22 -0
  23. package/lib/cli/translate-terms.js +33 -0
  24. package/lib/cli/translate.d.ts +15 -10
  25. package/lib/cli/translate.js +228 -185
  26. package/lib/eslint.js +48 -5
  27. package/lib/plugins/api/index.js +1 -1
  28. package/lib/plugins/api/types.d.ts +36 -1
  29. package/lib/plugins/global/components.d.ts +18 -0
  30. package/lib/plugins/global/components.js +33 -0
  31. package/lib/plugins/global/index.js +2 -10
  32. package/lib/remark-lint/index.d.ts +20 -0
  33. package/lib/remark-lint/index.js +40 -0
  34. package/lib/remark-lint/no-unmatched-anchor.d.ts +10 -0
  35. package/lib/remark-lint/no-unmatched-anchor.js +13 -0
  36. package/lib/remark-lint/no-unopened-frontmatter.d.ts +2 -0
  37. package/lib/remark-lint/no-unopened-frontmatter.js +70 -0
  38. package/lib/remark-lint/no-unparsed-emphasis.d.ts +2 -0
  39. package/lib/remark-lint/no-unparsed-emphasis.js +53 -0
  40. package/lib/remark-lint/no-unresolved-api-ref.d.ts +40 -0
  41. package/lib/remark-lint/no-unresolved-api-ref.js +194 -0
  42. package/lib/remark-lint/rule-sets.d.ts +75 -0
  43. package/lib/remark-lint/rule-sets.js +120 -0
  44. package/lib/remark-lint/translation-parity/component-multiset.d.ts +17 -0
  45. package/lib/remark-lint/translation-parity/component-multiset.js +35 -0
  46. package/lib/remark-lint/translation-parity/echoed-source.d.ts +2 -0
  47. package/lib/remark-lint/translation-parity/echoed-source.js +37 -0
  48. package/lib/remark-lint/translation-parity/frontmatter-preservation.d.ts +2 -0
  49. package/lib/remark-lint/translation-parity/frontmatter-preservation.js +36 -0
  50. package/lib/remark-lint/translation-parity/heading-sequence.d.ts +12 -0
  51. package/lib/remark-lint/translation-parity/heading-sequence.js +25 -0
  52. package/lib/remark-lint/translation-parity/index.d.ts +24 -0
  53. package/lib/remark-lint/translation-parity/index.js +24 -0
  54. package/lib/remark-lint/translation-parity/jsx-attribute-parity.d.ts +14 -0
  55. package/lib/remark-lint/translation-parity/jsx-attribute-parity.js +47 -0
  56. package/lib/remark-lint/translation-parity/length-ratio.d.ts +2 -0
  57. package/lib/remark-lint/translation-parity/length-ratio.js +49 -0
  58. package/lib/remark-lint/translation-parity/link-isomorphism.d.ts +26 -0
  59. package/lib/remark-lint/translation-parity/link-isomorphism.js +45 -0
  60. package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
  61. package/lib/remark-lint/translation-parity/shared.js +282 -0
  62. package/lib/remark-lint/translation-parity/terminology-adherence.d.ts +2 -0
  63. package/lib/remark-lint/translation-parity/terminology-adherence.js +67 -0
  64. package/lib/remark-lint/translation-parity/up-to-date.d.ts +11 -0
  65. package/lib/remark-lint/translation-parity/up-to-date.js +21 -0
  66. package/lib/remark-lint/translation-parity/url-residue.d.ts +2 -0
  67. package/lib/remark-lint/translation-parity/url-residue.js +46 -0
  68. package/lib/remarkrc.d.ts +1 -1
  69. package/lib/remarkrc.js +7 -34
  70. package/lib/runtime/api-paths.d.ts +20 -0
  71. package/lib/runtime/api-paths.js +29 -0
  72. package/lib/runtime/components/K8sAPI.d.ts +14 -1
  73. package/lib/runtime/components/K8sAPI.js +49 -10
  74. package/lib/runtime/components/K8sCrd.d.ts +1 -1
  75. package/lib/runtime/components/K8sPermissionTable.js +10 -5
  76. package/lib/runtime/components/OpenAPIPath.js +19 -2
  77. package/lib/runtime/components/_HeadingTitle.js +24 -6
  78. package/lib/runtime/components/_K8sAPIEndpoints.d.ts +8 -1
  79. package/lib/runtime/components/_K8sAPIEndpoints.js +27 -9
  80. package/lib/runtime/components/_K8sAPISchema.d.ts +9 -1
  81. package/lib/runtime/components/_K8sAPISchema.js +24 -6
  82. package/lib/runtime/components/_translation-policy.d.ts +23 -0
  83. package/lib/runtime/components/_translation-policy.js +32 -0
  84. package/lib/runtime/hooks/useTranslation.d.ts +1 -1
  85. package/lib/runtime/translation.d.ts +68 -0
  86. package/lib/runtime/translation.js +51 -0
  87. package/lib/runtime/utils.d.ts +24 -2
  88. package/lib/runtime/utils.js +87 -5
  89. package/lib/shared/constants.d.ts +9 -0
  90. package/lib/shared/constants.js +14 -0
  91. package/lib/types.d.ts +70 -0
  92. package/lib/utils/helpers.js +8 -2
  93. 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,2 @@
1
+ import type { Root } from 'mdast';
2
+ export declare const translationEchoedSource: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -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,2 @@
1
+ import type { Root } from 'mdast';
2
+ export declare const translationFrontmatterPreservation: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -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>;