kayg/infraternal

Watch

Fork 0

Doc-comment coverage (D345) #342

New issue

Closed

opened 2026-11-04 09:59:40 +00:00 by kayg · 5 comments

kayg commented

2026-11-04 09:59:40 +00:00

Owner

Job J185. Adds scripts/doc-coverage (documented vs undocumented modules, fns, types, consts per Rust crate, TS package and the Swift helper, plus code lines excluding comments and blanks) and a never-go-down ratchet row in scripts/verify quick and fast. Baseline table follows in a comment.

Branch: doc-coverage-j185, base bb30a573b (origin/dev).

Plan: one stdlib python3 scanner (comment/string-aware lexer, no syn, no cargo build), baseline JSON committed, ratchet compares per unit by exact fraction. Estimate 1.5 h.

Job J185. Adds `scripts/doc-coverage` (documented vs undocumented modules, fns, types, consts per Rust crate, TS package and the Swift helper, plus code lines excluding comments and blanks) and a never-go-down ratchet row in `scripts/verify quick` and `fast`. Baseline table follows in a comment. Branch: `doc-coverage-j185`, base `bb30a573b` (origin/dev). Plan: one stdlib python3 scanner (comment/string-aware lexer, no syn, no cargo build), baseline JSON committed, ratchet compares per unit by exact fraction. Estimate 1.5 h.

kayg commented

2026-11-04 10:09:41 +00:00

Author

Owner

Baseline on origin/dev `bb30a573b` (committed as `scripts/doc-coverage-baseline.json`)

Cells are documented/total. pub = public/exported items (all kinds). "code" = lines excluding comments and blanks. Only /// and /** */ count as documentation; plain // does not.

