@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db7b338

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 (276) hide show
  1. package/README.md +22 -1
  2. package/api/blog/blog.doc.mjs +1 -0
  3. package/api/build/build.doc.mjs +1 -0
  4. package/api/component/component.doc.mjs +1 -0
  5. package/api/discover/discover.doc.mjs +1 -0
  6. package/api/docs/_adapter.d.mts +3 -8
  7. package/api/docs/_adapter.mjs +13 -105
  8. package/api/docs/detail/section/section.mjs +9 -15
  9. package/api/docs/detail/section/section.test.mjs +15 -6
  10. package/api/docs/docs.doc.mjs +1 -0
  11. package/api/docs/list/list.mjs +3 -7
  12. package/api/doctor/doctor.d.mts +25 -3
  13. package/api/doctor/doctor.doc.mjs +1 -0
  14. package/api/doctor/doctor.mjs +186 -14
  15. package/api/doctor/doctor.test.mjs +332 -7
  16. package/api/gap-report/gap-report.doc.mjs +1 -0
  17. package/api/hook/_adapter.mjs +19 -5
  18. package/api/hook/hook.doc.mjs +1 -0
  19. package/api/hook/list/list.d.mts +1 -1
  20. package/api/hook/list/list.mjs +69 -17
  21. package/api/init/init.doc.mjs +1 -0
  22. package/api/integration/add-contribution.mjs +7 -7
  23. package/api/integration/add-contribution.test.mjs +37 -3
  24. package/api/integration/add-theme.mjs +34 -64
  25. package/api/integration/add-theme.test.mjs +105 -21
  26. package/api/integration/authoring-checks.test.mjs +8 -4
  27. package/api/integration/integration-block-exports.test.mjs +10 -6
  28. package/api/integration/integrationAdd.doc.mjs +1 -0
  29. package/api/integration/integrationAddAgentDoc.doc.mjs +1 -0
  30. package/api/integration/integrationAddCodemod.doc.mjs +1 -0
  31. package/api/integration/integrationAddComponent.doc.mjs +1 -0
  32. package/api/integration/integrationAddDoc.doc.mjs +1 -0
  33. package/api/integration/integrationAddTemplate.doc.mjs +1 -0
  34. package/api/integration/integrationAddTheme.doc.mjs +6 -5
  35. package/api/integration/integrationComponentConflicts.doc.mjs +1 -0
  36. package/api/integration/integrationDocConflicts.doc.mjs +1 -0
  37. package/api/integration/integrationPackCheck.doc.mjs +1 -0
  38. package/api/integration/integrationTemplateConflicts.doc.mjs +1 -0
  39. package/api/integration/pack-check.test.mjs +17 -47
  40. package/api/integration/summarizeIssues.doc.mjs +1 -0
  41. package/api/integration/validate-integration-fixes.test.mjs +1389 -0
  42. package/api/integration/validate-integration.mjs +50 -102
  43. package/api/integration/validate-integration.test.mjs +85 -23
  44. package/api/integration/validate-unread-theme-folders.test.mjs +110 -0
  45. package/api/integration/validateIntegration.doc.mjs +1 -0
  46. package/api/json/assertResponse.doc.mjs +1 -0
  47. package/api/json/isError.doc.mjs +1 -0
  48. package/api/json/parseResponse.doc.mjs +1 -0
  49. package/api/layout/layoutCheck.doc.mjs +1 -0
  50. package/api/layout/layoutExpand.doc.mjs +1 -0
  51. package/api/layout/layoutGrammar.doc.mjs +1 -0
  52. package/api/search/search.doc.mjs +1 -0
  53. package/api/search/search.mjs +16 -6
  54. package/api/swizzle/swizzle.doc.mjs +1 -0
  55. package/api/template/template-suffix.test.mjs +41 -21
  56. package/api/template/template.doc.mjs +1 -0
  57. package/api/theme/_adapter.d.mts +2 -3
  58. package/api/theme/_adapter.mjs +4 -5
  59. package/api/theme/add/add.binary.test.mjs +10 -17
  60. package/api/theme/add/add.test.mjs +14 -1
  61. package/api/theme/generateTonalPalette.doc.mjs +1 -0
  62. package/api/theme/integration-themes.test.mjs +39 -28
  63. package/api/theme/list/list.test.mjs +19 -20
  64. package/api/theme/listThemes.doc.mjs +6 -5
  65. package/api/theme/themeAdd.doc.mjs +4 -3
  66. package/api/theme/themeBuild.doc.mjs +1 -0
  67. package/api/theme/themeList.doc.mjs +6 -3
  68. package/api/theme/themeListAvailable.doc.mjs +5 -3
  69. package/api/theme/themePaletteGenerate.doc.mjs +1 -0
  70. package/api/theme/themeTargets.doc.mjs +1 -0
  71. package/api/theme/themeTemplate.doc.mjs +1 -0
  72. package/api/upgrade/_adapter.d.mts +32 -5
  73. package/api/upgrade/_adapter.mjs +97 -69
  74. package/api/upgrade/provider-agreement.test.mjs +152 -0
  75. package/api/upgrade/run/run.mjs +356 -59
  76. package/api/upgrade/upgrade.doc.mjs +6 -1
  77. package/api/upgrade/upgrade.type.d.mts +34 -0
  78. package/api/upgrade/upgrade.type.mjs +15 -0
  79. package/assets/codemods/__tests__/runner.test.mjs +330 -8
  80. package/assets/codemods/integration-discovery.mjs +8 -2
  81. package/assets/codemods/integration-discovery.test.mjs +15 -0
  82. package/assets/codemods/integration-runner.mjs +56 -4
  83. package/assets/codemods/integration-runner.protection.test.mjs +153 -0
  84. package/assets/codemods/run-codemod.mjs +177 -34
  85. package/assets/codemods/runner.mjs +350 -102
  86. package/assets/codemods/transforms/next/__tests__/migrate-native-picker-to-presentation.test.mjs +63 -0
  87. package/assets/codemods/transforms/next/__tests__/migrate-theme-catalog-to-descriptors.test.mjs +220 -0
  88. package/assets/codemods/transforms/next/index.mjs +19 -1
  89. package/assets/codemods/transforms/next/migrate-native-picker-to-presentation.mjs +148 -0
  90. package/assets/codemods/transforms/next/migrate-theme-catalog-to-descriptors.mjs +141 -0
  91. package/assets/docs/cli-integrations.doc.mjs +30 -30
  92. package/assets/docs/cli.doc.mjs +15 -0
  93. package/assets/docs/theme.doc.mjs +1 -1
  94. package/assets/templates/blocks/components/DateInput/DateInputDateRange.tsx +1 -1
  95. package/assets/templates/blocks/components/Item/ItemDocumentTabs.doc.mjs +14 -0
  96. package/assets/templates/blocks/components/Item/ItemDocumentTabs.tsx +100 -0
  97. package/assets/templates/blocks/components/TimeInput/TimeInputConstrained.tsx +1 -0
  98. package/assets/templates/themes/butter/butterTheme.doc.mjs +11 -0
  99. package/assets/templates/themes/chocolate/chocolateTheme.doc.mjs +11 -0
  100. package/assets/templates/themes/gothic/gothicTheme.doc.mjs +11 -0
  101. package/assets/templates/themes/matcha/matchaTheme.doc.mjs +11 -0
  102. package/assets/templates/themes/neutral/neutralTheme.doc.mjs +11 -0
  103. package/assets/templates/themes/stone/stoneTheme.doc.mjs +11 -0
  104. package/assets/templates/themes/y2k/y2kTheme.doc.mjs +11 -0
  105. package/authoring/codemod/codemod.doc.mjs +1 -1
  106. package/authoring/codemod/type.ts +12 -0
  107. package/authoring/config/config.doc.mjs +1 -1
  108. package/authoring/debug/debug.doc.d.mts +11 -0
  109. package/authoring/debug/debug.doc.mjs +182 -0
  110. package/authoring/doctypes/_schema.d.mts +71 -141
  111. package/authoring/doctypes/_schema.mjs +29 -2
  112. package/authoring/doctypes/base/graph-fields.doc.mjs +1 -1
  113. package/authoring/doctypes/command/command.doc.mjs +1 -1
  114. package/authoring/doctypes/command/type.ts +1 -1
  115. package/authoring/doctypes/component/type.ts +2 -2
  116. package/authoring/doctypes/doctypes-new.test.mjs +48 -6
  117. package/authoring/doctypes/enum/enum.doc.mjs +1 -1
  118. package/authoring/doctypes/enum/type.ts +1 -1
  119. package/authoring/doctypes/function/function.doc.mjs +1 -1
  120. package/authoring/doctypes/function/type.ts +1 -1
  121. package/authoring/doctypes/hook/type.ts +2 -2
  122. package/authoring/doctypes/load-contract.test.mjs +3 -2
  123. package/authoring/doctypes/namespace/namespace.doc.mjs +2 -2
  124. package/authoring/doctypes/namespace/parse.test.mjs +23 -25
  125. package/authoring/doctypes/namespace/type.ts +5 -2
  126. package/authoring/doctypes/parse.d.mts +4 -2
  127. package/authoring/doctypes/parse.mjs +10 -5
  128. package/authoring/doctypes/reference/reference.doc.mjs +6 -4
  129. package/authoring/doctypes/reference/type.ts +9 -10
  130. package/authoring/doctypes/schema/schema.doc.mjs +1 -1
  131. package/authoring/doctypes/schema/type.ts +1 -2
  132. package/authoring/doctypes/template/template.doc.mjs +3 -3
  133. package/authoring/doctypes/theme/parse.d.mts +35 -0
  134. package/authoring/doctypes/theme/parse.mjs +76 -0
  135. package/authoring/doctypes/theme/theme.doc.d.mts +9 -0
  136. package/authoring/doctypes/theme/theme.doc.mjs +79 -0
  137. package/authoring/doctypes/theme/type.ts +42 -0
  138. package/authoring/doctypes/types.ts +2 -1
  139. package/authoring/gap-report/gap-report.doc.d.mts +12 -0
  140. package/authoring/gap-report/gap-report.doc.mjs +183 -0
  141. package/authoring/index.d.mts +1 -0
  142. package/authoring/index.d.ts +7 -4
  143. package/authoring/index.mjs +2 -1
  144. package/authoring/integration/integration.doc.mjs +2 -2
  145. package/authoring/integration/type.ts +3 -9
  146. package/clients/cli/__tests__/cliManifest.test.ts +27 -29
  147. package/clients/cli/commands/blog.doc.mjs +1 -1
  148. package/clients/cli/commands/build-theme.adaptations.test.mjs +100 -1
  149. package/clients/cli/commands/build-theme.mjs +10 -44
  150. package/clients/cli/commands/build.doc.mjs +1 -1
  151. package/clients/cli/commands/component.doc.mjs +1 -1
  152. package/clients/cli/commands/discover.doc.mjs +1 -1
  153. package/clients/cli/commands/docs.doc.mjs +1 -1
  154. package/clients/cli/commands/docs.mjs +15 -58
  155. package/clients/cli/commands/docs.test.mjs +11 -14
  156. package/clients/cli/commands/doctor-integration-components.doc.mjs +1 -1
  157. package/clients/cli/commands/doctor-integration-docs.doc.mjs +1 -1
  158. package/clients/cli/commands/doctor-integration-templates.doc.mjs +1 -1
  159. package/clients/cli/commands/doctor-integration-validate.doc.mjs +1 -1
  160. package/clients/cli/commands/doctor-integration.doc.mjs +1 -1
  161. package/clients/cli/commands/doctor-integration.test.mjs +15 -7
  162. package/clients/cli/commands/doctor.doc.mjs +1 -1
  163. package/clients/cli/commands/gap-report.doc.mjs +1 -1
  164. package/clients/cli/commands/hook.doc.mjs +1 -1
  165. package/clients/cli/commands/init.doc.mjs +1 -1
  166. package/clients/cli/commands/integration-add.controls.test.mjs +1 -1
  167. package/clients/cli/commands/integration-add.doc.mjs +1 -1
  168. package/clients/cli/commands/integration-pack.doc.mjs +1 -1
  169. package/clients/cli/commands/integration-real-world.test.mjs +3 -9
  170. package/clients/cli/commands/integration.doc.mjs +1 -1
  171. package/clients/cli/commands/layout-check.doc.mjs +1 -1
  172. package/clients/cli/commands/layout-expand.doc.mjs +1 -1
  173. package/clients/cli/commands/layout-grammar.doc.mjs +1 -1
  174. package/clients/cli/commands/layout.doc.mjs +1 -1
  175. package/clients/cli/commands/manifest.doc.mjs +1 -1
  176. package/clients/cli/commands/search.doc.mjs +1 -1
  177. package/clients/cli/commands/swizzle.doc.mjs +1 -1
  178. package/clients/cli/commands/template.doc.mjs +1 -1
  179. package/clients/cli/commands/text-json-parity.test.mjs +718 -0
  180. package/clients/cli/commands/theme-add.doc.mjs +2 -2
  181. package/clients/cli/commands/theme-build.doc.mjs +1 -1
  182. package/clients/cli/commands/theme-list.doc.mjs +2 -2
  183. package/clients/cli/commands/theme-palette-generate.doc.mjs +3 -3
  184. package/clients/cli/commands/theme-palette.doc.mjs +1 -1
  185. package/clients/cli/commands/theme-targets.behavior.test.mjs +4 -3
  186. package/clients/cli/commands/theme-targets.doc.mjs +1 -1
  187. package/clients/cli/commands/theme-template.doc.mjs +1 -1
  188. package/clients/cli/commands/theme.doc.mjs +1 -1
  189. package/clients/cli/commands/upgrade.doc.mjs +3 -2
  190. package/clients/cli/commands/upgrade.file-protection.test.mjs +228 -0
  191. package/clients/cli/commands/upgrade.mjs +29 -7
  192. package/clients/cli/formatters/index.mjs +2 -0
  193. package/clients/cli/formatters/index.test.mjs +6 -0
  194. package/clients/cli/lib/hook-format.mjs +14 -5
  195. package/foundation/config/project-themes.test.mjs +11 -19
  196. package/foundation/config/project.d.mts +8 -0
  197. package/foundation/config/project.mjs +50 -21
  198. package/foundation/config/project.test.mjs +3 -16
  199. package/foundation/discovery/authoring-self-docs.d.mts +6 -0
  200. package/foundation/discovery/authoring-self-docs.mjs +17 -7
  201. package/foundation/discovery/authoring-self-docs.test.mjs +3 -2
  202. package/foundation/discovery/authoring-surface.d.mts +74 -0
  203. package/foundation/discovery/authoring-surface.mjs +525 -0
  204. package/foundation/discovery/authoring-surface.test.mjs +392 -0
  205. package/foundation/discovery/cli-self-docs.d.mts +113 -0
  206. package/foundation/discovery/cli-self-docs.mjs +514 -0
  207. package/foundation/discovery/cli-self-docs.test.mjs +437 -0
  208. package/foundation/discovery/component-loader.d.mts +35 -38
  209. package/foundation/discovery/component-loader.mjs +53 -222
  210. package/foundation/discovery/docs-discovery.d.mts +3 -2
  211. package/foundation/discovery/docs-discovery.mjs +14 -17
  212. package/foundation/discovery/docs-discovery.test.mjs +15 -15
  213. package/foundation/discovery/docs-section-key.d.mts +19 -8
  214. package/foundation/discovery/docs-section-key.mjs +119 -32
  215. package/foundation/discovery/docs-section-key.test.mjs +41 -19
  216. package/foundation/discovery/template-adapter.d.mts +7 -0
  217. package/foundation/discovery/template-adapter.mjs +27 -40
  218. package/foundation/discovery/template-adapter.test.mjs +15 -0
  219. package/foundation/discovery/theme-discovery.d.mts +67 -7
  220. package/foundation/discovery/theme-discovery.mjs +916 -186
  221. package/foundation/discovery/theme-discovery.test.mjs +613 -219
  222. package/foundation/doc-compiler/bundle.d.mts +47 -0
  223. package/foundation/doc-compiler/bundle.mjs +218 -0
  224. package/foundation/doc-compiler/bundle.test.mjs +255 -0
  225. package/foundation/doc-compiler/compile.d.mts +200 -0
  226. package/foundation/doc-compiler/compile.mjs +259 -9
  227. package/foundation/doc-compiler/diagnostics.d.mts +126 -0
  228. package/foundation/doc-compiler/diagnostics.mjs +277 -0
  229. package/foundation/doc-compiler/doc-compiler.test.mjs +28 -1
  230. package/foundation/doc-compiler/doc-loads.test.mjs +1642 -0
  231. package/foundation/doc-compiler/import.d.mts +24 -0
  232. package/foundation/doc-compiler/import.mjs +59 -0
  233. package/foundation/doc-compiler/inputs.d.mts +102 -0
  234. package/foundation/doc-compiler/inputs.mjs +286 -0
  235. package/foundation/doc-compiler/inputs.test.mjs +299 -0
  236. package/foundation/doc-compiler/ir.d.mts +13 -0
  237. package/foundation/doc-compiler/ir.mjs +189 -12
  238. package/foundation/doc-compiler/lower-doc.test.mjs +492 -0
  239. package/foundation/doc-compiler/overlays.d.mts +37 -0
  240. package/foundation/doc-compiler/overlays.mjs +206 -0
  241. package/foundation/doc-compiler/parse-readable.d.mts +9 -0
  242. package/foundation/doc-compiler/parse-readable.mjs +29 -0
  243. package/foundation/doc-compiler/read.d.mts +126 -0
  244. package/foundation/doc-compiler/read.mjs +320 -0
  245. package/foundation/doc-compiler/read.test.mjs +313 -0
  246. package/foundation/doc-compiler/source.d.mts +33 -0
  247. package/foundation/doc-compiler/source.mjs +128 -0
  248. package/foundation/fs/file-protection.d.mts +33 -0
  249. package/foundation/fs/file-protection.mjs +825 -0
  250. package/foundation/fs/file-protection.test.mjs +250 -0
  251. package/foundation/integrations/autolink.d.mts +58 -1
  252. package/foundation/integrations/autolink.mjs +143 -57
  253. package/foundation/integrations/contribution-fixes.d.mts +145 -0
  254. package/foundation/integrations/contribution-fixes.mjs +1284 -0
  255. package/foundation/integrations/contribution-inventory.d.mts +1 -1
  256. package/foundation/integrations/contribution-inventory.mjs +17 -20
  257. package/foundation/integrations/contribution-inventory.test.mjs +67 -27
  258. package/foundation/integrations/integrations.d.mts +3 -0
  259. package/foundation/integrations/integrations.mjs +11 -97
  260. package/foundation/integrations/provider-ledger.test.mjs +275 -0
  261. package/foundation/integrations/provider-resolution.d.mts +152 -0
  262. package/foundation/integrations/provider-resolution.mjs +576 -0
  263. package/foundation/integrations/provider-resolution.test.mjs +369 -0
  264. package/foundation/integrations/theme-descriptor.d.mts +8 -0
  265. package/foundation/integrations/theme-descriptor.mjs +44 -0
  266. package/foundation/integrations/validate-contributions.mjs +104 -10
  267. package/foundation/response/error-codes.d.mts +3 -1
  268. package/foundation/response/error-codes.d.ts +2 -0
  269. package/foundation/response/error-codes.doc.mjs +12 -2
  270. package/foundation/response/error-codes.mjs +7 -1
  271. package/foundation/response/error-codes.test.mjs +55 -11
  272. package/foundation/response/response-types.doc.mjs +1 -1
  273. package/foundation/response/response.doc.mjs +1 -1
  274. package/foundation/text/string-utils.mjs +22 -10
  275. package/package.json +10 -9
  276. package/assets/templates/themes/manifest.json +0 -95
