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

package/authoring/gap-report/gap-report.doc.mjs

@@ -0,0 +1,183 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for GapReportHandler, the handler `astryx gap-report` calls.
+ * @input The GapReportHandler type beside it (`type.ts`), which `parse.mjs`
+ *   validates.
+ * @output The `gap-report-handler` section of `astryx docs authoring`.
+ * @position packages/cli/authoring/gap-report — schema documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+  type: 'schema',
+  name: 'gap-report-handler',
+  displayName: 'GapReportHandler',
+  namespace: 'authoring',
+  description:
+    'A handler for `astryx gap-report`: a plain object with an `audience` and a `handle` function. Set it as `gapReport` in astryx.config, or export it as `gapReport` from an integration manifest. Every handler runs: the project handler first, then each integration handler in config order.',
+  appliesTo:
+    '`gapReport` in astryx.config.*, or the `gapReport` named export of astryx.integration.*',
+  fields: [
+    {
+      name: 'audience',
+      type: "'internal' | 'public'",
+      description:
+        'Whether the destination is internal to your organization or public. A public handler runs only when the caller agrees; an internal handler always runs.',
+      required: true,
+    },
+    {
+      name: 'handle',
+      type: '(report: GapReport, context: GapReportHandlerContext) => GapReportHandlerReceipt | Promise<GapReportHandlerReceipt>',
+      description:
+        'Gets the report and returns a receipt. It can be async, and the CLI waits at most 30 seconds for it. A throw, a timeout, or an invalid receipt is a failed delivery, and the other handlers still run.',
+      required: true,
+      fields: [
+        {
+          name: 'report',
+          type: 'GapReport',
+          description: 'The report. Each handler gets its own copy.',
+          required: true,
+          fields: [
+            {
+              name: 'report.schemaVersion',
+              type: '1',
+              description: 'Version of the report shape.',
+              required: true,
+            },
+            {
+              name: 'report.component',
+              type: 'string',
+              description: 'The component the gap is about.',
+              required: true,
+            },
+            {
+              name: 'report.category',
+              type: 'GapReportCategory',
+              description:
+                "The kind of gap: 'missing_component', 'missing_variant', 'layout_gap', 'styling_gap', 'a11y_gap', 'api_friction', 'docs_gap', or 'other'.",
+              required: true,
+            },
+            {
+              name: 'report.categoryLabel',
+              type: 'string',
+              description: 'A readable name for the category.',
+              required: true,
+            },
+            {
+              name: 'report.intention',
+              type: 'string',
+              description: 'What the caller was trying to do.',
+              required: true,
+            },
+            {
+              name: 'report.detail',
+              type: 'string',
+              description: 'More detail, when the caller gave some.',
+            },
+            {
+              name: 'report.source',
+              type: 'DebugInvocationSource',
+              description:
+                "Who sent the report: 'human', 'ai', 'automation', or 'unknown'.",
+              required: true,
+            },
+            {
+              name: 'report.timestamp',
+              type: 'string',
+              description: 'When the report was sent, as ISO 8601.',
+              required: true,
+            },
+            {
+              name: 'report.target',
+              type: 'GapReportTarget',
+              description: 'The package the report is about.',
+              required: true,
+              fields: [
+                {
+                  name: 'report.target.package',
+                  type: 'string',
+                  description: 'The package name.',
+                  required: true,
+                },
+                {
+                  name: 'report.target.version',
+                  type: 'string',
+                  description:
+                    'The installed version. Null when it is not known.',
+                  required: true,
+                },
+                {
+                  name: 'report.target.issuesUrl',
+                  type: 'string',
+                  description:
+                    'Where the package takes issues. Null when it does not say.',
+                  required: true,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'context',
+          type: 'GapReportHandlerContext',
+          description: 'The context of this call.',
+          required: true,
+          fields: [
+            {
+              name: 'context.signal',
+              type: 'AbortSignal',
+              description: 'Aborted when the handler runs past 30 seconds.',
+              required: true,
+            },
+          ],
+        },
+      ],
+    },
+  ],
+  examples: [
+    {
+      label: 'A project handler in astryx.config',
+      code:
+        'export default {\n' +
+        '  gapReport: {\n' +
+        "    audience: 'internal',\n" +
+        '    async handle(report, {signal}) {\n' +
+        '      const url = await fileIssue(report, {signal});\n' +
+        "      return {status: 'filed', url};\n" +
+        '    },\n' +
+        '  },\n' +
+        '};',
+    },
+  ],
+  notes: [
+    {
+      type: 'table',
+      headers: ['Receipt field', 'Type', 'Required', 'Description'],
+      rows: [
+        [
+          'status',
+          "'filed' | 'routed_only' | 'skipped'",
+          'yes',
+          "'filed': the handler created or queued the report. 'routed_only': it points to a place to file the report, and must return `url`. 'skipped': it chose not to act, for example on a duplicate.",
+        ],
+        [
+          'url',
+          'string',
+          'no',
+          'An http or https URL. Required when status is routed_only.',
+        ],
+        [
+          'message',
+          'string',
+          'no',
+          'A readable message of at most 2000 characters.',
+        ],
+      ],
+    },
+    {
+      type: 'prose',
+      text: 'The receipt is strict: an unknown field, a URL that is not http or https, or a filed or routed_only receipt with neither `url` nor `message` is invalid.',
+    },
+  ],
+};

package/authoring/index.d.mts

@@ -15,5 +15,6 @@ export { parseSchema } from "./doctypes/schema/parse.mjs";
 export { parseCommand } from "./doctypes/command/parse.mjs";
 export { parseEnum } from "./doctypes/enum/parse.mjs";
 export { parseNamespace } from "./doctypes/namespace/parse.mjs";
+export { parseTheme } from "./doctypes/theme/parse.mjs";
 export { parseLegacyDoc } from "./doctypes/legacy.mjs";
 export { parseGapReportHandler, parseGapReportReceipt } from "./gap-report/parse.mjs";

package/authoring/index.d.ts

@@ -23,15 +23,16 @@
 // ═══════════════════════════════════════════════════════════════════════
 // AUTHOR THESE — each is the default export of one authored file.
 // ═══════════════════════════════════════════════════════════════════════
-export type {ComponentDoc} from './doctypes/types.js'; //   Button.doc.{ts,mjs}
-export type {HookDoc} from './doctypes/types.js'; //         useToast.doc.{ts,mjs}
+export type {ComponentDoc} from './doctypes/types.js'; //   Button.doc.mjs
+export type {HookDoc} from './doctypes/types.js'; //         useToast.doc.mjs
 export type {FunctionDoc} from './doctypes/types.js'; //     search.doc.mjs (hook | api)
-export type {ReferenceDoc} from './doctypes/types.js'; //    theming.doc.{ts,mjs}
-export type {TemplateDoc} from './doctypes/types.js'; //     Foo.template.{ts,mjs}
+export type {ReferenceDoc} from './doctypes/types.js'; //    theming.doc.mjs
+export type {TemplateDoc} from './doctypes/types.js'; //     Foo.doc.mjs
 export type {SchemaDoc} from './doctypes/types.js'; //       config.doc.mjs (object shape)
 export type {CommandDoc} from './doctypes/types.js'; //      search.doc.mjs (CLI command)
 export type {EnumDoc} from './doctypes/types.js'; //         error-codes.doc.mjs (vocabulary)
 export type {NamespaceDoc} from './doctypes/types.js'; //    cli.doc.mjs (hierarchy)
+export type {ThemeDoc} from './doctypes/types.js'; //        oceanTheme.doc.mjs
 export type {AstryxConfig} from './config/type.js'; //       astryx.config.{ts,mjs}
 export type {DebugEvent} from './debug/type.js'; //          one recorded CLI run
 export type {AstryxIntegration} from './integration/type.js'; // astryx.integration.{ts,mjs}
@@ -58,6 +59,7 @@ export {parseSchema} from './doctypes/schema/parse.mjs';
 export {parseCommand} from './doctypes/command/parse.mjs';
 export {parseEnum} from './doctypes/enum/parse.mjs';
 export {parseNamespace} from './doctypes/namespace/parse.mjs';
+export {parseTheme} from './doctypes/theme/parse.mjs';
 export {parseLegacyDoc} from './doctypes/legacy.mjs';
 export {parseConfig} from './config/parse.mjs';
 export {parseIntegration} from './integration/parse.mjs';
@@ -129,6 +131,7 @@ export type {
   // reference
   ReferenceSection,
   ReferenceContentBlock,
+  GraphContentBlock,
   ReferenceTokenPreviewType,
   ReferenceTranslationDoc,
   WorkflowStep,

package/authoring/index.mjs

@@ -11,7 +11,7 @@
  * `type` directly.
  *
  * Types (config, integration, codemod, and the doc vocabulary —
- * component/hook/reference/template) are re-exported via `./index.ts`.
+ * component/hook/reference/template/theme) are re-exported via `./index.ts`.
  */
 
 export {parseConfig} from './config/parse.mjs';
@@ -32,4 +32,5 @@ export {parseSchema} from './doctypes/schema/parse.mjs';
 export {parseCommand} from './doctypes/command/parse.mjs';
 export {parseEnum} from './doctypes/enum/parse.mjs';
 export {parseNamespace} from './doctypes/namespace/parse.mjs';
+export {parseTheme} from './doctypes/theme/parse.mjs';
 export {parseLegacyDoc} from './doctypes/legacy.mjs';

package/authoring/integration/integration.doc.mjs

@@ -11,7 +11,7 @@ export const doc = {
   type: 'schema',
   name: 'integration',
   displayName: 'Astryx Integration',
-  namespace: 'cli',
+  namespace: 'authoring',
   description:
     'The astryx.integration.* manifest that sits beside an integration ' +
     "package's package.json. It can preserve a stable provider identity across a package rename, " +
@@ -57,7 +57,7 @@ export const doc = {
       name: 'themes',
       type: 'string',
       description:
-        'Relative path to a source-theme catalog root containing manifest.json plus one directory per theme slug. Installed themes appear in `astryx theme list` and can be copied with `astryx theme add`.',
+        'Relative path to a source-theme root with one directory per theme slug. Each directory contains a source module and mandatory same-stem, strongly typed .doc.mjs descriptor. Installed themes appear in `astryx theme list` and can be copied with `astryx theme add`.',
       example: "'./themes'",
     },
     {

package/authoring/integration/type.ts

@@ -34,15 +34,9 @@ export interface AstryxIntegration {
    *  serves from `astryx docs`, alongside the built-in ones. A topic may also
    *  `replace` or `extend` a built-in topic; see the ReferenceDoc type. */
   docs?: string;
-  /** Relative path to the source-theme catalog root (resolved to absolute).
-   *  The root contains `manifest.json` plus one directory per theme slug.
-   *  `manifest.json` is `{ "version": 1, "themes": [...] }` where each
-   *  entry requires `slug`, `displayName`, `description` (string),
-   *  `maintained` (boolean), `entry` (source file relative to `themes/<slug>/`),
-   *  `exportName` (a valid JS identifier naming the runtime export), and
-   *  `files` (non-empty array of filenames relative to `themes/<slug>/`).
-   *  Every file listed must exist on disk; the entry file must also appear
-   *  in `files`. */
+  /** Relative path to the source-theme root (resolved to absolute). Each
+   *  lower-kebab theme directory contains a source module and mandatory
+   *  same-stem, strongly typed `.doc.mjs` descriptor. */
   themes?: string;
   /** Static package guidance appended to the CLI-owned managed agent block. */
   agentDocs?: {

package/clients/cli/__tests__/cliManifest.test.ts

@@ -3,37 +3,35 @@
 import fs from 'fs';
 import path from 'path';
 import {describe, it, expect} from 'vitest';
-
-describe('@astryxdesign/cli Theme Manifest & Template Validation', () => {
-  const manifestPath = path.resolve(
-    'packages/cli/assets/templates/themes/manifest.json',
-  );
-
-  it('validates theme manifest existence and structure', () => {
-    expect(fs.existsSync(manifestPath)).toBe(true);
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-
-    expect(manifest.version).toBe(1);
-    expect(Array.isArray(manifest.themes)).toBe(true);
-    expect(manifest.themes.length).toBeGreaterThan(0);
-  });
-
-  it('verifies all referenced theme files exist', () => {
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    const themesDir = path.dirname(manifestPath);
-
-    for (const theme of manifest.themes) {
-      expect(theme.slug).toBeDefined();
-      expect(theme.displayName).toBeDefined();
-      expect(theme.entry).toBeDefined();
-
-      const entryPath = path.join(themesDir, theme.slug, theme.entry);
-      expect(fs.existsSync(entryPath)).toBe(true);
-
+import {discoverBundledThemes} from '../../../foundation/discovery/theme-discovery.mjs';
+
+describe('@astryxdesign/cli bundled theme descriptor validation', () => {
+  it('discovers typed descriptors and their same-stem source files', () => {
+    const themes = discoverBundledThemes();
+    expect(themes.length).toBeGreaterThan(0);
+
+    for (const theme of themes) {
+      expect(theme.slug).toBeTruthy();
+      expect(theme.displayName).toBeTruthy();
+      expect(theme.docPath).toBe(
+        path.join(
+          theme.sourceDir,
+          `${path.basename(theme.entry, path.extname(theme.entry))}.doc.mjs`,
+        ),
+      );
+      expect(fs.existsSync(theme.docPath)).toBe(true);
+      expect(fs.existsSync(path.join(theme.sourceDir, theme.entry))).toBe(true);
       for (const file of theme.files) {
-        const filePath = path.join(themesDir, theme.slug, file);
-        expect(fs.existsSync(filePath)).toBe(true);
+        expect(fs.existsSync(path.join(theme.sourceDir, file))).toBe(true);
       }
     }
   });
+
+  it('does not ship the obsolete central theme catalog', () => {
+    expect(
+      fs.existsSync(
+        path.resolve('packages/cli/assets/templates/themes/manifest.json'),
+      ),
+    ).toBe(false);
+  });
 });

package/clients/cli/commands/blog.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'blog',
   displayName: 'astryx blog',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Read the Astryx blog from the published feed',
   description:
     'Reads the design-system blog over its published RSS feed (never the source ' +

package/clients/cli/commands/build-theme.adaptations.test.mjs

@@ -3,7 +3,8 @@
 /**
  * @file Ensures `astryx theme build` preserves AST-012 adaptation semantics.
  * Runtime and static output share core's compiler; this suite guards the CLI
- * loading, diagnostics, serialization, and extension boundaries around it.
+ * loading, diagnostics, serialization, and extension boundaries around it,
+ * including root component overrides underneath adapted typography scales.
  */
 
 import {afterEach, beforeAll, beforeEach, describe, expect, it} from 'vitest';
@@ -94,6 +95,104 @@ describe('theme build adaptations', () => {
     );
   });
 
+  it.each([
+    ['defined', writeTheme],
+    ['plain', writePlainTheme],
+  ])(
+    'preserves component pins in %s themes and built extensions',
+    async (_kind, write) => {
+      const {defineTheme, generateAdaptationCSS, generateThemeCSS} =
+        await import('@astryxdesign/core/theme');
+      const project = path.join(tmpDir, 'project');
+      const themesDir = path.join(project, 'themes');
+      const displayFamily =
+        'Sarina, "Brush Script MT", "Snell Roundhand", cursive';
+      const input = {
+        name: 'adaptive-display',
+        typography: {
+          scale: {base: 16, ratio: 1.25},
+          body: {family: 'Outfit', fallbacks: 'sans-serif'},
+        },
+        components: {
+          text: Object.fromEntries(
+            ['display-1', 'display-2', 'display-3'].map(type => [
+              `type:${type}`,
+              {fontFamily: displayFamily},
+            ]),
+          ),
+          button: {base: {borderRadius: '12px'}},
+        },
+        adaptations: {
+          rules: [
+            {
+              when: {width: {below: 'md'}, pointer: 'coarse'},
+              value: {typography: {scale: {base: 14, ratio: 1.2}}},
+            },
+            {
+              when: {contrast: 'more'},
+              value: {
+                typography: {scale: {base: 15}},
+                components: {
+                  text: {'type:display-1': {fontFamily: 'monospace'}},
+                },
+              },
+            },
+          ],
+        },
+      };
+      const themeFile = write(themesDir, input.name, JSON.stringify(input));
+      const result = await build(project, themeFile);
+      expect(result.code, result.stderr).toBe(0);
+      const css = fs.readFileSync(
+        path.join(themesDir, 'adaptive-display.css'),
+        'utf8',
+      );
+      const compact = value => value.replace(/\s+/g, ' ').trim();
+      const source = defineTheme(input);
+      const runtime = generateThemeCSS(source);
+      // The CLI wraps root, adaptation, and surface CSS in separate @layer
+      // blocks; their contents and order must still match runtime output.
+      const adaptationCSS = generateAdaptationCSS(source).component;
+      const [rootCSS, surfaceCSS] = runtime.component.split(adaptationCSS);
+      const blocks = [rootCSS, adaptationCSS, surfaceCSS].map(compact);
+      let previousIndex = -1;
+      for (const block of blocks) {
+        expect(compact(css)).toContain(block);
+        const index = compact(css).indexOf(block);
+        expect(index).toBeGreaterThan(previousIndex);
+        previousIndex = index;
+      }
+      expect(compact(css)).toContain(compact(runtime.prose));
+      const scaleBlock = css.slice(
+        css.indexOf('@media (width < 768px) and (pointer: coarse)'),
+        css.indexOf('@media (prefers-contrast: more)'),
+      );
+      expect(scaleBlock).toContain('--font-size-base: 0.875rem');
+      expect(scaleBlock).not.toContain('.astryx-text');
+      expect(scaleBlock).not.toContain('.astryx-heading');
+      expect(scaleBlock).not.toContain('.astryx-button');
+      expect(css).toContain(`font-family: ${displayFamily};`);
+      expect(css).toContain('font-family: monospace;');
+
+      const {adaptiveDisplayTheme: builtTheme} = await import(
+        pathToFileURL(path.join(themesDir, 'adaptive-display.js')).href
+      );
+      expect(builtTheme.__adaptationRules).toBeUndefined();
+      expect(generateThemeCSS(builtTheme)).toEqual(runtime);
+      const childInput = {
+        name: 'display-child',
+        components: {text: {'type:display-2': {fontFamily: 'serif'}}},
+      };
+      const fromSource = defineTheme({...childInput, extends: source});
+      const fromBuilt = defineTheme({...childInput, extends: builtTheme});
+      expect(generateThemeCSS(fromBuilt)).toEqual(generateThemeCSS(fromSource));
+      expect(fromBuilt.__adaptationRules[0].components).toBeUndefined();
+      expect(fromBuilt.components.text['type:display-2'].fontFamily).toBe(
+        'serif',
+      );
+    },
+  );
+
   it('resolves a plain object whose only input-only field is adaptations', async () => {
     const project = path.join(tmpDir, 'project');
     const themesDir = path.join(project, 'themes');

package/clients/cli/commands/build-theme.mjs

@@ -33,7 +33,7 @@ import {fileURLToPath} from 'node:url';
 import {spawn} from 'node:child_process';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, section, text, list, code} from '../formatters/index.mjs';
+import {emit, section, text, list, records, code} from '../formatters/index.mjs';
 import {logger} from '../../../api/logger.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
@@ -229,47 +229,6 @@ function printThemeList(themes) {
   );
 }
 
-/**
- * Render the targets as one greppable line each, under an aligned header. A
- * `records()` block would be five lines per target — over a thousand for the
- * full surface, which is the view this command exists to make readable.
- * @param {import('../../../api/theme/theme.type.mjs').ThemeTargetEntry[]} targets
- * @returns {string}
- */
-function formatTargetsTable(targets) {
-  const rows = targets.map(t => ({
-    key: t.deprecatedFor
-      ? `${t.key} [deprecated; use ${t.deprecatedFor}]`
-      : t.key,
-    component: t.component,
-    props: t.props.join(', ') || '-',
-    states: t.states.join(', ') || '-',
-  }));
-  const head = {
-    key: 'key',
-    component: 'component',
-    props: 'props',
-    states: 'states',
-  };
-  const width = (/** @type {'key'|'component'|'props'} */ field) =>
-    [head, ...rows].reduce((max, r) => Math.max(max, r[field].length), 0);
-  const w = {
-    key: width('key'),
-    component: width('component'),
-    props: width('props'),
-  };
-  const line = (/** @type {typeof head} */ r) =>
-    [
-      r.key.padEnd(w.key),
-      r.component.padEnd(w.component),
-      r.props.padEnd(w.props),
-      r.states,
-    ]
-      .join('  ')
-      .trimEnd();
-  return [line(head), ...rows.map(line)].join('\n');
-}
-
 /**
  * @param {import('commander').Command} program
  */
@@ -811,9 +770,16 @@ export function registerTheme(program) {
       emit(
         section(
           'Theming targets',
-          `${targets.length} across ${componentCount} component${componentCount === 1 ? '' : 's'}`,
+          `${targets.length} across ${componentCount} component${componentCount === 1 ? '' : 's'}\n(key - component - props - states - className - deprecatedFor)`,
         ),
-        text(formatTargetsTable(targets)),
+        records(targets, {
+          fields: ['key', 'component', 'props', 'states', 'className', 'deprecatedFor'],
+          layout: 'inline',
+          format: {
+            deprecatedFor: (/** @type {string|null} */ v) =>
+              v ? `deprecated; use ${v}` : '',
+          },
+        }),
         text(
           [
             `Each key goes under \`components\` in defineTheme; it paints \`.astryx-<key>\`.`,

package/clients/cli/commands/build.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'build',
   displayName: 'astryx build',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary:
     'Build a page: composition kit for an idea, or the workflow playbook (no args)',
   description:

package/clients/cli/commands/component.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'component',
   displayName: 'astryx component',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'List components or print component docs',
   description:
     'Resolves a component by name across core and integration packages and prints ' +

package/clients/cli/commands/discover.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'discover',
   displayName: 'astryx discover',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Discover external packages and components',
   description:
     'Explores components contributed by configured external packages and integrations. ' +

package/clients/cli/commands/docs.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'docs',
   displayName: 'astryx docs',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Print reference docs',
   description:
     'Reads the reference docs: with no topic it lists every topic; a topic prints that ' +