@alauda/doom 2.5.4 → 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 (92) 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 +22 -3
  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 +16 -0
  30. package/lib/plugins/global/components.js +16 -1
  31. package/lib/remark-lint/index.d.ts +20 -0
  32. package/lib/remark-lint/index.js +40 -0
  33. package/lib/remark-lint/no-unmatched-anchor.d.ts +10 -0
  34. package/lib/remark-lint/no-unmatched-anchor.js +13 -0
  35. package/lib/remark-lint/no-unopened-frontmatter.d.ts +2 -0
  36. package/lib/remark-lint/no-unopened-frontmatter.js +70 -0
  37. package/lib/remark-lint/no-unparsed-emphasis.d.ts +2 -0
  38. package/lib/remark-lint/no-unparsed-emphasis.js +53 -0
  39. package/lib/remark-lint/no-unresolved-api-ref.d.ts +40 -0
  40. package/lib/remark-lint/no-unresolved-api-ref.js +194 -0
  41. package/lib/remark-lint/rule-sets.d.ts +75 -0
  42. package/lib/remark-lint/rule-sets.js +120 -0
  43. package/lib/remark-lint/translation-parity/component-multiset.d.ts +17 -0
  44. package/lib/remark-lint/translation-parity/component-multiset.js +35 -0
  45. package/lib/remark-lint/translation-parity/echoed-source.d.ts +2 -0
  46. package/lib/remark-lint/translation-parity/echoed-source.js +37 -0
  47. package/lib/remark-lint/translation-parity/frontmatter-preservation.d.ts +2 -0
  48. package/lib/remark-lint/translation-parity/frontmatter-preservation.js +36 -0
  49. package/lib/remark-lint/translation-parity/heading-sequence.d.ts +12 -0
  50. package/lib/remark-lint/translation-parity/heading-sequence.js +25 -0
  51. package/lib/remark-lint/translation-parity/index.d.ts +24 -0
  52. package/lib/remark-lint/translation-parity/index.js +24 -0
  53. package/lib/remark-lint/translation-parity/jsx-attribute-parity.d.ts +14 -0
  54. package/lib/remark-lint/translation-parity/jsx-attribute-parity.js +47 -0
  55. package/lib/remark-lint/translation-parity/length-ratio.d.ts +2 -0
  56. package/lib/remark-lint/translation-parity/length-ratio.js +49 -0
  57. package/lib/remark-lint/translation-parity/link-isomorphism.d.ts +26 -0
  58. package/lib/remark-lint/translation-parity/link-isomorphism.js +45 -0
  59. package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
  60. package/lib/remark-lint/translation-parity/shared.js +282 -0
  61. package/lib/remark-lint/translation-parity/terminology-adherence.d.ts +2 -0
  62. package/lib/remark-lint/translation-parity/terminology-adherence.js +67 -0
  63. package/lib/remark-lint/translation-parity/up-to-date.d.ts +11 -0
  64. package/lib/remark-lint/translation-parity/up-to-date.js +21 -0
  65. package/lib/remark-lint/translation-parity/url-residue.d.ts +2 -0
  66. package/lib/remark-lint/translation-parity/url-residue.js +46 -0
  67. package/lib/remarkrc.d.ts +1 -1
  68. package/lib/remarkrc.js +7 -34
  69. package/lib/runtime/api-paths.d.ts +20 -0
  70. package/lib/runtime/api-paths.js +29 -0
  71. package/lib/runtime/components/K8sAPI.d.ts +14 -1
  72. package/lib/runtime/components/K8sAPI.js +49 -10
  73. package/lib/runtime/components/K8sCrd.d.ts +1 -1
  74. package/lib/runtime/components/K8sPermissionTable.js +10 -5
  75. package/lib/runtime/components/OpenAPIPath.js +19 -2
  76. package/lib/runtime/components/_HeadingTitle.js +24 -6
  77. package/lib/runtime/components/_K8sAPIEndpoints.d.ts +8 -1
  78. package/lib/runtime/components/_K8sAPIEndpoints.js +27 -9
  79. package/lib/runtime/components/_K8sAPISchema.d.ts +9 -1
  80. package/lib/runtime/components/_K8sAPISchema.js +24 -6
  81. package/lib/runtime/components/_translation-policy.d.ts +23 -0
  82. package/lib/runtime/components/_translation-policy.js +32 -0
  83. package/lib/runtime/hooks/useTranslation.d.ts +1 -1
  84. package/lib/runtime/translation.d.ts +68 -0
  85. package/lib/runtime/translation.js +51 -0
  86. package/lib/runtime/utils.d.ts +24 -2
  87. package/lib/runtime/utils.js +87 -5
  88. package/lib/shared/constants.d.ts +9 -0
  89. package/lib/shared/constants.js +14 -0
  90. package/lib/types.d.ts +70 -0
  91. package/lib/utils/helpers.js +8 -2
  92. package/package.json +3 -1
