@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.10dd683
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +66 -63
- package/api/component/_adapter.d.mts +0 -25
- package/api/component/_adapter.mjs +5 -59
- package/api/component/component.d.mts +3 -6
- package/api/component/component.doc.mjs +10 -23
- package/api/component/component.mjs +9 -249
- package/api/component/component.type.d.mts +0 -25
- package/api/component/component.type.mjs +0 -44
- package/api/docs/docs.test.mjs +0 -2
- package/api/doctor/doctor.d.mts +3 -8
- package/api/doctor/doctor.mjs +9 -90
- package/api/doctor/doctor.test.mjs +10 -122
- package/api/index.d.mts +2 -1
- package/api/index.mjs +4 -4
- package/api/integration/pack-check.mjs +3 -28
- package/api/json/index.ts +1 -0
- package/api/layout/_adapter.d.mts +34 -0
- package/api/layout/_adapter.mjs +148 -0
- package/api/layout/check/check.d.mts +16 -0
- package/api/layout/check/check.mjs +40 -0
- package/api/layout/expand/expand.d.mts +22 -0
- package/api/layout/expand/expand.mjs +155 -0
- package/api/layout/expand/expand.path-safety.test.mjs +53 -0
- package/api/layout/grammar/grammar.d.mts +13 -0
- package/api/layout/grammar/grammar.mjs +87 -0
- package/api/layout/layout.d.mts +6 -0
- package/api/layout/layout.mjs +17 -0
- package/api/layout/layout.test.mjs +297 -0
- package/api/layout/layout.type.d.mts +89 -0
- package/api/layout/layout.type.mjs +103 -0
- package/api/layout/layoutCheck.doc.d.mts +11 -0
- package/api/layout/layoutCheck.doc.mjs +85 -0
- package/api/layout/layoutExpand.doc.d.mts +11 -0
- package/api/layout/layoutExpand.doc.mjs +107 -0
- package/api/layout/layoutGrammar.doc.d.mts +11 -0
- package/api/layout/layoutGrammar.doc.mjs +57 -0
- package/api/search/search.test.mjs +0 -18
- package/api/template/template-integration.test.mjs +65 -1
- package/api/template/template.mjs +1 -1
- package/api/upgrade/run/run.mjs +4 -6
- package/api/upgrade/upgrade.type.mjs +2 -2
- package/assets/codemods/__tests__/runner.test.mjs +1 -3
- package/assets/codemods/integration-runner.mjs +3 -3
- package/assets/codemods/runner.mjs +4 -5
- package/authoring/config/config.doc.mjs +1 -1
- package/authoring/config/type.ts +2 -2
- package/authoring/doctypes/command/command.doc.mjs +1 -1
- package/authoring/doctypes/command/type.ts +1 -1
- package/clients/cli/command-result-coverage.test.mjs +7 -7
- package/clients/cli/commands/component/index.mjs +55 -152
- package/clients/cli/commands/component-ownership.test.mjs +0 -89
- package/clients/cli/commands/component.doc.mjs +6 -23
- package/clients/cli/commands/debug-result-summary.test.mjs +2 -2
- package/clients/cli/commands/docs.test.mjs +0 -29
- package/clients/cli/commands/layout-check.doc.mjs +65 -0
- package/clients/cli/commands/layout-expand.doc.mjs +83 -0
- package/clients/cli/commands/layout-grammar.doc.mjs +30 -0
- package/clients/cli/commands/layout.doc.mjs +34 -0
- package/clients/cli/commands/layout.error-codes.test.mjs +66 -0
- package/clients/cli/commands/layout.exit-parity.test.mjs +41 -0
- package/clients/cli/commands/layout.mjs +275 -0
- package/clients/cli/commands/layout.path-help.test.mjs +33 -0
- package/clients/cli/commands/layout.stdin-cap.test.mjs +47 -0
- package/clients/cli/commands/layout.text-fields.test.mjs +39 -0
- package/clients/cli/commands/text-json-parity.test.mjs +17 -0
- package/clients/cli/index.mjs +4 -0
- package/clients/cli/lib/exit-codes.test.mjs +8 -1
- package/clients/cli/lib/json-shim.mjs +14 -24
- package/clients/cli/lib/json-shim.test.mjs +20 -6
- package/clients/cli/lib/manifest.mjs +8 -2
- package/clients/cli/lib/manifest.test.mjs +2 -5
- package/foundation/discovery/template-adapter.mjs +1 -1
- package/foundation/doc-compiler/doc-loads.test.mjs +12 -0
- package/foundation/doc-compiler/tree.test.mjs +1 -9
- package/foundation/response/response-types.doc.mjs +17 -5
- package/foundation/response/response-types.doc.test.mjs +0 -23
- package/foundation/xle/browser.d.mts +3 -3
- package/foundation/xle/browser.mjs +3 -3
- package/foundation/xle/expand.mjs +2 -2
- package/foundation/xle/parse.mjs +1 -1
- package/foundation/xle/print.mjs +2 -2
- package/foundation/xle/splice.mjs +1 -1
- package/package.json +9 -9
- package/api/integration/pack-check.lifecycle-output.test.mjs +0 -105
- package/api/upgrade/run/files-changed.test.mjs +0 -111
- package/assets/codemods/file-count.test.mjs +0 -163
- package/assets/docs/tree/component-lookups.doc.mjs +0 -149
- package/clients/cli/commands/component-batch.test.mjs +0 -341
- package/clients/cli/lib/parse-error-format.test.mjs +0 -81
- package/foundation/response/batch.type.d.mts +0 -33
- package/foundation/response/batch.type.mjs +0 -34
package/README.md
CHANGED
|
@@ -89,6 +89,7 @@ Options:
|
|
|
89
89
|
| `hook` | List hooks or print hook docs |
|
|
90
90
|
| `init` | Initialize the design system in your project |
|
|
91
91
|
| `integration` | Author and verify an Astryx integration package |
|
|
92
|
+
| `layout` | Generate XDS layouts from compressed expressions (XLE/XLO) |
|
|
92
93
|
| `search` | Search components, hooks, docs, and templates in one ranked list |
|
|
93
94
|
| `swizzle` | Copy component source for customization |
|
|
94
95
|
| `template` | Inject a page or block template |
|
|
@@ -417,63 +418,65 @@ Every response has a `type` discriminant. The full set is below (generated from
|
|
|
417
418
|
|
|
418
419
|
<!-- BEGIN GENERATED: response-types -->
|
|
419
420
|
|
|
420
|
-
| Type | What `data` carries
|
|
421
|
-
| --------------------------------- |
|
|
422
|
-
| `init.run` | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted.
|
|
423
|
-
| `init.remove` | Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when --remove-agents is set.
|
|
424
|
-
| `component.list` | The component catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.
|
|
425
|
-
| `component.
|
|
426
|
-
| `component.detail`
|
|
427
|
-
| `component.detail.
|
|
428
|
-
| `component.detail.
|
|
429
|
-
| `component.detail.
|
|
430
|
-
| `
|
|
431
|
-
| `docs.
|
|
432
|
-
| `docs.
|
|
433
|
-
| `docs.
|
|
434
|
-
| `docs.
|
|
435
|
-
| `
|
|
436
|
-
| `blog.
|
|
437
|
-
| `
|
|
438
|
-
| `discover.
|
|
439
|
-
| `discover.detail`
|
|
440
|
-
| `discover.
|
|
441
|
-
| `discover.
|
|
442
|
-
| `
|
|
443
|
-
| `
|
|
444
|
-
| `build.
|
|
445
|
-
| `
|
|
446
|
-
| `swizzle.
|
|
447
|
-
| `
|
|
448
|
-
| `gap-report.
|
|
449
|
-
| `
|
|
450
|
-
| `template.
|
|
451
|
-
| `template.
|
|
452
|
-
| `template.
|
|
453
|
-
| `template.
|
|
454
|
-
| `
|
|
455
|
-
| `hook.
|
|
456
|
-
| `hook.detail`
|
|
457
|
-
| `
|
|
458
|
-
| `theme.build`
|
|
459
|
-
| `theme.build.
|
|
460
|
-
| `theme.
|
|
461
|
-
| `theme.
|
|
462
|
-
| `theme.
|
|
463
|
-
| `theme.
|
|
464
|
-
| `theme.
|
|
465
|
-
| `
|
|
466
|
-
| `upgrade.
|
|
467
|
-
| `upgrade.
|
|
468
|
-
| `
|
|
469
|
-
| `
|
|
470
|
-
| `
|
|
471
|
-
| `integration.
|
|
472
|
-
| `integration.
|
|
473
|
-
| `integration.
|
|
474
|
-
| `integration.
|
|
475
|
-
| `integration.
|
|
476
|
-
| `
|
|
421
|
+
| Type | What `data` carries |
|
|
422
|
+
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
423
|
+
| `init.run` | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted. |
|
|
424
|
+
| `init.remove` | Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when --remove-agents is set. |
|
|
425
|
+
| `component.list` | The component catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry. |
|
|
426
|
+
| `component.detail` | One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc). |
|
|
427
|
+
| `component.detail.props` | Just one component's props table (ComponentPropDoc[]). |
|
|
428
|
+
| `component.detail.source` | One component's source file, as {component, source}. |
|
|
429
|
+
| `component.detail.showcase` | One component's showcase example, as {component, aspectRatio, source}. |
|
|
430
|
+
| `component.detail.blocks` | One component's example blocks, as {component, showcase, examples, related} of BlockEntry. |
|
|
431
|
+
| `docs.list` | All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load. |
|
|
432
|
+
| `docs.detail` | One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there). |
|
|
433
|
+
| `docs.index` | One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there). |
|
|
434
|
+
| `docs.detail.section` | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it). |
|
|
435
|
+
| `docs.node` | One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names). |
|
|
436
|
+
| `blog.list` | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL. |
|
|
437
|
+
| `blog.detail` | One post's metadata plus the feed URL and the post's full plaintext body. |
|
|
438
|
+
| `discover.list` | The integrations the project loads (name, category, components, version, a list per other kind they add, and latest when a source knows it); with a discover source, meta.available lists what the project could add and meta.sources reports each source; when empty it carries meta.configured to tell "nothing configured" from "nothing discovered". |
|
|
439
|
+
| `discover.detail` | One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it. |
|
|
440
|
+
| `discover.detail.doc` | The validated ComponentDoc for one installed component, for an @scope/name/Component query. |
|
|
441
|
+
| `discover.item` | One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package. |
|
|
442
|
+
| `discover.search` | The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list. |
|
|
443
|
+
| `search` | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title, parent (the command that opens the level above), package (for a docs-tree hit), and, for a hit on one section, section (docs), or displayName and kind (templates). |
|
|
444
|
+
| `build.help` | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation. |
|
|
445
|
+
| `build.kit` | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, command, basis, reason, alternatives, ...}, pages (search's closest templates), blocks and domain as SearchResultEntry[], frame, foundation, and hint {reason, commands} when thin. |
|
|
446
|
+
| `swizzle.list` | The names of swizzlable components discoverable from cwd's @astryxdesign/core. |
|
|
447
|
+
| `swizzle.copy` | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note. |
|
|
448
|
+
| `gap-report.categories` | The fixed gap category values and human-readable labels. |
|
|
449
|
+
| `gap-report.file` | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals. |
|
|
450
|
+
| `template.list` | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list. |
|
|
451
|
+
| `template.show` | The resolved template's raw source plus its description, kind, and the component names it composes. |
|
|
452
|
+
| `template.skeleton` | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes. |
|
|
453
|
+
| `template.copy` | A scaffold receipt: template id, output directory, written file name, and file count. |
|
|
454
|
+
| `template.cdn` | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |
|
|
455
|
+
| `hook.list` | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry. |
|
|
456
|
+
| `hook.detail` | One hook's full authored HookDoc. |
|
|
457
|
+
| `hook.detail.params` | Just one hook's parameters table (HookParamDoc[]). |
|
|
458
|
+
| `theme.build` | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load). |
|
|
459
|
+
| `theme.build.check` | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing. |
|
|
460
|
+
| `theme.build.batch` | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS. |
|
|
461
|
+
| `theme.list` | Every bundled or installed integration theme as a ThemeListEntry[]: each with slug, displayName, description, maintained flag, and owner package. |
|
|
462
|
+
| `theme.add` | A scaffold receipt: resolved slug, displayName, maintained flag, owner package, outputDir (relative to cwd), the theme entry file, its exportName, and the files written. |
|
|
463
|
+
| `theme.template` | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |
|
|
464
|
+
| `theme.targets` | The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key. |
|
|
465
|
+
| `theme.palette.generate` | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result. |
|
|
466
|
+
| `upgrade.list` | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything. |
|
|
467
|
+
| `upgrade.status` | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. |
|
|
468
|
+
| `upgrade.run` | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors. |
|
|
469
|
+
| `manifest` | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index. |
|
|
470
|
+
| `doctor` | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status. |
|
|
471
|
+
| `integration.add` | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun. |
|
|
472
|
+
| `integration.pack-check` | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}]. |
|
|
473
|
+
| `integration.validate` | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}. |
|
|
474
|
+
| `integration.template-conflicts` | The integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}. |
|
|
475
|
+
| `integration.component-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. |
|
|
476
|
+
| `integration.doc-conflicts` | The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`). |
|
|
477
|
+
| `layout.expand` | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written). |
|
|
478
|
+
| `layout.check` | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline). |
|
|
479
|
+
| `layout.grammar` | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry. |
|
|
477
480
|
|
|
478
481
|
<!-- END GENERATED: response-types -->
|
|
479
482
|
<!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
|
|
@@ -574,12 +577,12 @@ There is no factory: write a plain object. For editor autocomplete and
|
|
|
574
577
|
type-checking, annotate it with the `AstryxConfig` type exported from
|
|
575
578
|
`@astryxdesign/cli/authoring`.
|
|
576
579
|
|
|
577
|
-
| Field | Type | Purpose
|
|
578
|
-
| ----------------------------- | ------------------------------ |
|
|
579
|
-
| `integrations` | `string[]` | Integration package names to load (see [Integrations](#integrations)).
|
|
580
|
-
| `issuesUrl` | `string` | Where "report an issue" links point for your project. Defaults to the core issue tracker.
|
|
581
|
-
| `hooks.postCodemod` | `PostCodemodHook[]` | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).
|
|
582
|
-
| `experimental.xle.components` | `Record<string, XleComponent>` |
|
|
580
|
+
| Field | Type | Purpose |
|
|
581
|
+
| ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
|
|
582
|
+
| `integrations` | `string[]` | Integration package names to load (see [Integrations](#integrations)). |
|
|
583
|
+
| `issuesUrl` | `string` | Where "report an issue" links point for your project. Defaults to the core issue tracker. |
|
|
584
|
+
| `hooks.postCodemod` | `PostCodemodHook[]` | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat). |
|
|
585
|
+
| `experimental.xle.components` | `Record<string, XleComponent>` | Register app-local components so layout (XLE) expressions can reference them by name. Unstable. |
|
|
583
586
|
|
|
584
587
|
The config is validated against a strict schema when the CLI loads it, so an
|
|
585
588
|
unknown field is a hard error rather than a silent no-op. `astryx doctor`
|
|
@@ -68,16 +68,6 @@ export function requireCoreDir(cwd: string): string;
|
|
|
68
68
|
* @returns {Promise<import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]>}
|
|
69
69
|
*/
|
|
70
70
|
export function loadIntegrationsSafely(cwd: string): Promise<import("../../foundation/integrations/integrations.mjs").LoadedIntegration[]>;
|
|
71
|
-
/**
|
|
72
|
-
* Read the exact installed version available to a package-qualified component
|
|
73
|
-
* selector. Legacy docs packages do not expose a reliable version here, so a
|
|
74
|
-
* version-qualified lookup never falls through to them.
|
|
75
|
-
* @param {string} coreDir
|
|
76
|
-
* @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
|
|
77
|
-
* @param {string} packageName
|
|
78
|
-
* @returns {string|null}
|
|
79
|
-
*/
|
|
80
|
-
export function installedComponentPackageVersion(coreDir: string, loadedIntegrations: import("../../foundation/integrations/integrations.mjs").LoadedIntegration[], packageName: string): string | null;
|
|
81
71
|
/**
|
|
82
72
|
* Build the set of OWNER packages that provide a component with this name
|
|
83
73
|
* across core + every loaded integration. This is what lets the CLI
|
|
@@ -190,20 +180,6 @@ export function scopeSubComponent(docs: LoadedComponentDoc, dirName: string, cor
|
|
|
190
180
|
matchingComponent: any;
|
|
191
181
|
} | null;
|
|
192
182
|
export { CORE_PACKAGE };
|
|
193
|
-
/**
|
|
194
|
-
* Internal ambiguity marker. Single-component callers still receive the same
|
|
195
|
-
* AstryxError code, message, and suggestions; batch callers can additionally
|
|
196
|
-
* project every installed candidate without parsing prose.
|
|
197
|
-
*/
|
|
198
|
-
export class ComponentAmbiguityError extends AstryxError {
|
|
199
|
-
/**
|
|
200
|
-
* @param {ComponentOwner[]} owners
|
|
201
|
-
* @param {string} dirName
|
|
202
|
-
*/
|
|
203
|
-
constructor(owners: ComponentOwner[], dirName: string);
|
|
204
|
-
/** @type {import('./component.type.mjs').ComponentBatchCandidate[]} */
|
|
205
|
-
candidates: import("./component.type.mjs").ComponentBatchCandidate[];
|
|
206
|
-
}
|
|
207
183
|
/**
|
|
208
184
|
* A loaded component doc. The shared validated loader accepts stamped and legacy
|
|
209
185
|
* component docs; this loose view captures the fields the API reads across both.
|
|
@@ -282,4 +258,3 @@ export type ResolvedUnscopedDoc = {
|
|
|
282
258
|
resolvedSourcePath: string | null;
|
|
283
259
|
};
|
|
284
260
|
import { CORE_PACKAGE } from '../../foundation/discovery/component-discovery.mjs';
|
|
285
|
-
import { AstryxError } from '../error.mjs';
|
|
@@ -18,8 +18,6 @@
|
|
|
18
18
|
* deduped, so each leaf stays a thin projection.
|
|
19
19
|
*/
|
|
20
20
|
|
|
21
|
-
import * as fs from 'node:fs';
|
|
22
|
-
import * as path from 'node:path';
|
|
23
21
|
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
|
|
24
22
|
import {
|
|
25
23
|
findCoreDir,
|
|
@@ -148,34 +146,6 @@ function findLoadedIntegration(loadedIntegrations, packageName) {
|
|
|
148
146
|
return loadedIntegrations.find(i => i.name === packageName) ?? null;
|
|
149
147
|
}
|
|
150
148
|
|
|
151
|
-
/**
|
|
152
|
-
* Read the exact installed version available to a package-qualified component
|
|
153
|
-
* selector. Legacy docs packages do not expose a reliable version here, so a
|
|
154
|
-
* version-qualified lookup never falls through to them.
|
|
155
|
-
* @param {string} coreDir
|
|
156
|
-
* @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
|
|
157
|
-
* @param {string} packageName
|
|
158
|
-
* @returns {string|null}
|
|
159
|
-
*/
|
|
160
|
-
export function installedComponentPackageVersion(
|
|
161
|
-
coreDir,
|
|
162
|
-
loadedIntegrations,
|
|
163
|
-
packageName,
|
|
164
|
-
) {
|
|
165
|
-
if (packageName === CORE_PACKAGE) {
|
|
166
|
-
try {
|
|
167
|
-
const pkg = JSON.parse(
|
|
168
|
-
fs.readFileSync(path.join(coreDir, 'package.json'), 'utf8'),
|
|
169
|
-
);
|
|
170
|
-
return typeof pkg.version === 'string' ? pkg.version : null;
|
|
171
|
-
} catch {
|
|
172
|
-
return null;
|
|
173
|
-
}
|
|
174
|
-
}
|
|
175
|
-
const integration = findLoadedIntegration(loadedIntegrations, packageName);
|
|
176
|
-
return typeof integration?.version === 'string' ? integration.version : null;
|
|
177
|
-
}
|
|
178
|
-
|
|
179
149
|
/**
|
|
180
150
|
* Resolve an external package by name from the discovered externals list.
|
|
181
151
|
* @param {string} packageName - e.g. '@acme/xds-widgets'
|
|
@@ -274,34 +244,6 @@ export function classifyScope(
|
|
|
274
244
|
return {kind: 'legacy', ext};
|
|
275
245
|
}
|
|
276
246
|
|
|
277
|
-
/**
|
|
278
|
-
* Internal ambiguity marker. Single-component callers still receive the same
|
|
279
|
-
* AstryxError code, message, and suggestions; batch callers can additionally
|
|
280
|
-
* project every installed candidate without parsing prose.
|
|
281
|
-
*/
|
|
282
|
-
export class ComponentAmbiguityError extends AstryxError {
|
|
283
|
-
/** @type {import('./component.type.mjs').ComponentBatchCandidate[]} */
|
|
284
|
-
candidates;
|
|
285
|
-
|
|
286
|
-
/**
|
|
287
|
-
* @param {ComponentOwner[]} owners
|
|
288
|
-
* @param {string} dirName
|
|
289
|
-
*/
|
|
290
|
-
constructor(owners, dirName) {
|
|
291
|
-
super(
|
|
292
|
-
`Component "${dirName}" is provided by multiple packages. Re-run with --package <pkg> to choose one.`,
|
|
293
|
-
owners.map(o => ({name: o.package, reason: 'provides this component'})),
|
|
294
|
-
ERROR_CODES.ERR_UNKNOWN_COMPONENT,
|
|
295
|
-
);
|
|
296
|
-
this.candidates = owners.map(owner => ({
|
|
297
|
-
package: owner.package,
|
|
298
|
-
component: dirName,
|
|
299
|
-
kind: 'component',
|
|
300
|
-
installed: true,
|
|
301
|
-
}));
|
|
302
|
-
}
|
|
303
|
-
}
|
|
304
|
-
|
|
305
247
|
/**
|
|
306
248
|
* Refuse to guess when the name is owned by MORE THAN ONE package (core and/or
|
|
307
249
|
* integrations) and the caller did not scope with --package. Legacy
|
|
@@ -312,7 +254,11 @@ export class ComponentAmbiguityError extends AstryxError {
|
|
|
312
254
|
*/
|
|
313
255
|
export function assertUnambiguousOwners(owners, dirName) {
|
|
314
256
|
if (owners.length > 1) {
|
|
315
|
-
throw new
|
|
257
|
+
throw new AstryxError(
|
|
258
|
+
`Component "${dirName}" is provided by multiple packages. Re-run with --package <pkg> to choose one.`,
|
|
259
|
+
owners.map(o => ({name: o.package, reason: 'provides this component'})),
|
|
260
|
+
ERROR_CODES.ERR_UNKNOWN_COMPONENT,
|
|
261
|
+
);
|
|
316
262
|
}
|
|
317
263
|
}
|
|
318
264
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
|
-
* @param {string
|
|
5
|
+
* @param {string} [name]
|
|
6
6
|
* @param {object} [options]
|
|
7
7
|
* @param {string} [options.cwd]
|
|
8
8
|
* @param {boolean} [options.list]
|
|
@@ -18,7 +18,6 @@
|
|
|
18
18
|
* @param {boolean} [options.dense]
|
|
19
19
|
* @returns {Promise<(
|
|
20
20
|
* import('./component.type.mjs').ComponentListResponse
|
|
21
|
-
* | import('./component.type.mjs').ComponentBatchResponse
|
|
22
21
|
* | import('./component.type.mjs').ComponentDetailResponse
|
|
23
22
|
* | import('./component.type.mjs').ComponentDetailPropsResponse
|
|
24
23
|
* | import('./component.type.mjs').ComponentDetailSourceResponse
|
|
@@ -26,7 +25,7 @@
|
|
|
26
25
|
* | import('./component.type.mjs').ComponentDetailBlocksResponse
|
|
27
26
|
* )>}
|
|
28
27
|
*/
|
|
29
|
-
export function component(name?: string
|
|
28
|
+
export function component(name?: string, options?: {
|
|
30
29
|
cwd?: string | undefined;
|
|
31
30
|
list?: boolean | undefined;
|
|
32
31
|
category?: string | undefined;
|
|
@@ -39,6 +38,4 @@ export function component(name?: string | string[], options?: {
|
|
|
39
38
|
lang?: string | undefined;
|
|
40
39
|
zh?: boolean | undefined;
|
|
41
40
|
dense?: boolean | undefined;
|
|
42
|
-
}): Promise<(import("./component.type.mjs").ComponentListResponse | import("./component.type.mjs").
|
|
43
|
-
/** Maximum selectors accepted before any component resolution starts. */
|
|
44
|
-
export const COMPONENT_BATCH_SELECTOR_LIMIT: 100;
|
|
41
|
+
}): Promise<(import("./component.type.mjs").ComponentListResponse | import("./component.type.mjs").ComponentDetailResponse | import("./component.type.mjs").ComponentDetailPropsResponse | import("./component.type.mjs").ComponentDetailSourceResponse | import("./component.type.mjs").ComponentDetailShowcaseResponse | import("./component.type.mjs").ComponentDetailBlocksResponse)>;
|
|
@@ -15,16 +15,16 @@ export const doc = {
|
|
|
15
15
|
namespace: 'cli/api',
|
|
16
16
|
displayName: 'component()',
|
|
17
17
|
summary:
|
|
18
|
-
'Resolve
|
|
18
|
+
'Resolve a component by name, or list the catalog, with optional focused slices (props, source, showcase, blocks).',
|
|
19
19
|
description:
|
|
20
|
-
'Routes on its arguments:
|
|
21
|
-
'integration packages
|
|
22
|
-
'
|
|
23
|
-
'Boolean flags narrow
|
|
24
|
-
'showcase, or example blocks.',
|
|
20
|
+
'Routes on its arguments: a name resolves that component across core and ' +
|
|
21
|
+
'integration packages and returns its authored ComponentDoc plus ownership ' +
|
|
22
|
+
'metadata; no name (or `list`/`category`) returns the catalog grouped by ' +
|
|
23
|
+
'category. Boolean flags narrow a single component to just its props, ' +
|
|
24
|
+
'source, showcase, or example blocks.',
|
|
25
25
|
importPath: '@astryxdesign/cli/api',
|
|
26
26
|
signature:
|
|
27
|
-
'component(name?: string
|
|
27
|
+
'component(name?: string, options?: ComponentOptions): Promise<ComponentListResponse | ComponentDetailResponse | ComponentDetailPropsResponse | ComponentDetailSourceResponse | ComponentDetailShowcaseResponse | ComponentDetailBlocksResponse>',
|
|
28
28
|
keywords: [
|
|
29
29
|
'component',
|
|
30
30
|
'components',
|
|
@@ -37,9 +37,9 @@ export const doc = {
|
|
|
37
37
|
params: [
|
|
38
38
|
{
|
|
39
39
|
name: 'name',
|
|
40
|
-
type: 'string
|
|
40
|
+
type: 'string',
|
|
41
41
|
description:
|
|
42
|
-
"
|
|
42
|
+
"Component name to resolve (e.g. 'Button'). Omit to list the catalog.",
|
|
43
43
|
},
|
|
44
44
|
{
|
|
45
45
|
name: 'options.cwd',
|
|
@@ -112,11 +112,6 @@ export const doc = {
|
|
|
112
112
|
description:
|
|
113
113
|
"The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integration and legacy package components; brief entries; or full ComponentDoc entries.",
|
|
114
114
|
},
|
|
115
|
-
{
|
|
116
|
-
type: 'component.batch',
|
|
117
|
-
description:
|
|
118
|
-
'An explicit selector array returns one ordered receipt at every array length: count and one results row per selector, including duplicates. ComponentBatchResponse specializes the shared BatchResponse and BatchRow types. Each row carries selector and status (found, not_found, ambiguous, or error); found rows carry the single-selector result, ambiguous rows carry installed candidates ({package, component, kind, installed}), and failed rows carry code, error, and optional suggestions.',
|
|
119
|
-
},
|
|
120
115
|
{
|
|
121
116
|
type: 'component.detail',
|
|
122
117
|
description:
|
|
@@ -142,10 +137,6 @@ export const doc = {
|
|
|
142
137
|
},
|
|
143
138
|
],
|
|
144
139
|
throws: [
|
|
145
|
-
{
|
|
146
|
-
code: 'ERR_INVALID_ARGUMENT',
|
|
147
|
-
when: 'a selector array has more than 100 entries, a package-shaped selector has no component item, or its package conflicts with options.package',
|
|
148
|
-
},
|
|
149
140
|
{
|
|
150
141
|
code: 'ERR_INVALID_DETAIL',
|
|
151
142
|
when: "options.detail is not 'full', 'compact', or 'brief'",
|
|
@@ -168,7 +159,7 @@ export const doc = {
|
|
|
168
159
|
},
|
|
169
160
|
{
|
|
170
161
|
code: 'ERR_UNKNOWN_PACKAGE',
|
|
171
|
-
when: 'options.package names a legacy external package that cannot be found
|
|
162
|
+
when: 'options.package names a legacy external package that cannot be found',
|
|
172
163
|
},
|
|
173
164
|
{
|
|
174
165
|
code: 'ERR_NO_DOC',
|
|
@@ -188,10 +179,6 @@ export const doc = {
|
|
|
188
179
|
label: 'Look up a component',
|
|
189
180
|
code: "const r = await component('Button');",
|
|
190
181
|
},
|
|
191
|
-
{
|
|
192
|
-
label: 'Look up several components',
|
|
193
|
-
code: "await component(['Button', 'Badge']);",
|
|
194
|
-
},
|
|
195
182
|
{label: 'Props only', code: "await component('Button', {props: true});"},
|
|
196
183
|
{
|
|
197
184
|
label: 'Browse a category',
|