@astryxdesign/cli 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/commands/gap-report.mjs

@@ -0,0 +1,456 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file gap-report command — File a gap report for missing Astryx capabilities
+ *
+ * Interactive and non-interactive modes for reporting gaps in the design system.
+ * Creates GitHub issues with the `gap-report` label.
+ *
+ * Includes `gap-report setup` subcommand for configuring gap report delivery.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as p from '@clack/prompts';
+import {
+  buildGapReportPreview,
+  checkGhCli,
+  createGapReport,
+  loadGapReportConfig,
+  GAP_CATEGORIES,
+} from '../utils/github.mjs';
+import {getRunPrefix} from '../utils/package-manager.mjs';
+import {jsonOut, jsonError, humanLog} from '../lib/json.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../lib/error-codes.mjs';
+
+/**
+ * Decide whether we're in a context safe to actually file a report.
+ *
+ * Returns true ONLY when the user has explicitly opted in via --commit, OR
+ * we're in an interactive TTY session AND --dry-run was not requested.
+ *
+ * Defaults are intentionally conservative: in CI, when piped, when --json is
+ * set, or when neither --commit nor a TTY is present, we dry-run.
+ */
+export function shouldActuallyFile({
+  commit = false,
+  dryRun = false,
+  json = false,
+  isTTY = process.stdout.isTTY,
+} = {}) {
+  if (dryRun) return false;
+  if (commit) return true;
+  if (json) return false;
+  if (!isTTY) return false;
+  // Interactive TTY without --commit: caller must show a confirmation prompt.
+  return true;
+}
+
+/**
+ * Render a human-readable preview of the gap report that would be filed.
+ */
+export function formatPreview(preview) {
+  const lines = [];
+  if (preview.mode === 'github') {
+    lines.push(`Would file GitHub issue on ${preview.repo}:`);
+  } else if (preview.mode === 'custom') {
+    lines.push(`Would invoke custom command: ${preview.command}`);
+  } else {
+    lines.push('Gap reporting is disabled (no action would be taken).');
+    return lines.join('\n');
+  }
+  lines.push('');
+  lines.push(`  Title: ${preview.title}`);
+  lines.push('');
+  lines.push('  Body:');
+  for (const ln of preview.body.split('\n')) {
+    lines.push(`    ${ln}`);
+  }
+  lines.push('');
+  lines.push('  Labels: gap-report');
+  return lines.join('\n');
+}
+
+function isCancel(value) {
+  if (p.isCancel(value)) {
+    p.cancel('Gap report cancelled.');
+    process.exit(0);
+  }
+  return value;
+}
+
+/**
+ * Update or insert the gapReport key in astryx.config.mjs.
+ * Preserves existing keys (e.g. theme).
+ */
+function writeGapReportConfig(targetDir, gapReportValue) {
+  const configPath = path.join(targetDir, 'astryx.config.mjs');
+
+  if (fs.existsSync(configPath)) {
+    let content = fs.readFileSync(configPath, 'utf-8');
+
+    // Replace existing gapReport key (handles both `false` and `{ command: '...' }`)
+    if (/gapReport\s*:/.test(content)) {
+      content = content.replace(
+        /gapReport\s*:\s*(?:\{[^}]*\}|false|true)\s*,?/s,
+        `gapReport: ${gapReportValue},`,
+      );
+    } else {
+      // Insert before the closing `};`
+      content = content.replace(
+        /(\n};?\s*)$/,
+        `\n  gapReport: ${gapReportValue},$1`,
+      );
+    }
+
+    fs.writeFileSync(configPath, content);
+  } else {
+    const content = `/**
+ * Astryx Configuration
+ * Generated by \`astryx gap-report setup\`
+ */
+export default {
+  gapReport: ${gapReportValue},
+};
+`;
+    fs.writeFileSync(configPath, content);
+  }
+
+  return configPath;
+}
+
+export function registerGapReport(program) {
+  const gapCmd = program
+    .command('gap-report')
+    .description('Report a gap in the design system');
+
+  // --- setup subcommand ---
+  gapCmd
+    .command('setup')
+    .description('Configure where gap reports are sent')
+    .action(async () => {
+      p.intro('Gap report setup');
+
+      const config = loadGapReportConfig();
+      const currentMode = !config.enabled
+        ? 'disabled'
+        : config.command
+          ? 'custom'
+          : 'github';
+
+      const mode = isCancel(
+        await p.select({
+          message: `How should gap reports be delivered? (current: ${currentMode})`,
+          options: [
+            {
+              value: 'github',
+              label: 'GitHub Issues',
+              hint: 'Creates issues on facebookexperimental/xds (requires gh CLI)',
+            },
+            {
+              value: 'custom',
+              label: 'Custom command',
+              hint: 'Run a script that receives the report as JSON on stdin',
+            },
+            {
+              value: 'disabled',
+              label: 'Disabled',
+              hint: 'Turn off gap reporting entirely',
+            },
+          ],
+        }),
+      );
+
+      let configValue;
+      const targetDir = process.cwd();
+
+      if (mode === 'disabled') {
+        configValue = 'false';
+        writeGapReportConfig(targetDir, configValue);
+        p.log.success('Gap reporting disabled.');
+      } else if (mode === 'custom') {
+        const command = isCancel(
+          await p.text({
+            message: 'Path to script:',
+            placeholder: './scripts/report-gap.sh',
+            validate: val => {
+              if (!val.trim()) return 'Script path is required';
+            },
+          }),
+        );
+
+        configValue = `{ command: '${command.trim()}' }`;
+        writeGapReportConfig(targetDir, configValue);
+
+        p.log.success(`Gap reports will be sent to: ${command.trim()}`);
+        p.note(
+          'Your script receives JSON on stdin with these fields:\n' +
+            '  component, category, categoryLabel, intention,\n' +
+            '  detail, source, timestamp\n\n' +
+            'Anything printed to stdout is shown to the user.',
+          'Script contract',
+        );
+      } else {
+        // GitHub mode — remove gapReport key or set to default
+        const configPath = path.join(targetDir, 'astryx.config.mjs');
+        if (fs.existsSync(configPath)) {
+          let content = fs.readFileSync(configPath, 'utf-8');
+          // Remove the gapReport line entirely to use default
+          content = content.replace(
+            /\s*gapReport\s*:\s*(?:\{[^}]*\}|false|true)\s*,?/s,
+            '',
+          );
+          fs.writeFileSync(configPath, content);
+        }
+
+        if (!checkGhCli()) {
+          p.log.warning(
+            'gh CLI is not installed or not authenticated.\n' +
+              'Install from https://cli.github.com and run `gh auth login`.',
+          );
+        } else {
+          p.log.success(
+            'Gap reports will create GitHub issues on facebookexperimental/xds.',
+          );
+        }
+      }
+
+      p.outro('Configuration saved to astryx.config.mjs');
+    });
+
+  // --- main gap-report command ---
+  gapCmd
+    .option('--component <name>', 'Component name')
+    .option('--category <category>', 'Gap category')
+    .option('--reason <reason>', 'What capability was missing')
+    .option('--list-categories', 'List valid gap categories')
+    .option(
+      '--dry-run',
+      'Print the issue that would be filed without contacting GitHub. Default in CI / non-TTY / --json mode.',
+    )
+    .option(
+      '--commit',
+      'Actually file the issue. Required in non-interactive mode (CI, piped, --json).',
+    )
+    .addHelpText(
+      'after',
+      '\nSafety:\n' +
+        '  Set ASTRYX_GAP_REPORT=off to disable gap reporting entirely.\n' +
+        '  In non-interactive mode (CI, piped stdout, --json), gap-report is\n' +
+        '  dry-run by default. Pass --commit to actually file an issue.\n' +
+        '  In interactive mode, you will always be shown a confirmation prompt.\n',
+    )
+    .action(async options => {
+      const json = program.opts().json || false;
+
+      if (options.listCategories) {
+        if (json) return jsonOut('gap-report.categories', GAP_CATEGORIES);
+        for (const cat of GAP_CATEGORIES) {
+          humanLog(`  ${cat.value.padEnd(20)} ${cat.label}`);
+        }
+        return;
+      }
+
+      const config = loadGapReportConfig();
+      if (!config.enabled) {
+        if (json) return jsonError('Gap reporting is disabled', undefined, ERROR_CODES.ERR_GAP_REPORT_FAILED);
+        humanLog(
+          `Gap reporting is disabled (ASTRYX_GAP_REPORT=off or astryx.config.mjs).\n` +
+            `Run \`${getRunPrefix()} astryx gap-report setup\` to configure.`,
+        );
+        return;
+      }
+
+      // We only need gh available when we'd actually file. For dry-run, skip
+      // the gh check so users can preview output in CI without `gh` installed.
+      const willFile = shouldActuallyFile({
+        commit: options.commit,
+        dryRun: options.dryRun,
+        json,
+      });
+
+      if (willFile && !config.command && !checkGhCli()) {
+        const msg =
+          'GitHub CLI (gh) is not installed or not authenticated. ' +
+          'Install it from https://cli.github.com and run `gh auth login`. ' +
+          `Or run \`${getRunPrefix()} astryx gap-report setup\` to configure a custom command.`;
+        cliError(msg, {code: ERROR_CODES.ERR_GH_CLI});
+        return;
+      }
+
+      const isNonInteractive =
+        options.component && options.category && options.reason;
+
+      if (isNonInteractive) {
+        // Non-interactive mode for LLM/script use
+        const validCategory = GAP_CATEGORIES.find(
+          c => c.value === options.category,
+        );
+        if (!validCategory) {
+          cliError(
+            `Invalid category "${options.category}". Valid: ${GAP_CATEGORIES.map(c => c.value).join(', ')}`,
+            {code: ERROR_CODES.ERR_UNKNOWN_CATEGORY},
+          );
+          return;
+        }
+
+        const preview = buildGapReportPreview({
+          component: options.component,
+          category: options.category,
+          intention: options.reason,
+          source: 'cli',
+        });
+
+        if (!willFile) {
+          // DRY-RUN: print what would be filed and exit cleanly.
+          if (json) {
+            return jsonOut('gap-report.dryRun', {
+              dryRun: true,
+              wouldFile: preview.mode !== 'disabled',
+              mode: preview.mode,
+              title: preview.title,
+              body: preview.body,
+              repo: preview.repo,
+              command: preview.command || null,
+              hint:
+                'Re-run with --commit to actually file. ' +
+                'Default is dry-run in non-interactive contexts.',
+            });
+          }
+          humanLog(formatPreview(preview));
+          humanLog(
+            '\n[dry-run] Nothing was filed. Re-run with --commit to file this report.',
+          );
+          return;
+        }
+
+        try {
+          const url = createGapReport({
+            component: options.component,
+            category: options.category,
+            intention: options.reason,
+            source: 'cli',
+          });
+          if (json)
+            return jsonOut('gap-report.file', {
+              filed: !!url,
+              url: url || null,
+            });
+          if (url) {
+            humanLog(`\n✓ Gap report filed: ${url}\n`);
+          } else {
+            humanLog('\nGap reporting is disabled via configuration.\n');
+          }
+        } catch (err) {
+          cliError(`Filing gap report failed: ${err.message}`, {code: ERROR_CODES.ERR_GAP_REPORT_FAILED});
+          return;
+        }
+        return;
+      }
+
+      // --json without --component/--category/--reason can't go interactive —
+      // emit a structured error explaining the required flags.
+      if (json) {
+        return jsonError(
+          'gap-report --json requires --component, --category, and --reason. ' +
+            'Run with --list-categories to see valid categories.',
+          undefined,
+          ERROR_CODES.ERR_INVALID_ARGUMENT,
+        );
+      }
+
+      // Interactive mode
+      p.intro('Report a gap');
+
+      const component = isCancel(
+        await p.text({
+          message: 'Which component is this about?',
+          placeholder: 'e.g. Button, Table, or "general"',
+          validate: val => {
+            if (!val.trim()) return 'Component name is required';
+          },
+        }),
+      );
+
+      const category = isCancel(
+        await p.select({
+          message: 'What kind of gap is this?',
+          options: GAP_CATEGORIES,
+        }),
+      );
+
+      const intention = isCancel(
+        await p.text({
+          message: 'What were you trying to achieve?',
+          placeholder:
+            'e.g. "Need a compact variant for use in dense data tables"',
+          validate: val => {
+            if (!val.trim()) return 'Please describe what you were trying to do';
+          },
+        }),
+      );
+
+      const detail = isCancel(
+        await p.text({
+          message: 'Any additional context? (optional)',
+          placeholder: 'Press Enter to skip',
+        }),
+      );
+
+      const previewArgs = {
+        component: component.trim(),
+        category,
+        intention: intention.trim(),
+        detail: detail?.trim() || undefined,
+        source: 'interactive',
+      };
+
+      const preview = buildGapReportPreview(previewArgs);
+
+      // Always show the user exactly what would be filed before sending.
+      p.note(
+        `${preview.mode === 'github' ? `Repo: ${preview.repo}` : `Custom command: ${preview.command}`}\n\n` +
+          `Title:\n  ${preview.title}\n\n` +
+          `Body:\n${preview.body
+            .split('\n')
+            .map(l => `  ${l}`)
+            .join('\n')}`,
+        'Preview — this is exactly what will be filed',
+      );
+
+      if (options.dryRun) {
+        p.outro('[dry-run] Nothing filed.');
+        return;
+      }
+
+      const confirm = isCancel(
+        await p.confirm({
+          message: 'File this gap report now?',
+          initialValue: false,
+        }),
+      );
+
+      if (!confirm) {
+        p.outro('Cancelled — nothing was filed.');
+        return;
+      }
+
+      const s = p.spinner();
+      s.start('Filing gap report');
+
+      try {
+        const url = createGapReport(previewArgs);
+        s.stop(url ? 'Gap report filed' : 'Gap reporting is disabled');
+        if (url) {
+          p.log.success(url);
+        }
+      } catch (err) {
+        s.stop('Failed to file gap report');
+        p.log.error(err.message);
+        process.exit(1);
+      }
+
+      p.outro('Thanks for the feedback!');
+    });
+}

