@endora-commerce/cli 0.100.0

package/dist/lib/divergence-artefacts.d.ts

@@ -0,0 +1,305 @@
+import type { DivergenceReport } from '@endora-commerce/contracts';
+import { type DivergenceInput, type DivergenceResult, type OverlaySource } from './divergence.js';
+import type { ModulePackage } from './module-packages.js';
+/**
+ * What each rung costs, in the words a reader who has never seen this repository
+ * needs (SC-001).
+ *
+ * The human rendering spells the **cost** rather than the number, because a
+ * number is only meaningful to somebody who has the ladder open beside them —
+ * and the reader this artefact exists for is a client's developer who has not.
+ * The full ladder is `docs/docs/architecture/customisation-ladder.md`; these are
+ * its one-line summaries and they are kept in step by
+ * `test/unit/overlay/divergence-render.test.ts`.
+ */
+export declare const RUNG_COSTS: Readonly<Record<number, string>>;
+/**
+ * The "do not edit" headers this repository's own generator writes.
+ *
+ * Parameters rather than literals, on `admin-artefacts.ts`' and
+ * `docs-artefacts.ts`' precedent: the two hosts tell a reader different things
+ * to run, and an artefact naming the wrong one would send a client to a script
+ * their tree does not have. The default is this repository's, so its committed
+ * artefacts are byte-identical across the move and a host that means the other
+ * one says so.
+ */
+export declare const COMPOSER_DIVERGENCE_MODULE_HEADER: string;
+/** The same, for the human rendering, whose comment syntax is HTML's. */
+export declare const COMPOSER_DIVERGENCE_MARKDOWN_HEADER: string[];
+/**
+ * Emit the report as a committed, typed TS module (mirrors
+ * `manifest-index.generated.ts`).
+ *
+ * `typesImportSpecifier` is the module-resolvable path from the emitted file's
+ * directory to `src/overlay/types.js` — it differs between the core output
+ * (`./types.js`) and a deployment output (`../../overlay/types.js`), so the
+ * caller computes and passes it.
+ */
+export declare function serializeDivergenceModule(report: DivergenceReport, typesImportSpecifier: string, header?: string): string;
+/** Stable JSON serialization, for a caller that wants the shape and no module. */
+export declare function serializeDivergenceJson(report: DivergenceReport): string;
+/**
+ * The human rendering — D-30's own word for this artefact is *report*.
+ *
+ * Three rules, all of them SC-001's: no key strings (a reader is not looking
+ * anything up), no repository-relative paths (the reader's tree is not this
+ * one), and the rung's **cost** spelled out rather than its number.
+ */
+export declare function renderDivergenceMarkdown(report: DivergenceReport, header?: readonly string[]): string;
+/**
+ * Every TypeScript or emitted-JavaScript source under a root, recursively.
+ *
+ * One walk rather than one per host, because the two hosts read two *different
+ * dialects of the same tree* — this repository's modules are sources and an
+ * instance's are the `dist` those sources compile to — and the analysis is the
+ * compiler API either way (`registeredNames` and `routeIdentities` both parse
+ * with `ts.createSourceFile`, which reads emitted JavaScript as readily as it
+ * reads TypeScript). Measured on `packages/modules/blog`: the six container
+ * names and the twenty-nine route identities its sources yield are the same six
+ * and the same twenty-nine its `dist/backend` yields.
+ *
+ * `.d.ts` is excluded here and asked for separately by {@link seamsFromKernel},
+ * which is the one input whose instance answer is a declaration file.
+ */
+export declare function walkAnalysableSources(root: string, out?: string[]): string[];
+/**
+ * A deployment's own overlay sources, attributed to the overlay module that
+ * owns them.
+ *
+ * `base` is the root the reported path is relative to — this repository's root
+ * here, the instance's root there — so an entry names a path in the reader's own
+ * tree and never in ours (SC-001's second rule).
+ */
+export declare function overlaySourcesUnder(overlayRoot: string | null, moduleIds: readonly string[], base: string): OverlaySource[];
+/**
+ * Everything one run needs that does not change between deployments.
+ *
+ * Four facts, and the whole of what the two hosts differ about is **how each is
+ * assembled** — never what it is. `contracts/divergence-report.md` §3.2's
+ * *"it is not recomputed here"* is the same instruction one host over.
+ */
+export interface DivergenceEnvironment {
+    /** Container name → the module that registers it. */
+    readonly owners: ReadonlyMap<string, string>;
+    /** Names a composition root supplies, which no module owns. */
+    readonly rootSupplied: ReadonlySet<string>;
+    /** Every `"<METHOD> <path>"` the composition serves, and who owns it. */
+    readonly routes: ReadonlyMap<string, string | null>;
+    /** `ModuleContext`'s own members. */
+    readonly seams: readonly string[];
+    /** Files this assembly opened — half of the run's `files`. */
+    readonly filesRead: number;
+}
+/** One rendering a host asks for: where it goes and in which dialect. */
+export type DivergenceRenderingSpec = {
+    readonly rendering: 'module';
+    readonly outputPath: string;
+    /** The module-resolvable specifier the emitted file imports `DivergenceReport` from. */
+    readonly typesImportSpecifier: string;
+    readonly header?: string;
+    readonly label: string;
+} | {
+    readonly rendering: 'markdown';
+    readonly outputPath: string;
+    readonly header?: readonly string[];
+    readonly label: string;
+} | {
+    readonly rendering: 'json';
+    readonly outputPath: string;
+    readonly label: string;
+};
+/** One rendering, rendered. */
+export interface DivergenceRendering {
+    readonly outputPath: string;
+    readonly content: string;
+    /** The label `overlay:check` and `endora generate` print. */
+    readonly label: string;
+}
+export interface RenderedDivergenceArtefacts {
+    readonly result: DivergenceResult;
+    readonly renderings: readonly DivergenceRendering[];
+}
+/**
+ * One derivation, N renderings (`data-model.md` §3).
+ *
+ * The loop is here rather than in either host for the reason the file header
+ * gives: a second derivation for a second rendering is two answers to one
+ * question waiting to disagree, and the moment there were three renderings
+ * across two hosts that stopped being hypothetical.
+ */
+export declare function renderDivergenceArtefacts(input: DivergenceInput, specs: readonly DivergenceRenderingSpec[]): RenderedDivergenceArtefacts;
+/**
+ * Does the overlay tree **spell** a seam call at all?
+ *
+ * A second author for the "no seam call of any kind read" refusal
+ * (`divergence-report.md` §5, refusal 3), and the reason it is a text probe
+ * rather than a second walk: what has to be caught is the *syntax walk* going
+ * blind, and a second syntax walk would go blind with it. With two overlay
+ * modules in this repository, a resolver that stopped recognising
+ * `ctx.di.decorate` prints a clean report over a tree full of decorations, and
+ * `sites=0` is indistinguishable from a deployment that only registers routes —
+ * which is a legal thing for an overlay module to do. This tells the two apart.
+ */
+export declare function overlayTreeSpellsASeamCall(sources: readonly OverlaySource[]): boolean;
+/**
+ * What an instance's report cannot derive, each with a reason (FR-018).
+ *
+ * **Every one of the nine kinds is derived in an instance exactly as it is
+ * here**, because the population of all nine is the deployment's own overlay
+ * tree — `apps/<deployment>/modules/**` — which is the client's own source and
+ * is read by the same walk. What differs is **attribution**, in one place, and
+ * that one place is written down here rather than left to be discovered by a
+ * client reading a report with a silent hole in it.
+ *
+ * `HOST_REGISTERED_PORTS` is the bridging table `check:port-dependencies`
+ * carries: names this repository's composition roots register *on an unconverted
+ * module's behalf*, each with its own retiring condition. It is a judgement about
+ * this repository's roots and nothing derives it, so it has no instance
+ * equivalent — in an instance those names are registered by `composeApp` inside
+ * `@endora-commerce/platform`, the walk finds them there, and they come out as
+ * root-supplied. That answer is *true of the instance*; it is simply less
+ * specific than ours, and a client who did not know that would read `a
+ * composition root (no module owns it)` and conclude nothing owns it.
+ */
+export declare const INSTANCE_BOUNDARY_NOTES: ReadonlyArray<{
+    readonly seam: string;
+    readonly why: string;
+}>;
+/** One installed package this run could not read, named rather than skipped. */
+export interface UnreadableCompositionInput {
+    readonly packageName: string;
+    readonly at: string;
+    readonly reason: string;
+}
+export interface InstanceCompositionScan {
+    readonly environment: DivergenceEnvironment;
+    readonly unreadable: readonly UnreadableCompositionInput[];
+    /** Module packages that contributed at least one analysable file. */
+    readonly covered: number;
+    /** Module packages that publish a `./backend` subpath at all. */
+    readonly expected: number;
+}
+/**
+ * `ModuleContext`'s members, out of whatever file beside the platform's
+ * `./kernel` entry point declares the interface.
+ *
+ * A **search** rather than a spelled path, and deliberately: the entry point is
+ * a barrel and re-exports the interface rather than declaring it, so the
+ * declaration is in a sibling — and which sibling is the platform's own business
+ * and its build layout's, neither of which this file may assert (D-100). The
+ * interface *name* is the one thing that is contract here, and it is already
+ * spelled exactly once, in `moduleContextSeams`.
+ */
+export declare function seamsFromKernel(kernelEntry: string): readonly string[];
+/**
+ * The composition an instance runs, read out of what it installed.
+ *
+ * Three of the four facts come from the same two walks: each module package's
+ * published `./backend` layer, and the platform's own. The fourth —
+ * `ModuleContext`'s members — comes from the platform's shipped kernel
+ * declarations, which yield byte-identically what this repository's source does
+ * (measured: the same sixteen members, in the same order).
+ *
+ * A package that publishes no `./backend` subpath is an admin- or
+ * storefront-only module: it registers nothing and serves nothing, so it is
+ * *readable and empty* rather than unreadable, exactly as
+ * `package-declarations.ts` classifies the same state. A package that publishes
+ * one whose target the walk cannot open is **named**, because an unread package
+ * is a package whose registrations are in no owner map and every decoration of
+ * one of its names would read `unowned-subject` — a finding about the run
+ * dressed as a finding about the tree.
+ */
+export declare function instanceComposition(input: {
+    readonly packages: readonly ModulePackage[];
+    /** The installed platform, or `null` when it does not resolve. */
+    readonly platform: {
+        readonly dir: string;
+        readonly exports: ReadonlyMap<string, string>;
+    } | null;
+}): InstanceCompositionScan;
+/**
+ * The scan's environment, with the **deployment's own** overlay registrations
+ * merged into the owner map (`specs/124-instance-customisation-gap/` FR-005,
+ * FR-006, FR-007).
+ *
+ * ## Why it is a second step rather than a fourth input to `instanceComposition`
+ *
+ * That function is documented as *"everything one run needs that does not change
+ * between deployments"*, and the overlay claim set is **per deployment** — a
+ * report is rendered once per directory under `apps/`. The package half is where
+ * the scan's cost is (one platform walk plus one per installed package, against
+ * one small overlay tree), so hoisting it and merging here is the shape that
+ * repairs the defect without making the expensive half run once per deployment.
+ *
+ * ## Why it is a conformance repair and not a widening
+ *
+ * `contracts/divergence-report.md` §3.2 specifies the owner map as *"module
+ * sources plus each installed package's `./backend` artefact"*, and this
+ * repository's own host already obeys it: `moduleWalkRoots` contains
+ * `overlayRoot`. The instance host was the one out of conformance — it built
+ * `owners` from installed packages and `rootSupplied` from the platform walk,
+ * and the client's own overlay tree was in neither. Measured by A8 of the
+ * instance acceptance criterion: one rendering listing
+ * `registration:<overlay>:<name>` and reporting `unowned-subject` for `<name>`,
+ * whose remedy sentence — *"Composition throws for it at boot"* — was untrue of
+ * a tree that had just booted.
+ *
+ * ## The claim is keyed from `OverlaySource.moduleId`, never from `moduleOf`
+ *
+ * FR-006, and it is not a preference: `moduleOf`'s overlay branch requires
+ * `/src/apps/` in the path and an instance's overlay root is
+ * `<root>/apps/<deployment>/modules/`, so a claim placed by path would attribute
+ * nothing at all here. `overlaySourcesUnder` already carries the id, from the
+ * directory the walk descended into.
+ *
+ * The precedence is `registration-owners.ts`': the deployment's own tree is the
+ * **tree** half and overwrites, an installed package claims only what nothing
+ * above claimed. That is the right way round — a name the client registers in
+ * their own overlay module is theirs — and it is the same rule this repository's
+ * host applies to its own `backend/src/apps/` sources.
+ */
+export declare function withOverlayRegistrationOwners(environment: DivergenceEnvironment, sources: readonly OverlaySource[]): DivergenceEnvironment;
+/** The refusal sentence, or `null` when every package this run needed was readable. */
+export declare function unreadableCompositionReason(scan: InstanceCompositionScan): string | null;
+/** The three fields a deployment declares (`deployment-declaration.md` §2). */
+export interface DeclarationLiterals {
+    readonly omittedModules: ReadonlyArray<{
+        readonly moduleId: string;
+        readonly reason: string;
+    }>;
+    readonly decorationOrder: Readonly<Record<string, readonly string[]>>;
+    readonly reasons: Readonly<Record<string, string>>;
+}
+/** The empty declaration — what a deployment that has declared nothing says. */
+export declare const EMPTY_DECLARATION: DeclarationLiterals;
+export interface DeclarationReading {
+    readonly declaration: DeclarationLiterals;
+    /**
+     * Fields the analysis could not resolve to literals, each named.
+     *
+     * Never merged into "declares nothing": an absent declaration and one this run
+     * could not read are the same answer only if you let them be, and that is the
+     * exact silence `divergence-loader.ts`' own header records as having hidden a
+     * broken root derivation from every deployment in the tree.
+     */
+    readonly unresolved: readonly string[];
+}
+/**
+ * A deployment's declaration, out of the file's **source text**.
+ *
+ * The running platform `import()`s this file; this run may not, and the reason
+ * is not a preference. `endora` runs as compiled JavaScript under plain `node`,
+ * and an instance's `apps/<deployment>/divergence.ts` is TypeScript — there is
+ * no loader in the process that could evaluate it, and adding one would make a
+ * scaffolding tool evaluate a client's code in order to describe it. Reading the
+ * text is also what the rest of this analysis does: the whole derivation is
+ * *"every subject is read as a literal"* (§3.3), and the declaration is held to
+ * the same rule as the tree it describes.
+ *
+ * What that costs is stated rather than discovered: a declaration whose fields
+ * are computed — spread from another module, built in a loop — resolves to
+ * nothing and is **named** in {@link DeclarationReading.unresolved}, never
+ * silently read as empty.
+ */
+export declare function readDivergenceDeclaration(source: string, file: string): DeclarationReading;
+//# sourceMappingURL=divergence-artefacts.d.ts.map

package/dist/lib/divergence-artefacts.d.ts.map

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