@endora-commerce/cli 0.100.0

package/dist/check/peer-owners.d.ts

@@ -0,0 +1,116 @@
+/**
+ * What a package's **peers** own — the one input Phase 3's owner-map rules share
+ * (`specs/101-endora-check/contracts/package-scope-layout.md` §2, the `owner
+ * maps` row, and §5's Tier B).
+ *
+ * ## The measurement that made this file necessary
+ *
+ * `check:port-catches` was assessed as needing no peer input at all, on the
+ * reasoning that its alias table is *"a fixpoint over port-carrying values"*
+ * seeded on a resolution — and a consuming package writes its own resolutions.
+ * That reasoning is wrong, and the code says where: the seed is
+ * `lazyPort(ctx, '<name>')` **whose name is already in `portOwners`**, and
+ * `portOwners` is built from `di.providePort` in a file that declares
+ * `registerModule` — the **owner's** file, not the consumer's. A package that
+ * only consumes ports has an empty seed.
+ *
+ * Measured over this repository's module packages, because the hazard is worth
+ * having as evidence rather than as an assertion: the whole-tree run attributes
+ * **226** guarded-port sites to 41 packages; the same analysis run over each
+ * package **in isolation** finds **19**, in 10 packages. **31 of the 41 lose
+ * every site**, and they include all four PIM connectors (17–19 sites each) and
+ * `product_feeds` (24) — which is to say the integration-heavy modules a
+ * package-scope host exists to judge, the ones whose ports are almost all
+ * somebody else's. A package-scope host without this input would have printed
+ * `violations=0` over exactly the packages it was built to judge.
+ *
+ * The reasoning that produced the wrong assessment is worth naming too, since it
+ * is not specific to this rule: it came from **the rule's header comment**, which
+ * describes the alias table as a fixpoint over port-carrying values and is
+ * accurate — and says nothing about the seed. The predicate is six lines of
+ * `isProxyCall`. A written statement trusted in place of the thing it describes is
+ * the failure this whole estate exists against, and it reaches the people
+ * building the estate too.
+ *
+ * ## Both discovery halves are needed, and a reader will not notice deleting one
+ *
+ * Stated here because neither tree alone shows it: the **installed** walk finds
+ * nothing in this repository, because every module package is a workspace member
+ * symlinked into `node_modules` and the walk correctly rejects a candidate whose
+ * real path leaves the `node_modules` it was reached through. The **workspace**
+ * walk finds nothing in a client instance, which has no workspace. So a reader
+ * who deletes either half sees a green run in whichever tree they are standing
+ * in, and the other tree's hosts go quietly blind.
+ *
+ * ## Why this is synchronous, takes no new dependency, and duplicates nothing
+ *
+ * The obvious route — resolve `@endora-commerce/platform/packages` out of the
+ * subject's tree and call `scanNodeModulesRoots` — is async, and
+ * {@link PackageRuleHost} is synchronous by Phase 1's design. It is also
+ * unnecessary: `lib/module-packages.ts` already carries an **installed** walk
+ * beside its workspace one, with its own recorded reason for being separate from
+ * the platform's boot walk and an explicit agreement on the three rules that
+ * decide an answer. So the discovery exists, in this package, and this file adds
+ * none of its own.
+ *
+ * What it adds is the *reading*: a peer's registrations come out of its emitted
+ * `./backend`-ish artefact as **text through the compiler API**, using the same
+ * `providedPortNames` / `registeredNames` the repository hosts use over source.
+ * No import of a stranger's composition, no platform, no ORM, no `await`.
+ *
+ * ## Two sources, because a peer can be either
+ *
+ * A peer is a workspace member (this checkout, and a stranger's monorepo) **or**
+ * a package installed under a `node_modules` (a stranger's instance). That is
+ * `module-roots.ts`' own two-sourced derivation with the population narrowed, and
+ * both halves are needed: in *this* repository every module package is a
+ * workspace member symlinked into `node_modules`, which the installed walk
+ * correctly rejects as `links-out-of-node-modules`, so the installed half alone
+ * would find nothing here and the workspace half alone would find nothing in a
+ * client instance.
+ *
+ * ## It never answers "nobody owns it"
+ *
+ * A name no peer provides is **not attributed to nobody** — it is *unattributed*,
+ * and the count of those is what a rule turns into `sources=owners:<n>/<m>` on
+ * its own `read:` line and, when `n` is zero, into `unreadable`. That is the
+ * whole of §5's *"a port whose owner module is not installed is `unreadable` for
+ * that edge, never `unowned`"*, expressed in the idiom the estate already prints
+ * rather than in a sentence a reader has to trust.
+ */
+import { type ModulePackage } from '../lib/module-packages.js';
+import type { PackageLayout } from './layout.js';
+/** A peer whose declarations could not be read, named with the reason. */
+export interface UnreadablePeer {
+    readonly name: string;
+    readonly moduleId: string;
+    /** In the words the rule's own line uses. */
+    readonly reason: string;
+}
+export interface PeerOwners {
+    /** Peer module packages found, the subject excluded. */
+    readonly peers: readonly ModulePackage[];
+    /** Gated port name → the module id whose artefact provides it. */
+    readonly portOwners: ReadonlyMap<string, string>;
+    /** Container registration name → the module id whose artefact registers it. */
+    readonly containerOwners: ReadonlyMap<string, string>;
+    /** Emitted artefacts opened — the `files=` contribution. */
+    readonly filesRead: number;
+    /** Peers that claimed to be modules and could not be read. Never a silent zero. */
+    readonly unreadable: readonly UnreadablePeer[];
+    /** Which half, or halves, the peers came from. Printed, so a zero is legible. */
+    readonly discovery: 'installed' | 'workspace' | 'both' | 'none';
+}
+/** The empty answer — a package standing alone, with nothing installed beside it. */
+export declare const NO_PEER_OWNERS: PeerOwners;
+/**
+ * Read what the subject's peers own.
+ *
+ * Every failure is named. A peer that publishes no composing artefact is
+ * *readable and empty* — it registers nothing, by its own `exports` map — while a
+ * peer whose artefact is absent is **unreadable**, because a package that was
+ * never built is a package whose registrations this run cannot see and must not
+ * credit with none.
+ */
+export declare function readPeerOwners(layout: PackageLayout): PeerOwners;
+//# sourceMappingURL=peer-owners.d.ts.map

