@astryxdesign/cli 0.4.7 → 0.5.0-canary.009bcb3

package/foundation/discovery/hook-discovery.test.mjs

@@ -5,16 +5,25 @@
  * @astryxdesign/core source tree plus throwaway fixtures. Pins the
  * category grouping, the missing-src guarding (which differs from
  * component-discovery), and the Levenshtein fuzzy-fallback in findHookDoc.
+ * Also gates the index against the hooks barrel: every hook the built barrel
+ * exports must be discoverable, so adding a hook without a doc fails here.
  */
 
 import {describe, it, expect, afterAll} from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import {fileURLToPath} from 'node:url';
-import {discoverHooks, findHookDoc, getAllHookNames} from './hook-discovery.mjs';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {
+  discoverHooks,
+  findHookDoc,
+  getAllHookNames,
+} from './hook-discovery.mjs';
 
-const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const REPO = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../..',
+);
 const CORE = path.join(REPO, 'packages', 'core');
 const SLOW = 30_000;
 
@@ -29,35 +38,53 @@ afterAll(() => {
 });
 
 describe('discoverHooks (real core)', () => {
-  it('discovers real hooks grouped by category', () => {
-    const hooks = discoverHooks(CORE);
-    const cats = Object.keys(hooks);
-    expect(cats.length).toBeGreaterThan(1);
-    if (cats.includes('Other')) expect(cats[cats.length - 1]).toBe('Other');
-    const nonOther = cats.filter(c => c !== 'Other');
-    expect([...nonOther].sort((a, b) => a.localeCompare(b))).toEqual(nonOther);
-    for (const members of Object.values(hooks)) {
-      expect([...members].sort()).toEqual(members);
-    }
-    const all = getAllHookNames(CORE);
-    expect(all).toContain('useMediaQuery');
-    expect(all.length).toBeGreaterThan(10);
-  }, SLOW);
+  it(
+    'discovers real hooks grouped by category',
+    () => {
+      const hooks = discoverHooks(CORE);
+      const cats = Object.keys(hooks);
+      expect(cats.length).toBeGreaterThan(1);
+      if (cats.includes('Other')) expect(cats[cats.length - 1]).toBe('Other');
+      const nonOther = cats.filter(c => c !== 'Other');
+      expect([...nonOther].sort((a, b) => a.localeCompare(b))).toEqual(
+        nonOther,
+      );
+      for (const members of Object.values(hooks)) {
+        expect([...members].sort()).toEqual(members);
+      }
+      const all = getAllHookNames(CORE);
+      expect(all).toContain('useMediaQuery');
+      expect(all.length).toBeGreaterThan(10);
+    },
+    SLOW,
+  );
 
   it('capitalizes categories and buckets category-less docs into Other', () => {
     const core = mkTmp('as-hd-cat-');
     const hooksDir = path.join(core, 'src', 'hooks');
     fs.mkdirSync(hooksDir, {recursive: true});
-    fs.writeFileSync(path.join(hooksDir, 'useThing.doc.mjs'), "export default {\n  category: 'layout',\n};\n");
-    fs.writeFileSync(path.join(hooksDir, 'useOrphan.doc.mjs'), 'export default {};\n');
-    expect(discoverHooks(core)).toEqual({Layout: ['useThing'], Other: ['useOrphan']});
+    fs.writeFileSync(
+      path.join(hooksDir, 'useThing.doc.mjs'),
+      "export default {\n  category: 'layout',\n};\n",
+    );
+    fs.writeFileSync(
+      path.join(hooksDir, 'useOrphan.doc.mjs'),
+      'export default {};\n',
+    );
+    expect(discoverHooks(core)).toEqual({
+      Layout: ['useThing'],
+      Other: ['useOrphan'],
+    });
   });
 
   it('discovers use*.doc.mjs colocated in component directories', () => {
     const core = mkTmp('as-hd-colo-');
     const compDir = path.join(core, 'src', 'Resizable');
     fs.mkdirSync(compDir, {recursive: true});
-    fs.writeFileSync(path.join(compDir, 'useResizable.doc.mjs'), "export default {\n  category: 'interaction',\n};\n");
+    fs.writeFileSync(
+      path.join(compDir, 'useResizable.doc.mjs'),
+      "export default {\n  category: 'interaction',\n};\n",
+    );
     expect(discoverHooks(core)).toEqual({Interaction: ['useResizable']});
   });
 
@@ -69,13 +96,25 @@ describe('discoverHooks (real core)', () => {
 });
 
 describe('findHookDoc (real core)', () => {
-  it('resolves an exact hook name', () => {
-    expect(findHookDoc(CORE, 'useMediaQuery')).toMatch(/useMediaQuery\.doc\.mjs$/);
-  }, SLOW);
+  it(
+    'resolves an exact hook name',
+    () => {
+      expect(findHookDoc(CORE, 'useMediaQuery')).toMatch(
+        /useMediaQuery\.doc\.mjs$/,
+      );
+    },
+    SLOW,
+  );
 
-  it('resolves a bare (use-prefix-stripped, case-insensitive) name', () => {
-    expect(findHookDoc(CORE, 'mediaquery')).toMatch(/useMediaQuery\.doc\.mjs$/);
-  }, SLOW);
+  it(
+    'resolves a bare (use-prefix-stripped, case-insensitive) name',
+    () => {
+      expect(findHookDoc(CORE, 'mediaquery')).toMatch(
+        /useMediaQuery\.doc\.mjs$/,
+      );
+    },
+    SLOW,
+  );
 
   it('returns null when src/ is missing (guarded)', () => {
     const core = mkTmp('as-fhd-nosrc-');
@@ -84,14 +123,94 @@ describe('findHookDoc (real core)', () => {
 });
 
 describe('findHookDoc fuzzy Levenshtein fallback (pinned current behavior)', () => {
-  it('auto-resolves a typo within edit distance 3', () => {
-    expect(getAllHookNames(CORE)).not.toContain('useLayers');
-    expect(getAllHookNames(CORE)).toContain('useLayer');
-    expect(findHookDoc(CORE, 'useLayers')).toMatch(/useLayer\.doc\.mjs$/);
-  }, SLOW);
-
-  it('returns null when the closest hook is farther than distance 3', () => {
-    expect(findHookDoc(CORE, 'useZzzzzz')).toBeNull();
-    expect(findHookDoc(CORE, 'zzzzzzzzzz')).toBeNull();
-  }, SLOW);
+  it(
+    'auto-resolves a typo within edit distance 3',
+    () => {
+      expect(getAllHookNames(CORE)).not.toContain('useLayers');
+      expect(getAllHookNames(CORE)).toContain('useLayer');
+      expect(findHookDoc(CORE, 'useLayers')).toMatch(/useLayer\.doc\.mjs$/);
+    },
+    SLOW,
+  );
+
+  it(
+    'returns null when the closest hook is farther than distance 3',
+    () => {
+      expect(findHookDoc(CORE, 'useZzzzzz')).toBeNull();
+      expect(findHookDoc(CORE, 'zzzzzzzzzz')).toBeNull();
+    },
+    SLOW,
+  );
+});
+
+/**
+ * The set of hooks a barrel actually exports, read from the module itself
+ * rather than from its text. Importing is what makes this a derivation: it sees
+ * `export * from` re-exports, aliases and any other form the language allows,
+ * and type-only exports have already been erased. A regex over the source can
+ * only see the spellings someone thought to write a pattern for.
+ * @param {string} entry absolute path to a built ESM barrel
+ */
+async function exportedHookNames(entry) {
+  const mod = await import(pathToFileURL(entry).href);
+  return new Set(Object.keys(mod).filter(name => /^use[A-Z]/.test(name)));
+}
+
+describe('core hooks barrel coverage (real core)', () => {
+  // Discovery is filesystem-driven: a hook is only reachable from `astryx hook`
+  // and `astryx search` if it ships a .doc.mjs. Nothing about adding a hook
+  // forces one, so the index silently goes stale; seven exported hooks,
+  // useAnnounce among them, were invisible until this check existed.
+  //
+  // Only the standalone hooks in src/hooks/ are in scope. Hooks that belong to
+  // a component's API (useDialog, useToast, ...) are documented in that
+  // component's directory and deliberately never enter this barrel, so their
+  // absence from it is not a defect.
+  it(
+    'every hook exported from the barrel has a doc and is discoverable',
+    async () => {
+      // The built barrel, not src/hooks/index.ts: this suite runs in the `node`
+      // project, which has no StyleX babel transform, so importing core's TS
+      // source throws on the first stylex.defineVars it reaches. dist is present
+      // because the project's globalSetup builds core before any worker forks.
+      const exported = await exportedHookNames(
+        path.join(CORE, 'dist', 'hooks', 'index.js'),
+      );
+      expect(exported.size).toBeGreaterThan(10);
+
+      const discovered = new Set(getAllHookNames(CORE));
+      const missing = [...exported]
+        .filter(name => !discovered.has(name))
+        .sort();
+      if (missing.length) {
+        throw new Error(
+          `${missing.length} exported hook(s) are missing from the CLI hook index, so ` +
+            `\`astryx hook <name>\` and \`astryx search\` deny they exist. Add a ` +
+            `<hook>.doc.mjs next to each hook in packages/core/src/hooks/:\n  ${missing.join('\n  ')}`,
+        );
+      }
+      expect(missing).toEqual([]);
+    },
+    SLOW,
+  );
+
+  it('sees hooks re-exported with `export *`, which a regex over `export {…}` misses', async () => {
+    const dir = mkTmp('as-hd-star-');
+    fs.writeFileSync(
+      path.join(dir, 'useStarred.mjs'),
+      'export function useStarred() {}\n',
+    );
+    fs.writeFileSync(
+      path.join(dir, 'useNamed.mjs'),
+      'export function useNamed() {}\n',
+    );
+    fs.writeFileSync(
+      path.join(dir, 'index.mjs'),
+      "export * from './useStarred.mjs';\nexport {useNamed} from './useNamed.mjs';\n",
+    );
+
+    expect(await exportedHookNames(path.join(dir, 'index.mjs'))).toEqual(
+      new Set(['useStarred', 'useNamed']),
+    );
+  });
 });

package/foundation/discovery/theming-targets.d.mts

@@ -0,0 +1,86 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Every theming target declared under a core `src` directory, sorted by key
+ * then component. A key can appear more than once: a shared sub-element (the
+ * radio indicator, say) is documented by every component that renders it.
+ *
+ * Unreadable docs are skipped rather than fatal — a single malformed doc must
+ * not take out theme validation or the listing.
+ *
+ * @param {string} coreSrc - absolute path to `<core>/src`
+ * @returns {Promise<ThemingTarget[]>}
+ */
+export function collectThemingTargets(coreSrc: string): Promise<ThemingTarget[]>;
+/**
+ * One public custom property a theme may set on a component's target.
+ * @typedef {object} ThemingVar
+ * @property {string} name - the custom property, e.g. `--tree-list-indent`
+ * @property {string} component - the component whose doc declares it
+ * @property {string} dir - absolute path to the directory the doc lives in
+ * @property {string} default - the documented default value
+ */
+/**
+ * Every PUBLIC theming var declared under a core `src` directory, sorted by
+ * name. Private `--_*` vars are a component's own plumbing, not a theme's to
+ * set, so they are not enumerated here.
+ *
+ * @param {string} coreSrc - absolute path to `<core>/src`
+ * @returns {Promise<ThemingVar[]>}
+ */
+export function collectThemingVars(coreSrc: string): Promise<ThemingVar[]>;
+/**
+ * Collapse the enumeration into the `{key: [props and states]}` map theme
+ * validation checks override keys against — both are legal override keys, so
+ * they share one list.
+ * @param {ThemingTarget[]} targets
+ * @returns {Record<string, string[]>}
+ */
+export function targetsByKey(targets: ThemingTarget[]): Record<string, string[]>;
+/**
+ * One theming target, as a theme author has to write it.
+ */
+export type ThemingTarget = {
+    /**
+     * - the `defineTheme` `components` key (class minus the `astryx-` prefix)
+     */
+    key: string;
+    /**
+     * - the stable class the component renders
+     */
+    className: string;
+    /**
+     * - the component whose doc declares it
+     */
+    component: string;
+    /**
+     * - visual props the target reflects (`variant:value` keys)
+     */
+    props: string[];
+    /**
+     * - runtime states the target reflects (bare-name keys)
+     */
+    states: string[];
+};
+/**
+ * One public custom property a theme may set on a component's target.
+ */
+export type ThemingVar = {
+    /**
+     * - the custom property, e.g. `--tree-list-indent`
+     */
+    name: string;
+    /**
+     * - the component whose doc declares it
+     */
+    component: string;
+    /**
+     * - absolute path to the directory the doc lives in
+     */
+    dir: string;
+    /**
+     * - the documented default value
+     */
+    default: string;
+};

package/foundation/discovery/theming-targets.mjs

@@ -0,0 +1,202 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The one enumeration of component theming targets.
+ *
+ * @input  a core `src` directory
+ * @output every `theming.targets` entry authored in a component `.doc.mjs`,
+ *         flattened into the `defineTheme` component key a theme author writes
+ * @position packages/cli/foundation/discovery — shared by `theme targets` (the
+ *           listing) and `theme build` (override validation). Both read the
+ *           component docs, which are the source of truth `astryx component
+ *           <Name>` prints; nothing here is a second registry, so the list a
+ *           theme author can enumerate and the set the compiler accepts cannot
+ *           drift from the components or from each other.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {loadComponentDoc} from './component-loader.mjs';
+
+const SKIP_DIRS = new Set(['node_modules', '__tests__']);
+
+/**
+ * One theming target, as a theme author has to write it.
+ * @typedef {object} ThemingTarget
+ * @property {string} key - the `defineTheme` `components` key (class minus the `astryx-` prefix)
+ * @property {string} className - the stable class the component renders
+ * @property {string} component - the component whose doc declares it
+ * @property {string[]} props - visual props the target reflects (`variant:value` keys)
+ * @property {string[]} states - runtime states the target reflects (bare-name keys)
+ */
+
+/**
+ * Strip the namespace prefix to get the `defineTheme` key for a class name.
+ *
+ * Keep the `astryx-` literal in sync with packages/core/src/naming.ts
+ * (NAMESPACE / classPrefix), the same way component-format.mjs does.
+ * <!-- SYNC: packages/core/src/naming.ts (namespace prefix source of truth) -->
+ * @param {string} className
+ * @returns {string}
+ */
+function targetKey(className) {
+  return className.replace(/^astryx-/, '');
+}
+
+/**
+ * Every theming target declared under a core `src` directory, sorted by key
+ * then component. A key can appear more than once: a shared sub-element (the
+ * radio indicator, say) is documented by every component that renders it.
+ *
+ * Unreadable docs are skipped rather than fatal — a single malformed doc must
+ * not take out theme validation or the listing.
+ *
+ * @param {string} coreSrc - absolute path to `<core>/src`
+ * @returns {Promise<ThemingTarget[]>}
+ */
+export async function collectThemingTargets(coreSrc) {
+  if (!coreSrc || !fs.existsSync(coreSrc)) return [];
+
+  /** @type {ThemingTarget[]} */
+  const targets = [];
+
+  /** @param {string} dir */
+  async function scan(dir) {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await scan(full);
+        continue;
+      }
+      if (!entry.name.endsWith('.doc.mjs')) continue;
+
+      /** @type {any} */
+      let doc;
+      try {
+        doc = await loadComponentDoc(full);
+      } catch {
+        continue;
+      }
+
+      const component =
+        typeof doc?.name === 'string' && doc.name
+          ? doc.name
+          : path.basename(path.dirname(full));
+
+      for (const target of doc?.theming?.targets || []) {
+        const className = target?.className;
+        if (typeof className !== 'string') continue;
+        const key = targetKey(className);
+        if (!key) continue;
+        targets.push({
+          key,
+          className,
+          component,
+          props: stringList(target.visualProps),
+          states: stringList(target.states),
+        });
+      }
+    }
+  }
+
+  await scan(coreSrc);
+
+  targets.sort(
+    (a, b) => a.key.localeCompare(b.key) || a.component.localeCompare(b.component),
+  );
+  return targets;
+}
+
+/**
+ * One public custom property a theme may set on a component's target.
+ * @typedef {object} ThemingVar
+ * @property {string} name - the custom property, e.g. `--tree-list-indent`
+ * @property {string} component - the component whose doc declares it
+ * @property {string} dir - absolute path to the directory the doc lives in
+ * @property {string} default - the documented default value
+ */
+
+/**
+ * Every PUBLIC theming var declared under a core `src` directory, sorted by
+ * name. Private `--_*` vars are a component's own plumbing, not a theme's to
+ * set, so they are not enumerated here.
+ *
+ * @param {string} coreSrc - absolute path to `<core>/src`
+ * @returns {Promise<ThemingVar[]>}
+ */
+export async function collectThemingVars(coreSrc) {
+  if (!coreSrc || !fs.existsSync(coreSrc)) return [];
+
+  /** @type {Map<string, ThemingVar>} */
+  const vars = new Map();
+
+  /** @param {string} dir */
+  async function scan(dir) {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await scan(full);
+        continue;
+      }
+      if (!entry.name.endsWith('.doc.mjs')) continue;
+
+      /** @type {any} */
+      let doc;
+      try {
+        doc = await loadComponentDoc(full);
+      } catch {
+        continue;
+      }
+
+      const component =
+        typeof doc?.name === 'string' && doc.name
+          ? doc.name
+          : path.basename(path.dirname(full));
+
+      for (const entryVar of doc?.theming?.vars || []) {
+        const name = entryVar?.name;
+        if (typeof name !== 'string') continue;
+        if (entryVar.private === true || name.startsWith('--_')) continue;
+        if (vars.has(name)) continue;
+        vars.set(name, {
+          name,
+          component,
+          dir: path.dirname(full),
+          default: typeof entryVar.default === 'string' ? entryVar.default : '',
+        });
+      }
+    }
+  }
+
+  await scan(coreSrc);
+
+  return [...vars.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Collapse the enumeration into the `{key: [props and states]}` map theme
+ * validation checks override keys against — both are legal override keys, so
+ * they share one list.
+ * @param {ThemingTarget[]} targets
+ * @returns {Record<string, string[]>}
+ */
+export function targetsByKey(targets) {
+  /** @type {Record<string, string[]>} */
+  const byKey = {};
+  for (const t of targets) {
+    byKey[t.key] = [...new Set([...(byKey[t.key] || []), ...t.props, ...t.states])];
+  }
+  return byKey;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+function stringList(value) {
+  return Array.isArray(value)
+    ? value.filter((/** @type {unknown} */ v) => typeof v === 'string')
+    : [];
+}