@endora-commerce/cli 0.100.0

package/dist/lib/nested-checkouts.js

@@ -0,0 +1,160 @@
+/**
+ * "Is this path part of *this* checkout?" — one derivation for the TypeScript
+ * half of the estate (D-168 follow-up; the same question `scripts/lib/module-root.sh`
+ * answers for the shell half).
+ *
+ * ## The problem it exists for
+ *
+ * Agents in this project work in `git worktree`s created **under** the
+ * repository directory, and each one is a complete copy of the tree. So any
+ * walk rooted at the repository — as opposed to one bounded by the workspace
+ * globs or by a named source directory — finds every file of this repository
+ * once per worktree, plus its own. Fifty-one of them stood on the machine this
+ * was written for.
+ *
+ * Every consequence of that is a wrong answer about *this* commit. A rule that
+ * counts finds a population that swells with housekeeping nobody performed
+ * deliberately. A rule that reconciles a scan against a declaration finds
+ * entries it cannot account for and reports them as defects, when what it has
+ * actually done is read another branch's tree and file the verdict under ours.
+ * That is what happened to the D-168 module-package guard an hour after it
+ * merged: red on every developer machine, green in CI, and CI right only
+ * because it has no nested worktrees.
+ *
+ * ## The discriminator is the `.git` entry, not a path name
+ *
+ * `scripts/lib/module-root.sh` ruled this and the ruling holds here unchanged;
+ * its header carries the long form. In brief: a rule keyed on
+ * `.claude/worktrees` would be a derived fact written down (D-100) and would
+ * miss the first worktree somebody puts elsewhere — a nested clone under
+ * `vendor/`, a submodule, a second checkout parked wherever it was convenient.
+ * `git worktree list --porcelain` was the alternative and was rejected there for
+ * three reasons that apply here too: the walk sees *files*, and the `.git`
+ * marker travels with them while git's registry can disagree with the
+ * filesystem in both directions; the registry knows only worktrees, so a nested
+ * clone or a submodule would still be walked; and it needs `git` on `PATH`.
+ *
+ * Both markers git writes count, because both occur here: `git worktree add`
+ * leaves a `.git` **file** (a gitfile naming the administrative directory), and
+ * a clone or a submodule leaves a `.git` **directory**. A rule that saw one of
+ * them would prune half the nested checkouts on this machine and go on reading
+ * the rest.
+ *
+ * **What it cannot see**, stated rather than discovered later: a checkout whose
+ * marker is somewhere else — `GIT_DIR` in the environment, a
+ * `--separate-git-dir` whose gitfile has been removed, a tree exported without
+ * its `.git` — reads as ordinary source and is walked. That is the direction to
+ * be wrong in: such a tree is indistinguishable from a copied directory, and
+ * walking it costs reads rather than coverage.
+ *
+ * ## Two functions, because the two halves are different kinds of question
+ *
+ * {@link nestedCheckoutRoots} asks the filesystem and answers with a list of
+ * repo-relative roots. {@link isInsideNestedCheckout} is a **pure predicate**
+ * over that list. The shell twin is split the same way
+ * (`module_root_scan_nested_checkouts` / `module_root_drop_nested_checkouts`),
+ * and the split is what lets a caller whose own exclusion rule must stay
+ * decidable from a synthetic path — `check-nul-bytes`' `isScannablePath` is the
+ * standing example — take the roots once at the top of its run and keep its
+ * predicate pure.
+ *
+ * ## Why there are still two implementations, and which third is retiring
+ *
+ * `scripts/lib/module-root.sh` is **not** merged into this file and cannot be:
+ * `quality:static` runs with bash, grep, perl and POSIX awk and no `pnpm
+ * install`, so a shell check cannot call a TypeScript library. The two are a
+ * deliberate twin pair, as `lib/read-size.sh` and `lib/read-size.ts` are, and
+ * the ruling they implement is written once — in the shell file's header, which
+ * this one cites rather than restates.
+ *
+ * `check-nul-bytes.ts` is the third answer and it should become a caller of
+ * this one. Its `SKIPPED_PATH_PREFIXES` names `.claude/worktrees` as a literal,
+ * which is the derived fact D-100 refuses and which misses a nested clone or a
+ * worktree parked anywhere else. The reason its own comment gives — that
+ * `.claude/` holds tracked source, so the exclusion cannot be name-anchored —
+ * argues against `SKIPPED_DIRECTORIES` and not against this discriminator. What
+ * it does have is a real constraint: `isScannablePath` is deliberately decidable
+ * from a synthetic path, so that the walk's prune and the rule's exclusion are
+ * one function and its red proofs can enter at the top. That is why this file
+ * splits into a filesystem half and a pure half — the conversion is to resolve
+ * the roots once in `main()` and pass them into the predicate, so the predicate
+ * stays pure and the literal becomes derived. It is not done here, because the
+ * conversion re-measures a green check's read size and its inventory entry, and
+ * a bug fix is the wrong place to move a passing check's population.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { PRUNED_DIRECTORIES } from './module-roots.js';
+/**
+ * The entry whose presence makes a directory the root of a checkout.
+ *
+ * A constant rather than a literal in three places, because the whole rule
+ * rests on this one name and a reader has to be able to find every use of it.
+ */
+export const CHECKOUT_MARKER = '.git';
+/** How deep {@link nestedCheckoutRoots} descends before giving up. */
+const MAX_DEPTH = 12;
+function isDirectory(path) {
+    const stat = statSync(path, { throwIfNoEntry: false });
+    return stat !== undefined && stat.isDirectory();
+}
+function exists(path) {
+    return statSync(path, { throwIfNoEntry: false }) !== undefined;
+}
+/**
+ * The root of every checkout nested inside `repoRoot`, repo-relative, sorted.
+ *
+ * The checkout's **own** marker is stepped over by name: the walk starts at the
+ * repository root, so the marker there says nothing about a nested tree. A rule
+ * that pruned any directory carrying a `.git` would prune the repository and
+ * answer "nothing here", which is the vacuous pass in its purest form — the
+ * fixture in `test/unit/scripts/nested-checkouts.test.ts` carries an outer
+ * marker for exactly that reason.
+ *
+ * The walk does not descend into a nested checkout: everything under it belongs
+ * to that checkout, and a worktree of this repository holds a full copy of
+ * `node_modules`-free source that would otherwise be walked in its entirety.
+ */
+export function nestedCheckoutRoots(repoRoot) {
+    const roots = [];
+    const visit = (directory, relative, depth) => {
+        if (depth > MAX_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(directory);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (PRUNED_DIRECTORIES.includes(entry))
+                continue;
+            const full = join(directory, entry);
+            if (!isDirectory(full))
+                continue;
+            const key = relative === '' ? entry : `${relative}/${entry}`;
+            if (exists(join(full, CHECKOUT_MARKER))) {
+                roots.push(key);
+                continue;
+            }
+            visit(full, key, depth + 1);
+        }
+    };
+    visit(repoRoot, '', 0);
+    return roots.sort();
+}
+/**
+ * Whether a repo-relative path names a nested checkout or something inside one.
+ *
+ * The roots are literal paths, so the comparison is a literal prefix test with
+ * the separator appended — that is what makes `vendor/fork` not match
+ * `vendor/fork-of-ours`, and it is why the shell twin uses `index(…) == 1`
+ * rather than a regex built from a path holding unescaped dots. The root itself
+ * matches: a listing that names the directory is naming another checkout.
+ */
+export function isInsideNestedCheckout(relativePath, roots) {
+    const path = relativePath.split('\\').join('/');
+    return roots.some((root) => path === root || path.startsWith(`${root}/`));
+}
+//# sourceMappingURL=nested-checkouts.js.map

