@endora-commerce/cli 0.100.0

package/dist/generate/divergence.js

@@ -0,0 +1,237 @@
+/**
+ * The divergence report, rendered for a client's instance
+ * (`specs/107-override-report-and-ladder/contracts/divergence-report.md`;
+ * `specs/110-instance-repository/contracts/instance-tree.md` §2.2, §2.6).
+ *
+ * ## Why an instance renders one at all
+ *
+ * `endora new instance` writes `apps/<deployment>/divergence.ts` and
+ * `apps/<deployment>/modules/.gitkeep`, so the tree a client customises in
+ * exists from the first minute — and until T138a nothing could describe it. The
+ * renderer was `backend/scripts/generate-divergence.ts`, over this repository's
+ * module layout, its platform sources and a port→owner map built from module
+ * **sources**, none of which an instance has. D-30 asks that *"every override is
+ * visible in a generated artefact"*, and for every tree but this one that was
+ * a sentence with no implementation behind it.
+ *
+ * ## The population is the parameter; the derivation is one program (R3.5)
+ *
+ * Nine kinds, each from one seam of `ModuleContext`, over the deployment's own
+ * overlay tree. **That population is identical in the two hosts** — an overlay
+ * module is a client's own source in either tree — so every kind an instance
+ * records is the kind this repository records, derived by the same
+ * `deriveDivergence`.
+ *
+ * ## What is genuinely narrower, and where the artefact says so
+ *
+ * Attribution, in one place. This repository's owner map has three sources —
+ * module sources, a composition root's bridging table, and installed packages —
+ * and an instance has the third alone: every module is an installed package and
+ * `composeApp` is the platform's, so a name the platform registers on a module's
+ * behalf is reported as a composition root's rather than as that module's. That
+ * is true of the instance and is simply less specific than ours, and it is
+ * written into the report's own `boundary.notRecorded`
+ * (`lib/divergence-artefacts.ts`' `INSTANCE_BOUNDARY_NOTES`) rather than left for
+ * a client to discover by reading a report with a silent hole in it.
+ *
+ * Two differences in the artefact **set** rather than in what a report records,
+ * both of them deliberate:
+ *
+ *  - **markdown and JSON, never a typed TS module.** The `.ts` rendering's two
+ *    readers here are a program and `overlay:check`'s byte-comparison; an
+ *    instance has no check estate (`instance-tree.md` §2.5) and the emitted
+ *    module imports `DivergenceReport` by a **relative** path, which
+ *    `backend/src/overlay/types.ts` carries and an instance has no equivalent
+ *    of. A bare specifier there would be the one generated artefact whose import
+ *    depends on the client's dependency graph, which is the state that file's own
+ *    header exists to refuse. JSON is the machine shape with no import at all.
+ *  - **no bare-core rendering.** This repository renders one because `DEPLOYMENT`
+ *    is legitimately unset here; an instance is scaffolded with exactly one
+ *    deployment and every build composes it, so a bare-core report would describe
+ *    a build the client never makes.
+ *
+ * ## It is committed, unlike the other three artefacts this command writes
+ *
+ * §1 of the report contract is the predicate: *an artefact is committed when its
+ * content is a fact about the tree, and resolved at runtime when it is a fact
+ * about the process*. A deployment's overlay modules and what they decorate are
+ * facts about the client's own tree, visible in the merge request that creates
+ * them — which is the whole reason the report is worth having. So this pair is
+ * not `.gitignore`d and the header does not tell a reader not to commit it.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { instanceComposition, INSTANCE_BOUNDARY_NOTES, overlaySourcesUnder, overlayTreeSpellsASeamCall, readDivergenceDeclaration, renderDivergenceArtefacts, unreadableCompositionReason, withOverlayRegistrationOwners, EMPTY_DECLARATION, } from '../lib/divergence-artefacts.js';
+import { divergenceRefusal, selfContradictingSubjects } from '../lib/divergence.js';
+import { scanInstalledPlatformPackage, } from '../lib/module-packages.js';
+/** Raised when this half has an input it could not read — the caller's exit 2. */
+export class DivergenceHostError extends Error {
+    name = 'DivergenceHostError';
+}
+/** The "do not edit" header an instance's rendered report carries. */
+export const INSTANCE_DIVERGENCE_MARKDOWN_HEADER = [
+    '<!-- AUTO-GENERATED by `endora generate` — DO NOT EDIT. -->',
+    '<!-- It is derived from this deployment’s own `modules/` tree and its `divergence.ts`, -->',
+    '<!-- so it is a fact about your repository: commit it, and read the diff. -->',
+];
+/** Sorted directory names directly under a root; `[]` when there is none. */
+function directoriesUnder(root) {
+    if (!existsSync(root))
+        return [];
+    try {
+        return readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Every deployment in an instance — one directory under `<root>/apps/`. */
+export function instanceDeployments(root) {
+    return directoriesUnder(join(root, 'apps'));
+}
+/**
+ * The deployment's declaration file on disk, or `null`.
+ *
+ * `.ts` before `.js`, which is the opposite of the platform's own resolution
+ * order and is right for this reader: the platform resolves what it is about to
+ * **execute**, where a stray source beside a build is the wrong answer, and this
+ * reads what the client **wrote**.
+ */
+function declarationPathFor(root, deployment) {
+    for (const extension of ['ts', 'mts', 'cts', 'js', 'mjs', 'cjs']) {
+        const candidate = join(root, 'apps', deployment, `divergence.${extension}`);
+        try {
+            if (statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Render one report per deployment this instance holds.
+ *
+ * A tree with no `apps/` directory at all is the empty list rather than a
+ * refusal: an instance scaffolded and not yet customised is a supported state,
+ * and the caller names it as an omission the way it names an absent admin
+ * member.
+ */
+export function renderInstanceDivergence(input) {
+    const deployments = instanceDeployments(input.root);
+    if (deployments.length === 0)
+        return [];
+    const platform = scanInstalledPlatformPackage(input.root);
+    if (platform === null) {
+        throw new DivergenceHostError(`no installed package in ${join(input.root, 'node_modules')} declares ` +
+            '`endora.type: "platform"`, so the composition this deployment diverges *from* cannot ' +
+            'be read: no container name has an owner, no endpoint has a route, and ' +
+            "`ModuleContext`'s own members — the list every seam is classified against — are " +
+            'unknown. A report derived from that would record every decoration as owned by nobody ' +
+            'and classify no seam at all. Run `pnpm install` first.');
+    }
+    const scan = instanceComposition({ packages: input.packages, platform });
+    const unreadable = unreadableCompositionReason(scan);
+    if (unreadable !== null)
+        throw new DivergenceHostError(unreadable);
+    if (scan.environment.seams.length === 0) {
+        throw new DivergenceHostError(`${platform.name} publishes no file declaring the \`ModuleContext\` interface beside its ` +
+            '`./kernel` entry point, so there is nothing to classify this deployment’s seams ' +
+            'against. Every seam would be recorded with no rung and the `unclassified-seam` ' +
+            'finding could never fire, which is a finding about this run dressed as a clean tree.');
+    }
+    // Every committed report on disk, read from the directories rather than from
+    // the deployments the walk found: refusal 1's whole subject is the state in
+    // which those two disagree. In an instance it cannot fire — a client's report
+    // lives at `apps/<d>/divergence.generated.md`, inside the directory
+    // `instanceDeployments` counts, so an artefact implies its deployment — and
+    // the input is supplied truthfully anyway rather than stubbed, because a
+    // layout change is exactly the thing that would make a stub wrong in silence.
+    const committedDeploymentArtefacts = deployments.filter((deployment) => existsSync(join(input.root, 'apps', deployment, 'divergence.generated.md')));
+    return deployments.map((deployment) => {
+        const overlayRoot = join(input.root, 'apps', deployment, 'modules');
+        const overlayModules = directoriesUnder(overlayRoot);
+        const sources = overlaySourcesUnder(overlayRoot, overlayModules, input.root);
+        // FR-005/FR-006/FR-007 — the deployment's own registrations, merged per
+        // deployment because the overlay set is per deployment while the scan is not.
+        const environment = withOverlayRegistrationOwners(scan.environment, sources);
+        const declarationPath = declarationPathFor(input.root, deployment);
+        const reading = declarationPath === null
+            ? { declaration: EMPTY_DECLARATION, unresolved: [] }
+            : readDivergenceDeclaration(readFileSync(declarationPath, 'utf8'), declarationPath);
+        const base = join(input.root, 'apps', deployment, 'divergence.generated');
+        const { result, renderings } = renderDivergenceArtefacts({
+            deployment,
+            overlayRoot: relative(input.root, overlayRoot).split(sep).join('/'),
+            overlayModules,
+            sources,
+            routes: environment.routes,
+            owners: environment.owners,
+            rootSupplied: environment.rootSupplied,
+            declaration: reading.declaration,
+            seams: environment.seams,
+            hostNotRecorded: INSTANCE_BOUNDARY_NOTES,
+            // The file this run really read, relative to the client's own root. A
+            // finding's job is to send somebody to a file, and the default is this
+            // repository's `backend/src/apps/<d>/divergence.ts`, which no instance has.
+            declarationPath: declarationPath === null
+                ? join('apps', deployment, 'divergence.ts')
+                : relative(input.root, declarationPath).split(sep).join('/'),
+        }, [
+            {
+                rendering: 'markdown',
+                outputPath: `${base}.md`,
+                header: INSTANCE_DIVERGENCE_MARKDOWN_HEADER,
+                label: `the divergence report for \`${deployment}\``,
+            },
+            {
+                rendering: 'json',
+                outputPath: `${base}.json`,
+                label: `the divergence report for \`${deployment}\`, as data`,
+            },
+        ]);
+        // FR-008 — the refusals, evaluated here because `divergenceRefusal` lives in
+        // the shared library and had exactly one caller: `backend/scripts/check-divergence.ts`,
+        // which an instance does not have. Every input it needs is in hand, so an
+        // instance was the one host that could print a vacuous pass with nothing to
+        // stop it — the state refusal 3 exists for, reached by a client writing
+        // JavaScript. A refusal is an input this run could not read, which is
+        // `DivergenceHostError`'s class and the caller's exit 2, never exit 1.
+        const refusal = divergenceRefusal({
+            deployments,
+            committedDeploymentArtefacts,
+            sites: result.sites.length,
+            overlaySpellsASeamCall: overlayTreeSpellsASeamCall(sources),
+            ownersResolved: environment.owners.size,
+            // The platform's declared `ModuleContext` members. The rung table itself
+            // is a constant this package ships, so the input that can genuinely be
+            // zero in an instance is the member list — and a zero is already refused
+            // above, with a message naming the platform package. Passing the real
+            // number keeps the predicate answering over what this run read rather
+            // than over a stub that cannot go wrong.
+            seamsClassified: environment.seams.length,
+            selfContradictingSubjects: selfContradictingSubjects(result),
+        });
+        if (refusal !== null) {
+            throw new DivergenceHostError(`the divergence report for \`${deployment}\` was refused rather than rendered ` +
+                `[${refusal.kind}]: ${refusal.message}`);
+        }
+        return {
+            deployment,
+            renderings,
+            overlayModules,
+            entries: result.report.entries.length,
+            findings: result.findings.map((finding) => ({
+                kind: finding.kind,
+                where: finding.where,
+                detail: finding.detail,
+            })),
+            unresolvedDeclaration: reading.unresolved,
+        };
+    });
+}
+//# sourceMappingURL=divergence.js.map

package/dist/generate/divergence.js.map

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

package/dist/generate/index.d.ts

@@ -0,0 +1,90 @@
+import { type DocsCollection } from '../lib/docs-artefacts.js';
+import { type SkippedInstalledPackage } from '../lib/module-packages.js';
+import { type InstanceDivergence } from './divergence.js';
+/** A refusal the operator can act on — exit 1. */
+export declare class GenerateInputError extends Error {
+    readonly name = "GenerateInputError";
+}
+/** An input this run could not read — exit 2. */
+export declare class GenerateHostError extends Error {
+    readonly name = "GenerateHostError";
+}
+export interface GenerateOptions {
+    /** Where the run was invoked. The instance root is found upwards from here. */
+    readonly cwd?: string | undefined;
+    /** Report what would be written, and write nothing. */
+    readonly dryRun?: boolean | undefined;
+}
+/** One artefact this run rendered. */
+export interface GeneratedArtefact {
+    /** Absolute. */
+    readonly path: string;
+    readonly content: string;
+    /** What it is, for the line the command prints. */
+    readonly label: string;
+}
+export interface GenerateResult {
+    /** The workspace root this run rendered for. */
+    readonly root: string;
+    readonly artefacts: readonly GeneratedArtefact[];
+    /** How many installed module packages the population held. */
+    readonly modules: number;
+    /** R8.2 — every candidate the discovery excluded, with its reason. */
+    readonly excluded: readonly SkippedInstalledPackage[];
+    /**
+     * A member this instance does not have, and therefore an artefact family this
+     * run did not render — named rather than silently skipped.
+     *
+     * `instance-tree.md` §2.4's own reasoning: *"a client who does not know they
+     * have no operator interface spends their first hour looking for one"*. The
+     * same holds for a documentation site, and the member is legitimately absent
+     * — `endora new instance` omits either one when the packages it is mounted on
+     * do not resolve.
+     */
+    readonly omitted: readonly string[];
+    /** What the documentation copy step did, or `null` when there is no site. */
+    readonly collected: DocsCollection | null;
+    /**
+     * Reference pages this run removed because no installed module renders them
+     * any more — the category's half of {@link GenerateResult.collected}.
+     */
+    readonly swept: readonly string[];
+    /**
+     * One divergence report per deployment this instance holds
+     * (`specs/107-override-report-and-ladder/contracts/divergence-report.md`).
+     *
+     * **Unlike the other three families these are committed**, and the predicate
+     * that decides it is §1's: an artefact is committed when its content is a fact
+     * about the tree. Which packages a client installed is a fact about the
+     * install; what their own overlay modules decorate is a fact about their
+     * repository, and it is only worth having because it turns up in the merge
+     * request that creates it.
+     */
+    readonly divergence: readonly InstanceDivergence[];
+    readonly dryRun: boolean;
+}
+/**
+ * The instance root: the nearest directory above `from` holding a
+ * `pnpm-workspace.yaml`.
+ *
+ * Upwards, so the command works from the admin member as well as from the root
+ * — `pnpm -C admin run generate` runs it with the member as its working
+ * directory, and a client typing it in the directory they are editing is the
+ * ordinary case.
+ */
+export declare function findInstanceRoot(from: string): string | null;
+/**
+ * Render the instance's build artefacts, and write them unless this is a dry
+ * run.
+ *
+ * Every artefact is rendered **before** any is written, in `new instance`'s own
+ * discipline (R5.2): a half-written pair is a bundle that names modules the
+ * stylesheet did not scan, which is the silent failure
+ * `admin-stylesheet-composition.md` exists to remove.
+ */
+export declare function runGenerate(options?: GenerateOptions): Promise<GenerateResult>;
+/** The lines the command prints, in order. Exported so a proof reads them. */
+export declare function generateReport(result: GenerateResult): readonly string[];
+/** Is this instance's admin registry the same as the one on disk? */
+export declare function artefactIsCurrent(artefact: GeneratedArtefact): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/generate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generate/index.ts"],"names":[],"mappings":"AAqDA,OAAO,EAOL,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,iBAAiB,CAAC;AAEzB,kDAAkD;AAClD,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAkB,IAAI,wBAAwB;CAC/C;AAED,iDAAiD;AACjD,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,uBAAuB;CAC9C;AAED,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACvC;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,gBAAgB;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACtD;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ5D;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAsNxF;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,MAAM,EAAE,CA8DxE;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAGtE"}