Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
18.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file `debug: event => {}` — the whole feature.
 *
 * A project sets one function in `astryx.config` and receives every command
 * run. That function's parameter is a published contract, so these cover what
 * it promises: the handler is called with a complete, scrubbed event, and a
 * handler that misbehaves can never affect the command that triggered it.
 *
 * @position packages/cli/foundation/debug — behaviour coverage
 */

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 {
  begin,
  finish,
  currentEvent,
  setCommand,
  setArgs,
  setOptions,
  setGlobalOptions,
  setOutcome,
  setEventHandler,
  setIntegrationEventHandlers,
  noteConfigGateSkipped,
  recordEnvelope,
  recordHelp,
  resetRecorder,
  MAX_CAPTURED_OUTPUT,
} from './recorder.mjs';
import {parseDebugEvent} from '../../authoring/debug/parse.mjs';
import {parseConfig} from '../../authoring/config/parse.mjs';

/** Collect every event a run delivers. */
function collect() {
  /** @type {any[]} */
  const seen = [];
  setEventHandler(e => seen.push(e));
  return seen;
}

beforeEach(() => {
  resetRecorder();
});

afterEach(() => {
  resetRecorder();
});

describe('delivery', () => {
  it('hands each run to the function', () => {
    const seen = collect();
    begin({argv: ['docs', 'tokens']});
    setCommand('docs');
    expect(finish({exitCode: 0})).toBe(true);

    expect(seen).toHaveLength(1);
    expect(seen[0].command).toBe('docs');
  });

  it('does nothing at all when no function is configured', () => {
    begin({argv: ['docs']});
    setCommand('docs');
    expect(finish({exitCode: 0})).toBe(false);
  });

  it('delivers at most once', () => {
    const seen = collect();
    begin({argv: []});
    expect(finish({exitCode: 0})).toBe(true);
    expect(finish({exitCode: 0})).toBe(false);
    expect(seen).toHaveLength(1);
  });

  it('accepts a function registered after the run started', () => {
    begin({argv: ['docs']});
    setCommand('docs');
    const seen = collect();
    finish({exitCode: 0});
    expect(seen).toHaveLength(1);
  });

  it('delivers one event per invocation', () => {
    /** @type {any[]} */
    const seen = [];
    for (const name of ['docs', 'component', 'hook']) {
      resetRecorder();
      setEventHandler(e => seen.push(e));
      begin({argv: [name]});
      setCommand(name);
      finish({exitCode: 0});
    }
    expect(seen.map(e => e.command)).toEqual(['docs', 'component', 'hook']);
  });
});

describe('what the event carries', () => {
  it('carries the whole invocation', () => {
    const seen = collect();
    begin({argv: ['theme', 'build', 'x.ts', '--check'], cliVersion: '9.9.9'});
    setCommand('theme build');
    setArgs({file: 'x.ts'});
    setOptions({check: true}, {check: 'cli'});
    setGlobalOptions({json: true, detail: 'full'});
    recordEnvelope('theme.build');
    finish({exitCode: 0});

    const [e] = seen;
    expect(e.command).toBe('theme build');
    expect(e.commandPath).toEqual(['theme', 'build']);
    expect(e.args).toEqual({file: 'x.ts'});
    expect(e.options).toEqual({check: true});
    expect(e.optionSources).toEqual({check: 'cli'});
    expect(e.globalOptions).toEqual({json: true, detail: 'full'});
    expect(e.output.jsonMode).toBe(true);
    expect(e.output.envelopeTypes).toEqual(['theme.build']);
    expect(e.env.cliVersion).toBe('9.9.9');
    expect(e.outcome).toBe('ok');
    expect(typeof e.durationMs).toBe('number');
  });

  it('satisfies the published contract', () => {
    const seen = collect();
    begin({argv: ['docs']});
    setCommand('docs');
    finish({exitCode: 0});
    expect(() => parseDebugEvent(seen[0])).not.toThrow();
  });

  it('drops an option source outside the published set', () => {
    const seen = collect();
    begin({argv: []});
    setOptions({a: 1, b: 2}, {a: 'cli', b: 'from-the-future'});
    finish({exitCode: 0});
    expect(seen[0].optionSources).toEqual({a: 'cli'});
  });

  it('flags a help invocation', () => {
    const seen = collect();
    begin({argv: []});
    recordHelp();
    finish({exitCode: 0});
    expect(seen[0].output.helpDisplayed).toBe(true);
  });
});