package/dist/lib/nested-checkouts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-checkouts.js","sourceRoot":"","sources":["../../src/lib/nested-checkouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AAEtC,sEAAsE;AACtE,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB,SAAS,WAAW,CAAC,IAAY;IAC/B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;IACvD,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;AAClD,CAAC;AAED,SAAS,MAAM,CAAC,IAAY;IAC1B,OAAO,QAAQ,CAAC,IAAI,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,KAAK,SAAS,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,MAAM,KAAK,GAAG,CAAC,SAAiB,EAAE,QAAgB,EAAE,KAAa,EAAQ,EAAE;QACzE,IAAI,KAAK,GAAG,SAAS;YAAE,OAAO;QAC9B,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,kBAAkB,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,SAAS;YACjD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;YACpC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;gBAAE,SAAS;YACjC,MAAM,GAAG,GAAG,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,IAAI,KAAK,EAAE,CAAC;YAC7D,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC;gBACxC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAChB,SAAS;YACX,CAAC;YACD,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC,CAAC;IAEF,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IACvB,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,YAAoB,EACpB,KAAwB;IAExB,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;AAC5E,CAAC"}

package/dist/lib/platform-root.d.ts

@@ -0,0 +1,43 @@
+import { type WorkspaceFs, type WorkspaceMember } from './workspace-packages.js';
+/** Raised when the platform cannot be located; a caller turns it into exit 2. */
+export declare class PlatformRootUnresolvableError extends Error {
+    readonly name = "PlatformRootUnresolvableError";
+}
+/**
+ * The platform's source directory among a set of workspace members, or `null`.
+ *
+ * `null` and not a throw, because the fixture workspaces the layout tests build
+ * legitimately have no platform. A caller for which the platform *is* the
+ * population — `check:platform-surface`, `check:kernel-boundary` — refuses on
+ * `null` itself, which is the only place that refusal means anything.
+ */
+export declare function platformSourceRootOf(members: readonly WorkspaceMember[]): string | null;
+/**
+ * The npm name the platform publishes under, or `null` when this workspace has
+ * no platform member (feature 080, T060).
+ *
+ * The name is what a packaged module *writes* — `@endora-commerce/platform/kernel`
+ * — so a check that judges a bare specifier needs it, and needs it derived: the
+ * scope was `@b2b/` until D-161 and a literal in a check is a rename away from a
+ * walk that silently sees nothing. It is read from the same manifest
+ * {@link platformSourceRootOf} and {@link platformSubpathsOf} read, so the three
+ * cannot come to disagree about which member is the platform.
+ */
+export declare function platformPackageNameOf(members: readonly WorkspaceMember[]): string | null;
+/** The same, reading the workspace at `repoRoot`. */
+export declare function platformSourceRootAt(repoRoot: string, fs?: WorkspaceFs): string | null;
+/**
+ * The subpaths the platform publishes, read off its own `exports` map.
+ *
+ * D-160.7 rules five enumerated subpaths, one per platform directory, and that
+ * map is where the ruling is authored. Reading it is what
+ * `lib/platform-surface.ts` said it would do "the day the host `package.json`
+ * exists": it does now, and `backend` depends on it, so a sixth published
+ * directory arrives in every walk at once instead of in whichever list somebody
+ * remembers. `./package.json` is filtered out — it is an `exports` entry and not
+ * a platform directory.
+ */
+export declare function platformSubpathsOf(members: readonly WorkspaceMember[]): readonly string[];
+/** The same, reading the workspace at `repoRoot`. */
+export declare function platformSubpathsAt(repoRoot: string, fs?: WorkspaceFs): readonly string[];
+//# sourceMappingURL=platform-root.d.ts.map

