rvlib-shipkit 0.38.1 → 1.0.1

package/src/release/unit-gate.ts

@@ -1,21 +1,14 @@
-// what a single unit must prove before its version is written or published.
-// The ROOT unit is the repo, so `shipkit ci` already gates its tests and its
-// typecheck; this adds the per-unit proof only a SUB-unit lacks, because a
-// lib compiles and tests standalone under its own tsconfig and the root
-// tsconfig deliberately excludes it.
-import { existsSync } from 'fs'
-import { join } from 'path'
+// what a single unit must prove before its version is written or published,
+// beside the release gate. Its TESTS are not here: every unit has its own test
+// check, `test:<unit id>`, and the release gate runs it in the full tier
+// (run-release.ts runReleaseGate). Nor is its typecheck: `typecheck:<unit id>`
+// compiles it under its own tsconfig in that same gate. What stays is what no
+// check can say: the tree under the unit is committed, and a package bound for
+// npm has a tsconfig at all.
 import { dirtyPaths } from './git-facts.ts'
-import { resolveTypecheckProjects } from '../ts/tsconfig-projects.ts'
 import type { ReleaseUnit } from './units.ts'
 import type { RepoConfig } from '../repo-config.ts'
 
-/** the unit's own tsc: its node_modules, then the repo's, then PATH */
-export function resolveTsc(root: string, unit: ReleaseUnit): string | null {
-    for (const c of [join(unit.dir, 'node_modules/.bin/tsc'), join(root, 'node_modules/.bin/tsc')]) if (existsSync(c)) return c
-    return Bun.which('tsc')
-}
-
 /** the publish argv. `--access public` is not a default: npm restricts a
  *  scoped package unless it is asked, and a restricted publish looks
  *  successful right up until a consumer cannot install it. */
@@ -23,13 +16,6 @@ export function npmPublishArgv(o: { npmrc?: string | null } = {}): string[] {
     return ['npm', 'publish', '--access', 'public', ...(o.npmrc != null ? ['--userconfig', o.npmrc] : [])]
 }
 
-/** count of passing tests in a `bun test` run, or null when the output does
- *  not say — a suite whose result cannot be read is not a proven suite */
-export const passCount = (out: string): number | null => {
-    const m = out.match(/(\d+) pass/)
-    return m?.[1] != null ? Number(m[1]) : null
-}
-
 /** everything that must hold for this unit, checked before anything is
  *  written. Empty means the unit is releasable as far as the machine can tell. */
 export function unitBlockers(root: string, config: RepoConfig, unit: ReleaseUnit): string[] {
@@ -43,38 +29,5 @@ export function unitBlockers(root: string, config: RepoConfig, unit: ReleaseUnit
     }
     if (unit.targets.npm && unit.tsconfig == null)
         out.push(`unit '${unit.id}': publishes to npm but has no tsconfig.json — a package nobody typechecks standalone is a package that breaks on install`)
-    if (unit.id === 'root') return out
-
-    if (Bun.which('bun') == null) return [...out, 'bun is not on PATH']
-    const t = Bun.spawnSync(['bun', 'test'], { cwd: unit.dir })
-    const tOut = `${t.stdout.toString()}${t.stderr.toString()}`
-    if (t.exitCode !== 0) out.push(`unit '${unit.id}': its own test suite is red (exit ${t.exitCode}) — bun test in ${unit.rel}`)
-    else {
-        const pass = passCount(tOut)
-        if (pass == null || pass < 1) out.push(`unit '${unit.id}': its test suite ran 0 tests — a vacuous suite proves nothing, write a real one`)
-    }
-    if (unit.tsconfig != null) {
-        const tsc = resolveTsc(root, unit)
-        if (tsc == null) out.push(`unit '${unit.id}': tsc not resolvable — bun add -d typescript at the repo root`)
-        else {
-            // a solution-style tsconfig (`files: []` plus `references`) makes
-            // tsc compile ZERO files and exit 0, which would publish a package
-            // whose only proof of soundness was that nobody looked
-            let projects: ReturnType<typeof resolveTypecheckProjects> | null = null
-            try { projects = resolveTypecheckProjects(unit.tsconfig) }
-            catch (e) { out.push(`unit '${unit.id}': ${String((e as Error)?.message ?? e)}`) }
-            for (const m of projects?.missing ?? [])
-                out.push(`unit '${unit.id}': its tsconfig references '${m}', which does not exist, so whatever that project covered is unchecked`)
-            if (projects != null && projects.vacuous)
-                out.push(`unit '${unit.id}': its tsconfig compiles no files of its own and reaches no project that does, so a typecheck over it proves nothing — it cannot be published`)
-            for (const p of projects?.projects ?? []) {
-                const r = Bun.spawnSync([tsc, '--noEmit', '-p', p], { cwd: root })
-                if (r.exitCode !== 0) {
-                    const lines = `${r.stdout.toString()}${r.stderr.toString()}`.trim().split('\n').slice(0, 8).join('\n')
-                    out.push(`unit '${unit.id}': does not typecheck under ${p} — it cannot be published\n${lines}`)
-                }
-            }
-        }
-    }
     return out
 }

