@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ee13359

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 (571) hide show
  1. package/README.md +114 -76
  2. package/api/blog/blog.doc.mjs +1 -0
  3. package/api/build/build.doc.mjs +4 -3
  4. package/api/build/build.test.mjs +14 -3
  5. package/api/build/build.type.d.mts +36 -2
  6. package/api/build/build.type.mjs +25 -4
  7. package/api/build/help/help.d.mts +8 -5
  8. package/api/build/help/help.mjs +56 -6
  9. package/api/component/_adapter.d.mts +6 -12
  10. package/api/component/_adapter.mjs +20 -10
  11. package/api/component/component.doc.mjs +13 -3
  12. package/api/component/component.mjs +91 -14
  13. package/api/component/component.test.mjs +38 -0
  14. package/api/component/component.type.d.mts +22 -11
  15. package/api/component/component.type.mjs +32 -24
  16. package/api/component/detail/blocks/blocks.d.mts +2 -1
  17. package/api/component/detail/blocks/blocks.mjs +4 -3
  18. package/api/component/list/list.d.mts +0 -5
  19. package/api/component/list/list.mjs +40 -11
  20. package/api/discover/discover.doc.mjs +2 -1
  21. package/api/discover/discover.type.d.mts +4 -4
  22. package/api/discover/discover.type.mjs +10 -10
  23. package/api/docs/_adapter.d.mts +230 -41
  24. package/api/docs/_adapter.mjs +734 -108
  25. package/api/docs/compiled-topics.test.mjs +78 -0
  26. package/api/docs/detail/detail.mjs +22 -63
  27. package/api/docs/detail/section/section.d.mts +1 -1
  28. package/api/docs/detail/section/section.mjs +54 -19
  29. package/api/docs/detail/section/section.test.mjs +50 -0
  30. package/api/docs/docs.d.mts +10 -3
  31. package/api/docs/docs.doc.mjs +54 -16
  32. package/api/docs/docs.mjs +53 -10
  33. package/api/docs/docs.test.mjs +164 -4
  34. package/api/docs/docs.type.d.mts +205 -5
  35. package/api/docs/docs.type.mjs +137 -11
  36. package/api/docs/index/index.d.mts +18 -0
  37. package/api/docs/index/index.mjs +40 -0
  38. package/api/docs/index/index.test.mjs +62 -0
  39. package/api/docs/integration-tree.test.mjs +547 -0
  40. package/api/docs/integrationDocs.test.mjs +114 -8
  41. package/api/docs/list/list.mjs +28 -12
  42. package/api/docs/node/node.d.mts +43 -0
  43. package/api/docs/node/node.mjs +192 -0
  44. package/api/doctor/doctor.d.mts +99 -1
  45. package/api/doctor/doctor.doc.mjs +1 -0
  46. package/api/doctor/doctor.mjs +544 -1
  47. package/api/doctor/doctor.test.mjs +610 -1
  48. package/api/gap-report/gap-report.doc.mjs +8 -4
  49. package/api/hook/_adapter.mjs +19 -5
  50. package/api/hook/hook.doc.mjs +1 -0
  51. package/api/hook/hook.type.d.mts +3 -3
  52. package/api/hook/hook.type.mjs +11 -11
  53. package/api/hook/list/list.d.mts +2 -2
  54. package/api/hook/list/list.mjs +69 -17
  55. package/api/index.d.mts +1 -1
  56. package/api/index.mjs +1 -0
  57. package/api/init/init.doc.mjs +6 -1
  58. package/api/init/init.test.mjs +41 -1
  59. package/api/init/remove/remove.mjs +1 -1
  60. package/api/init/run/run.mjs +20 -10
  61. package/api/integration/add-contribution.component-names.test.mjs +120 -0
  62. package/api/integration/add-contribution.d.mts +2 -1
  63. package/api/integration/add-contribution.mjs +130 -15
  64. package/api/integration/add-contribution.test.mjs +258 -7
  65. package/api/integration/add-theme.mjs +34 -64
  66. package/api/integration/add-theme.test.mjs +105 -21
  67. package/api/integration/authoring-checks.mjs +108 -31
  68. package/api/integration/authoring-checks.test.mjs +171 -6
  69. package/api/integration/authoring-checks.type.d.mts +3 -1
  70. package/api/integration/authoring-checks.type.mjs +3 -1
  71. package/api/integration/integration-authoring.type.d.mts +3 -1
  72. package/api/integration/integration-authoring.type.mjs +2 -0
  73. package/api/integration/integration-block-exports.test.mjs +10 -6
  74. package/api/integration/integrationAdd.doc.mjs +14 -4
  75. package/api/integration/integrationAddAgentDoc.doc.mjs +1 -0
  76. package/api/integration/integrationAddCodemod.doc.mjs +1 -0
  77. package/api/integration/integrationAddComponent.doc.mjs +2 -1
  78. package/api/integration/integrationAddDoc.doc.mjs +8 -1
  79. package/api/integration/integrationAddTemplate.doc.mjs +1 -0
  80. package/api/integration/integrationAddTheme.doc.mjs +6 -5
  81. package/api/integration/integrationComponentConflicts.doc.mjs +1 -0
  82. package/api/integration/integrationDocConflicts.doc.mjs +2 -1
  83. package/api/integration/integrationPackCheck.doc.mjs +2 -1
  84. package/api/integration/integrationTemplateConflicts.doc.mjs +7 -5
  85. package/api/integration/pack-check.mjs +83 -7
  86. package/api/integration/pack-check.test.mjs +387 -47
  87. package/api/integration/pack-check.type.d.mts +26 -2
  88. package/api/integration/pack-check.type.mjs +14 -1
  89. package/api/integration/summarizeIssues.doc.mjs +1 -0
  90. package/api/integration/validate-integration-fixes.test.mjs +1389 -0
  91. package/api/integration/validate-integration.mjs +52 -102
  92. package/api/integration/validate-integration.test.mjs +179 -26
  93. package/api/integration/validate-unread-theme-folders.test.mjs +110 -0
  94. package/api/integration/validateIntegration.doc.mjs +3 -2
  95. package/api/json/assertResponse.doc.mjs +1 -0
  96. package/api/json/envelope-types.test.mjs +76 -0
  97. package/api/json/index.ts +2 -0
  98. package/api/json/isError.doc.mjs +1 -0
  99. package/api/json/parseResponse.doc.mjs +3 -2
  100. package/api/layout/_adapter.mjs +20 -5
  101. package/api/layout/expand/expand.mjs +7 -5
  102. package/api/layout/expand/expand.path-safety.test.mjs +53 -0
  103. package/api/layout/grammar/grammar.mjs +2 -1
  104. package/api/layout/layoutCheck.doc.mjs +1 -0
  105. package/api/layout/layoutExpand.doc.mjs +2 -1
  106. package/api/layout/layoutGrammar.doc.mjs +1 -0
  107. package/api/search/search-return-type.test.mjs +54 -0
  108. package/api/search/search.d.mts +29 -11
  109. package/api/search/search.doc.mjs +8 -2
  110. package/api/search/search.mjs +337 -41
  111. package/api/search/search.test.mjs +124 -1
  112. package/api/search/search.type.d.mts +15 -3
  113. package/api/search/search.type.mjs +5 -2
  114. package/api/swizzle/copy/copy.mjs +28 -11
  115. package/api/swizzle/swizzle.doc.mjs +2 -1
  116. package/api/swizzle/swizzle.type.d.mts +2 -2
  117. package/api/swizzle/swizzle.type.mjs +2 -2
  118. package/api/template/copy/copy.mjs +17 -23
  119. package/api/template/copy/copy.test.mjs +17 -0
  120. package/api/template/list/list.mjs +1 -0
  121. package/api/template/template-integration.test.mjs +1022 -3
  122. package/api/template/template-suffix.test.mjs +41 -21
  123. package/api/template/template.d.mts +1 -1
  124. package/api/template/template.doc.mjs +30 -8
  125. package/api/template/template.mjs +45 -8
  126. package/api/template/template.type.d.mts +12 -14
  127. package/api/template/template.type.mjs +15 -14
  128. package/api/theme/_adapter.d.mts +2 -3
  129. package/api/theme/_adapter.mjs +4 -5
  130. package/api/theme/add/add.binary.test.mjs +84 -0
  131. package/api/theme/add/add.mjs +20 -3
  132. package/api/theme/add/add.staging.test.mjs +66 -0
  133. package/api/theme/add/add.test.mjs +14 -1
  134. package/api/theme/build/build.mjs +133 -42
  135. package/api/theme/build/build.public-component-vars.test.mjs +1 -1
  136. package/api/theme/build/build.receipt-doc.test.mjs +111 -0
  137. package/api/theme/build/build.test.mjs +127 -0
  138. package/api/theme/build/font-warning.mjs +3 -3
  139. package/api/theme/build/font-warning.test.mjs +5 -2
  140. package/api/theme/generateTonalPalette.doc.mjs +1 -0
  141. package/api/theme/integration-themes.test.mjs +39 -28
  142. package/api/theme/list/list.test.mjs +19 -20
  143. package/api/theme/listThemes.doc.mjs +6 -5
  144. package/api/theme/palette/generate/generate.mjs +8 -3
  145. package/api/theme/palette/generate/generate.test.mjs +96 -0
  146. package/api/theme/palette/generate/generator.d.mts +10 -13
  147. package/api/theme/palette/generate/generator.mjs +15 -4
  148. package/api/theme/palette/generate/generator.test.mjs +10 -0
  149. package/api/theme/template/template.mjs +11 -2
  150. package/api/theme/template/template.test.mjs +20 -0
  151. package/api/theme/theme.type.d.mts +170 -11
  152. package/api/theme/theme.type.mjs +94 -27
  153. package/api/theme/themeAdd.doc.mjs +4 -3
  154. package/api/theme/themeBuild.doc.mjs +8 -4
  155. package/api/theme/themeList.doc.mjs +6 -3
  156. package/api/theme/themeListAvailable.doc.mjs +5 -3
  157. package/api/theme/themePaletteGenerate.doc.mjs +1 -0
  158. package/api/theme/themeTargets.doc.mjs +1 -0
  159. package/api/theme/themeTemplate.doc.mjs +6 -2
  160. package/api/upgrade/_adapter.d.mts +32 -5
  161. package/api/upgrade/_adapter.mjs +139 -22
  162. package/api/upgrade/list/list.mjs +2 -1
  163. package/api/upgrade/list/list.test.mjs +73 -0
  164. package/api/upgrade/project-context.test.mjs +272 -0
  165. package/api/upgrade/provider-agreement.test.mjs +152 -0
  166. package/api/upgrade/run/run.mjs +356 -59
  167. package/api/upgrade/status/status.mjs +2 -2
  168. package/api/upgrade/upgrade.doc.mjs +12 -5
  169. package/api/upgrade/upgrade.type.d.mts +43 -5
  170. package/api/upgrade/upgrade.type.mjs +27 -11
  171. package/assets/codemods/__tests__/runner.test.mjs +330 -8
  172. package/assets/codemods/integration-discovery.mjs +48 -4
  173. package/assets/codemods/integration-discovery.test.mjs +73 -0
  174. package/assets/codemods/integration-runner.mjs +56 -4
  175. package/assets/codemods/integration-runner.protection.test.mjs +153 -0
  176. package/assets/codemods/run-codemod.mjs +177 -34
  177. package/assets/codemods/runner.mjs +350 -102
  178. package/assets/codemods/term-log.mjs +32 -8
  179. package/assets/codemods/term-log.test.mjs +19 -1
  180. package/assets/codemods/transform-prop.mjs +109 -0
  181. package/assets/codemods/transform-prop.test.mjs +95 -0
  182. package/assets/codemods/transforms/next/__tests__/migrate-native-picker-to-presentation.test.mjs +63 -0
  183. package/assets/codemods/transforms/next/__tests__/migrate-theme-catalog-to-descriptors.test.mjs +220 -0
  184. package/assets/codemods/transforms/next/index.mjs +19 -1
  185. package/assets/codemods/transforms/next/migrate-native-picker-to-presentation.mjs +148 -0
  186. package/assets/codemods/transforms/next/migrate-theme-catalog-to-descriptors.mjs +141 -0
  187. package/assets/codemods/transforms/v0.0.14/__tests__/rename-status-variants.test.mjs +86 -165
  188. package/assets/codemods/transforms/v0.0.14/rename-status-variants.mjs +72 -210
  189. package/assets/codemods/transforms/v0.1.8/__tests__/rename-avatar-size-scale.test.mjs +83 -115
  190. package/assets/codemods/transforms/v0.1.8/rename-avatar-size-scale.mjs +57 -186
  191. package/assets/codemods/transforms/v0.3.0/__tests__/unwrap-authoring-factories.test.mjs +27 -5
  192. package/assets/codemods/transforms/v0.3.0/unwrap-authoring-factories.mjs +20 -5
  193. package/assets/codemods/transforms/v0.6.0/__tests__/next-codemods.test.mjs +47 -0
  194. package/assets/codemods/transforms/v0.6.0/rename-resizable-pixel-bounds.mjs +57 -10
  195. package/assets/docs/README.md +9 -0
  196. package/assets/docs/authoring.doc.mjs +14 -0
  197. package/assets/docs/getting-started.doc.mjs +2 -2
  198. package/assets/docs/principles.doc.mjs +6 -6
  199. package/assets/docs/styling-libraries.doc.mjs +3 -3
  200. package/assets/docs/styling.doc.mjs +4 -4
  201. package/assets/docs/theme.doc.mjs +4 -4
  202. package/assets/docs/tokens.doc.mjs +1 -1
  203. package/assets/docs/tree/api.doc.mjs +30 -0
  204. package/assets/docs/tree/cli.doc.mjs +23 -0
  205. package/assets/docs/tree/commands.doc.mjs +25 -0
  206. package/assets/docs/{cli-integrations.doc.mjs → tree/integrations.doc.mjs} +124 -25
  207. package/assets/docs/tree/integrations.test.mjs +62 -0
  208. package/assets/docs/tree/writing-docs.doc.mjs +286 -0
  209. package/assets/docs/working-with-ai.doc.mjs +1 -1
  210. package/assets/templates/blocks/components/DateInput/DateInputDateRange.tsx +1 -1
  211. package/assets/templates/blocks/components/Item/ItemDocumentTabs.doc.mjs +14 -0
  212. package/assets/templates/blocks/components/Item/ItemDocumentTabs.tsx +100 -0
  213. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.doc.mjs +14 -0
  214. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.tsx +61 -0
  215. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.doc.mjs +14 -0
  216. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.tsx +126 -0
  217. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.doc.mjs +15 -0
  218. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.tsx +86 -0
  219. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.doc.mjs +14 -0
  220. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.tsx +99 -0
  221. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.doc.mjs +14 -0
  222. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.tsx +122 -0
  223. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.doc.mjs +14 -0
  224. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.tsx +95 -0
  225. package/assets/templates/blocks/components/TimeInput/TimeInputConstrained.tsx +1 -0
  226. package/assets/templates/pages/table-tree/page.tsx +1704 -0
  227. package/assets/templates/pages/table-tree/template.doc.mjs +12 -0
  228. package/assets/templates/themes/butter/butterTheme.doc.mjs +11 -0
  229. package/assets/templates/themes/chocolate/chocolateTheme.doc.mjs +11 -0
  230. package/assets/templates/themes/gothic/gothicTheme.doc.mjs +11 -0
  231. package/assets/templates/themes/matcha/matchaTheme.doc.mjs +11 -0
  232. package/assets/templates/themes/neutral/neutralTheme.doc.mjs +11 -0
  233. package/assets/templates/themes/stone/stoneTheme.doc.mjs +11 -0
  234. package/assets/templates/themes/y2k/y2kTheme.doc.mjs +11 -0
  235. package/authoring/_shared/contract.ts +22 -0
  236. package/authoring/codemod/codemod.doc.mjs +7 -2
  237. package/authoring/codemod/parse.d.mts +8 -8
  238. package/authoring/codemod/parse.mjs +8 -6
  239. package/authoring/codemod/type.ts +12 -0
  240. package/authoring/config/config.doc.mjs +2 -2
  241. package/authoring/config/debug-composition.test.mjs +92 -0
  242. package/authoring/config/parse.d.mts +13 -13
  243. package/authoring/config/parse.mjs +8 -8
  244. package/authoring/config/type.ts +18 -6
  245. package/authoring/debug/debug.doc.d.mts +11 -0
  246. package/authoring/debug/debug.doc.mjs +182 -0
  247. package/authoring/debug/parse.d.mts +8 -8
  248. package/authoring/debug/parse.mjs +3 -3
  249. package/authoring/doctypes/_schema.d.mts +718 -23
  250. package/authoring/doctypes/_schema.mjs +519 -39
  251. package/authoring/doctypes/base/graph-fields.doc.d.mts +9 -0
  252. package/authoring/doctypes/base/graph-fields.doc.mjs +64 -0
  253. package/authoring/doctypes/base/type.ts +41 -0
  254. package/authoring/doctypes/command/command.doc.mjs +4 -3
  255. package/authoring/doctypes/command/parse.d.mts +2 -2
  256. package/authoring/doctypes/command/parse.mjs +1 -1
  257. package/authoring/doctypes/command/type.ts +5 -4
  258. package/authoring/doctypes/component/component.doc.mjs +6 -3
  259. package/authoring/doctypes/component/parse.d.mts +2 -2
  260. package/authoring/doctypes/component/parse.mjs +1 -1
  261. package/authoring/doctypes/component/type.ts +6 -5
  262. package/authoring/doctypes/doctypes-new.test.mjs +48 -6
  263. package/authoring/doctypes/enum/enum.doc.mjs +1 -1
  264. package/authoring/doctypes/enum/parse.d.mts +2 -2
  265. package/authoring/doctypes/enum/parse.mjs +1 -1
  266. package/authoring/doctypes/enum/type.ts +4 -2
  267. package/authoring/doctypes/function/function.doc.mjs +7 -2
  268. package/authoring/doctypes/function/parse.d.mts +2 -2
  269. package/authoring/doctypes/function/parse.mjs +1 -1
  270. package/authoring/doctypes/function/type.ts +9 -4
  271. package/authoring/doctypes/hook/hook.doc.mjs +4 -0
  272. package/authoring/doctypes/hook/parse.d.mts +2 -2
  273. package/authoring/doctypes/hook/parse.mjs +1 -1
  274. package/authoring/doctypes/hook/type.ts +5 -4
  275. package/authoring/doctypes/legacy.d.mts +8 -6
  276. package/authoring/doctypes/legacy.mjs +5 -4
  277. package/authoring/doctypes/load-contract.test.mjs +208 -0
  278. package/authoring/doctypes/namespace/namespace.doc.d.mts +9 -0
  279. package/authoring/doctypes/namespace/namespace.doc.mjs +128 -0
  280. package/authoring/doctypes/namespace/parse.d.mts +12 -0
  281. package/authoring/doctypes/namespace/parse.mjs +25 -0
  282. package/authoring/doctypes/namespace/parse.test.mjs +163 -0
  283. package/authoring/doctypes/namespace/type.ts +74 -0
  284. package/authoring/doctypes/parse.d.mts +22 -18
  285. package/authoring/doctypes/parse.mjs +22 -11
  286. package/authoring/doctypes/parse.test.mjs +77 -3
  287. package/authoring/doctypes/reference/parse.d.mts +2 -2
  288. package/authoring/doctypes/reference/parse.mjs +8 -5
  289. package/authoring/doctypes/reference/reference.doc.mjs +20 -5
  290. package/authoring/doctypes/reference/type.ts +53 -5
  291. package/authoring/doctypes/schema/parse.d.mts +2 -2
  292. package/authoring/doctypes/schema/parse.mjs +1 -1
  293. package/authoring/doctypes/schema/schema.doc.mjs +1 -1
  294. package/authoring/doctypes/schema/type.ts +4 -4
  295. package/authoring/doctypes/template/parse.d.mts +94 -1
  296. package/authoring/doctypes/template/parse.mjs +40 -2
  297. package/authoring/doctypes/template/parse.test.mjs +26 -2
  298. package/authoring/doctypes/template/template.doc.mjs +13 -3
  299. package/authoring/doctypes/template/type.ts +13 -2
  300. package/authoring/doctypes/theme/parse.d.mts +35 -0
  301. package/authoring/doctypes/theme/parse.mjs +76 -0
  302. package/authoring/doctypes/theme/theme.doc.d.mts +9 -0
  303. package/authoring/doctypes/theme/theme.doc.mjs +79 -0
  304. package/authoring/doctypes/theme/type.ts +42 -0
  305. package/authoring/doctypes/types.ts +12 -10
  306. package/authoring/gap-report/gap-report.doc.d.mts +12 -0
  307. package/authoring/gap-report/gap-report.doc.mjs +183 -0
  308. package/authoring/gap-report/parse.d.mts +10 -10
  309. package/authoring/gap-report/parse.mjs +6 -6
  310. package/authoring/gap-report/type.ts +1 -1
  311. package/authoring/identity/identity.doc.d.mts +9 -0
  312. package/authoring/identity/identity.doc.mjs +61 -0
  313. package/authoring/identity/type.ts +132 -0
  314. package/authoring/index.d.mts +2 -0
  315. package/authoring/index.d.ts +52 -17
  316. package/authoring/index.mjs +3 -1
  317. package/authoring/integration/integration.doc.mjs +15 -8
  318. package/authoring/integration/parse.d.mts +2 -2
  319. package/authoring/integration/parse.mjs +1 -1
  320. package/authoring/integration/parse.test.mjs +10 -1
  321. package/authoring/integration/schema.d.mts +6 -4
  322. package/authoring/integration/schema.mjs +9 -3
  323. package/authoring/integration/type.ts +19 -8
  324. package/authoring/shadcn/receipt.d.mts +6 -6
  325. package/clients/cli/__tests__/cliManifest.test.ts +27 -29
  326. package/clients/cli/command-load-failure.test.mjs +83 -0
  327. package/clients/cli/commands/blog.doc.mjs +1 -1
  328. package/clients/cli/commands/blog.mjs +23 -8
  329. package/clients/cli/commands/blog.test.mjs +42 -1
  330. package/clients/cli/commands/build-theme.adaptations.test.mjs +100 -1
  331. package/clients/cli/commands/build-theme.ascii-output.test.mjs +161 -0
  332. package/clients/cli/commands/build-theme.flag-docs.test.mjs +110 -0
  333. package/clients/cli/commands/build-theme.mjs +16 -50
  334. package/clients/cli/commands/build-theme.path-safety.test.mjs +86 -1
  335. package/clients/cli/commands/build-theme.variants.test.mjs +76 -0
  336. package/clients/cli/commands/build.doc.mjs +5 -2
  337. package/clients/cli/commands/build.exit-codes-doc.test.mjs +50 -0
  338. package/clients/cli/commands/build.mjs +37 -49
  339. package/clients/cli/commands/build.playbook.test.mjs +75 -0
  340. package/clients/cli/commands/build.text-fields.test.mjs +40 -0
  341. package/clients/cli/commands/component/index.mjs +3 -8
  342. package/clients/cli/commands/component-ownership.test.mjs +3 -3
  343. package/clients/cli/commands/component-package.test.mjs +46 -0
  344. package/clients/cli/commands/component-resolution.test.mjs +21 -0
  345. package/clients/cli/commands/component.doc.mjs +1 -1
  346. package/clients/cli/commands/component.test.mjs +19 -0
  347. package/clients/cli/commands/detail-levels.test.mjs +2 -2
  348. package/clients/cli/commands/discover.broken-integration.test.mjs +52 -5
  349. package/clients/cli/commands/discover.components-flag.test.mjs +97 -0
  350. package/clients/cli/commands/discover.doc.mjs +5 -3
  351. package/clients/cli/commands/discover.mjs +4 -4
  352. package/clients/cli/commands/discover.text-projection.test.mjs +103 -0
  353. package/clients/cli/commands/docs.doc.mjs +28 -6
  354. package/clients/cli/commands/docs.mjs +238 -24
  355. package/clients/cli/commands/docs.test.mjs +193 -1
  356. package/clients/cli/commands/doctor-integration-components.doc.mjs +1 -1
  357. package/clients/cli/commands/doctor-integration-docs.doc.mjs +3 -3
  358. package/clients/cli/commands/doctor-integration-templates.doc.mjs +15 -8
  359. package/clients/cli/commands/doctor-integration-validate.doc.mjs +1 -1
  360. package/clients/cli/commands/doctor-integration.doc.mjs +1 -1
  361. package/clients/cli/commands/doctor-integration.package-json.test.mjs +53 -0
  362. package/clients/cli/commands/doctor-integration.test.mjs +83 -8
  363. package/clients/cli/commands/doctor.doc.mjs +1 -1
  364. package/clients/cli/commands/doctor.mjs +30 -25
  365. package/clients/cli/commands/doctor.test.mjs +42 -0
  366. package/clients/cli/commands/gap-report.doc.mjs +17 -6
  367. package/clients/cli/commands/gap-report.test.mjs +72 -0
  368. package/clients/cli/commands/hook/index.mjs +7 -17
  369. package/clients/cli/commands/hook.doc.mjs +1 -1
  370. package/clients/cli/commands/hook.text-projection.test.mjs +45 -0
  371. package/clients/cli/commands/init.doc.mjs +20 -9
  372. package/clients/cli/commands/init.flag-help.test.mjs +153 -0
  373. package/clients/cli/commands/integration-add.controls.test.mjs +132 -0
  374. package/clients/cli/commands/integration-add.doc.mjs +32 -6
  375. package/clients/cli/commands/integration-authoring.test.mjs +13 -9
  376. package/clients/cli/commands/integration-pack.doc.mjs +1 -1
  377. package/clients/cli/commands/integration-real-world.test.mjs +3 -9
  378. package/clients/cli/commands/integration.doc.mjs +1 -1
  379. package/clients/cli/commands/integration.mjs +1 -0
  380. package/clients/cli/commands/interactive-guard.test.mjs +101 -24
  381. package/clients/cli/commands/json-contract.test.mjs +33 -0
  382. package/clients/cli/commands/layout-check.doc.mjs +15 -4
  383. package/clients/cli/commands/layout-expand.doc.mjs +22 -5
  384. package/clients/cli/commands/layout-grammar.doc.mjs +1 -1
  385. package/clients/cli/commands/layout.doc.mjs +3 -3
  386. package/clients/cli/commands/layout.mjs +21 -9
  387. package/clients/cli/commands/layout.path-help.test.mjs +33 -0
  388. package/clients/cli/commands/layout.stdin-cap.test.mjs +47 -0
  389. package/clients/cli/commands/layout.text-fields.test.mjs +39 -0
  390. package/clients/cli/commands/manifest.doc.mjs +1 -1
  391. package/clients/cli/commands/no-prompt-wording.test.mjs +94 -0
  392. package/clients/cli/commands/search.doc.mjs +7 -4
  393. package/clients/cli/commands/search.mjs +28 -9
  394. package/clients/cli/commands/search.test.mjs +75 -0
  395. package/clients/cli/commands/setup-nudge.test.mjs +6 -0
  396. package/clients/cli/commands/swizzle.doc.mjs +3 -2
  397. package/clients/cli/commands/swizzle.path-safety.test.mjs +42 -0
  398. package/clients/cli/commands/template.doc.mjs +52 -13
  399. package/clients/cli/commands/template.flag-help.test.mjs +117 -0
  400. package/clients/cli/commands/template.mjs +4 -91
  401. package/clients/cli/commands/template.path-help.test.mjs +40 -0
  402. package/clients/cli/commands/text-json-parity.test.mjs +719 -0
  403. package/clients/cli/commands/theme-add.doc.mjs +4 -3
  404. package/clients/cli/commands/theme-build.doc.mjs +8 -7
  405. package/clients/cli/commands/theme-list.doc.mjs +2 -2
  406. package/clients/cli/commands/theme-palette-generate.doc.mjs +9 -5
  407. package/clients/cli/commands/theme-palette-generate.test.mjs +19 -0
  408. package/clients/cli/commands/theme-palette.doc.mjs +1 -1
  409. package/clients/cli/commands/theme-targets.behavior.test.mjs +4 -3
  410. package/clients/cli/commands/theme-targets.doc.mjs +1 -1
  411. package/clients/cli/commands/theme-template.behavior.test.mjs +12 -0
  412. package/clients/cli/commands/theme-template.doc.mjs +2 -2
  413. package/clients/cli/commands/theme.doc.mjs +1 -1
  414. package/clients/cli/commands/upgrade.ascii-output.test.mjs +87 -0
  415. package/clients/cli/commands/upgrade.doc.mjs +22 -10
  416. package/clients/cli/commands/upgrade.file-protection.test.mjs +228 -0
  417. package/clients/cli/commands/upgrade.flag-help.test.mjs +188 -0
  418. package/clients/cli/commands/upgrade.hook-output.test.mjs +88 -0
  419. package/clients/cli/commands/upgrade.mjs +29 -7
  420. package/clients/cli/formatters/index.mjs +164 -1
  421. package/clients/cli/formatters/index.test.mjs +97 -0
  422. package/clients/cli/index.mjs +21 -30
  423. package/clients/cli/latest-version-env.test.mjs +50 -0
  424. package/clients/cli/lib/cli-error.test.mjs +7 -0
  425. package/clients/cli/lib/component-format.mjs +9 -9
  426. package/clients/cli/lib/component-format.test.mjs +1 -1
  427. package/clients/cli/lib/define-command.mjs +32 -6
  428. package/clients/cli/lib/doc-text-ascii.test.mjs +82 -0
  429. package/clients/cli/lib/exit-codes.test.mjs +97 -0
  430. package/clients/cli/lib/hook-format.mjs +19 -10
  431. package/clients/cli/lib/json-shim.mjs +38 -2
  432. package/clients/cli/lib/json-shim.test.mjs +83 -0
  433. package/clients/cli/lib/manifest.d.ts +2 -0
  434. package/clients/cli/lib/manifest.mjs +36 -2
  435. package/clients/cli/lib/manifest.test.mjs +17 -0
  436. package/foundation/agent-docs/agent-docs.d.mts +4 -0
  437. package/foundation/agent-docs/agent-docs.mjs +70 -3
  438. package/foundation/agent-docs/agent-docs.path-safety.test.mjs +266 -4
  439. package/foundation/agent-docs/agent-docs.test.mjs +10 -1
  440. package/foundation/config/integration-debug.test.mjs +28 -3
  441. package/foundation/config/project-themes.test.mjs +11 -19
  442. package/foundation/config/project.d.mts +20 -11
  443. package/foundation/config/project.mjs +263 -91
  444. package/foundation/config/project.test.mjs +270 -21
  445. package/foundation/discovery/authoring-self-docs.d.mts +75 -0
  446. package/foundation/discovery/authoring-self-docs.mjs +224 -0
  447. package/foundation/discovery/authoring-self-docs.test.mjs +165 -0
  448. package/foundation/discovery/authoring-surface.d.mts +74 -0
  449. package/foundation/discovery/authoring-surface.mjs +525 -0
  450. package/foundation/discovery/authoring-surface.test.mjs +392 -0
  451. package/foundation/discovery/cli-self-docs.d.mts +119 -0
  452. package/foundation/discovery/cli-self-docs.mjs +490 -0
  453. package/foundation/discovery/cli-self-docs.test.mjs +375 -0
  454. package/foundation/discovery/component-discovery.d.mts +39 -1
  455. package/foundation/discovery/component-discovery.mjs +50 -1
  456. package/foundation/discovery/component-loader.d.mts +35 -38
  457. package/foundation/discovery/component-loader.mjs +53 -222
  458. package/foundation/discovery/docs-discovery.d.mts +116 -11
  459. package/foundation/discovery/docs-discovery.mjs +389 -108
  460. package/foundation/discovery/docs-discovery.test.mjs +325 -20
  461. package/foundation/discovery/docs-output-budget.d.mts +28 -0
  462. package/foundation/discovery/docs-output-budget.mjs +50 -0
  463. package/foundation/discovery/docs-section-key.d.mts +116 -0
  464. package/foundation/discovery/docs-section-key.mjs +322 -0
  465. package/foundation/discovery/docs-section-key.test.mjs +246 -0
  466. package/foundation/discovery/template-adapter.d.mts +113 -11
  467. package/foundation/discovery/template-adapter.fixture-refs.test.mjs +248 -0
  468. package/foundation/discovery/template-adapter.integration-isolation.test.mjs +94 -0
  469. package/foundation/discovery/template-adapter.mjs +774 -83
  470. package/foundation/discovery/template-adapter.test.mjs +57 -0
  471. package/foundation/discovery/theme-discovery.d.mts +67 -7
  472. package/foundation/discovery/theme-discovery.mjs +916 -186
  473. package/foundation/discovery/theme-discovery.test.mjs +613 -219
  474. package/foundation/discovery/theming-targets.test.mjs +4 -0
  475. package/foundation/doc-compiler/bundle.d.mts +47 -0
  476. package/foundation/doc-compiler/bundle.mjs +278 -0
  477. package/foundation/doc-compiler/bundle.test.mjs +266 -0
  478. package/foundation/doc-compiler/compile.d.mts +343 -0
  479. package/foundation/doc-compiler/compile.mjs +558 -0
  480. package/foundation/doc-compiler/diagnostics.d.mts +126 -0
  481. package/foundation/doc-compiler/diagnostics.mjs +305 -0
  482. package/foundation/doc-compiler/doc-compiler.test.mjs +714 -0
  483. package/foundation/doc-compiler/doc-loads.test.mjs +1642 -0
  484. package/foundation/doc-compiler/import.d.mts +24 -0
  485. package/foundation/doc-compiler/import.mjs +59 -0
  486. package/foundation/doc-compiler/inputs.d.mts +102 -0
  487. package/foundation/doc-compiler/inputs.mjs +291 -0
  488. package/foundation/doc-compiler/inputs.test.mjs +299 -0
  489. package/foundation/doc-compiler/ir.d.mts +22 -0
  490. package/foundation/doc-compiler/ir.mjs +471 -0
  491. package/foundation/doc-compiler/lenses.d.mts +34 -0
  492. package/foundation/doc-compiler/lenses.mjs +128 -0
  493. package/foundation/doc-compiler/links.d.mts +135 -0
  494. package/foundation/doc-compiler/links.mjs +253 -0
  495. package/foundation/doc-compiler/links.test.mjs +139 -0
  496. package/foundation/doc-compiler/lower-doc.test.mjs +495 -0
  497. package/foundation/doc-compiler/overlays.d.mts +37 -0
  498. package/foundation/doc-compiler/overlays.mjs +206 -0
  499. package/foundation/doc-compiler/parse-readable.d.mts +9 -0
  500. package/foundation/doc-compiler/parse-readable.mjs +29 -0
  501. package/foundation/doc-compiler/read.d.mts +127 -0
  502. package/foundation/doc-compiler/read.mjs +325 -0
  503. package/foundation/doc-compiler/read.test.mjs +313 -0
  504. package/foundation/doc-compiler/source.d.mts +33 -0
  505. package/foundation/doc-compiler/source.mjs +128 -0
  506. package/foundation/doc-compiler/tree.d.mts +288 -0
  507. package/foundation/doc-compiler/tree.mjs +876 -0
  508. package/foundation/doc-compiler/tree.test.mjs +598 -0
  509. package/foundation/fs/file-protection.d.mts +33 -0
  510. package/foundation/fs/file-protection.mjs +825 -0
  511. package/foundation/fs/file-protection.test.mjs +250 -0
  512. package/foundation/fs/module-loader.d.mts +1 -0
  513. package/foundation/fs/module-loader.mjs +50 -1
  514. package/foundation/fs/module-loader.stdout.test.mjs +332 -0
  515. package/foundation/fs/path-safety.d.mts +3 -2
  516. package/foundation/fs/path-safety.mjs +49 -19
  517. package/foundation/fs/path-safety.test.mjs +50 -0
  518. package/foundation/fs/publish-file-hardlink-unavailable.test.mjs +129 -94
  519. package/foundation/identity/provider-identity.d.mts +90 -0
  520. package/foundation/identity/provider-identity.mjs +320 -0
  521. package/foundation/identity/provider-identity.test.mjs +254 -0
  522. package/foundation/identity/providers.d.mts +7 -0
  523. package/foundation/identity/providers.mjs +16 -0
  524. package/foundation/integrations/autolink.d.mts +58 -1
  525. package/foundation/integrations/autolink.mjs +143 -45
  526. package/foundation/integrations/autolink.test.mjs +1 -1
  527. package/foundation/integrations/cli-requirement.d.mts +45 -0
  528. package/foundation/integrations/cli-requirement.mjs +154 -0
  529. package/foundation/integrations/cli-requirement.test.mjs +109 -0
  530. package/foundation/integrations/contribution-fixes.d.mts +145 -0
  531. package/foundation/integrations/contribution-fixes.mjs +1284 -0
  532. package/foundation/integrations/contribution-inventory.d.mts +3 -2
  533. package/foundation/integrations/contribution-inventory.mjs +27 -24
  534. package/foundation/integrations/contribution-inventory.test.mjs +86 -27
  535. package/foundation/integrations/integration-warnings.d.mts +9 -2
  536. package/foundation/integrations/integration-warnings.mjs +52 -21
  537. package/foundation/integrations/integration-warnings.test.mjs +74 -1
  538. package/foundation/integrations/integrations.d.mts +49 -2
  539. package/foundation/integrations/integrations.mjs +81 -8
  540. package/foundation/integrations/integrations.test.mjs +384 -1
  541. package/foundation/integrations/provider-conflicts.test.mjs +125 -0
  542. package/foundation/integrations/provider-ledger.test.mjs +275 -0
  543. package/foundation/integrations/provider-resolution.d.mts +152 -0
  544. package/foundation/integrations/provider-resolution.mjs +576 -0
  545. package/foundation/integrations/provider-resolution.test.mjs +369 -0
  546. package/foundation/integrations/theme-descriptor.d.mts +8 -0
  547. package/foundation/integrations/theme-descriptor.mjs +44 -0
  548. package/foundation/integrations/validate-contributions.d.mts +2 -0
  549. package/foundation/integrations/validate-contributions.mjs +131 -29
  550. package/foundation/response/base.d.ts +8 -4
  551. package/foundation/response/error-codes.d.mts +3 -1
  552. package/foundation/response/error-codes.d.ts +2 -0
  553. package/foundation/response/error-codes.doc.mjs +13 -4
  554. package/foundation/response/error-codes.mjs +8 -2
  555. package/foundation/response/error-codes.test.mjs +137 -10
  556. package/foundation/response/json-contract.test.mjs +57 -17
  557. package/foundation/response/json.d.mts +4 -2
  558. package/foundation/response/json.mjs +8 -10
  559. package/foundation/response/response-types.doc.mjs +26 -16
  560. package/foundation/response/response-types.doc.test.mjs +158 -0
  561. package/foundation/response/response.doc.mjs +1 -1
  562. package/foundation/text/string-utils.mjs +22 -10
  563. package/foundation/xle/expand.d.mts +2 -0
  564. package/foundation/xle/expand.mjs +4 -3
  565. package/foundation/xle/expand.test.mjs +54 -0
  566. package/foundation/xle/xle.test.mjs +13 -0
  567. package/package.json +10 -11
  568. package/assets/templates/themes/manifest.json +0 -95
  569. package/clients/cli/lib/update-check.mjs +0 -83
  570. package/clients/cli/lib/update-check.test.mjs +0 -137
  571. package/clients/cli/update-hint-commands.test.mjs +0 -54