package/dist/lib/platform-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-root.d.ts","sourceRoot":"","sources":["../../src/lib/platform-root.ts"],"names":[],"mappings":"AAqCA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,yBAAyB,CAAC;AAEjC,iFAAiF;AACjF,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,SAAkB,IAAI,mCAAmC;CAC1D;AASD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,GAAG,IAAI,CAmBvF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,GAAG,IAAI,CAWxF;AAED,qDAAqD;AACrD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,EAAE,GAAE,WAA+B,GAClC,MAAM,GAAG,IAAI,CAEf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,MAAM,EAAE,CAuBzF;AAED,qDAAqD;AACrD,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,EAAE,GAAE,WAA+B,GAClC,SAAS,MAAM,EAAE,CAEnB"}

package/dist/lib/platform-root.js

@@ -0,0 +1,134 @@
+/**
+ * "Where does the platform's source live?" — derived, never spelled (feature
+ * 080, the platform relocation).
+ *
+ * The five platform directories — `kernel`, `http`, `tenancy`, `commands`,
+ * `events` — moved out of `backend/src` and into `@endora-commerce/platform`,
+ * so that the application and an installed extension package resolve **one**
+ * copy of them. A dozen tools read that tree: `check:platform-surface`,
+ * `check:kernel-boundary`, every check that walks
+ * {@link ModuleTreeLayout.sourceRoots}, and the composer generator, whose entity
+ * registry would otherwise lose `sales_channels`, `settings`, `audit_logs` and
+ * `module_registrations`.
+ *
+ * Every one of them used to write `join(BACKEND_ROOT, 'src', 'kernel')`, which
+ * is the shape `scripts/lib/module-root.sh` was written to end for the module
+ * tree and for the same reason (feature 080, T012): a path written into a tool
+ * is a derived fact recorded by hand (D-100), and a layout move takes the tool
+ * with it — the walk iterates nothing, the check reports on what is left, and
+ * the run prints a green tick. Issue #215 is that defect one directory over.
+ *
+ * ## The discriminator is a declaration, not a name
+ *
+ * The platform is the workspace member whose manifest declares
+ * `"endora": { "type": "platform" }` — the same authored block `lib/module-roots.ts`
+ * and `lib/module-packages.ts` already read to find a *module* package, and the
+ * shape D-142 makes authoritative for a package's identity. Keying on the
+ * package name would work until the scope rename D-161 is finished; keying on
+ * `packages/platform/` would work until somebody moves it, which is the move
+ * this file exists because of.
+ *
+ * Two members declaring it is an error rather than a first-one-wins, for the
+ * reason `scripts/lib/module-root.sh` refuses two manifest indexes: the walk
+ * would silently narrow to whichever sorted first.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { nodeWorkspaceFs, workspaceMembers, } from './workspace-packages.js';
+/** Raised when the platform cannot be located; a caller turns it into exit 2. */
+export class PlatformRootUnresolvableError extends Error {
+    name = 'PlatformRootUnresolvableError';
+}
+/** The `endora` block a member declares about itself, if it is the platform's. */
+function declaresPlatform(member) {
+    const endora = member.manifest['endora'];
+    if (typeof endora !== 'object' || endora === null || Array.isArray(endora))
+        return false;
+    return endora['type'] === 'platform';
+}
+/**
+ * The platform's source directory among a set of workspace members, or `null`.
+ *
+ * `null` and not a throw, because the fixture workspaces the layout tests build
+ * legitimately have no platform. A caller for which the platform *is* the
+ * population — `check:platform-surface`, `check:kernel-boundary` — refuses on
+ * `null` itself, which is the only place that refusal means anything.
+ */
+export function platformSourceRootOf(members) {
+    const declared = members.filter(declaresPlatform);
+    if (declared.length === 0)
+        return null;
+    if (declared.length > 1) {
+        throw new PlatformRootUnresolvableError(`${declared.length} workspace members declare \`endora.type: "platform"\` ` +
+            `(${declared.map((member) => member.dir).join(', ')}). A walk would narrow to ` +
+            'whichever sorted first and report on it as if it were the platform.');
+    }
+    const root = join(declared[0].dir, 'src');
+    if (!existsSync(root)) {
+        throw new PlatformRootUnresolvableError(`${root} does not exist — ${declared[0].name} declares itself the platform and its ` +
+            'sources are not there. A walk of it would come back empty, which is ' +
+            'indistinguishable from a clean platform (issue #113).');
+    }
+    return root;
+}
+/**
+ * The npm name the platform publishes under, or `null` when this workspace has
+ * no platform member (feature 080, T060).
+ *
+ * The name is what a packaged module *writes* — `@endora-commerce/platform/kernel`
+ * — so a check that judges a bare specifier needs it, and needs it derived: the
+ * scope was `@b2b/` until D-161 and a literal in a check is a rename away from a
+ * walk that silently sees nothing. It is read from the same manifest
+ * {@link platformSourceRootOf} and {@link platformSubpathsOf} read, so the three
+ * cannot come to disagree about which member is the platform.
+ */
+export function platformPackageNameOf(members) {
+    const declared = members.filter(declaresPlatform);
+    if (declared.length === 0)
+        return null;
+    if (declared.length > 1) {
+        throw new PlatformRootUnresolvableError(`${declared.length} workspace members declare \`endora.type: "platform"\` ` +
+            `(${declared.map((member) => member.name).join(', ')}). A consumer's bare specifier ` +
+            'would be judged against whichever sorted first.');
+    }
+    return declared[0].name;
+}
+/** The same, reading the workspace at `repoRoot`. */
+export function platformSourceRootAt(repoRoot, fs = nodeWorkspaceFs()) {
+    return platformSourceRootOf(workspaceMembers(repoRoot, fs));
+}
+/**
+ * The subpaths the platform publishes, read off its own `exports` map.
+ *
+ * D-160.7 rules five enumerated subpaths, one per platform directory, and that
+ * map is where the ruling is authored. Reading it is what
+ * `lib/platform-surface.ts` said it would do "the day the host `package.json`
+ * exists": it does now, and `backend` depends on it, so a sixth published
+ * directory arrives in every walk at once instead of in whichever list somebody
+ * remembers. `./package.json` is filtered out — it is an `exports` entry and not
+ * a platform directory.
+ */
+export function platformSubpathsOf(members) {
+    const declared = members.filter(declaresPlatform);
+    if (declared.length !== 1) {
+        throw new PlatformRootUnresolvableError(`${declared.length} workspace members declare \`endora.type: "platform"\` — the ` +
+            'published subpaths are read off exactly one manifest');
+    }
+    const exportsBlock = declared[0].manifest['exports'];
+    const subpaths = typeof exportsBlock === 'object' && exportsBlock !== null && !Array.isArray(exportsBlock)
+        ? Object.keys(exportsBlock)
+            .filter((key) => key.startsWith('./') && key !== './package.json')
+            .map((key) => key.slice(2))
+            .sort()
+        : [];
+    if (subpaths.length === 0) {
+        throw new PlatformRootUnresolvableError(`${declared[0].name} publishes no subpath. Every consumer of this list would walk ` +
+            'nothing and report a clean result over an empty population.');
+    }
+    return subpaths;
+}
+/** The same, reading the workspace at `repoRoot`. */
+export function platformSubpathsAt(repoRoot, fs = nodeWorkspaceFs()) {
+    return platformSubpathsOf(workspaceMembers(repoRoot, fs));
+}
+//# sourceMappingURL=platform-root.js.map

