rvlib-shipkit 0.35.3 → 0.35.5

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.35.5
+
+- **The `TaskDef.inputs` doc comment stated only half the safety rule.** It said undeclared means never cached, so forgetting costs speed and never correctness, which is true for forgetting a whole task and false for the mistake that actually ships a false green: a list MISSING a path the command reads. The key cannot move when that path changes, so the answer replays over a tree it no longer describes. Observed twice in the field in one day. The comment now carries the asymmetry, names `['.']` as the declaration that cannot under declare, and says that a task carries no code closure, so the script it runs belongs in `inputs` too.
+- **`shipkit release` scopes its dirt check exactly like `shipkit bump`.** `bump` examined the released unit plus every package.json and lockfile a version commit can touch; `release` examined the WHOLE worktree, refused, and then named `shipkit release` as the fix, which refuses identically. Several agents share one checkout here, so a neighbour editing an unrelated package was enough to wedge a release with no way forward that the message described. The reason to refuse at all is unchanged and still applies inside the scope: `npm publish` packs the WORKING TREE rather than the commit, so a half written file inside the unit ships under a tag that describes something else. Dirt in another unit reaches neither the tarball nor the tag, and the refusal now says what it examined.
+
+## 0.35.4
+
+- **The imports refusal did not follow tsconfig `extends`, so a correctly configured repo went red and was told to add a key it already had.** Inheriting `paths` from a base config is the more common way to carry them, and only `references` was handled. `extends` is now followed (relative and node-resolved, chains and cycles included), and a mapping counts only when its TARGET is on disk: `"src/*": ["./packages/core/src/*"]` maps the prefix and resolves nothing. A package prefix is no longer accepted on the package DIRECTORY existing either, since a stale installed copy missing the file is the same false green one level up. `baseUrl` is no longer proof at all: tsc follows one, but rollup, esbuild and vite do not resolve a bare specifier through it, and the field failure this guard exists for was a rollup one. A multi-segment root (`packages/core`) is named as itself rather than as `packages`.
+- **The refusal prints once per REASON, not once per import site.** An unresolvable root is one repo-wide fact, and the case that hits it is a repo with ~150 imports, so the single actionable instruction was buried under 150 identical copies of itself. One line per reason now, with the count and the first two sites.
+- **`shipkit mv` refused to nest a sibling directory inside an existing one.** `git mv` moves a source directory INSIDE an existing destination rather than refusing, so a page whose sibling folder collided landed its probe one level too deep while the command printed ok. Reachable only once moves could cross directories.
+- **`shipkit mv` reads a link definition and a titled link as references**, resolves the `→` form only when it is EXPLICITLY relative (a bare target is a docs-root id in some trees and a file-relative path in others, and guessing corrupts one of them), requires a target to be a real FILE so prose naming a directory is not rewritten, and splices by index so a path containing `$&` is never read as a backreference.
+- The `mv` header comment no longer claims the token sweep has nothing left to corrupt. A path that merely ENDS with the old path is still rewritten by that sweep, the relative pass declines it on purpose, and the comment now says so instead of telling the next reader to stop looking.
+- The STATUS.md RED verdict no longer claims `1 FAIL line` when the body has none. A red exit with no FAIL line of its own is its own state and says so.
+
+- **The contract-folder repair asks the REPO whether the dotted name is ignored, instead of trusting a regex over a comment.** The candidate names come from the SK004 policy block, and three of them (`.rv-itch`, `.rv-steam`, `.rv-discord`) carry "ignored until the listing is live, override below the block". On a repo with a live listing those folders are TRACKED on purpose, so renaming an undotted one into them would have committed the removal of real files from the index, silently, inside somebody else's gate run. Now: untracked folders rename freely, since nothing can be lost, and a TRACKED one only renames when `git check-ignore` says this repo treats the dotted name as local.
+- **A repair that renamed and could not commit is REPORTED.** Silence is for a repair that completed. The hooks can refuse, `SHIPKIT_NO_AUTOCOMMIT=1` can be set, a merge can be in progress: the rename is still the right end state, and the dirt it leaves has to be traceable to the run that made it rather than surfacing as an unexplained refusal in the next bump.
+
 ## 0.35.3
 
 - **`shipkit mv` no longer resolves a link that climbs out of the repo.** The cross-directory pass rewrites references by resolving them against the file that carries them, and a target like `../../outside.md` resolves to somewhere on the wider disk, which `existsSync` will happily confirm. A reference that leaves the repo is not this repo's to retarget, so it is left exactly as written.