@@ -6,6 +6,8 @@ import * as path from 'node:path';
6
6
  import * as os from 'node:os';
7
7
  import {Command} from 'commander';
8
8
  import {registerDocs} from './docs.mjs';
9
+ import {runCli} from '../../../test-utils/run-cli.mjs';
10
+ import {displayWidth} from '../formatters/index.mjs';
9
11
 
10
12
  let tmpDir;
11
13
 
@@ -73,7 +75,7 @@ describe('hyphenated doc filenames', () => {
73
75
 
74
76
  it('returns docs.detail via API for hyphenated topic', async () => {
75
77
  const {docs: docsApi} = await import('../../../api/docs/docs.mjs');
76
- const result = await docsApi('getting-started');
78
+ const result = await docsApi('getting-started', undefined, {full: true});
77
79
  expect(result.type).toBe('docs.detail');
78
80
  expect(result.data).toBeDefined();
79
81
  expect(result.data.description).toBeDefined();
@@ -100,3 +102,193 @@ describe('migration docs', () => {
100
102
  expect(output).toContain('Map shadcn and Radix Primitives');
101
103
  });
102
104
  });
105
+
106
+ describe('progressive reads', () => {
107
+ const SLOW = 60_000;
108
+ /** @param {string} out */
109
+ const widest = out => Math.max(...out.split('\n').map(line => line.length));
110
+
111
+ it('lists every topic on one line each', async () => {
112
+ const {status, stdout} = await runCli(['docs']);
113
+ expect(status).toBe(0);
114
+ expect(stdout).toMatch(/^principles +\S/m);
115
+ expect(widest(stdout)).toBeLessThanOrEqual(120);
116
+ expect(stdout).toContain('Usage: pnpm exec astryx docs <topic>');
117
+ }, SLOW);
118
+
119
+ it("prints a topic's section index with the keys to read by", async () => {
120
+ const {status, stdout} = await runCli(['docs', 'theme', '--index']);
121
+ expect(status).toBe(0);
122
+ expect(stdout).toMatch(/^quick-start +Quick Start/m);
123
+ expect(stdout).toContain('docs theme <section>');
124
+ expect(stdout).toMatch(/Read everything: +\S.* docs theme --full$/m);
125
+ expect(widest(stdout)).toBeLessThanOrEqual(120);
126
+ }, SLOW);
127
+
128
+ it('prints one section by its key', async () => {
129
+ const {status, stdout} = await runCli(['docs', 'theme', 'quick-start']);
130
+ expect(status).toBe(0);
131
+ expect(stdout).toMatch(/^## Quick Start/m);
132
+ }, SLOW);
133
+
134
+ it("lists a topic's sections by default; --full prints the whole topic", async () => {
135
+ const index = await runCli(['docs', 'theme', '--index']);
136
+ expect((await runCli(['docs', 'theme'])).stdout).toBe(index.stdout);
137
+ const full = await runCli(['docs', 'theme', '--full']);
138
+ expect(full.status).toBe(0);
139
+ expect(full.stdout).toMatch(/^## Quick Start/m);
140
+ expect(full.stdout.length).toBeGreaterThan(index.stdout.length * 3);
141
+ expect((await runCli(['--detail', 'full', 'docs', 'theme', '--full'])).stdout).toBe(
142
+ full.stdout,
143
+ );
144
+ }, SLOW);
145
+
146
+ it('returns the matching envelopes as JSON', async () => {
147
+ const envelope = async args => JSON.parse((await runCli([...args, '--json'])).stdout);
148
+ // JSON keeps docs(): a bare read is the whole topic.
149
+ expect((await envelope(['docs', 'theme'])).type).toBe('docs.detail');
150
+ expect((await envelope(['docs', 'theme', '--full'])).type).toBe('docs.detail');
151
+ expect((await envelope(['docs', 'theme', '--index'])).type).toBe(
152
+ 'docs.index',
153
+ );
154
+ expect((await envelope(['docs', 'theme', 'quick-start'])).type).toBe(
155
+ 'docs.detail.section',
156
+ );
157
+ }, SLOW);
158
+ });
159
+
160
+ describe('the docs tree, one level at a time', () => {
161
+ const SLOW = 60_000;
162
+ /** @param {string} out */
163
+ const widest = out => Math.max(...out.split('\n').map(line => line.length));
164
+
165
+ it('lists the docs tree first, under its own heading, then the topics', async () => {
166
+ const {status, stdout} = await runCli(['docs']);
167
+ expect(status).toBe(0);
168
+ expect(stdout).toMatch(/^Docs tree$/m);
169
+ expect(stdout).toMatch(/^Topics$/m);
170
+ expect(stdout).toMatch(/^cli +Commands, programmatic APIs/m);
171
+ expect(stdout.indexOf('\ncli ')).toBeLessThan(stdout.indexOf('\nprinciples '));
172
+ expect(stdout).not.toMatch(/^cli-integrations /m);
173
+ }, SLOW);
174
+
175
+ it("shows a child's own name when its route name does not spell it", async () => {
176
+ const {status, stdout} = await runCli(['docs', 'cli/api/functions']);
177
+ expect(status).toBe(0);
178
+ expect(stdout).toMatch(/^assert-response +assertResponse\(\): \S/m);
179
+ expect(stdout).toMatch(/^search +search\(\): Unified ranked search/m);
180
+ }, SLOW);
181
+
182
+ it('prints a namespace: each slot, its children, and how to go down and up', async () => {
183
+ const {status, stdout} = await runCli(['docs', 'cli/api']);
184
+ expect(status).toBe(0);
185
+ expect(stdout).toMatch(/^API$/m);
186
+ expect(stdout).toMatch(/^Reference$/m);
187
+ expect(stdout).toMatch(/^functions +Functions: Every function/m);
188
+ expect(stdout).toMatch(/^schemas +/m);
189
+ expect(stdout).toMatch(/^enums +/m);
190
+ // One level only: no function is listed on the api page.
191
+ expect(stdout).not.toMatch(/^search +/m);
192
+ expect(stdout).toMatch(/Open one: .*docs cli\/api\/<name>$/m);
193
+ expect(stdout).toMatch(/Up: .*docs cli$/m);
194
+ expect(widest(stdout)).toBeLessThanOrEqual(120);
195
+ }, SLOW);
196
+
197
+ it('prints a typed doc and the way back up', async () => {
198
+ const {status, stdout} = await runCli(['docs', 'cli/api/functions/search']);
199
+ expect(status).toBe(0);
200
+ expect(stdout).toMatch(/^## search\(\)/m);
201
+ expect(stdout).toContain('Read it with `astryx docs cli/commands/search`.');
202
+ expect(stdout).toMatch(/Up: .*docs cli\/api\/functions$/m);
203
+ }, SLOW);
204
+
205
+ it('reads the dense variant whole, asked with --dense or with --lang dense', async () => {
206
+ for (const args of [['--dense', 'docs', 'theme'], ['--lang', 'dense', 'docs', 'theme']]) {
207
+ const {status, stdout} = await runCli(args);
208
+ expect(status).toBe(0);
209
+ expect(stdout).not.toContain('Read one section:');
210
+ }
211
+ }, SLOW);
212
+
213
+ it('refuses --index with --full', async () => {
214
+ const both = await runCli(['docs', 'theme', '--index', '--full', '--json']);
215
+ expect(both.status).toBe(1);
216
+ expect(JSON.parse(both.stdout).code).toBe('ERR_INVALID_ARGUMENT');
217
+ }, SLOW);
218
+
219
+ it('reads the integration guide by its route, and not by its old name', async () => {
220
+ const guide = await runCli(['docs', 'cli/integrations', '--index']);
221
+ expect(guide.status).toBe(0);
222
+ expect(guide.stdout).toMatch(/Read one section: .*docs cli\/integrations <section>/);
223
+ // A bare read is one level too: the sections, and how to read it all.
224
+ const bare = await runCli(['docs', 'cli/integrations']);
225
+ expect(bare.status).toBe(0);
226
+ expect(bare.stdout).toBe(guide.stdout);
227
+ expect(bare.stdout).toMatch(/Read everything: +.*docs cli\/integrations --full$/m);
228
+ const one = await runCli(['docs', 'cli/integrations', 'codemods']);
229
+ expect(one.status).toBe(0);
230
+ expect(one.stdout).toMatch(/^## Codemods$/m);
231
+ expect(one.stdout).toMatch(/^Up: .*docs cli\/integrations --index$/m);
232
+ expect(one.stdout).toMatch(/^Previous: .*docs cli\/integrations agent-docs$/m);
233
+ expect(one.stdout).toMatch(/^Next: .*docs cli\/integrations recording-runs$/m);
234
+ const full = await runCli(['docs', 'cli/integrations', '--full']);
235
+ expect(full.status).toBe(0);
236
+ expect(full.stdout).toMatch(/^## Overview$/m);
237
+ expect(full.stdout.length).toBeGreaterThan(bare.stdout.length * 4);
238
+ const old = await runCli(['docs', 'cli-integrations']);
239
+ expect(old.status).toBe(1);
240
+ expect(old.stderr).toContain('Unknown topic "cli-integrations"');
241
+ }, SLOW);
242
+
243
+ it('returns docs.node as JSON, and fails a section of a namespace', async () => {
244
+ const node = JSON.parse((await runCli(['docs', 'cli', '--json'])).stdout);
245
+ expect(node).toMatchObject({
246
+ type: 'docs.node',
247
+ data: {route: 'cli', kind: 'namespace', breadcrumb: []},
248
+ });
249
+ expect(node.data.slots.map(slot => slot.name)).toEqual(['guides', 'reference']);
250
+ const section = await runCli(['docs', 'cli', 'commands', '--json']);
251
+ expect(section.status).toBe(1);
252
+ const error = JSON.parse(section.stdout);
253
+ expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});
254
+ expect(error.suggestions.map(s => s.name)).toEqual([
255
+ 'cli/integrations',
256
+ 'cli/writing-docs',
257
+ 'cli/commands',
258
+ 'cli/api',
259
+ ]);
260
+ }, SLOW);
261
+ });
262
+
263
+ describe('text width in every language', () => {
264
+ const SLOW = 60_000;
265
+ /** Widest line outside code blocks, in terminal columns. */
266
+ const widest = out => {
267
+ let inCode = false;
268
+ let max = 0;
269
+ for (const line of out.split('\n')) {
270
+ if (/^\s*```/.test(line)) {
271
+ inCode = !inCode;
272
+ continue;
273
+ }
274
+ // A single unbreakable token (a long URL) cannot wrap without breaking it.
275
+ const oneToken = !/\s/.test(line.trim());
276
+ if (!inCode && !line.startsWith('#') && !oneToken) {
277
+ max = Math.max(max, displayWidth(line));
278
+ }
279
+ }
280
+ return max;
281
+ };
282
+
283
+ it('keeps the additive section index within 120 columns', async () => {
284
+ const {status, stdout} = await runCli([
285
+ 'docs',
286
+ 'theme',
287
+ '--index',
288
+ '--lang',
289
+ 'zh',
290
+ ]);
291
+ expect(status).toBe(0);
292
+ expect(widest(stdout)).toBeLessThanOrEqual(120);
293
+ }, SLOW);
294
+ });
@@ -7,7 +7,7 @@ export const doc = {
7
7
  type: 'command',
8
8
  name: 'doctor integration components',
9
9
  displayName: 'astryx doctor integration components',
10
- namespace: 'cli',
10
+ namespace: 'cli/commands',
11
11
  summary: 'Warn when integration component names conflict with Core',
12
12
  description:
13
13
  'Compares one local or installed integration with Core component names. A ' +
@@ -7,8 +7,8 @@ export const doc = {
7
7
  type: 'command',
8
8
  name: 'doctor integration docs',
9
9
  displayName: 'astryx doctor integration docs',
10
- namespace: 'cli',
11
- summary: 'Classify integration doc overlaps with Core topics',
10
+ namespace: 'cli/commands',
11
+ summary: 'Check an integration\'s docs: the docs tree they add, every link, and overlaps with Core topics',
12
12
  description:
13
13
  'Reports intentional Core topic replacements and extensions as information. ' +
14
14
  'A same-name topic without `replaces` or `extends` is an accidental conflict ' +
@@ -32,7 +32,7 @@ export const doc = {
32
32
  ],
33
33
  exitCodes: [
34
34
  {code: 0, when: 'all Core overlaps are explicitly declared or no overlap exists'},
35
- {code: 1, when: 'an overlap is accidental or the integration docs are invalid'},
35
+ {code: 1, when: 'an overlap is accidental, a doc is invalid, or a namespace or placement fails. A link that names no doc is a warning, and does not change the exit code'},
36
36
  ],
37
37
  related: ['doctor integration validate', 'docs'],
38
38
  };
@@ -9,13 +9,14 @@ export const doc = {
9
9
  type: 'command',
10
10
  name: 'doctor integration templates',
11
11
  displayName: 'astryx doctor integration templates',
12
- namespace: 'cli',
13
- summary: 'Warn when integration template ids conflict with Core',
12
+ namespace: 'cli/commands',
13
+ summary: 'Validate integration template replacements and Core id overlaps',
14
14
  description:
15
- 'Compares one local or installed integration with the built-in Core page and ' +
16
- 'block template ids. A conflict is allowed and exits successfully, but the ' +
17
- 'report recommends renaming and gives the exact --package command required ' +
18
- 'to select the integration template when the overlap is intentional.',
15
+ 'Validates one local or installed integration against the built-in Core page ' +
16
+ 'and block template ids. Intentional replacements are informational and name ' +
17
+ 'the command for selecting the Core original. Missing targets, ambiguous ' +
18
+ 'replacements, and invalid declarations are errors; undeclared same-id overlaps ' +
19
+ 'remain warnings that require package selection.',
19
20
  fn: 'integrationTemplateConflicts',
20
21
  args: [
21
22
  {
@@ -37,8 +38,14 @@ export const doc = {
37
38
  },
38
39
  ],
39
40
  exitCodes: [
40
- {code: 0, when: 'the check completed; template conflicts are warnings'},
41
- {code: 1, when: 'the integration or one of its templates is invalid'},
41
+ {
42
+ code: 0,
43
+ when: 'replacement declarations are valid; undeclared id conflicts are warnings',
44
+ },
45
+ {
46
+ code: 1,
47
+ when: 'the integration, a template, or a replacement declaration is invalid',
48
+ },
42
49
  ],
43
50
  related: ['doctor integration validate', 'template'],
44
51
  };
@@ -9,7 +9,7 @@ export const doc = {
9
9
  type: 'command',
10
10
  name: 'doctor integration validate',
11
11
  displayName: 'astryx doctor integration validate',
12
- namespace: 'cli',
12
+ namespace: 'cli/commands',
13
13
  summary: 'Validate an integration manifest and its contributions',
14
14
  description:
15
15
  'Validates one integration at a time: the local package rooted at cwd, or an ' +
@@ -9,7 +9,7 @@ export const doc = {
9
9
  type: 'command',
10
10
  name: 'doctor integration',
11
11
  displayName: 'astryx doctor integration',
12
- namespace: 'cli',
12
+ namespace: 'cli/commands',
13
13
  summary: 'Check an integration package while authoring it',
14
14
  description:
15
15
  'The integration-authoring diagnostics group. Validate a manifest and all ' +
@@ -0,0 +1,53 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ import {afterEach, beforeEach, describe, expect, it} from 'vitest';
4
+ import * as fs from 'node:fs';
5
+ import * as path from 'node:path';
6
+ import {runCli} from '../../../test-utils/run-cli.mjs';
7
+ import {validateIntegration} from '../../../api/integration/validate-integration.mjs';
8
+
9
+ const NO_MANIFEST = 'No astryx.integration.* found next to package.json.';
10
+
11
+ let tmpDir;
12
+
13
+ beforeEach(() => {
14
+ tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-pkgjson-'));
15
+ fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name": "@acme/widgets",}\n');
16
+ fs.writeFileSync(
17
+ path.join(tmpDir, 'astryx.integration.mjs'),
18
+ "export default {\n templates: './templates',\n};\n",
19
+ );
20
+ });
21
+
22
+ afterEach(() => {
23
+ fs.rmSync(tmpDir, {recursive: true, force: true});
24
+ });
25
+
26
+ describe('doctor integration with a malformed package.json', () => {
27
+ it('keeps a null name for the no-manifest case only', async () => {
28
+ const result = await validateIntegration(undefined, {cwd: tmpDir});
29
+
30
+ expect(result.data.name).toBe('(local package)');
31
+ expect(result.data.issues.map(issue => issue.code)).toEqual([
32
+ 'invalid_package_json',
33
+ ]);
34
+ });
35
+
36
+ for (const leaf of ['validate', 'templates', 'components', 'docs']) {
37
+ it(`${leaf} prints the package.json error instead of "no manifest"`, async () => {
38
+ const text = await runCli(['doctor', 'integration', leaf], tmpDir);
39
+ const json = await runCli(
40
+ ['doctor', 'integration', leaf, '--json'],
41
+ tmpDir,
42
+ );
43
+
44
+ expect(text.status).toBe(1);
45
+ expect(json.status).toBe(1);
46
+ expect(text.stdout).not.toContain(NO_MANIFEST);
47
+ expect(text.stdout).toContain('invalid_package_json');
48
+ expect(JSON.parse(json.stdout).data.issues).toContainEqual(
49
+ expect.objectContaining({code: 'invalid_package_json'}),
50
+ );
51
+ });
52
+ }
53
+ });
@@ -31,6 +31,8 @@ function writeIntegration({
31
31
  id,
32
32
  name = 'Integration template',
33
33
  missingRoot = false,
34
+ replacements,
35
+ type = 'page',
34
36
  }) {
35
37
  fs.writeFileSync(
36
38
  path.join(tmpDir, 'package.json'),
@@ -44,8 +46,8 @@ function writeIntegration({
44
46
  const stem = path.join(tmpDir, 'templates', id);
45
47
  fs.mkdirSync(path.dirname(stem), {recursive: true});
46
48
  fs.writeFileSync(
47
- `${stem}.template.mjs`,
48
- `export default {type: 'page', name: ${JSON.stringify(name)}, description: 'fixture'};\n`,
49
+ `${stem}.doc.mjs`,
50
+ `export default {type: '${type}', name: ${JSON.stringify(name)}, description: 'fixture'${replacements?.[id] == null ? '' : `, replaces: ${JSON.stringify(replacements[id])}`}};\n`,
49
51
  );
50
52
  fs.writeFileSync(
51
53
  `${stem}.tsx`,
@@ -124,7 +126,12 @@ describe('doctor integration — command', () => {
124
126
  return true;
125
127
  });
126
128
 
127
- await createProgram().parseAsync(['node', 'astryx', 'doctor', 'integration']);
129
+ await createProgram().parseAsync([
130
+ 'node',
131
+ 'astryx',
132
+ 'doctor',
133
+ 'integration',
134
+ ]);
128
135
 
129
136
  const output = writes.join('');
130
137
  expect(output).toContain('validate [package]');
@@ -136,7 +143,9 @@ describe('doctor integration — command', () => {
136
143
 
137
144
  it('explains the optional package argument in every leaf help', () => {
138
145
  const program = createProgram();
139
- const doctor = program.commands.find(command => command.name() === 'doctor');
146
+ const doctor = program.commands.find(
147
+ command => command.name() === 'doctor',
148
+ );
140
149
  const integration = doctor?.commands.find(
141
150
  command => command.name() === 'integration',
142
151
  );
@@ -152,7 +161,10 @@ describe('doctor integration — command', () => {
152
161
  });
153
162
 
154
163
  it('templates explains how to check an installed package when no local manifest exists', async () => {
155
- fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'plain'}));
164
+ fs.writeFileSync(
165
+ path.join(tmpDir, 'package.json'),
166
+ JSON.stringify({name: 'plain'}),
167
+ );
156
168
  process.chdir(tmpDir);
157
169
 
158
170
  await createProgram().parseAsync([
@@ -239,6 +251,71 @@ describe('doctor integration — command', () => {
239
251
  expect(process.exitCode).toBeUndefined();
240
252
  });
241
253
 
254
+ it('templates reports an intentional replacement and the Core-original command', async () => {
255
+ const core = (await discoverCoreTemplates()).find(
256
+ template => template.type === 'page',
257
+ );
258
+ expect(core).toBeDefined();
259
+ writeIntegration({
260
+ id: 'acme-app-shell',
261
+ type: core.type,
262
+ replacements: {'acme-app-shell': core.dirName},
263
+ });
264
+ process.chdir(tmpDir);
265
+
266
+ await createProgram().parseAsync([
267
+ 'node',
268
+ 'astryx',
269
+ '--json',
270
+ 'doctor',
271
+ 'integration',
272
+ 'templates',
273
+ ]);
274
+
275
+ const parsed = JSON.parse(logCalls.join('\n'));
276
+ expect(parsed.data.issues).toEqual([]);
277
+ expect(parsed.data.conflicts).toEqual([
278
+ expect.objectContaining({
279
+ id: 'acme-app-shell',
280
+ relationship: 'replaces',
281
+ replaces: core.dirName,
282
+ severity: 'info',
283
+ }),
284
+ ]);
285
+ expect(parsed.data.conflicts[0].command).toContain(
286
+ `--package @astryxdesign/core`,
287
+ );
288
+ expect(process.exitCode).toBeUndefined();
289
+ });
290
+
291
+ it('templates exits 1 for a missing replacement target', async () => {
292
+ writeIntegration({
293
+ id: 'acme-app-shell',
294
+ replacements: {'acme-app-shell': 'missing-core-shell'},
295
+ });
296
+ process.chdir(tmpDir);
297
+
298
+ await createProgram().parseAsync([
299
+ 'node',
300
+ 'astryx',
301
+ '--json',
302
+ 'doctor',
303
+ 'integration',
304
+ 'templates',
305
+ ]);
306
+
307
+ const parsed = JSON.parse(logCalls.join('\n'));
308
+ expect(parsed.data.issues).toEqual(
309
+ expect.arrayContaining([
310
+ expect.objectContaining({
311
+ code: 'missing_template_replacement_target',
312
+ severity: 'error',
313
+ }),
314
+ ]),
315
+ );
316
+ expect(process.exitCode).toBe(1);
317
+ });
318
+
242
319
  it('templates exits 1 when structural errors prevent a trustworthy check', async () => {
243
320
  writeIntegration({missingRoot: true});
244
321
  process.chdir(tmpDir);
@@ -278,9 +355,7 @@ describe('doctor integration — command', () => {
278
355
  const output = logCalls.join('\n');
279
356
  expect(output).toContain('[warn]');
280
357
  expect(output).toContain(core.name);
281
- expect(output).toContain(
282
- `component ${core.name} --package @acme/widgets`,
283
- );
358
+ expect(output).toContain(`component ${core.name} --package @acme/widgets`);
284
359
  expect(process.exitCode).toBeUndefined();
285
360
  });
286
361
 
@@ -12,7 +12,7 @@ export const doc = {
12
12
  type: 'command',
13
13
  name: 'doctor',
14
14
  displayName: 'astryx doctor',
15
- namespace: 'cli',
15
+ namespace: 'cli/commands',
16
16
  summary: 'Diagnose Astryx projects and integration packages',
17
17
  description:
18
18
  'Runs read-only project health diagnostics by default: Node version, @astryxdesign/core ' +
@@ -17,7 +17,7 @@ import {
17
17
  validateIntegration,
18
18
  } from '../../../api/integration/validate-integration.mjs';
19
19
  import {jsonOut} from '../../../foundation/response/json.mjs';
20
- import {emit, section, records, text} from '../formatters/index.mjs';
20
+ import {emit, section, record, records, text} from '../formatters/index.mjs';
21
21
  import {defineCommand} from '../lib/define-command.mjs';
22
22
  import {doc as doctorCommand} from './doctor.doc.mjs';
23
23
  import {doc as doctorIntegrationGroup} from './doctor-integration.doc.mjs';
@@ -55,7 +55,7 @@ function integrationLabel(data) {
55
55
  * @param {import('../../../api/doctor/doctor.mjs').DoctorReport} report
56
56
  */
57
57
  function printHuman(report) {
58
- const {pass, warn, fail, info} = report.summary;
58
+ const {warn, fail} = report.summary;
59
59
  const closing =
60
60
  fail > 0
61
61
  ? 'Some checks failed. Address the items marked [fail] above.'
@@ -63,18 +63,15 @@ function printHuman(report) {
63
63
  ? 'No failures — but review the [warn] warnings above when you can.'
64
64
  : 'All checks passed. Your Astryx setup looks healthy.';
65
65
 
66
+ // Field names are the JSON keys, so text and --json map one to one.
66
67
  emit(
67
68
  section('astryx doctor — diagnosing your setup'),
68
69
  records(report.checks, {
69
- fields: ['status', 'label', 'message', 'fix'],
70
- labels: {label: 'check'},
70
+ fields: ['id', 'status', 'label', 'message', 'fix'],
71
71
  format: {status: statusToken},
72
72
  }),
73
- text(
74
- `Summary: ${pass} passed, ${warn} warning${warn === 1 ? '' : 's'}, ` +
75
- `${fail} failure${fail === 1 ? '' : 's'}` +
76
- (info ? `, ${info} info` : ''),
77
- ),
73
+ section('summary'),
74
+ record(report.summary, {fields: ['pass', 'warn', 'fail', 'info']}),
78
75
  text(closing),
79
76
  );
80
77
  }
@@ -128,14 +125,18 @@ function printTemplateConflicts(data) {
128
125
  ),
129
126
  ...issueBlocks(data.issues),
130
127
  ];
131
- if (data.conflicts.length === 0) {
132
- output.push(text('[ok] No template ids conflict with Core.'));
133
- } else {
128
+ if (data.conflicts.length === 0 && data.issues.length === 0) {
129
+ output.push(
130
+ text('[ok] No template replacements or id conflicts with Core.'),
131
+ );
132
+ } else if (data.conflicts.length > 0) {
134
133
  output.push(
135
134
  records(data.conflicts, {
136
135
  fields: [
137
136
  'severity',
137
+ 'relationship',
138
138
  'id',
139
+ 'replaces',
139
140
  'integrationPackage',
140
141
  'integrationType',
141
142
  'integrationName',
@@ -144,10 +145,7 @@ function printTemplateConflicts(data) {
144
145
  ],
145
146
  format: {severity: statusToken},
146
147
  }),
147
- text(
148
- `${data.conflicts.length} Core template conflict(s). ` +
149
- 'Renaming is recommended but optional; keep the package-qualified command if the overlap is intentional.',
150
- ),
148
+ text(`${data.conflicts.length} Core template relationship(s).`),
151
149
  );
152
150
  }
153
151
  emit(...output);
@@ -168,7 +166,13 @@ function printComponentConflicts(data) {
168
166
  } else {
169
167
  output.push(
170
168
  records(data.conflicts, {
171
- fields: ['severity', 'name', 'integrationPackage', 'message', 'command'],
169
+ fields: [
170
+ 'severity',
171
+ 'name',
172
+ 'integrationPackage',
173
+ 'message',
174
+ 'command',
175
+ ],
172
176
  format: {severity: statusToken},
173
177
  }),
174
178
  text(
@@ -190,6 +194,13 @@ function printDocConflicts(data) {
190
194
  ),
191
195
  ...issueBlocks(data.issues),
192
196
  ];
197
+ if (
198
+ !data.issues.some(
199
+ issue => issue.severity === 'error' || issue.code === 'invalid_doc_graph',
200
+ )
201
+ ) {
202
+ output.push(text('[ok] The docs tree and every link in these docs check out.'));
203
+ }
193
204
  if (data.findings.length === 0) {
194
205
  output.push(text('[ok] No doc topics overlap with Core.'));
195
206
  } else {
@@ -275,7 +286,8 @@ async function runAuthoringCheck(program, pkg, kind) {
275
286
  const structuralErrors = summarizeIssues(result.data.issues).errors;
276
287
  const docErrors =
277
288
  result.type === 'integration.doc-conflicts'
278
- ? result.data.findings.filter(finding => finding.severity === 'error').length
289
+ ? result.data.findings.filter(finding => finding.severity === 'error')
290
+ .length
279
291
  : 0;
280
292
  if (structuralErrors > 0 || docErrors > 0) process.exitCode = 1;
281
293
  return NO_RESULT_SET;
@@ -290,13 +302,6 @@ export function registerDoctor(program) {
290
302
  fn: doctorFn,
291
303
  action: async () => runProjectDoctor(program),
292
304
  });
293
- doctorCmd.addHelpText(
294
- 'after',
295
- '\nExit code:\n' +
296
- ' 0 no failures (warnings are allowed) — safe as a CI gate\n' +
297
- ' 1 one or more checks failed\n',
298
- );
299
-
300
305
  /** @type {import('commander').Command} */
301
306
  let integrationCmd;
302
307
  integrationCmd = defineCommand(doctorCmd, doctorIntegrationGroup, {
@@ -354,3 +354,45 @@ describe('doctor — command', () => {
354
354
  }
355
355
  });
356
356
  });
357
+
358
+ describe('doctor — text output mirrors the JSON', () => {
359
+ /** @param {string} line */
360
+ const field = line => /^(\w+):\s+(.*)$/.exec(line)?.slice(1) ?? [line, ''];
361
+
362
+ it('prints every check and summary field under its JSON key', async () => {
363
+ const prevCwd = process.cwd();
364
+ const prevExit = process.exitCode;
365
+ process.chdir(tmpDir);
366
+ try {
367
+ await createProgram().parseAsync(['node', 'astryx', '--json', 'doctor']);
368
+ const {checks, summary} = JSON.parse(logCalls.join('\n')).data;
369
+ logCalls = [];
370
+ await createProgram().parseAsync(['node', 'astryx', 'doctor']);
371
+ const blocks = logCalls
372
+ .join('\n')
373
+ .split(/\n{2,}/)
374
+ .map(block => block.split('\n').map(field));
375
+
376
+ for (const check of checks) {
377
+ const block = blocks.find(fields =>
378
+ fields.some(([key, value]) => key === 'id' && value === check.id),
379
+ );
380
+ expect(block, `no text record for check ${check.id}`).toBeDefined();
381
+ expect(
382
+ /** @type {string[][]} */ (block).map(([key]) => key).sort(),
383
+ ).toEqual(Object.keys(check).sort());
384
+ }
385
+
386
+ const heading = blocks.findIndex(
387
+ fields => fields.length === 1 && fields[0][0] === 'summary',
388
+ );
389
+ expect(heading, 'no summary section').toBeGreaterThan(-1);
390
+ expect(blocks[heading + 1]).toEqual(
391
+ Object.entries(summary).map(([key, count]) => [key, String(count)]),
392
+ );
393
+ } finally {
394
+ process.chdir(prevCwd);
395
+ process.exitCode = prevExit;
396
+ }
397
+ }, 60_000);
398
+ });