fix: reject unknown codegen CLI arguments

[kang-heewon]

Outcome

OpenAPI and RPC codegen commands now reject unknown options and unsupported positional arguments before loading generation modules. Stable CROCO_CLI_UNKNOWN_OPTION and CROCO_CLI_UNEXPECTED_POSITIONAL diagnostics prevent misspelled output/check flags from silently changing behavior, including when combined with help.

Documented compatibility flags and existing single-dash-prefixed option values remain accepted. Each CLI uses one declarative flag schema for validation and extraction, and both publishable packages include patch changesets.

Verification

• pnpm --filter @croco/openapi-spec test — 54/54
• pnpm --filter @croco/rpc-codegen test — 109/109
• targeted typecheck/build — 36/36 typecheck graph; both package builds passed
• pnpm strict-contract-typecheck — baseline matched, 0 added diagnostics
• pnpm check — passed
• pre-push pnpm test — 226/226
• pre-push pnpm typecheck — 225/225
• independent adversarial re-review — CLEAR

Review gates

• Correctness/regression: PASS — both CLIs reject close --out/--check misspellings, unexpected positionals, and help+unknown bypasses before generation; compatibility paths remain tested.
• API/security/release: PASS — public API snapshots and strict contracts are unchanged; no manifest or lockfile change; patch changesets cover both CLI packages.
• Maintainability/minimality: PASS — accepted tokens derive from per-CLI declarative schemas; the diff is confined to both parsers, their tests, and one changeset.

No known issue-scoped residual risk remains.

Fixes #1397.

Summary by CodeRabbit

• 개선 사항
  • OpenAPI 및 RPC 코드 생성 CLI가 지원되지 않는 옵션이나 예기치 않은 위치 인자를 명확한 진단 메시지와 함께 거부합니다.
  • 잘못된 입력은 코드 생성 작업을 시작하기 전에 즉시 실패하며, 오류 메시지와 도움말이 함께 표시됩니다.
  • 하이픈으로 시작하는 옵션 값도 정상적으로 처리됩니다.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: fdb95293-6110-45c3-af54-229a41212b6b

📥 Commits

Reviewing files that changed from the base of the PR and between 0012ec8 and f9414eb.

📒 Files selected for processing (5)

• .changeset/codegen-cli-arguments.md
• packages/openapi-spec/src/libs/cli.ts
• packages/openapi-spec/src/tests/Cli.spec.ts
• packages/rpc-codegen/src/libs/cli.ts
• packages/rpc-codegen/src/tests/Cli.spec.ts

---

📝 Walkthrough

Walkthrough

OpenAPI 및 RPC 코드 생성 CLI가 알 수 없는 옵션과 지원되지 않는 위치 인자를 안정적인 진단과 함께 거부하도록 변경되었습니다. 플래그 정의가 중앙화되었고, 잘못된 입력 및 단일 대시로 시작하는 값에 대한 테스트가 추가되었습니다.

Changes

CLI 인자 검증

Layer / File(s)	Summary
OpenAPI CLI 검증 및 회귀 테스트 packages/openapi-spec/src/libs/cli.ts, packages/openapi-spec/src/tests/Cli.spec.ts, .changeset/codegen-cli-arguments.md	parseArgs가 지원되지 않는 옵션과 위치 인자를 진단과 함께 거부하고, runCli가 진단과 도움말을 출력하도록 변경되었습니다. 중앙화된 플래그 해석과 잘못된 입력 및 단일 대시 값 테스트가 추가되었습니다.
RPC CLI 검증 및 회귀 테스트 packages/rpc-codegen/src/libs/cli.ts, packages/rpc-codegen/src/tests/Cli.spec.ts	RPC CLI에 동일한 인자 검증과 진단 출력 흐름이 적용되었으며, reactQuery, failOnDiagnostics, strict/compatibility 및 문제 런타임 옵션 해석이 플래그 상수 기반으로 갱신되었습니다.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant parseArgs
  participant runCli
  participant Codegen
  User->>parseArgs: CLI arguments
  parseArgs-->>runCli: invalid diagnostic or parsed options
  runCli-->>User: diagnostic and help on invalid input
  runCli->>Codegen: load and generate only for valid input

Loading

Possibly related PRs

• croco-dev/framework#1126: 동일한 코드 생성 CLI 진입점의 플래그 중앙화 및 인자 검증과 직접 연결됩니다.
• croco-dev/framework#1217: --fail-on-diagnostics와 strict/compatibility 플래그 해석을 공유하는 코드 경로와 관련됩니다.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목이 unknown codegen CLI arguments 거부라는 핵심 변경을 정확히 요약합니다.
Linked Issues check	✅ Passed	OpenAPI/RPC CLI에서 미지원 옵션과 포지셔널 인자를 거부하고, 안정적 진단과 회귀 테스트를 추가해 #1397 요구사항을 충족합니다.
Out of Scope Changes check	✅ Passed	변경은 CLI 검증, 진단, 테스트, 변경 이력에 집중되어 있어 링크된 목표 밖의 불필요한 범위는 보이지 않습니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/1397-reject-unknown-codegen-flags

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📊 Benchmark Results

✅ All benchmarks passed

Benchmark	p75	Threshold	Baseline	vs Baseline	Status	Notes
CrocoApp constructor	9.2μs	30.0ms	8.2μs	+13.0%	✅	-
CrocoApp lambdaHandler (10 controllers)	301.1μs	50.0ms	258.4μs	+16.5%	✅	-
Lambda cold-start simulation	453.2μs	80.0ms	418.1μs	+8.4%	✅	-
Lambda cold-start with headers	408.2μs	80.0ms	369.7μs	+10.4%	✅	-
Lambda cold-start with binary body	379.8μs	80.0ms	339.1μs	+12.0%	✅	-
Lambda cold-start with query params	327.9μs	80.0ms	301.3μs	+8.8%	✅	-
Lambda cold-start with authorizer context	324.2μs	80.0ms	299.8μs	+8.1%	✅	-
Lambda cold-start realistic scenario	325.1μs	80.0ms	299.2μs	+8.6%	✅	-
EventBusConfig.start (10 handlers)	1.6μs	10.0ms	1.4μs	+10.5%	✅	-
EventPublisher.publishNow single event	1.8μs	2.0ms	1.7μs	+6.5%	✅	-
DefaultHandlerResolver.resolve × 10	0.1μs	5.0ms	0.1μs	+0.0%	✅	-
Container.get singleton (cold)	81.3μs	5.0ms	70.3μs	+15.8%	✅	-
Container.register × 50 components	3.7ms	10.0ms	3.2ms	+13.4%	✅	-
Container.validate (50 components)	4.1ms	20.0ms	3.4ms	+19.5%	✅	-
Container.get singleton (warm)	1.7μs	500.0μs	1.6μs	+1.2%	✅	-
TelemetryRuntime.init (lambda preset)	2.1μs	200.0ms	1.1ms	-99.8%	✅	-
lambdaPreset config creation	1.4μs	2.0ms	1.4μs	+0.1%	✅	-

_{Updated: 2026-07-16T12:47:23.743Z · Commit: c23642e}