@astryxdesign/cli 0.1.2 → 0.1.3

package/src/commands/gap-report.mjs

@@ -1,464 +0,0 @@
-// 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 = await 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 = await 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 = await 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 = await 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 = await 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 = await 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

@@ -1,168 +0,0 @@
-// 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');
-    await expect(loadGapReportConfig()).resolves.toMatchObject({
-      enabled: false,
-    });
-
-    // createGapReport must return null and never invoke gh.
-    const result = await 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');
-    await expect(mod.loadGapReportConfig()).resolves.toMatchObject({
-      enabled: false,
-    });
-
-    process.env.ASTRYX_GAP_REPORT = '0';
-    vi.resetModules();
-    mod = await import('../utils/github.mjs');
-    await expect(mod.loadGapReportConfig()).resolves.toMatchObject({
-      enabled: 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 = await 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 = await buildGapReportPreview({
-      component: 'Button',
-      category: 'other',
-      intention: 'x',
-    });
-    expect(preview.mode).toBe('disabled');
-    expect(preview.enabled).toBe(false);
-  });
-});