package/dist/check/peer-owners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-owners.d.ts","sourceRoot":"","sources":["../../src/check/peer-owners.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AAKH,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,2BAA2B,CAAC;AAInC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtD,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;IAC/C,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;CACjE;AAED,qFAAqF;AACrF,eAAO,MAAM,cAAc,EAAE,UAO5B,CAAC;AA6CF;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAiFhE"}

package/dist/check/peer-owners.js

@@ -0,0 +1,225 @@
+/**
+ * What a package's **peers** own — the one input Phase 3's owner-map rules share
+ * (`specs/101-endora-check/contracts/package-scope-layout.md` §2, the `owner
+ * maps` row, and §5's Tier B).
+ *
+ * ## The measurement that made this file necessary
+ *
+ * `check:port-catches` was assessed as needing no peer input at all, on the
+ * reasoning that its alias table is *"a fixpoint over port-carrying values"*
+ * seeded on a resolution — and a consuming package writes its own resolutions.
+ * That reasoning is wrong, and the code says where: the seed is
+ * `lazyPort(ctx, '<name>')` **whose name is already in `portOwners`**, and
+ * `portOwners` is built from `di.providePort` in a file that declares
+ * `registerModule` — the **owner's** file, not the consumer's. A package that
+ * only consumes ports has an empty seed.
+ *
+ * Measured over this repository's module packages, because the hazard is worth
+ * having as evidence rather than as an assertion: the whole-tree run attributes
+ * **226** guarded-port sites to 41 packages; the same analysis run over each
+ * package **in isolation** finds **19**, in 10 packages. **31 of the 41 lose
+ * every site**, and they include all four PIM connectors (17–19 sites each) and
+ * `product_feeds` (24) — which is to say the integration-heavy modules a
+ * package-scope host exists to judge, the ones whose ports are almost all
+ * somebody else's. A package-scope host without this input would have printed
+ * `violations=0` over exactly the packages it was built to judge.
+ *
+ * The reasoning that produced the wrong assessment is worth naming too, since it
+ * is not specific to this rule: it came from **the rule's header comment**, which
+ * describes the alias table as a fixpoint over port-carrying values and is
+ * accurate — and says nothing about the seed. The predicate is six lines of
+ * `isProxyCall`. A written statement trusted in place of the thing it describes is
+ * the failure this whole estate exists against, and it reaches the people
+ * building the estate too.
+ *
+ * ## Both discovery halves are needed, and a reader will not notice deleting one
+ *
+ * Stated here because neither tree alone shows it: the **installed** walk finds
+ * nothing in this repository, because every module package is a workspace member
+ * symlinked into `node_modules` and the walk correctly rejects a candidate whose
+ * real path leaves the `node_modules` it was reached through. The **workspace**
+ * walk finds nothing in a client instance, which has no workspace. So a reader
+ * who deletes either half sees a green run in whichever tree they are standing
+ * in, and the other tree's hosts go quietly blind.
+ *
+ * ## Why this is synchronous, takes no new dependency, and duplicates nothing
+ *
+ * The obvious route — resolve `@endora-commerce/platform/packages` out of the
+ * subject's tree and call `scanNodeModulesRoots` — is async, and
+ * {@link PackageRuleHost} is synchronous by Phase 1's design. It is also
+ * unnecessary: `lib/module-packages.ts` already carries an **installed** walk
+ * beside its workspace one, with its own recorded reason for being separate from
+ * the platform's boot walk and an explicit agreement on the three rules that
+ * decide an answer. So the discovery exists, in this package, and this file adds
+ * none of its own.
+ *
+ * What it adds is the *reading*: a peer's registrations come out of its emitted
+ * `./backend`-ish artefact as **text through the compiler API**, using the same
+ * `providedPortNames` / `registeredNames` the repository hosts use over source.
+ * No import of a stranger's composition, no platform, no ORM, no `await`.
+ *
+ * ## Two sources, because a peer can be either
+ *
+ * A peer is a workspace member (this checkout, and a stranger's monorepo) **or**
+ * a package installed under a `node_modules` (a stranger's instance). That is
+ * `module-roots.ts`' own two-sourced derivation with the population narrowed, and
+ * both halves are needed: in *this* repository every module package is a
+ * workspace member symlinked into `node_modules`, which the installed walk
+ * correctly rejects as `links-out-of-node-modules`, so the installed half alone
+ * would find nothing here and the workspace half alone would find nothing in a
+ * client instance.
+ *
+ * ## It never answers "nobody owns it"
+ *
+ * A name no peer provides is **not attributed to nobody** — it is *unattributed*,
+ * and the count of those is what a rule turns into `sources=owners:<n>/<m>` on
+ * its own `read:` line and, when `n` is zero, into `unreadable`. That is the
+ * whole of §5's *"a port whose owner module is not installed is `unreadable` for
+ * that edge, never `unowned`"*, expressed in the idiom the estate already prints
+ * rather than in a sentence a reader has to trust.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { discoverModulePackages, scanInstalledModulePackages, } from '../lib/module-packages.js';
+import { declaresRegisterModule } from '../lib/module-roots.js';
+import { providedPortNames, registeredNames } from '../lib/port-registrations.js';
+/** The empty answer — a package standing alone, with nothing installed beside it. */
+export const NO_PEER_OWNERS = {
+    peers: [],
+    portOwners: new Map(),
+    containerOwners: new Map(),
+    filesRead: 0,
+    unreadable: [],
+    discovery: 'none',
+};
+/**
+ * Every ancestor of the package that could hold peers, nearest first.
+ *
+ * "Could hold peers" is *has a `node_modules`* or *declares a workspace* — both
+ * questions about the tree rather than about a path anybody spells. The walk
+ * stops at the filesystem root; a package in a temp directory yields none, which
+ * is the honest answer and the one the fixtures rely on.
+ */
+function candidateRoots(packageRoot) {
+    const roots = [];
+    let dir = resolve(packageRoot);
+    for (;;) {
+        if (existsSync(join(dir, 'node_modules')) || existsSync(join(dir, 'pnpm-workspace.yaml'))) {
+            roots.push(dir);
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return roots;
+        dir = parent;
+    }
+}
+/**
+ * The subpath whose artefact **composes** the peer, derived rather than spelled.
+ *
+ * `declaresRegisterModule` is `generate-composer.ts`'s own marker, so the
+ * composer, the repository hosts and this file cannot disagree about which file
+ * composes a module. Nothing here names `./backend` (D-100): the composing
+ * artefact is whichever declared target says so about itself.
+ */
+function composingArtefact(pkg) {
+    for (const target of pkg.exports.values()) {
+        const path = join(pkg.dir, ...target.replace(/^\.\//, '').split('/'));
+        let text;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (declaresRegisterModule(text))
+            return { path, text };
+    }
+    return null;
+}
+/**
+ * Read what the subject's peers own.
+ *
+ * Every failure is named. A peer that publishes no composing artefact is
+ * *readable and empty* — it registers nothing, by its own `exports` map — while a
+ * peer whose artefact is absent is **unreadable**, because a package that was
+ * never built is a package whose registrations this run cannot see and must not
+ * credit with none.
+ */
+export function readPeerOwners(layout) {
+    const byId = new Map();
+    let installed = false;
+    let workspace = false;
+    const unreadable = [];
+    for (const root of candidateRoots(layout.packageRoot)) {
+        const scan = scanInstalledModulePackages(root);
+        for (const pkg of scan.packages) {
+            if (pkg.moduleId === layout.moduleId)
+                continue;
+            if (!byId.has(pkg.moduleId)) {
+                byId.set(pkg.moduleId, pkg);
+                installed = true;
+            }
+        }
+        try {
+            for (const pkg of discoverModulePackages(root)) {
+                if (pkg.moduleId === layout.moduleId)
+                    continue;
+                if (!byId.has(pkg.moduleId)) {
+                    byId.set(pkg.moduleId, pkg);
+                    workspace = true;
+                }
+            }
+        }
+        catch (error) {
+            // Two workspace members claiming one module id. It is a real defect and it
+            // is not the subject's, so it is reported as an unreadable peer set rather
+            // than thrown: a stranger's malformed workspace must not abort their run,
+            // and crediting it with no peers would be the silence this file exists
+            // against.
+            unreadable.push({
+                name: root,
+                moduleId: '(workspace)',
+                reason: `its workspace could not be enumerated (${error instanceof Error ? error.message : String(error)})`,
+            });
+        }
+    }
+    const portOwners = new Map();
+    const containerOwners = new Map();
+    let filesRead = 0;
+    for (const pkg of [...byId.values()].sort((a, b) => a.moduleId.localeCompare(b.moduleId))) {
+        const artefact = composingArtefact(pkg);
+        if (artefact === null) {
+            // Readable and empty vs unreadable, decided by the package's own map: a
+            // peer that declares subpaths whose targets are not on disk was never
+            // built, and its registrations are unread rather than absent.
+            const declaresTargets = [...pkg.exports.values()].some((target) => existsSync(join(pkg.dir, ...target.replace(/^\.\//, '').split('/'))));
+            if (pkg.exports.size > 0 && !declaresTargets) {
+                unreadable.push({
+                    name: pkg.name,
+                    moduleId: pkg.moduleId,
+                    reason: 'none of the targets its `exports` map declares is on disk, so the ports and ' +
+                        'container names it registers cannot be read — it was never built',
+                });
+            }
+            continue;
+        }
+        filesRead += 1;
+        for (const name of providedPortNames(artefact.text, artefact.path)) {
+            if (!portOwners.has(name))
+                portOwners.set(name, pkg.moduleId);
+        }
+        for (const name of registeredNames(artefact.text, artefact.path)) {
+            if (!containerOwners.has(name))
+                containerOwners.set(name, pkg.moduleId);
+        }
+    }
+    return {
+        peers: [...byId.values()],
+        portOwners,
+        containerOwners,
+        filesRead,
+        unreadable,
+        discovery: installed && workspace ? 'both' : installed ? 'installed' : workspace ? 'workspace' : 'none',
+    };
+}
+//# sourceMappingURL=peer-owners.js.map

package/dist/check/peer-owners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-owners.js","sourceRoot":"","sources":["../../src/check/peer-owners.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EACL,sBAAsB,EACtB,2BAA2B,GAE5B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AA2BlF,qFAAqF;AACrF,MAAM,CAAC,MAAM,cAAc,GAAe;IACxC,KAAK,EAAE,EAAE;IACT,UAAU,EAAE,IAAI,GAAG,EAAE;IACrB,eAAe,EAAE,IAAI,GAAG,EAAE;IAC1B,SAAS,EAAE,CAAC;IACZ,UAAU,EAAE,EAAE;IACd,SAAS,EAAE,MAAM;CAClB,CAAC;AAEF;;;;;;;GAOG;AACH,SAAS,cAAc,CAAC,WAAmB;IACzC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/B,SAAS,CAAC;QACR,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC;YAC1F,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,KAAK,CAAC;QACjC,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,iBAAiB,CAAC,GAAkB;IAC3C,KAAK,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACtE,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,sBAAsB,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC1D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAqB;IAClD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC9C,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,MAAM,UAAU,GAAqB,EAAE,CAAC;IAExC,KAAK,MAAM,IAAI,IAAI,cAAc,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,GAAG,2BAA2B,CAAC,IAAI,CAAC,CAAC;QAC/C,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChC,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,CAAC,QAAQ;gBAAE,SAAS;YAC/C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;gBAC5B,SAAS,GAAG,IAAI,CAAC;YACnB,CAAC;QACH,CAAC;QACD,IAAI,CAAC;YACH,KAAK,MAAM,GAAG,IAAI,sBAAsB,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/C,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,CAAC,QAAQ;oBAAE,SAAS;gBAC/C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;oBAC5B,SAAS,GAAG,IAAI,CAAC;gBACnB,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,2EAA2E;YAC3E,2EAA2E;YAC3E,0EAA0E;YAC1E,uEAAuE;YACvE,WAAW;YACX,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,IAAI;gBACV,QAAQ,EAAE,aAAa;gBACvB,MAAM,EAAE,0CACN,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CACvD,GAAG;aACJ,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,MAAM,eAAe,GAAG,IAAI,GAAG,EAAkB,CAAC;IAClD,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QAC1F,MAAM,QAAQ,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,wEAAwE;YACxE,sEAAsE;YACtE,8DAA8D;YAC9D,MAAM,eAAe,GAAG,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAChE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CACrE,CAAC;YACF,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;gBAC7C,UAAU,CAAC,IAAI,CAAC;oBACd,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,QAAQ,EAAE,GAAG,CAAC,QAAQ;oBACtB,MAAM,EACJ,8EAA8E;wBAC9E,kEAAkE;iBACrE,CAAC,CAAC;YACL,CAAC;YACD,SAAS;QACX,CAAC;QACD,SAAS,IAAI,CAAC,CAAC;QACf,KAAK,MAAM,IAAI,IAAI,iBAAiB,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACnE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;QAChE,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,eAAe,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACjE,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,UAAU;QACV,eAAe;QACf,SAAS;QACT,UAAU;QACV,SAAS,EACP,SAAS,IAAI,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM;KAC/F,CAAC;AACJ,CAAC"}

package/dist/check/report.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The report — one line per rule, then the arithmetic
+ * (`specs/101-endora-check/contracts/exit-reduction.md` §3).
+ *
+ * Formatting only. Every decision is made in `run.ts` and every verdict in
+ * `hosts.ts`; a reporter that could change either would be a second place the
+ * exit code is decided.
+ *
+ * Two properties are contract rather than presentation:
+ *
+ *   * **every rule appears**, whatever the aggregate found. That is what makes
+ *     the reduction's `max` honest — the information a masked finding is about
+ *     is on its own line, not something a reader infers from a scroll;
+ *   * **`findings=<n>` is printed even when the exit code is 2** (FR-014). It is
+ *     the whole of §4.4's answer to the masking objection, and it is normative.
+ */
+import { coverageToken } from '../lib/read-size.js';
+import type { LedgerRead } from './ledger.js';
+import type { RunReport } from './run.js';
+/**
+ * The arithmetic line, last.
+ *
+ * A narrowed run prints `selected=<n>/<estate>` **in place of** `estate=<n>`, so
+ * it cannot be mistaken for a full run's (§6). That is the only difference.
+ */
+export declare function arithmeticLine(report: RunReport): string;
+/** The sentence after the counts — why the run exited as it did. */
+export declare function verdictSentence(report: RunReport): string;
+/** The whole report, as the lines the command writes to stdout. */
+export declare function formatReport(report: RunReport, ledger: LedgerRead): readonly string[];
+/** The `sources=` token, re-exported so a caller need not reach past this file. */
+export { coverageToken };
+//# sourceMappingURL=report.d.ts.map

package/dist/check/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/check/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,aAAa,EAAgB,MAAM,qBAAqB,CAAC;AAElE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,UAAU,CAAC;AAuCtD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAWxD;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CA0BzD;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,CAYrF;AAED,mFAAmF;AACnF,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/check/report.js

@@ -0,0 +1,107 @@
+/**
+ * The report — one line per rule, then the arithmetic
+ * (`specs/101-endora-check/contracts/exit-reduction.md` §3).
+ *
+ * Formatting only. Every decision is made in `run.ts` and every verdict in
+ * `hosts.ts`; a reporter that could change either would be a second place the
+ * exit code is decided.
+ *
+ * Two properties are contract rather than presentation:
+ *
+ *   * **every rule appears**, whatever the aggregate found. That is what makes
+ *     the reduction's `max` honest — the information a masked finding is about
+ *     is on its own line, not something a reader infers from a scroll;
+ *   * **`findings=<n>` is printed even when the exit code is 2** (FR-014). It is
+ *     the whole of §4.4's answer to the masking objection, and it is normative.
+ */
+import { coverageToken, readSizeLine } from '../lib/read-size.js';
+import { reasonFor } from './ledger.js';
+const VERDICT_WIDTH = 15;
+const ID_WIDTH = 34;
+function pad(text, width) {
+    return text.length >= width ? text : text + ' '.repeat(width - text.length);
+}
+/** `ran` splits into the two sub-states a reader cares about. */
+function verdictWord(result) {
+    if (result.verdict !== 'ran')
+        return result.verdict;
+    return result.findings.length === 0 ? 'clean' : `findings=${result.findings.length}`;
+}
+function ruleLines(result, ledger) {
+    const lines = [];
+    const head = `  ${pad(result.id, ID_WIDTH)} ${pad(verdictWord(result), VERDICT_WIDTH)}`;
+    lines.push(result.readSize === null ? `${head}${result.explanation}` : `${head}${readSizeLine(result.readSize)}`);
+    if (result.readSize !== null && result.explanation.length > 0) {
+        lines.push(`      ${result.explanation}`);
+    }
+    for (const signal of result.unevaluatedSignals) {
+        lines.push(`      not evaluated — ${signal.signal}: ${signal.reason}`);
+    }
+    for (const finding of result.findings) {
+        lines.push(`      ${finding.location ?? result.id}  ${finding.message}`);
+    }
+    for (const finding of result.acknowledged) {
+        lines.push(`      acknowledged  ${finding.location ?? result.id}  ${finding.message}`);
+        lines.push(`        reason: ${reasonFor(ledger, finding)}`);
+    }
+    return lines;
+}
+/**
+ * The arithmetic line, last.
+ *
+ * A narrowed run prints `selected=<n>/<estate>` **in place of** `estate=<n>`, so
+ * it cannot be mistaken for a full run's (§6). That is the only difference.
+ */
+export function arithmeticLine(report) {
+    const counts = report.counts;
+    const scope = report.selected === null
+        ? `estate=${counts.estate}`
+        : `selected=${report.selected.selected}/${report.selected.estate}`;
+    return (`endora check: ${scope} ran=${counts.ran} clean=${counts.clean} ` +
+        `findings=${counts.findings} not-applicable=${counts.notApplicable} ` +
+        `unreadable=${counts.unreadable} pending=${counts.pending}`);
+}
+/** The sentence after the counts — why the run exited as it did. */
+export function verdictSentence(report) {
+    const counts = report.counts;
+    if (report.arithmeticFailures.length > 0) {
+        return `  → 2  ${report.arithmeticFailures.join(' ')}`;
+    }
+    const causes = [];
+    if (counts.pending > 0) {
+        const phases = [
+            ...new Set(report.results
+                .filter((result) => result.verdict === 'pending')
+                .map((result) => result.explanation)),
+        ];
+        causes.push(`${counts.pending} rule(s) have no package-scope host in this build (${phases.join('; ')})`);
+    }
+    if (counts.unreadable > 0) {
+        causes.push(`${counts.unreadable} rule(s) could not read an input this package must supply`);
+    }
+    if (causes.length > 0)
+        return `  → 2  ${causes.join('; ')}`;
+    if (counts.findings > 0 || report.ledgerFindings.length > 0) {
+        return `  → 1  ${counts.findings} rule(s) reported a finding`;
+    }
+    return '  → 0  the estate was completely evaluated and found nothing';
+}
+/** The whole report, as the lines the command writes to stdout. */
+export function formatReport(report, ledger) {
+    const lines = [
+        `endora check: ${report.packageName}@${report.packageVersion}`,
+        '',
+    ];
+    for (const result of report.results)
+        lines.push(...ruleLines(result, ledger));
+    if (report.ledgerFindings.length > 0) {
+        lines.push('');
+        for (const finding of report.ledgerFindings)
+            lines.push(`  ledger: ${finding}`);
+    }
+    lines.push('', arithmeticLine(report), verdictSentence(report));
+    return lines;
+}
+/** The `sources=` token, re-exported so a caller need not reach past this file. */
+export { coverageToken };
+//# sourceMappingURL=report.js.map

package/dist/check/report.js.map

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

package/dist/check/run.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The verdicts, the arithmetic and the reduction
+ * (`specs/101-endora-check/contracts/exit-reduction.md` §1, §3, §4).
+ *
+ * ## The reduction is `max`, and that is not a new decision
+ *
+ * `0` and `1` are statements about the **tree**; `2` is a statement about the
+ * **run**. So the aggregate's job is to make each code a *complete* statement:
+ *
+ *   * **2** — the picture is incomplete. There may or may not be findings under
+ *     it; repair the picture.
+ *   * **1** — the picture is complete and there are findings.
+ *   * **0** — the picture is complete and there are none.
+ *
+ * Every member of this estate already reduces this way internally, over many
+ * signals and many files: `check:module-boundary` exits 2 on an owner map that
+ * resolved zero tables even when its walk found real unledgered reaches. An
+ * aggregate reducing differently would be a second derivation of one convention.
+ *
+ * The masking objection — *"one unreadable input hides every real finding"* — is
+ * answered where it lives: it masks them **in the exit code and nowhere else**.
+ * Every rule prints its own line regardless, and {@link countsOf}'s `findings`
+ * is printed on the arithmetic line **even when the code is 2**. That is
+ * normative (FR-014), not cosmetic.
+ *
+ * ## The identities have to be able to fail
+ *
+ * {@link countsOf} takes the estate's size as an argument rather than deriving it
+ * from the results it was handed. A count computed by summing the results a run
+ * happens to hold can never detect a lost rule — it is a tautology, and the
+ * whole point of §3's first identity is that losing a rule is the failure this
+ * command exists to make impossible. The second identity fails on a malformed
+ * host: a result that is not `ran` and still carries a finding.
+ */
+import type { ReadSizeInput } from '../lib/read-size.js';
+import type { PartialSignal } from './estate.js';
+/** One thing a rule found. */
+export interface Finding {
+    /** The estate id of the rule that found it. */
+    readonly rule: string;
+    /**
+     * The rule's own key shape for this finding — what a package ledger entry
+     * names. Never a line number where the rule's repository-side ledger keys on
+     * a digest: a line-keyed entry reds on any insertion above the site.
+     */
+    readonly key: string;
+    /** The sentence the author reads. */
+    readonly message: string;
+    /** Package-relative, or `null` where the finding is about the package. */
+    readonly location: string | null;
+}
+export type Verdict = 'ran' | 'not-applicable' | 'unreadable' | 'pending';
+export interface RuleResult {
+    /** Matches {@link EstateEntry.id}. */
+    readonly id: string;
+    readonly verdict: Verdict;
+    /** Empty for every verdict but `ran`. */
+    readonly findings: readonly Finding[];
+    /**
+     * Findings a package ledger entry matched. Excluded from the author's exit
+     * code, included under `--as-platform` (`contracts/package-ledger.md` §4).
+     */
+    readonly acknowledged: readonly Finding[];
+    /** `null` only for `not-applicable` and `pending`. */
+    readonly readSize: ReadSizeInput | null;
+    /**
+     * Required for every verdict but `ran`, and that requirement **is** the
+     * design: a rule that did not run and cannot say why is the silent skip.
+     * Making the field non-optional is the cheapest place to make that
+     * unreachable.
+     */
+    readonly explanation: string;
+    /** Printed on the rule's own line. */
+    readonly unevaluatedSignals: readonly PartialSignal[];
+}
+export interface RunCounts {
+    readonly estate: number;
+    readonly ran: number;
+    readonly clean: number;
+    readonly findings: number;
+    readonly notApplicable: number;
+    readonly unreadable: number;
+    readonly pending: number;
+}
+/** `null` for a full run; the pair for a `--rule` run. */
+export interface Selection {
+    readonly selected: number;
+    readonly estate: number;
+}
+export interface RunReport {
+    /** As read from the package's own manifest. */
+    readonly packageName: string;
+    readonly packageVersion: string;
+    readonly results: readonly RuleResult[];
+    readonly selected: Selection | null;
+    readonly counts: RunCounts;
+    /**
+     * Ledger entries that describe no finding this run produced, that carry no
+     * reason, or that are expressed as a count. Each makes the run exit 1; none
+     * of them is an estate member, so none disturbs §3's arithmetic.
+     */
+    readonly ledgerFindings: readonly string[];
+    /** Why §3's identities do not hold, or empty. */
+    readonly arithmeticFailures: readonly string[];
+    /** Computed by {@link reduce} and by nothing else. */
+    readonly exitCode: number;
+}
+/** Which findings count against the exit code, for this reader. */
+export declare function effectiveFindings(result: RuleResult, asPlatform: boolean): readonly Finding[];
+/**
+ * The counts, over the results and an **independently supplied** estate size.
+ *
+ * `estateSize` is a parameter rather than `results.length` on purpose — see the
+ * header. `clean` and `findings` are each counted directly rather than one being
+ * derived from the other, so §3's second identity is a real comparison.
+ */
+export declare function countsOf(results: readonly RuleResult[], estateSize: number, asPlatform?: boolean): RunCounts;
+/**
+ * Why §3's identities do not hold, or an empty list.
+ *
+ * A narrowed run suppresses the first — it is meaningless over a subset — and
+ * keeps the second, which is about the results themselves.
+ */
+export declare function arithmeticFailures(counts: RunCounts, narrowed: boolean): readonly string[];
+/**
+ * The exit code. `max` over the members' own codes, with `pending` folded into 2.
+ *
+ * ```
+ * exit 2  if  unreadable > 0  or  pending > 0  or  either identity fails
+ * exit 1  else if  findings > 0  or  a ledger entry is stale
+ * exit 0  else
+ * ```
+ */
+export declare function reduce(counts: RunCounts, failures: readonly string[], ledgerFindings: readonly string[]): number;
+export interface RunReportInput {
+    readonly packageName: string;
+    readonly packageVersion: string;
+    readonly results: readonly RuleResult[];
+    /** The estate's size — never `results.length` (see the header). */
+    readonly estateSize: number;
+    /** `null` for a full run. */
+    readonly selected: Selection | null;
+    readonly ledgerFindings?: readonly string[];
+    readonly asPlatform?: boolean;
+}
+export declare function buildRunReport(input: RunReportInput): RunReport;
+//# sourceMappingURL=run.d.ts.map