fix(cli): improve docs generation logging — silence example noise, elevate skipped API errors

[devin-ai-integration]

Description

Improves CLI log output during fern generate --docs in three ways:

1. Silence verbose example validation warnings: Individual example validation warnings ("Example value 'element' is not a valid enum value...") moved from warn → debug. The per-API summary ("Validated 54 examples: 39 valid, 15 invalid") stays at warn. Users get better output from fern check --warnings.

2. Improve logging for skipped APIs: When an API is skipped during docs generation:

• Log level changed from warn → error (skipping an API is actionable)
• Messages now include the workspace name (e.g., fulfillment-importer) instead of full absolute path
• Validation reasons are inlined in the skip message (no more misleading "Run fern check for details")
• Repetitive per-endpoint violations (e.g., 9 frontmatter warnings) collapsed into single summary per API

3. Remove duplicate validation: Removed validateOpenApiSpecForDocsCompat() from generateIr.ts — the OSS validator already catches the same issues, so this was producing duplicate log lines.

Before

[docs]: openapi/openapi.yml: Endpoint description for POST /import/ contains "---" which will be...
[docs]: openapi/openapi.yml: Endpoint description for GET /import/{import_id}/ contains "---"...
[docs]: openapi/openapi.yml: Endpoint description for GET /queue_length/ contains "---"...
... (6 more identical lines)
[docs]: Skipping API workspace at /Users/kenny/.../fulfillment-importer due to 9 validation errors. Run fern check for details.

After

[docs]: Skipping API collision-api due to 1 validation error:
         - openapi/openapi.yml: Parameters path parameter 'format', query parameter 'format'
           all normalize to 'format' in generated SDKs...
[docs]: Skipping API frontmatter-api due to 5 validation errors:
         - 5 endpoints contain "---" frontmatter delimiters that will cause 500 errors on the docs site
[docs]: Validation complete, starting remote docs generation...
[docs]: Published docs to https://smoke-test-preview-....docs.dev.buildwithfern.com

Changes Made

• ExampleTypeFactory.ts: Moved 2 warn → debug (enum mismatch + primitive type mismatch)
• ExampleTypeFactory.test.ts: Updated 23 test assertions mockLogger.warn → mockLogger.debug
• ExampleConverter.ts: Moved 2 warn → debug (enum mismatch + primitive type mismatch) in v3 importer
• generateDocsWorkspace.ts: Skip logging warn → error, added API name, added summarizeValidationErrors() helper with inline reasons
• generateIr.ts: Removed duplicate validateOpenApiSpecForDocsCompat() function
• oss-validator/index.ts: Exported ValidationViolation type
• Added unreleased changelog entry

Testing

• Unit tests updated and passing (15/15 in ExampleTypeFactory.test.ts)
• CI green (186/186 passed)
• Built CLI locally and tested against 3-API fixture (frontmatter errors, param collision, clean spec)
• All 7 test assertions passed — see PR comment for full test report

Link to Devin session: https://app.devin.ai/sessions/a4d85bb7350141469b5c794cb560d189

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[github-actions]

Docs Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-04-23T04:59:11Z).

Fixture	main	PR	Delta
docs	301.0s (n=5)	319.8s (35 versions)	+18.8s (+6.2%)

Docs generation runs fern generate --docs --preview end-to-end against the benchmark fixture with 35 API versions (each version: markdown processing + OpenAPI-to-IR + FDR upload).
Delta is computed against the nightly baseline on main.
Baseline from nightly run(s) on main (latest: 2026-04-23T04:59:11Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-05-01 04:14 UTC

[github-actions]

SDK Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-04-23T04:59:11Z).

Full benchmark table (click to expand)

Generator	Spec	main (generator)	main (E2E)	PR (generator)	Delta
csharp-sdk	square	56s (n=5)	86s (n=5)	64s	+8s (+14.3%)
go-sdk	square	115s (n=5)	132s (n=5)	120s	+5s (+4.3%)
java-sdk	square	179s (n=5)	207s (n=5)	198s	+19s (+10.6%)
php-sdk	square	43s (n=5)	66s (n=5)	50s	+7s (+16.3%)
python-sdk	square	115s (n=5)	223s (n=5)	122s	+7s (+6.1%)
ruby-sdk-v2	square	130s (n=5)	159s (n=5)	71s	-59s (-45.4%)
rust-sdk	square	166s (n=5)	163s (n=5)	171s	+5s (+3.0%)
swift-sdk	square	41s (n=5)	290s (n=5)	42s	+1s (+2.4%)
ts-sdk	square	74s (n=5)	86s (n=5)	74s	+0s (+0.0%)

main (generator): generator-only time via --skip-scripts (includes Docker image build, container startup, IR parsing, and code generation — this is the same Docker-based flow customers use via fern generate). main (E2E): full customer-observable time including build/test scripts (nightly baseline, informational). Delta is computed against generator-only baseline.
⚠️ = generation exited with a non-zero exit code (timing may not reflect a successful run).
Baseline from nightly runs on main (latest: 2026-04-23T04:59:11Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-05-01 04:14 UTC

[devin-ai-integration]

Test Results: Improved Docs Generation Logging

Built CLI from this branch and ran fern generate --docs --preview against a 3-API test fixture designed to trigger different validation errors (frontmatter "---" in descriptions, duplicate parameter names, and a clean spec).

Before/After Comparison

Before (Kenny's production logs on main):

[docs]: openapi/openapi.yml: Endpoint description for POST /import/ contains "---" which will be...
[docs]: openapi/openapi.yml: Endpoint description for GET /import/{import_id}/ contains "---"...
[docs]: openapi/openapi.yml: Endpoint description for GET /queue_length/ contains "---"...
... (6 more identical per-endpoint lines)
[docs]: Skipping API workspace at /Users/kennyderek/.../fulfillment-importer due to 9 validation errors. Run fern check for details.

After (PR branch CLI):

[docs]: Skipping API collision-api due to 1 validation error:
         - openapi/openapi.yml: Parameters path parameter 'format', query parameter 'format'
           all normalize to 'format' in generated SDKs. This causes broken code...
[docs]: Skipping API frontmatter-api due to 5 validation errors:
         - 5 endpoints contain "---" frontmatter delimiters that will cause 500 errors on the docs site
[docs]: Validation complete, starting remote docs generation...
[docs]: Published docs to https://smoke-test-preview-05db942c-a69e-4d2a-b38e-a224629d7db4.docs.dev.buildwithfern.com

Assertion Details (7/7 passed)

#	Assertion	Result
A1	Skip messages use ERROR level (not WARN)	Passed
A2	Skip messages show workspace name, not full path	Passed
A3	Inline reasons included, no "Run fern check for details"	Passed
A4	Frontmatter violations aggregated (5 endpoints → 1 summary line)	Passed
A5	Collision API shows clear inline reason with parameter details	Passed
A6	Healthy API is NOT skipped, docs publish succeeds	Passed
A7	Example validation warnings silenced (debug-only)	Passed

Test Fixture

3 APIs in a single docs project:

• frontmatter-api: 5 endpoints with "---" in descriptions → 5 validation errors → SKIPPED
• collision-api: duplicate format path+query params → 1 validation error → SKIPPED
• healthy-api: clean spec → INCLUDED in generation

CI: 186/186 passed | Devin session