describe('outcomes', () => {
  it('keeps the first terminal outcome', () => {
    const seen = collect();
    begin({argv: []});
    setOutcome('error', {exitCode: 1, code: 'ERR_FIRST'});
    setOutcome('fatal', {exitCode: 70, code: 'ERR_SECOND'});
    finish();
    expect(seen[0].outcome).toBe('error');
    expect(seen[0].error.code).toBe('ERR_FIRST');
  });

  it('captures a thrown error', () => {
    const seen = collect();
    begin({argv: []});
    setOutcome('fatal', {exitCode: 1, error: new TypeError('bad thing')});
    finish();
    expect(seen[0].error.name).toBe('TypeError');
    expect(seen[0].error.message).toBe('bad thing');
  });

  it('infers failure from a non-zero exit', () => {
    const seen = collect();
    begin({argv: []});
    finish({exitCode: 1});
    expect(seen[0].outcome).toBe('error');
  });

  it('marks an exit that bypassed the error path', () => {
    const seen = collect();
    begin({argv: []});
    finish({exitCode: 1}); // no cliError, no setOutcome
    expect(seen[0].error.code).toBe('ERR_UNCLASSIFIED_EXIT');
  });

  it('leaves a clean exit with no error', () => {
    const seen = collect();
    begin({argv: []});
    finish({exitCode: 0});
    expect(seen[0].outcome).toBe('ok');
    expect(seen[0].error).toBe(null);
  });
});

describe('scrubbing', () => {
  it('scrubs by default', () => {
    const seen = collect();
    begin({argv: ['--token=ghp_abcdefghijklmnopqrstuvwxyz01']});
    setOptions({out: 'ghp_abcdefghijklmnopqrstuvwxyz01'});
    finish({exitCode: 0});
    expect(seen[0].redacted).toBe(true);
    expect(JSON.stringify(seen[0])).not.toContain('ghp_abcdef');
  });

  it('clamps an oversized value instead of dropping the run', () => {
    const seen = collect();
    begin({argv: []});
    setCommand('docs');
    setOptions({blob: 'x'.repeat(500_000)});
    finish({exitCode: 0});
    expect(seen[0].command).toBe('docs');
    expect(String(seen[0].options.blob)).toContain('chars]');
  });

  it('scrubs the value after a sensitive flag in argv', () => {
    const seen = collect();
    begin({argv: ['docs', '--token', 'hunter2SECRETVALUE']});
    finish({exitCode: 0});
    expect(JSON.stringify(seen[0].argv)).not.toContain('hunter2SECRETVALUE');
    expect(seen[0].argv[1]).toBe('--token');
  });

  it('leaves an ordinary flag and its value in argv alone', () => {
    const seen = collect();
    begin({argv: ['theme', 'build', '--out', 'dist']});
    finish({exitCode: 0});
    expect(seen[0].argv).toEqual(['theme', 'build', '--out', 'dist']);
  });
});

describe('what a run with no handler costs', () => {
  it('does not probe the environment while collecting', () => {
    begin({argv: ['--version']});
    expect(currentEvent()?.env).toBe(null);
  });

  it('fills the environment in by the time a handler sees the event', () => {
    const seen = collect();
    begin({argv: [], cliVersion: '9.9.9'});
    finish({exitCode: 0});
    expect(seen[0].env).toBeTruthy();
    expect(seen[0].env.cliVersion).toBe('9.9.9');
    expect(seen[0].env.nodeVersion).toBe(process.versions.node);
  });
});

