Egonex-AI/Understand-Anything · error

--exclude requires patterns

Error message

--exclude requires patterns

What it means

parseArgs validates CLI arguments for prepare-incremental.mjs. The --exclude flag was given but the next argument is missing or itself starts with '--', so there is no pattern value to consume, and the script stops with a usage error rather than silently excluding nothing.

Source

Thrown at understand-anything-plugin/skills/understand/prepare-incremental.mjs:460

  const edges = (graph?.edges ?? []).filter(
    edge =>
      !removedNodeIds.has(edge.source)
      && !removedNodeIds.has(edge.target)
      && !(edge.type === 'imports' && refreshedImportSourceIds.has(edge.source))
      && retainedIds.has(edge.source)
      && retainedIds.has(edge.target),
  );
  return { nodes, edges };
}

function parseArgs(argv) {
  const positionals = [];
  const excludePatterns = [];
  for (let i = 0; i < argv.length; i++) {
    const arg = argv[i];
    if (arg === '--exclude') {
      const value = argv[++i];
      if (!value || value.startsWith('--')) throw new Error('--exclude requires patterns');
      excludePatterns.push(...value.split(',').map(item => item.trim()).filter(Boolean));
    } else if (arg.startsWith('--')) {
      throw new Error(`Unknown option: ${arg}`);
    } else {
      positionals.push(arg);
    }
  }
  if (positionals.length !== 2) {
    throw new Error(
      'Usage: node prepare-incremental.mjs <projectRoot> <baseCommit> [--exclude <patterns>]',
    );
  }
  return { projectRoot: positionals[0], baseCommit: positionals[1], excludePatterns };
}

async function main() {
  const args = parseArgs(process.argv.slice(2));
  const projectRoot = realpathSync(args.projectRoot);

View on GitHub (pinned to 07edf82a04)

Solutions

  1. Pass the patterns immediately after --exclude, e.g. --exclude 'dist,test-fixtures'
  2. Use comma-separated patterns in a single value: --exclude 'build,node_modules'
  3. Quote patterns so shell splitting does not separate them unexpectedly
  4. Check the command in your script/CI config for a missing or mis-quoted value

Example fix

// before
node prepare-incremental.mjs . HEAD --exclude
// after
node prepare-incremental.mjs . HEAD --exclude dist,coverage
Defensive patterns

Strategy: validation

Validate before calling

const args = process.argv.slice(2);
const idx = args.indexOf('--exclude');
if (idx !== -1 && (idx + 1 >= args.length || args[idx + 1].startsWith('--'))) {
  throw new Error('--exclude requires patterns');
}

Try / catch

try {
  const parsed = parseArgs(process.argv.slice(2));
} catch (err) {
  if (err.message === '--exclude requires patterns') {
    console.error('Usage: node prepare-incremental.mjs <projectRoot> <baseCommit> [--exclude <patterns>]');
    process.exit(1);
  }
  throw err;
}

Prevention

When it happens

Trigger: Running `node prepare-incremental.mjs <root> <commit> --exclude` with no value, or `--exclude --other-flag`, or `--exclude` as the last argument before the end of argv.

Common situations: Typing the flag without its value, copy-pasting a command where the pattern list was dropped, or intending a flag whose name begins with -- right after --exclude.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

AI-assisted analysis of Egonex-AI/Understand-Anything@07edf82a04 (2026-09-07). Data as JSON: /api/errors/1044d98609ebc534. Report an issue: GitHub.