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:
@@ -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._
|
||||
|
||||
Reference in New Issue
Block a user