package/dist/lib/platform-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-root.js","sourceRoot":"","sources":["../../src/lib/platform-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACL,eAAe,EACf,gBAAgB,GAGjB,MAAM,yBAAyB,CAAC;AAEjC,iFAAiF;AACjF,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACpC,IAAI,GAAG,+BAA+B,CAAC;CAC1D;AAED,kFAAkF;AAClF,SAAS,gBAAgB,CAAC,MAAuB;IAC/C,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IACzF,OAAQ,MAAkC,CAAC,MAAM,CAAC,KAAK,UAAU,CAAC;AACpE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAmC;IACtE,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAClD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,6BAA6B,CACrC,GAAG,QAAQ,CAAC,MAAM,yDAAyD;YACzE,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,4BAA4B;YAC/E,qEAAqE,CACxE,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC3C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,6BAA6B,CACrC,GAAG,IAAI,qBAAqB,QAAQ,CAAC,CAAC,CAAE,CAAC,IAAI,wCAAwC;YACnF,sEAAsE;YACtE,uDAAuD,CAC1D,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAmC;IACvE,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAClD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,6BAA6B,CACrC,GAAG,QAAQ,CAAC,MAAM,yDAAyD;YACzE,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,iCAAiC;YACrF,iDAAiD,CACpD,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC;AAC3B,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,oBAAoB,CAClC,QAAgB,EAChB,KAAkB,eAAe,EAAE;IAEnC,OAAO,oBAAoB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAmC;IACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAClD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,6BAA6B,CACrC,GAAG,QAAQ,CAAC,MAAM,+DAA+D;YAC/E,sDAAsD,CACzD,CAAC;IACJ,CAAC;IACD,MAAM,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACtD,MAAM,QAAQ,GACZ,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC;QACvF,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC;aACtB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,gBAAgB,CAAC;aACjE,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;aAC1B,IAAI,EAAE;QACX,CAAC,CAAC,EAAE,CAAC;IACT,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,6BAA6B,CACrC,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC,IAAI,gEAAgE;YAClF,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,KAAkB,eAAe,EAAE;IAEnC,OAAO,kBAAkB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/lib/platform-surface.d.ts