unit                                         files    code        mod          fn      type     const        pub   doc/total     %
-------------------------------------------  -----  ------  ---------  ----------  --------  --------  ---------  ----------  ----
rust:(no crate)                                  3      70        3/3         0/2       0/1       0/1        3/3         3/7  42.9
rust:crates/infraternal                         68   18424      85/90     173/721     27/72      7/38    147/181     292/921  31.7
rust:crates/infraternal-agent                   68   23461      91/93     214/737    53/150     12/55    224/336    370/1035  35.7
rust:crates/infraternal-mesh                    17    2859      18/18      37/128     33/44       7/7     94/127      95/197  48.2
rust:crates/infraternal-mesh/fuzz                1      86        1/1         0/1       0/0       0/0        1/1         1/2  50.0
rust:crates/infraternal-plugin-api              23    3774      27/30     114/215     61/84     18/32    212/253     220/361  60.9
rust:crates/infraternal-protocol                 8    2567        8/8       14/81     10/13       7/8      39/42      39/110  35.5
rust:crates/infraternal-server                 268   89497    299/328    736/2502   170/426    27/187   762/1097   1232/3443  35.8
rust:crates/infraternal-session                  2      93        3/3         0/7       0/1       0/0        2/2        3/11  27.3
rust:crates/infraternal-shim                    62   19440    100/105     198/789     28/76     27/78    216/348    353/1048  33.7
rust:crates/infraternal-status                  10    2473      10/10       29/84      9/10      2/11      30/30      50/115  43.5
rust:crates/plugins/backup                       2     101        3/3         1/2       0/0       1/1        4/4         5/6  83.3
rust:crates/plugins/canvas                       7    1486       9/10        5/62       4/8       0/7      13/39       18/87  20.7
rust:crates/plugins/desktop                     54   13523      61/70      85/380    17/128      4/34    148/222     167/612  27.3
rust:crates/plugins/host-facts                   6    1123        7/7       13/49      8/10      2/12      28/28       30/78  38.5
rust:crates/plugins/mesh                        68   21601      74/89     251/736    84/120     20/85    297/325    429/1030  41.7
rust:crates/plugins/mesh/fuzz                    2      58        2/2         0/1       0/0       0/1        2/2         2/4  50.0
rust:crates/plugins/proxy                       28   11087      28/30      86/420     42/88      9/63    146/163     165/601  27.5
rust:crates/plugins/relay                       10    2579      14/15      41/121     21/30     15/45      69/70      91/211  43.1
rust:crates/plugins/release                     10    1379      10/10        6/36      6/18       2/7      23/31       24/71  33.8
rust:crates/plugins/remote                      26   10506      31/38     143/339     45/76     24/40    180/224     243/493  49.3
rust:crates/plugins/ssh                         85   22724     92/102     238/702   100/193      8/49    346/443    438/1046  41.9
rust:fuzz                                       36     979      36/36         1/2       0/0       0/0      36/36       37/38  97.4
rust:research/mesh-engines/netlink-bench         3     479        3/3        0/22       0/1      0/10        3/3        3/36   8.3
rust:research/process-per-user/vt-carry          5    1861        6/7      32/104      3/14       1/7      32/40      42/132  31.8
rust:research/quic-stacks/harness                8    1829        8/8       13/59       2/9      0/10      21/45       23/86  26.7
rust:research/ssh-client/probe                   2     136        2/2         0/5       0/1       0/0        2/2         2/8  25.0
swift:crates/plugins/desktop/native             12    1847      12/12       8/107      5/26     2/163      12/12      27/308   8.8
swift:crates/plugins/desktop/tests/fixtures     13    1129      13/13        1/34      0/16      0/23      13/13       14/86  16.3
ts:apps/release-signer/src                       1     150        1/1        4/17       1/2       1/3        1/1        7/23  30.4
ts:apps/tracer                                 669   78612    626/669    882/2371   157/604  222/1295  1433/2470   1887/4939  38.2
ts:docs/verification/addhost-breakit2            5     145        5/5         0/0       0/0      0/17        5/5        5/22  22.7
ts:docs/verification/ca-update-audit             2     143        2/2         0/3       0/0      0/16        2/2        2/21   9.5
ts:packages/protocol                            18    2489      17/18      37/112     26/44      3/16     82/126      83/190  43.7
ts:packages/ui                                  83    7601      72/83     174/301    32/165    52/193    267/475     330/742  44.5
ts:research/vnc/benchmark                        1     268        1/1         0/3       0/0      0/18        1/1        1/22   4.5
ts:scripts                                       5     128        5/5         0/2       0/0      0/10        5/6        5/17  29.4
ts:scripts/browser-auth                         13    2642      13/13        5/46       0/0     1/135      14/14      19/194   9.8
ts:scripts/hosts-from-server                     1      91        1/1         0/0       0/0       0/8        1/1         1/9  11.1
ts:scripts/release                               5     512        5/5         1/3       0/0      0/12        5/5        6/20  30.0
TOTAL                                         1710  349952  1804/1949  3542/11306  944/2430  474/2697  4921/7228  6764/18382  36.8

What counts: modules (one per file plus inline Rust mod x {}), fns (free, methods, associated; not trait-impl methods, not fns nested in fn bodies), types, consts. Not counted: struct fields, enum variants, macros, vendor/, node_modules/, *.d.ts.

Usage: scripts/doc-coverage (table), --json [FILE], --check (the ratchet, exit 1 if any unit fell), --update (raise the baseline; refuses to lower it, --force overrides). The ratchet compares exact fractions per unit, so one new undocumented item in a fully documented crate fails. Jobs should not edit the baseline file (parallel branches would conflict); raise it after merges with --update.

Runtime of the new verify row (doc coverage ratchet, fixture tests plus ratchet): 1.0 s on dev-02 (arm64, load 15), 5.9 s on compute01 (x86_64, load 39). Pure python, no build.