@@ -1,245 +1,76 @@
1
1
  // Copyright (c) Meta Platforms, Inc. and affiliates.
2
2
 
3
3
  /**
4
- * @file Component doc loader — load and merge translations
5
- */
6
-
7
- import {pathToFileURL} from 'node:url';
8
- import {importUserModule} from '../fs/module-loader.mjs';
9
- import {parseDoc} from '../../authoring/doctypes/parse.mjs';
10
-
11
- /**
12
- * Load a component doc through the shared load/validation boundary.
13
- *
14
- * This is the typed counterpart to {@link loadDocs}: it loads `.doc.ts` via
15
- * jiti (and `.doc.mjs`/`.doc.js` via native import) and validates via
16
- * `parseDoc`, which accepts BOTH formats, so this loader reads whichever the
17
- * file uses:
18
- * - NEW: a stamped default export (`export default {type: 'component', ...}`
19
- * / `'function'` / `'generic'`) — the same single-export convention the
20
- * other authoring parsers use for config/integration/template. These carry
21
- * a stamped `type` and validate against the matching per-kind parser.
22
- * - OLD: the legacy loose `export const docs = {...}` (no `type`), validated
23
- * against the permissive legacy union.
24
- * The default export wins when both are present. Throws a readable
25
- * `formatZodError`-style message on failure. Translations (`docsZh`/
26
- * `docsDense`) are merged exactly as {@link loadDocs} does so callers see
27
- * identical output.
4
+ * @file Component and hook doc loader.
28
5
  *
29
- * @param {string} docPath absolute path to a `.doc.{ts,mjs,js}` file
30
- * @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
31
- * @returns {Promise<object>} the validated (and optionally translated) doc
6
+ * @input A component or hook `.doc.{ts,mjs,js}` path and the reading language
7
+ * (`lang`, or the legacy `zh`/`dense` flags).
8
+ * @output The module's own doc, with its translation laid over it for `lang`.
9
+ * @position The loaders every component and hook reader calls. Both read
10
+ * through the doc compiler (foundation/doc-compiler/read.mjs), which lowers
11
+ * the doc on every read. The two differ only in how strict they are:
12
+ * {@link loadComponentDoc} reports a doc that fails its kind's parser, and
13
+ * {@link loadDocs}, which has never checked docs, still reads one.
32
14
  */