@@ -0,0 +1,235 @@
+/**
+ * The platform directories the host publishes, in the order §2.1 lists them.
+ *
+ * A ruling (D-160.7), not a measurement — see the header. `db`, `overlay` and
+ * `packages` are absent on purpose and `db`'s absence is the whole of §1.4f: a
+ * reach into it is not public API. All three are now **declared and
+ * host-internal** (`specs/110-instance-repository/` T113, T114 and T116): the
+ * code moved into the package, so the application needed an address for it, and
+ * the answer to "may a module name it" is still no — see
+ * {@link HOST_INTERNAL_SUBPATHS}, which is where that judgement is recorded.
+ */
+export declare const PUBLISHED_SUBPATHS: readonly string[];
+/**
+ * The subpaths the `exports` map declares and **no published barrel carries**
+ * (D-160.14), each with the reason it is on this side of the line.
+ *
+ * A subpath here is declared, so `node` and `tsc` resolve it for the host, the
+ * test kit and the composition root — and it is not public API, so
+ * {@link resolveHostSpecifier} answers a module's reach into one with
+ * `host-internal-subpath` rather than with a pass. **The reason is the member**:
+ * a set of bare names is a list somebody grows, and this whole class is a
+ * judgement about who may name a surface, which no name records.
+ *
+ * It is kept apart from {@link PUBLISHED_SUBPATHS} rather than appended to it
+ * because the two answer different questions, and `host-package.md` §2.7.5(a) is
+ * that merging them is the mistake: the published list is what a **symbol** is
+ * judged against, and an entry there would publish `composeModules` out of
+ * `kernel/compose.ts` for every reach at that file — a module's relative one
+ * included — while changing nothing `check:platform-surface` prints.
+ *
+ * It lives here rather than in a test because by the time it had two members it
+ * had two copies, in two test files, neither carrying a per-member reason. Two
+ * independently written answers to "which subpaths are host-internal" are two
+ * answers waiting to disagree, in the estate whose own rule that is (D-100).
+ */
+export declare const HOST_INTERNAL_SUBPATHS: Readonly<Record<string, string>>;
+/** The file a published directory's surface is written in. */
+export declare function barrelKeyOf(subpath: string): string;
+/** One name a barrel publishes, and the file it publishes it out of. */
+export interface PublishedSymbol {
+    /** The exported name, after any `as` rename. */
+    readonly name: string;
+    /**
+     * The file it comes from, keyed relative to the source root with POSIX
+     * separators — `http/error-envelope.ts`. A name the barrel *declares* itself
+     * is attributed to the barrel.
+     */
+    readonly target: string;
+}
+/** Why a barrel could not be read in full — never a reason to report a pass. */
+export interface BarrelUnreadable {
+    /** The barrel, keyed relative to the source root. */
+    readonly barrel: string;
+    readonly line: number;
+    readonly reason: string;
+}
+export interface BarrelParse {
+    readonly barrel: string;
+    readonly published: readonly PublishedSymbol[];
+    readonly unreadable: readonly BarrelUnreadable[];
+}
+/**
+ * How a barrel's re-export specifier becomes a file key.
+ *
+ * Injected because the answer needs the walk's file list — `./ports` is a
+ * directory in one tree and a file in another — while {@link parseBarrel} must
+ * stay pure over source text so both consumers' fixtures enter at the top.
+ * {@link firstCandidate} is the answer for a caller that has no file list: the
+ * `.js` → `.ts` rewrite every specifier in this tree's barrels is written as.
+ */
+export type TargetResolver = (fromKey: string, specifier: string) => string | null;
+/** The `.js` → `.ts` rewrite, with no filesystem behind it. */
+export declare const firstCandidate: TargetResolver;
+/**
+ * Everything one barrel publishes, and everything about it this parse could not
+ * read.
+ *
+ * Pure over the source text, so both consumers — and every fixture — enter
+ * where a real run enters.
+ *
+ * The three shapes it refuses to guess at are the three that would make the
+ * published set come back **short**, which is the direction that turns a
+ * correct reach into a finding and, worse, lets an author "repair" it by
+ * widening the barrel:
+ *
+ *   * `export * from './x.js'` — the names are in another file;
+ *   * `export * as ns from './x.js'` — a namespace object, whose members no
+ *     `exports` map can enumerate;
+ *   * `export { X }` with no `from` — a re-export of a local binding whose own
+ *     origin this parse does not follow.
+ *
+ * None of the three occurs in the five barrels today. Each is reported rather
+ * than skipped, because a barrel this file reads *partially* is exactly the
+ * "green while not looking" shape issue #113 is about.
+ */
+export declare function parseBarrel(source: string, barrel: string, resolve?: TargetResolver): BarrelParse;
+/**
+ * A relative specifier from `fromKey`, as a key relative to the same root.
+ *
+ * The `.js` an ESM specifier carries is rewritten to `.ts`, an extensionless
+ * specifier gains one, and a directory specifier gains `/index.ts` — the three
+ * shapes this tree writes. `null` for a specifier that is not relative, or that
+ * climbs out of the root.
+ */
+export declare function resolveRelative(fromKey: string, specifier: string): string | null;
+/**
+ * The host package as a consumer names it (feature 080, T060).
+ *
+ * A module that has become a workspace package stops writing
+ * `../../kernel/index.js` and writes `@endora-commerce/platform/kernel`. Both
+ * are the same reach at the same barrel, and until T060 only the first was in
+ * the check's population — so a module's platform reaches left the walk the day
+ * the module left the tree, 216 of them by the first batch.
+ *
+ * Neither field is written down anywhere. {@link HostPackage.name} is the name
+ * in the manifest of the member declaring `endora.type: "platform"`, and
+ * {@link HostPackage.subpathTargets} is that manifest's own `exports` map read
+ * back as file keys — so the D-161 scope rename, a sixth published directory
+ * and a renamed host all arrive here by being authored once.
+ */
+export interface HostPackage {
+    /** The npm name the host publishes under. */
+    readonly name: string;
+    /**
+     * **Published** subpath (`kernel`) → the barrel's file key, in the caller's
+     * own namespace. This is {@link PUBLISHED_SUBPATHS}' population, not the
+     * `exports` map's: a subpath the map declares and no barrel carries is in
+     * {@link HostPackage.declaredSubpaths} and not here.
+     */
+    readonly subpathTargets: ReadonlyMap<string, string>;
+    /**
+     * Every subpath the host's own `exports` map declares, `./package.json`
+     * aside — read off the manifest, never written down (`lib/platform-root.ts`'s
+     * `platformSubpathsOf`).
+     *
+     * It exists because the two lists legitimately differ (D-160.14, feature 109;
+     * `host-package.md` §2.7.5a). `./composition` carries the 27 composition
+     * symbols the host's own root and the test kit need: **declared** by the map,
+     * so `node` and `tsc` resolve it, and **published** by no barrel, so no module
+     * may name it. Without both lists a reach into it is indistinguishable from a
+     * reach into a subpath that does not exist, and the remedy a consumer is
+     * handed — *"the map refuses this at resolution time"* — is false.
+     *
+     * It must not be folded into {@link PUBLISHED_SUBPATHS} either, which was
+     * measured: {@link PlatformSurface.published} is keyed by **target file** with
+     * no subpath dimension, so a sixth entry there publishes `composeModules` out
+     * of `kernel/compose.ts` for every reach at that file, a module's *relative*
+     * one included — and because this check reports `violations=0`, the widening
+     * would change nothing it prints. A blindness that arrives green.
+     */
+    readonly declaredSubpaths: ReadonlySet<string>;
+}
+/** What a bare specifier into the host package names, or nothing. */
+export type HostReach = {
+    readonly kind: 'published-subpath';
+    readonly subpath: string;
+    readonly target: string;
+}
+/**
+ * Declared by the `exports` map, carried by no barrel — host composition
+ * surface. It resolves for `node` and `tsc`, which is exactly why a module
+ * naming it needs a finding of its own: nothing else would stop it.
+ */
+ | {
+    readonly kind: 'host-internal-subpath';
+    readonly subpath: string;
+} | {
+    readonly kind: 'undeclared-subpath';
+    readonly subpath: string;
+};
+/**
+ * The host file a bare specifier names, or `null` when it does not name the
+ * host at all.
+ *
+ * The match is on a **segment boundary**, which is the same care
+ * `check-module-boundary`'s `resolveModulePackage` takes and for the same
+ * reason: `@endora-commerce/platform-extras` is a different package, and a bare
+ * `startsWith` reads it as this one.
+ *
+ * `null` for a relative specifier, for a third party's, and for every specifier
+ * at all when the workspace declares no platform — a fixture workspace
+ * legitimately has none, and "no host reach" is the only honest answer there.
+ *
+ * **Three answers, not two** (D-160.14). A subpath the `exports` map declares
+ * and no barrel carries is `host-internal-subpath`, between the published one
+ * and the one that does not exist. Collapsing it into either is wrong in a
+ * different way: as *published* it would license the reach, and as *undeclared*
+ * it would tell the author their specifier does not resolve, which it does.
+ */
+export declare function resolveHostSpecifier(specifier: string, host: HostPackage | null): HostReach | null;
+/**
+ * Every candidate file a relative specifier could name, most specific first.
+ *
+ * `.tsx` is here beside `.ts` because a module's sources are no longer only
+ * Node code: a module package's `./admin` layer (feature 091) is React
+ * components, and a `./pages/Screen.js` specifier inside one resolves to a
+ * `.tsx` file or to nothing. Nothing is the fail-closed answer this check gives
+ * an unresolvable reach — correct as a default, and wrong here, where the file
+ * is there and the candidate list had never heard of its extension.
+ */
+export declare function resolutionCandidates(joined: string): readonly string[];
+/** The platform's published surface, as both consumers read it. */
+export interface PlatformSurface {
+    /** `<target file>` → the names the barrels publish out of it. */
+    readonly published: ReadonlyMap<string, ReadonlySet<string>>;
+    /**
+     * `<target file>` → the barrels that publish it — {@link PlatformSurface.published}'s
+     * provenance, which the merge above otherwise drops.
+     *
+     * It exists for one question {@link PlatformSurface.published} cannot answer:
+     * *which subpath carries this file*. A caller holding the `exports` map knows
+     * subpath → barrel, so barrel → target closes the chain and a remedy can name
+     * the address a reach should have used. Deriving it here rather than in the
+     * caller keeps it the same parse the verdict rests on: a second walk of the
+     * barrels would be a second answer to "what does this barrel re-export", which
+     * is the duplication this file's own header exists to refuse.
+     */
+    readonly publishedBy: ReadonlyMap<string, ReadonlySet<string>>;
+    /** The barrel files themselves — reaching one is reaching the published surface. */
+    readonly barrels: ReadonlySet<string>;
+    /** Everything the parse could not read. A caller turns a non-empty list into exit 2. */
+    readonly unreadable: readonly BarrelUnreadable[];
+    /** Barrels that parsed to at least one published name — the `sources=` numerator. */
+    readonly barrelsWithExports: number;
+}
+/**
+ * The surface, from the barrel sources.
+ *
+ * `barrels` is keyed by the barrel's own path relative to the source root, so a
+ * caller that hands in fewer than {@link PUBLISHED_SUBPATHS} gets a surface that
+ * says so through {@link PlatformSurface.barrelsWithExports} rather than a
+ * quietly narrower answer.
+ */
+export declare function publishedSurface(barrels: ReadonlyMap<string, string>, resolve?: TargetResolver): PlatformSurface;
+//# sourceMappingURL=platform-surface.d.ts.map

package/dist/lib/platform-surface.d.ts.map

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