@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,47 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { TRANSLATABLE_JSX_ATTRS } from "../../runtime/components/_translation-policy.js";
3
+ import { collectJsxAttributes, currentPair, diffMultiset } from "./shared.js";
4
+ /**
5
+ * `src` and `href` are compared by `translation-link-isomorphism` instead,
6
+ * which resolves them first. They legitimately differ as *written*: assets are
7
+ * not copied per language, so a translation points back into the source tree —
8
+ * `../../../en/networking/x.png` where the source says `./x.png`. Both name the
9
+ * same file. Comparing the strings reports every illustrated page in the
10
+ * corpus, which is what it did before this exemption existed.
11
+ */
12
+ const RESOLVED_ELSEWHERE = new Set(['href', 'src']);
13
+ const isExempt = (key) => {
14
+ const [element, attribute] = key.split('.');
15
+ return (RESOLVED_ELSEWHERE.has(attribute) ||
16
+ !!TRANSLATABLE_JSX_ATTRS[element]?.includes(attribute));
17
+ };
18
+ /**
19
+ * Component attributes are identifiers, and identifiers survive translation
20
+ * unchanged.
21
+ *
22
+ * `<Term name="productShort" />`, `<K8sAPI name="backups.velero.io" />`,
23
+ * `<OpenAPIPath path="/v1/alerthistories" />` — none of these is prose, and a
24
+ * translation that changes one produces a page that renders wrong while the
25
+ * build stays green. The exceptions are declared in one place,
26
+ * `runtime/components/_translation-policy.ts`, and are the same list the
27
+ * translator's masking uses: what may be translated is exactly what is not
28
+ * protected.
29
+ */
30
+ export const translationJsxAttributeParity = lintRule('doom-lint:translation-jsx-attribute-parity', async (tree, vfile) => {
31
+ const pair = await currentPair(tree, vfile);
32
+ if (!pair) {
33
+ return;
34
+ }
35
+ const expected = collectJsxAttributes(pair.sourceTree);
36
+ const actual = collectJsxAttributes(tree);
37
+ for (const key of new Set([...expected.keys(), ...actual.keys()])) {
38
+ if (isExempt(key)) {
39
+ continue;
40
+ }
41
+ const { missing, extra } = diffMultiset(expected.get(key) ?? [], actual.get(key) ?? []);
42
+ if (!missing.length && !extra.length) {
43
+ continue;
44
+ }
45
+ vfile.message(`Translation changed \`${key}\`, which is an identifier rather than prose: source has ${missing.length ? missing.map((v) => `\`${v}\``).join(', ') : '(nothing extra)'}, this has ${extra.length ? extra.map((v) => `\`${v}\``).join(', ') : '(nothing extra)'}.`, tree);
46
+ }
47
+ });
@@ -0,0 +1,2 @@
1
+ import type { Root } from 'mdast';
2
+ export declare const translationLengthRatio: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,49 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { collectProseText, currentPair } from "./shared.js";
3
+ /**
4
+ * A translation is roughly as long as its source, in the way that language is.
5
+ *
6
+ * This is the one check that catches a translation which simply stops — the
7
+ * model ran out of room, or answered with a summary. It cannot be tight,
8
+ * because languages differ in density, and it has to be calibrated against the
9
+ * measure the rule actually uses. Measured over 1050 real pairs, on **prose
10
+ * only** (code, inline code and component attributes excluded):
11
+ *
12
+ * zh min 0.247 p05 0.288 p50 0.394 p95 0.541 max 1.000
13
+ * ru min 0.644 p05 0.987 p50 1.090 p95 1.209 max 1.714
14
+ *
15
+ * Chinese says the same thing in roughly two fifths of the characters, so a
16
+ * band borrowed from a whole-file byte ratio sits *inside* the healthy
17
+ * distribution and condemns ordinary pages — which is what happened before
18
+ * these numbers were measured. The bands below sit well outside the observed
19
+ * range: a page has to be out of family, not merely at the edge of it.
20
+ *
21
+ * Re-measure before changing them, and measure the same thing the rule measures.
22
+ */
23
+ const RATIO_BANDS = {
24
+ zh: { floor: 0.12, ceiling: 1.5 },
25
+ ru: { floor: 0.35, ceiling: 2.5 },
26
+ };
27
+ /** Below this many characters the ratio is noise, not signal. */
28
+ const MIN_PROSE_CHARS = 200;
29
+ export const translationLengthRatio = lintRule('doom-lint:translation-length-ratio', async (tree, vfile) => {
30
+ const pair = await currentPair(tree, vfile);
31
+ if (!pair || pair.isCopyOnly) {
32
+ return;
33
+ }
34
+ const band = RATIO_BANDS[pair.targetLang];
35
+ if (!band) {
36
+ return;
37
+ }
38
+ const source = collectProseText(pair.sourceTree).length;
39
+ if (source < MIN_PROSE_CHARS) {
40
+ return;
41
+ }
42
+ const ratio = collectProseText(tree).length / source;
43
+ if (ratio < band.floor) {
44
+ vfile.message(`Translation is far shorter than its source (${ratio.toFixed(2)}× the prose, expected at least ${band.floor}× for ${pair.targetLang}) — it looks truncated or summarised.`, tree);
45
+ }
46
+ else if (ratio > band.ceiling) {
47
+ vfile.message(`Translation is far longer than its source (${ratio.toFixed(2)}× the prose, expected at most ${band.ceiling}× for ${pair.targetLang}) — it looks like content was added or repeated.`, tree);
48
+ }
49
+ });
@@ -0,0 +1,26 @@
1
+ import type { Root } from 'mdast';
2
+ /**
3
+ * A translation points at exactly the same places its source points at.
4
+ *
5
+ * Not "its links resolve" — that is a much weaker property, and it is the one
6
+ * the build happens to check. A link can be rewritten into a different, still
7
+ * existing page and the build stays green while the reader is sent somewhere
8
+ * else. Every link is therefore resolved against the position of the document
9
+ * holding it and stripped of its language segment, and the resulting multisets
10
+ * must match.
11
+ *
12
+ * Resolving is what makes the comparison possible: a translation's asset links
13
+ * legitimately read `../../../en/networking/x.png` where the source reads
14
+ * `./x.png`, because assets are not copied per language. Both name the same
15
+ * file, so they compare equal — while every corruption measured on this corpus
16
+ * does not:
17
+ *
18
+ * - a `<ExternalSiteLink … href="/global/install.html" />` flattened into
19
+ * `[…](../global/install.html)`;
20
+ * - `../virtualization/virtualization/virtual_machine/…` collapsed into
21
+ * `../virtualization/virtualization_virtual_machine/…`;
22
+ * - `../global_dr.mdx` rewritten as `../global.dr.mdx`;
23
+ * - `how_to/` rewritten as `how-to/`;
24
+ * - the same link generated twice.
25
+ */
26
+ export declare const translationLinkIsomorphism: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,45 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { collectLinkTargets, currentPair, diffMultiset, docDirInRoot, } from "./shared.js";
3
+ const preview = (values) => values
4
+ .slice(0, 5)
5
+ .map((value) => `\`${value}\``)
6
+ .join(', ') + (values.length > 5 ? `, … (${values.length} total)` : '');
7
+ /**
8
+ * A translation points at exactly the same places its source points at.
9
+ *
10
+ * Not "its links resolve" — that is a much weaker property, and it is the one
11
+ * the build happens to check. A link can be rewritten into a different, still
12
+ * existing page and the build stays green while the reader is sent somewhere
13
+ * else. Every link is therefore resolved against the position of the document
14
+ * holding it and stripped of its language segment, and the resulting multisets
15
+ * must match.
16
+ *
17
+ * Resolving is what makes the comparison possible: a translation's asset links
18
+ * legitimately read `../../../en/networking/x.png` where the source reads
19
+ * `./x.png`, because assets are not copied per language. Both name the same
20
+ * file, so they compare equal — while every corruption measured on this corpus
21
+ * does not:
22
+ *
23
+ * - a `<ExternalSiteLink … href="/global/install.html" />` flattened into
24
+ * `[…](../global/install.html)`;
25
+ * - `../virtualization/virtualization/virtual_machine/…` collapsed into
26
+ * `../virtualization/virtualization_virtual_machine/…`;
27
+ * - `../global_dr.mdx` rewritten as `../global.dr.mdx`;
28
+ * - `how_to/` rewritten as `how-to/`;
29
+ * - the same link generated twice.
30
+ */
31
+ export const translationLinkIsomorphism = lintRule('doom-lint:translation-link-isomorphism', async (tree, vfile) => {
32
+ const pair = await currentPair(tree, vfile);
33
+ if (!pair) {
34
+ return;
35
+ }
36
+ const expected = collectLinkTargets(pair.sourceTree, docDirInRoot(pair.sourceLang, pair.relativePath));
37
+ const actual = collectLinkTargets(tree, docDirInRoot(pair.targetLang, pair.relativePath));
38
+ const { missing, extra } = diffMultiset(expected, actual);
39
+ if (missing.length) {
40
+ vfile.message(`Translation lost ${missing.length} link target(s) the source has: ${preview(missing)}.`, tree);
41
+ }
42
+ if (extra.length) {
43
+ vfile.message(`Translation points at ${extra.length} target(s) the source does not: ${preview(extra)}.`, tree);
44
+ }
45
+ });
@@ -0,0 +1,110 @@
1
+ import type { Root } from 'mdast';
2
+ import type { VFile } from 'vfile';
3
+ /**
4
+ * Shared plumbing for the `translation-parity` rules.
5
+ *
6
+ * These are the only lint rules that need a *second* document: they compare a
7
+ * translation against the source it was made from. Everything they can say
8
+ * follows from that pairing, so getting the pairing right — and refusing to
9
+ * report anything when it is not right — is most of the work.
10
+ *
11
+ * The pairing itself is exact rather than heuristic: `doom translate` writes
12
+ * `sourceSHA` (the sha256 of the source file's bytes) into every translation it
13
+ * produces, so a translation and a source either belong together or do not.
14
+ * There is no "probably the same version" state to reason about.
15
+ */
16
+ export interface TranslationPair {
17
+ /** language the document was translated from, e.g. `en` */
18
+ sourceLang: string;
19
+ /** language of the document being linted, e.g. `zh` */
20
+ targetLang: string;
21
+ /** path inside the locale directory, e.g. `install/installing.mdx` */
22
+ relativePath: string;
23
+ /** absolute path of the source document */
24
+ sourcePath: string;
25
+ sourceRaw: string;
26
+ sourceTree: Root;
27
+ sourceFrontmatter: Record<string, unknown>;
28
+ targetFrontmatter: Record<string, unknown>;
29
+ /**
30
+ * The document is copied rather than translated (`translate.copyOnlyDirectories`).
31
+ * Its structure must still match its source, but it is *supposed* to still be
32
+ * in the source language — so asking whether it reads as Chinese asks the
33
+ * wrong question of the right file.
34
+ */
35
+ isCopyOnly: boolean;
36
+ }
37
+ export type TranslationStatus =
38
+ /** not under the docs root, or is itself the source language */
39
+ {
40
+ kind: 'not-a-translation';
41
+ }
42
+ /**
43
+ * No `sourceSHA`: the document is maintained by hand — the documented escape
44
+ * hatch is `i18n.disableAutoTranslation` in the source's frontmatter. Nothing
45
+ * here can say anything about it.
46
+ */
47
+ | {
48
+ kind: 'unmanaged';
49
+ } | {
50
+ kind: 'source-missing';
51
+ sourcePath: string;
52
+ } | {
53
+ kind: 'stale';
54
+ sourcePath: string;
55
+ expected: string;
56
+ actual: string;
57
+ } | {
58
+ kind: 'current';
59
+ pair: TranslationPair;
60
+ };
61
+ /**
62
+ * Works out whether the document being linted is a translation, and if so
63
+ * whether it still corresponds to its source.
64
+ */
65
+ export declare const resolveTranslation: (tree: Root, vfile: VFile) => Promise<TranslationStatus>;
66
+ /** Resolves the pair, or nothing at all when there is nothing to compare. */
67
+ export declare const currentPair: (tree: Root, vfile: VFile) => Promise<TranslationPair | undefined>;
68
+ /** Open tags of every component used in a document, counted by name. */
69
+ export declare const collectComponents: (tree: Root) => Map<string, number>;
70
+ /** The document's heading levels, in order. */
71
+ export declare const collectHeadingDepths: (tree: Root) => number[];
72
+ /**
73
+ * Every JSX attribute that carries a literal string value, keyed
74
+ * `Component.attribute`. Expression values are read through to their source
75
+ * text, which is what has to stay byte-identical.
76
+ */
77
+ export declare const collectJsxAttributes: (tree: Root) => Map<string, string[]>;
78
+ /**
79
+ * Resolves a link the way the site does — against the position of the document
80
+ * that holds it — and then drops the language segment.
81
+ *
82
+ * This is what makes source and translation comparable at all. A translation's
83
+ * links legitimately differ from the source's as *written*: assets are rewritten
84
+ * to point back into the source-language tree (`../../../en/…/x.png`) because
85
+ * they are not copied per language. Resolved and de-localised, both spellings
86
+ * name the same file, so anything still different is a real difference.
87
+ */
88
+ export declare const resolveLinkTarget: (url: string, docDirInRoot: string) => string;
89
+ /**
90
+ * Every link target a document points at: markdown links and images, reference
91
+ * definitions, `href`/`src` on components, and the same inside raw HTML.
92
+ */
93
+ export declare const collectLinkTargets: (tree: Root, docDirInRoot: string) => string[];
94
+ /** Multiset difference, reported as what is missing and what is extra. */
95
+ export declare const diffMultiset: (expected: readonly string[], actual: readonly string[]) => {
96
+ missing: string[];
97
+ extra: string[];
98
+ };
99
+ /**
100
+ * The document's prose — the text a reader reads, and the only text a
101
+ * translation is supposed to change.
102
+ *
103
+ * Code, inline code and component attributes are excluded because they are not
104
+ * prose: counting them would make a page full of `kubectl` commands look
105
+ * untranslated, and would make a translated page look longer or shorter than it
106
+ * is for reasons that have nothing to do with the translation.
107
+ */
108
+ export declare const collectProseText: (tree: Root) => string;
109
+ /** The directory a document sits in, relative to the docs root, in posix form. */
110
+ export declare const docDirInRoot: (targetLang: string, relativePath: string) => string;
@@ -0,0 +1,282 @@
1
+ import crypto from 'node:crypto';
2
+ import fs from 'node:fs/promises';
3
+ import path from 'node:path';
4
+ import picomatch from 'picomatch';
5
+ import { visit } from 'unist-util-visit';
6
+ import { parse as parseYaml } from 'yaml';
7
+ import { escapeMarkdownHeadingIds } from "../../cli/helpers.js";
8
+ import { mdProcessor, mdxProcessor } from "../../plugins/index.js";
9
+ import { DEFAULT_COPY_ONLY_DIRECTORIES, SUPPORTED_LANGUAGES, } from "../../shared/index.js";
10
+ import { getConfig } from "../utils.js";
11
+ const matcherCache = new Map();
12
+ /** Memoised, because it is asked once per document and the patterns never change. */
13
+ const isCopyOnlyMatcher = (patterns) => {
14
+ const key = patterns.join('\u0000');
15
+ let matcher = matcherCache.get(key);
16
+ if (!matcher) {
17
+ // Same matcher tinyglobby uses to select these files in `doom translate`,
18
+ // so what is checked here is exactly what is copied there.
19
+ matcher = picomatch([...patterns]);
20
+ matcherCache.set(key, matcher);
21
+ }
22
+ return matcher;
23
+ };
24
+ const frontmatterOf = (tree) => {
25
+ const first = tree.children.at(0);
26
+ if (first?.type !== 'yaml') {
27
+ return {};
28
+ }
29
+ return parseYaml(first.value) ?? {};
30
+ };
31
+ const sourceCache = new Map();
32
+ const loadSource = async (sourcePath) => {
33
+ const raw = await fs.readFile(sourcePath, 'utf8');
34
+ const sha = crypto.createHash('sha256').update(raw).digest('hex');
35
+ const cached = sourceCache.get(sourcePath);
36
+ if (cached?.sha === sha) {
37
+ return cached;
38
+ }
39
+ const processor = sourcePath.endsWith('.mdx') ? mdxProcessor : mdProcessor;
40
+ // The same escaping `doom translate` applies before parsing: without it a
41
+ // custom heading anchor is an MDX expression and the parse fails outright.
42
+ const entry = {
43
+ sha,
44
+ raw,
45
+ tree: processor.parse(escapeMarkdownHeadingIds(raw)),
46
+ };
47
+ sourceCache.set(sourcePath, entry);
48
+ return entry;
49
+ };
50
+ /**
51
+ * Works out whether the document being linted is a translation, and if so
52
+ * whether it still corresponds to its source.
53
+ */
54
+ export const resolveTranslation = async (tree, vfile) => {
55
+ const { config } = await getConfig();
56
+ const root = config.root;
57
+ if (!root || !vfile.path) {
58
+ return { kind: 'not-a-translation' };
59
+ }
60
+ const relative = path.relative(root, vfile.path);
61
+ if (relative.startsWith('..')) {
62
+ return { kind: 'not-a-translation' };
63
+ }
64
+ const segments = relative.split(path.sep);
65
+ const targetLang = segments[0];
66
+ const sourceLang = config.lang ?? 'en';
67
+ if (segments.length < 2 ||
68
+ targetLang === sourceLang ||
69
+ !SUPPORTED_LANGUAGES.includes(targetLang)) {
70
+ return { kind: 'not-a-translation' };
71
+ }
72
+ const targetFrontmatter = frontmatterOf(tree);
73
+ const declared = targetFrontmatter.sourceSHA;
74
+ if (typeof declared !== 'string') {
75
+ return { kind: 'unmanaged' };
76
+ }
77
+ const relativePath = segments.slice(1).join('/');
78
+ const sourcePath = path.join(root, sourceLang, ...segments.slice(1));
79
+ let source;
80
+ try {
81
+ source = await loadSource(sourcePath);
82
+ }
83
+ catch {
84
+ return { kind: 'source-missing', sourcePath };
85
+ }
86
+ if (source.sha !== declared) {
87
+ return {
88
+ kind: 'stale',
89
+ sourcePath,
90
+ expected: source.sha,
91
+ actual: declared,
92
+ };
93
+ }
94
+ return {
95
+ kind: 'current',
96
+ pair: {
97
+ sourceLang,
98
+ targetLang,
99
+ relativePath,
100
+ sourcePath,
101
+ sourceRaw: source.raw,
102
+ sourceTree: source.tree,
103
+ sourceFrontmatter: frontmatterOf(source.tree),
104
+ targetFrontmatter,
105
+ isCopyOnly: isCopyOnlyMatcher(config.translate?.copyOnlyDirectories ?? DEFAULT_COPY_ONLY_DIRECTORIES)(relativePath),
106
+ },
107
+ };
108
+ };
109
+ /** Resolves the pair, or nothing at all when there is nothing to compare. */
110
+ export const currentPair = async (tree, vfile) => {
111
+ const status = await resolveTranslation(tree, vfile);
112
+ return status.kind === 'current' ? status.pair : undefined;
113
+ };
114
+ // ---------------------------------------------------------------------------
115
+ // Collectors — everything below reads a tree and returns something comparable.
116
+ // ---------------------------------------------------------------------------
117
+ const isJsxElement = (node) => node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement';
118
+ /** Open tags of every component used in a document, counted by name. */
119
+ export const collectComponents = (tree) => {
120
+ const counts = new Map();
121
+ visit(tree, (node) => {
122
+ if (isJsxElement(node) && node.name) {
123
+ counts.set(node.name, (counts.get(node.name) ?? 0) + 1);
124
+ }
125
+ });
126
+ return counts;
127
+ };
128
+ /** The document's heading levels, in order. */
129
+ export const collectHeadingDepths = (tree) => {
130
+ const depths = [];
131
+ visit(tree, 'heading', (node) => {
132
+ depths.push(node.depth);
133
+ });
134
+ return depths;
135
+ };
136
+ /**
137
+ * Every JSX attribute that carries a literal string value, keyed
138
+ * `Component.attribute`. Expression values are read through to their source
139
+ * text, which is what has to stay byte-identical.
140
+ */
141
+ export const collectJsxAttributes = (tree) => {
142
+ const values = new Map();
143
+ visit(tree, (node) => {
144
+ if (!isJsxElement(node) || !node.name) {
145
+ return;
146
+ }
147
+ for (const attr of node.attributes) {
148
+ if (attr.type === 'mdxJsxExpressionAttribute') {
149
+ push(values, `${node.name}.{...}`, attr.value);
150
+ continue;
151
+ }
152
+ if (attr.value == null) {
153
+ continue;
154
+ }
155
+ push(values, `${node.name}.${attr.name}`, typeof attr.value === 'string' ? attr.value : attr.value.value);
156
+ }
157
+ });
158
+ return values;
159
+ };
160
+ const push = (map, key, value) => {
161
+ const list = map.get(key);
162
+ if (list) {
163
+ list.push(value);
164
+ }
165
+ else {
166
+ map.set(key, [value]);
167
+ }
168
+ };
169
+ const EXTERNAL_URL = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
170
+ const LOCALE_PREFIX = new RegExp(`^/(?:${SUPPORTED_LANGUAGES.join('|')})(?=/|$)`);
171
+ /**
172
+ * Resolves a link the way the site does — against the position of the document
173
+ * that holds it — and then drops the language segment.
174
+ *
175
+ * This is what makes source and translation comparable at all. A translation's
176
+ * links legitimately differ from the source's as *written*: assets are rewritten
177
+ * to point back into the source-language tree (`../../../en/…/x.png`) because
178
+ * they are not copied per language. Resolved and de-localised, both spellings
179
+ * name the same file, so anything still different is a real difference.
180
+ */
181
+ export const resolveLinkTarget = (url, docDirInRoot) => {
182
+ const trimmed = url.trim();
183
+ if (!trimmed || EXTERNAL_URL.test(trimmed) || trimmed.startsWith('#')) {
184
+ return trimmed;
185
+ }
186
+ const hashAt = trimmed.indexOf('#');
187
+ const target = hashAt < 0 ? trimmed : trimmed.slice(0, hashAt);
188
+ const hash = hashAt < 0 ? '' : trimmed.slice(hashAt);
189
+ if (!target) {
190
+ return trimmed;
191
+ }
192
+ const absolute = target.startsWith('/')
193
+ ? path.posix.normalize(target)
194
+ : path.posix.resolve(`/${docDirInRoot}`, target);
195
+ return absolute.replace(LOCALE_PREFIX, '') + hash;
196
+ };
197
+ const LINK_ATTRIBUTES = new Set(['href', 'src']);
198
+ const HTML_LINK_ATTRIBUTE = /\b(?:href|src)\s*=\s*(["'])(.*?)\1/gi;
199
+ /**
200
+ * Every link target a document points at: markdown links and images, reference
201
+ * definitions, `href`/`src` on components, and the same inside raw HTML.
202
+ */
203
+ export const collectLinkTargets = (tree, docDirInRoot) => {
204
+ const targets = [];
205
+ const add = (url) => {
206
+ const resolved = resolveLinkTarget(url, docDirInRoot);
207
+ if (resolved) {
208
+ targets.push(resolved);
209
+ }
210
+ };
211
+ visit(tree, (node) => {
212
+ switch (node.type) {
213
+ case 'link':
214
+ case 'image':
215
+ case 'definition': {
216
+ add(node.url);
217
+ return;
218
+ }
219
+ case 'html': {
220
+ for (const [, , value] of node.value.matchAll(HTML_LINK_ATTRIBUTE)) {
221
+ add(value);
222
+ }
223
+ return;
224
+ }
225
+ default: {
226
+ if (!isJsxElement(node)) {
227
+ return;
228
+ }
229
+ for (const attr of node.attributes) {
230
+ if (attr.type === 'mdxJsxAttribute' &&
231
+ LINK_ATTRIBUTES.has(attr.name) &&
232
+ typeof attr.value === 'string') {
233
+ add(attr.value);
234
+ }
235
+ }
236
+ }
237
+ }
238
+ });
239
+ return targets;
240
+ };
241
+ /** Multiset difference, reported as what is missing and what is extra. */
242
+ export const diffMultiset = (expected, actual) => {
243
+ const counts = new Map();
244
+ for (const value of expected) {
245
+ counts.set(value, (counts.get(value) ?? 0) + 1);
246
+ }
247
+ for (const value of actual) {
248
+ counts.set(value, (counts.get(value) ?? 0) - 1);
249
+ }
250
+ const missing = [];
251
+ const extra = [];
252
+ for (const [value, delta] of counts) {
253
+ for (let i = 0; i < delta; i++) {
254
+ missing.push(value);
255
+ }
256
+ for (let i = 0; i < -delta; i++) {
257
+ extra.push(value);
258
+ }
259
+ }
260
+ return { missing: missing.sort(), extra: extra.sort() };
261
+ };
262
+ /**
263
+ * The document's prose — the text a reader reads, and the only text a
264
+ * translation is supposed to change.
265
+ *
266
+ * Code, inline code and component attributes are excluded because they are not
267
+ * prose: counting them would make a page full of `kubectl` commands look
268
+ * untranslated, and would make a translated page look longer or shorter than it
269
+ * is for reasons that have nothing to do with the translation.
270
+ */
271
+ export const collectProseText = (tree) => {
272
+ const parts = [];
273
+ visit(tree, 'text', (node) => {
274
+ parts.push(node.value);
275
+ });
276
+ return parts.join(' ');
277
+ };
278
+ /** The directory a document sits in, relative to the docs root, in posix form. */
279
+ export const docDirInRoot = (targetLang, relativePath) => {
280
+ const dir = path.posix.dirname(`${targetLang}/${relativePath}`);
281
+ return dir === '.' ? '' : dir;
282
+ };
@@ -0,0 +1,2 @@
1
+ import type { Root } from 'mdast';
2
+ export declare const translationTerminologyAdherence: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,67 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { parseTerms } from "../../cli/helpers.js";
3
+ import { collectProseText, currentPair } from "./shared.js";
4
+ /**
5
+ * A translation uses the agreed word for an agreed term.
6
+ *
7
+ * The terminology table is already resolved and injected into the translator's
8
+ * prompt for every document, and nothing has ever checked whether the output
9
+ * used it. Turning that into a check costs nothing: same table, read the same
10
+ * way.
11
+ *
12
+ * **Not registered in the default rule set**, and this is why. Run over 1050
13
+ * real pairs it reported 490 problems on a corpus that is substantially
14
+ * correct, because the table is a glossary of preferences rather than a set of
15
+ * invariants: `Application` → `原生应用` fired 124 times, `view` → `视图` 84,
16
+ * `log` → `日志` 39, `NodePort` → `主机端口` 8. Those source words are ordinary
17
+ * English, and their agreed rendering applies to the product feature, not to
18
+ * every sentence that happens to contain the word. A rule that fires 490 times
19
+ * on a healthy corpus does not enforce terminology; it teaches people to
20
+ * disregard the gate.
21
+ *
22
+ * Making it enforceable is an upstream change: the table needs to say which
23
+ * entries are invariants. Until then this is available to run deliberately —
24
+ * `doom lint` with the rule switched on — and is not part of any gate.
25
+ *
26
+ * Matching happens on prose only. `Alauda` inside `security.alauda.io` is an
27
+ * API group, not the company, and a check that cannot tell the difference is a
28
+ * check nobody would keep switched on.
29
+ */
30
+ const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
31
+ let termsFailureReported = false;
32
+ export const translationTerminologyAdherence = lintRule('doom-lint:translation-terminology-adherence', async (tree, vfile) => {
33
+ const pair = await currentPair(tree, vfile);
34
+ if (!pair || pair.isCopyOnly) {
35
+ return;
36
+ }
37
+ let terms;
38
+ try {
39
+ terms = await parseTerms();
40
+ }
41
+ catch (error) {
42
+ // A check that cannot run must say so. Once per process: the table is
43
+ // fetched once, and one unreadable table is one problem, not nine hundred.
44
+ if (!termsFailureReported) {
45
+ termsFailureReported = true;
46
+ vfile.message(`Terminology could not be read, so terminology adherence went unchecked in this run: ${error instanceof Error ? error.message : String(error)}`, tree);
47
+ }
48
+ return;
49
+ }
50
+ const sourceProse = collectProseText(pair.sourceTree);
51
+ const targetProse = collectProseText(tree).toLowerCase();
52
+ for (const term of terms) {
53
+ const source = term[pair.sourceLang];
54
+ const target = term[pair.targetLang];
55
+ if (!source || !target) {
56
+ continue;
57
+ }
58
+ const inSource = new RegExp(`\\b${escapeRegExp(source)}\\b`, 'i');
59
+ if (!inSource.test(sourceProse)) {
60
+ continue;
61
+ }
62
+ if (targetProse.includes(target.toLowerCase())) {
63
+ continue;
64
+ }
65
+ vfile.message(`Translation does not use the agreed term for \`${source}\`: expected \`${target}\` somewhere in the prose.`, tree);
66
+ }
67
+ });
@@ -0,0 +1,11 @@
1
+ import type { Root } from 'mdast';
2
+ /**
3
+ * A translation must correspond to the source it declares.
4
+ *
5
+ * Every other `translation-parity` rule compares two documents, and every one of
6
+ * them is meaningless — noisy, or falsely quiet — if the two are different
7
+ * versions of the same page. So they all stand down unless this one is
8
+ * satisfied, and this one says so out loud rather than letting them skip in
9
+ * silence.
10
+ */
11
+ export declare const translationUpToDate: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -0,0 +1,21 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { resolveTranslation } from "./shared.js";
3
+ /**
4
+ * A translation must correspond to the source it declares.
5
+ *
6
+ * Every other `translation-parity` rule compares two documents, and every one of
7
+ * them is meaningless — noisy, or falsely quiet — if the two are different
8
+ * versions of the same page. So they all stand down unless this one is
9
+ * satisfied, and this one says so out loud rather than letting them skip in
10
+ * silence.
11
+ */
12
+ export const translationUpToDate = lintRule('doom-lint:translation-up-to-date', async (tree, vfile) => {
13
+ const status = await resolveTranslation(tree, vfile);
14
+ if (status.kind === 'stale') {
15
+ vfile.message(`Translation is out of date: its \`sourceSHA\` names a version of \`${status.sourcePath}\` that no longer exists. Re-run \`doom translate\`; until then no translation check can say anything about this file.`, tree);
16
+ return;
17
+ }
18
+ if (status.kind === 'source-missing') {
19
+ vfile.message(`Translation has no source: nothing exists at \`${status.sourcePath}\`. Either the source page was removed and this one should go too, or it is in the wrong place.`, tree);
20
+ }
21
+ });
@@ -0,0 +1,2 @@
1
+ import type { Root } from 'mdast';
2
+ export declare const translationUrlResidue: import("unified-lint-rule").Plugin<Root, unknown>;