Skip to content

Commit 59e7c16

Browse files
committed
Address review on #307: no-call models sweep, per-BRD reuse, stack exit 4
1. graph-sweep.sh / app-facts.sh: the first cut required a 'call' edge and refused a model with no microflow-to-microflow calls (reached only from pages/buttons), which master swept. Now FAULT only on an empty or kind-less refs table, report per-kind counts, and graph-sweep warns when none of its orphan-read kinds is present. The per-kind query is fixed (aggregate in GROUP BY). Fixture renamed test-catalog-edge-guard.sh, adds the action-only and kind-less cases (16 checks). 2. review-module.sh reads every report of the run: --reuse-conformance <report-date.tsv> also reads its report-<date>-<BRD>.tsv siblings, and its own run slices every report newer than the run start, so a per-BRD module no longer FAULTs verify-module's rung 13 or drops BRDs. verify-module.sh documents the contract. test-review-conformance-per-brd.sh. 3. conformance-check.sh: per-BRD reports via while-read, so a BRD id with a space stays one BRD (fixture case 9). 4. CHANGELOG: missing LEDGER_FILE now FAULTs; per-BRD baseline rows are re-keyed <BRD>:<pointer>, so run once after upgrade and re-check. 5. #313 follow-up: verify-module.sh grades test-stack-up exit 4 (port held by another process) as FAULT on the stack rung only, not FINDING. test-verify-stack-blocked.sh. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
1 parent a8df6ad commit 59e7c16

10 files changed

Lines changed: 328 additions & 66 deletions

‎CHANGELOG.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,9 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are.
1717

1818
## Unreleased
1919