@@ -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>;
@@ -0,0 +1,46 @@
1
+ import { lintRule } from 'unified-lint-rule';
2
+ import { visit } from 'unist-util-visit';
3
+ import { currentPair, diffMultiset } from "./shared.js";
4
+ /**
5
+ * URLs written in prose that markdown does not turn into links still survive
6
+ * translation.
7
+ *
8
+ * This is the other half of a deliberate asymmetry. A URL with a scheme becomes
9
+ * a link node and is protected structurally; a bare `example.com` or an
10
+ * `ftp://…` stays plain text, and protecting *that* would mean pattern-matching
11
+ * inside prose — the one way masking could swallow something that ought to have
12
+ * been translated. So it is checked instead: a check that misfires costs one
13
+ * finding to read, whereas a mask that misfires hides a sentence.
14
+ *
15
+ * The pattern insists on a scheme or a `www.`, which is narrower than "looks
16
+ * like a domain" on purpose. A first attempt matched any `name.tld/path` and
17
+ * reported seven documents — every one an API group or an annotation key
18
+ * (`autoscaling.k8s.io/v1`, `kubevirt.io/storage`) that had merely moved
19
+ * between prose and inline code. Those are identifiers, not links, and a guard
20
+ * that cries wolf about them is worse than no guard at all.
21
+ *
22
+ * Honest caveat: measured exposure on this corpus is zero — all seven bare URLs
23
+ * carry `https://`, which makes them link nodes, protected structurally. This
24
+ * is a guard for a case nothing else covers, not a demonstrated detector.
25
+ */
26
+ const BARE_URL = /\b(?:[a-z][a-z0-9+.-]*:\/\/|www\.)\S+/gi;
27
+ const collect = (tree) => {
28
+ const found = [];
29
+ visit(tree, 'text', (node) => {
30
+ for (const [match] of node.value.matchAll(BARE_URL)) {
31
+ found.push(match);
32
+ }
33
+ });
34
+ return found;
35
+ };
36
+ export const translationUrlResidue = lintRule('doom-lint:translation-url-residue', async (tree, vfile) => {
37
+ const pair = await currentPair(tree, vfile);
38
+ if (!pair) {
39
+ return;
40
+ }
41
+ const { missing } = diffMultiset(collect(pair.sourceTree), collect(tree));
42
+ if (!missing.length) {
43
+ return;
44
+ }
45
+ vfile.message(`Translation lost ${missing.length} URL(s) written in prose: ${missing.map((url) => `\`${url}\``).join(', ')}. These are plain text rather than links, so nothing protects them structurally.`, tree);
46
+ });
package/lib/remarkrc.d.ts CHANGED
@@ -1,4 +1,4 @@
1
1
  declare const _default: {
2
- plugins: any[];
2
+ plugins: import("unified").Plugin<[], import("mdast").Root>[];
3
3
  };
4
4
  export default _default;
package/lib/remarkrc.js CHANGED
@@ -1,39 +1,12 @@
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 doomLint, { checkDeadLinks, headingAnchorFormat, noDeepHeading, noDeepList, noLegacyOSNames, noMultiOpenAPIPaths, noParagraphIndent, noUnmatchedAnchor, site, tableSize, titleRequired, unitCase, } from "./remark-lint/index.js";
1
+ import doomLint from "./remark-lint/index.js";
2
+ import { LINT_RULES, SYNTAX_PLUGINS } from "./remark-lint/rule-sets.js";
14
3
  export default {
15
4
  plugins: [
16
- remarkDirective,
17
- remarkFrontmatter,
18
- remarkGfm,
19
- remarkLintCodeBlockSplitList,
20
- remarkLintHeadingIncrement,
21
- remarkLintLintMatchPunctuation,
22
- remarkLintNoChinesePunctuationInNumber,
23
- remarkLintNoDuplicateHeadingsInSection,
24
- remarkLintNoHiddenTableCell,
5
+ ...SYNTAX_PLUGINS,
6
+ // Message control (`<!-- lint disable -->`). It registers its transformer
7
+ // from inside its own attacher, which lands it at the end of the queue, so
8
+ // it filters the messages of every rule regardless of where it sits here.
25
9
  doomLint,
26
- checkDeadLinks,
27
- headingAnchorFormat,
28
- noDeepHeading,
29
- noDeepList,
30
- noLegacyOSNames,
31
- noMultiOpenAPIPaths,
32
- noParagraphIndent,
33
- noUnmatchedAnchor,
34
- site,
35
- tableSize,
36
- titleRequired,
37
- unitCase,
10
+ ...LINT_RULES,
38
11
  ],
39
12
  };
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Reading facts off an OpenAPI document's `paths`.
3
+ *
4
+ * Kept free of the `doom-@api-*` virtual modules so it stays importable — and
5
+ * therefore testable — outside a build.
6
+ */
7
+ /**
8
+ * Whether an OpenAPI document declares a `/status` subresource route for a
9
+ * resource.
10
+ *
11
+ * A `/status` endpoint exists because the API server routes it, not because the
12
+ * resource's schema happens to carry a `status` property — a property is state,
13
+ * a route is an interface. CRDs say so in `subresources.status`; an OpenAPI
14
+ * document says so by listing the route.
15
+ *
16
+ * Returns `undefined` when the document does not describe the resource's routes
17
+ * at all: it then says nothing about the subresource either, and the caller must
18
+ * fall back to a weaker signal rather than read the silence as a denial.
19
+ */
20
+ export declare const declaresStatusSubresource: (paths: string[], pluralName: string | undefined) => boolean | undefined;
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Reading facts off an OpenAPI document's `paths`.
3
+ *
4
+ * Kept free of the `doom-@api-*` virtual modules so it stays importable — and
5
+ * therefore testable — outside a build.
6
+ */
7
+ /**
8
+ * Whether an OpenAPI document declares a `/status` subresource route for a
9
+ * resource.
10
+ *
11
+ * A `/status` endpoint exists because the API server routes it, not because the
12
+ * resource's schema happens to carry a `status` property — a property is state,
13
+ * a route is an interface. CRDs say so in `subresources.status`; an OpenAPI
14
+ * document says so by listing the route.
15
+ *
16
+ * Returns `undefined` when the document does not describe the resource's routes
17
+ * at all: it then says nothing about the subresource either, and the caller must
18
+ * fall back to a weaker signal rather than read the silence as a denial.
19
+ */
20
+ export const declaresStatusSubresource = (paths, pluralName) => {
21
+ if (!pluralName) {
22
+ return;
23
+ }
24
+ const covers = (path) => path.includes(`/${pluralName}/`) || path.endsWith(`/${pluralName}`);
25
+ if (!paths.some(covers)) {
26
+ return;
27
+ }
28
+ return paths.some((path) => path.endsWith('/status') && covers(path));
29
+ };
@@ -6,6 +6,19 @@ export interface K8sAPIProps {
6
6
  apiGroup?: string;
7
7
  apiVersion?: string;
8
8
  apiKind?: string;
9
+ /**
10
+ * Override the resource's plural name in the endpoint paths. Only needed for
11
+ * OpenAPI-sourced resources whose plural cannot be read from a CRD; for CRD
12
+ * sources the plural comes from `spec.names.plural` automatically.
13
+ */
14
+ plural?: string;
15
+ /**
16
+ * Whether the API server exposes a `/status` subresource. Declared by the
17
+ * caller when the source cannot be trusted to answer — an aggregation-layer
18
+ * OpenAPI document may describe neither the subresource routes nor the
19
+ * resource's own routes.
20
+ */
21
+ hasStatus?: boolean;
9
22
  }
10
- export declare const K8sAPI: ({ name, namespaced, pathPrefix, filepath, apiGroup, apiVersion, apiKind, }: K8sAPIProps) => import("react/jsx-runtime").JSX.Element | null;
23
+ export declare const K8sAPI: ({ name, namespaced, pathPrefix, filepath, apiGroup, apiVersion, apiKind, plural, hasStatus, }: K8sAPIProps) => import("react/jsx-runtime").JSX.Element | null;
11
24
  export default K8sAPI;