describe('a broken handler cannot break the CLI', () => {
  it('swallows a handler that throws', () => {
    setEventHandler(() => {
      throw new Error('handler blew up');
    });
    begin({argv: []});
    setCommand('docs');
    expect(() => finish({exitCode: 0})).not.toThrow();
  });

  it('ignores a handler that is not a function', () => {
    setEventHandler(/** @type {any} */ ('not a function'));
    begin({argv: []});
    expect(finish({exitCode: 0})).toBe(false);
  });

  it('cannot corrupt anything by mutating the event it was given', () => {
    /** @type {any[]} */
    const seen = [];
    setEventHandler(e => {
      seen.push(e);
      e.command = 'MUTATED';
    });
    begin({argv: []});
    setCommand('docs');
    finish({exitCode: 0});
    expect(seen[0].command).toBe('MUTATED');
  });

  it('survives a circular structure in the captured options', () => {
    collect();
    begin({argv: []});
    /** @type {any} */
    const circular = {name: 'loop'};
    circular.self = circular;
    setOptions({circular});
    expect(() => finish({exitCode: 0})).not.toThrow();
  });

  it('is dropped by resetRecorder so it cannot leak between runs', () => {
    const handler = vi.fn();
    setEventHandler(handler);
    resetRecorder();
    begin({argv: []});
    finish({exitCode: 0});
    expect(handler).not.toHaveBeenCalled();
  });

  it('ignores lifecycle calls made before begin', () => {
    expect(() => {
      setCommand('docs');
      setArgs({a: 1});
      setOptions({b: 2});
      setOutcome('error', {exitCode: 1});
      recordEnvelope('x');
      recordHelp();
    }).not.toThrow();
  });

  it('cannot change the exit code by calling process.exit', () => {
    const exits = [];
    const realExit = process.exit;
    process.exit = /** @type {any} */ (code => exits.push(code));
    try {
      setEventHandler(() => {
        process.exit(7);
      });
      begin({argv: []});
      setCommand('docs');
      finish({exitCode: 0});
    } finally {
      process.exit = realExit;
    }
    expect(exits).toEqual([]);
  });

  it('cannot change the exit code by assigning process.exitCode', () => {
    const before = process.exitCode;
    setEventHandler(() => {
      process.exitCode = 42;
    });
    begin({argv: []});
    finish({exitCode: 0});
    expect(process.exitCode).toBe(before);
  });

  it('sends what it prints to stderr, because stdout belongs to the command', () => {
    const out = [];
    const err = [];
    const realOut = process.stdout.write;
    const realErr = process.stderr.write;
    process.stdout.write = /** @type {any} */ (
      c => (out.push(String(c)), true)
    );
    process.stderr.write = /** @type {any} */ (
      c => (err.push(String(c)), true)
    );
    try {
      setEventHandler(() => {
        process.stdout.write('handler diagnostics\n');
      });
      begin({argv: []});
      finish({exitCode: 0});
    } finally {
      process.stdout.write = realOut;
      process.stderr.write = realErr;
    }
    expect(out.join('')).not.toContain('handler diagnostics');
    expect(err.join('')).toContain('handler diagnostics');
  });

  it('puts the real writers back after the handler returns', () => {
    const before = {out: process.stdout.write, err: process.stderr.write};
    setEventHandler(() => {
      process.stdout.write('x');
    });
    begin({argv: []});
    finish({exitCode: 0});
    expect(process.stdout.write).toBe(before.out);
    expect(process.stderr.write).toBe(before.err);
  });
});

