feat(tools,www): generated API + Custom Element reference from repository truth (#1158, B2.4) - #1304
Merged
Merged
Conversation
Deploying openelement with
|
| Latest commit: |
ff9851c
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://7d772b66.lessjs.pages.dev |
| Branch Preview URL: | https://kimi-v044-b24-1158-api-truth.lessjs.pages.dev |
Contributor
|
APIError: Insufficient Balance |
…tory truth (#1158, B2.4) Generate www/app/data/_generated-api-reference.ts from the real public exports of every supported subpath (TypeScript compiler API enumeration with workspace paths resolution, matching the public-interface snapshot), each export's JSDoc summary and declaration location, the PACKAGE_SURFACE.md stability classes, and the @openelement/ui compiler manifest (tags, attributes, events, slots, CSS parts, SSR/DSD layer, hydration/activation). The generator fails closed on unclassified exports, stale classifications (removed exports), undocumented stable-candidate exports, internal exports leaking into the documented surface, and duplicate anchors. --check is the CI drift gate (byte-identical regeneration), registered in the AutoFlow policy. The handwritten API inventory in www/app/routes/apilist.tsx is gone: the route consumes the generated inventory and keeps only authored bilingual prose, with a fail-closed projection that refuses stale or missing copy keys. check-package-surface.ts now validates the generated module's subpath inventory against each package's exports map instead of regexing handwritten literals. Comment-only JSDoc summaries were added to previously undocumented stable-candidate exports across packages (ADR-0151; no behavioral change — freeze:semantics:check and the public interface snapshot are unchanged).
SisyphusZheng
force-pushed
the
kimi/v044-b24-1158-api-truth
branch
from
September 4, 2026 03:32
b101b01 to
ff9851c
Compare
Contributor
|
APIError: Insufficient Balance |
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1158 (B2.4, stage #1288). Follows #1157 (content graph, PR #1303).
Problem
The website API reference was a handwritten inventory in
www/app/routes/apilist.tsxthat could silently drift from the real public exports; nothing derived per-export documentation, anchors, source links or search records from repository truth, and no gate detected missing/removed/internal/undocumented exports.Owner
B2.4 / #1158 — generated API + Custom Element reference (tools + generated www data module + apilist consumption).
Before
check-package-surface.tsagainst literal chips.After
tools/lib/api-reference.ts: deterministic export enumeration via the TypeScript compiler API (same program configuration as the public-interface snapshot — no hand-rolled parser, nodeno docsubprocess), with a workspacepathsmap so cross-package re-exports resolve to their true declarations; PACKAGE_SURFACE.md machine-block parsing; JSDoc summary extraction.tools/generate-api-reference.ts+deno task generate:api-reference/deno task api-reference:check: generateswww/app/data/_generated-api-reference.ts(5 packages, 167 documented exports with kind/summary/stability/anchor/source location, 10 custom elements with attributes/events/slots/CSS parts/layer/hydrate/module, plus search records). Fails closed on: unclassified exports, stale classifications (removed exports), undocumented stable-candidates,internal-importableexports leaking into the documented surface, and duplicate anchors.www/app/routes/apilist.tsx: handwritten inventory deleted; the route consumes the generated module and keeps only authored bilingual prose, with a fail-closed projection (a generated package without authored copy, or authored copy without a generated package, throws at build/SSR time).tools/check-package-surface.ts: the apilist gate now validates the generated module's supported+internal subpath inventory against each package's real exports map instead of regexing handwritten literals.open-props-tokens.tsdocumentation lives in its generator template sogenerate:ui-tokensregeneration cannot drop it.api-reference:checkregistered intools/autoflow/policy.ts(ci + release tiers).Why-not-second-owner
The package edits are JSDoc comments only — no public-surface, behavioral or frozen-semantics change (ADR-0151 cited; freeze:semantics:check and the public-interface snapshot pass unchanged). The adapter-vite enumeration approach deliberately reuses the existing TS-API pattern instead of adding a
deno doc --jsonsubprocess dependency.Evidence
deno run tools/generate-api-reference.ts→ 5 packages / 167 documented exports / 10 custom elements;deno task api-reference:checkbyte-identical; render determinism asserted in tests.tools/lib/api-reference.test.ts— 5 passed (block parsing, paths mapping, enumeration kind/summary/source on a fixture, zero-failure real-repo build, unique anchors, no internal leak, byte-identical regeneration).deno task test— 1823 passed (105 steps) | 0 failed | 1 ignored; supabase example 150 passed.deno task build— green; built/apilistrenders all five generated package rows (+8 moreoverflow chip for UI's 12 subpaths within the fixed 5-chip grammar).deno task pack:dry-run— 5 tarballs;deno task package-artifacts:check— passed.deno fmt --check,deno lint,deno task lint:markdown,deno task typecheck— clean.CI=true deno task test:e2e(chromium) — see CI run on this PR; local run results in the PR checks thread.Scope
New: tools/lib/api-reference.ts + test, tools/generate-api-reference.ts, www/app/data/_generated-api-reference.ts. Modified: apilist route (inventory → generated consumption), check-package-surface.ts apilist gate, policy.ts gate registration, deno.json tasks, generate-ui-token-module.ts template, and JSDoc-only comment additions in 24 package source files.
Risk / recorded scope notes
/apilistvisual baseline snapshots (the explicit, CI-skippedOPEN_VISUAL_REGRESSIONreview gate) will show the chip change on next reviewed refresh; no baseline was silently normalized.