## Baseline on origin/dev `bb30a573b` (committed as `scripts/doc-coverage-baseline.json`) Cells are documented/total. `pub` = public/exported items (all kinds). "code" = lines excluding comments and blanks. Only `///` and `/** */` count as documentation; plain `//` does not. ``` unit files code mod fn type const pub doc/total % ------------------------------------------- ----- ------ --------- ---------- -------- -------- --------- ---------- ---- rust:(no crate) 3 70 3/3 0/2 0/1 0/1 3/3 3/7 42.9 rust:crates/infraternal 68 18424 85/90 173/721 27/72 7/38 147/181 292/921 31.7 rust:crates/infraternal-agent 68 23461 91/93 214/737 53/150 12/55 224/336 370/1035 35.7 rust:crates/infraternal-mesh 17 2859 18/18 37/128 33/44 7/7 94/127 95/197 48.2 rust:crates/infraternal-mesh/fuzz 1 86 1/1 0/1 0/0 0/0 1/1 1/2 50.0 rust:crates/infraternal-plugin-api 23 3774 27/30 114/215 61/84 18/32 212/253 220/361 60.9 rust:crates/infraternal-protocol 8 2567 8/8 14/81 10/13 7/8 39/42 39/110 35.5 rust:crates/infraternal-server 268 89497 299/328 736/2502 170/426 27/187 762/1097 1232/3443 35.8 rust:crates/infraternal-session 2 93 3/3 0/7 0/1 0/0 2/2 3/11 27.3 rust:crates/infraternal-shim 62 19440 100/105 198/789 28/76 27/78 216/348 353/1048 33.7 rust:crates/infraternal-status 10 2473 10/10 29/84 9/10 2/11 30/30 50/115 43.5 rust:crates/plugins/backup 2 101 3/3 1/2 0/0 1/1 4/4 5/6 83.3 rust:crates/plugins/canvas 7 1486 9/10 5/62 4/8 0/7 13/39 18/87 20.7 rust:crates/plugins/desktop 54 13523 61/70 85/380 17/128 4/34 148/222 167/612 27.3 rust:crates/plugins/host-facts 6 1123 7/7 13/49 8/10 2/12 28/28 30/78 38.5 rust:crates/plugins/mesh 68 21601 74/89 251/736 84/120 20/85 297/325 429/1030 41.7 rust:crates/plugins/mesh/fuzz 2 58 2/2 0/1 0/0 0/1 2/2 2/4 50.0 rust:crates/plugins/proxy 28 11087 28/30 86/420 42/88 9/63 146/163 165/601 27.5 rust:crates/plugins/relay 10 2579 14/15 41/121 21/30 15/45 69/70 91/211 43.1 rust:crates/plugins/release 10 1379 10/10 6/36 6/18 2/7 23/31 24/71 33.8 rust:crates/plugins/remote 26 10506 31/38 143/339 45/76 24/40 180/224 243/493 49.3 rust:crates/plugins/ssh 85 22724 92/102 238/702 100/193 8/49 346/443 438/1046 41.9 rust:fuzz 36 979 36/36 1/2 0/0 0/0 36/36 37/38 97.4 rust:research/mesh-engines/netlink-bench 3 479 3/3 0/22 0/1 0/10 3/3 3/36 8.3 rust:research/process-per-user/vt-carry 5 1861 6/7 32/104 3/14 1/7 32/40 42/132 31.8 rust:research/quic-stacks/harness 8 1829 8/8 13/59 2/9 0/10 21/45 23/86 26.7 rust:research/ssh-client/probe 2 136 2/2 0/5 0/1 0/0 2/2 2/8 25.0 swift:crates/plugins/desktop/native 12 1847 12/12 8/107 5/26 2/163 12/12 27/308 8.8 swift:crates/plugins/desktop/tests/fixtures 13 1129 13/13 1/34 0/16 0/23 13/13 14/86 16.3 ts:apps/release-signer/src 1 150 1/1 4/17 1/2 1/3 1/1 7/23 30.4 ts:apps/tracer 669 78612 626/669 882/2371 157/604 222/1295 1433/2470 1887/4939 38.2 ts:docs/verification/addhost-breakit2 5 145 5/5 0/0 0/0 0/17 5/5 5/22 22.7 ts:docs/verification/ca-update-audit 2 143 2/2 0/3 0/0 0/16 2/2 2/21 9.5 ts:packages/protocol 18 2489 17/18 37/112 26/44 3/16 82/126 83/190 43.7 ts:packages/ui 83 7601 72/83 174/301 32/165 52/193 267/475 330/742 44.5 ts:research/vnc/benchmark 1 268 1/1 0/3 0/0 0/18 1/1 1/22 4.5 ts:scripts 5 128 5/5 0/2 0/0 0/10 5/6 5/17 29.4 ts:scripts/browser-auth 13 2642 13/13 5/46 0/0 1/135 14/14 19/194 9.8 ts:scripts/hosts-from-server 1 91 1/1 0/0 0/0 0/8 1/1 1/9 11.1 ts:scripts/release 5 512 5/5 1/3 0/0 0/12 5/5 6/20 30.0 TOTAL 1710 349952 1804/1949 3542/11306 944/2430 474/2697 4921/7228 6764/18382 36.8 ``` What counts: modules (one per file plus inline Rust `mod x {}`), fns (free, methods, associated; not trait-impl methods, not fns nested in fn bodies), types, consts. Not counted: struct fields, enum variants, macros, vendor/, node_modules/, `*.d.ts`. Usage: `scripts/doc-coverage` (table), `--json [FILE]`, `--check` (the ratchet, exit 1 if any unit fell), `--update` (raise the baseline; refuses to lower it, `--force` overrides). The ratchet compares exact fractions per unit, so one new undocumented item in a fully documented crate fails. Jobs should not edit the baseline file (parallel branches would conflict); raise it after merges with `--update`. Runtime of the new `verify` row (`doc coverage ratchet`, fixture tests plus ratchet): 1.0 s on dev-02 (arm64, load 15), 5.9 s on compute01 (x86_64, load 39). Pure python, no build.