describe('the config gate, when it guesses wrong', () => {
  function withStderr(fn) {
    const lines = [];
    const real = process.stderr.write;
    process.stderr.write = /** @type {any} */ (
      c => (lines.push(String(c)), true)
    );
    try {
      fn();
    } finally {
      process.stderr.write = real;
    }
    return lines.join('');
  }

  it('says so when a handler turns up after the gate declined', () => {
    const said = withStderr(() => {
      begin({argv: []});
      noteConfigGateSkipped();
      setEventHandler(() => {});
    });
    expect(said).toMatch(/a debug handler was registered/);
  });

  it('says so when the handler that turns up came from an integration', () => {
    const said = withStderr(() => {
      begin({argv: []});
      noteConfigGateSkipped();
      setIntegrationEventHandlers([() => {}]);
    });
    expect(said).toMatch(/a debug handler was registered/);
  });

  it('stays quiet when the gate was right', () => {
    const said = withStderr(() => {
      begin({argv: []});
      noteConfigGateSkipped();
    });
    expect(said).toBe('');
  });

  it.each([undefined, null, 'not a function'])(
    'stays quiet when what arrives is %s rather than a handler',
    value => {
      const said = withStderr(() => {
        begin({argv: []});
        noteConfigGateSkipped();
        setEventHandler(/** @type {any} */ (value));
      });
      expect(said).toBe('');
    },
  );

  it('stays quiet when the gate let the config through', () => {
    const said = withStderr(() => {
      begin({argv: []});
      setEventHandler(() => {});
    });
    expect(said).toBe('');
  });

  it('says it once, not once per lifecycle call', () => {
    const said = withStderr(() => {
      begin({argv: []});
      noteConfigGateSkipped();
      setEventHandler(() => {});
      setEventHandler(() => {});
    });
    expect(said.match(/a debug handler was registered/g)).toHaveLength(1);
  });

  it('stays quiet under --json, where stderr is still not the place', () => {
    const said = withStderr(() => {
      begin({argv: ['--json']});
      setGlobalOptions({json: true});
      noteConfigGateSkipped();
      setEventHandler(() => {});
    });
    expect(said).toBe('');
  });
});

describe('config: the whole surface is one function', () => {
  it('accepts a function', () => {
    expect(parseConfig({debug: () => {}}).debug).toBeTypeOf('function');
  });

  it.each([
    ['a string', 'nope'],
    ['a number', 42],
    ['an object', {onEvent: () => {}}],
    ['an array', [() => {}]],
    ['null', null],
    ['true', true],
  ])('rejects %s', (_label, value) => {
    expect(() => parseConfig({debug: value})).toThrow(/debug/);
  });

  it('treats a missing debug value as no opt-in', () => {
    expect(parseConfig({}).debug).toBeUndefined();
  });
});

describe('captured output — what the CLI answered', () => {
  const say = (out = '', err = '') => {
    if (out) process.stdout.write(`${out}\n`);
    if (err) process.stderr.write(`${err}\n`);
  };

  it('captures stdout', () => {
    const seen = collect();
    begin({argv: ['docs']});
    say('the answer');
    finish({exitCode: 0});
    expect(seen[0].output.stdout).toContain('the answer');
  });

  it('captures stderr separately', () => {
    const seen = collect();
    begin({argv: ['docs']});
    say('', 'Error: nope');
    finish({exitCode: 1});
    expect(seen[0].output.stderr).toContain('Error: nope');
    expect(seen[0].output.stdout).toBe('');
  });

  it('records true byte counts', () => {
    const seen = collect();
    begin({argv: []});
    say('12345');
    finish({exitCode: 0});
    expect(seen[0].output.stdoutBytes).toBe(6);
    expect(seen[0].output.truncated).toBe(false);
  });

  it('truncates a huge answer but reports its real size', () => {
    const seen = collect();
    begin({argv: []});
    say('x'.repeat(MAX_CAPTURED_OUTPUT * 2));
    finish({exitCode: 0});

    const {output} = seen[0];
    expect(output.truncated).toBe(true);
    expect(output.stdoutBytes).toBeGreaterThan(MAX_CAPTURED_OUTPUT);
    expect(output.stdout).toContain('truncated');
    expect(output.stdout.length).toBeLessThan(MAX_CAPTURED_OUTPUT + 200);
  });

  it('scrubs captured output like every other value', () => {
    const seen = collect();
    begin({argv: []});
    say('wrote ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA to disk');
    finish({exitCode: 0});
    expect(seen[0].output.stdout).not.toContain('ghp_AAAA');
  });

  it('keeps a long answer intact below the cap, unlike other fields', () => {
    const seen = collect();
    begin({argv: []});
    say('y'.repeat(8000));
    finish({exitCode: 0});
    expect(seen[0].output.stdout.length).toBeGreaterThan(7000);
  });

  it('still lets the output reach the real stream', () => {
    const written = [];
    const original = process.stdout.write;
    process.stdout.write = chunk => {
      written.push(String(chunk));
      return true;
    };
    try {
      collect();
      begin({argv: []});
      say('visible');
      finish({exitCode: 0});
    } finally {
      process.stdout.write = original;
    }
    expect(written.join('')).toContain('visible');
  });

  it('does not capture what the handler itself prints', () => {
    /** @type {any} */
    let received;
    setEventHandler(e => {
      received = e;
      process.stdout.write('handler noise\n');
    });
    begin({argv: []});
    say('command output');
    finish({exitCode: 0});
    expect(received.output.stdout).toContain('command output');
    expect(received.output.stdout).not.toContain('handler noise');
  });

  it('restores the real writers once the run ends', () => {
    const before = process.stdout.write;
    collect();
    begin({argv: []});
    expect(process.stdout.write).not.toBe(before);
    finish({exitCode: 0});
    expect(process.stdout.write).toBe(before);
  });
});