@@ -16,7 +33,7 @@
 
 - **The STATUS.md verdict counted the runner's own tally as a failure**, so N failing tasks always reported as N+1 (`RED — 2 FAIL lines` over one). `FAIL: 1/5 failed: cycles` is a line ABOUT the failures. A red exit with no FAIL line of its own also rendered `1 FAIL lines`, because the plural followed the number counted rather than the number shown. The header no longer asks to be committed either: SK004 ignores AND untracks this file, so the invitation sent readers into the state that fixer exists to undo.
 
-- **`shipkit start` wrote a stale package.json's name into `repo.config.ts`.** An adopted repo usually carries the manifest of whatever it was forked from, so a repo started as `voyager` got `name: 'bun-react-template'` in the one file every agent reads to learn what this repo IS. The name is on the command line and is the directory too, and `start` passes it now. With nothing to go on at all the DIRECTORY answers, rather than the `my-repo` placeholder that was waiting for someone not to notice it.
+- **`shipkit start` wrote a stale package.json's name into `repo.config.ts`.** An adopted repo usually carries the manifest of whatever it was forked from, so a repo adopted under its own name got the template's name in the one file every agent reads to learn what this repo IS. The name is on the command line and is the directory too, and `start` passes it now. With nothing to go on at all the DIRECTORY answers, rather than the `my-repo` placeholder that was waiting for someone not to notice it.
 
 - **The scaffolded `repo.config.ts` carried dash punctuation into repos that ban it.** It is authored by shipkit and lands as that repo's source, so its comments answer to that repo's comment style, and a scaffold is the one comment nobody rewrites, so it teaches the style of whatever wrote it. A test gates the shape.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.35.3",
+    "version": "0.35.5",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
     "type": "module",

package/src/core/repair-contract-dirs.ts

@@ -10,10 +10,14 @@
 // what needs taste or hands.
 //
 // The names come from the SK004 policy block, which is the one table that
-// already lists the always-ignored `.rv-*` contract folders. The TRACKED
-// contract dirs (`.rv-identity`, `.rv-assets`) stay out of it deliberately:
-// their own contract check reports them missing, so those never fail silently,
-// and a rename that untracks a tracked folder is not a repair.
+// already lists the `.rv-*` contract folders. The TRACKED contract dirs
+// (`.rv-identity`, `.rv-assets`) are not in it, and a rename that untracks a
+// tracked folder is not a repair, so the ignore is checked against THIS REPO
+// before anything moves: the venue names in that block carry "ignored until the
+// listing is live, override below the block", so a repo with a live listing
+// tracks `.rv-itch/` on purpose and a rename there would delete its files from
+// the index. `git check-ignore` answers for the repo instead of a regex
+// answering for a comment.
 import { readdirSync, renameSync, rmdirSync } from 'fs'
 import { join } from 'path'
 import { POLICY_LINES } from '../rules/SK004-gitignore-policy.ts'
@@ -62,7 +66,18 @@ const dirsIn = (root: string): string[] => {
     try { return readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name) } catch { return [] }
 }
 
