@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,2 @@
1
+ import { Command } from 'commander';
2
+ export declare const apiCommand: Command;
package/lib/cli/api.js ADDED
@@ -0,0 +1,147 @@
1
+ import path from 'node:path';
2
+ import { logger } from '@rspress/core';
3
+ import { Command } from 'commander';
4
+ import { glob } from 'tinyglobby';
5
+ import { cyan, red, yellow } from 'yoctocolors';
6
+ import { resolveStaticConfig } from "../utils/helpers.js";
7
+ import { loadConfig } from "./load-config.js";
8
+ const rel = (base, file) => path.relative(base, file) || file;
9
+ /**
10
+ * `doom api check` — a zero-network, offline validation of the local API
11
+ * schema sources (`api.crds` / `api.openapis`). It closes the gap the ingest
12
+ * contract leaves open: there is no naming rule, no drift detection and no
13
+ * conflict report for the hand-committed CRD / OpenAPI files. It never talks to
14
+ * a cluster; it only reads what is already on disk, so a documentation build
15
+ * stays reproducible.
16
+ */
17
+ const checkApiSources = async (root, globalOptions) => {
18
+ const { config, configFilePath } = await loadConfig(root, globalOptions);
19
+ const base = configFilePath ? path.dirname(configFilePath) : config.root;
20
+ const problems = [];
21
+ const warnings = [];
22
+ // ---- CRDs -------------------------------------------------------------
23
+ const crdFiles = config.api?.crds?.length
24
+ ? await glob(config.api.crds, { cwd: base, absolute: true })
25
+ : [];
26
+ const crdNameOwners = new Map();
27
+ for (const file of crdFiles) {
28
+ let crd;
29
+ try {
30
+ crd = await resolveStaticConfig(file);
31
+ }
32
+ catch (error) {
33
+ problems.push({
34
+ file: rel(base, file),
35
+ message: `failed to parse: ${error.message}`,
36
+ });
37
+ continue;
38
+ }
39
+ if (crd?.kind !== 'CustomResourceDefinition') {
40
+ problems.push({
41
+ file: rel(base, file),
42
+ message: `not a CustomResourceDefinition (kind: ${cyan(String(crd?.kind))})`,
43
+ });
44
+ continue;
45
+ }
46
+ const name = crd.metadata?.name;
47
+ if (!name) {
48
+ problems.push({ file: rel(base, file), message: 'missing metadata.name' });
49
+ continue;
50
+ }
51
+ const previous = crdNameOwners.get(name);
52
+ if (previous) {
53
+ problems.push({
54
+ file: rel(base, file),
55
+ message: `duplicate CRD \`${cyan(name)}\` (also in ${cyan(previous)})`,
56
+ });
57
+ }
58
+ else {
59
+ crdNameOwners.set(name, rel(base, file));
60
+ }
61
+ // Filename convention: `<group>_<plural>.yaml`.
62
+ const group = crd.spec?.group;
63
+ const plural = crd.spec?.names?.plural;
64
+ if (group && plural) {
65
+ const expected = `${group}_${plural}.yaml`;
66
+ const actual = path.basename(file);
67
+ if (actual !== expected && actual !== `${group}_${plural}.yml`) {
68
+ warnings.push({
69
+ file: rel(base, file),
70
+ message: `filename \`${actual}\` does not match the \`<group>_<plural>.yaml\` convention (expected \`${cyan(expected)}\`)`,
71
+ });
72
+ }
73
+ }
74
+ }
75
+ // ---- OpenAPI definitions ---------------------------------------------
76
+ const openapiFiles = config.api?.openapis?.length
77
+ ? await glob(config.api.openapis, { cwd: base, absolute: true })
78
+ : [];
79
+ // schema name -> list of { file, content }
80
+ const schemaOwners = new Map();
81
+ for (const file of openapiFiles) {
82
+ let doc;
83
+ try {
84
+ doc = await resolveStaticConfig(file);
85
+ }
86
+ catch (error) {
87
+ problems.push({
88
+ file: rel(base, file),
89
+ message: `failed to parse: ${error.message}`,
90
+ });
91
+ continue;
92
+ }
93
+ const components = doc?.components;
94
+ const schemas = {
95
+ ...(components?.schemas ?? {}),
96
+ ...(doc?.definitions ?? {}),
97
+ };
98
+ for (const [name, schema] of Object.entries(schemas)) {
99
+ const list = schemaOwners.get(name) ?? [];
100
+ list.push({ file: rel(base, file), content: JSON.stringify(schema) });
101
+ schemaOwners.set(name, list);
102
+ }
103
+ }
104
+ let duplicateNames = 0;
105
+ let conflictNames = 0;
106
+ for (const [name, owners] of schemaOwners) {
107
+ if (owners.length < 2) {
108
+ continue;
109
+ }
110
+ duplicateNames++;
111
+ const distinctContent = new Set(owners.map((o) => o.content));
112
+ if (distinctContent.size > 1) {
113
+ conflictNames++;
114
+ problems.push({
115
+ file: owners.map((o) => o.file).join(', '),
116
+ message: `OpenAPI definition \`${cyan(name)}\` is defined ${owners.length} times with ${distinctContent.size} different bodies`,
117
+ });
118
+ }
119
+ }
120
+ // ---- report -----------------------------------------------------------
121
+ logger.info(`Checked ${cyan(String(crdFiles.length))} CRD file(s) and ${cyan(String(openapiFiles.length))} OpenAPI file(s).`);
122
+ if (duplicateNames) {
123
+ logger.info(`${cyan(String(duplicateNames))} OpenAPI definition name(s) appear in more than one file (${conflictNames} with conflicting bodies).`);
124
+ }
125
+ for (const w of warnings) {
126
+ logger.warn(`${yellow(w.file)}: ${w.message}`);
127
+ }
128
+ for (const p of problems) {
129
+ logger.error(`${red(p.file)}: ${p.message}`);
130
+ }
131
+ if (problems.length) {
132
+ logger.error(`\`doom api check\` found ${red(String(problems.length))} problem(s) and ${warnings.length} warning(s).`);
133
+ process.exitCode = 1;
134
+ }
135
+ else {
136
+ logger.success(`\`doom api check\` passed with ${warnings.length} warning(s).`);
137
+ }
138
+ };
139
+ export const apiCommand = new Command('api').description('Work with the local API schema sources (`api.crds` / `api.openapis`)');
140
+ apiCommand
141
+ .command('check')
142
+ .description('Validate the local CRD / OpenAPI sources offline: every file parses, CRDs have the right kind, names are unique, filenames follow the `<group>_<plural>.yaml` convention, and OpenAPI definitions do not conflict across files')
143
+ .argument('[root]', 'Root directory of the documentation')
144
+ .action(async function (root) {
145
+ const globalOptions = this.optsWithGlobals();
146
+ await checkApiSources(root, globalOptions);
147
+ });
@@ -1,4 +1,4 @@
1
- import type { Code, Root, RootContent } from 'mdast';
1
+ import type { RootContent } from 'mdast';
2
2
  export declare const parseBoolean: (value?: string) => boolean;
