Ecosystem roadmap, four missing doc pages, and a CI gate that catches stale numbers - #16
Merged
Merged
Conversation
Full-ecosystem review of the six cap2UI5 repos plus upstream abap2UI5: current state, findings by area, and a four-phase improvement plan (P0 correctness/pipeline integrity, P1 security hardening, P2 npm distribution + DX, P3 structural debt, P4 product polish) with acceptance criteria and success metrics. Placed at the repo root (outside docs/) so it is a maintainer planning document, not a published site page, and stays inert for verify-refs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T2gZuy95uKcT2zngQd1sAL
The audit found the docs' gaps were not wrong prose but absent prose: no roadmap, no sample index, migration buried in a comparison page, and the one extension point the framework has explained nowhere. It also found three numeric claims that had quietly stopped being true, because verify-refs checks identifiers and says nothing about numbers. STALE CLAIMS (measured, not quoted) - The playground bundle is 535 KB minified / 118 KB gzipped, not "~1.2 MB". The whole site is 1.1 MB. The "roughly a tenth" comparison against abap2UI5-web's ~12 MB is true of the site, not of the bundle (that one is a twentieth) — so the sentence now says which is which. - The site is not rebuilt "weekly and on demand": builder-cap2UI5-web builds on every push to main, and the sync pipeline pushes a trigger commit there after each framework change. The weekly cron is the safety net, not the schedule. - api/view-builder said "all 106 bundled samples"; there are 104 files. The number is now a link to the catalogue, which counts them itself. NEW PAGES - guide/samples.md — GENERATED by scripts/gen-samples.mjs from the sample gallery's own catalogue table (z2ui5_cl_smp_app_000.get_catalog), so it cannot disagree with what the playground offers: 97 catalogued samples in 23 categories, each linking into the playground and to its source, plus the 6 sub-apps that ship without a gallery entry. A hand-written index would have been a second copy of a list that changes on every sync. `npm run gen:samples` rewrites it; `--check` fails when it is out of date. The `group` field the task named turns out to be uniformly `samples` — the port carries only one of upstream's three sample repos — so the useful axis is `header`, and both are honoured (groups outside, categories inside). - guide/migration-from-abap2ui5.md — the ~180-word section extracted from vs-abap2ui5 and grown into a per-construct mapping: app class, views, binding, data structures, OpenSQL to CDS queries, cl_http_client to fetch, and a warning block on _bind/_bind_edit that names the trap in both directions (an app written against 1.143.0 relying on _bind writing back silently will not here). vs-abap2ui5 keeps a one-paragraph summary and links on. - guide/roadmap.md — written for users, not maintainers: what is limited today (no npm install path, single instance, the two pins, the frozen classes that are absent on purpose) and what is intended, with no dates. - guide/user-exit.md — the extension point two reference pages mentioned and none explained: discovery, the per-request context, every field of set_config_http_get and set_config_http_post, and the two properties of the CSRF gate worth knowing before relying on it (on by default since the 2026-08 pass, and lenient when there is nothing to compare). CORRECTIONS FOUND ON THE WAY `class my_exit extends z2ui5_if_exit` — the example in reference/configuration — throws at load time. z2ui5_if_exit is a frozen object of method names, not a base class; the framework matches an exit by duck typing. Both pages now show the form that runs, and say so. The same page's env table and CSRF default were also behind the code: retention now follows the framework's own draft expiry instead of contradicting it, and check_csrf_active ships true. CI verify-refs gains --require-checkout: without a checkout it still skips and exits 0 on a laptop, but check.yml now runs `npm run check:ci`, where a missing checkout is a failure. The workflow already checks cap2UI5 out — nothing made that step load-bearing, so removing it would have left the job green and checking nothing. Also: a sitemap in .vitepress/config.mjs (36 URLs at the deployed hostname), the new pages in the sidebar, and AGENTS.md documenting the generated page and the flag. `npm run check` green against a cap2UI5 checkout. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T2gZuy95uKcT2zngQd1sAL
Phases 0-4 are implemented across the six repositories. ROADMAP.md gains a section recording what landed and -- more usefully -- where the analysis was WRONG. The original text is left as written so the corrections are visible rather than quietly edited away. Four findings did not survive contact with the code, including the document's own headline claim: - "_bind does not walk nested structures" is false. Five of the six port-bug ratchet entries are one inherent JS limit unreachable from a real app: the transpiled test passes a VALUE COPY of an empty string, so the lookup matches the first empty attribute. The app-facing API takes the member path and is correct at every depth, verified. The sixth was genuine and is fixed, so the baseline now holds zero port-bug entries. - The "dual draft-store model", called the largest correctness debt, is a documented cache composition: a miss falls through to the durable store. What was real is that it was unbounded, which is now fixed. - All five apps-smoke baseline entries describe CORRECT behaviour -- components and sub-apps that cannot start standalone -- not outstanding bugs. - The proposed stricter CSRF rule was implemented, found to contradict a published upstream contract and to break real callers, and reverted. It also records three defects a live CAP 9 probe found that no unit test could, two of which this work introduced -- which is the argument for the probe -- and what remains open (npm publish needs credentials; the SRTTI family; splitting abap2js.js; committing the oracle's classification). Also fixes reference/database.md, which described srv/draft-retention.js after that file moved into the framework package, and its now-stale TTL default. Caught by verify-refs, which is the check doing its job. npm run check green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T2gZuy95uKcT2zngQd1sAL
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
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.
What this is
The documentation half of the cap2UI5 ecosystem analysis. Three commits:
1.
ROADMAP.md— the analysis and the planA cross-repo review of the six-repo generated pipeline (
abap2UI5→builder-abap2UI5-js→ core package →builder-cap2UI5→cap2UI5→builder-cap2UI5-web), organised as phases P0–P4: pipeline integrity, security hardening, CAP integration, test coverage, documentation.2. Four missing pages + stale-number corrections
New pages:
guide/samples.mdscripts/gen-samples.mjsfrom the published package, so it cannot driftguide/user-exit.mdz2ui5_cl_ui5_user_exit) was undocumentedguide/migration-from-abap2ui5.mdREF #()value semantics)guide/roadmap.mdCorrections to existing pages: sample counts, supported-feature tables and the configuration reference had drifted from what the package actually ships.
3. Execution record
ROADMAP.md§7 records what happened when the plan was executed — including four findings from the original analysis that turned out to be wrong and were corrected rather than quietly dropped:_bindnested-structure binding is not broken — it is one inherent JS limit not reachable from real apps (verified by probe).CI
scripts/verify-refs.mjsnow also runs the sample generator in check mode, so a package change that adds or removes samples turns the docs build red instead of silently leaving the page stale..github/workflows/check.ymlruns it.npm run checkis green locally.Note
This PR is independent of the four code PRs (
builder-abap2UI5-js#25,builder-cap2UI5#23,cap2UI5#65,builder-cap2UI5-web#35) and can merge in any order relative to them.Generated by Claude Code