docs(code-reviews): review Secrets, LocalDb, GalaxyRepository, Overview; re-review changed libs (scadaproj#15)

First reviews of Secrets, LocalDb, GalaxyRepository and Overview, and
2026-11-09 re-reviews of Auth, Health, Theme, Telemetry, Audit and
Configuration, all at 91fb2b4. 49 new open findings, each with a P1/P2/P3
priority and a failure scenario: 1 P1, 13 P2, 35 P3. README regenerated;
REVIEW-PROCESS, template and regen script now cover all ten libraries and
the Priority field.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 14:33:14 -05:00
parent 91fb2b48dd
commit 477245f5db
14 changed files with 2602 additions and 52 deletions
+156 -5
View File
@@ -7,14 +7,45 @@
| Component spec | `components/ui-theme/spec/SPEC.md` |
| Shared contract | `components/ui-theme/shared-contract/ZB.MOM.WW.Theme.md` |
| Status | Reviewed |
| Last reviewed | 2026-06-01 |
| Reviewer | Claude (automated baseline) |
| Commit reviewed | `5f75cd4` |
| Open findings | 0 |
| Last reviewed | 2026-11-09 (re-review; baseline 2026-06-01 at `5f75cd4`) |
| Reviewer | Claude (2026-11-09 re-review, scadaproj#15; baseline: Claude automated) |
| Commit reviewed | `91fb2b4` |
| Open findings | 2 |
## Summary
`ZB.MOM.WW.Theme` is a small, clean, well-scoped Blazor Razor Class Library: ten flat-namespace
**2026-11-09 re-review (`91fb2b4`, scadaproj#15).** Re-reviewed at `91fb2b4` (2026-11-09) against the 2026-06-01 baseline `5f75cd4`; the kit is now `0.5.0`.
New since the baseline:
- the CSS-only `<details>` app shell, with the `::details-content` fix and the mobile shell fix;
- `nav-state.js` (localStorage persistence of `NavRailSection`, active-link reveal, and a
`MutationObserver` backstop for interactive render modes);
- `ThemeScripts`;
- the `TechButton` `Size`/`Class` extensions;
- the stateless `TreeTable<TRow>`/`ITreeRow`;
- the upstreamed `.btn` sizing block and the 0.5.0 presentation classes.
The C# components hold no state, implement no `IDisposable` and hold no JS interop references. There is
no `MarkupString` anywhere, and every caller-supplied string is attribute- or text-encoded by Razor.
`LoginCard` still delegates `ReturnUrl` validation and antiforgery to the host, with explicit docs.
`TreeTable` documents its Bootstrap Icons dependency.
The `MutationObserver` is never disconnected. That is fine: it is page-lifetime, created once per
document, and the observe→mutate loop is guarded. The `<details>` shell relies on author `display`
rules for browsers without `::details-content`. That could not be verified without those browsers, so it
is not raised.
All 60 bUnit/static-asset tests pass. There are two new findings:
- **Theme-007 (Medium):** `TechButton` silently discards a caller-supplied `disabled` attribute. The
explicit `disabled="@Busy"` is written after the splat, so a button the caller meant to disable
renders enabled. Verified with a bUnit probe.
- **Theme-008 (Low):** `nav-state.js` marks a section as wired with a DOM attribute. Blazor's
enhanced-navigation DOM sync strips that attribute, so toggle listeners pile up on each navigation,
and the extra listeners save the transient active-link reveal as the user's preference, which is the
issue #2 regression. Verified by reading the code and simulating it in jsdom, with a control.
**2026-06-01 baseline (`5f75cd4`).** `ZB.MOM.WW.Theme` is a small, clean, well-scoped Blazor Razor Class Library: ten flat-namespace
SSR components, two stylesheets (`theme.css` 379 lines, `layout.css` 191 lines), three vendored
IBM Plex `.woff2` fonts, and two public enums. The component C# is correct and minimal — stateless
render logic, no concurrency surface, no secret handling, sensible `[Parameter]`/`EditorRequired`
@@ -31,6 +62,23 @@ absence of XML docs on the public parameter surface.
## Checklist coverage
2026-11-09 re-review at `91fb2b4`:
| # | Category | Examined | Notes |
|---|----------|----------|-------|
| 1 | Correctness & logic bugs | ☑ | `TechButton` drops caller `disabled` → Theme-007. Duplicate toggle listeners after enhanced navigation persist the transient reveal → Theme-008. `TreeTable` (keyed rows, leaf ARIA omission, invariant-culture depth style) and the `NavRailSection` slug are correct. |
| 2 | Public API surface & compatibility | ☑ | Additive in 0.2.0–0.5.0: `ButtonSize`, `TechButton.Size`/`Class`, `TreeTable`/`ITreeRow`, `NavRailSection.Key`, `LoginCard.Heading`, `ThemeScripts`. No removals. The `CaptureUnmatchedValues` contract is not fully honoured for `disabled` (Theme-007). |
| 3 | Concurrency & thread safety | ☑ | Stateless components; the JS is single-threaded with idempotent `apply()`. No issues found. |
| 4 | Error handling & resilience | ☑ | `localStorage` access is wrapped in try/catch, and the script degrades when `window.Blazor` or `MutationObserver` is absent. No issues found. |
| 5 | Security & secret handling | ☑ | No `MarkupString` and no raw HTML. `Accent` goes into a `style` attribute but is developer-supplied. `LoginCard` `ReturnUrl` is echoed into an encoded hidden field, and the open-redirect check stays documented as the host's job. localStorage holds only open/closed flags. No issues found. |
| 6 | Performance & resource management | ☑ | The `MutationObserver` (whole-document `childList`/`subtree`) is page-lifetime and cheap per mutation. Toggle listeners accumulate one per enhanced navigation (Theme-008). No `IJSObjectReference` or `IDisposable` to leak. |
| 7 | Spec & shared-contract adherence | ☑ | No-JS shell holds: native `<details>`, no Bootstrap JS. Tokens and chips are unchanged apart from documented additions. No new drift found. |
| 8 | Packaging, dependencies & project layout | ☑ | 0.5.0 RCL, `FrameworkReference` only. `nav-state.js` is shipped and asserted by `StaticAssetsTests`. AngleSharp is pinned to 1.5.0 in the test project only. No issues found. |
| 9 | Testing coverage | ☑ | 60 tests pass. Gaps: no test passes `disabled` through `TechButton`'s splat (Theme-007), and nothing exercises `nav-state.js` under DOM sync (Theme-008). |
| 10 | Documentation & XML docs | ☑ | Theme-006 fix holds (XML docs on every component, parameter and enum). README documents `TreeTable`'s Bootstrap Icons and interactivity requirements. No issues found. |
<details><summary>2026-06-01 baseline checklist (<code>5f75cd4</code>)</summary>
| # | Category | Examined | Notes |
|---|----------|----------|-------|
| 1 | Correctness & logic bugs | ☑ | Component render logic correct; `open="@Expanded"` boolean-attribute binding behaves (tests confirm); chip/variant `switch` mappings complete. No issues found. |
@@ -44,6 +92,8 @@ absence of XML docs on the public parameter surface.
| 9 | Testing coverage | ☑ | 32 tests cover every component's render contract + corrected font path. CSS-class wiring (e.g. `.rail-ico`, orphan nav CSS) is not asserted, which is how Theme-004/005 slipped through. |
| 10 | Documentation & XML docs | ☑ | README/contract accurate. XML docs present only on `LoginCard`; absent on the other 9 components, all their parameters, and both enums (Theme-006). |
</details>
## Findings
### Theme-001 — Mobile hamburger toggle silently depends on Bootstrap collapse JS
@@ -240,3 +290,104 @@ minimum the non-obvious ones (`ThemeShell.Accent`, `NavRailItem.Match`, `TechBut
**Resolution**
Resolved in `544a6dd`, 2026-06-01 — added `///` summaries to all nine remaining components, every public `[Parameter]`, and both enums (`ButtonVariant`, `StatusState`); enabled `GenerateDocumentationFile` (CS1591 left off the error set for Razor-generated members) so docs build under `TreatWarningsAsErrors` with 0 warnings.
<!-- 2026-11-09 re-review (scadaproj#15) findings below. -->
### Theme-007 — `TechButton` silently discards a caller-supplied `disabled` attribute
| | |
|--|--|
| Severity | Medium |
| Priority | P2 |
| Category | Correctness & logic bugs |
| Status | Open |
| Location | `ZB.MOM.WW.Theme/src/ZB.MOM.WW.Theme/Components/TechButton.razor:3` |
**Description**
The button is rendered as
`<button @attributes="AdditionalAttributes" type="@Type" class="@ButtonClass" disabled="@Busy">`.
In Blazor, an attribute written after an `@attributes` splat overrides the same-named splatted
attribute. `disabled` is not a declared parameter, so a caller's `disabled="…"` is captured into
`AdditionalAttributes` and then overwritten by `disabled="@Busy"`. When `Busy` is `false`, Blazor drops
the attribute entirely. 0.5.0 added a merge for `class` (`ButtonClass` folds in the splatted `class`),
but `disabled` was not merged. The XML doc on `AdditionalAttributes` says "arbitrary additional HTML
attributes splatted onto the underlying `<button>`". The existing test
`Class_composition_keeps_busy_type_and_click_behavior` covers only the opposite direction
(`Busy=true` beating caller `disabled=false`).
**Failure scenario**
A page renders `<TechButton Variant="ButtonVariant.Danger" disabled="@(!CanDelete)" @onclick="Delete">Delete</TechButton>`
for a user who cannot delete, or for a form that is not yet valid. The output is
`<button type="button" class="btn btn-danger">Delete</button>`, with no `disabled`, so the button is
clickable and fires `Delete`. A bUnit probe in the scratchpad confirmed this:
`Render<TechButton>(p => p.AddUnmatched("disabled", true))` produced
`<button type="button" class="btn btn-primary">Delete</button>`. No current family call site passes
`disabled` (20 `.razor` files use `TechButton`), so this is latent. It is still a natural use of the
documented splat, and any server-side authorization check would be the only backstop.
**Recommendation**
Compute the effective state as `Busy || callerDisabled`, where `callerDisabled` is read from
`AdditionalAttributes["disabled"]` with the same case-insensitive lookup used for `class`. Better still,
add an explicit `[Parameter] public bool Disabled`. Then render `disabled="@(Busy || Disabled)"`. Add a
bUnit test for caller `disabled=true` with `Busy=false`.
**Resolution**
_Unresolved._
### Theme-008 — `nav-state.js` "wired" guard is a DOM attribute that Blazor enhanced-navigation DOM sync strips, so toggle listeners accumulate and the transient active-link reveal is persisted
| | |
|--|--|
| Severity | Low |
| Priority | P3 |
| Category | Correctness & logic bugs |
| Status | Open |
| Location | `ZB.MOM.WW.Theme/src/ZB.MOM.WW.Theme/wwwroot/js/nav-state.js:7`, `:17-18`, `:39`, `:65-66` |
**Description**
`wire()` marks a section as initialised with the attribute `data-zbnav-initialized`. `apply()` uses
`hasAttribute(INIT_ATTR)` as its only guard against adding a second `toggle` listener (commit `9e4dedc`,
"guard nav-state.js against duplicate toggle listeners"). After an enhanced navigation, Blazor's DOM
sync (`blazor.web.js` 10.0.1, its attribute synchronisation step) keeps the existing `<details>` element
but removes every attribute that is not in the newly server-rendered HTML. That includes
`data-zbnav-initialized`, which the server never renders. Then `enhancedload` calls `apply()`, which
finds no marker and calls `wire()` again, adding another `toggle` listener to the same element. After N
navigations the element carries N+1 listeners.
The transient-reveal protection assumes a single listener. The first listener consumes
`data-zbnav-transient` and returns. Every later listener sees no flag and writes
`localStorage[zbnav:<key>]`.
**Failure scenario**
1. A user collapses the "Admin" rail section; `zbnav:admin` is saved as `"0"`.
2. They move around the app by enhanced (static-SSR) navigation.
3. They reach a page whose active link lives inside "Admin", for example from a link in the page body
or a redirect.
4. `apply()` reveals the section and flags it transient.
The duplicate listeners then overwrite the saved preference with `"1"`, so the section stays expanded on
every later page. This is the issue #2 bug the transient flag exists to prevent.
A jsdom simulation reproduced it, running the shipped `nav-state.js`, stripping the attribute the way
DOM sync does, and firing `enhancedload` 3 times:
- one collapse produced 4 `setItem` writes;
- the reveal produced 3 writes of `"1"`, leaving `saved=1`;
- the control run, with the attribute not stripped, produced 1 collapse write and 0 reveal writes,
leaving `saved=0`.
**Recommendation**
Track wiring in a JS-side structure that DOM sync cannot touch, for example a module-level
`WeakSet` of wired elements or an expando property (`el.__zbnavWired = true`), instead of a DOM
attribute. Add a test that strips attributes, re-runs `apply()`, and asserts one write per toggle.
**Resolution**
_Unresolved._