@endora-commerce/cli 0.100.0

package/dist/rules/entry-presence.d.ts

@@ -0,0 +1,142 @@
+/**
+ * An entry point with no caller **decides** presence before it works
+ * (issue #126; Constitution XVII).
+ *
+ * Routes are gated at the `ctx.routes` seam, workers at `defineModuleWorker`,
+ * subscriptions at `ctx.subscribe` — and each of those seams has a static check.
+ * A timer a module starts in its own plugin body had none: `defineModuleRoutes`
+ * gates *requests* through an `onRequest` hook, and a plugin body is not a
+ * request, so it runs at boot whatever the module's effective state and the
+ * callback keeps firing every five minutes after an operator switches the module
+ * off. In `price_lists` that meant price lists went on activating and expiring on
+ * a timer — it changed what customers are charged, not merely what a log said.
+ *
+ * The rule this enforces is the one in `AGENTS.md`, "Module enable/disable",
+ * item 3: **where nothing can catch the throw, presence is decided before the
+ * work, not caught after it.**
+ *
+ * The whole of the reasoning — the four constructs, why a mixed boot hook is
+ * reported rather than probed, and what this analysis deliberately cannot see —
+ * is in `backend/scripts/check-entry-presence.ts`, the repository-scope host,
+ * whose header it has always been. Two things live there rather than here and
+ * both are deliberate:
+ *
+ *   * **the ledgers.** `TIMERS_WITHOUT_PRESENCE` and
+ *     `BOOT_HOOKS_WITHOUT_PRESENCE` are entries about *these* modules, and a
+ *     third-party package is in no such ledger — the same placement
+ *     `check:command-coverage`'s `MIGRATED_MODULES` has. It is also load-bearing
+ *     for a second reason: `check:lock-claims`' population includes
+ *     `backend/scripts/check-*.ts` precisely because that is where a check's own
+ *     ledger reasons live, so moving these two out of that tree would take them
+ *     out of that check's population without anything saying so.
+ *   * **the default for `checkEntryPresence`'s ledger argument.** It has none
+ *     here: a host must state which ledger it is judging against, because
+ *     "whichever one the library happened to carry" is how a package inherits
+ *     this repository's exemptions.
+ *
+ * `specs/101-endora-check/contracts/package-scope-layout.md` §6 — one analysis,
+ * two hosts.
+ */
+import ts from 'typescript';
+import { type HostResidentModules } from '../lib/module-population.js';
+/** The entry-point construct this finding is about. */
+export type EntryConstruct = 'setInterval' | 'setTimeout' | 'process.on' | 'ctx.onBoot';
+/** Why the site fails the rule. Each maps to its own line in the failure output. */
+export type EntryFinding = 
+/** Nothing in the callback asks `isPresent`. */
+'no-presence-decision'
+/** It asks, but from inside a `try` — where a switched-off module and a failed
+ *  tick end up in the same `catch`. */
+ | 'presence-decided-inside-try'
+/** It asks about a different module than the one that owns the file. */
+ | 'presence-decided-for-another-module'
+/**
+ * A boot hook that **does work and contributes** in one body. Neither answer
+ * fits: probing it stops the contribution, leaving it unprobed keeps the work.
+ * The remedy is a split, and the reported kind says so rather than repeating
+ * the probe advice that is wrong here (D-68).
+ */
+ | 'mixed-boot-hook';
+export interface UngatedEntry {
+    /** Path under `src/`, POSIX separators. */
+    readonly file: string;
+    readonly line: number;
+    readonly moduleId: string;
+    readonly construct: EntryConstruct;
+    /**
+     * The enclosing named function, or `<module scope>` — part of the ledger key.
+     * A boot hook has no enclosing name worth keying on (every one of them sits in
+     * `registerModule`), so it uses `onBoot#<n>`, its ordinal among the hooks the
+     * file registers. That is stable under everything except reordering the hooks
+     * themselves, which is a change to what each one is.
+     */
+    readonly scheduler: string;
+    readonly finding: EntryFinding;
+}
+/** `<file>:<scheduler>:<construct>` — the ledger key, and the identity of a site. */
+export declare function keyOf(found: UngatedEntry): string;
+export interface EntryPresenceInput {
+    /** Every source under `src/`, keyed by path relative to `src/`. */
+    readonly sources: ReadonlyMap<string, string>;
+    /**
+     * Modules whose manifest declares `activation.nonDeactivatable`, from
+     * `lib/switchable-modules.ts`. Their boot hooks are out of the population: no
+     * undeclared absence lets one run while the module is absent, and a declared
+     * one ships neither the hook nor the module (D-101). Timers stay
+     * in — `_lifecycle`'s lease heartbeat is ledgered rather than exempted, and
+     * that entry is what documents the circularity behind it.
+     *
+     * Defaulting to empty widens the population rather than narrowing it, so a
+     * caller that forgets it over-reports instead of going quietly blind.
+     */
+    readonly lockedModules?: ReadonlySet<string> | undefined;
+    /**
+     * Directories whose files belong to a module that no `modules/<id>/` segment
+     * names — `lib/module-roots.ts`' `hostResidentModules` (feature 080, T040b).
+     *
+     * Without it `_lifecycle`'s lease heartbeat attributes to `null` and this
+     * rule skips it as "not a module's file", which is the ledger entry below
+     * going stale while the timer it describes is still there.
+     */
+    readonly hostResidentModules?: HostResidentModules | undefined;
+}
+/**
+ * Does this hook body **do work** — the question that decides whether it owes a
+ * presence probe?
+ *
+ * Syntactic, like every other shape here: an `await` anywhere in the body, a
+ * call on the module's own `emFactory` / `em` / `redis` / `.handle`, or a call on
+ * something the body just constructed (`new Reconciler(em).run()`).
+ */
+export declare function bootHookDoesWork(body: ts.Node): boolean;
+/**
+ * Does this hook body also **contribute** — push a descriptor into a registry
+ * some other module reads?
+ *
+ * A `registry.register(…)` / `.push(…)` call, or a helper whose name says so
+ * (`registerBlogAssetReferences(…)`). Both spellings shipped in the two mixed
+ * hooks D-68 had to split.
+ */
+export declare function bootHookContributes(body: ts.Node): boolean;
+/** Every uncatchable entry point in a module's sources that fails the rule. */
+export declare function findUngatedEntries(input: EntryPresenceInput): UngatedEntry[];
+export interface CheckResult {
+    readonly total: number;
+    readonly violations: readonly UngatedEntry[];
+    readonly ledgered: readonly UngatedEntry[];
+    /** Ledger keys that no longer describe an ungated entry point. */
+    readonly stale: readonly string[];
+}
+export declare function checkEntryPresence(input: EntryPresenceInput, ledger: Readonly<Record<string, string>>): CheckResult;
+export declare const EXPLANATION: Readonly<Record<EntryFinding, string>>;
+/** The sentence an author reads for one site. One spelling, two hosts. */
+export declare function remedyFor(found: UngatedEntry): string;
+/**
+ * Every source this rule reads under `roots`.
+ *
+ * One spelling, both hosts: the repository host supplies its source roots and the
+ * package host supplies one package's, and neither gets to differ about which
+ * files are in the population.
+ */
+export declare function collectPresenceFiles(roots: readonly string[], out?: string[]): string[];
+//# sourceMappingURL=entry-presence.d.ts.map