package/src/release/unit-resolve.ts

@@ -0,0 +1,282 @@
+// unit RESOLUTION, with no disk access of its own: every read goes through the
+// reader it is handed. release/units.ts hands it plain fs, a check hands it the
+// check context, so a check reading units stays keyed on what it read.
+import { basename, isAbsolute, join, relative } from 'path'
+import type { CheckCtx } from '../core/check-ctx.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import type { TestsConfig } from '../suite/judge-suites.ts'
+
+/** how resolution reads the disk, by repo-relative path. Plain fs by default,
+ *  the check context inside a check so every read lands in its read set */
+export type UnitReader = {
+    text: (rel: string) => string | null
+    exists: (rel: string, kind?: 'file' | 'dir') => boolean
+}
+
+/** the check context as a reader. A path outside the repo (a config pointing
+ *  a tsconfig at `../`) is not the repo's to read: it reads as absent, and the
+ *  answer is marked untracked rather than stored on reads that never saw it */
+export function checkUnitReader(c: CheckCtx): UnitReader {
+    const outside = (rel: string): boolean => isAbsolute(rel) || rel === '..' || rel.startsWith('../')
+    return {
+        text: (rel) => (outside(rel) ? (c.untrack(`read ${rel}, outside the repo`), null) : c.read(rel)),
+        // the root itself is the one path that cannot move under a check
+        exists: (rel, kind) => (rel === '' ? kind !== 'file' : outside(rel) ? (c.untrack(`probed ${rel}, outside the repo`), false) : c.exists(rel, kind)),
+    }
+}
+
+export type UnitDecl = {
+    /** repo-relative directory holding the unit's package.json — the only required key */
+    dir: string
+    /** default: basename(dir) */
+    id?: string
+    /** tag template, `{name}` and `{version}` substituted (default '{name}@{version}') */
+    tag?: string
+    /** repo-relative changelog (default '<dir>/CHANGELOG.md') */
+    changelog?: string
+    /** publish this sub-unit to npm. REQUIRED unless its package.json says
+     *  `private: true`: the npm target is declared, never inferred, and the
+     *  ambiguous package REFUSES rather than defaulting to the quiet answer.
+     *  `true` on a private package.json is a resolution FAILURE */
+    npm?: boolean
+    /** cut a GitHub release for this unit's tag (default false for sub-units) */
+    githubRelease?: boolean
+    /** repo-relative tsconfig for the unit's own typecheck, `typecheck:<unit id>`
+     *  and the release gate (default '<dir>/tsconfig.json' when it exists) */
+    tsconfig?: string
+    /** the unit's own suite budget, paths relative to the unit dir (suite/judge-suites.ts) */
+    tests?: TestsConfig
+    /** `false` = a unit that never releases and exists to scope its own checks:
+     *  a bench, a fixture app, an examples folder. Its tests run as
+     *  `test:<unit id>` in its own dir (own package.json script, bunfig,
+     *  preload, `tests` budget), its tsconfig as `typecheck:<unit id>`, and it
+     *  claims its dir for rule SK010, but `shipkit releases`, `bump`,
+     *  `release`, the npm checks and the per unit release gate never see it. Only
+     *  `dir`, `id`, `tests`, `tsconfig` and `deps` mean anything beside it */
+    release?: false
+    /** checks the unit's generated checks (`test:<unit id>`, `typecheck:<unit id>`)
+     *  wait for, by id: a check that says whether the world they need is
+     *  there (a local server binary, installed dependencies). A dep that warns
+     *  or fails SKIPS them with its reason, so a missing prerequisite reads as
+     *  a visible skip, never as a green or a red */
+    deps?: string[]
+}
+
+export const UNIT_DECL_KEYS: readonly string[] = ['dir', 'id', 'tag', 'changelog', 'npm', 'githubRelease', 'tsconfig', 'tests', 'release', 'deps']
+
+/** the only keys a `release: false` unit reads. Any other one describes a
+ *  release that never happens, so it is refused rather than ignored */
+export const TEST_ONLY_UNIT_KEYS: readonly string[] = ['dir', 'id', 'tests', 'tsconfig', 'deps', 'release']
+
+/** a unit declared `release: false`: it scopes tests and claims its dir, and
+ *  no release surface ever lists it */
+export type TestOnlyUnit = {
+    id: string
+    /** absolute */
+    dir: string
+    /** repo-relative */
+    rel: string
+}
+
+/** a unit, fully resolved: no optionals, no defaults left to re-apply downstream */
+export type ReleaseUnit = {
+    id: string
+    /** absolute */
+    dir: string
+    /** repo-relative git pathspec, '' for the root */
+    rel: string
+    name: string
+    /** package.json version — THE only version source */
+    version: string
+    /** absolute path to the versioned changelog */
+    changelog: string
+    /** tag template, `{name}` and `{version}` unsubstituted — bump renders the NEXT tag from it */
+    tagTemplate: string
+    /** rendered tag for the current version */
+    tag: string
+    /** the tag template with `{version}` replaced by `*` — feeds the stranded-tag probe */
+    tagGlob: string
+    targets: { npm: boolean; tag: boolean; githubRelease: boolean }
+    /** the unit's OWN package.json `private: true`, never the repo's visibility */
+    isPrivate: boolean
+    /** absolute path, or null when the unit has no tsconfig of its own */
+    tsconfig: string | null
+}
+
+/** a unit that could not be described, and why. Scoped by id because the two
+ *  cases differ: a broken DECLARED unit is a repo-wide declaration bug (rule
+ *  SK010), while a root package that is not release-shaped only matters the
+ *  day someone releases it. */
+export type UnitError = { id: string; message: string }
+
+export type UnitResolution = {
+    /** every unit that resolved — a broken sibling never hides the working ones */
+    units: ReleaseUnit[]
+    /** non-empty means no release of the named unit may proceed */
+    errors: UnitError[]
+    /** the units declared `release: false`, kept apart so no release surface
+     *  can list one by accident, and so rule SK010 still counts their dirs */
+    testOnly: TestOnlyUnit[]
+}
+
+export const formatUnitError = (e: UnitError): string => `unit '${e.id}': ${e.message}`
+
+const ROOT_TAG = 'v{version}'
+const SUB_TAG = '{name}@{version}'
+
+export const render = (template: string, p: { name: string; version: string }): string =>
+    template.replaceAll('{name}', p.name).replaceAll('{version}', p.version)
+
+export type Pkg = {
+    name?: string
+    version?: string
+    private?: boolean
+    scripts?: Record<string, string>
+    dependencies?: Record<string, string>
+    peerDependencies?: Record<string, string>
+    optionalDependencies?: Record<string, string>
+}
+
+export function readPkg(root: string, dir: string, io: UnitReader): { pkg: Pkg } | { error: string } {
+    const p = join(dir, 'package.json')
+    const text = io.text(relative(root, p))
+    if (text == null) return { error: `no package.json in ${dir}` }
+    try { return { pkg: JSON.parse(text) as Pkg } }
+    catch (e) { return { error: `${p} is unparseable (${String(e).slice(0, 120)})` } }
+}
+
+/** every releasable unit, root first then the declared sub-units in declared
+ *  order. Release ORDER is different (releaseOrder below) — the root ships
+ *  last because it depends on its sub-units, never the reverse. */
+export function resolveUnits(root: string, config: RepoConfig, io: UnitReader): UnitResolution {
+    const errors: UnitError[] = []
+    const units: ReleaseUnit[] = []
+    const testOnly: TestOnlyUnit[] = []
+    const rc = config.release ?? {}
+
+    const rootPkg = readPkg(root, root, io)
+    if ('error' in rootPkg) errors.push({ id: 'root', message: `${rootPkg.error} — release reads name and version from it` })
+    else {
+        const u = build({
+            root,
+            id: 'root',
+            dir: root,
+            pkg: rootPkg.pkg,
+            tagTemplate: rc.tag ?? ROOT_TAG,
+            changelogRel: rc.changelog ?? 'CHANGELOG.md',
+            npm: rc.npm,
+            // the root IS the repo: its package.json private flag is the whole
+            // declaration, and a public root package publishes by default
+            npmWhenUndeclared: 'from-private-flag',
+            githubRelease: rc.githubRelease ?? true,
+            tsconfigRel: rc.tsconfig,
+            checkFolderName: false,
+            io,
+        })
+        if ('error' in u) errors.push(...u.error)
+        else units.push(u.unit)
+    }
+
+    const seen = new Set<string>(['root'])
+    for (const decl of config.units ?? []) {
+        const id = decl.id ?? (typeof decl.dir === 'string' ? basename(decl.dir) : '?')
+        const bad = Object.keys(decl).filter((k) => !UNIT_DECL_KEYS.includes(k))
+        if (bad.length > 0) { errors.push({ id, message: `unknown key(s) ${bad.join(', ')} (known: ${UNIT_DECL_KEYS.join(', ')})` }); continue }
+        if (typeof decl.dir !== 'string' || decl.dir === '') { errors.push({ id, message: 'every units[] entry needs a `dir`' }); continue }
+        const dir = join(root, decl.dir)
+        if (!io.exists(relative(root, dir), 'dir')) { errors.push({ id, message: `'${decl.dir}' is not a directory` }); continue }
+        if (seen.has(id)) { errors.push({ id, message: `duplicate unit id — give '${decl.dir}' an explicit id` }); continue }
+        seen.add(id)
+        if ('release' in decl) {
+            if (decl.release !== false) { errors.push({ id, message: `\`release\` takes only \`false\` (a unit that never releases); drop the key for a unit that does` }); continue }
+            const idle = Object.keys(decl).filter((k) => !TEST_ONLY_UNIT_KEYS.includes(k))
+            if (idle.length > 0) { errors.push({ id, message: `release: false, so ${idle.join(', ')} describe(s) a release that never happens — drop them (a test only unit reads ${TEST_ONLY_UNIT_KEYS.join(', ')})` }); continue }
+            testOnly.push({ id, dir, rel: relative(root, dir) })
+            continue
+        }
+        const pkg = readPkg(root, dir, io)
+        if ('error' in pkg) { errors.push({ id, message: pkg.error }); continue }
+        const u = build({
+            root,
+            id,
+            dir,
+            pkg: pkg.pkg,
+            tagTemplate: decl.tag ?? SUB_TAG,
+            changelogRel: decl.changelog ?? `${decl.dir}/CHANGELOG.md`,
+            npm: decl.npm,
+            npmWhenUndeclared: 'refuse',
+            githubRelease: decl.githubRelease ?? false,
+            tsconfigRel: decl.tsconfig,
+            // only the DEFAULT tag renders the package name into a git tag, so
+            // only there does the folder have to agree with it
+            checkFolderName: decl.tag == null,
+            io,
+        })
+        if ('error' in u) errors.push(...u.error)
+        else units.push(u.unit)
+    }
+    return { units, errors, testOnly }
+}
+
+function build(p: {
+    root: string
+    id: string
+    dir: string
+    pkg: Pkg
+    tagTemplate: string
+    changelogRel: string
+    npm: boolean | undefined
+    /** how an UNDECLARED npm target resolves. The root IS the repo, so its
+     *  package.json private flag is the whole declaration. A sub-unit has no
+     *  such declaration, so a non-private package with no `npm` key is
+     *  ambiguous and REFUSES. */
+    npmWhenUndeclared: 'from-private-flag' | 'refuse'
+    githubRelease: boolean
+    tsconfigRel: string | undefined
+    checkFolderName: boolean
+    io: UnitReader
+}): { unit: ReleaseUnit } | { error: UnitError[] } {
+    const errors: UnitError[] = []
+    const at = (message: string): UnitError => ({ id: p.id, message })
+    const name = p.pkg.name ?? ''
+    const version = p.pkg.version ?? ''
+    if (name === '' || version === '') errors.push(at('package.json needs both name and version'))
+    // under the default template the package NAME becomes the git tag, so the
+    // folder it lives in must be findable from that tag. A scope satisfies it
+    // (`@acme/thing` in `thing/`), and an explicit `tag` opts out entirely.
+    const base = basename(p.dir)
+    if (p.checkFolderName && name !== '' && name !== base && !name.endsWith(`/${base}`))
+        errors.push(at(`package name '${name}' must equal the folder name '${base}' (a scope is fine: '@scope/${base}') — or declare an explicit \`tag\` for this unit`))
+    const isPrivate = p.pkg.private === true
+    // npm's own unconditional refusal. Declaring npm:true on top of it is a
+    // contradiction, not a preference — surface it instead of silently winning
+    if (p.npm === true && isPrivate)
+        errors.push(at('npm: true but package.json says private: true — drop one, npm refuses the publish either way'))
+    // "declared, never inferred" cuts BOTH ways: the package nobody decided
+    // about must refuse, not quietly resolve to no-publish. A silent false
+    // here is a lib that bumps, tags and cuts a release while publishing
+    // nothing, and the only trace is one note line in a long log.
+    if (p.npm == null && !isPrivate && p.npmWhenUndeclared === 'refuse')
+        errors.push(at('package.json is not private and this units[] entry does not say `npm` — add `npm: true` to publish it, or `private: true` to its package.json to keep it internal'))
+    if (errors.length > 0) return { error: errors }
+    const declaredNpm = p.npm ?? (p.npmWhenUndeclared === 'from-private-flag' && !isPrivate)
+    const tsconfig = p.tsconfigRel != null ? join(p.root, p.tsconfigRel) : join(p.dir, 'tsconfig.json')
+    return {
+        unit: {
+            id: p.id,
+            dir: p.dir,
+            rel: relative(p.root, p.dir),
+            name,
+            version,
+            changelog: join(p.root, p.changelogRel),
+            tagTemplate: p.tagTemplate,
+            tag: render(p.tagTemplate, { name, version }),
+            tagGlob: render(p.tagTemplate, { name, version: '*' }),
+            // the `!isPrivate` is a belt over the declaration: a private
+            // package never publishes, whatever anything else says
+            targets: { npm: declaredNpm && !isPrivate, tag: true, githubRelease: p.githubRelease },
+            isPrivate,
+            tsconfig: p.io.exists(relative(p.root, tsconfig)) ? tsconfig : null,
+        },
+    }
+}

