config-audit/tests/scanners/cli-unknown-flag-rejection.test.mjs

/**
 * Session #51 — CLIs must reject an unknown flag, never ignore it.
 *
 * Third arm of the argument-handling class first measured in #44/#47/#50. The
 * earlier arms were about a flag's VALUE being swallowed as the scan target
 * (`else if (!args[i].startsWith('-')) targetPath = args[i]`). This arm is
 * quieter and worse: several CLIs have no `else` branch at all, so an
 * unrecognised flag falls out of the parse loop leaving no trace — exit 0, a
 * full payload, and an answer to a question the caller did not ask.
 *
 * Measured cost, live, in the same session that wrote this test: the
 * `knowledge-refresh` command's only user-facing knob (`--stale-after N`)
 * reached the CLI as one malformed argv entry (see
 * command-flag-value-portability.test.mjs). Because the CLI ignored it, the
 * command reported "✓ All 14 register entries were re-verified within the last
 * 90 days" — a true-sounding sentence about a threshold the user had just
 * overridden. Had the CLI failed loudly, the shell bug would have been a
 * one-line exit-3 message instead of a silent wrong answer.
 *
 * Scope of this guard: the CLIs whose commands were dogfooded in this chunk.
 * `optimize-lens-cli.mjs` and `token-hotspots-cli.mjs` share the defect but
 * also carry the still-open positional-swallow arm; both are fixed together in
 * the v5.14 arg-handling chunk, where every call site's flags can be audited at
 * once. They are listed in KNOWN_OPEN so the number stays visible rather than
 * being quietly rounded down to zero.
 */

import { test } from 'node:test';
import { strict as assert } from 'node:assert';
import { spawn } from 'node:child_process';
import { readFile } from 'node:fs/promises';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = dirname(fileURLToPath(import.meta.url));
const SCANNERS_DIR = resolve(__dirname, '..', '..', 'scanners');

/** CLIs this guard holds to the invariant, with the argv they need to get past required-arg checks. */
const GUARDED = [
  { cli: 'campaign-cli.mjs', argv: [] },
  { cli: 'knowledge-refresh-cli.mjs', argv: [] },
  { cli: 'campaign-write-cli.mjs', argv: ['init'] },
  { cli: 'campaign-export-cli.mjs', argv: ['--repo', '.'] },
];

/** Same defect, deferred to the v5.14 arg-handling chunk together with their positional-swallow arm. */
const KNOWN_OPEN = ['optimize-lens-cli.mjs', 'token-hotspots-cli.mjs'];

function run(cli, argv) {
  return new Promise((res) => {
    const child = spawn(process.execPath, [resolve(SCANNERS_DIR, cli), ...argv], {
      cwd: resolve(__dirname, '..', '..'),
    });
    let stderr = '';
    child.stderr.on('data', (d) => { stderr += d; });
    child.stdout.on('data', () => {});
    child.on('close', (code) => res({ code, stderr }));
  });
}

for (const { cli, argv } of GUARDED) {
  test(`${cli} rejects an unknown flag with exit 3`, async () => {
    const { code, stderr } = await run(cli, [...argv, '--zzz-not-a-real-flag']);

    assert.equal(
      code,
      3,
      `${cli} accepted an unknown flag (exit ${code}). A flag the CLI does not understand\n` +
        'must fail loudly — silently ignoring it turns a caller-side bug into a confident\n' +
        'wrong answer. stderr was: ' + JSON.stringify(stderr),
    );
    assert.match(
      stderr,
      /--zzz-not-a-real-flag/,
      `${cli} must name the offending flag so the caller can find it.`,
    );
  });
}

test('the deferred CLIs are still deferred, and still counted', () => {
  assert.equal(
    KNOWN_OPEN.length,
    2,
    'When the v5.14 arg-handling chunk closes optimize-lens-cli and token-hotspots-cli,\n' +
      'move them from KNOWN_OPEN into GUARDED rather than deleting them — the count is\n' +
      'the record of how wide the class was.',
  );
});

/**
 * The caller arm. #45/#46/#47 all taught the same lesson: fixing a CLI does not fix the
 * command that reads its payload. `addedUnverified` and the `skipped` reasons only reach the
 * user if the command template is told to report them — otherwise the CLI is honest into a
 * void, and the phantom repo is just as invisible as before.
 */
const CAMPAIGN_MD = resolve(__dirname, '..', '..', 'commands', 'campaign.md');

test('campaign.md reports the fields the write-CLI added for honest coverage', async () => {
  const content = await readFile(CAMPAIGN_MD, 'utf-8');

  assert.match(
    content,
    /addedUnverified/,
    'campaign.md must report `addedUnverified` after an add — a tracked path the CLI could\n' +
      'not read is exactly the row that silently pollutes the backlog and the token bill.',
  );
  assert.match(
    content,
    /skipped/,
    'campaign.md must report `skipped[]` after a token sweep so the bill\'s coverage is honest.',
  );
});