33
- export async function loadComponentDoc(
34
- docPath,
35
- {zh = false, dense = false, lang} = {},
36
- ) {
37
- const mod = await importUserModule(docPath);
38
- /** @type {any} */
39
- const authored = mod?.default ?? mod?.docs;
40
-
41
- parseDoc(authored, docPath);
42
- const docs = authored;
43
15
 
44
- const locale = lang || (dense ? 'dense' : zh ? 'zh' : null);
45
- if (!locale) return docs;
16
+ import {readDocView} from '../doc-compiler/read.mjs';
46
17
 
47
- const translationKey =
48
- locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
49
- if (!translationKey || !mod[translationKey]) return docs;
50
-
51
- /** @type {any} */
52
- const translation = mod[translationKey];
53
- if (translation.props || translation.components?.some((/** @type {any} */ c) => c.props)) {
54
- return overlayComponentDoc(docs, translation);
55
- }
56
- return mergeTranslation(docs, translation);
57
- }
18
+ export {mergeTranslation} from '../doc-compiler/overlays.mjs';
58
19
 
59
20
  /**
60
- * @param {any} docs
61
- * @param {any} translation
62
- * @returns {any}
21
+ * @typedef {object} LoadDocOptions
22
+ * @property {boolean} [zh] legacy flag for `lang: 'zh'`
23
+ * @property {boolean} [dense] legacy flag for `lang: 'dense'`
24
+ * @property {string | null} [lang] wins over the legacy flags
25
+ * @property {'components' | 'hooks'} [root] which root reads the doc
26
+ * (default: components)
63
27
  */