-export type DirRepairResult = { renamed: DirRepair[]; removed: string[]; refusals: DirRefusal[] }
+export type DirRepairResult = { renamed: DirRepair[]; removed: string[]; refusals: DirRefusal[]; uncommitted: DirRepair[] }
+
+/** does THIS repo's ignore policy cover the dotted name (the index is not
+ *  consulted: the question is about the patterns, and the path does not exist yet) */
+const isIgnoredHere = (root: string, name: string): boolean =>
+    Bun.spawnSync(['git', 'check-ignore', '-q', '--no-index', `${name}/`], { cwd: root }).exitCode === 0
+
+/** does git track anything under this folder today */
+const isTracked = (root: string, name: string): boolean => {
+    const r = Bun.spawnSync(['git', 'ls-files', '--', name], { cwd: root })
+    return r.exitCode === 0 && r.stdout.toString().trim() !== ''
+}
 
 /**
  * Apply the plan. An EMPTY undotted folder is removed rather than renamed:
@@ -81,6 +96,7 @@ export function repairContractDirs(root: string): DirRepairResult {
     const plan = planContractDirRepairs(dirsIn(root))
     const renamed: DirRepair[] = []
     const removed: string[] = []
+    const uncommitted: DirRepair[] = []
     for (const r of plan.repairs) {
         const from = join(root, r.from)
         const to = join(root, r.to)
@@ -90,13 +106,28 @@ export function repairContractDirs(root: string): DirRepairResult {
                 removed.push(r.from)
                 continue
             }
+            // renaming TRACKED files into an ignored path takes them out of the
+            // index, which is the contract for a reflections folder and data
+            // loss for a live venue folder the repo tracks on purpose. So the
+            // untracking half only happens where the repo's own ignore policy
+            // says those files are local. Untracked files rename freely: there
+            // is nothing to lose and nothing to commit
+            const tracked = isTracked(root, r.from)
+            if (tracked && !isIgnoredHere(root, r.to)) continue
             renameSync(from, to)
             renamed.push(r)
-            machineCommit({ anchor: root, message: `chore(machine): rename ${r.from} to ${r.to}`, paths: [from] })
+            // a repair that half happened is not the silence that was asked
+            // for. the hooks can refuse, SHIPKIT_NO_AUTOCOMMIT can be set, a
+            // merge can be in progress: the rename is still the right end
+            // state, and the dirt it leaves has to be traceable to this run
+            // rather than surfacing as an unexplained refusal in the next bump
+            if (tracked && !machineCommit({ anchor: root, message: `chore(machine): rename ${r.from} to ${r.to}`, paths: [from] })) {
+                uncommitted.push(r)
+            }
         } catch {
             // a permission error or a race is not worth a red gate: the folder
             // stays where it is and the next run tries again
         }
     }
-    return { renamed, removed, refusals: plan.refusals }
+    return { renamed, removed, refusals: plan.refusals, uncommitted }
 }

package/src/core/run-fixers.ts

@@ -180,10 +180,18 @@ async function fixPassBody(root: string, config: RepoConfig, o: FixPassOpts, ver
     // ambiguous case reaches a human. Runs before the tree snapshot: the rename
     // lands in its own commit and is never counted as a fixer rewrite
     if (!verify) {
-        for (const r of repairContractDirs(root).refusals) {
+        const repaired = repairContractDirs(root)
+        for (const r of repaired.refusals) {
             o.print(`WARN ${r.from}/ and ${r.to}/ both exist — ${r.reason}`)
             o.print(`      fix: move the files into ${r.to}/ yourself, then delete ${r.from}/`)
         }
+        // silence is for a repair that COMPLETED. one that renamed and could
+        // not land the commit leaves dirt nobody can trace to a run they did
+        // not make, which is the failure the silence was meant to prevent
+        for (const r of repaired.uncommitted) {
+            o.print(`WARN renamed ${r.from}/ to ${r.to}/, and the commit did not land`)
+            o.print(`      fix: commit the removal of ${r.from}/ yourself — the files are in ${r.to}/`)
+        }
     }
     const { slots, unfilled, disabled } = resolveFixers(root, config)
     for (const u of unfilled) o.print(`skip: ${u.id} (${u.reason})`)

package/src/core/task-runner.ts

@@ -32,8 +32,14 @@ export type TaskDef = {
     timeoutMs?: number
     /** CONTENT population: the repo-relative paths this task reads. Declaring
      *  them is what makes the task keyable (ledger/git-key.ts). Undeclared is
-     *  the DEFAULT and means never cached, so forgetting costs speed and never
-     *  correctness. Declaring both this and `ttl` is a registration failure. */
+     *  the DEFAULT and means never cached, so forgetting a whole task costs
+     *  speed and never correctness. A list MISSING a path the command reads is
+     *  the one that costs correctness: the key cannot move when that path
+     *  changes, so the answer replays over a tree it no longer describes. Over
+     *  declaring costs a re-run, under declaring is a false green, and `['.']`
+     *  is the whole work tree and cannot under declare. A task carries no code
+     *  closure, so the script it runs belongs in here too.
+     *  Declaring both this and `ttl` is a registration failure. */
     inputs?: string[]
     /** WORLD population: this task reads the network, a keychain, $PATH or the
      *  clock, so nothing on disk describes its answer and a clean pass is

package/src/core/write-status.ts

@@ -41,11 +41,12 @@ export function writeStatus(root: string, s: StatusInput): StatusOutcome {
         // too, or a narrowed green hides behind a nag nobody reads twice
         const full = s.fullGate === true
         const scope = full ? 'clear to ship' : `${s.command} ran, not the whole gate`
-        // a red exit with no FAIL line of its own still reads RED, and the
-        // plural follows the number SHOWN, not the number counted
-        const shown = Math.max(fails, 1)
-        const verdict = s.exitCode !== 0 || fails > 0
-            ? `RED — ${shown} FAIL line${shown === 1 ? '' : 's'}. Fixes are printed under each FAIL.`
+        // a red exit with no FAIL line of its own is its OWN state: claiming a
+        // FAIL line sends the reader hunting for one that is not in the body
+        const verdict = fails > 0
+            ? `RED — ${fails} FAIL line${fails === 1 ? '' : 's'}. Fixes are printed under each FAIL.`
+            : s.exitCode !== 0
+            ? `RED — exit ${s.exitCode}, with no FAIL line of its own. The run died before it could report one.`
             : warns > 0
                 ? `GREEN with nags — ${warns} WARN. ${full ? 'Proceed.' : `${scope}.`}`
                 : `GREEN — ${scope}.`

package/src/mv/mv-md.ts

@@ -6,7 +6,7 @@
 // script it runs after the moves (repo-specific re-stamps). TS module moves
 // are a different concern (a TS-aware renamer owns import graphs).
 import { execSync } from 'child_process'
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs'
 import { basename, dirname, join, relative } from 'path'
 
 export type MvIo = { print: (l: string) => void; printErr: (l: string) => void }
@@ -15,18 +15,33 @@ export type MvOpts = { write?: boolean; commit?: boolean }
 const sh = (cmd: string, cwd: string): string => execSync(cmd, { cwd }).toString()
 
 const posix = (p: string): string => p.replace(/\\/g, '/')
+/** a link points at a file. A directory that happens to share a prose word's
+ *  spelling is not a reference, and existsSync alone accepts it */
+const isFile = (p: string): boolean => { try { return statSync(p).isFile() } catch { return false } }
 const dirOf = (p: string): string => { const d = dirname(p); return d === '.' ? '' : d }
 
 // A reference written RELATIVE to the file that carries it survives a same-dir
 // rename untouched, which is why sweeping path TOKENS was enough while moves
 // were confined to one directory. A move between directories invalidates both
 // directions at once: the links the page carries out, and the links other
