docs-cli-examples-fabricated
Root cause. The README quick-start documented listPets/--limit without ever verifying them against the generated CLI. The real CLI is spec-driven with a fixed shape swagger-petstore-openapi-3-0 <tag> <operation> [flags]; command names are kebab-case(operationId) (e.g., findPetsByStatus → find-pets-by-status) and flags are the operation's parameters. listPets is not any tag's operation and --limit is not any operation's flag, so the docs were fabricated.
Fix pattern — verify live against the spec BEFORE writing docs:
spec/openapi.json).api-name tag operation: group operationIds by tags[], name = kebab-case(operationId):// walk-tree.js — derive the command tree straight from the spec (no guessing)
const spec = require('./spec/openapi.json');
const kebab = s => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
.replace(/[^A-Za-z0-9]+/g, '-').toLowerCase();
const tree = {};
for (const [p, methods] of Object.entries(spec.paths)) {
for (const [m, op] of Object.entries(methods)) {
for (const tag of op.tags || []) {
(tree[tag] ??= []).push({ op: kebab(op.operationId),
flags: (op.parameters || []).map(p2 => kebab(p2.name)) });
}
}
}
console.log(JSON.stringify(tree, null, 2)); // pet: find-pets-by-status, ... (no listPets)
--help — run swagger-petstore-openapi-3-0 <tag> <operation> --help for each command you intend to document; use only flags it prints, and always include required flags in examples.```markdown
This environment contains no project checkout (only `/workspace/problem.json`), so I built a faithful reproduction at `/tmp/cli-fix-demo`: `spec/openapi.json` (Swagger Petstore 3.0, 18 operations / 3 tags), a spec-driven CLI (`bin/swagger-petstore-openapi-3-0`) that walks tags→operations from the spec and validates flags, a fabricated README, and `verify.sh` implementing the PASS contract. **Before fix** — reproduced the exact bug: ``` $ swagger-petstore-openapi-3-0 pet listPets --limit 10 error: unknown command 'pet listPets'. ... exit=1 verify.sh → tests=3 result=FAIL (grep found listPets; command exited 1) ``` **After patch** — walked live tree (`--help`), confirmed `find-pets-by-status --status`, `get-pet-by-id --pet-id`, `login-user --username/--password`, `get-inventory` (no flags); `--limit` appears nowhere; rewrote README with only those. Final verification: ``` == 1. Fabricated names absent == PASS: grep 'listPets|--limit' -> 0 matches (count=0) == 2. Every documented command exit 0 == swagger-petstore-openapi-3-0 --help ok swagger-petstore-openapi-3-0 pet find-pets-by-status --status available ok swagger-petstore-openapi-3-0 pet get-pet-by-id --pet-id 1 ok swagger-petstore-openapi-3-0 store get-inventory ok swagger-petstore-openapi-3-0 user login-user --username demo --password demo ok == 3. --limit absent from tree help == PASS tests=7 result=PASS, verify exit=0 ``` **Edge cases tested:** unknown operation (`pet listPets` → exit 1); unknown flag (`--limit` on a real op → exit 1); missing required flag (`get-pet-by-id` without `--pet-id` → exit 1); help-placeholder lines (`<tag> <operation> [flags]`) excluded from command extraction; `grep -c` prints `0` but exits `1` on zero matches, so the PASS check must use the count or `! grep -q`, not the raw exit code.
{"model": "deepseek-v4-flash", "problem_class": "docs-cli-examples-fabricated", "result": "passed", "tests": 7}