scaffold-a-port

name	scaffold-a-port
description	Batch planning rules (breadth-first then idiom-first depth, HOLDOUT rows, GROUP-nested samples) and the port scaffolding tooling - npm run scaffold, npm run json-to-abap, the OPENUI5_SRC sparse-clone recipe, scope-of pre-checks. Use when planning the next porting batch or creating a new port skeleton.

Planning & scaffolding a port

Part of the ai-demokit rulebook — the scope gate itself (1.71, deprecation, non-app families, exceptions) is defined in AGENTS.md §1 and is a hard CI gate; this guide covers picking the next samples and generating the skeleton.

Batch planning

Batch planning is breadth-first, then idiom-first depth. The mission is gap discovery, and the gap yield of a port drops sharply once its control is covered — many samples are near-duplicates on the same control. So: port one sample per uncovered control first; only when every in-scope control has at least one port does depth (more samples per control) pay. --backlog encodes both phases: rows sort NEW-CONTROL first (control has no port at all), then covered-control(n) ascending by n — a control with one port still yields more new idioms than one with five. Within equal n, pick by idiom, not by name: prefer the sample whose title/files show a feature no existing port of that control exercises (a different aggregation, binding form, event wiring, popup path — skim the sample's view/controller against the control's existing ports), and skip true near-duplicates entirely — a depth port that exercises nothing new is corpus weight without training signal. Rows marked HOLDOUT belong to the hold-out set (ui5/holdout.json, TRAINING.md) and stay out of regular batch planning. GROUP-nested samples (the demo kit's group folders: TreeTable.…, p13n.…, UploadSetwithTablePlugin.…, View.…, …) are part of the universe — named <Group>.<Child>, source at sample/<Group>/<Child>, archived flat as ui5/<lib>/<Group>.<Child>/ (the scaffolder handles the mapping); only children the docuindex lists as official samples count.

Developer tooling — starting a port

Two helpers remove the mechanical boilerplate (they do not write the view — that is the actual porting work):

• npm run scaffold <sample> (scripts/scaffold.mjs) — from an OpenUI5 demo-kit sample id/name it archives the template into ui5/<lib>/<Name>/, picks the next app number, files the port into src/<category>/<library>/ (AGENTS §3 — a fresh port starts in the <= 1.71 half of its flavour, i.e. src/01/<lib>/ for an OpenUI5 sample; declaring the first POST_171 deviation later moves it to src/02/<lib>/, and validate-meta names the target folder) and stamps the batch id into the sidecar (--new-batch / --batch bNN — batches are meta, not folders), and writes the class stub, clas.xml, both package.devc.xml levels and a valid meta/ sidecar. Since 2026-08-04 it enforces the two pre-checks that used to be manual: a HOLDOUT sample (ui5/holdout.json) and an out-of-scope sample (same verdict as generate-coverage.mjs scopeOf: 1.71 floor, deprecation, non-app family — facts from the universe enriched with ui5/properties.json) are refused with the facts printed; ui5/scope-exceptions.json entries pass with a note, --force overrides as a recorded maintainer decision. The stub is a TODO placeholder view: it passes abaplint / pattern-lint / view-gates immediately, and structural_diff (correctly) fails until you rebuild the view 1:1. Needs an OpenUI5 checkout (OPENUI5_SRC, default ../fork-openui5). --dry-run to preview. /home/user/fork-openui5 carries only src/<lib>/src — no test/…/demokit/sample, so the scaffolder finds nothing there. A blobless sparse clone gets just the sample trees in ~350 MB: git clone --filter=blob:none --sparse https://github.com/SAP/openui5.git … then git sparse-checkout set src/<lib>/test/<lib path>/demokit/sample …, and point OPENUI5_SRC at it. Add src/<lib>/src to that same sparse set — scope-of.mjs reads the control JSDoc from there and answers UNRESOLVED (no source .js found) for every entity when the checkout has only the sample trees. That reads like "unknown control" but means "wrong checkout": one sparse clone must carry both halves (~170 MB for the ported libraries), or the scope pre-check silently stops gating.

Artefact regeneration is automated by the tracked .githooks/pre-commit hook: on every commit it regenerates the overview app, the coverage docs and the STATUS.md state block and stages them, so they never drift from meta/ (which the meta_valid CI job enforces on PRs). It is enabled with git config core.hooksPath .githooks, which npm ci / npm install runs automatically via the prepare script.