JuliusBrussee/caveman · error · Error

at least one report path and the canonical span fixture…

Error message

at least one report path and the canonical span fixture path are required

What it means

The validate-continuous-improvement script is a CLI: it takes one or more report fixture paths followed by exactly one canonical span fixture path. If fewer than two argv entries are supplied, it cannot identify both a report and the spans file, so it throws at startup before reading anything. This is the script's argument-count guard, matching its documented usage line.

Solutions

1. Re-run with at least two arguments: one or more report fixtures, then the canonical span fixture last: `validate-continuous-improvement.mjs report.json spans.json`.
2. If invoking through `npm run`, pass args after `--` so they reach the script.
3. Check that your shell globs actually expanded (unmatched globs pass a literal pattern).

Example fix

// before
node scripts/validate-continuous-improvement.mjs report.json
// after
node scripts/validate-continuous-improvement.mjs report.json ../fixtures/spans.json

const args = process.argv.slice(2);
if (args.length < 2) {
  console.error("Usage: validate-continuous-improvement.mjs <reportPath...> <spansPath>");
  process.exit(1);
}

try {
  await run();
} catch (e) {
  if (String(e.message).includes("are required")) {
    console.error("Usage: validate-continuous-improvement.mjs <report...> <spans>");
    process.exit(2);
  }
  throw e;
}

When it happens

Trigger: Running `node scripts/validate-continuous-improvement.mjs` with zero or one arguments — e.g. `... report.json` only (missing spans path), or no arguments at all.

Common situations: Forgot the spans fixture argument; npm script wrapper drops arguments (need `--` to forward args through npm run); copy-pasting an example command that used placeholders; shell glob matching no files so the glob is passed literally as one arg or consumed differently.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• at least one sink id is required
• base and head must be full Git object IDs
• cave_budget_release_reason_required
• cave_live_eval_sandbox_profile_invalid
• cave_subagent_arguments_invalid

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/70ca67850865092a. Report an issue: GitHub.

Appendix: source

Thrown at packages/shared/contracts/scripts/validate-continuous-improvement.mjs:11

import { readFile } from "node:fs/promises";
import { fileURLToPath } from "node:url";
import path from "node:path";
import Ajv2020 from "ajv/dist/2020.js";

// Usage: validate-continuous-improvement.mjs <reportPath...> <spansPath>
// One or more report fixtures followed by the canonical span fixture they were
// built from. Every report is validated; an empty span fixture always fails.
const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const args = process.argv.slice(2);
if (args.length < 2) throw new Error("at least one report path and the canonical span fixture path are required");
const spansPath = args[args.length - 1];
const reportPaths = args.slice(0, -1);

const [reportSchema, spanSchema, spans] = await Promise.all([
  readFile(path.join(packageRoot, "schemas", "continuous-improvement-report.schema.json"), "utf8").then(JSON.parse),
  readFile(path.join(packageRoot, "schemas", "canonical-span.schema.json"), "utf8").then(JSON.parse),
  readFile(spansPath, "utf8").then(JSON.parse),
]);
const reports = await Promise.all(reportPaths.map((reportPath) => readFile(reportPath, "utf8").then(JSON.parse)));

const ajv = new Ajv2020({ allErrors: true, strict: true });
const validateReport = ajv.compile(reportSchema);
const validateSpan = ajv.compile(spanSchema);
const contiguouslyContains = (haystack, needle) => {
  for (let start = 0; start + needle.length <= haystack.length; start += 1) {
    if (needle.every((operation, offset) => haystack[start + offset] === operation)) return true;
  }
  return false;

View on GitHub (pinned to 3ee70a1026)