panates / rman / 36055998623

95%

main: 95%

Pull #30

github

docs(claude): the Platform/Plugin split, the walk, the selector, and what the suite cannot see

Six things this session measured that CLAUDE.md had no place for, and one
heading that had stopped being true.

**`Platform` is the narrow type, `Plugin` the broad one** - and the brand that
tells a 2.x contribution from an rman 1.x plugin cannot be a module-scope
`const`: the file-layout rule puts privates below the exports, and
`basePlatform`'s initializer calls `definePlatform`, so it sits in its own TDZ.
The whole suite failed to load.

**Discovery walks the tree.** The workspace seam was recorded here as a known
limitation ("per-repository discovery is not polyglot yet"); that paragraph is
now what replaced it. With it: `Package` is handed its platform at construction,
`children` is enumerable and `parent` is not, and `declare readonly parent?` is
load-bearing - a plain declaration is a class field, so every package got an
enumerable `undefined` and `Object.keys(rootPackage)` listed `parent` while
`Object.keys(pkg-a)` did not.

**A selector addresses a package; a name is what it calls itself.** Plus the
two keys a glob block cannot carry, and `"[/]"` needing no selector - which did
not work, so `platform` under `"[/]"` silently did nothing.

**A root `platform` naming a built-in brings it**, at the front of `plugins`,
and "at the front" is only observable with two built-ins - rman ships one, so a
control swapping the ends passes until a second is stubbed in.

**`npm run smoke` is a section of its own**, because the reason it exists is
structural rather than incidental: mocha resolves `rman` to `src` through a
different module graph, and the test tsconfig includes every source file. An ESM
cycle fatal in `build/` and an augmentation that reaches rman and nobody else
were both live at once, with 843 specs green. The second cannot be pinned by a
spec at all.

The docs heading is "two reference files" now, with a note not to recreate the
two that were dele... (continued)

2490 of 2747 branches covered (90.64%)

Branch coverage included in aggregate %.

7000 of 7177 new or added lines in 75 files covered. (97.53%)

15482 of 16183 relevant lines covered (95.67%)

156.35 hits per line