20-
- fix(graph-sweep, app-facts): **the catalog guard checks for `call` edges, not the `build_mode` label; mxcli v0.24+ labels a complete catalog `source` and both scripts refused every one** ([#259](https://github.com/MendixMau/mxcli-project-toolkit/issues/259)). Field report: four module reviews recorded the sweep as "Instrument FAULT" on a fresh catalog with 5,368 refs rows. Now an empty refs table or zero `RefKind='call'` edges FAULTs, naming the mode and per-kind edge counts; `manifest.json` records the real mode. `tests/wave2/test-catalog-call-edges.sh` (12 checks, both layouts) fails 10 of 12 on master's scripts, including the verbatim FAULT line. Synthetic catalogs; a field run on a v0.24 project is still owed. — AlvinnYeo
21-
- fix(conformance-check, coverage-ledger): **per-BRD ledgers (`<Module>/coverage-ledger/<BRD>.md`) are all measured, one report per BRD, and an index file is named as one instead of "0 measurable rows"** ([#260](https://github.com/MendixMau/mxcli-project-toolkit/issues/260)). Field report: every module with an index ended in `FAULT: 0 measurable rows extracted from 1 ledger(s).`, while `LEDGER_FILE` on one per-BRD file measured 128 rows. Baseline pointers carry the BRD id, `LEDGER_FILE` (file or directory) is in the usage text, and a missing one FAULTs instead of falling back. `tests/wave2/test-conformance-per-brd-ledger.sh` (17 checks, both layouts) fails all 17 on master's script. A field run on a per-BRD project is still owed. — AlvinnYeo
20+
- fix(graph-sweep, app-facts): **the catalog guard checks the refs table, not the `build_mode` label; mxcli v0.24+ labels a complete catalog `source` and both scripts refused every one** ([#259](https://github.com/MendixMau/mxcli-project-toolkit/issues/259)). Field report: four module reviews recorded the sweep as "Instrument FAULT" on a fresh catalog with 5,368 refs rows. Now only an empty or kind-less refs table FAULTs, naming the mode and the per-kind edge counts; a model with no microflow-to-microflow calls (reached only from pages and buttons) still sweeps, and graph-sweep warns when no orphan-read kind is present. `manifest.json` records the real mode. `tests/wave2/test-catalog-edge-guard.sh` (16 checks, both layouts) fails 14 on master's scripts, including the verbatim FAULT line. Synthetic catalogs; a field run on a v0.24 project is still owed. — AlvinnYeo
21+
- fix(conformance-check, review-module, verify-module, coverage-ledger): **per-BRD ledgers (`<Module>/coverage-ledger/<BRD>.md`) are all measured, one report per BRD, review/verify read every report of the run, and an index file is named as one instead of "0 measurable rows"** ([#260](https://github.com/MendixMau/mxcli-project-toolkit/issues/260)). Field report: every module with an index ended in `FAULT: 0 measurable rows extracted from 1 ledger(s).`, while `LEDGER_FILE` on one per-BRD file measured 128 rows. `LEDGER_FILE` (file or directory) is in the usage text. **Upgrade notes:** (a) a `LEDGER_FILE` that does not exist now FAULTs instead of silently falling back to another ledger, and `verify-module.sh` reads `LEDGER_FILE` and passes it on to conformance through the environment, so a stale export now FAULTs the conformance rung; (b) baseline pointers of per-BRD rows are re-keyed `<BRD>:<pointer>`, so a project that had both a filled index and a per-BRD directory sees its old rows go unmatched and the new ones re-seeded as "newly baselined" on the first run after upgrade, with no regressions reported: run conformance once, then re-check. Fixtures: `test-conformance-per-brd-ledger.sh` (19, both layouts), `test-review-conformance-per-brd.sh` (4, both layouts), all failing on master. A field run on a per-BRD project is still owed. — AlvinnYeo
22+
- fix(verify-module): **a stack rung exit 4 from `test-stack-up.sh` (port held by another process) is an instrument FAULT, not a FINDING** — follow-up to [#313](https://github.com/MendixMau/mxcli-project-toolkit/pull/313), whose header says to record it as blocked, not as a test failure; review of #313 found verify-module grading it as findings. Scoped to the stack rung (exit 4 is NOT APPLICABLE from conformance-check). `tests/wave2/test-verify-stack-blocked.sh` (6) fails 2 on master. — AlvinnYeo (port-holder report), review of #313
2223
- learn(testing-shape, test-result-audit): **three test-strength rules, each with a denominator: refusals probed on the server, every undeclared 4xx a failure, one clean-database final run** ([#172](https://github.com/MendixMau/mxcli-project-toolkit/issues/172)). A field comparison of two builds against one frozen spec found the toolkit build checked permission refusals only in the client (a hidden menu item), logged unexpected 400/422 responses as information, and reached 20/20 by stitching three runs. `testing-shape.md` §7 gains three report lines (`N of N restricted pairs probed server-side`, `undeclared 4xx/5xx: 0 of M requests — each fails its step`, `one clean-DB run <id>: N of N scenarios incl. timers, not stitched`); `test-result-audit.md` gains check 2e, which carries the reasons and the field evidence and asks for those numbers. Both baseline skills stay inside the 80,000-word baseline budget (79,997): the reasons live in the on-demand audit skill, and two redundant sentences in `testing-shape.md` §4's verdict paragraphs were folded (the empty-set corollary is stated in the Trace row, `harness-architecture.md` and `report-schema.md`). The backing inbox note is trimmed to its unpromoted "Keep" items. — MendixMau
2324
- learn(learned-detection-gaps, module-review): **two UI defects every model gate passes: a lazy-loaded combo box filter hides its preset, and a theme that pins row heights by position lets the next row cover an inserted widget** ([#299](https://github.com/MendixMau/mxcli-project-toolkit/issues/299)). Both passed check, mxbuild, lint and the scripted checks on a 127-module production app and were found only in the running app. Two register rows with the first oracle and the pre-build check (pluggable properties that change *when* data loads; grep the theme for fixed `height` on positional row classes before an insert), and two LOOK lines in `module-review.md` §4c with denominators (`N of N filters show their preset on first load`, `N of N widgets inserted into an existing container fully visible`). — jopterhorst
2425
- fix(app-restart, test-stack-up): **a port held by another process before `run --local` is named and reported as "instrument blocked" (exit 4), never killed** ([#262](https://github.com/MendixMau/mxcli-project-toolkit/issues/262)). Studio Pro had started its own runtime on the app/admin ports a restart needed; `mxcli run --local` then failed with "Authentication failed" (the admin API answering was Studio Pro's), the next journey ran against Studio Pro's runtime, and four more runs were NOT RUN. `app-restart.sh` now checks the app port and the admin port (record's `adminPort`, else app + 10) before stopping anything — a holder outside the recorded process tree exits 4 with its name, pid and parent — and again after the stop, where anything still holding a port is by definition not ours. `test-stack-up.sh` runs the same check wherever it would tell you to start `run --local` (`--no-docker`, no Docker daemon, `--check` with a leftover record), on the record's ports, `RUN_LOCAL_APP_PORT`/`RUN_LOCAL_ADMIN_PORT`, or mxcli's defaults 8080/8090. Holder lookup: lsof, then ss, then netstat + tasklist on Windows; unnamed holders still block when nothing of ours is running. Fixtures: `test-app-restart.sh` +2 cases (14 assertions, all fail on the old script), `test-stack-up-local.sh` T7 (4 of 6 fail on the old script). — AlvinnYeo

‎project-bin/app-facts.sh‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -249,8 +249,10 @@ BUILD_MODE="$(q "SELECT Value FROM catalog_meta WHERE Key='build_mode';")"
249249
# The build_mode LABEL is not checked (fixed 2026-10-13, field report 2026-10-11): mxcli v0.24.0
250250
# labels a complete catalog 'source', and the old `!= full` test refused it on every run. What
251251
# this script needs is checked instead, below: the tables by name, non-empty refs/activities,
252-
# and at least one 'call' edge (the call graph in step 2 reads RefKind='call'). The label is
253-
# recorded in manifest.json as found, so a reader can still see it.
252+
# and at least one refs row that carries a RefKind (the dependency facts group by it). The label
253+
# is recorded in manifest.json as found, so a reader can still see it. Zero 'call' edges is NOT a
254+
# fault: an early module reached only from pages and buttons has none, and its call graph is
255+
# legitimately empty — requiring them (the first cut of this fix) refused such apps.
254256
MISSING=""
255257
for t in modules_data entities_data microflows_data activities_data pages_data scheduled_events_data refs catalog_meta projects; do
256258
[ "$(q "SELECT count(*) FROM sqlite_master WHERE name='$t';")" = "1" ] || MISSING="$MISSING $t"
@@ -268,14 +270,14 @@ if [ "${N_MODULES:-0}" -eq 0 ] || [ "${N_REFS:-0}" -eq 0 ] || [ "${N_ACTS:-0}" -
268270
echo "FAULT: catalog is vacuous (modules=$N_MODULES refs=$N_REFS activities=$N_ACTS, build_mode '${BUILD_MODE:-unset}'). An empty graph is not a clean app." >&2
269271
exit 2
270272
fi
271-
N_CALLS=$(q "SELECT count(*) FROM refs WHERE RefKind='call';")
272-
if [ "${N_CALLS:-0}" -eq 0 ]; then
273-
KINDS="$(q "SELECT RefKind || '=' || count(*) FROM refs GROUP BY RefKind ORDER BY count(*) DESC LIMIT 8;" | paste -sd' ' -)"
274-
echo "FAULT: catalog has 0 'call' edges (build_mode '${BUILD_MODE:-unset}', $N_REFS refs: ${KINDS:-none})." >&2
275-
echo " The call graph and dead-asset facts read 'call' edges. Refusing to write facts without them." >&2
273+
KINDS="$(q "SELECT k || '=' || n FROM (SELECT COALESCE(NULLIF(RefKind,''),'(none)') k, count(*) n FROM refs GROUP BY k ORDER BY n DESC LIMIT 8);" | paste -sd' ' -)"
274+
N_KINDED=$(q "SELECT count(*) FROM refs WHERE COALESCE(RefKind,'') <> '';")
275+
if [ "${N_KINDED:-0}" -eq 0 ]; then
276+
echo "FAULT: catalog refs carry no RefKind (build_mode '${BUILD_MODE:-unset}', $N_REFS refs by kind: ${KINDS:-none})." >&2
277+
echo " The dependency and call-graph facts are read by kind. Refusing to write facts without one." >&2
276278
exit 2
277279
fi
278-
log "catalog ok: build_mode=${BUILD_MODE:-unset} modules=$N_MODULES refs=$N_REFS (call=$N_CALLS) activities=$N_ACTS (${T1}s)"
280+
log "catalog ok: build_mode=${BUILD_MODE:-unset} modules=$N_MODULES refs=$N_REFS (${KINDS:-none}) activities=$N_ACTS (${T1}s)"
279281

280282
# ---------------------------------------------------------------------------------------------
281283
# Step 2 — inventory + dependencies, straight from the catalog through the REAL module column.

‎project-bin/conformance-check.sh‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -428,13 +428,15 @@ STAMP="$(date +%Y-%m-%d)"
428428
# One report per BRD for per-BRD ledgers (report-<date>-<BRD>.tsv), so measuring several BRDs
429429
# does not leave only the last one on disk; rows from every other shape keep report-<date>.tsv.
430430
REPORTS=""
431-
for b in $(printf '%s\n' "$RESULTS" | awk -F'\t' 'NF{print $7}' | sort -u); do
431+
# while-read, not `for b in $(…)`: a BRD file name with a space must stay one BRD.
432+
while IFS= read -r b; do
433+
[ -n "$b" ] || continue
432434
if [ "$b" = "-" ]; then REPORT="$OUTDIR/report-$STAMP.tsv"; else REPORT="$OUTDIR/report-$STAMP-$b.tsv"; fi
433435
{ printf 'module\tpointer\tstored\tobserved\tverdict\tcommand\n'
434436
printf '%s\n' "$RESULTS" | awk -F'\t' -v b="$b" 'BEGIN{OFS="\t"} $7==b {print $1,$2,$3,$4,$5,$6}'
435437
} > "$REPORT"
436438
REPORTS+="$REPORT"$'\n'
437-
done
439+
done <<< "$(printf '%s\n' "$RESULTS" | awk -F'\t' 'NF{print $7}' | sort -u)"
438440

439441
count() { printf '%s\n' "$RESULTS" | awk -F'\t' -v v="$1" '$5==v' | grep -c . || true; }
440442
OK=$(count OK); STALE=$(count STALE); UNDER=$(count UNDERSTATED); UNK=$(count UNKNOWN-STATUS)

‎project-bin/graph-sweep.sh‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
# is an intent question, answered against the module brief, not here.
2727
#
2828
# Usage: bin/graph-sweep.sh [--module <Name>] [--min-elements N] [--tsv]
29-
# Exit: 0 swept · 2 instrument fault (stale catalog, empty graph, no 'call' edges, missing db)
29+
# Exit: 0 swept · 2 instrument fault (stale catalog, empty or untyped graph, missing db)
3030

3131
set -uo pipefail
3232

@@ -119,26 +119,32 @@ fi
119119
# rows. So the sweep FAULTed on every run on that mxcli, on a fresh, complete catalog:
120120
# FAULT: catalog build_mode is 'source'; reference edges require 'full'.
121121
# The label was a proxy for "the reference edges are there". Test that directly instead: the
122-
# orphan finding reads RefKind 'call' (with action/menu_item/show_page/datasource), and a
123-
# catalog built without edges (the old 'fast' mode) has none. Zero 'call' edges is the
124-
# signature of a catalog that cannot answer the question, whatever its label says.
125-
# Assumption, stated: a real model with microflows has at least one microflow-to-microflow
126-
# call. A model with literally none would FAULT here; the message says what was counted.
122+
# wiring finding reads every refs row, grouped by module, and the orphan finding reads the
123+
# inbound kinds in $READ_KINDS (shared with the ORPHANS query below). A catalog built without
124+
# edges (the old 'fast' mode) has an empty refs table; one whose rows carry no RefKind cannot
125+
# answer the orphan question either. Those two FAULT, naming the mode and the per-kind counts.
126+
#
127+
# Requiring 'call' specifically (the first cut of this fix) was a regression: an early greenfield
128+
# module reached only from buttons and pages has action/show_page edges and no microflow-to-
129+
# microflow call at all, and master swept it fine. So any kinded edge is enough to run; a catalog
130+
# with none of the orphan-read kinds still sweeps, with a warning that its orphan list is moot.
131+
READ_KINDS="'call','action','menu_item','show_page','datasource'"
127132
REFS=$(q "SELECT COUNT(*) FROM refs;")
128133
OBJS=$(q "SELECT COUNT(*) FROM objects;")
134+
KINDS="$(q "SELECT k || '=' || n FROM (SELECT COALESCE(NULLIF(RefKind,''),'(none)') k, count(*) n FROM refs GROUP BY k ORDER BY n DESC LIMIT 8);" | paste -sd' ' -)"
129135
if [ "${REFS:-0}" -eq 0 ] || [ "${OBJS:-0}" -eq 0 ]; then
130136
echo "FAULT: graph is empty (refs=$REFS objects=$OBJS, build_mode '${BUILD_MODE:-unset}'). Refusing to report a clean sweep." >&2
131137
echo " Rebuild: ./mxcli -p $MPR -c 'REFRESH CATALOG FULL'" >&2
132138
exit 2
133139
fi
134-
CALLS=$(q "SELECT COUNT(*) FROM refs WHERE RefKind='call';")
135-
if [ "${CALLS:-0}" -eq 0 ]; then
136-
KINDS="$(q "SELECT RefKind || '=' || COUNT(*) FROM refs GROUP BY RefKind ORDER BY COUNT(*) DESC LIMIT 8;" | paste -sd' ' -)"
137-
echo "FAULT: catalog has 0 'call' edges (build_mode '${BUILD_MODE:-unset}', $REFS refs: ${KINDS:-none})." >&2
138-
echo " The orphan finding reads 'call' edges; without them every microflow looks orphaned." >&2
140+
KINDED=$(q "SELECT COUNT(*) FROM refs WHERE COALESCE(RefKind,'') <> '';")
141+
if [ "${KINDED:-0}" -eq 0 ]; then
142+
echo "FAULT: catalog refs carry no RefKind (build_mode '${BUILD_MODE:-unset}', $REFS refs by kind: ${KINDS:-none})." >&2
143+
echo " The orphan finding is read by kind. Refusing to report a sweep from untyped edges." >&2
139144
echo " Rebuild: ./mxcli -p $MPR -c 'REFRESH CATALOG FULL'" >&2
140145
exit 2
141146
fi
147+
READ_EDGES=$(q "SELECT COUNT(*) FROM refs WHERE RefKind IN ($READ_KINDS);")
142148

143149
WIRING_FILTER=""
144150
ORPHAN_FILTER=""
@@ -194,7 +200,7 @@ WHERE m.ModuleName NOT IN (
194200
AND NOT EXISTS (
195201
SELECT 1 FROM refs r
196202
WHERE r.TargetName = m.QualifiedName
197-
AND r.RefKind IN ('call','action','menu_item','show_page','datasource'))
203+
AND r.RefKind IN ($READ_KINDS))
198204
$ORPHAN_FILTER
199205
ORDER BY m.ModuleName, m.Name;
200206
")"
@@ -210,14 +216,15 @@ fi
210216
N_UNWIRED=$(printf '%s\n' "$WIRING" | awk -F'|' 'NF && $3==0' | grep -c . || true)
211217
N_ORPH=$(printf '%s\n' "$ORPHANS" | grep -c . || true)
212218

213-
echo "graph-sweep · catalog $CAT_MTIME (build_mode ${BUILD_MODE:-unset}) · $OBJS objects · $REFS typed edges ($CALLS call)"
219+
echo "graph-sweep · catalog $CAT_MTIME (build_mode ${BUILD_MODE:-unset}) · $OBJS objects · $REFS typed edges (${KINDS:-none})"
214220
echo
215221
echo " module wiring (>= $MIN_ELEMENTS elements)"
216222
printf ' %-24s %8s %9s %10s\n' MODULE ELEMENTS INBOUND OUTBOUND
217223
printf '%s\n' "$WIRING" | awk -F'|' 'NF {printf " %-24s %8s %9s %10s%s\n", $1, $2, $3, $4, ($3==0 ? " <- no inbound" : "")}'
218224

219225
echo
220226
echo " orphaned microflows (no call / action / nav inbound, entry-point prefixes excluded): $N_ORPH"
227+
[ "${READ_EDGES:-0}" -eq 0 ] && echo " WARNING: the catalog has no call/action/menu_item/show_page/datasource edges, so every microflow reads as orphaned here; check the edge kinds above."
221228
if [ "$N_ORPH" -gt 0 ]; then
222229
printf '%s\n' "$ORPHANS" | awk -F'|' 'NF {printf " %-56s %s activities\n", $1, $2}' | head -40
223230
[ "$N_ORPH" -gt 40 ] && echo " ... and $((N_ORPH-40)) more"

0 commit comments

Comments
 (0)