kayg commented

2026-11-04 10:20:17 +00:00

Author

Owner

Progress (J185): scanner, fixture tests, committed baseline and the doc coverage ratchet row in verify quick and fast are pushed (branch doc-coverage-j185, head 6704d5f46). Baseline table is in the comment above. verify quick/fast are queued on dev-02 (slot queue position about 7); log ~/j185-logs/{quick,fast}.log on dev-02. Will post the verbatim gate output when they finish.

Progress (J185): scanner, fixture tests, committed baseline and the `doc coverage ratchet` row in `verify quick` and `fast` are pushed (branch `doc-coverage-j185`, head `6704d5f46`). Baseline table is in the comment above. `verify quick`/`fast` are queued on dev-02 (slot queue position about 7); log `~/j185-logs/{quick,fast}.log` on dev-02. Will post the verbatim gate output when they finish.

kayg commented

2026-11-04 12:21:55 +00:00

Author

Owner

Finding (head 6704d5f46, scripts/verify fast on dev-02, exit 1): all rows PASS except test (101), a timing failure in code this branch does not touch (only scripts/ changed). Excerpt, verbatim:

1689:thread 'restart::tests::deleted_path_review::relative_recovery_after_atomic_install_keeps_live_install_path' (2675281) panicked at crates/infraternal/src/restart_deleted_path_review_tests.rs:74:13:
1690-replaced-path child did not complete

+---------------------------+--------------+
| Rust gate                 | Result       |
+---------------------------+--------------+
| fmt                       | PASS         |
| VT native fmt             | PASS         |
| CLI plugin compile-out    | PASS         |
| clippy                    | PASS         |
| SSH runtime test helper   | PASS         |
| real-binary fixture paths | PASS         |
| Traefik component manifest | PASS         |
| release component publication | PASS         |
| test                      | FAIL (101)   |
| SSH inode reuse fixture   | PASS         |
| shim process-per-user     | PASS         |
| cargo-deny                | PASS         |
| gate architecture         | PASS         |
| doc coverage ratchet      | PASS         |
| static builds             | PASS         |
+---------------------------+--------------+
VERIFY_EXIT=1

The child process hit HANG_BOUND after the infraternal bin tests took 236 s on a loaded VM (every other test in that run passed). Re-running that test alone through a slot to confirm it is load-related; will report.

kayg commented

2026-11-04 13:11:04 +00:00

Author

Owner

