fix: create OpenAPI output directories predictably

[kang-heewon]

Outcome

The OpenAPI CLI now creates missing parent directories before writing generated output, so clean nested targets such as generated/contracts/openapi.json succeed. --output-check remains read-only and reports missing output without creating directories, while write failures preserve their original filesystem diagnostics.

Fixes #1714

Verification

• pnpm --filter @croco/openapi-spec test — 65 tests passed.
• pnpm --filter @croco/openapi-spec typecheck, lint, and build — passed.
• pnpm check — 24/25 repository gates passed; 1 not applicable; 0 failed.
• pnpm changeset-required:check -- --base origin/trunk --head HEAD — passed.
• Pre-push full workspace test and typecheck gates — passed.

Review gates

• Correctness and regression — PASS. The nested-output regression failed with ENOENT before the change and now writes parseable OpenAPI from a clean directory; missing-output check coverage proves no parent directory is created, and an ENOSPC fixture proves write diagnostics are preserved.
• API, security, compatibility, and release — PASS. Generated content, public exports, dependencies, package metadata, and the lockfile are unchanged; a patch changeset covers @croco/openapi-spec.
• Maintainability and minimality — PASS. Production behavior changes only at the existing write boundary by recursively creating dirname(outFile) before writeFile, reusing Node filesystem primitives without new abstractions.

Residual risk

None identified within the issue scope.

Summary by CodeRabbit

• 개선 사항

  • OpenAPI 생성 시 중첩된 출력 경로에 필요한 상위 디렉터리가 자동으로 생성됩니다.
  • 출력 검사 모드에서는 디렉터리나 파일을 생성하지 않고 결과만 확인합니다.
  • 파일 저장 오류가 발생하면 원래 오류 정보가 그대로 전달됩니다.

• 테스트

  • 출력 디렉터리 생성, 저장 오류, 검사 모드 동작에 대한 검증을 강화했습니다.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 275d191f-8739-482f-a068-306bd029c807

📥 Commits

Reviewing files that changed from the base of the PR and between b278729 and bf0b4b0.

📒 Files selected for processing (4)

• .changeset/deterministic-openapi-output-directories.md
• packages/openapi-spec/src/libs/cli.ts
• packages/openapi-spec/src/tests/Cli.spec.ts
• packages/openapi-spec/src/tests/OpenApiCliGeneration.spec.ts

---

📝 Walkthrough

Walkthrough

OpenAPI CLI가 쓰기 모드에서 출력 파일의 상위 디렉터리를 생성합니다. --output-check 모드는 읽기 전용 동작을 유지합니다. 이 변경을 검증하는 단위 테스트, 생성 테스트, changeset이 추가되었습니다.

Changes

OpenAPI 출력 경로 처리

Layer / File(s)	Summary
쓰기 모드 디렉터리 생성 .changeset/deterministic-openapi-output-directories.md, packages/openapi-spec/src/libs/cli.ts	cli.ts가 dirname을 사용해 writeFile 전에 mkdir(..., { recursive: true })를 호출합니다. changeset은 중첩 출력 경로 생성과 읽기 전용 검사 유지 내용을 기록합니다.
테스트와 읽기 전용 검사 packages/openapi-spec/src/tests/Cli.spec.ts, packages/openapi-spec/src/tests/OpenApiCliGeneration.spec.ts	파일시스템 모킹에 mkdir 추적과 쓰기 실패 주입을 추가합니다. 테스트는 현재 디렉터리 생성, 중첩 출력 경로 생성, 쓰기 실패 전파, --output-check에서 디렉터리와 파일을 만들지 않는 동작을 검증합니다.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• croco-dev/framework#1126: 두 PR 모두 packages/openapi-spec/src/libs/cli.ts의 OpenAPI CLI 생성 흐름을 수정합니다.

🚥 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	제목은 OpenAPI 출력 디렉터리를 예측 가능하게 생성하는 핵심 변경을 간결하고 명확하게 설명한다.
Linked Issues check	✅ Passed	변경 사항은 [#1714]의 중첩 경로 생성, check 모드 무변경, 쓰기 오류 보존 및 테스트 요구사항을 충족한다.
Out of Scope Changes check	✅ Passed	소스 변경, 테스트, changeset은 모두 [#1714]의 구현과 검증 범위에 포함된다.
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/1714-openapi-output-directories

---

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	38.5μs	30.0ms	8.2μs	+371.2%	❌	-
CrocoApp lambdaHandler (10 controllers)	1.9ms	50.0ms	258.4μs	+617.2%	❌	-
Lambda cold-start simulation	1.8ms	80.0ms	418.1μs	+331.6%	❌	-
Lambda cold-start with headers	1.6ms	80.0ms	369.7μs	+339.8%	❌	-
Lambda cold-start with binary body	1.7ms	80.0ms	339.1μs	+388.5%	❌	-
Lambda cold-start with query params	1.6ms	80.0ms	301.3μs	+429.0%	❌	-
Lambda cold-start with authorizer context	1.6ms	80.0ms	299.8μs	+420.5%	❌	-
Lambda cold-start realistic scenario	1.6ms	80.0ms	299.2μs	+425.8%	❌	-
EventBusConfig.start (10 handlers)	2.1μs	10.0ms	1.4μs	+43.9%	❌	-
EventPublisher.publishNow single event	2.3μs	2.0ms	1.7μs	+35.1%	❌	-
DefaultHandlerResolver.resolve × 10	0.1μs	5.0ms	0.1μs	-16.2%	✅	-
Container.get singleton (cold)	74.0μs	5.0ms	70.3μs	+5.3%	✅	-
Container.register × 50 components	3.5ms	10.0ms	3.2ms	+7.8%	✅	-
Container.validate (50 components)	4.0ms	20.0ms	3.4ms	+19.3%	✅	-
Container.get singleton (warm)	1.9μs	500.0μs	1.6μs	+17.3%	✅	-
TelemetryRuntime.init (lambda preset)	2.4μs	200.0ms	1.1ms	-99.8%	✅	-
lambdaPreset config creation	1.5μs	2.0ms	1.4μs	+4.1%	✅	-

_{Updated: 2026-08-05T13:07:29.363Z · Commit: e5c2db0}