A committed catalogue, and a route to the one package each reader needs - #55
Merged
Merged
Conversation
The same catalogue exists three times for three readers - SAMPLES.md as a page for a person, web/apps.json behind the page in web/, the overview app inside the system - and none of them serves a program with a question. "Which sample shows a SmartTable, and what does my system need for it?" asked against a raw checkout had no better answer than a regex over SAMPLES.md's prose rows, and web/apps.json is deliberately not committed, so before a deploy it does not exist at all. catalogue.json is that answer: one entry per sample with class, path, package, technology, @summary, @Keywords, and the package's Runs on and Plays together with facts repeated on the entry, plus a head block saying what this repository is (step 3 of 3, the stack integrations) and how a sample is started. One committed file, one raw.githubusercontent.com fetch from main, no generator run on the reader's side - which is exactly why it is committed while web/apps.json stays a build output. It introduces no new source of truth. generate-catalogue.mjs reads the same scan as SAMPLES.md (scripts/lib/scan-samples.mjs) and the same packages.json-plus-README merge as the page - that merge moved out of generate-web-index.mjs into scripts/lib/read-packages.mjs so both generators share one copy instead of drifting apart the way two copies of the sample scan once did; web/apps.json is byte-identical before and after. No timestamp in the output either: the content is a pure function of the tree, so the freshness check can compare bytes. A committed generated file goes stale the first time somebody adds a sample and does not rerun the generator, so the gate follows the samples-md pattern: npm run check:catalogue runs the generator with --check, sits in npm run check, and gets its own check-catalogue workflow - a check only npm run check runs cannot make a pull request red. AGENTS.md section 6 documents the artefact next to SAMPLES.md, and the add-a-sample checklist in section 7 gains the regeneration step. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLKJKRzJ6gYAM6i9Bjyt45
Nine packages, nine unrelated technologies, and most readers need exactly one - but the front page made them derive which one from a table organised by technology name. A reader who does not yet know that "Smart Controls" is the name for columns-from-metadata scrolls past their answer. So the README opens with a decision table phrased from the reader's goal: "Put a screen in front of a RAP business object" -> src/03, "Expose your app in the Fiori Launchpad" -> src/09 - one row per package with what it needs (release floor, service, ICF node), each row taken from the package README's What you need section. The package table below keeps the exact release strings; the decision table routes, it does not repeat. The table is prose kept by hand - a reader's goal is nothing a generator can write - and a hand-kept index next to a machine one is exactly the drift check-overview exists for. It gains a fifth direction: the decision table routes to every package of .github/packages.json exactly once, so a package added without a row (nobody routed to it) and a row pointing at a directory that is gone (routed to nothing) both fail while they can still be fixed. The rows deliberately start with the goal, not with the directory link, so the two README-table parsers (check-overview direction 3 and the web index) keep reading only the package table. Verified both ways: npm run check is green, and removing a row makes check-overview name the missing package. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLKJKRzJ6gYAM6i9Bjyt45
The page in web/ tells a reader what every sample needs and what it costs, but not what any of them looks like - and unlike the sibling pages there is no playground link to click through to, because a system is exactly what every sample here requires. abap2UI5/samples just proved the answer: the linter's screenshotFiles keeps the render gate's headless harness standing long enough to photograph each main view - statically, seeded with mock data, no Gateway, RAP or APC anywhere - so a thumbnail is the gate's own view of the class, not a staged picture. Ported here with the same three decisions. Generated at deploy, never committed: deploy-web writes web/thumbs/ fresh on every run, exactly like apps.json, so no sample pull request carries a binary diff. Skip-and-report: a view the harness cannot render loses only its picture, and the <img> removes itself so the card is complete without it. Fail only on zero: a run that photographs nothing is a harness problem, and even then the deploy publishes (continue-on-error), since a page without pictures beats no page. Measured before wiring CI, because this corpus builds against a system the harness does not have: 19 of 32 app views render, across eight of the ten packages. The 13 skips are three stable categories - sap.ui.comp is SAPUI5-only and absent from the harness's OpenUI5 runtime (7 of the 9 Smart Controls samples), z2ui5.cc custom controls do not load headless (the WebSocket, MIME-audio and Smart Multi Input samples), and the mock model seeds an empty ObjectStatus state on three RAP samples. AGENTS.md section 8 carries those numbers, so the picture-less Smart Controls, AMC/APC and MIME cards read as expected rather than broken. One divergence from the sibling, said in the CSS: their cards float the shot beside the text, these cards are narrow grid columns and flex columns - where a float is just another item - so the thumbnail is a banner across the top, cropped from the top by object-fit so nothing is squashed. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLKJKRzJ6gYAM6i9Bjyt45
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.
Two additions:
catalogue.json, committed — head block (repo id, step-3-of-3 role, how to start a sample, overview app) + 10 package entries (technology, topic, needs, runsOn, cloud, release, branch, readme) + 32 sample entries. No timestamp, so content is a pure function of the tree and the gate compares bytes. Built byscripts/generate-catalogue.mjson the existing scan; thepackages.json+ README-table merge was extracted verbatim intoscripts/lib/read-packages.mjsand now shared withgenerate-web-index.mjs(verified:web/apps.jsonbyte-identical before/after). Wired:npm run catalogue/check:catalogueinnpm run check, workflowcheck-catalogue.yaml, documented in AGENTS.md §6 and the §7 add-a-sample checklist.src/-row parsers keep reading only the package table. The routing is itself gated:check-overview.mjsgained a fifth direction — the decision table must route to everypackages.jsonpackage exactly once (negative-tested).Full
npm run check(12 checks) green before each commit; shared/synced files untouched. Part of an ecosystem-wide pass; no cross-repo merge dependency.🤖 Generated with Claude Code
https://claude.ai/code/session_01WLKJKRzJ6gYAM6i9Bjyt45
Generated by Claude Code