3
3
  export declare const parseBooleanOrString: (value?: string) => string | boolean;
4
4
  export declare const isDoc: (filename: string) => boolean;
@@ -27,9 +27,3 @@ export declare const translateCodeFile: (content: RootContent, { sourceBase, tar
27
27
  sourceBase: string;
28
28
  targetBase: string;
29
29
  }) => RootContent;
30
- export interface CodeBlockPlaceholder {
31
- node: Code;
32
- placeholder: string;
33
- }
34
- export declare const replaceCodeBlocksWithPlaceholders: (content: Root | RootContent) => CodeBlockPlaceholder[];
35
- export declare const restoreCodeBlockPlaceholders: (content: Root | RootContent, placeholders: readonly CodeBlockPlaceholder[]) => RootContent | Root;
@@ -59,44 +59,7 @@ export const translateCodeFile = (content, { sourceBase, targetBase }) => {
59
59
  });
60
60
  return content;
61
61
  };
62
- const CODE_BLOCK_PLACEHOLDER_PREFIX = '__DOOM_TRANSLATE_CODE_BLOCK_';
63
- const CODE_BLOCK_PLACEHOLDER_PATTERN = new RegExp(`^${CODE_BLOCK_PLACEHOLDER_PREFIX}(\\d+)__$`);
64
- const getCodeBlockPlaceholderIndex = (value) => {
65
- const match = CODE_BLOCK_PLACEHOLDER_PATTERN.exec(value);
66
- if (!match) {
67
- return;
68
- }
69
- return +match[1];
70
- };
71
- export const replaceCodeBlocksWithPlaceholders = (content) => {
72
- const placeholders = [];
73
- visit(content, 'code', (code) => {
74
- if (code.value.length <= 50) {
75
- return;
76
- }
77
- const placeholder = `${CODE_BLOCK_PLACEHOLDER_PREFIX}${placeholders.length}__`;
78
- placeholders.push({
79
- node: { ...code },
80
- placeholder,
81
- });
82
- code.value = placeholder;
83
- delete code.lang;
84
- delete code.meta;
85
- });
86
- return placeholders;
87
- };
88
- export const restoreCodeBlockPlaceholders = (content, placeholders) => {
89
- visit(content, 'code', (code) => {
90
- const value = code.value.trim();
91
- const index = getCodeBlockPlaceholderIndex(value);
92
- if (index == null) {
93
- return;
94
- }
95
- const placeholder = placeholders.at(index);
96
- if (!placeholder || placeholder.placeholder !== value) {
97
- throw new Error(`Unmatched code block placeholder: ${value}`);
98
- }
99
- Object.assign(code, placeholder.node);
100
- });
101
- return content;
102
- };
62
+ // Code blocks used to be protected here, on their own and only above 50
63
+ // characters. That mechanism now lives in `translate-mask.ts`, which protects
64
+ // every value a translation model must not author — code blocks included, with
65
+ // no length floor.
package/lib/cli/index.js CHANGED
@@ -10,6 +10,7 @@ import { watch } from 'chokidar';
10
10
  import { program } from 'commander';