64
- export function mergeTranslation(docs, translation) {
65
- if (!translation) return docs;
66
-
67
- /** @type {any} */
68
- const merged = {...docs};
69
-
70
- // Merge prose into usage
71
- if (merged.usage) {
72
- merged.usage = {...merged.usage};
73
- if (translation.usage?.description) merged.usage.description = translation.usage.description;
74
- else if (translation.description) merged.usage.description = translation.description;
75
- if (translation.usage?.bestPractices) merged.usage.bestPractices = translation.usage.bestPractices;
76
- if (translation.usage?.accessibility) merged.usage.accessibility = translation.usage.accessibility;
77
- }
78
-
79
- // Legacy top-level fields (for docsZh that are full ComponentDoc clones)
80
- if (translation.description && !merged.usage) merged.description = translation.description;
81
-
82
- // Merge prop descriptions for single-component docs
83
- if (translation.propDescriptions && merged.props) {
84
- merged.props = merged.props.map((/** @type {any} */ prop) => {
85
- const desc = translation.propDescriptions[prop.name];
86
- return desc != null ? {...prop, description: desc} : prop;
87
- });
88
- }
89
-
90
- // Merge hook param descriptions (HookTranslationDoc). Params are an array of
91
- // {name, type, description, required}; override description by name where the
92
- // translation has an entry. Names may include dots (e.g. 'options.isActive');
93
- // the lookup is keyed by the exact param name.
94
- if (translation.paramDescriptions && merged.params) {
95
- merged.params = merged.params.map((/** @type {any} */ param) => {
96
- const desc = translation.paramDescriptions[param.name];
97
- return desc != null ? {...param, description: desc} : param;
98
- });
99
- }
100
-
101
- // Merge hook return descriptions (HookTranslationDoc). Returns are an array
102
- // of {name, type, description}; override description by name where present.
103
- if (translation.returnDescriptions && merged.returns) {
104
- merged.returns = merged.returns.map((/** @type {any} */ ret) => {
105
- const desc = translation.returnDescriptions[ret.name];
106
- return desc != null ? {...ret, description: desc} : ret;
107
- });
108
- }
109
-
110
- // Merge sub-component translations
111
- if (translation.components && merged.components) {
112
- merged.components = merged.components.map((/** @type {any} */ comp, /** @type {any} */ i) => {
113
- const trans = translation.components.find((/** @type {any} */ t) => t.name === comp.name)
114
- || translation.components[i];
115
- if (!trans) return comp;
116
-
117
- const mergedComp = {...comp};
118
- if (trans.description) mergedComp.description = trans.description;
119
- if (trans.propDescriptions && comp.props) {
120
- mergedComp.props = comp.props.map((/** @type {any} */ prop) => {
121
- const desc = trans.propDescriptions[prop.name];
122
- return desc != null ? {...prop, description: desc} : prop;
123
- });
124
- }
125
- return mergedComp;
126
- });
127
- }
128
-
129
- return merged;
130
- }
131
28
 
