@alauda/doom 2.5.4 → 2.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/cli/api.d.ts +2 -0
- package/lib/cli/api.js +147 -0
- package/lib/cli/helpers.d.ts +1 -7
- package/lib/cli/helpers.js +4 -41
- package/lib/cli/index.js +2 -0
- package/lib/cli/translate-agent.d.ts +81 -0
- package/lib/cli/translate-agent.js +450 -0
- package/lib/cli/translate-check.d.ts +17 -0
- package/lib/cli/translate-check.js +67 -0
- package/lib/cli/translate-checker.d.ts +58 -0
- package/lib/cli/translate-checker.js +112 -0
- package/lib/cli/translate-judge.d.ts +119 -0
- package/lib/cli/translate-judge.js +224 -0
- package/lib/cli/translate-limits.d.ts +43 -0
- package/lib/cli/translate-limits.js +55 -0
- package/lib/cli/translate-mask.d.ts +144 -0
- package/lib/cli/translate-mask.js +617 -0
- package/lib/cli/translate-models.d.ts +127 -0
- package/lib/cli/translate-models.js +189 -0
- package/lib/cli/translate-scratch.d.ts +142 -0
- package/lib/cli/translate-scratch.js +187 -0
- package/lib/cli/translate-terms.d.ts +22 -0
- package/lib/cli/translate-terms.js +33 -0
- package/lib/cli/translate.d.ts +15 -10
- package/lib/cli/translate.js +228 -185
- package/lib/eslint.js +22 -3
- package/lib/plugins/api/index.js +1 -1
- package/lib/plugins/api/types.d.ts +36 -1
- package/lib/plugins/global/components.d.ts +16 -0
- package/lib/plugins/global/components.js +16 -1
- package/lib/remark-lint/index.d.ts +20 -0
- package/lib/remark-lint/index.js +40 -0
- package/lib/remark-lint/no-unmatched-anchor.d.ts +10 -0
- package/lib/remark-lint/no-unmatched-anchor.js +19 -2
- package/lib/remark-lint/no-unopened-frontmatter.d.ts +2 -0
- package/lib/remark-lint/no-unopened-frontmatter.js +70 -0
- package/lib/remark-lint/no-unparsed-emphasis.d.ts +2 -0
- package/lib/remark-lint/no-unparsed-emphasis.js +53 -0
- package/lib/remark-lint/no-unresolved-api-ref.d.ts +40 -0
- package/lib/remark-lint/no-unresolved-api-ref.js +194 -0
- package/lib/remark-lint/rule-sets.d.ts +73 -0
- package/lib/remark-lint/rule-sets.js +114 -0
- package/lib/remark-lint/syntax-plugins.d.ts +32 -0
- package/lib/remark-lint/syntax-plugins.js +46 -0
- package/lib/remark-lint/translation-parity/component-multiset.d.ts +17 -0
- package/lib/remark-lint/translation-parity/component-multiset.js +35 -0
- package/lib/remark-lint/translation-parity/echoed-source.d.ts +2 -0
- package/lib/remark-lint/translation-parity/echoed-source.js +37 -0
- package/lib/remark-lint/translation-parity/frontmatter-preservation.d.ts +2 -0
- package/lib/remark-lint/translation-parity/frontmatter-preservation.js +36 -0
- package/lib/remark-lint/translation-parity/heading-sequence.d.ts +12 -0
- package/lib/remark-lint/translation-parity/heading-sequence.js +25 -0
- package/lib/remark-lint/translation-parity/index.d.ts +24 -0
- package/lib/remark-lint/translation-parity/index.js +24 -0
- package/lib/remark-lint/translation-parity/jsx-attribute-parity.d.ts +14 -0
- package/lib/remark-lint/translation-parity/jsx-attribute-parity.js +47 -0
- package/lib/remark-lint/translation-parity/length-ratio.d.ts +2 -0
- package/lib/remark-lint/translation-parity/length-ratio.js +49 -0
- package/lib/remark-lint/translation-parity/link-isomorphism.d.ts +34 -0
- package/lib/remark-lint/translation-parity/link-isomorphism.js +81 -0
- package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
- package/lib/remark-lint/translation-parity/shared.js +286 -0
- package/lib/remark-lint/translation-parity/terminology-adherence.d.ts +2 -0
- package/lib/remark-lint/translation-parity/terminology-adherence.js +67 -0
- package/lib/remark-lint/translation-parity/up-to-date.d.ts +11 -0
- package/lib/remark-lint/translation-parity/up-to-date.js +21 -0
- package/lib/remark-lint/translation-parity/url-residue.d.ts +3 -0
- package/lib/remark-lint/translation-parity/url-residue.js +67 -0
- package/lib/remarkrc.d.ts +1 -1
- package/lib/remarkrc.js +7 -34
- package/lib/runtime/api-paths.d.ts +20 -0
- package/lib/runtime/api-paths.js +29 -0
- package/lib/runtime/components/K8sAPI.d.ts +14 -1
- package/lib/runtime/components/K8sAPI.js +49 -10
- package/lib/runtime/components/K8sCrd.d.ts +1 -1
- package/lib/runtime/components/K8sPermissionTable.js +10 -5
- package/lib/runtime/components/OpenAPIPath.js +19 -2
- package/lib/runtime/components/_HeadingTitle.js +24 -6
- package/lib/runtime/components/_K8sAPIEndpoints.d.ts +8 -1
- package/lib/runtime/components/_K8sAPIEndpoints.js +27 -9
- package/lib/runtime/components/_K8sAPISchema.d.ts +9 -1
- package/lib/runtime/components/_K8sAPISchema.js +24 -6
- package/lib/runtime/components/_translation-policy.d.ts +23 -0
- package/lib/runtime/components/_translation-policy.js +32 -0
- package/lib/runtime/hooks/useTranslation.d.ts +1 -1
- package/lib/runtime/translation.d.ts +68 -0
- package/lib/runtime/translation.js +51 -0
- package/lib/runtime/utils.d.ts +24 -2
- package/lib/runtime/utils.js +87 -5
- package/lib/shared/constants.d.ts +9 -0
- package/lib/shared/constants.js +14 -0
- package/lib/types.d.ts +70 -0
- package/lib/utils/helpers.js +8 -2
- package/package.json +3 -1
package/lib/plugins/api/index.js
CHANGED
|
@@ -6,7 +6,7 @@ export const apiPlugin = ({ localBasePath, }) => {
|
|
|
6
6
|
name: 'doom-api',
|
|
7
7
|
async addRuntimeModules(config, isProd) {
|
|
8
8
|
return {
|
|
9
|
-
'doom-@api-virtual': `export default ${JSON.stringify({ references: config.api?.references, pathPrefix: config.api?.pathPrefix }, null, isProd ? 0 : 2)}`,
|
|
9
|
+
'doom-@api-virtual': `export default ${JSON.stringify({ references: config.api?.references, pathPrefix: config.api?.pathPrefix, crdVersion: config.api?.crdVersion }, null, isProd ? 0 : 2)}`,
|
|
10
10
|
...(await generateRuntimeModule(config.api?.crds, 'api-crds', config.root, localBasePath, isProd)),
|
|
11
11
|
...(await generateRuntimeModule(config.api?.openapis, 'api-openapis', config.root, localBasePath, isProd, async (doc) => {
|
|
12
12
|
// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
|
|
@@ -3,8 +3,34 @@ export interface ApiPluginOptions {
|
|
|
3
3
|
localBasePath: string;
|
|
4
4
|
crds?: string[];
|
|
5
5
|
openapis?: string[];
|
|
6
|
-
|
|
6
|
+
/**
|
|
7
|
+
* Map a schema ref name to how it should be linked / whether it is documented
|
|
8
|
+
* elsewhere. A plain string is the link href (backward compatible). The object
|
|
9
|
+
* form separates the two roles a value plays:
|
|
10
|
+
*
|
|
11
|
+
* - `href`: where a `RefLink` to this schema points.
|
|
12
|
+
* - `routePath`: the page that documents this schema inline. On that page the
|
|
13
|
+
* schema is expanded; elsewhere it is only linked. `false` disables the
|
|
14
|
+
* omit entirely (always link, never expand) — the explicit form of the
|
|
15
|
+
* `.html`-href trick.
|
|
16
|
+
*/
|
|
17
|
+
references?: Record<string, string | {
|
|
18
|
+
href: string;
|
|
19
|
+
routePath?: string | false;
|
|
20
|
+
}>;
|
|
7
21
|
pathPrefix?: string;
|
|
22
|
+
/**
|
|
23
|
+
* Which version of a multi-version CRD to render by default when a page does
|
|
24
|
+
* not pass an explicit `apiVersion` prop.
|
|
25
|
+
*
|
|
26
|
+
* - `preferred` (default): the version `kubectl` resolves to — highest
|
|
27
|
+
* priority among `served` versions (GA > beta > alpha).
|
|
28
|
+
* - `storage`: the etcd storage version (`storage: true`).
|
|
29
|
+
* - `first`: legacy behavior — `spec.versions[0]`.
|
|
30
|
+
*
|
|
31
|
+
* @default 'preferred'
|
|
32
|
+
*/
|
|
33
|
+
crdVersion?: 'preferred' | 'storage' | 'first';
|
|
8
34
|
}
|
|
9
35
|
export interface CustomResourceDefinitionVersion {
|
|
10
36
|
name: string;
|
|
@@ -13,6 +39,15 @@ export interface CustomResourceDefinitionVersion {
|
|
|
13
39
|
};
|
|
14
40
|
served: boolean;
|
|
15
41
|
storage: boolean;
|
|
42
|
+
/**
|
|
43
|
+
* Subresources the API server actually exposes for this version. `/status`
|
|
44
|
+
* and `/scale` endpoints exist if and only if they are declared here — not
|
|
45
|
+
* because the schema happens to contain a `status` property.
|
|
46
|
+
*/
|
|
47
|
+
subresources?: {
|
|
48
|
+
status?: object;
|
|
49
|
+
scale?: object;
|
|
50
|
+
};
|
|
16
51
|
}
|
|
17
52
|
export interface CustomResourceDefinition {
|
|
18
53
|
apiVersion: string;
|
|
@@ -1,2 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether a file in `runtime/components/` becomes a global MDX component.
|
|
3
|
+
*
|
|
4
|
+
* The filename is the identifier: it is emitted as `import <basename> from …`
|
|
5
|
+
* into every document of every site doom builds. Two consequences, and both
|
|
6
|
+
* have bitten:
|
|
7
|
+
*
|
|
8
|
+
* - the basename must be a valid JS identifier — a hyphen in it is a syntax
|
|
9
|
+
* error in every document, not a naming nit;
|
|
10
|
+
* - it must start with an uppercase letter, or MDX reads it as an HTML tag.
|
|
11
|
+
*
|
|
12
|
+
* A module that lives here for proximity but is *not* a component — shared
|
|
13
|
+
* constants, helpers — opts out with a `_` prefix, the way `_utils.ts` always
|
|
14
|
+
* has. `test/plugins/global/components.spec.ts` enforces both halves.
|
|
15
|
+
*/
|
|
16
|
+
export declare const isGlobalComponentFile: (file: string) => boolean;
|
|
1
17
|
export declare const getGlobalComponentFiles: () => string[];
|
|
2
18
|
export declare const getGlobalComponentNames: () => string[];
|
|
@@ -2,7 +2,22 @@ import fs from 'node:fs';
|
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
import { baseResolve } from "../../utils/index.js";
|
|
4
4
|
const componentsDir = baseResolve('runtime/components');
|
|
5
|
-
|
|
5
|
+
/**
|
|
6
|
+
* Whether a file in `runtime/components/` becomes a global MDX component.
|
|
7
|
+
*
|
|
8
|
+
* The filename is the identifier: it is emitted as `import <basename> from …`
|
|
9
|
+
* into every document of every site doom builds. Two consequences, and both
|
|
10
|
+
* have bitten:
|
|
11
|
+
*
|
|
12
|
+
* - the basename must be a valid JS identifier — a hyphen in it is a syntax
|
|
13
|
+
* error in every document, not a naming nit;
|
|
14
|
+
* - it must start with an uppercase letter, or MDX reads it as an HTML tag.
|
|
15
|
+
*
|
|
16
|
+
* A module that lives here for proximity but is *not* a component — shared
|
|
17
|
+
* constants, helpers — opts out with a `_` prefix, the way `_utils.ts` always
|
|
18
|
+
* has. `test/plugins/global/components.spec.ts` enforces both halves.
|
|
19
|
+
*/
|
|
20
|
+
export const isGlobalComponentFile = (file) => {
|
|
6
21
|
const basename = path.basename(file, path.extname(file));
|
|
7
22
|
return (!basename.startsWith('_') &&
|
|
8
23
|
!basename.endsWith('.d') &&
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { Root } from 'mdast';
|
|
2
2
|
import type { Plugin } from 'unified';
|
|
3
|
+
import type { VFile } from 'vfile';
|
|
3
4
|
export * from './check-dead-links.ts';
|
|
4
5
|
export * from './file-naming.ts';
|
|
5
6
|
export * from './heading-anchor-format.ts';
|
|
@@ -17,9 +18,28 @@ export * from './no-legacy-os-names.ts';
|
|
|
17
18
|
export * from './no-multi-open-api-paths.ts';
|
|
18
19
|
export * from './no-paragraph-indent.ts';
|
|
19
20
|
export * from './no-unmatched-anchor.ts';
|
|
21
|
+
export * from './no-unopened-frontmatter.ts';
|
|
22
|
+
export * from './no-unparsed-emphasis.ts';
|
|
23
|
+
export * from './no-unresolved-api-ref.ts';
|
|
20
24
|
export * from './site.ts';
|
|
21
25
|
export * from './table-size.ts';
|
|
22
26
|
export * from './title-required.ts';
|
|
27
|
+
export * from './translation-parity/index.ts';
|
|
23
28
|
export * from './unit-case.ts';
|
|
24
29
|
declare const doomLint: Plugin<[], Root>;
|
|
30
|
+
/**
|
|
31
|
+
* Drops the Chinese-typography rules' messages on documents that are not
|
|
32
|
+
* Chinese.
|
|
33
|
+
*
|
|
34
|
+
* Filtering afterwards rather than not running the rules is deliberate: the
|
|
35
|
+
* rules are third-party plugins with no notion of language, and message control
|
|
36
|
+
* already establishes that filtering `file.messages` is how this rule set
|
|
37
|
+
* expresses "this does not apply here".
|
|
38
|
+
*
|
|
39
|
+
* A document whose language cannot be told from its path keeps its messages —
|
|
40
|
+
* not knowing is a reason to report, not a reason to go quiet.
|
|
41
|
+
*/
|
|
42
|
+
export declare const dropChineseTypographyMessages: (file: VFile) => void;
|
|
43
|
+
/** Must come after the rules it filters. */
|
|
44
|
+
export declare const chineseTypographyOnlyInChinese: Plugin<[], Root>;
|
|
25
45
|
export default doomLint;
|
package/lib/remark-lint/index.js
CHANGED
|
@@ -16,9 +16,13 @@ export * from "./no-legacy-os-names.js";
|
|
|
16
16
|
export * from "./no-multi-open-api-paths.js";
|
|
17
17
|
export * from "./no-paragraph-indent.js";
|
|
18
18
|
export * from "./no-unmatched-anchor.js";
|
|
19
|
+
export * from "./no-unopened-frontmatter.js";
|
|
20
|
+
export * from "./no-unparsed-emphasis.js";
|
|
21
|
+
export * from "./no-unresolved-api-ref.js";
|
|
19
22
|
export * from "./site.js";
|
|
20
23
|
export * from "./table-size.js";
|
|
21
24
|
export * from "./title-required.js";
|
|
25
|
+
export * from "./translation-parity/index.js";
|
|
22
26
|
export * from "./unit-case.js";
|
|
23
27
|
const doomLint = function () {
|
|
24
28
|
this.use(() => remarkMessageControl({
|
|
@@ -26,4 +30,40 @@ const doomLint = function () {
|
|
|
26
30
|
source: ['doom-lint', 'remark-lint'],
|
|
27
31
|
}));
|
|
28
32
|
};
|
|
33
|
+
/**
|
|
34
|
+
* Rules about Chinese typography, which only mean anything on a Chinese
|
|
35
|
+
* document.
|
|
36
|
+
*
|
|
37
|
+
* They came into the rule set when the only documents anyone linted were
|
|
38
|
+
* Chinese. Once translations are linted too they read `pod’ами` — Russian
|
|
39
|
+
* declining a Latin word, which is how Russian does it — as an unmatched
|
|
40
|
+
* quotation mark, and report every page that uses one.
|
|
41
|
+
*/
|
|
42
|
+
const CHINESE_ONLY_RULES = new Set([
|
|
43
|
+
'match-punctuation',
|
|
44
|
+
'no-chinese-punctuation-in-number',
|
|
45
|
+
]);
|
|
46
|
+
const CHINESE_DOCUMENT = /(?:^|[\\/])zh[\\/]/;
|
|
47
|
+
/**
|
|
48
|
+
* Drops the Chinese-typography rules' messages on documents that are not
|
|
49
|
+
* Chinese.
|
|
50
|
+
*
|
|
51
|
+
* Filtering afterwards rather than not running the rules is deliberate: the
|
|
52
|
+
* rules are third-party plugins with no notion of language, and message control
|
|
53
|
+
* already establishes that filtering `file.messages` is how this rule set
|
|
54
|
+
* expresses "this does not apply here".
|
|
55
|
+
*
|
|
56
|
+
* A document whose language cannot be told from its path keeps its messages —
|
|
57
|
+
* not knowing is a reason to report, not a reason to go quiet.
|
|
58
|
+
*/
|
|
59
|
+
export const dropChineseTypographyMessages = (file) => {
|
|
60
|
+
if (!file.path || CHINESE_DOCUMENT.test(file.path)) {
|
|
61
|
+
return;
|
|
62
|
+
}
|
|
63
|
+
file.messages = file.messages.filter((message) => !CHINESE_ONLY_RULES.has(message.ruleId ?? ''));
|
|
64
|
+
};
|
|
65
|
+
/** Must come after the rules it filters. */
|
|
66
|
+
export const chineseTypographyOnlyInChinese = () => (_tree, file) => {
|
|
67
|
+
dropChineseTypographyMessages(file);
|
|
68
|
+
};
|
|
29
69
|
export default doomLint;
|
|
@@ -1,2 +1,12 @@
|
|
|
1
1
|
import type { Root } from 'mdast';
|
|
2
|
+
/**
|
|
3
|
+
* Forget what this document looked like the last time it was linted.
|
|
4
|
+
*
|
|
5
|
+
* Both caches key on a path and assume a path names one fixed document, which
|
|
6
|
+
* holds for a lint run over a directory. The translator breaks that assumption:
|
|
7
|
+
* it checks the same target path once per repair turn, with different content
|
|
8
|
+
* each time. Without this, turn 2 is judged against turn 1's anchors — a red
|
|
9
|
+
* that no amount of repairing can clear, because the repair is invisible.
|
|
10
|
+
*/
|
|
11
|
+
export declare const forgetDocumentAnchors: (filepath: string) => void;
|
|
2
12
|
export declare const noUnmatchedAnchor: import("unified-lint-rule").Plugin<Root, unknown>;
|
|
@@ -6,10 +6,23 @@ import { lintRule } from 'unified-lint-rule';
|
|
|
6
6
|
import { visit } from 'unist-util-visit';
|
|
7
7
|
import { visitParents } from 'unist-util-visit-parents';
|
|
8
8
|
import { isDoc } from "../cli/helpers.js";
|
|
9
|
-
import {
|
|
9
|
+
import { syntaxProcessor } from "./syntax-plugins.js";
|
|
10
10
|
import { getConfig } from "./utils.js";
|
|
11
11
|
const anchorsCache = new Map();
|
|
12
12
|
const astCache = new Map();
|
|
13
|
+
/**
|
|
14
|
+
* Forget what this document looked like the last time it was linted.
|
|
15
|
+
*
|
|
16
|
+
* Both caches key on a path and assume a path names one fixed document, which
|
|
17
|
+
* holds for a lint run over a directory. The translator breaks that assumption:
|
|
18
|
+
* it checks the same target path once per repair turn, with different content
|
|
19
|
+
* each time. Without this, turn 2 is judged against turn 1's anchors — a red
|
|
20
|
+
* that no amount of repairing can clear, because the repair is invisible.
|
|
21
|
+
*/
|
|
22
|
+
export const forgetDocumentAnchors = (filepath) => {
|
|
23
|
+
anchorsCache.delete(filepath);
|
|
24
|
+
astCache.delete(filepath);
|
|
25
|
+
};
|
|
13
26
|
const getAnchors = (filepath) => {
|
|
14
27
|
if (anchorsCache.has(filepath)) {
|
|
15
28
|
return anchorsCache.get(filepath);
|
|
@@ -17,7 +30,11 @@ const getAnchors = (filepath) => {
|
|
|
17
30
|
const anchors = new Set();
|
|
18
31
|
let ast = astCache.get(filepath);
|
|
19
32
|
if (!ast) {
|
|
20
|
-
|
|
33
|
+
// The same stack the lint pipeline uses, so a document's anchors do not
|
|
34
|
+
// depend on whether this run happened to lint it before reading it.
|
|
35
|
+
const processor = filepath.endsWith('.mdx')
|
|
36
|
+
? syntaxProcessor.mdx
|
|
37
|
+
: syntaxProcessor.md;
|
|
21
38
|
ast = processor.parse(fs.readFileSync(filepath, 'utf-8'));
|
|
22
39
|
astCache.set(filepath, ast);
|
|
23
40
|
}
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import { lintRule } from 'unified-lint-rule';
|
|
2
|
+
import { pointStart } from 'unist-util-position';
|
|
3
|
+
import { visit } from 'unist-util-visit';
|
|
4
|
+
/**
|
|
5
|
+
* Frontmatter whose opening `---` is missing.
|
|
6
|
+
*
|
|
7
|
+
* A document that starts
|
|
8
|
+
*
|
|
9
|
+
* ```
|
|
10
|
+
* weight: 13
|
|
11
|
+
* ---
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* has no frontmatter at all. What it has is a setext heading: a line of text
|
|
15
|
+
* underlined by `---` is a level-two heading, so the page gets a heading called
|
|
16
|
+
* "weight: 13" and loses whatever the frontmatter was supposed to say.
|
|
17
|
+
*
|
|
18
|
+
* Nothing else notices. The file parses, every link resolves, the heading is a
|
|
19
|
+
* perfectly ordinary heading — `heading-increment` sees a rank drop from 2 to 1
|
|
20
|
+
* and is fine with it, `title-required` finds the `#` heading below and is
|
|
21
|
+
* satisfied. It took a *translation* to surface it, because comparing the two
|
|
22
|
+
* documents showed a heading the translation did not have. A single document
|
|
23
|
+
* cannot tell "weight: 13" from a heading someone meant to write; this rule can,
|
|
24
|
+
* because it only looks at the very first node and only at the keys doom's
|
|
25
|
+
* frontmatter actually uses.
|
|
26
|
+
*
|
|
27
|
+
* Measured on acp-docs before being turned on: 914 English documents, of which
|
|
28
|
+
* 88 legitimately have no frontmatter (generated api pages, index pages) — and
|
|
29
|
+
* exactly one of those 88 opens with something shaped like a frontmatter key.
|
|
30
|
+
* One true positive, no false ones. "Every document must have frontmatter"
|
|
31
|
+
* would have reported all 88.
|
|
32
|
+
*/
|
|
33
|
+
/**
|
|
34
|
+
* The keys doom's frontmatter actually uses, counted across acp-docs rather
|
|
35
|
+
* than remembered: weight 797 · sourceSHA 194 · title 132 · i18n 125 ·
|
|
36
|
+
* queries 73 · description 21 · category 5 · author 4.
|
|
37
|
+
*
|
|
38
|
+
* Deliberately a list and not `\w+:` — a heading really can begin "Note:" or
|
|
39
|
+
* "Step 1:", and reporting those would be a rule nobody keeps.
|
|
40
|
+
*/
|
|
41
|
+
const FRONTMATTER_KEYS = [
|
|
42
|
+
'author',
|
|
43
|
+
'category',
|
|
44
|
+
'description',
|
|
45
|
+
'i18n',
|
|
46
|
+
'queries',
|
|
47
|
+
'sourceSHA',
|
|
48
|
+
'title',
|
|
49
|
+
'weight',
|
|
50
|
+
];
|
|
51
|
+
const OPENS_WITH_FRONTMATTER_KEY = new RegExp(`^(?:${FRONTMATTER_KEYS.join('|')})\\s*:`);
|
|
52
|
+
export const noUnopenedFrontmatter = lintRule('doom-lint:no-unopened-frontmatter', (root, vfile) => {
|
|
53
|
+
if (root.children.length === 0) {
|
|
54
|
+
return;
|
|
55
|
+
}
|
|
56
|
+
const [first] = root.children;
|
|
57
|
+
// Frontmatter that opened properly is a `yaml` node, not a heading.
|
|
58
|
+
if (first.type !== 'heading') {
|
|
59
|
+
return;
|
|
60
|
+
}
|
|
61
|
+
let text = '';
|
|
62
|
+
visit(first, 'text', (node) => {
|
|
63
|
+
text += node.value;
|
|
64
|
+
});
|
|
65
|
+
const match = OPENS_WITH_FRONTMATTER_KEY.exec(text.trim());
|
|
66
|
+
if (!match) {
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
vfile.message(`This document opens with a heading called \`${text.trim()}\`, which is frontmatter that never opened: the \`---\` above it is missing, so the line below it underlined it into a heading instead. Add the opening \`---\`.`, { ancestors: [first], place: pointStart(first) });
|
|
70
|
+
});
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import { lintRule } from 'unified-lint-rule';
|
|
2
|
+
import { pointStart } from 'unist-util-position';
|
|
3
|
+
import { visitParents } from 'unist-util-visit-parents';
|
|
4
|
+
/**
|
|
5
|
+
* Emphasis delimiters that did not become emphasis.
|
|
6
|
+
*
|
|
7
|
+
* `**bold**` only works when the delimiters flank the text: `** bold **` does
|
|
8
|
+
* not, and neither does `**注意:**卸载`, because the closing run is preceded by
|
|
9
|
+
* punctuation and followed by a letter. Either way the page shows the asterisks
|
|
10
|
+
* to the reader, and nothing else notices — the document parses, every link
|
|
11
|
+
* resolves, every component is present.
|
|
12
|
+
*
|
|
13
|
+
* A `text` node holding `**` is exactly that situation: the delimiters reached
|
|
14
|
+
* the tree as literal characters instead of wrapping anything.
|
|
15
|
+
*
|
|
16
|
+
* Measured on the acp-docs corpus before being turned on: 2 of 922 English
|
|
17
|
+
* documents, 7 of 875 Chinese, 2 of 875 Russian — 11 in all, every one of them
|
|
18
|
+
* a real page with literal asterisks on it, and two of them the English source
|
|
19
|
+
* of the Russian pair. The Chinese cases are the common shape: a translation
|
|
20
|
+
* writes `**注意:**此标签`, which is bold in the source's spacing and is not in
|
|
21
|
+
* the translation's.
|
|
22
|
+
*
|
|
23
|
+
* `__`, which CommonMark treats the same way, is covered by the same rule and
|
|
24
|
+
* by its tests, but was not measured — it does not occur in this corpus at all.
|
|
25
|
+
*
|
|
26
|
+
* A document that means to show literal asterisks says so with
|
|
27
|
+
* `<!-- lint disable no-unparsed-emphasis -->`.
|
|
28
|
+
*/
|
|
29
|
+
/**
|
|
30
|
+
* A `**` anywhere, or a `__` that is not inside a word.
|
|
31
|
+
*
|
|
32
|
+
* `__` gets the narrower test because `snake__case` in prose is not emphasis
|
|
33
|
+
* anyone attempted, while `**` in prose is not something anyone types by
|
|
34
|
+
* accident.
|
|
35
|
+
*/
|
|
36
|
+
const UNPARSED_EMPHASIS = /\*\*|(?<![\p{L}\p{N}])__|__(?![\p{L}\p{N}])/u;
|
|
37
|
+
export const noUnparsedEmphasis = lintRule('doom-lint:no-unparsed-emphasis', (root, vfile) => {
|
|
38
|
+
visitParents(root, 'text', (node, parents) => {
|
|
39
|
+
const match = UNPARSED_EMPHASIS.exec(node.value);
|
|
40
|
+
if (!match) {
|
|
41
|
+
return;
|
|
42
|
+
}
|
|
43
|
+
const delimiter = match[0];
|
|
44
|
+
vfile.message(`\`${delimiter}\` is printed to the page here, not read as emphasis: \`${preview(node.value, match.index)}\`. ` +
|
|
45
|
+
`Emphasis delimiters must sit directly against the text they emphasise — \`**text**\`, not \`** text **\` and not \`**text:**more\`.`, { ancestors: [...parents, node], place: pointStart(node) });
|
|
46
|
+
});
|
|
47
|
+
});
|
|
48
|
+
/** A short window around the offending delimiter, for a person reading the log. */
|
|
49
|
+
const preview = (value, index) => {
|
|
50
|
+
const from = Math.max(0, index - 20);
|
|
51
|
+
const to = Math.min(value.length, index + 30);
|
|
52
|
+
return `${from > 0 ? '…' : ''}${value.slice(from, to)}${to < value.length ? '…' : ''}`;
|
|
53
|
+
};
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { Root } from 'mdast';
|
|
2
|
+
import type { Node, Position } from 'unist';
|
|
3
|
+
/**
|
|
4
|
+
* Build-integrity face for the API components (DOOM-1).
|
|
5
|
+
*
|
|
6
|
+
* Every `<K8sAPI>` / `<K8sCrd>` / `<OpenAPIRef>` / `<OpenAPIPath>` /
|
|
7
|
+
* `<K8sPermissionTable>` whose reference cannot be resolved renders a blank page
|
|
8
|
+
* (or a table with vanished rows) with a green `doom build`. These components
|
|
9
|
+
* scatter `console.error` calls that are never surfaced. This rule resolves the
|
|
10
|
+
* same sources the runtime plugins load and reports an unresolved reference at
|
|
11
|
+
* lint time, before it ships silently.
|
|
12
|
+
*/
|
|
13
|
+
export interface ApiSources {
|
|
14
|
+
crdNames: Set<string>;
|
|
15
|
+
schemaNames: Set<string>;
|
|
16
|
+
/**
|
|
17
|
+
* OpenAPI schema names that carry no `x-kubernetes-group-version-kind`
|
|
18
|
+
* extension. `<K8sAPI>` derives the endpoint paths' group/version/kind from
|
|
19
|
+
* that extension (or from a CRD); without either, the paths cannot be built
|
|
20
|
+
* from facts and the caller has to declare them via props.
|
|
21
|
+
*/
|
|
22
|
+
schemaNamesWithoutGvk: Set<string>;
|
|
23
|
+
pathNames: Set<string>;
|
|
24
|
+
functionNames: Set<string>;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Reads a Kubernetes source that may be either a single resource or a
|
|
28
|
+
* `kind: List` wrapper.
|
|
29
|
+
*
|
|
30
|
+
* The permission plugin unwraps `items` when it builds the runtime module, so a
|
|
31
|
+
* check that reads `metadata.name` off the wrapper finds nothing at all and
|
|
32
|
+
* then reports every reference as unresolved.
|
|
33
|
+
*/
|
|
34
|
+
export declare const unwrapK8sList: <T>(doc: unknown) => T[];
|
|
35
|
+
/**
|
|
36
|
+
* The rule's decision logic, separated from source loading so it can be
|
|
37
|
+
* exercised against hand-built {@link ApiSources} in tests.
|
|
38
|
+
*/
|
|
39
|
+
export declare const checkApiRefs: (root: Root, sources: ApiSources, report: (message: string, place: Position | undefined, ancestors: Node[]) => void) => void;
|
|
40
|
+
export declare const noUnresolvedApiRef: import("unified-lint-rule").Plugin<Root, unknown>;
|
|
@@ -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
|
+
});
|