describe('signals — the runs that never reach `exit`', () => {
  const debugDir = path.dirname(fileURLToPath(import.meta.url));

  /**
   * @param {{owner?: boolean, handlerFirst?: boolean}} [options]
   * @returns {{status: number | null, signal: string | null, event: any, raw: string}}
   */
  function signalledRun({owner = false, handlerFirst = false} = {}) {
    const install = `d.setEventHandler(e => process.stderr.write('EVENT ' + JSON.stringify(e) + '\\n'));`;
    const source = `
      const d = await import(${JSON.stringify(path.join(debugDir, 'index.mjs'))});
      ${handlerFirst ? install : ''}
      d.begin({argv: ['theme', 'build', '--watch'], cliVersion: '0.0.0'});
      d.setCommand('theme build');
      ${handlerFirst ? '' : install}
      ${owner ? `process.on('SIGINT', () => process.exit(0));` : ''}
      process.kill(process.pid, 'SIGINT');
      setTimeout(() => process.exit(7), 2000);
    `;
    const res = spawnSync(
      process.execPath,
      ['--input-type=module', '-e', source],
      {
        encoding: 'utf8',
        timeout: 30_000,
      },
    );
    const line = (res.stderr || '')
      .split('\n')
      .find(l => l.startsWith('EVENT '));
    return {
      status: res.status,
      signal: res.signal,
      event: line ? JSON.parse(line.slice(6)) : null,
      raw: `${res.stdout || ''}${res.stderr || ''}`,
    };
  }

  it('records a Ctrl-C nobody else was listening for', () => {
    const {event} = signalledRun();
    expect(event).toBeTruthy();
    expect(event.signal).toBe('SIGINT');
    expect(event.outcome).toBe('error');
    expect(event.exitCode).toBe(130);
    expect(event.error.code).toBe('ERR_SIGNAL_TERMINATED');
  });

  it('still lets the signal kill the process', () => {
    const {status, signal} = signalledRun();
    expect(signal).toBe('SIGINT');
    expect(status).toBe(null);
  });

  it('leaves the outcome to the command that owns the signal', () => {
    const {status, event} = signalledRun({owner: true});
    expect(status).toBe(0);
    expect(event.outcome).toBe('ok');
    expect(event.exitCode).toBe(0);
    expect(event.error).toBe(null);
    expect(event.signal).toBe('SIGINT');
  });

  it('arms the signal handlers whichever order the lifecycle runs in', () => {
    const {event} = signalledRun({handlerFirst: true});
    expect(event).toBeTruthy();
    expect(event.signal).toBe('SIGINT');
    expect(event.error.code).toBe('ERR_SIGNAL_TERMINATED');
  });
});