rvlib-shipkit 2.0.2 → 2.1.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2.1.1
+
+- **`--only a,b` takes a comma list** in `sk ci`, `sk cache-audit` and `sk fleet`, the same as repeating the flag.
+- **`sk gp start` waits for pm to act.** The state the switch leaves (down for a start, up for a stop) counts as pm not there yet for 30 s, so a process that takes a few seconds to launch no longer reads as down. A crash still fails at once.
+- **`sk mv` rewrites relative markdown links on a folder move**, through the same pass the page move uses, and a page move no longer crashes on a repo with a git submodule.
+
+## 2.1.0
+
+- **SK027 requires exhaustive agent/ indexes.** Every `agent/` page is listed by an index (a bullet, numbered item, table row, `→` pointer or `@` include names it or its folder), and every index is loaded from CLAUDE.md or listed by a loaded file. A page linked only from prose now fails, with the page that already names it as the fix. The template's house `[lint]` block makes `typescript/no-empty-object-type` an error.
+- **The store sweep clears what it measures.** A job past its 7 day keep window is swept even when its pid is alive, because a pid that old has been reused. The answers measure leaves out the forever answers the sweep keeps, so a decided fact never reads as over cap.
+- **SK031 states a task it cannot trace as one note.** A binary macOS will not trace is the platform, so it no longer prints one WARN per task.
+
 ## 2.0.2
 
 - **SK001 clears its own lint shadow.** A `lint` or `fmt` script that routes through `shipkit ci` beside the bunfig section of the same name is deleted by the repair, with its `:raw` half, so `bun lint` runs the built-in. A script whose body is a tool stays named for a human.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "2.0.2",
+    "version": "2.1.1",
     "funding": "https://github.com/sponsors/rvion",
     "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",

package/src/checks/SK027-agent-wiki-links.check.ts

@@ -1,42 +1,50 @@
 // SK027 agent wiki links (build/shipkit/built-in-checks.md): a repo's agent/
-// IS an md wiki (entry index.md, the CLAUDE.md include), so an orphan page or
-// a dangling ref there fails. A link that leaves agent/ but stays in the repo
-// is checked on disk; a pointer out of the repo (a house wiki) is backticked,
+// IS an md wiki, entered by agent/index.md. Every page is LISTED by an index
+// (src/wiki/agent-index.ts: one bullet, numbered item, table row or @ include
+// names it or its folder), every index is in sight of what a session loads,
+// and a dangling ref fails. A link that leaves agent/ but stays in the repo is
+// checked on disk; a pointer out of the repo (a house wiki) is backticked,
 // never a bare → or @. A repo without agent/index.md skips.
-// agent/global-contribution.md is no orphan: the house index links it (SK033).
+// agent/global-contribution.md is listed by the house index (SK033), never agent/'s.
 import { existsSync, readFileSync } from 'fs'
-import { basename, join } from 'path'
+import { basename, dirname, join } from 'path'
 import { check } from '../check.ts'
 import { CONTRIBUTION_FILE } from '../core/global-contribution.ts'
