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
+40 -4
View File
@@ -7,14 +7,31 @@
| Component spec | `components/audit/spec/SPEC.md` |
| Shared contract | `components/audit/shared-contract/ZB.MOM.WW.Audit.md` |
| Status | Reviewed |
| Last reviewed | 2026-06-01 |
| Reviewer | Claude (automated baseline) |
| Commit reviewed | `5f75cd4` |
| 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 | 0 |
## Summary
`ZB.MOM.WW.Audit` is a small, clean, well-scoped library: one canonical `AuditEvent`
**2026-11-09 re-review (`91fb2b4`, scadaproj#15).** Re-reviewed at `91fb2b4` (2026-11-09) against the 2026-06-01 baseline `5f75cd4`. The only source changes
since the baseline are the five baseline fixes from `544a6dd` and the repository-URL correction from
`01c6dc1`; the version is still `0.1.0`. The fixes are:
- `CompositeAuditWriter` now swallows `OperationCanceledException` along with every other writer
fault, so the "must not throw" contract holds.
- `TruncatingAuditRedactor` over-redacts both `DetailsJson` and `Target` on internal failure, and
clamps a negative cap to 0.
- `TruncatingAuditRedactorOptions` is an immutable `record` with `init` accessors. A reflection check
of the locally cached `0.1.0` nupkg (2026-06-02) shows this shape, so the published package already
carries it.
- XML docs are generated.
- Edge-case tests were added.
All five fixes are correct. `AddZbAudit` (`TryAdd` defaults) has a container-building test
(`AuditServiceCollectionExtensionsTests`). All 23 tests pass. No new findings.
**2026-06-01 baseline (`5f75cd4`).** `ZB.MOM.WW.Audit` is a small, clean, well-scoped library: one canonical `AuditEvent`
sealed record, a 3-value `AuditOutcome` enum, two narrow seams (`IAuditWriter`,
`IAuditRedactor`), five shipped helpers, and a single `AddZbAudit` registration. The record
matches `EVENT-MODEL.md` field-for-field (names, types, required/optional split, and the
@@ -33,6 +50,23 @@ family-wide baseline pattern), and a couple of missing edge-case tests (Audit-00
## Checklist coverage
2026-11-09 re-review at `91fb2b4`:
| # | Category | Examined | Notes |
|---|----------|----------|-------|
| 1 | Correctness & logic bugs | ☑ | `Truncate` covers null, at-cap, a marker longer than the cap, cap 0 and a negative cap (clamped). Fan-out continues past a failing or cancelled writer. No issues found. |
| 2 | Public API surface & compatibility | ☑ | The class→record and `set`→`init` change on `TruncatingAuditRedactorOptions` is source- and binary-breaking for mutating callers. It shipped inside `0.1.0` (verified against the cached nupkg) and no consumer mutates the options. No issues found. |
| 3 | Concurrency & thread safety | ☑ | Options are now immutable; writers and redactors are stateless; the composite snapshots its writers with `ToArray()`. No issues found. |
| 4 | Error handling & resilience | ☑ | The composite swallows all inner faults, OCE included. The redactor never throws, and its catch path scrubs both owned fields. No issues found. |
| 5 | Security & secret handling | ☑ | `RedactingAuditWriter` still applies the redactor strictly before the inner writer. Over-redaction is now strictly safer. No issues found. |
| 6 | Performance & resource management | ☑ | One `with`-copy per redaction and nothing disposable. When cancelled, the composite still calls each remaining writer once with the cancelled token, which is cheap and intended. No issues found. |
| 7 | Spec & shared-contract adherence | ☑ | Writer hard rule ("never throws to caller") is now honoured; the options are the immutable record the contract describes. No issues found. |
| 8 | Packaging, dependencies & project layout | ☑ | `GenerateDocumentationFile` is on; repository URLs point at `scadaproj`; `push.sh` packs a named solution from the repo root. No issues found. |
| 9 | Testing coverage | ☑ | 23 tests, including never-throw/over-redact, negative caps, composite null/empty and OCE swallowing, plus a container-building `AddZbAudit` test. No issues found. |
| 10 | Documentation & XML docs | ☑ | XML remarks on the composite and redactor match the new behaviour, and docs are emitted. No issues found. |
<details><summary>2026-06-01 baseline checklist (<code>5f75cd4</code>)</summary>
| # | Category | Examined | Notes |
|---|----------|----------|-------|
| 1 | Correctness & logic bugs | ☑ | `Truncate` boundary logic correct for sane configs; marker-longer-than-max clips safely. Partial over-redaction edge under negative max → Audit-002. |
@@ -46,6 +80,8 @@ family-wide baseline pattern), and a couple of missing edge-case tests (Audit-00
| 9 | Testing coverage | ☑ | 19 tests; public contract exercised (round-trip, UTC normalization, fan-out, cancellation, redaction ordering). Missing never-throw/over-redact and null-writer cases → Audit-005. |
| 10 | Documentation & XML docs | ☑ | XML docs present and accurate on the whole public surface; README accurate. Docs not emitted to a file → Audit-004. |
</details>
## Findings
### Audit-001 — `CompositeAuditWriter` re-throws `OperationCanceledException` to the caller, contradicting the "must not throw" writer contract