package/src/release/units.ts

@@ -1,227 +1,35 @@
-// a repo is N releasable units. The ROOT unit is mandatory, never declared,
+// a repo is N units, and every one releases unless it says `release: false`. The ROOT unit is mandatory, never declared,
 // and configured by `release`. Sub-units are optional, exist only as entries
 // in `units[]`, and are configured by their own entry. Nothing is scanned
 // into existence: an undeclared package is caught by rule SK010, so
 // resolution stays deterministic and a forgotten package still cannot hide.
+// A `release: false` entry resolves into `testOnly`, never into `units`, so
+// no release surface can list one: it only scopes tests (suite/test-units.ts).
 //
 // This module is THE source of unit facts. Every surface that used to
 // rediscover packages (drift probes, per-lib tests, per-lib typecheck, the
 // stranded-tag probe) reads it instead of walking the tree with its own rules.
-import { existsSync, readFileSync, statSync } from 'fs'
-import type { TestsConfig } from '../suite/judge-suites.ts'
-import { basename, join, relative } from 'path'
+import { readFileSync, statSync } from 'fs'
+import { join } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
-
-export type ReleaseUnitDecl = {
-    /** repo-relative directory holding the unit's package.json — the only required key */
-    dir: string
-    /** default: basename(dir) */
-    id?: string
-    /** tag template, `{name}` and `{version}` substituted (default '{name}@{version}') */
-    tag?: string
-    /** repo-relative changelog (default '<dir>/CHANGELOG.md') */
-    changelog?: string
-    /** publish this sub-unit to npm. REQUIRED unless its package.json says
-     *  `private: true`: the npm target is declared, never inferred, and the
-     *  ambiguous package REFUSES rather than defaulting to the quiet answer.
-     *  `true` on a private package.json is a resolution FAILURE */
-    npm?: boolean
-    /** cut a GitHub release for this unit's tag (default false for sub-units) */
-    githubRelease?: boolean
-    /** repo-relative tsconfig for the unit's own typecheck (default '<dir>/tsconfig.json' when it exists) */
-    tsconfig?: string
-    /** the unit's own suite budget, paths relative to the unit dir (suite/judge-suites.ts) */
-    tests?: TestsConfig
-}
-
-export const UNIT_DECL_KEYS: readonly string[] = ['dir', 'id', 'tag', 'changelog', 'npm', 'githubRelease', 'tsconfig', 'tests']
-
-/** a unit, fully resolved: no optionals, no defaults left to re-apply downstream */
-export type ReleaseUnit = {
-    id: string
-    /** absolute */
-    dir: string
-    /** repo-relative git pathspec, '' for the root */
-    rel: string
-    name: string
-    /** package.json version — THE only version source */
-    version: string
-    /** absolute path to the versioned changelog */
-    changelog: string
-    /** tag template, `{name}` and `{version}` unsubstituted — bump renders the NEXT tag from it */
-    tagTemplate: string
-    /** rendered tag for the current version */
-    tag: string
-    /** the tag template with `{version}` replaced by `*` — feeds the stranded-tag probe */
-    tagGlob: string
-    targets: { npm: boolean; tag: boolean; githubRelease: boolean }
-    /** the unit's OWN package.json `private: true`, never the repo's visibility */
-    isPrivate: boolean
-    /** absolute path, or null when the unit has no tsconfig of its own */
-    tsconfig: string | null
-}
-
-/** a unit that could not be described, and why. Scoped by id because the two
- *  cases differ: a broken DECLARED unit is a repo-wide declaration bug (rule
- *  SK010), while a root package that is not release-shaped only matters the
- *  day someone releases it. */
-export type UnitError = { id: string; message: string }
-
-export type UnitResolution = {
-    /** every unit that resolved — a broken sibling never hides the working ones */
-    units: ReleaseUnit[]
-    /** non-empty means no release of the named unit may proceed */
-    errors: UnitError[]
-}
-
-export const formatUnitError = (e: UnitError): string => `unit '${e.id}': ${e.message}`
-
-const ROOT_TAG = 'v{version}'
-const SUB_TAG = '{name}@{version}'
-
-const render = (template: string, p: { name: string; version: string }): string =>
-    template.replaceAll('{name}', p.name).replaceAll('{version}', p.version)
-
-type Pkg = {
-    name?: string
-    version?: string
-    private?: boolean
-    scripts?: Record<string, string>
-    dependencies?: Record<string, string>
-    peerDependencies?: Record<string, string>
-    optionalDependencies?: Record<string, string>
-}
-
-function readPkg(dir: string): { pkg: Pkg } | { error: string } {
-    const p = join(dir, 'package.json')
-    if (!existsSync(p)) return { error: `no package.json in ${dir}` }
-    try { return { pkg: JSON.parse(readFileSync(p, 'utf8')) as Pkg } }
-    catch (e) { return { error: `${p} is unparseable (${String(e).slice(0, 120)})` } }
-}
-
-/** every releasable unit, root first then the declared sub-units in declared
- *  order. Release ORDER is different (releaseOrder below) — the root ships
- *  last because it depends on its sub-units, never the reverse. */
-export function resolveUnits(root: string, config: RepoConfig): UnitResolution {
-    const errors: UnitError[] = []
-    const units: ReleaseUnit[] = []
-    const rc = config.release ?? {}
-
-    const rootPkg = readPkg(root)
-    if ('error' in rootPkg) errors.push({ id: 'root', message: `${rootPkg.error} — release reads name and version from it` })
-    else {
-        const u = build({
-            root,
-            id: 'root',
-            dir: root,
-            pkg: rootPkg.pkg,
-            tagTemplate: rc.tag ?? ROOT_TAG,
-            changelogRel: rc.changelog ?? 'CHANGELOG.md',
-            npm: rc.npm,
-            // the root IS the repo: its package.json private flag is the whole
-            // declaration, and a public root package publishes by default
-            npmWhenUndeclared: 'from-private-flag',
-            githubRelease: rc.githubRelease ?? true,
-            tsconfigRel: rc.tsconfig,
-            checkFolderName: false,
-        })
-        if ('error' in u) errors.push(...u.error)
-        else units.push(u.unit)
-    }
-
-    const seen = new Set<string>(['root'])
-    for (const decl of config.units ?? []) {
-        const id = decl.id ?? (typeof decl.dir === 'string' ? basename(decl.dir) : '?')
-        const bad = Object.keys(decl).filter((k) => !UNIT_DECL_KEYS.includes(k))
-        if (bad.length > 0) { errors.push({ id, message: `unknown key(s) ${bad.join(', ')} (known: ${UNIT_DECL_KEYS.join(', ')})` }); continue }
-        if (typeof decl.dir !== 'string' || decl.dir === '') { errors.push({ id, message: 'every units[] entry needs a `dir`' }); continue }
-        const dir = join(root, decl.dir)
-        if (!existsSync(dir) || !statSync(dir).isDirectory()) { errors.push({ id, message: `'${decl.dir}' is not a directory` }); continue }
-        if (seen.has(id)) { errors.push({ id, message: `duplicate unit id — give '${decl.dir}' an explicit id` }); continue }
-        seen.add(id)
-        const pkg = readPkg(dir)
-        if ('error' in pkg) { errors.push({ id, message: pkg.error }); continue }
-        const u = build({
-            root,
-            id,
-            dir,
-            pkg: pkg.pkg,
-            tagTemplate: decl.tag ?? SUB_TAG,
-            changelogRel: decl.changelog ?? `${decl.dir}/CHANGELOG.md`,
-            npm: decl.npm,
-            npmWhenUndeclared: 'refuse',
-            githubRelease: decl.githubRelease ?? false,
-            tsconfigRel: decl.tsconfig,
-            // only the DEFAULT tag renders the package name into a git tag, so
-            // only there does the folder have to agree with it
-            checkFolderName: decl.tag == null,
-        })
-        if ('error' in u) errors.push(...u.error)
-        else units.push(u.unit)
-    }
-    return { units, errors }
-}
-
-function build(p: {
-    root: string
-    id: string
-    dir: string
-    pkg: Pkg
-    tagTemplate: string
-    changelogRel: string
-    npm: boolean | undefined
-    /** how an UNDECLARED npm target resolves. The root IS the repo, so its
-     *  package.json private flag is the whole declaration. A sub-unit has no
-     *  such declaration, so a non-private package with no `npm` key is
-     *  ambiguous and REFUSES. */
-    npmWhenUndeclared: 'from-private-flag' | 'refuse'
-    githubRelease: boolean
-    tsconfigRel: string | undefined
-    checkFolderName: boolean
-}): { unit: ReleaseUnit } | { error: UnitError[] } {
-    const errors: UnitError[] = []
-    const at = (message: string): UnitError => ({ id: p.id, message })
-    const name = p.pkg.name ?? ''
-    const version = p.pkg.version ?? ''
-    if (name === '' || version === '') errors.push(at('package.json needs both name and version'))
-    // under the default template the package NAME becomes the git tag, so the
-    // folder it lives in must be findable from that tag. A scope satisfies it
-    // (`@acme/thing` in `thing/`), and an explicit `tag` opts out entirely.
-    const base = basename(p.dir)
-    if (p.checkFolderName && name !== '' && name !== base && !name.endsWith(`/${base}`))
-        errors.push(at(`package name '${name}' must equal the folder name '${base}' (a scope is fine: '@scope/${base}') — or declare an explicit \`tag\` for this unit`))
-    const isPrivate = p.pkg.private === true
-    // npm's own unconditional refusal. Declaring npm:true on top of it is a
-    // contradiction, not a preference — surface it instead of silently winning
-    if (p.npm === true && isPrivate)
-        errors.push(at('npm: true but package.json says private: true — drop one, npm refuses the publish either way'))
-    // "declared, never inferred" cuts BOTH ways: the package nobody decided
-    // about must refuse, not quietly resolve to no-publish. A silent false
-    // here is a lib that bumps, tags and cuts a release while publishing
-    // nothing, and the only trace is one note line in a long log.
-    if (p.npm == null && !isPrivate && p.npmWhenUndeclared === 'refuse')
-        errors.push(at('package.json is not private and this units[] entry does not say `npm` — add `npm: true` to publish it, or `private: true` to its package.json to keep it internal'))
-    if (errors.length > 0) return { error: errors }
-    const declaredNpm = p.npm ?? (p.npmWhenUndeclared === 'from-private-flag' && !isPrivate)
-    const tsconfig = p.tsconfigRel != null ? join(p.root, p.tsconfigRel) : join(p.dir, 'tsconfig.json')
-    return {
-        unit: {
-            id: p.id,
-            dir: p.dir,
-            rel: relative(p.root, p.dir),
-            name,
-            version,
-            changelog: join(p.root, p.changelogRel),
-            tagTemplate: p.tagTemplate,
-            tag: render(p.tagTemplate, { name, version }),
-            tagGlob: render(p.tagTemplate, { name, version: '*' }),
-            // the `!isPrivate` is a belt over the declaration: a private
-            // package never publishes, whatever anything else says
-            targets: { npm: declaredNpm && !isPrivate, tag: true, githubRelease: p.githubRelease },
-            isPrivate,
-            tsconfig: existsSync(tsconfig) ? tsconfig : null,
-        },
-    }
+import { readPkg, render, resolveUnits as resolveWith, type Pkg, type ReleaseUnit, type UnitReader, type UnitResolution } from './unit-resolve.ts'
+
+export * from './unit-resolve.ts'
+
+export const fsUnitReader = (root: string): UnitReader => ({
+    text: (rel) => { try { return readFileSync(join(root, rel), 'utf8') } catch { return null } },
+    exists: (rel, kind) => {
+        try {
+            const st = statSync(join(root, rel))
+            return kind == null || (kind === 'dir' ? st.isDirectory() : st.isFile())
+        } catch { return false }
+    },
+})
+
+/** every releasable unit, read from the disk (release/unit-resolve.ts owns the
+ *  resolution and its order) */
+export function resolveUnits(root: string, config: RepoConfig, io: UnitReader = fsUnitReader(root)): UnitResolution {
+    return resolveWith(root, config, io)
 }
 
 /** publish order: sub-units first, the root last. The root depends on what
@@ -240,7 +48,7 @@ export function releaseOrder(units: ReleaseUnit[]): ReleaseUnit[] {
     const deps = new Map<string, Set<string>>()
     for (const u of subs) {
         const need = new Set<string>()
-        const read = readPkg(u.dir)
+        const read = readPkg(u.dir, u.dir, fsUnitReader(u.dir))
         const manifest: Pkg = 'error' in read ? {} : read.pkg
         for (const block of ['dependencies', 'peerDependencies', 'optionalDependencies'] as const)
             for (const dep of Object.keys(manifest[block] ?? {})) {
@@ -271,6 +79,13 @@ export function releaseOrder(units: ReleaseUnit[]): ReleaseUnit[] {
 
 export const unitById = (units: ReleaseUnit[], id: string): ReleaseUnit | undefined => units.find((u) => u.id === id)
 
+/** why `id` names no releasing unit. A `release: false` unit says so, rather
+ *  than reading as a typo */
+export function unknownUnit(r: UnitResolution, id: string): string {
+    if (r.testOnly.some((u) => u.id === id)) return `unit '${id}' is declared release: false, so it never releases (its tests run as test:${id})`
+    return `no unit '${id}' — releasing units: ${r.units.map((u) => u.id).join(', ')}`
+}
+
 /** the tag this unit WOULD carry at another version — bump needs it before it
  *  writes, to refuse on a tag that already exists */
 export const renderTag = (unit: ReleaseUnit, version: string): string => render(unit.tagTemplate, { name: unit.name, version })
@@ -290,6 +105,7 @@ export function prepublishScripts(scripts: Record<string, string>): string[] {
 /** the unit's own prepublish hooks, read from ITS package.json (a sub-unit's
  *  hooks are invisible to the root's) */
 export function unitPrepublishScripts(unit: ReleaseUnit): string[] {
-    const p = readPkg(unit.dir)
+    const p = readPkg(unit.dir, unit.dir, fsUnitReader(unit.dir))
     return 'error' in p ? [] : prepublishScripts(p.pkg.scripts ?? {})
 }
+