Finish (J185). Branch doc-coverage-j185, head 6704d5f46 (base origin/dev bb30a573b). Only scripts/ changed; baseline table is in the comment above.

scripts/verify quick passed (dev-02); the new row ran in 2 s there. scripts/verify fast (dev-02): every row PASS (fmt, VT fmt, clippy, doc coverage ratchet, static builds, cargo-deny, gate architecture, ...) except test (101), one timing failure restart::tests::deleted_path_review::relative_recovery_after_atomic_install_keeps_live_install_path ("replaced-path child did not complete", HANG_BOUND) in a run where the infraternal bin tests took 236 s on a loaded VM. Re-run alone: passes in 2.14 s. So fast is not fully green and I did not re-queue the whole gate (about 3 h of queue); I judge the failure load-related and unrelated to this change, but have not proved it flakes on unmodified origin/dev.

Verbatim:

quick scope vs merge base with origin/dev: workspace=0 packages=[] tracer=0

==> fmt
doc coverage ratchet: ok
(doc coverage ratchet: 2s)

+---------------------------+--------------+
| Rust gate                 | Result       |
+---------------------------+--------------+
| fmt                       | PASS         |
| doc coverage ratchet      | PASS         |
+---------------------------+--------------+

QUICK pre-check passed. This is not the gate: run scripts/verify fast before reporting done.
QUICK_EXIT=0
---
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 157 filtered out; finished in 2.14s

RERUN_EXIT=0
cleaned

Finish (J185). Branch `doc-coverage-j185`, head `6704d5f46` (base origin/dev `bb30a573b`). Only `scripts/` changed; baseline table is in the comment above. `scripts/verify quick` passed (dev-02); the new row ran in 2 s there. `scripts/verify fast` (dev-02): every row PASS (fmt, VT fmt, clippy, doc coverage ratchet, static builds, cargo-deny, gate architecture, ...) except `test` (101), one timing failure `restart::tests::deleted_path_review::relative_recovery_after_atomic_install_keeps_live_install_path` ("replaced-path child did not complete", `HANG_BOUND`) in a run where the `infraternal` bin tests took 236 s on a loaded VM. Re-run alone: passes in 2.14 s. So `fast` is not fully green and I did not re-queue the whole gate (about 3 h of queue); I judge the failure load-related and unrelated to this change, but have not proved it flakes on unmodified origin/dev. Verbatim: ``` quick scope vs merge base with origin/dev: workspace=0 packages=[] tracer=0 ==> fmt doc coverage ratchet: ok (doc coverage ratchet: 2s) +---------------------------+--------------+ | Rust gate | Result | +---------------------------+--------------+ | fmt | PASS | | doc coverage ratchet | PASS | +---------------------------+--------------+ QUICK pre-check passed. This is not the gate: run scripts/verify fast before reporting done. QUICK_EXIT=0 --- test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 157 filtered out; finished in 2.14s RERUN_EXIT=0 cleaned ```

kayg commented

2026-11-04 17:04:52 +00:00

Author

Owner

J210 owner-authorized housekeeping: closing this completed scope because its work is merged on dev in 092f7fd0a. Verified the merge commit is an ancestor of current origin/dev. The implementation reports and evidence remain in this issue.

J210 owner-authorized housekeeping: closing this completed scope because its work is merged on dev in [092f7fd0a](https://git.kayg.org/kayg/infraternal/commit/092f7fd0ae4fbeb2e7f6e4d8ba0945fc059f759b). Verified the merge commit is an ancestor of current origin/dev. The implementation reports and evidence remain in this issue.

kayg closed this issue

2026-11-04 17:04:53 +00:00

kayg referenced this issue

2026-11-04 17:07:06 +00:00

J210: overnight housekeeping, 2026-11-04 #350

No labels

launch-qa

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

kayg/infraternal#342

No description provided.

Rows
Columns

Doc-comment coverage (D345) #342

Baseline on origin/dev bb30a573b (committed as scripts/doc-coverage-baseline.json)

Baseline on origin/dev `bb30a573b` (committed as `scripts/doc-coverage-baseline.json`)