package/src/commands/gap-report.test.mjs

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Tests for gap-report safety gates: dry-run-by-default in non-interactive
+ * mode, --commit required to actually file, --no-report suppression in swizzle,
+ * and ASTRYX_GAP_REPORT=off honored everywhere.
+ *
+ * Regression cases for issues #2370 and #2371: real gap-report issues filed
+ * unintentionally in CI/non-TTY runs.
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {shouldActuallyFile, formatPreview} from './gap-report.mjs';
+
+describe('shouldActuallyFile', () => {
+  it('returns false in non-TTY mode by default (dry-run by default in CI)', () => {
+    expect(shouldActuallyFile({isTTY: false})).toBe(false);
+  });
+
+  it('returns false when --json is set, even with TTY', () => {
+    expect(shouldActuallyFile({isTTY: true, json: true})).toBe(false);
+  });
+
+  it('returns false when --dry-run is explicitly set', () => {
+    expect(shouldActuallyFile({isTTY: true, dryRun: true})).toBe(false);
+  });
+
+  it('returns true in TTY mode without dry-run/json (interactive prompts will gate)', () => {
+    expect(shouldActuallyFile({isTTY: true})).toBe(true);
+  });
+
+  it('returns true with --commit even in non-TTY mode', () => {
+    expect(shouldActuallyFile({isTTY: false, commit: true})).toBe(true);
+  });
+
+  it('--commit overrides --json being set', () => {
+    expect(shouldActuallyFile({isTTY: false, commit: true, json: true})).toBe(
+      true,
+    );
+  });
+
+  it('--dry-run wins over --commit (safety)', () => {
+    expect(
+      shouldActuallyFile({isTTY: true, commit: true, dryRun: true}),
+    ).toBe(false);
+  });
+});
+
+describe('formatPreview', () => {
+  it('renders a github-mode preview with title, body, and repo', () => {
+    const out = formatPreview({
+      mode: 'github',
+      repo: 'facebookexperimental/xds',
+      title: '[gap] Button: missing compact variant',
+      body: '## User Intention\n\nNeed a compact variant',
+    });
+    expect(out).toContain('Would file GitHub issue on facebookexperimental/xds');
+    expect(out).toContain('[gap] Button');
+    expect(out).toContain('Need a compact variant');
+    expect(out).toContain('Labels: gap-report');
+  });
+
+  it('renders disabled mode without filing instructions', () => {
+    const out = formatPreview({mode: 'disabled'});
+    expect(out).toContain('Gap reporting is disabled');
+    expect(out).not.toContain('Would file');
+  });
+
+  it('renders custom-command mode', () => {
+    const out = formatPreview({
+      mode: 'custom',
+      command: './scripts/report.sh',
+      title: 't',
+      body: 'b',
+    });
+    expect(out).toContain('Would invoke custom command: ./scripts/report.sh');
+  });
+});
+
+describe('ASTRYX_GAP_REPORT=off env var', () => {
+  let originalEnv;
+  beforeEach(() => {
+    originalEnv = process.env.ASTRYX_GAP_REPORT;
+  });
+  afterEach(() => {
+    if (originalEnv === undefined) delete process.env.ASTRYX_GAP_REPORT;
+    else process.env.ASTRYX_GAP_REPORT = originalEnv;
+    vi.resetModules();
+  });
+
+  it('disables gap reporting when set to "off"', async () => {
+    process.env.ASTRYX_GAP_REPORT = 'off';
+    vi.resetModules();
+    const {loadGapReportConfig, createGapReport} = await import(
+      '../utils/github.mjs'
+    );
+    expect(loadGapReportConfig().enabled).toBe(false);
+
+    // createGapReport must return null and never invoke gh.
+    const result = createGapReport({
+      component: 'Button',
+      category: 'other',
+      intention: 'test',
+    });
+    expect(result).toBeNull();
+  });
+
+  it('also accepts "false" and "0" as disable values', async () => {
+    process.env.ASTRYX_GAP_REPORT = 'false';
+    vi.resetModules();
+    let mod = await import('../utils/github.mjs');
+    expect(mod.loadGapReportConfig().enabled).toBe(false);
+
+    process.env.ASTRYX_GAP_REPORT = '0';
+    vi.resetModules();
+    mod = await import('../utils/github.mjs');
+    expect(mod.loadGapReportConfig().enabled).toBe(false);
+  });
+});
+
+describe('buildGapReportPreview', () => {
+  let originalEnv;
+  beforeEach(() => {
+    originalEnv = process.env.ASTRYX_GAP_REPORT;
+    // Force github mode (default) for these tests.
+    delete process.env.ASTRYX_GAP_REPORT;
+  });
+  afterEach(() => {
+    if (originalEnv === undefined) delete process.env.ASTRYX_GAP_REPORT;
+    else process.env.ASTRYX_GAP_REPORT = originalEnv;
+  });
+
+  it('renders title and body without invoking gh', async () => {
+    vi.resetModules();
+    const {buildGapReportPreview} = await import('../utils/github.mjs');
+    const preview = buildGapReportPreview({
+      component: 'Button',
+      category: 'missing_variant',
+      intention: 'Need compact variant for tables',
+    });
+    expect(preview.mode).toBe('github');
+    expect(preview.enabled).toBe(true);
+    expect(preview.title).toBe(
+      '[gap] Button: Need compact variant for tables',
+    );
+    expect(preview.body).toContain('| **Component** | Button |');
+    expect(preview.body).toContain('Need compact variant for tables');
+    expect(preview.repo).toBe('facebookexperimental/xds');
+  });
+
+  it('reports disabled mode when env var is off', async () => {
+    process.env.ASTRYX_GAP_REPORT = 'off';
+    vi.resetModules();
+    const {buildGapReportPreview} = await import('../utils/github.mjs');
+    const preview = buildGapReportPreview({
+      component: 'Button',
+      category: 'other',
+      intention: 'x',
+    });
+    expect(preview.mode).toBe('disabled');
+    expect(preview.enabled).toBe(false);
+  });
+});