+import { indexCovers, indexesOutOfSight, loadedFiles, unlisted } from '../wiki/agent-index.ts'
 import { lintMd } from '../wiki/lint-md.ts'
 
 export const agentWikiLinks = check({
     id: 'SK027',
     blocking: true,
     title: 'agent wiki links',
-    description: 'every agent/ page is linked from somewhere, and every agent/ link resolves',
+    description: 'every agent/ page is listed by an index a session sees, and every agent/ link resolves',
     owner: 'meta/agent-folder.md',
     runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
-    // the md lint walks agent/ on disk rather than through `c`: agent/ is all it reads
-    cache: { by: 'files', inputs: ['agent'], key: null },
+    // the md lint walks agent/ on disk rather than through `c`; the loaded context starts at CLAUDE.md
+    cache: { by: 'files', inputs: ['agent', 'CLAUDE.md', 'CLAUDE.local.md'], key: null },
     fix: 'none',
     applies: 'always',
     run: (c) => {
         if (!existsSync(join(c.root, 'agent/index.md'))) return void c.lines.push({ kind: 'skip', text: 'no agent/ wiki in this repo' })
         const lint = lintMd({ root: join(c.root, 'agent'), index: 'index.md', boundary: c.root })
-        // the global contribution is the house index's to link (SK033), never agent/'s
-        const orphans = lint.orphans.filter((f) => `agent/${f}` !== CONTRIBUTION_FILE)
-        const linked = lint.pages.filter((p) => !orphans.includes(p))
-        for (const f of orphans) {
-            const by = namingPage(c.root, f, linked)
-            const where = by != null ? `${by}, which already names it (turn that mention into the link)` : 'agent/index.md or the page of its topic'
-            c.fail(`agent/${f}: orphan, unreachable from agent/index.md: add a markdown link to it from ${where}; delete it only if the page is dead`, { at: { file: `agent/${f}` } })
+        const read = (p: string): string | null => {
+            try { return readFileSync(join(c.root, p), 'utf8') } catch { return null }
         }
+        const pages = new Map(lint.pages.map((p) => [`agent/${p}`, read(`agent/${p}`) ?? '']))
+        const folders = new Set([...pages.keys()].map((p) => dirname(p)))
+        for (const f of unlisted(pages, new Set([CONTRIBUTION_FILE]))) {
+            // only an index that can list the page is worth naming as the fix
+            const by = namingPage(c.root, f.slice('agent/'.length), lint.pages.filter((p) => indexCovers(`agent/${p}`, f, folders)))
+            const where = by != null ? `${by}, which already names it (make that mention a listing line)` : 'agent/index.md or the index of its folder'
+            c.fail(`${f}: no index lists it: add one bullet or table row naming it to ${where}; delete it only if the page is dead`, { at: { file: f } })
+        }
+        for (const f of indexesOutOfSight(pages, loadedFiles(read), read))
+            c.fail(`${f}: an index no session sees: list it on one line of agent/index.md (or another loaded index), or include it with @`, { at: { file: f } })
         for (const d of lint.dangling) {
             const file = `agent/${d.from}`
             c.fail(`${file}:${d.line}: dangling ref → ${d.token}, target not found on disk: fix the path or delete the pointer (a pointer out of this repo, into a house wiki or another repo, goes in backticks)`, { at: { file, line: d.line } })
         }
-        if (!c.failed) c.ok('agent/ has no orphans and no dangling refs')
+        if (!c.failed) c.ok(`agent/: ${pages.size} pages, each listed by an index in sight; no dangling refs`)
     },
 })
 

package/src/checks/SK031-trace-audit.check.ts

@@ -27,7 +27,9 @@ export const traceAuditCheck = check({
         let out: { skipped?: string; tasks: { id: string; status: string; why?: string; uncovered: string[]; propose: string[] }[] }
         try { out = JSON.parse(r.out.trim().split('\n').at(-1) ?? '') } catch { return c.fail(`sk trace-audit did not answer (exit ${r.code}: ${r.out.trim().slice(0, 160)})`) }
         if (out.skipped != null) return c.note(`nothing traced: ${out.skipped}`)
-        for (const t of out.tasks.filter((x) => x.status === 'unaudited')) c.warn(`${t.id} could not be audited: ${t.why}`)
+        // a binary macOS will not trace is the platform, never the repo: nobody can clear it, so it is a note
+        const unaudited = out.tasks.filter((x) => x.status === 'unaudited').map((x) => x.id)
+        if (unaudited.length > 0) c.note(`${unaudited.length} task(s) not auditable here, a binary ran untraced (macOS traces no system binary): ${unaudited.join(', ')}`)
         const missing = out.tasks.filter((x) => x.uncovered.length > 0)
         // a finding joins its task's key at once (core/audit-report.ts), so it
         // is news, never a failure: SK032 carries it into repo.config.ts

package/src/cli/cmd_CacheAudit.ts

@@ -4,6 +4,7 @@
 import { Command, Option } from 'clipanion'
 import { loadRepoConfig } from '../repo-config.ts'
 import { auditCache } from '../core/cache-audit.ts'
+import { listFlag } from './list-flag.ts'
 
 export class CacheAuditCommand extends Command {
     static override paths = [['cache-audit']]
@@ -28,9 +29,9 @@ export class CacheAuditCommand extends Command {
         const root = process.cwd()
         const n = Number(this.sample)
         if (!Number.isInteger(n) || n < 1) { this.context.stdout.write(`FAIL: --sample takes a whole number above 0, got '${this.sample}'\n`); return 1 }
-        const r = await auditCache(root, await loadRepoConfig(root), { sample: n, only: this.only })
+        const r = await auditCache(root, await loadRepoConfig(root), { sample: n, only: this.only == null ? undefined : listFlag(this.only) })
         if (this.json) { this.context.stdout.write(`${JSON.stringify(r)}\n`); return r.stale.length > 0 ? 1 : 0 }
-        if (r.rows.length === 0) { this.context.stdout.write(`skip: nothing to audit, the cache answers none of ${this.only?.join(', ') ?? 'the checks'} right now\n`); return 0 }
+        if (r.rows.length === 0) { this.context.stdout.write(`skip: nothing to audit, the cache answers none of ${this.only == null ? 'the checks' : listFlag(this.only).join(', ')} right now\n`); return 0 }
         for (const row of r.rows) {
             const same = row.fresh === row.cached || row.fresh === 'skip'
             this.context.stdout.write(same

package/src/cli/cmd_Ci.ts

@@ -7,6 +7,7 @@ import { runJob } from '../core/job-run.ts'
 import { runCi } from '../core/run-ci.ts'
 import { runViaHub } from '../home/via-hub.ts'
 import { maybeSelfUpdateAndRestart } from '../core/self-update.ts'
+import { listFlag } from './list-flag.ts'
 
 export class CiCommand extends Command {
     static override paths = [['ci']]
@@ -37,7 +38,7 @@ export class CiCommand extends Command {
     frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for self-maintaining checks: SK005 never touches package.json, and generated paths are never untracked. STATUS.md is still refreshed on disk, but it is gitignored, so a run leaves the tree clean' })
     skip = Option.Array('--skip', [], { description: 'skip a check group (repeatable)' })
     withIds = Option.Array('--with', [], { description: 'include a check the quick gate leaves out (repeatable)' })
-    only = Option.Array('--only', [], { description: 'run only this check + its dep closure (repeatable). A group name runs every check declaring that group. No repair pass unless --fix is named' })
+    only = Option.Array('--only', [], { description: 'run only this check + its dep closure (repeatable, or comma separated). A group name runs every check declaring that group. No repair pass unless --fix is named' })
     fresh = Option.Boolean('--fresh', false, { description: 'run every check: no answer comes from the cache, and what this run finds is stored fresh' })
     full = Option.Boolean('--full', false, { description: `run the FULL test tier: every suite the repo declares, the slow ones it skips while you work included. What the release path always runs. Same as SHIPKIT_TEST_FULL=1` })
 
@@ -74,7 +75,7 @@ export class CiCommand extends Command {
             ...(this.frozen ? ['--frozen'] : []),
             ...this.skip.flatMap((v) => ['--skip', v]),
             ...this.withIds.flatMap((v) => ['--with', v]),
-            ...this.only.flatMap((v) => ['--only', v]),
+            ...listFlag(this.only).flatMap((v) => ['--only', v]),
             ...(this.fresh ? ['--fresh'] : []),
             ...(this.full ? ['--full'] : []),
             ...(this.verbose ? ['--verbose'] : []),
@@ -95,7 +96,7 @@ export class CiCommand extends Command {
                 frozen: this.frozen,
                 skipGroups: this.skip,
                 withIds: this.withIds,
-                onlyIds: this.only,
+                onlyIds: listFlag(this.only),
                 fresh: this.fresh,
                 ...(this.full ? { tests: 'full' as const } : {}),
                 ...(this.verbose ? { verbose: true } : {}),

package/src/cli/cmd_Fleet.ts

@@ -6,6 +6,7 @@ import { Command, Option } from 'clipanion'
 import { join } from 'path'
 import { npmLatest, resolveLatest, scanFleet, type FleetRepo } from '../fleet/scan-fleet.ts'
 import { short, updateFleet } from '../fleet/update-fleet.ts'
+import { listFlag } from './list-flag.ts'
 
 export class FleetCommand extends Command {
     static override paths = [['fleet']]
@@ -32,7 +33,8 @@ export class FleetCommand extends Command {
     async execute(): Promise<number> {
         const root = this.root ?? join(process.cwd(), '..')
         let repos = scanFleet(root)
-        if (this.only != null && this.only.length > 0) repos = repos.filter((r) => this.only!.includes(r.name))
+        const only = listFlag(this.only)
+        if (only.length > 0) repos = repos.filter((r) => only.includes(r.name))
         const w = (l: string) => this.context.stdout.write(`${l}\n`)
         if (repos.length === 0) {
             w(`skip: no repo under ${root} depends on an rvlib-* package`)

package/src/cli/cmd_GlobalProcesses.ts

@@ -172,6 +172,8 @@ export type SwitchDeps = {
 /** the longest a switch is followed: a bring-up polls its health for minutes */
 export const SWITCH_WAIT_MS = 10 * 60_000
 const SWITCH_POLL_MS = 1_000
+/** how long the state the switch left counts as pm not having acted yet */
+export const SWITCH_GRACE_MS = 30_000
 
 /** flip a global process through pm, then follow pm's state until its probe
  *  settles it: 0 once it is up (or down for stop), 1 otherwise. The launcher's
@@ -183,7 +185,8 @@ export async function switchProcess(id: string, act: SwitchAct, d: SwitchDeps, w
         return 1
     }
     const want = act === 'stop' ? 'down' : 'up'
-    const end = d.now() + waitMs
+    const start = d.now()
+    const end = start + waitMs
     let said = ''
     for (;;) {
         const v = await d.view(id)
@@ -195,7 +198,9 @@ export async function switchProcess(id: string, act: SwitchAct, d: SwitchDeps, w
             said = v.status
             d.log(`${id}: ${v.status}`)
         }
-        const moving = v.status === 'starting' || v.status === 'stopping' || v.want !== want
+        // the state it is leaving, read just after the switch, is pm not there yet
+        const leaving = v.status === (want === 'up' ? 'down' : 'up') && d.now() - start < SWITCH_GRACE_MS
+        const moving = v.status === 'starting' || v.status === 'stopping' || v.want !== want || leaving
         if (!moving) {
             if (v.status === want) return 0
             d.log(`FAIL ${id} is ${v.status}, not ${want}${v.note == null ? '' : `: ${v.note}`}`)

package/src/cli/list-flag.ts

@@ -0,0 +1,3 @@
+/** a repeatable flag's values, each also split on commas: `--only a,b` is `--only a --only b` */
+export const listFlag = (values: readonly string[] | undefined): string[] =>
+    (values ?? []).flatMap((v) => v.split(',')).map((v) => v.trim()).filter((v) => v !== '')

package/src/core/jobs.ts

@@ -177,9 +177,11 @@ export function sweepJobs(root: string, now = Date.now(), o: { keepMs?: number;
         })
     } catch { return /* no jobs yet: nothing to sweep */ }
     dirs.sort((a, b) => b.mtime - a.mtime).forEach((d, i) => {
-        if (d.mtime > now - (o.keepMs ?? JOBS_KEEP_MS) && i < (o.max ?? JOBS_MAX)) return
+        const fresh = d.mtime > now - (o.keepMs ?? JOBS_KEEP_MS)
+        if (fresh && i < (o.max ?? JOBS_MAX)) return
+        // past the keep window a live pid is a reused one: no gate runs for a week
         const j = readJson<Job>(join(d.dir, 'job.json'))
-        if (j != null && alive(j.pid)) return
+        if (fresh && j != null && alive(j.pid)) return
         try { rmSync(d.dir, { recursive: true, force: true }) } catch { /* raced: gone either way */ }
     })
 }

package/src/ledger/store.ts

@@ -193,8 +193,9 @@ export class Answers {
         return r == null ? 'none' : `${r.n}/${r.last ?? 0}`
     }
 
+    /** the rows the cap governs: a forever answer is kept by the sweep, so it is no use against the cap */
     use(): AnswersUse | null {
-        const r = this.with(READ_BUSY_MS, (h) => h.query('select count(*) as n, min(used) as oldest from answers').get() as { n: number; oldest: number | null } | null)
+        const r = this.with(READ_BUSY_MS, (h) => h.query('select count(*) as n, min(used) as oldest from answers where coalesce(keeps, 0) < ?').get(FOREVER_MS) as { n: number; oldest: number | null } | null)
         return r == null ? null : { count: Number(r.n), oldestUsed: r.oldest }
     }
 

package/src/mv/mv-md.ts

@@ -154,7 +154,8 @@ export function movePage(root: string, oldRel: string, newRel: string, io: MvIo,
     let touched = 0
     for (const f of tracked) {
         const p = join(root, f)
-        if (!existsSync(p)) continue
+        // a submodule is one ls-files entry and a directory: nothing to read
+        if (!isFile(p)) continue
         const before = readFileSync(p, 'utf8')
         let after = retargetRelativeRefs(root, before, dirOf(f), dirOf(moves.get(f) ?? f), moves)
         for (const [oldTok, newTok] of pairs) after = after.replace(bound(oldTok), newTok)

package/src/scaffold/files/bunfig.toml

@@ -9,3 +9,7 @@ tabWidth = 4
 ignorePatterns = ["*.md", "*.json", "*.jsonc", "*.yaml", "*.yml", "*.toml"]
 
 [lint]
+
+[lint.rules]
+# `{}` as a type accepts any non nullish value: name the shape, or write Record<string, never>
+"typescript/no-empty-object-type" = "error"

package/src/ts/rename.ts

@@ -16,6 +16,7 @@ import { basename, dirname, extname, join, relative, resolve } from 'path'
 import { canonicalSpecifier, isSkipped, loadConfig, toPosix, type RvtConfig } from 'rvlib-shipkit/src/ts/config.ts'
 import { extractSpecs } from 'rvlib-shipkit/src/ts/source-graph.ts'
 import { gitBin } from '../core/git-bin.ts'
+import { retargetRelativeRefs } from '../mv/mv-md.ts'
 
 const CODE_RE = /\.[cm]?[jt]sx?$/
 
@@ -106,7 +107,15 @@ export function runRename(srcArg: string, dstArg: string, opts: { apply?: boolea
    const isFile = (rel: string): boolean => {
       try { return statSync(join(repoRoot, rel)).isFile() } catch { return false }
    }
+   // a markdown link is relative to its page: the md engine's pass retargets it
+   const mdMoves = new Map(allFiles.flatMap((f): [string, string][] => { const to = movedTo(f); return to == null ? [] : [[f, to]] }))
+   const dirOf = (p: string): string => { const d = dirname(p); return d === '.' ? '' : d }
    const rewriteFile = (file: string, content: string): { text: string; count: number } => {
+      if (file.endsWith('.md')) {
+         const linked = retargetRelativeRefs(repoRoot, content, dirOf(file), dirOf(movedTo(file) ?? file), mdMoves)
+         const scanned = scanPairs(linked, pairs)
+         return { text: scanned.text, count: scanned.count + (linked === content ? 0 : 1) }
+      }
       const rel = CODE_RE.test(file) ? relativeRewrites(file, content, movedTo, isFile) : new Map<string, string>()
       if (rel.size === 0) return scanPairs(content, pairs)
       // the relative specifiers this move retargets are set aside while the

package/src/wiki/agent-index.ts

@@ -0,0 +1,114 @@
+// every agent/ page is LISTED: a bullet, a numbered item, a table row or an `@`
+// include of an index page names it, or names a folder that holds it. A link in
+// prose does not count, so an agent finds every page by reading indexes, never
+// by luck. Index pages: agent/index.md and any `index.md` under agent/ (they
+// list any page), `agent/<dir>.md` (it lists the pages of `agent/<dir>/`). Every
+// index page is in sight of what a session loads: loaded, or named by a listing
+// line of a loaded file. Pure: callers pass the texts, so the rule tests in memory.
+import { dirname, join, normalize } from 'path'
+
+export const ROOT_INDEX = 'agent/index.md'
+
+/** the files a session loads first, before any include */
+export const ENTRIES = ['CLAUDE.md', 'CLAUDE.local.md'] as const
+
+const MAX_HOPS = 5
+
+/** a line that lists: a bullet, a numbered item, a table row (not its rule), an `@` include, a `→` pointer */
+const LISTING = /^\s*(?:[-*+]\s|\d+\.\s|\|(?!\s*:?-{3})|@\S|→\s)/
+
+/** the `@` paths of a page, code fences and code spans left out */
+export function includesOf(text: string): string[] {
+    const prose = text.replace(/^```[\s\S]*?^```/gm, '').replace(/`[^`\n]*`/g, '')
+    return [...prose.matchAll(/(?:^|\s)@([^\s]+)/g)].map((m) => m[1]!)
+}
+
+/** an include as a repo path, or null when it leaves the repo (`~/…`, absolute, `../` past the root) */
+function repoPath(from: string, include: string): string | null {
+    if (include.startsWith('~') || include.startsWith('/')) return null
+    const p = normalize(join(dirname(from), include))
+    return p.startsWith('..') ? null : p
+}
+
+/** every repo file a session loads: each entry, then its `@` includes inside the repo */
+export function loadedFiles(read: (path: string) => string | null): string[] {
+    const seen = new Set<string>()
+    const visit = (path: string, hops: number): void => {
+        if (seen.has(path)) return
+        const text = read(path)
+        if (text == null) return
+        seen.add(path)
+        if (hops >= MAX_HOPS) return
+        for (const include of includesOf(text)) {
+            const next = repoPath(path, include)
+            if (next != null) visit(next, hops + 1)
+        }
+    }
+    // agent/index.md is in sight by contract: its include in CLAUDE.md is another rule's
+    for (const e of [...ENTRIES, ROOT_INDEX]) visit(e, 0)
+    return [...seen]
+}
+
+/** the md pages and folders (ending in `/`) one listing line names, as repo paths */
+function named(line: string, from: string): string[] {
+    const dir = dirname(from)
+    const out: string[] = []
+    const add = (raw: string): void => {
+        const p = raw.split('#')[0]!.replace(/^@/, '')
+        if (/^[a-z]+:/.test(p) || !(p.endsWith('.md') || p.endsWith('/'))) return
+        const abs = p.startsWith('agent/') ? normalize(p) : normalize(join(dir, p))
+        out.push(p.endsWith('/') && !abs.endsWith('/') ? `${abs}/` : abs)
+    }
+    for (const m of line.matchAll(/\]\(([^)\s]+)\)/g)) add(m[1]!)
+    for (const m of line.matchAll(/(?:^|[\s`(@])((?:\.{0,2}\/)?(?:[\w.-]+\/)*[\w.-]+(?:\.md|\/))(?=[\s`),.;:|]|$)/g)) add(m[1]!)
+    return out
+}
+
+/** the folder an index page lists, '' for every page, null when the page is no index */
+function scopeOf(path: string, folders: ReadonlySet<string>): string | null {
+    if (path === ROOT_INDEX || path.endsWith('/index.md')) return ''
+    const sibling = path.slice(0, -'.md'.length)
+    return folders.has(sibling) ? `${sibling}/` : null
+}
+
+/** can `index` list `page`: it is an index page and its folder holds the page */
+export function indexCovers(index: string, page: string, folders: ReadonlySet<string>): boolean {
+    const scope = scopeOf(index, folders)
+    return scope != null && index !== page && page.startsWith(scope)
+}
+
+/** what the listing lines of `path` name, code fences and html comments left out */
+function listedBy(path: string, text: string): string[] {
+    const out: string[] = []
+    let fence = false
+    for (const line of text.replace(/<!--[\s\S]*?-->/g, '').split('\n')) {
+        if (/^\s*(?:```|~~~)/.test(line)) fence = !fence
+        if (!fence && LISTING.test(line)) out.push(...named(line, path))
+    }
+    return out
+}
+
+const covers = (names: ReadonlySet<string>, page: string): boolean =>
+    names.has(page) || [...names].some((n) => n.endsWith('/') && n !== 'agent/' && page.startsWith(n))
+
+/** every page of `pages` (repo path → text) that no index lists, sorted */
+export function unlisted(pages: ReadonlyMap<string, string>, exempt: ReadonlySet<string> = new Set()): string[] {
+    const folders = new Set([...pages.keys()].map((p) => dirname(p)))
+    const listed = new Set<string>([ROOT_INDEX])
+    for (const [path, text] of pages) {
+        const scope = scopeOf(path, folders)
+        if (scope == null) continue
+        // naming its own folder lists no page: each page gets its own line
+        const own = new Set([`${dirname(path)}/`, scope])
+        for (const p of listedBy(path, text)) if (p !== path && p.startsWith(scope) && !own.has(p)) listed.add(p)
+    }
+    return [...pages.keys()].filter((p) => !exempt.has(p) && !covers(listed, p)).sort()
+}
+
+/** every index page that no loaded file includes or names on a listing line, sorted */
+export function indexesOutOfSight(pages: ReadonlyMap<string, string>, loaded: readonly string[], read: (path: string) => string | null): string[] {
+    const folders = new Set([...pages.keys()].map((p) => dirname(p)))
+    const seen = new Set<string>(loaded)
+    for (const path of loaded) for (const p of listedBy(path, read(path) ?? '')) seen.add(p)
+    return [...pages.keys()].filter((p) => scopeOf(p, folders) != null && !covers(seen, p)).sort()
+}