fix(api): render API reference from CRD/OpenAPI facts instead of guessing

[youyongsong]

What

The API-reference components ignored facts already present in the CRD / OpenAPI sources and pushed the responsibility onto authors, who miss it. This fixes a family of rendering defects and adds offline integrity tooling. Full defect inventory + neutral review: this was tracked as DOOM-1..23 (18 actionable).

Correctness — read the source instead of guessing

• namespaced derived from spec.scope (Cluster resources no longer render an unreachable /namespaces/{namespace}/ path); prop still overrides.
• plural from spec.names.plural instead of pluralize(kind) — fixes hyphenated (vpc-egress-gateways) and irregular (alaudaloadbalancer2) plurals; new plural escape-hatch prop; toLocaleLowerCase→toLowerCase.
• default version for multi-version CRDs = the version kubectl resolves to (highest-priority served version, never served: false), applied to both the schema and the endpoint path; configurable via api.crdVersion.
• /status (and new /scale) rendered from spec.versions[].subresources, not from a status property — fixes both fabricated and missing status endpoints.
• x-kubernetes-int-or-string (anyOf) fields render their type instead of an empty cell.

Anchors & badges

• Array-item schema sections (.spec.foo[]) no longer collide with the parent (.spec.foo) on the same HTML id (page-level stateful slugger).
• Operations without a summary no longer produce id="undefined" / bare numeric anchors.
• The Request Body required badge reads requestBody.required (boolean), not the body schema's required-property list.

New config & tooling

• doom api check — offline validation of local CRD/OpenAPI sources (parse, kind, unique name, <group>_<plural>.yaml filename convention, cross-file OpenAPI definition conflicts).
• no-unresolved-api-ref lint rule for the five API components.
• api.references object form { href, routePath?: string | false } (strings unchanged); translate.copyOnlyDirectories.
• Deterministic source ordering; filepath/openapiPath keys independent of process.cwd().
• <K8sPermissionTable> shows a visible "not found" row instead of dropping it.
• Component chrome translated via useTranslation (en/zh/ru).
• API pages surface top-level schema properties in the outline.

Testing

• yarn build (tsc) ✅ · yarn test 380 passed ✅
• Added fixture-docs regression fixtures (Cluster scope / hyphenated + irregular plural / served:false version / no-status-subresource / IntOrString / summary-less OpenAPIPath). doom's own tekton fixtures are 8/8 Namespaced, pluralize-compatible, single-version, 0 subresources — they structurally cannot trip these bugs.
• before/after on the fixtures: fabricated endpoints and duplicate/#undefined anchors go to zero.

Downstream impact: the scope / plural / version / status fixes change the rendered endpoints on already-published pages. namespaced (docs/*/usage/api.md) and the CRD default-version were documented public defaults; downstream docs should re-review their API pages after upgrading. See the changeset for details.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: fb22c26

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@alauda/doom	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

yarn add https://pkg.pr.new/@alauda/doom@347.tgz

yarn add https://pkg.pr.new/@alauda/doom-export@347.tgz

commit: fb22c26

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 55.43%. Comparing base (c33261e) to head (fb22c26).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #347      +/-   ##
==========================================
+ Coverage   54.27%   55.43%   +1.15%     
==========================================
  Files          63       63              
  Lines        1555     1555              
  Branches      482      482              
==========================================
+ Hits          844      862      +18     
+ Misses        550      534      -16     
+ Partials      161      159       -2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.