@astryxdesign/cli 0.0.0-bootstrap.0 → 0.0.15

package/src/lib/hook-discovery.mjs

@@ -0,0 +1,228 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Hook discovery — find, list, and resolve Astryx hooks
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {levenshteinDistance} from './string-utils.mjs';
+
+const SKIP_DIRS = new Set(['utils', '__tests__', 'node_modules']);
+
+// Matches the top-level `category: 'categoryName'` field in a hook .doc.mjs file.
+const CATEGORY_RE = /(?:^|\n) {0,4}category:\s*['"]([^'"]+)['"]/;
+
+/**
+ * Read the `category` field from a hook's .doc.mjs file (synchronous).
+ */
+function readHookMeta(docPath) {
+  try {
+    const content = fs.readFileSync(docPath, 'utf-8');
+    const categoryMatch = CATEGORY_RE.exec(content);
+    return {
+      category: categoryMatch ? categoryMatch[1].charAt(0).toUpperCase() + categoryMatch[1].slice(1) : null,
+    };
+  } catch {
+    return {category: null};
+  }
+}
+
+/**
+ * Extract the hook name from a doc filename.
+ * e.g. 'useFocusTrap.doc.mjs' → 'useFocusTrap'
+ */
+function hookNameFromFile(fileName) {
+  return fileName.replace('.doc.mjs', '');
+}
+
+/**
+ * Discover all hooks that have .doc.mjs files.
+ * Returns Record<category, hookName[]> similar to discoverComponents.
+ * Categories from HookDoc.category: focus, layout, animation, interaction, data, media, streaming
+ * Hooks without a category go in 'Other'.
+ */
+export function discoverHooks(coreDir) {
+  const srcDir = path.join(coreDir, 'src');
+  const hooksDir = path.join(srcDir, 'hooks');
+
+  /** @type {Map<string, string>} hookName → category */
+  const hookCategories = new Map();
+
+  // 1. Scan src/hooks/ for *.doc.mjs files
+  if (fs.existsSync(hooksDir)) {
+    const entries = fs.readdirSync(hooksDir, {withFileTypes: true});
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (!entry.name.endsWith('.doc.mjs')) continue;
+      const hookName = hookNameFromFile(entry.name);
+      const docPath = path.join(hooksDir, entry.name);
+      const {category} = readHookMeta(docPath);
+      hookCategories.set(hookName, category || 'Other');
+    }
+  }
+
+  // 2. Scan ALL component directories for files matching use*.doc.mjs
+  if (fs.existsSync(srcDir)) {
+    const topEntries = fs.readdirSync(srcDir, {withFileTypes: true});
+    for (const entry of topEntries) {
+      if (!entry.isDirectory() || SKIP_DIRS.has(entry.name) || entry.name === 'hooks') continue;
+      const dirPath = path.join(srcDir, entry.name);
+      scanDirForHookDocs(dirPath, hookCategories);
+    }
+  }
+
+  // 3. Group by category, sorted alphabetically
+  /** @type {Map<string, string[]>} */
+  const groups = new Map();
+  for (const [hookName, category] of hookCategories) {
+    if (!groups.has(category)) groups.set(category, []);
+    groups.get(category).push(hookName);
+  }
+
+  // Sort members within each group
+  for (const members of groups.values()) {
+    members.sort();
+  }
+
+  // Sort groups alphabetically, but 'Other' goes last
+  const sortedEntries = Array.from(groups.entries()).sort((a, b) => {
+    if (a[0] === 'Other') return 1;
+    if (b[0] === 'Other') return -1;
+    return a[0].localeCompare(b[0]);
+  });
+
+  /** @type {Record<string, string[]>} */
+  const ordered = {};
+  for (const [key, values] of sortedEntries) {
+    ordered[key] = values;
+  }
+
+  return ordered;
+}
+
+/**
+ * Recursively scan a directory for use*.doc.mjs files.
+ */
+function scanDirForHookDocs(dirPath, hookCategories) {
+  if (!fs.existsSync(dirPath)) return;
+  const entries = fs.readdirSync(dirPath, {withFileTypes: true});
+  for (const entry of entries) {
+    if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
+      scanDirForHookDocs(path.join(dirPath, entry.name), hookCategories);
+    } else if (
+      entry.isFile() &&
+      entry.name.startsWith('use') &&
+      entry.name.endsWith('.doc.mjs')
+    ) {
+      const hookName = hookNameFromFile(entry.name);
+      if (!hookCategories.has(hookName)) {
+        const docPath = path.join(dirPath, entry.name);
+        const {category} = readHookMeta(docPath);
+        hookCategories.set(hookName, category || 'Other');
+      }
+    }
+  }
+}
+
+/**
+ * Find the .doc.mjs file for a hook by name.
+ * Searches hooks/ directory and component directories.
+ * Matches both exact name and with 'use' prefix stripped.
+ *
+ * @param {string} coreDir
+ * @param {string} name - Hook name (e.g. 'useMediaQuery', 'MediaQuery', 'mediaquery')
+ * @returns {string|null} Path to the .doc.mjs file, or null
+ */
+export function findHookDoc(coreDir, name) {
+  const srcDir = path.join(coreDir, 'src');
+  const hooksDir = path.join(srcDir, 'hooks');
+
+  // Normalize: ensure we have both 'useFoo' and 'Foo' variants
+  const normalized = name.replace(/^use/, '');
+  const withUse = 'use' + normalized.charAt(0).toUpperCase() + normalized.slice(1);
+  const candidates = [name, withUse, 'use' + normalized];
+
+  // Deduplicate candidates
+  const uniqueCandidates = [...new Set(candidates)];
+
+  // 1. Check src/hooks/{name}.doc.mjs first
+  for (const candidate of uniqueCandidates) {
+    const direct = path.join(hooksDir, `${candidate}.doc.mjs`);
+    if (fs.existsSync(direct)) return direct;
+  }
+
+  // 2. Case-insensitive search in hooks directory
+  if (fs.existsSync(hooksDir)) {
+    const entries = fs.readdirSync(hooksDir);
+    for (const entry of entries) {
+      if (!entry.endsWith('.doc.mjs')) continue;
+      const hookName = hookNameFromFile(entry);
+      if (hookName.toLowerCase() === name.toLowerCase() ||
+          hookName.toLowerCase() === withUse.toLowerCase()) {
+        return path.join(hooksDir, entry);
+      }
+    }
+  }
+
+  // 3. Check all component dirs for {name}.doc.mjs or use{Name}.doc.mjs
+  if (fs.existsSync(srcDir)) {
+    const topEntries = fs.readdirSync(srcDir, {withFileTypes: true});
+    for (const entry of topEntries) {
+      if (!entry.isDirectory() || SKIP_DIRS.has(entry.name) || entry.name === 'hooks') continue;
+      const found = searchDirForHookDoc(path.join(srcDir, entry.name), uniqueCandidates);
+      if (found) return found;
+    }
+  }
+
+  // 4. Fuzzy fallback: levenshtein distance on discovered hooks
+  const allHooks = discoverHooks(coreDir);
+  const allNames = Object.values(allHooks).flat();
+  const needle = name.toLowerCase();
+
+  let bestMatch = null;
+  let bestDist = Infinity;
+  for (const hookName of allNames) {
+    const dist = levenshteinDistance(needle, hookName.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      bestMatch = hookName;
+    }
+  }
+
+  if (bestMatch && bestDist <= 3) {
+    return findHookDoc(coreDir, bestMatch);
+  }
+
+  return null;
+}
+
+/**
+ * Recursively search a directory for a hook doc matching any of the candidate names.
+ */
+function searchDirForHookDoc(dirPath, candidates) {
+  if (!fs.existsSync(dirPath)) return null;
+  const entries = fs.readdirSync(dirPath, {withFileTypes: true});
+  for (const entry of entries) {
+    if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
+      const found = searchDirForHookDoc(path.join(dirPath, entry.name), candidates);
+      if (found) return found;
+    } else if (entry.isFile() && entry.name.endsWith('.doc.mjs')) {
+      const hookName = hookNameFromFile(entry.name);
+      for (const candidate of candidates) {
+        if (hookName === candidate || hookName.toLowerCase() === candidate.toLowerCase()) {
+          return path.join(dirPath, entry.name);
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Get all discovered hook names as a flat array (for fuzzy matching).
+ */
+export function getAllHookNames(coreDir) {
+  const hooks = discoverHooks(coreDir);
+  return Object.values(hooks).flat();
+}

package/src/lib/hook-format.mjs

@@ -0,0 +1,247 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Hook doc formatting — render HookDoc objects to text
+ *
+ * Mirrors component-format.mjs conventions:
+ * - Full: markdown with ## sections, tables, best practices
+ * - Compact: markdown with import block, params table, abbreviated practices
+ * - Brief: signature line with import hint, description, key params
+ */
+
+import {discoverHooks, findHookDoc} from './hook-discovery.mjs';
+import {loadDocs} from './component-loader.mjs';
+
+/**
+ * Build a signature string from hook docs.
+ * e.g. 'useFocusTrap(options: UseFocusTrapOptions): { containerRef, focusFirst }'
+ */
+function buildSignature(docs) {
+  const name = docs.name;
+
+  // Build params string — only top-level params (skip options.foo nested params)
+  const topParams = (docs.params || []).filter(p => !p.name.includes('.'));
+  const paramStr = topParams
+    .map(p => {
+      const opt = p.required ? '' : '?';
+      return `${p.name}${opt}: ${p.type}`;
+    })
+    .join(', ');
+
+  // Build return type
+  const returns = docs.returns || [];
+  let returnStr;
+  if (returns.length === 0) {
+    returnStr = 'void';
+  } else if (returns.length === 1 && returns[0].name === 'value') {
+    returnStr = returns[0].type;
+  } else {
+    returnStr = `{ ${returns.map(r => r.name).join(', ')} }`;
+  }
+
+  return `${name}(${paramStr}): ${returnStr}`;
+}
+
+/**
+ * Format a parameters table (matches component props table style).
+ */
+function formatParamsTable(params) {
+  if (!params || params.length === 0) return '';
+  const lines = [];
+  lines.push('| Param | Type | Default | Description |');
+  lines.push('|-------|------|---------|-------------|');
+  for (const p of params) {
+    const def = p.default ? `\`${p.default}\`` : '\u2014';
+    const req = p.required ? ' **(required)**' : '';
+    lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Format a returns table.
+ */
+function formatReturnsTable(returns) {
+  if (!returns || returns.length === 0) return '';
+  const lines = [];
+  lines.push('| Field | Type | Description |');
+  lines.push('|-------|------|-------------|');
+  for (const r of returns) {
+    lines.push(`| \`${r.name}\` | \`${r.type}\` | ${r.description} |`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Format full hook docs (default mode).
+ * Matches component formatFull structure:
+ *   # Name, description, anatomy→params, best practices, props→params+returns, theming→related
+ */
+export function formatHookFull(docs) {
+  const sections = [];
+
+  sections.push(`# ${docs.name}\n`);
+
+  const desc = docs.usage?.description || '';
+  if (desc) sections.push(desc + '\n');
+
+  // Best Practices (same position as component format)
+  if (docs.usage?.bestPractices?.length) {
+    sections.push('## Best Practices\n');
+    for (const bp of docs.usage.bestPractices) {
+      const badge = bp.guidance ? '**Do:**' : "**Don't:**";
+      sections.push(`- ${badge} ${bp.description}`);
+    }
+    sections.push('');
+  }
+
+  // Parameters (analogous to ## Props)
+  if (docs.params?.length) {
+    sections.push('## Parameters\n');
+    sections.push(formatParamsTable(docs.params) + '\n');
+  }
+
+  // Returns (hook-specific, no component equivalent)
+  if (docs.returns?.length) {
+    sections.push('## Returns\n');
+    sections.push(formatReturnsTable(docs.returns) + '\n');
+  }
+
+  return sections.join('\n');
+}
+
+/**
+ * Format compact hook docs for LLM consumption.
+ * Matches component formatCompact structure:
+ *   # Name, description, ## Import, ## Best Practices, ## Parameters, ## Returns
+ */
+export function formatHookCompact(docs, importPath) {
+  const sections = [];
+
+  sections.push(`# ${docs.name}\n`);
+
+  // Description
+  const desc = docs.usage?.description || '';
+  if (desc) sections.push(desc + '\n');
+
+  // Import block (matches component compact)
+  const imp = importPath || docs.importPath;
+  if (imp) {
+    sections.push('## Import\n');
+    sections.push(`\`\`\`tsx\nimport { ${docs.name} } from '${imp}';\n\`\`\`\n`);
+  }
+
+  // Best Practices (matches component compact)
+  if (docs.usage?.bestPractices?.length) {
+    sections.push('## Best Practices\n');
+    for (const bp of docs.usage.bestPractices) {
+      const badge = bp.guidance ? '**Do:**' : "**Don't:**";
+      sections.push(`- ${badge} ${bp.description}`);
+    }
+    sections.push('');
+  }
+
+  // Parameters (matches ## Props in component compact)
+  if (docs.params?.length) {
+    sections.push('## Parameters\n');
+    sections.push(formatParamsTable(docs.params) + '\n');
+  }
+
+  // Returns
+  if (docs.returns?.length) {
+    sections.push('## Returns\n');
+    sections.push(formatReturnsTable(docs.returns) + '\n');
+  }
+
+  // Related components (compact footer)
+  const relatedParts = [];
+  if (docs.relatedComponents?.length) {
+    relatedParts.push(`Components: ${docs.relatedComponents.join(', ')}`);
+  }
+  if (docs.relatedHooks?.length) {
+    relatedParts.push(`Hooks: ${docs.relatedHooks.join(', ')}`);
+  }
+  if (relatedParts.length) {
+    sections.push('## Related\n');
+    for (const part of relatedParts) sections.push(part);
+    sections.push('');
+  }
+
+  return sections.join('\n');
+}
+
+/**
+ * Format a brief, LLM-optimized hook summary.
+ * Matches component formatBrief conventions:
+ *   signature  ← from 'import/path'
+ *   description
+ *   key params
+ */
+export function formatHookBrief(docs) {
+  const output = [];
+
+  // Signature line with import hint (matches component brief)
+  const sig = buildSignature(docs);
+  const imp = docs.importPath;
+  output.push(imp ? `${sig}  \u2190 from '${imp}'` : sig);
+
+  // Description (shortened, matches component brief)
+  const desc = docs.usage?.description || '';
+  if (desc) {
+    const shortDesc = desc.length > 80 ? desc.slice(0, 77) + '...' : desc;
+    output.push(`  ${shortDesc}`);
+  }
+
+  // Related components (compact)
+  if (docs.relatedComponents?.length) {
+    output.push(`  Related: ${docs.relatedComponents.join(', ')}`);
+  }
+
+  // Key params (matches component brief 'prop · prop' line)
+  const paramNames = (docs.params || [])
+    .filter(p => !p.name.includes('.'))
+    .map(p => p.required ? `${p.name}: ${p.type.split('|')[0].trim()}` : p.name);
+  if (paramNames.length > 0) {
+    output.push(`  ${paramNames.join(' \u00b7 ')}`);
+  }
+
+  return output.join('\n') + '\n';
+}
+
+/**
+ * Format brief summaries for ALL hooks in one output.
+ * Matches component formatBriefAll: group headers with ##.
+ */
+export async function formatHookBriefAll(coreDir) {
+  const hooks = discoverHooks(coreDir);
+  const output = [];
+
+  for (const [category, hookNames] of Object.entries(hooks)) {
+    output.push(`## ${category}\n`);
+    for (const hookName of hookNames) {
+      const docPath = findHookDoc(coreDir, hookName);
+      if (docPath) {
+        try {
+          const docs = await loadDocs(docPath);
+          output.push(formatHookBrief(docs));
+        } catch {
+          output.push(`${hookName}\n  (no docs)\n`);
+        }
+      } else {
+        output.push(`${hookName}\n  (no docs)\n`);
+      }
+    }
+  }
+
+  return output.join('\n');
+}
+
+/**
+ * Format only the parameters table (matches component formatProps).
+ */
+export function formatHookParams(docs) {
+  if (docs.params?.length) {
+    return `## Parameters\n\n${formatParamsTable(docs.params)}\n`;
+  }
+  return `No parameters documentation found for ${docs.name}.\n`;
+}

package/src/lib/json-contract.test.mjs

@@ -0,0 +1,168 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit + subprocess tests for the "JSON is always JSON" contract.
+ *
+ * Guarantees under test:
+ *   1. Every JSON envelope carries apiVersion (success and error).
+ *   2. humanLog/humanWarn are suppressed in JSON mode (stdout discipline).
+ *   3. jsonOut supports optional meta as a sibling of data.
+ *   4. An uncaught throw in --json mode becomes a JSON error envelope
+ *      (the bin error boundary), never a raw stack trace.
+ */
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {
+  API_VERSION,
+  jsonOut,
+  jsonError,
+  toErrorEnvelope,
+  setJsonMode,
+  isJsonMode,
+  humanLog,
+  humanWarn,
+} from './json.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI = path.resolve(__dirname, '..', '..', 'bin', 'astryx.mjs');
+
+function runCli(args) {
+  return spawnSync(process.execPath, [CLI, ...args], {
+    encoding: 'utf8',
+    timeout: 20_000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: {...process.env, FORCE_COLOR: '0', CI: ''},
+  });
+}
+
+describe('json envelope shape', () => {
+  let logs;
+  beforeEach(() => {
+    logs = [];
+    vi.spyOn(console, 'log').mockImplementation((...a) => logs.push(a.join(' ')));
+    setJsonMode(false);
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+    setJsonMode(false);
+  });
+
+  it('jsonOut stamps apiVersion + type + data', () => {
+    jsonOut('docs.list', [{name: 'Button'}]);
+    const env = JSON.parse(logs[0]);
+    expect(env.apiVersion).toBe(API_VERSION);
+    expect(env.type).toBe('docs.list');
+    expect(env.data).toEqual([{name: 'Button'}]);
+    expect('meta' in env).toBe(false);
+  });
+
+  it('jsonOut attaches optional meta as a sibling of data', () => {
+    jsonOut('discover.list', [], {configured: false});
+    const env = JSON.parse(logs[0]);
+    expect(env.meta).toEqual({configured: false});
+    expect(env.data).toEqual([]);
+  });
+
+  it('toErrorEnvelope produces { apiVersion, error, code } from string or Error', () => {
+    expect(toErrorEnvelope('boom')).toEqual({
+      apiVersion: API_VERSION,
+      error: 'boom',
+      code: 'ERR_UNKNOWN',
+    });
+    expect(toErrorEnvelope(new Error('kaboom'))).toEqual({
+      apiVersion: API_VERSION,
+      error: 'kaboom',
+      code: 'ERR_UNKNOWN',
+    });
+  });
+
+  it('toErrorEnvelope honors an explicit code argument', () => {
+    expect(toErrorEnvelope('boom', undefined, 'ERR_UNKNOWN_COMPONENT')).toEqual({
+      apiVersion: API_VERSION,
+      error: 'boom',
+      code: 'ERR_UNKNOWN_COMPONENT',
+    });
+  });
+
+  it('toErrorEnvelope reads a code carried on a thrown Error', () => {
+    const err = Object.assign(new Error('kaboom'), {code: 'ERR_NO_DOC'});
+    expect(toErrorEnvelope(err)).toEqual({
+      apiVersion: API_VERSION,
+      error: 'kaboom',
+      code: 'ERR_NO_DOC',
+    });
+  });
+
+  it('toErrorEnvelope includes suggestions when present', () => {
+    const env = toErrorEnvelope('x', [{name: 'Button', reason: 'close match'}]);
+    expect(env.suggestions).toEqual([{name: 'Button', reason: 'close match'}]);
+  });
+});
+
+describe('stdout discipline (humanLog / humanWarn)', () => {
+  let logs, errs;
+  beforeEach(() => {
+    logs = [];
+    errs = [];
+    vi.spyOn(console, 'log').mockImplementation((...a) => logs.push(a.join(' ')));
+    vi.spyOn(console, 'error').mockImplementation((...a) => errs.push(a.join(' ')));
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+    setJsonMode(false);
+  });
+
+  it('humanLog prints when NOT in json mode', () => {
+    setJsonMode(false);
+    expect(isJsonMode()).toBe(false);
+    humanLog('hello');
+    expect(logs).toEqual(['hello']);
+  });
+
+  it('humanLog is a no-op in json mode', () => {
+    setJsonMode(true);
+    expect(isJsonMode()).toBe(true);
+    humanLog('should not appear');
+    expect(logs).toEqual([]);
+  });
+
+  it('humanWarn is a no-op in json mode', () => {
+    setJsonMode(true);
+    humanWarn('warning');
+    expect(errs).toEqual([]);
+  });
+});
+
+describe('contract: every --json emission is valid JSON with apiVersion', () => {
+  it('astryx --version --json', () => {
+    const r = runCli(['--version', '--json']);
+    const env = JSON.parse(r.stdout);
+    expect(env.apiVersion).toBe(API_VERSION);
+    expect(env.type).toBe('version');
+  });
+
+  it('astryx --json (bare) help envelope', () => {
+    const r = runCli(['--json']);
+    const env = JSON.parse(r.stdout);
+    expect(env.apiVersion).toBe(API_VERSION);
+    expect(env.type).toBe('help');
+  });
+
+  it('unsupported command error envelope carries apiVersion', () => {
+    const r = runCli(['init', '--json', '--all']);
+    const env = JSON.parse(r.stdout);
+    expect(env.apiVersion).toBe(API_VERSION);
+    expect(env.error).toMatch(/init/);
+  });
+
+  it('supported command (discover) emits clean JSON, no human chatter leak', () => {
+    const r = runCli(['discover', '--json']);
+    // Whole stdout must parse — nothing printed before/after the envelope.
+    const env = JSON.parse(r.stdout);
+    expect(env.apiVersion).toBe(API_VERSION);
+    expect(env.type).toBe('discover.list');
+  });
+});