@endora-commerce/cli 0.100.0

package/dist/lib/admin-surfaces.d.ts

@@ -0,0 +1,298 @@
+import type { WorkspaceMember } from './workspace-packages.js';
+/** The alias every admin file writes its own host imports through. */
+export declare const ADMIN_SOURCE_ALIAS = "@/*";
+/**
+ * The owner id of the admin application itself.
+ *
+ * Not a module, and it has to be spelled somewhere: since P1 of
+ * `specs/091-module-owned-admin-surfaces/` § *Phase 4* `check:module-boundary`
+ * attributes an admin **host** file to it, so a reach out of one has a consumer
+ * to be ledgered under.
+ *
+ * One spelling, **here**, and this is the moment that placement was for:
+ * `check:admin-registrations` — which attributed a route or a nav entry no
+ * module claimed to the same owner — and `ledgers/admin-registrations.ts`,
+ * where this constant used to live, were deleted by batch 16 when the drain
+ * emptied their population (SC-007, Phase 5 T5). The boundary ledger outlives
+ * them and goes on using this name unchanged.
+ */
+export declare const ADMIN_HOST_OWNER = "host";
+/**
+ * The generated admin contribution registry, by name.
+ *
+ * `generate-composer.ts` renders it into {@link AdminSurfaceLayout.sourceRoot},
+ * and `check:module-boundary` exempts it: a generated registry naming every
+ * contributing module package by a bare specifier is a composition root doing
+ * its job, exactly as `composition.generated.ts` is in the backend. Both derive
+ * the path from this constant and from the alias member, so neither can end up
+ * looking at a file the other has stopped writing.
+ */
+export declare const ADMIN_REGISTRY_ARTEFACT = "modules.generated.ts";
+/** Raised when the admin layout cannot be resolved; a caller turns it into exit 2. */
+export declare class AdminLayoutUnresolvableError extends Error {
+    readonly name = "AdminLayoutUnresolvableError";
+}
+/** One admin route as `App.tsx` declares it. */
+export interface AdminRouteDeclaration {
+    /** The `path` prop, exactly as written. */
+    readonly path: string;
+    /** The component the `element` prop renders, or `null` when it renders none. */
+    readonly component: string | null;
+    readonly line: number;
+}
+/** One sidebar entry as `AppShell.tsx`'s `NAV` declares it. */
+export interface AdminNavDeclaration {
+    /** The `to` field. */
+    readonly to: string;
+    /** The `module` field — `null` where the entry is the application's own. */
+    readonly module: string | null;
+    readonly line: number;
+}
+/** Everything derived about the admin application's module surfaces. */
+export interface AdminSurfaceLayout {
+    /** The workspace member declaring the `@/*` alias. */
+    readonly memberDir: string;
+    /**
+     * The directory that alias points at — `admin/src`.
+     *
+     * The **admin project's** source root, and since feature 110's T120 that is
+     * narrower than "where the admin's code is": the generated contribution
+     * registry lands here and the shell's screens do not. Use
+     * {@link AdminSurfaceLayout.hostRoots} for a walk of the admin's own sources.
+     */
+    readonly sourceRoot: string;
+    /**
+     * The source root holding the route table and the nav —
+     * `packages/admin-shell/src`, or {@link AdminSurfaceLayout.sourceRoot} on a
+     * tree where the alias member still holds them.
+     *
+     * Located by the pair of artefacts this layout is read out of rather than by
+     * a directory or a package name, so the extraction moved the derivation with
+     * the files instead of rewriting it (feature 110, T122).
+     */
+    readonly shellRoot: string;
+    /**
+     * Every source root the admin application owns — the alias member's and the
+     * shell's, deduplicated and sorted.
+     *
+     * This is the population for anything whose subject is *"the admin's own
+     * code"*: `check:module-boundary`'s {@link ADMIN_HOST_OWNER} walk,
+     * `check:admin-zones`' render and contribution walk, and `i18n:hardcoded`'s
+     * first root. One list, because two instruments deriving the same population
+     * twice are two answers waiting to disagree — which this repository has
+     * already watched happen to `i18n:hardcoded` and its own companion test
+     * (!1182).
+     *
+     * The shell is deliberately **not** an `endora: { type: 'admin-ui' }` member:
+     * that declaration's third population assumes no namespace in the file can be
+     * the file's own, which is true of a design-system package and false of the
+     * host — the dashboard's tiles gate on `catalog` and `orders` by name because
+     * mounting module surfaces is what the shell is for.
+     */
+    readonly hostRoots: readonly string[];
+    /**
+     * The directory holding the module surfaces — `admin/src/modules` — or
+     * `null` when the application has none left (feature 091, R16).
+     *
+     * **Zero module roots is a measurement; two is still blindness.** The
+     * predicate's two inputs are proved present before it is evaluated:
+     * {@link resolveAdminSurfaces} has already refused a missing or ambiguous
+     * alias member and an alias target that is not on disk, and the registered id
+     * set comes from a generated manifest index `requireModuleLayout` refuses a
+     * tree without. With both proved, *"no directory under the source root is
+     * named after a registered module"* is an answer three artefacts with three
+     * authors give together — the tsconfig alias, the manifest index and the
+     * filesystem — and it flips back by itself the day a module directory
+     * reappears, which is the property a written-down "drain complete" flag would
+     * not have.
+     *
+     * `null` rather than `''` so `tsc` forces every consumer to answer; every
+     * answer is the same trivial one, because nothing is under a directory that
+     * does not exist.
+     */
+    readonly moduleRoot: string | null;
+    /** The alias prefix a specifier is written with, including its slash: `@/`. */
+    readonly aliasPrefix: string;
+    /** Every directory under {@link moduleRoot}, sorted — empty where it is `null`. */
+    readonly directories: readonly string[];
+    /** Directory name → the module that owns it. Absent means host-owned. */
+    readonly moduleOfDirectory: ReadonlyMap<string, string>;
+    /** The routes `App.tsx` declares. */
+    readonly routes: readonly AdminRouteDeclaration[];
+    /** The nav entries `AppShell.tsx` declares. */
+    readonly nav: readonly AdminNavDeclaration[];
+    /** Component name → the module directory `App.tsx` imports it from. */
+    readonly componentDirectories: ReadonlyMap<string, string>;
+    /**
+     * The two hand-written registries this layout is read out of — `App.tsx` and
+     * `components/AppShell.tsx` under {@link AdminSurfaceLayout.shellRoot},
+     * absolute.
+     *
+     * Returned rather than left implicit because a consumer has to be able to
+     * exclude them **without spelling them a second time**. `App.tsx` imports one
+     * component per module screen, so a boundary ledger that counted them would
+     * record the feature's own subject as its debt, one entry per route, churning
+     * with every batch. They were the whole population of the deleted
+     * `check:admin-registrations` (`files=2`); what asserts them now is
+     * `admin/test/modules/host-admin-registrations.test.tsx` (R13a).
+     */
+    readonly registryFiles: readonly string[];
+    /**
+     * The generated contribution registry — {@link ADMIN_REGISTRY_ARTEFACT} under
+     * {@link sourceRoot}, absolute.
+     *
+     * Named whether or not it is on disk: the path is where the generator puts
+     * it, and a checkout that has not run `composer:generate` has no artefact and
+     * nothing to exclude.
+     */
+    readonly generatedRegistryFile: string;
+}
+/**
+ * The one workspace member whose tsconfig declares the source alias.
+ *
+ * Read out of `tsconfig.json` rather than out of a Vite config, because the
+ * tsconfig is the one both `tsc` and the bundler agree on and the one this
+ * repository's own `paths` discipline is already written against.
+ */
+export declare function findAliasMember(members: readonly WorkspaceMember[], readText?: (path: string) => string | null): {
+    readonly member: WorkspaceMember;
+    readonly target: string;
+};
+/**
+ * The directory `"@/*"` maps to, as written in the tsconfig, or `null`.
+ *
+ * Parsed with the compiler's own JSONC reader, because a tsconfig in this
+ * repository carries comments and `JSON.parse` refuses one.
+ */
+export declare function aliasTargetOf(tsconfigText: string): string | null;
+/**
+ * Does this workspace hold an admin application at all?
+ *
+ * `true` when a member declares the source alias, which is the one declaration
+ * that says *"this repository has a frontend"* and needs neither the shell nor
+ * a registered-id set to answer. It is the discriminator between the two states
+ * a `null` {@link AdminSurfaceLayout} has run together since feature 091: a
+ * workspace with no frontend — every fixture in the tree, and the behaviour
+ * that shipped — and a frontend whose route table the walk has stopped finding,
+ * which is exit 2 (feature 110, T122).
+ *
+ * The second state is not hypothetical and is what T120 makes reachable: with
+ * `App.tsx` and the nav inside `@endora-commerce/admin-shell`, a checkout whose
+ * shell is not installed, not built, or renamed has a perfectly good alias
+ * member holding four files — and every admin population would come back empty
+ * with `violations=0` beside it.
+ */
+export declare function adminApplicationPresent(members: readonly WorkspaceMember[], readText?: (path: string) => string | null): boolean;
+/**
+ * The source root holding **both** the route table and the nav.
+ *
+ * Feature 110's T120 moved them out of the admin project into
+ * `@endora-commerce/admin-shell`, and T122's requirement is that the two checks
+ * reading them report the same findings before and after. So the subject is the
+ * **pair of artefacts** and never the directory: whichever member holds them is
+ * the shell, and on a tree where that is still the alias member the answer does
+ * not move at all.
+ *
+ * Zero is a refusal and not a `null`, unlike {@link findAdminModuleRoot}'s
+ * empty answer: an admin application with no route table is not a drained
+ * population, it is a walk that has stopped finding the file every attribution
+ * in this module is read out of. Two is a refusal for {@link findAliasMember}'s
+ * reason — picking one narrows every scan to it without saying so.
+ */
+export declare function findAdminShellRoot(members: readonly WorkspaceMember[], readText?: (path: string) => string | null): string;
+/**
+ * Every source root the admin application owns — the alias member's and the
+ * shell's — sorted, deduplicated.
+ *
+ * **Narrower than the layout, deliberately**, on {@link adminRegistryPathOf}'s
+ * reasoning: `i18n:hardcoded` needs the walk and needs nothing about module
+ * attribution, so it must not be made to depend on a registered-id set it has
+ * no other use for. One derivation, two entry points —
+ * {@link resolveAdminSurfaces} builds its `hostRoots` from this function.
+ */
+export declare function adminHostRootsOf(members: readonly WorkspaceMember[], readText?: (path: string) => string | null): readonly string[];
+/**
+ * The generated admin contribution registry's path, or `null` when this
+ * workspace has no admin application at all (feature 091, R13b).
+ *
+ * **Narrower than the layout, deliberately.** It needs the alias member and its
+ * target and nothing else — not `App.tsx`, not `components/AppShell.tsx`, not a
+ * module root — because two checks gate a population floor on this file's
+ * presence and *"the gate went true for a reason having nothing to do with the
+ * registry"* is the exact defect §7.5 measured. `resolveAdminSurfaces` builds
+ * {@link AdminSurfaceLayout.generatedRegistryFile} from this function, so there
+ * is one derivation with two entry points rather than two answers.
+ *
+ * `null` here is the honest absence: with no alias member there is no directory
+ * the artefact could be under, and a caller omits its token rather than
+ * printing `0/0`.
+ */
+export declare function adminRegistryPathOf(members: readonly WorkspaceMember[], readText?: (path: string) => string | null): string | null;
+/**
+ * The one directory under `sourceRoot` whose children are named after registered
+ * modules, or `null` when none is.
+ *
+ * The same predicate {@link applicationModuleRoots} applies in `backend/src`,
+ * minus its `manifest.ts` half: an admin surface directory has no manifest, so
+ * requiring one would find nothing.
+ *
+ * **Absence is a measurement, ambiguity is blindness** (feature 091, R16). Zero
+ * is `null`, because this feature exists to empty that directory and a refusal
+ * would send a reader to repair a finished tree; two is still a throw, because
+ * picking one narrows every walk to it without saying so.
+ *
+ * It takes the admin's **host roots** since feature 110's T122 — the admin
+ * project's and the shell's — because a module surface directory left in the
+ * application would move with `App.tsx` rather than stay behind it. A single
+ * root is still accepted, and means the same thing it meant.
+ */
+export declare function findAdminModuleRoot(sourceRoots: readonly string[] | string, registered: ReadonlySet<string>): string | null;
+/** `<Route path="…" element={<X … />} />` — every one `source` declares. */
+export declare function adminRoutes(source: string, file?: string): AdminRouteDeclaration[];
+/**
+ * `{ to: '…', …, module: '…' }` — every nav entry `source` declares.
+ *
+ * Read as object literals carrying both fields rather than as members of a
+ * constant named `NAV`, so a second nav array — a mobile strip, a settings
+ * sub-nav — is in the population by construction rather than by being added
+ * here.
+ */
+export declare function adminNavEntries(source: string, file?: string): AdminNavDeclaration[];
+/**
+ * Component name → the module directory `App.tsx` imports it from.
+ *
+ * Only specifiers landing inside the module root are recorded, so a host
+ * component is absent rather than attributed to a directory that is not a
+ * module's.
+ */
+export declare function routeComponentDirectories(source: string, moduleRootSegment: string, file?: string): Map<string, string>;
+/**
+ * Directory name → the module that owns it, for every directory under the
+ * module root.
+ *
+ * Two rules, in order, and the second is the one this function exists for:
+ *
+ *   1. a directory named after a registered module is that module's;
+ *   2. a directory whose component renders a route a nav entry attributes to a
+ *      registered module is that module's.
+ *
+ * A directory neither rule claims is the admin application's own and is absent
+ * from the map. Rule 2's join is by route path — exact first, then the longest
+ * nav `to` the route sits under, because `/warehouses/new` is declared as a
+ * route and never as its own sidebar row.
+ */
+export declare function adminModuleDirectories(input: {
+    readonly directories: readonly string[];
+    readonly registered: ReadonlySet<string>;
+    readonly routes: readonly AdminRouteDeclaration[];
+    readonly nav: readonly AdminNavDeclaration[];
+    readonly componentDirectories: ReadonlyMap<string, string>;
+}): Map<string, string>;
+/**
+ * The whole admin layout, resolved once.
+ *
+ * `registered` is the manifest index's own id list, handed in rather than read
+ * here, so the two derivations of "which modules exist" cannot disagree.
+ */
+export declare function resolveAdminSurfaces(members: readonly WorkspaceMember[], registered: ReadonlySet<string>, readText?: (path: string) => string | null): AdminSurfaceLayout;
+//# sourceMappingURL=admin-surfaces.d.ts.map

package/dist/lib/admin-surfaces.d.ts.map

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