package/dist/rules/entry-presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-presence.d.ts","sourceRoot":"","sources":["../../src/rules/entry-presence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAKH,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAC;AA6BrC,uDAAuD;AACvD,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,CAAC;AAExF,oFAAoF;AACpF,MAAM,MAAM,YAAY;AACtB,gDAAgD;AAC9C,sBAAsB;AACxB;uCACuC;GACrC,6BAA6B;AAC/B,wEAAwE;GACtE,qCAAqC;AACvC;;;;;GAKG;GACD,iBAAiB,CAAC;AAEtB,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;CAChC;AAED,qFAAqF;AACrF,wBAAgB,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAEjD;AAED,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACzD;;;;;;;OAOG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CAChE;AA+ED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAgBvD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAQ1D;AAyCD,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,YAAY,EAAE,CAwF5E;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,WAAW,CASb;AAED,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAiB9D,CAAC;AAGF,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAc3F"}

package/dist/rules/entry-presence.js

@@ -0,0 +1,339 @@
+/**
+ * An entry point with no caller **decides** presence before it works
+ * (issue #126; Constitution XVII).
+ *
+ * Routes are gated at the `ctx.routes` seam, workers at `defineModuleWorker`,
+ * subscriptions at `ctx.subscribe` — and each of those seams has a static check.
+ * A timer a module starts in its own plugin body had none: `defineModuleRoutes`
+ * gates *requests* through an `onRequest` hook, and a plugin body is not a
+ * request, so it runs at boot whatever the module's effective state and the
+ * callback keeps firing every five minutes after an operator switches the module
+ * off. In `price_lists` that meant price lists went on activating and expiring on
+ * a timer — it changed what customers are charged, not merely what a log said.
+ *
+ * The rule this enforces is the one in `AGENTS.md`, "Module enable/disable",
+ * item 3: **where nothing can catch the throw, presence is decided before the
+ * work, not caught after it.**
+ *
+ * The whole of the reasoning — the four constructs, why a mixed boot hook is
+ * reported rather than probed, and what this analysis deliberately cannot see —
+ * is in `backend/scripts/check-entry-presence.ts`, the repository-scope host,
+ * whose header it has always been. Two things live there rather than here and
+ * both are deliberate:
+ *
+ *   * **the ledgers.** `TIMERS_WITHOUT_PRESENCE` and
+ *     `BOOT_HOOKS_WITHOUT_PRESENCE` are entries about *these* modules, and a
+ *     third-party package is in no such ledger — the same placement
+ *     `check:command-coverage`'s `MIGRATED_MODULES` has. It is also load-bearing
+ *     for a second reason: `check:lock-claims`' population includes
+ *     `backend/scripts/check-*.ts` precisely because that is where a check's own
+ *     ledger reasons live, so moving these two out of that tree would take them
+ *     out of that check's population without anything saying so.
+ *   * **the default for `checkEntryPresence`'s ledger argument.** It has none
+ *     here: a host must state which ledger it is judging against, because
+ *     "whichever one the library happened to carry" is how a package inherits
+ *     this repository's exemptions.
+ *
+ * `specs/101-endora-check/contracts/package-scope-layout.md` §6 — one analysis,
+ * two hosts.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import ts from 'typescript';
+import { NO_HOST_RESIDENT_MODULES, } from '../lib/module-population.js';
+import { moduleOf } from '../lib/port-registrations.js';
+import { callbackOf, calleeName, enclosingName, findRepeatingTimerSites, localFunctions, MODULE_SCOPE, parseScript, receiverName, stringLiteralOf, } from '../lib/repeating-timers.js';
+/** Process-lifecycle events: a handler for one of these has no caller either. */
+const PROCESS_EVENTS = new Set([
+    'SIGINT',
+    'SIGTERM',
+    'SIGHUP',
+    'SIGQUIT',
+    'SIGUSR1',
+    'SIGUSR2',
+    'beforeExit',
+    'exit',
+    'uncaughtException',
+    'unhandledRejection',
+]);
+/** `<file>:<scheduler>:<construct>` — the ledger key, and the identity of a site. */
+export function keyOf(found) {
+    return `${found.file}:${found.scheduler}:${found.construct}`;
+}
+/** Is `node` under a `try` that is itself inside `root`? */
+function underTry(node, root) {
+    for (let cursor = node.parent; cursor && cursor !== root; cursor = cursor.parent) {
+        if (ts.isTryStatement(cursor))
+            return true;
+    }
+    return false;
+}
+function presenceDecisionIn(callback, moduleId) {
+    let decidesOwnModule = false;
+    let decidesOtherModule = false;
+    let insideTry = false;
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && calleeName(node) === 'isPresent') {
+            const [argument] = node.arguments;
+            const asked = argument === undefined ? null : stringLiteralOf(argument);
+            if (asked === moduleId) {
+                if (underTry(node, callback))
+                    insideTry = true;
+                else
+                    decidesOwnModule = true;
+            }
+            else {
+                decidesOtherModule = true;
+            }
+        }
+        node.forEachChild(visit);
+    };
+    visit(callback);
+    return { decidesOwnModule, decidesOtherModule, insideTry };
+}
+/**
+ * Names whose *use as a receiver* marks a hook body as doing work rather than
+ * contributing: the module's own database factory, its Redis client and the
+ * service handle its plugin returns. Passing one along (`seed(emFactory)`) is
+ * not a call on it and does not count — see the header's blind spots.
+ */
+const WORK_RECEIVERS = new Set(['emFactory', 'em', 'redis', 'handle']);
+/** Verbs a contribution uses to push a descriptor into somebody else's table. */
+const CONTRIBUTION_VERBS = new Set(['register', 'push', 'unshift', 'add']);
+/** Does any node under `root` satisfy `predicate`? */
+function anyNode(root, predicate) {
+    let hit = false;
+    const visit = (node) => {
+        if (hit)
+            return;
+        if (predicate(node)) {
+            hit = true;
+            return;
+        }
+        node.forEachChild(visit);
+    };
+    visit(root);
+    return hit;
+}
+/** Every identifier in a callee's property-access chain, innermost last. */
+function calleeChain(node) {
+    const names = [];
+    let cursor = node.expression;
+    while (ts.isPropertyAccessExpression(cursor)) {
+        names.push(cursor.name.text);
+        cursor = cursor.expression;
+    }
+    if (ts.isIdentifier(cursor))
+        names.push(cursor.text);
+    if (ts.isCallExpression(cursor))
+        names.push(...calleeChain(cursor));
+    return names;
+}
+/**
+ * Does this hook body **do work** — the question that decides whether it owes a
+ * presence probe?
+ *
+ * Syntactic, like every other shape here: an `await` anywhere in the body, a
+ * call on the module's own `emFactory` / `em` / `redis` / `.handle`, or a call on
+ * something the body just constructed (`new Reconciler(em).run()`).
+ */
+export function bootHookDoesWork(body) {
+    return anyNode(body, (node) => {
+        if (ts.isAwaitExpression(node))
+            return true;
+        if (!ts.isCallExpression(node))
+            return false;
+        if (ts.isNewExpression(node.expression))
+            return true;
+        if (ts.isPropertyAccessExpression(node.expression) &&
+            ts.isNewExpression(node.expression.expression)) {
+            return true;
+        }
+        const chain = calleeChain(node);
+        // `emFactory()` itself is only a fork; what counts is a call *through* one of
+        // these, which is why the receiver names are read from the chain's tail.
+        return chain.slice(1).some((name) => WORK_RECEIVERS.has(name));
+    });
+}
+/**
+ * Does this hook body also **contribute** — push a descriptor into a registry
+ * some other module reads?
+ *
+ * A `registry.register(…)` / `.push(…)` call, or a helper whose name says so
+ * (`registerBlogAssetReferences(…)`). Both spellings shipped in the two mixed
+ * hooks D-68 had to split.
+ */
+export function bootHookContributes(body) {
+    return anyNode(body, (node) => {
+        if (!ts.isCallExpression(node))
+            return false;
+        const name = calleeName(node);
+        if (name === null)
+            return false;
+        if (CONTRIBUTION_VERBS.has(name))
+            return true;
+        return /^register[A-Z]/.test(name);
+    });
+}
+/**
+ * Every `onBoot(...)` registration in a file, in source order.
+ *
+ * The receiver is not required to be `ctx`: an overlay module composes through
+ * the feature-057 factory and may name its context differently, and a hook this
+ * check cannot see is exactly the hole it exists to close.
+ */
+function findBootHookSites(sf, bindings) {
+    const sites = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && calleeName(node) === 'onBoot') {
+            const body = callbackOf(node.arguments[0], bindings);
+            if (body !== null) {
+                sites.push({
+                    call: node,
+                    body,
+                    line: sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1,
+                    ordinal: sites.length + 1,
+                });
+            }
+        }
+        node.forEachChild(visit);
+    };
+    sf.forEachChild(visit);
+    return sites;
+}
+/** Every uncatchable entry point in a module's sources that fails the rule. */
+export function findUngatedEntries(input) {
+    const found = [];
+    const locked = input.lockedModules ?? new Set();
+    const hostResident = input.hostResidentModules ?? NO_HOST_RESIDENT_MODULES;
+    for (const [file, text] of input.sources) {
+        const moduleId = moduleOf(`/src/${file}`, hostResident);
+        // Only a module has an effective state to gate on. A file outside one — the
+        // kernel, `http/`, `db/`, a composition root — is not this rule's business.
+        if (moduleId === null)
+            continue;
+        const sf = parseScript(file, text);
+        const bindings = localFunctions(sf);
+        const report = (node, construct, finding, at) => {
+            found.push({
+                file,
+                line: at?.line ?? sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1,
+                moduleId,
+                construct,
+                scheduler: at?.scheduler ?? enclosingName(node) ?? MODULE_SCOPE,
+                finding,
+            });
+        };
+        const judge = (node, construct, callback, at) => {
+            const decision = presenceDecisionIn(callback, moduleId);
+            if (decision.decidesOwnModule)
+                return;
+            if (decision.insideTry)
+                return report(node, construct, 'presence-decided-inside-try', at);
+            if (decision.decidesOtherModule) {
+                return report(node, construct, 'presence-decided-for-another-module', at);
+            }
+            report(node, construct, 'no-presence-decision', at);
+        };
+        // Repeating timers come from the shared recognizer (issue #128), so this
+        // check and `check-entry-scope` cannot disagree about what one is.
+        for (const site of findRepeatingTimerSites(sf)) {
+            const at = { line: site.line, scheduler: site.scheduler };
+            // An unreadable callback is a finding, not a skip: what the check cannot
+            // see, it must not vouch for.
+            if (site.callback === null)
+                report(site.call, site.construct, 'no-presence-decision', at);
+            else
+                judge(site.call, site.construct, site.callback, at);
+        }
+        // Process-lifecycle handlers are this check's alone: they have no caller to
+        // answer either, but they start no repeating execution, so they are not the
+        // shared shape.
+        const visit = (node) => {
+            if (ts.isCallExpression(node) && calleeName(node) === 'on' && receiverName(node) === 'process') {
+                const event = node.arguments[0] ? stringLiteralOf(node.arguments[0]) : null;
+                const handler = callbackOf(node.arguments[1], bindings);
+                if (event !== null && PROCESS_EVENTS.has(event)) {
+                    if (handler === null)
+                        report(node, 'process.on', 'no-presence-decision');
+                    else
+                        judge(node, 'process.on', handler);
+                }
+            }
+            node.forEachChild(visit);
+        };
+        sf.forEachChild(visit);
+        // Boot hooks — the fourth construct (D-68). A module the orchestrator
+        // refuses to switch off has no absent state for a hook to run in, so it is
+        // out of the population; the derivation is shared with `check-port-catches`
+        // so withdrawing a lock re-reds both checks on the same run.
+        if (locked.has(moduleId))
+            continue;
+        for (const site of findBootHookSites(sf, bindings)) {
+            if (!bootHookDoesWork(site.body))
+                continue;
+            const at = { line: site.line, scheduler: `onBoot#${site.ordinal}` };
+            if (bootHookContributes(site.body)) {
+                report(site.call, 'ctx.onBoot', 'mixed-boot-hook', at);
+                continue;
+            }
+            judge(site.call, 'ctx.onBoot', site.body, at);
+        }
+    }
+    found.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file.localeCompare(b.file)));
+    return found;
+}
+export function checkEntryPresence(input, ledger) {
+    const all = findUngatedEntries(input);
+    const keys = new Set(all.map(keyOf));
+    return {
+        total: all.length,
+        violations: all.filter((entry) => ledger[keyOf(entry)] === undefined),
+        ledgered: all.filter((entry) => ledger[keyOf(entry)] !== undefined),
+        stale: Object.keys(ledger).filter((key) => !keys.has(key)),
+    };
+}
+export const EXPLANATION = {
+    'no-presence-decision': 'asks nothing about the module before it works — add ' +
+        "`if (!effectiveState.isPresent('<module>')) return;` as the callback's first statement",
+    'presence-decided-inside-try': 'asks inside a `try`, so a switched-off module and a failed tick share one `catch` — ' +
+        'move the question outside it',
+    'presence-decided-for-another-module': 'asks about a different module than the one that owns the file',
+    'mixed-boot-hook': 'does work **and** contributes a descriptor to another module in one hook — do NOT put a ' +
+        'presence check at the top of it. Split it in two first: the contribution hook stays ' +
+        'unprobed (the host filters it by contributor, and probing it would make runtime ' +
+        'activation require a restart, or worse — an asset-reference scanner that stops scanning ' +
+        'lets an operator delete data a switched-off module still points at), the work hook gets ' +
+        'the probe. `backend/src/modules/blog/backend.ts` and `product_feeds/backend.ts` ship the ' +
+        'shape',
+};
+/** The sentence an author reads for one site. One spelling, two hosts. */
+export function remedyFor(found) {
+    return `${found.construct} in ${found.file} (${found.scheduler}) ${EXPLANATION[found.finding]}`;
+}
+/**
+ * Every source this rule reads under `roots`.
+ *
+ * One spelling, both hosts: the repository host supplies its source roots and the
+ * package host supplies one package's, and neither gets to differ about which
+ * files are in the population.
+ */
+export function collectPresenceFiles(roots, out = []) {
+    for (const root of roots) {
+        if (!existsSync(root))
+            continue;
+        for (const name of readdirSync(root)) {
+            const full = join(root, name);
+            if (statSync(full).isDirectory()) {
+                if (name === 'node_modules' || name === 'dist')
+                    continue;
+                collectPresenceFiles([full], out);
+            }
+            else if (name.endsWith('.ts') && !name.endsWith('.test.ts') && !name.endsWith('.d.ts')) {
+                out.push(full);
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=entry-presence.js.map

package/dist/rules/entry-presence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-presence.js","sourceRoot":"","sources":["../../src/rules/entry-presence.ts"],"names":[],"mappings":"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"}

package/dist/rules/entry-scope.d.ts

@@ -0,0 +1,91 @@
+export type EntryKind = 'cli' | 'program' | 'worker' | 'interval' | 'message' | 'process';
+/**
+ * The construct a site was built from, spelled the way the source spells it.
+ *
+ * Part of the ledger key, so `setInterval` and a self-rescheduling `setTimeout`
+ * are different sites even in the same function — they are different code. The
+ * two file-level classes carry their own kind here: their construct *is* the
+ * file.
+ */
+export type EntryConstruct = 'cli' | 'program' | 'new Worker' | 'setInterval' | 'setTimeout' | "on('message')" | 'process.on' | 'process.once';
+/** The scheduler slot of a file-level site: the file's own top-level execution. */
+export declare const FILE_SCOPE = "<file>";
+export interface EntrySite {
+    /** Path as {@link relative} reports it — `src/...`, the spelling the ledger uses. */
+    readonly file: string;
+    readonly kind: EntryKind;
+    readonly construct: EntryConstruct;
+    /** The nearest enclosing named function, `<module scope>`, or `<file>`. */
+    readonly scheduler: string;
+    /** 1-based line of the construct. */
+    readonly line: number;
+    readonly scoped: boolean;
+}
+/**
+ * `<file>:<scheduler>:<construct>` — the ledger key, and the identity of a site.
+ *
+ * Line-independent, in the idiom of `check-entry-presence.ts`'s `keyOf`: moving
+ * code inside a file does not invalidate an entry, and re-opening the hole
+ * somewhere else does not silently inherit one.
+ *
+ * A key may cover **more than one site**: `index.ts` registers `SIGINT` and
+ * `SIGTERM` in the same function with the same construct, and one entry
+ * answering for both is what a reader wants there. It is deliberate, and it is
+ * the granularity's floor — two sites the key cannot tell apart are two sites
+ * one reason has to be true of.
+ */
+export declare function keyOf(site: EntrySite): string;
+/**
+ * Every TypeScript source under `dir` — colocated tests included, which is the
+ * one difference from the other walks in this estate and is deliberate: a test
+ * that starts a worker is an entry point too.
+ *
+ * Exported because the population is part of the rule, not part of a host.
+ */
+export declare function collectEntryScopeSources(dir: string, out?: string[]): string[];
+/**
+ * The `src/` files `package.json` runs as a process of their own.
+ *
+ * Read out of the **command**, not out of the script name: `seed:dev` is
+ * `pnpm run migration:up && tsx --env-file-if-exists=.env src/seeds/…`, so the
+ * entry point is the second of two commands behind three flags. `dist/` paths
+ * are ignored (this check reads sources) and so are `scripts/` paths outside
+ * `src/`, which the walk never sees.
+ */
+export declare function declaredProgramEntryPoints(packageJson: string): string[];
+/**
+ * The path as the ledger spells it: everything from the last `/src/` on.
+ * Derived from the path itself rather than from `SRC_ROOT` so the predicates
+ * here are testable without knowing where the checkout lives.
+ *
+ * **It is the default and no longer the only answer** (feature 080, T040a). A
+ * module that has become a workspace package lives at
+ * `packages/modules/<id>/src/…`, where "everything from the last `/src/` on"
+ * drops the module and leaves `src/services/x.ts` — a key two packages would
+ * share. The CLI therefore passes `resolveModuleLayout().displayOf`, which
+ * keeps the application's own spelling byte-for-byte and answers repo-relative
+ * for anything outside it. The default stays for the predicates' own tests,
+ * which have no checkout to resolve.
+ */
+export declare function relative(file: string): string;
+/** How a walked file becomes the key a site and a ledger entry are spelled with. */
+export type PathSpelling = (file: string) => string;
+/**
+ * Which file-level class this file belongs to, or `null` for neither.
+ *
+ * A file under `scripts/` that is *also* declared stays `cli`: fourteen of the
+ * fifteen are both, and moving them would make the count move for no reason.
+ */
+export declare function fileLevelKind(file: string, declared?: ReadonlySet<string>, pathOf?: PathSpelling): 'cli' | 'program' | null;
+/**
+ * Every entry site in one file, with its own scope answer.
+ *
+ * The top of the analysis: source **text** in, sites out. A caller — a test
+ * especially — decides what the repository says it runs by passing `declared`,
+ * the set `declaredProgramEntryPoints` returned.
+ */
+export declare function findEntrySites(file: string, source: string, declared?: ReadonlySet<string>, pathOf?: PathSpelling): EntrySite[];
+export declare function violationsOf(sites: readonly EntrySite[], allowed: Readonly<Record<string, string>>): EntrySite[];
+/** Ledger entries that no longer name an unscoped entry site. */
+export declare function staleAllowances(sites: readonly EntrySite[], allowed: Readonly<Record<string, string>>): string[];
+//# sourceMappingURL=entry-scope.d.ts.map

package/dist/rules/entry-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-scope.d.ts","sourceRoot":"","sources":["../../src/rules/entry-scope.ts"],"names":[],"mappings":"AAoKA,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1F;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GACtB,KAAK,GACL,SAAS,GACT,YAAY,GACZ,aAAa,GACb,YAAY,GACZ,eAAe,GACf,YAAY,GACZ,cAAc,CAAC;AAEnB,mFAAmF;AACnF,eAAO,MAAM,UAAU,WAAW,CAAC;AAEnC,MAAM,WAAW,SAAS;IACxB,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAE7C;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAWlF;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAOxE;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED,oFAAoF;AACpF,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAoB,EAChD,MAAM,GAAE,YAAuB,GAC9B,KAAK,GAAG,SAAS,GAAG,IAAI,CAI1B;AAmHD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAoB,EAChD,MAAM,GAAE,YAAuB,GAC9B,SAAS,EAAE,CAoDb;AAED,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACxC,SAAS,EAAE,CAEb;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACxC,MAAM,EAAE,CAGV"}