-// pages aim at it. Sweeping tokens cannot fix either, and on a tail that
-// happens to match ('../doc/bun.md' carrying 'doc/bun.md') it corrupts them,
-// so this pass runs FIRST and leaves nothing for the token sweep to hit.
+// pages aim at it. This pass runs FIRST so the token sweep finds those already
+// rewritten.
+//
+// KNOWN RESIDUAL, do not read this as closed: the token sweep below is a
+// substring replace, so a path that merely ENDS with the old path
+// ('other/doc/bun.md' referenced as '../doc/bun.md' from a file that is not
+// moving) is still rewritten to a path that does not exist. This pass declines
+// that case on purpose, because neither the target nor the carrier moved.
+// Closing it means teaching the sweep which character spans were already
+// resolved here.
+//
+// A target must resolve to a FILE. Directories are excluded because the arrow
+// form appears in prose ('→ shipkit ci'), and a bare word that happens to name
+// a directory is not a link.
 const REF_FORMS: { re: RegExp; group: number }[] = [
-    { re: /\]\(([^)\s]+)\)/g, group: 1 }, // [text](target)
-    { re: /(→\s+)([^\s,;)`]+)/g, group: 2 }, // → target
+    { re: /\]\(([^)\s]+)(?=[)\s])/g, group: 1 }, // [text](target) and [text](target "Title")
+    { re: /^(\[[^\]]+\]:\s*)(\S+)/gm, group: 2 }, // [ref]: target, the link definition
+    { re: /(→\s+)(\.\.?\/[^\s,;)`]+)/g, group: 2 }, // → target, only when EXPLICITLY relative
     { re: /^(@)(\S+)$/gm, group: 2 }, // @target, the include line
 ]
 