132
29
  /**
133
- * Load the typed docs object from a .doc.mjs file.
134
- * Supports --lang flag: 'zh' for Chinese, 'dense' for compressed format.
135
- * Also supports legacy --zh and --dense flags.
136
- * Translations are merged onto the base docs, keeping structure intact.
137
- * @param {string} readmePath
138
- * @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
139
- * @returns {Promise<any>}
30
+ * The overlay a read applies: `lang`, else the legacy flags.
31
+ * @param {LoadDocOptions} opts
32
+ * @returns {string | null}
140
33
  */
141
- export async function loadDocs(readmePath, {zh = false, dense = false, lang} = {}) {
142
- const mod = await import(pathToFileURL(readmePath).href);
143
- // Support both the new stamped default export (`export default {type: 'component', …}`)
144
- // and the legacy named export (`export const docs = {…}`). Default wins when both
145
- // are present, matching loadComponentDoc's precedence.
146
- const docs = mod?.default ?? mod.docs;
147
-
148
- // Resolve which translation to use (--lang takes priority over legacy flags)
149
- const locale = lang || (dense ? 'dense' : zh ? 'zh' : null);
150
- if (!locale) return docs;
151
-
152
- const translationKey = locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
153
- if (!translationKey || !mod[translationKey]) return docs;
154
-
155
- const translation = mod[translationKey];
156
-
157
- // A full ComponentDoc-shaped translation (legacy docsZh shape) used to be
158
- // returned wholesale. That made it a REPLACEMENT, not an overlay: any prop
159
- // the translation had not caught up with simply ceased to exist —
160
- // `component Button --zh` silently omitted `isInterruptible` and
161
- // `isIconOnly`. A reader of the translated docs cannot discover a prop that
162
- // is not there. Overlay it instead, so an untranslated prop falls back to
163
- // its English entry. (Same principle as the reference-doc overlays, #2182.)
164
- if (translation.props || translation.components?.some((/** @type {any} */ c) => c.props)) {
165
- return overlayComponentDoc(docs, translation);
166
- }
167
-
168
- // Otherwise it's a ComponentTranslationDoc — merge it onto docs
169
- return mergeTranslation(docs, translation);
34
+ function localeOf({zh = false, dense = false, lang} = {}) {
35
+ return lang || (dense ? 'dense' : zh ? 'zh' : null);
170
36
  }
171
37
 
172
38
  /**
173
- * Overlay a full-ComponentDoc-shaped translation onto the English doc.
39
+ * Load a component or hook doc and check it against its kind's parser.
174
40
  *
175
- * Base order and completeness win; the translation supplies text for the
176
- * entries it covers. Props are matched by name, never by position, so a
177
- * translation that is missing entries (or lists them in another order) can no
178
- * longer drop or misattribute one.
41
+ * Reads `.doc.ts` through jiti and `.doc.mjs`/`.doc.js` natively. Both formats
42
+ * load: a stamped default export (`export default {type: 'component', ...}`)
43
+ * checked against its kind, and the legacy `export const docs = {...}` checked
44
+ * against the permissive legacy union. The default export wins when both are
45
+ * present. Throws the parser's readable message when the doc fails.
179
46
  *
180
- * @param {any} docs Base (English) component doc.
181
- * @param {any} translation Translated doc, possibly covering only some props.
182
- * @returns {any} Merged doc with every base prop present.
47
+ * @param {string} docPath absolute path to a `.doc.{ts,mjs,js}` file
48
+ * @param {LoadDocOptions} [opts]
49
+ * @returns {Promise<any>} the checked (and optionally translated) doc
183
50
  */
184
- function overlayComponentDoc(docs, translation) {
185
- /** Merge one prop list: keep base entries and order, translate what's covered.
186
- * @param {any[] | undefined} baseProps
187
- * @param {any[] | undefined} tProps
188
- */
189
- const overlayProps = (baseProps, tProps) => {
190
- if (!baseProps) return baseProps;
191
- const byName = new Map((tProps ?? []).map((/** @type {any} */ p) => [p.name, p]));
192
- return baseProps.map((/** @type {any} */ prop) => {
193
- const t = byName.get(prop.name);
194
- // Take the translated text, but never let it drop the prop's contract
195
- // (type/default/required stay authoritative from the English doc).
196
- return t ? {...prop, ...t, name: prop.name, type: prop.type} : prop;
197
- });
198
- };
199
-
200
- /** Preserve canonical structured guidance added after legacy full-doc translations,
201
- * without changing established translated prose behavior.
202
- * @param {any} baseUsage
203
- * @param {any} translatedUsage
204
- */
205
- const mergeUsage = (baseUsage, translatedUsage) => {
206
- if (!translatedUsage) return baseUsage;
207
- return {
208
- ...translatedUsage,
209
- ...(translatedUsage.accessibility === undefined &&
210
- baseUsage?.accessibility !== undefined
211
- ? {accessibility: baseUsage.accessibility}
212
- : null),
213
- ...(translatedUsage.accessibilityThemeCoverage === undefined &&
214
- baseUsage?.accessibilityThemeCoverage !== undefined
215
- ? {accessibilityThemeCoverage: baseUsage.accessibilityThemeCoverage}
216
- : null),
217
- ...(translatedUsage.anatomy === undefined && baseUsage?.anatomy !== undefined
218
- ? {anatomy: baseUsage.anatomy}
219
- : null),
220
- };
221
- };
222
-
223
- const merged = {...docs, ...translation, usage: mergeUsage(docs.usage, translation.usage)};
224
-
225
- merged.props = overlayProps(docs.props, translation.props);
226
-
227
- if (docs.components) {
228
- const tByName = new Map(
229
- (translation.components ?? []).map((/** @type {any} */ c) => [c.name, c]),
230
- );
231
- merged.components = docs.components.map((/** @type {any} */ base) => {
232
- const t = tByName.get(base.name);
233
- if (!t) return base;
234
- return {...base, ...t, usage: mergeUsage(base.usage, t.usage), props: overlayProps(base.props, t.props)};
235
- });
236
- }
237
-
238
- return merged;
51
+ export async function loadComponentDoc(docPath, opts = {}) {
52
+ return readDocView(docPath, {
53
+ root: opts.root ?? 'components',
54
+ lang: localeOf(opts),
55
+ label: docPath,
56
+ strict: true,
57
+ });
239
58
  }
240
59
 
241
60
  /**
242
- * Find the doc file for a component, checking both top-level
243
- * and nested directories. Prefers {Name}.doc.mjs, then README.md
244
- * (for backward compatibility).
61
+ * Load a component or hook doc without checking it. Supports `lang` ('zh' for
62
+ * Chinese, 'dense' for compressed) and the legacy `zh`/`dense` flags; the
63
+ * translation is laid over the doc, keeping its structure. A file that exports
64
+ * no doc reads as `undefined`.
65
+ * @param {string} readmePath
66
+ * @param {LoadDocOptions} [opts]
67
+ * @returns {Promise<any>}
245
68
  */
69
+ export async function loadDocs(readmePath, opts = {}) {
70
+ return readDocView(readmePath, {
71
+ root: opts.root ?? 'components',
72
+ lang: localeOf(opts),
73
+ label: readmePath,
74
+ loader: 'native',
75
+ });
76
+ }
@@ -74,8 +74,9 @@ export function discoverIntegrationDocs(integration: {
74
74
  /**
75
75
  * Merge an extension onto a base topic: a section with a stable `id` replaces
76
76
  * the base section with the same `id`; legacy sections without IDs fall back to
77
- * title matching. A section with no match is appended, and title/description
78
- * are taken from the extension when it states them.
77
+ * title matching. A section with no match is appended. The title and
78
+ * description stay the base topic's: an extension adds to a topic, it never
79
+ * renames it. A topic that `replaces` another is the one that renames.
79
80
  *
80
81
  * Keyed by section TITLE rather than by position, the way the localization
81
82
  * overlays are — position keying grafts an overlay onto whichever section
@@ -32,12 +32,12 @@
32
32
  import * as fs from 'node:fs';
33
33
  import * as path from 'node:path';
34
34
  import {CLI_ROOT} from '../fs/paths.mjs';
35
- import {importUserModule} from '../fs/module-loader.mjs';
35
+ import {importDocModule} from '../doc-compiler/import.mjs';
36
36
  import {CLI_PROVIDER_ID} from '../identity/providers.mjs';
37
- import {parseDoc} from '../../authoring/doctypes/parse.mjs';
37
+ import {parseReadableDoc} from '../doc-compiler/parse-readable.mjs';
38
38
  import {
39
39
  sectionKey,
40
- sectionKeyProblems,
40
+ sectionKeyErrors,
41
41
  sourceTitle,
42
42
  withSourceTitle,
43
43
  } from './docs-section-key.mjs';
@@ -117,7 +117,7 @@ export function discoverBuiltinTopics() {
117
117
  * @returns {Promise<unknown>} the authored doc value
118
118
  */
119
119
  export async function loadTopicModule(file) {
120
- const mod = await importUserModule(file);
120
+ const mod = await importDocModule(file);
121
121
  const doc = mod?.docs ?? mod?.default;
122
122
  if (doc == null) {
123
123
  throw new Error(
@@ -312,9 +312,10 @@ export function problemsInTopic(doc) {
312
312
  );
313
313
  },
314
314
  );
315
- // Readers address a section by its key, so two sections sharing one would
316
- // make one of them unreachable.
317
- problems.push(...sectionKeyProblems(doc.sections));
315
+ // Explicit authored IDs are a new opt-in contract and remain strict. Topics
316
+ // that relied on 0.6.x title-only sections keep loading; the compiler assigns
317
+ // deterministic fallback/suffixed keys for the additive index API.
318
+ problems.push(...sectionKeyErrors(doc.sections));
318
319
  return problems;
319
320
  }
320
321
 
@@ -363,7 +364,7 @@ export async function discoverIntegrationDocs(integration) {
363
364
  for (const file of files) {
364
365
  let doc;
365
366
  try {
366
- doc = parseDoc(await loadTopicModule(file), path.basename(file));
367
+ doc = parseReadableDoc(await loadTopicModule(file), path.basename(file));
367
368
  } catch (err) {
368
369
  errors.push(
369
370
  new Error(
@@ -423,8 +424,9 @@ export async function discoverIntegrationDocs(integration) {
423
424
  /**
424
425
  * Merge an extension onto a base topic: a section with a stable `id` replaces
425
426
  * the base section with the same `id`; legacy sections without IDs fall back to
426
- * title matching. A section with no match is appended, and title/description
427
- * are taken from the extension when it states them.
427
+ * title matching. A section with no match is appended. The title and
428
+ * description stay the base topic's: an extension adds to a topic, it never
429
+ * renames it. A topic that `replaces` another is the one that renames.
428
430
  *
429
431
  * Keyed by section TITLE rather than by position, the way the localization
430
432
  * overlays are — position keying grafts an overlay onto whichever section
@@ -451,12 +453,7 @@ export function mergeTopic(base, overlay) {
451
453
  : section;
452
454
  }
453
455
  }
454
- return {
455
- ...base,
456
- title: overlay.title || base.title,
457
- description: overlay.description || base.description,
458
- sections,
459
- };
456
+ return {...base, sections};
460
457
  }
461
458
 
462
459
  /**
@@ -491,7 +488,7 @@ function findMergeTarget(sections, section) {
491
488
  const sameTitle = sections.findIndex(
492
489
  candidate => sourceTitle(candidate) === title,
493
490
  );
494
- return sameTitle === -1 ? byKey() : sameTitle;
491
+ return sameTitle;
495
492
  }
496
493
 
497
494
  /**
@@ -180,7 +180,7 @@ describe('discoverIntegrationDocs', () => {
180
180
  }),
181
181
  );
182
182
  expect(records).toEqual([]);
183
- expect(errors[0].message).toContain('requires the compiled graph renderer');
183
+ expect(errors[0].message).toContain('Invalid discriminator value');
184
184
  });
185
185
 
186
186
  it('names a namespace doc instead of listing topic fields it lacks', async () => {
@@ -505,11 +505,14 @@ describe('mergeTopic', () => {
505
505
  ]);
506
506
  });
507
507
 
508
- it('takes the title and description only when the overlay states them', () => {
509
- expect(mergeTopic(base, {sections: []}).title).toBe('Theme');
510
- expect(mergeTopic(base, {title: 'Theming', sections: []}).title).toBe(
511
- 'Theming',
512
- );
508
+ it('keeps the base title and description: an extension never renames a topic', () => {
509
+ const merged = mergeTopic(base, {
510
+ title: 'Acme theme notes',
511
+ description: 'Our additions.',
512
+ sections: [],
513
+ });
514
+ expect(merged.title).toBe('Theme');
515
+ expect(merged.description).toBe('Theming.');
513
516
  });
514
517
  });
515
518
 
@@ -526,12 +529,10 @@ describe('problemsInTopic section keys', () => {
526
529
  })),
527
530
  });
528
531
 
529
- it('rejects two sections that derive the same key', () => {
532
+ it('keeps legacy title-only key conflicts readable', () => {
530
533
  expect(
531
534
  problemsInTopic(doc([{title: 'Quick Start'}, {title: 'Quick-start'}])),
532
- ).toEqual([
533
- expect.stringContaining('"quick-start" is already used by sections[0]'),
534
- ]);
535
+ ).toEqual([]);
535
536
  });
536
537
 
537
538
  it('rejects an unsafe id', () => {
@@ -540,10 +541,8 @@ describe('problemsInTopic section keys', () => {
540
541
  ).toEqual([expect.stringContaining('is not a stable key')]);
541
542
  });
542
543
 
543
- it('rejects a title no key derives from, unless it has an id', () => {
544
- expect(problemsInTopic(doc([{title: '亮/暗模式'}]))).toEqual([
545
- expect.stringContaining('Give the section an id'),
546
- ]);
544
+ it('keeps a legacy title that has no derived key readable', () => {
545
+ expect(problemsInTopic(doc([{title: '亮/暗模式'}]))).toEqual([]);
547
546
  expect(
548
547
  problemsInTopic(doc([{id: 'light-dark', title: '亮/暗模式'}])),
549
548
  ).toEqual([]);
@@ -577,7 +576,7 @@ describe('mergeTopic by section key', () => {
577
576
  ]);
578
577
  });
579
578
 
580
- it('replaces the section a title variant derives the same key as', () => {
579
+ it('keeps a legacy title variant as a separate section', () => {
581
580
  const merged = mergeTopic(base, {
582
581
  sections: [
583
582
  {title: 'Light-Dark Mode', content: [{type: 'prose', text: 'acme'}]},
@@ -585,6 +584,7 @@ describe('mergeTopic by section key', () => {
585
584
  });
586
585
  expect(titles(merged)).toEqual([
587
586
  [null, 'Quick Start', 'base'],
587
+ [null, 'Light/Dark Mode', 'base'],
588
588
  [null, 'Light-Dark Mode', 'acme'],
589
589
  ]);
590
590
  });
@@ -31,9 +31,17 @@ export function sectionTitleKey(title: unknown): string;
31
31
  */
32
32
  export function sectionKey(section: any): string;
33
33
  /**
34
- * Problems with the keys of a topic's sections: an authored id that is not a
35
- * stable key, a title no key derives from, and two sections sharing a key.
36
- * Keys are never suffixed to make them unique, because readers link to them.
34
+ * Fatal key problems: only an explicitly authored `id` can make a previously
35
+ * readable topic invalid. Derived-key collisions and titles with no Latin
36
+ * letters or digits are handled by {@link withSectionKeys} for 0.6.x
37
+ * compatibility.
38
+ * @param {any[]} sections
39
+ * @returns {string[]}
40
+ */
41
+ export function sectionKeyErrors(sections: any[]): string[];
42
+ /**
43
+ * Compatibility notices for section keys. These inputs loaded in 0.6.x, so
44
+ * readers keep accepting them and assign deterministic fallback keys.
37
45
  * @param {any[]} sections
38
46
  * @returns {string[]}
39
47
  */
@@ -49,13 +57,16 @@ export function withSectionKeys<T extends {
49
57
  sections: any[];
50
58
  }>(doc: T): T;
51
59
  /**
52
- * Find the section a reader asked for: by key, then by exact title (or the
53
- * key the query derives), then by a title that contains the query. More than
54
- * one match is refused rather than guessed.
60
+ * Find the section a reader asked for. The 0.6.x first-match title-substring
61
+ * lookup remains first in the authored-title view. In a localized view, an
62
+ * exact stable key resolves before translated title substrings because those
63
+ * translations cannot participate in language-stable key allocation. Generated
64
+ * keys avoid authored-title conflicts, and authored IDs that would shadow an
65
+ * authored legacy query are rejected.
55
66
  * @param {any[]} sections
56
67
  * @param {string} query
57
- * @returns {{section: any | null, candidates: any[]}} `candidates` lists the
58
- * matches when the query is ambiguous, and is empty when nothing matches
68
+ * @returns {{section: any | null, candidates: any[]}} `candidates` lists every
69
+ * legacy title match when the query is ambiguous
59
70
  */
60
71
  export function findDocSection(sections: any[], query: string): {
61
72
  section: any | null;