11
11
  import { green } from 'yoctocolors';
12
12
  import { setNodeEnv } from '../utils/index.js';
13
+ import { apiCommand } from './api.js';
13
14
  import { CWD, DEFAULT_CONFIGS, SITES_FILE } from './constants.js';
14
15
  import { exportCommand } from './export.js';
15
16
  import { parseBoolean, parseBooleanOrString } from './helpers.js';
@@ -153,6 +154,7 @@ program.addCommand(newCommand);
153
154
  program.addCommand(translateCommand);
154
155
  program.addCommand(exportCommand);
155
156
  program.addCommand(lintCommand);
157
+ program.addCommand(apiCommand);
156
158
  program.parseAsync().catch((err) => {
157
159
  if (err instanceof Error && err.name === 'ExitPromptError') {
158
160
  return;
@@ -0,0 +1,81 @@
1
+ import type { Model, Models, ThinkingLevel } from '@earendil-works/pi-ai';
2
+ import { Language } from '../shared/index.ts';
3
+ import { type TranslationChecker, type TranslationFinding } from './translate-checker.ts';
4
+ import type { Judge } from './translate-judge.ts';
5
+ import { type MaskEntry, type MaskProcessor } from './translate-mask.ts';
6
+ import type { TermPair } from './translate-terms.ts';
7
+ /**
8
+ * Translating one document, as a loop that ends when the document passes its
9
+ * checks.
10
+ *
11
+ * The loop is pi's. What is ours is its boundary: the tools the agent has, the
12
+ * directory it can reach, what is released from its context, and — the part
13
+ * everything else rests on — the condition under which it is allowed to stop.
14
+ *
15
+ * `getFollowUpMessages` is pi's "the agent would finish here" hook: whatever it
16
+ * returns is appended to the context and the agent takes another turn. Putting
17
+ * the harness's own check there means the agent cannot finish while the
18
+ * document still fails it. Not "we check afterwards and start it again if it
19
+ * failed" — the check *is* the exit condition, and the agent has no name for
20
+ * it, no way to call it, and no way around it.
21
+ *
22
+ * The turn cap is enforced separately, in `shouldStopAfterTurn`, which pi
23
+ * consults *before* polling for follow-ups. So a run that will not converge
24
+ * ends, and ends failed: there is no third exit where a document is written out
25
+ * anyway.
26
+ */
27
+ export interface TranslateAgentOptions {
28
+ /** The masked source, exactly as the model will see it. */
29
+ maskedSource: string;
30
+ /** The mask table, for restoring and for counting what came back. */
31
+ maskEntries: readonly MaskEntry[];
32
+ /** Parser/stringifier matching the document's flavour. */
33
+ processor: MaskProcessor;
34
+ /** Merges the restored translation with the frontmatter it will be written with. */
35
+ compose: (restored: string) => string;
36
+ /** Absolute path the translation will be written to. Rules read the language and find the source from it. */
37
+ targetPath: string;
38
+ /** Path of the source, relative to the docs root — for logs only. */
39
+ sourceLabel: string;
40
+ source: Language;
41
+ target: Language;
42
+ /** The translation rules, rendered — the same prompt body the single-shot translator used. */
43
+ translationRules: string;
44
+ /** Terms the source matched, used to keep one document's wording consistent across segments. */
45
+ terms?: readonly TermPair[];
46
+ checker: TranslationChecker;
47
+ /** The semantic check. Absent only in tests that are about control flow. */
48
+ judge?: Judge;
49
+ models: Models;
50
+ model: Model<'openai-completions'>;
51
+ reasoningEffort: ThinkingLevel;
52
+ /** Directory scratch directories are created under. */
53
+ scratchDir: string;
54
+ /** How many times findings may be fed back before the document is failed. */
55
+ maxRepairRounds: number;
56
+ /** Runaway guard: total assistant turns, tool calls included. */
57
+ maxTurns: number;
58
+ /** Applied to every model call, so an agent's extra turns count against the same budget. */
59
+ limit: <T>(run: () => Promise<T>) => Promise<T>;
60
+ /** How many times a refused request is retried before the document fails. */
61
+ maxModelRetries?: number;
62
+ /** First backoff after a refused request, doubled per attempt. */
63
+ modelRetryDelayMs?: number;
64
+ onProgress?: (message: string) => void;
65
+ }
66
+ export interface TranslateAgentResult {
67
+ /** The finished document, when it passed. */
68
+ document?: string;
69
+ /**
70
+ * What was still wrong when the run ended.
71
+ *
72
+ * `document` is set exactly when none of these block. A passing document can
73
+ * still carry advisory findings — the judge's readability notes — which are
74
+ * worth printing and are not worth failing a build over.
75
+ */
76
+ findings: TranslationFinding[];
77
+ turns: number;
78
+ repairRounds: number;
79
+ modelCalls: number;
80
+ }
81
+ export declare const translateWithAgent: (options: TranslateAgentOptions) => Promise<TranslateAgentResult>;