@@ -48,8 +63,8 @@ export function retargetRelativeRefs(root: string, text: string, fromDir: string
         const to = moves.get(from)
         // nothing moved for this reference: neither its target nor its carrier
         if (to == null && fromDir === toDir) return null
-        // a target that is not a real path is prose, not a link
-        if (to == null && !existsSync(join(root, from))) return null
+        // a target that is not a real FILE is prose, not a link
+        if (to == null && !isFile(join(root, from))) return null
         const next = posix(relative(toDir, to ?? from))
         if (next === '') return null
         return `${path.startsWith('./') && !next.startsWith('.') ? `./${next}` : next}${anchor}`
@@ -59,7 +74,11 @@ export function retargetRelativeRefs(root: string, text: string, fromDir: string
         out = out.replace(re, (m, ...rest) => {
             const target = rest[group - 1] as string
             const next = fix(target)
-            return next == null ? m : m.replace(target, next)
+            // splice by INDEX, never a string replacement: a path carrying
+            // `$&` or `$1` would otherwise be interpreted as a backreference
+            if (next == null) return m
+            const at = m.lastIndexOf(target)
+            return at === -1 ? m : m.slice(0, at) + next + m.slice(at + target.length)
         })
     }
     return out
@@ -70,6 +89,13 @@ export function movePage(root: string, oldRel: string, newRel: string, io: MvIo,
     if (!oldRel.endsWith('.md') || !newRel.endsWith('.md')) return die('both paths must be .md (TS moves are not this tool\'s job)')
     if (!existsSync(join(root, oldRel))) return die(`${oldRel} does not exist`)
     if (existsSync(join(root, newRel))) return die(`${newRel} already exists`)
+    // git mv puts a source directory INSIDE an existing destination instead of
+    // refusing, so the probe lands one level too deep and the run still says
+    // ok. Unreachable while every move was a same-dir rename, likely the
+    // moment a move crosses directories
+    const oldSiblingDir = oldRel.slice(0, -3)
+    if (existsSync(join(root, oldSiblingDir)) && existsSync(join(root, newRel.slice(0, -3))))
+        return die(`${newRel.slice(0, -3)}/ already exists, and ${oldSiblingDir}/ would be nested inside it rather than become it — move or merge it by hand first`)
 
     const write = o.write === true || o.commit === true
     const oldName = basename(oldRel, '.md')

package/src/release/run-release.ts

@@ -11,6 +11,7 @@ import { join } from 'path'
 import { runCi } from '../core/run-ci.ts'
 import { extractChangelogSection } from './changelog.ts'
 import { deriveRemote, dirtyPaths, git, remoteTagState, tagExistsLocally, type RemoteTagState } from './git-facts.ts'
+import { releaseScope } from './release-scope.ts'
 import { npmPublishArgv, unitBlockers } from './unit-gate.ts'
 import { formatUnitError, resolveUnits, unitById, type ReleaseUnit } from './units.ts'
 import type { RepoConfig } from '../repo-config.ts'
@@ -172,9 +173,23 @@ export async function releaseUnit(root: string, config: RepoConfig, unit: Releas
     if (cur.code !== 0) blockers.push('not a git repository')
     else if (cur.out !== branch) blockers.push(`releases ship from '${branch}', HEAD is on '${cur.out}'`)
 
-    const dirty = dirtyPaths(root, config)
-    if (dirty !== '' && o.allowDirty !== true)
-        blockers.push(`working tree not clean (--allow-dirty overrides):\n${dirty.split('\n').slice(0, 10).join('\n')}`)
+    // scoped exactly like `bump`, and for the same reason: `npm publish` packs
+    // the WORKING TREE rather than the commit, so dirt INSIDE what ships can
+    // put a half written file under a tag that describes something else. Dirt
+    // in another unit reaches neither this tarball nor this tag. Checking the
+    // whole tree here made `release` refuse what `bump` allows, and then name
+    // `shipkit release` as the fix, which refuses identically: several agents
+    // share this checkout, so a neighbour editing an unrelated package was
+    // enough to wedge a release with no way forward that the message named.
+    // the sibling units matter to the SCOPE: a version write rewrites the
+    // rvlib range in every dependent's package.json, so those paths are inside
+    // this release even though they are outside this unit
+    const scope = releaseScope(root, resolveUnits(root, config).units, [unit])
+    const dirty = dirtyPaths(root, config, scope.specs ?? undefined)
+    if (dirty !== '' && o.allowDirty !== true) {
+        blockers.push(`uncommitted changes in ${scope.describe} (--allow-dirty overrides):\n${dirty.split('\n').slice(0, 10).join('\n')}`)
+        if (scope.specs != null) blockers.push('dirt elsewhere in the worktree is deliberately ignored, it cannot reach this tarball or this tag')
+    }
     if (o.skipUnitGate !== true) blockers.push(...unitBlockers(root, config, unit))
 
     let alreadyPublished = false

package/src/rules/SK013-one-way-in-policy.ts

@@ -130,7 +130,7 @@ export const oneWayInPolicy: Rule = {
         // replacement is named while the guard cannot run is the green that
         // measured nothing, one line under the WARN that says otherwise
         if (!t.failed)
-            t.ok(`${SETTINGS_PATH} closes ${want.length}/${RAW_RUNNERS.length} raw runner(s)${guardRuns ? ', with the replacement named' : ' — the guard that names the replacement is declared, not yet runnable'}`)
+            t.ok(`${SETTINGS_PATH} closes ${want.length}/${RAW_RUNNERS.length} raw runner(s)${guardRuns ? ', with the replacement named' : ' (the guard that names the replacement is declared, not yet runnable)'}`)
     },
     // MERGES, never rewrites: this file also carries the attribution silencer,
     // a repo's own allow list and its own hooks, and clobbering those to fix a

package/src/ts/imports.ts

@@ -62,58 +62,99 @@ export const clearExistsCache = (): void => {
 // reported by nobody, because this tool did not put it there and the
 // typechecker owns that verdict.
 
-type RepoResolution = { prefixes: Set<string>; baseDirs: string[] }
+/** one tsconfig `paths` entry, its targets already resolved against the config
+ *  file that DECLARED them. tsc resolves them there rather than at the root,
+ *  which is what makes `extends` work at all. */
+type PathEntry = { key: string; targets: string[] }
+type RepoResolution = { paths: PathEntry[] }
 const resolutionCache = new Map<string, RepoResolution>()
 
-/** every prefix the repo's own tsconfigs map, plus the baseUrls they set.
- *  Every `tsconfig*.json` at the root, because the standard vite shape keeps
- *  `paths` in a REFERENCED config and leaves the entry one empty. */
+/** the tsconfig an `extends` names: relative, or a package under node_modules.
+ *  `.json` is implied the way tsc implies it. */
+function resolveExtends(fromDir: string, root: string, spec: string): string | null {
+   const bases = spec.startsWith('.')
+      ? [resolve(fromDir, spec)]
+      : [join(root, 'node_modules', spec), join(root, 'node_modules', spec, 'tsconfig.json')]
+   for (const b of bases) for (const c of [b, `${b}.json`]) if (cachedExists(c)) return c
+   return null
+}
+
+/** every `paths` entry the repo declares, following `extends` as tsc does.
+ *  Every `tsconfig*.json` at the ROOT, because the standard vite shape keeps
+ *  its mappings in a REFERENCED config and leaves the entry one empty.
+ *
+ *  `baseUrl` is deliberately NOT proof. tsc follows one, but rollup, esbuild
+ *  and vite do not resolve a bare specifier through baseUrl alone, and the
+ *  field failure this guard exists for was a rollup one. Accepting it would
+ *  re-open the same bug in a narrower shape. */
 function repoResolution(root: string): RepoResolution {
    const hit = resolutionCache.get(root)
    if (hit != null) return hit
-   const prefixes = new Set<string>()
-   const baseDirs: string[] = []
+   const paths: PathEntry[] = []
+   const seen = new Set<string>()
+   const visit = (file: string): void => {
+      if (seen.has(file) || !cachedExists(file)) return // a cycle terminates here
+      seen.add(file)
+      let parsed: { extends?: unknown; compilerOptions?: { paths?: Record<string, unknown> } }
+      try {
+         parsed = parseJsonc(readFileSync(file, 'utf8')) as typeof parsed
+      } catch {
+         return // an unparseable tsconfig maps nothing, it does not map everything
+      }
+      const dir = dirname(file)
+      for (const [key, targets] of Object.entries(parsed.compilerOptions?.paths ?? {}))
+         if (Array.isArray(targets)) paths.push({ key, targets: targets.filter((t): t is string => typeof t === 'string').map((t) => toPosix(resolve(dir, t))) })
+      // an INHERITED mapping is the more common way to carry `paths`, and a
+      // repo that has one is correctly configured: refusing there would be
+      // this tool telling a working repo to add a key it already has
+      for (const e of Array.isArray(parsed.extends) ? parsed.extends : [parsed.extends])
+         if (typeof e === 'string') { const next = resolveExtends(dir, root, e); if (next != null) visit(next) }
+   }
    let names: string[] = []
    try {
       names = readdirSync(root).filter((n) => /^tsconfig(\..+)?\.json$/.test(n))
    } catch {
       // unreadable root: nothing is mapped, and every rewrite refuses loudly
    }
-   for (const n of names) {
-      let parsed: { compilerOptions?: { paths?: Record<string, unknown>; baseUrl?: unknown } }
-      try {
-         parsed = parseJsonc(readFileSync(join(root, n), 'utf8')) as typeof parsed
-      } catch {
-         continue // an unparseable tsconfig maps nothing, it does not map everything
-      }
-      const co = parsed.compilerOptions
-      for (const k of Object.keys(co?.paths ?? {})) prefixes.add(k.endsWith('/*') ? k.slice(0, -2) : k)
-      if (typeof co?.baseUrl === 'string') baseDirs.push(co.baseUrl)
-   }
-   const r = { prefixes, baseDirs }
+   for (const n of names) visit(join(root, n))
+   const r = { paths }
    resolutionCache.set(root, r)
    return r
 }
 
-/** the prefix a canonical specifier is rooted at: a discovered package's NAME
- *  (a scoped one carries a slash of its own, so splitting on '/' is wrong),
- *  else the leading segment */
-const specifierPrefix = (spec: string, cfg: RvtConfig): string =>
-   cfg.packages.find((p) => spec === p.name || spec.startsWith(`${p.name}/`))?.name ?? spec.split('/')[0]!
+/** can the repo resolve THIS specifier? The mapped target is checked on disk
+ *  rather than the prefix alone: `"src/*": ["./packages/core/src/*"]` maps the
+ *  prefix and still resolves nothing, and a stale `node_modules/<pkg>` missing
+ *  the file is the same false green one level up. */
+function repoCanResolve(spec: string, cfg: RvtConfig): boolean {
+   for (const { key, targets } of repoResolution(cfg.root).paths) {
+      if (key.endsWith('/*')) {
+         const p = key.slice(0, -2)
+         if (!spec.startsWith(`${p}/`)) continue
+         const rest = spec.slice(p.length + 1)
+         for (const t of targets) if (cachedExists(t.replace('*', rest))) return true
+      } else if (spec === key) {
+         for (const t of targets) if (cachedExists(t)) return true
+      }
+   }
+   // plain node resolution, which is what an npm consumer of the published
+   // source uses. The FILE, never merely the package directory
+   return cachedExists(join(cfg.root, 'node_modules', spec))
+}
 
-function repoCanResolve(prefix: string, cfg: RvtConfig): boolean {
-   const { prefixes, baseDirs } = repoResolution(cfg.root)
-   if (prefixes.has(prefix)) return true
-   if (baseDirs.some((b) => cachedExists(join(cfg.root, b, prefix)))) return true
-   // a package name also answers to plain node resolution, which is what an
-   // npm consumer of the published source will use
-   return cachedExists(join(cfg.root, 'node_modules', prefix))
+/** what the refusal NAMES: a discovered package (a scoped name carries a slash
+ *  of its own), else the longest configured root the specifier sits under, so
+ *  a multi-segment root like `packages/core` is not reported as `packages`. */
+function specifierPrefix(spec: string, cfg: RvtConfig): string {
+   const pkg = cfg.packages.find((p) => spec === p.name || spec.startsWith(`${p.name}/`))
+   if (pkg != null) return pkg.name
+   return [...cfg.roots].sort((a, b) => b.length - a.length).find((r) => spec.startsWith(`${r}/`)) ?? spec.split('/')[0]!
 }
 
 const unresolvableReason = (prefix: string, isPackage: boolean): string =>
    isPackage
-      ? `nothing resolves '${prefix}': install or link the package, or map "${prefix}/*" in compilerOptions.paths (tsconfig.json). Rewriting first would resolve on disk and nowhere else`
-      : `the repo maps nothing onto '${prefix}/': add "${prefix}/*": ["./${prefix}/*"] to compilerOptions.paths (tsconfig.json), plus the matching bundler alias. Rewriting first would resolve on disk and nowhere else`
+      ? `nothing resolves '${prefix}': install or link the package, or map "${prefix}/*" in compilerOptions.paths. Rewriting first would resolve on disk and nowhere else`
+      : `the repo maps nothing onto '${prefix}/': add "${prefix}/*": ["./${prefix}/*"] to compilerOptions.paths (any tsconfig at the root, or one it extends), plus the matching bundler alias. Rewriting first would resolve on disk and nowhere else`
 
 function resolveFileExtension(absPath: string): string | null {
    if (/\.(d\.ts|tsx?|json)$/.test(absPath) && cachedExists(absPath)) return absPath
@@ -198,7 +239,7 @@ export function rewriteFile(filePath: string, cfg: RvtConfig, save: boolean): Im
       }
       if (next === specifier) return null
       const prefix = specifierPrefix(next, cfg)
-      if (!repoCanResolve(prefix, cfg)) {
+      if (!repoCanResolve(next, cfg)) {
          pushError(lineNum, specifier, unresolvableReason(prefix, cfg.packages.some((p) => p.name === prefix)))
          return null
       }
@@ -311,6 +352,17 @@ export function runImports(opts: { save?: boolean; files?: string[]; cfg?: RvtCo
    return run
 }
 
+/** one entry per distinct reason, sites in the order they were found */
+function groupByReason(errors: ImportsRun['errors']): Map<string, ImportsRun['errors']> {
+   const out = new Map<string, ImportsRun['errors']>()
+   for (const e of errors) {
+      const at = out.get(e.reason)
+      if (at == null) out.set(e.reason, [e])
+      else at.push(e)
+   }
+   return out
+}
+
 // modes: (none)=preview · --check = CI gate (exit 1 if anything would change)
 // · --fix = rewrite in place · <file...> = fix exactly these files (on-save hook)
 export function importsCli(argv: string[]): number {
@@ -326,7 +378,14 @@ export function importsCli(argv: string[]): number {
    for (const r of run.missingRoots) console.log(`  WARN configured root '${r}' does not exist — drop it from package.json "rvt".roots or create it`)
    if (run.scanned === 0)
       console.log(`  scanned 0 files — roots (${run.roots.join(', ')}) hold no .ts/.tsx; this gate is checking NOTHING${check ? ', which fails the gate' : ''}`)
-   for (const e of run.errors) console.log(`  ${e.file}:${e.line} -> '${e.specifier}' (${e.reason})`)
+   // grouped by REASON: an unresolvable root is ONE repo-wide fact, and the
+   // field case is ~150 imports, so a line per site buries the one instruction
+   // under its own repetition
+   for (const [reason, sites] of groupByReason(run.errors)) {
+      console.log(`  ${reason}`)
+      const shown = sites.slice(0, 2).map((e) => `${e.file}:${e.line} -> '${e.specifier}'`).join(', ')
+      console.log(`    ${sites.length} import(s), e.g. ${shown}${sites.length > 2 ? `, +${sites.length - 2} more` : ''}`)
+   }
    if (check && run.changes > 0) console.log('non-absolute imports found — run `rvt imports --fix` and commit the result.')
    return run.errors.length > 0 || (check && (run.changes > 0 || run.scanned === 0)) ? 1 : 0
 }