@endora-commerce/cli 0.100.0

package/dist/rules/singleton-identity.d.ts

@@ -0,0 +1,205 @@
+/** One module package, as the analysis needs it. */
+export interface ModulePackageSurface {
+    /** The module id of record — `endora.id`, never a path segment (D-142). */
+    readonly moduleId: string;
+    /** The npm name its published artefact is reached by. */
+    readonly npmName: string;
+    /** Its directory, as a key in the same namespace as {@link SingletonIdentityInput.sources}. */
+    readonly root: string;
+}
+/**
+ * Everything the analysis reads, and nothing it computes.
+ *
+ * Specifier resolution happens *inside* the analysis over this key set rather
+ * than through an injected resolver, so a red proof drives the resolution too
+ * (issue #130): a fixture that handed in pre-resolved targets would prove the
+ * predicates and leave the step that finds them unproven, which is where a
+ * `.js` → `.ts` rewrite or an `index.ts` directory target goes wrong.
+ */
+export interface SingletonIdentityInput {
+    /** Repo-relative key → source text, for every file the walk opened. */
+    readonly sources: ReadonlyMap<string, string>;
+    readonly packages: readonly ModulePackageSurface[];
+}
+export type SingletonIdentityFindingKind = 'composed-singleton-reach' | 'chain-parent-reach' | 'whole-file-reach' | 'stale-allowance';
+export interface SingletonIdentityFinding {
+    readonly kind: SingletonIdentityFindingKind;
+    /** The file holding the second copy, or the ledger key for a stale entry. */
+    readonly file: string;
+    readonly line: number;
+    /** The package whose source is reached. */
+    readonly moduleId: string;
+    /** The reached source file, in the same key namespace. */
+    readonly target: string;
+    /** The duplicated binding, where the finding names one. */
+    readonly binding: string | null;
+    /** Why the platform holds the other copy — printed to the author. */
+    readonly why: string;
+}
+export interface SingletonIdentityResult {
+    readonly findings: readonly SingletonIdentityFinding[];
+    /** Reaches into a module package's source that the run examined. */
+    readonly sites: number;
+    /** Composed singletons derived from the packages' own sources. */
+    readonly singletons: number;
+    /** Module packages the derivation found at least one entity class for. */
+    readonly packagesWithEntities: readonly string[];
+    /**
+     * The tenant-chain parents this walk named, and which of them it resolved to
+     * a classified entity class — the `tenant-chains` reconciliation.
+     *
+     * Two authors answer it: the `@TransitivelyScoped` decorator on the *child*
+     * (which module owns the child is nobody's choice but the chain's) and the
+     * `@Entity()` class declaration of the *parent*, in another module and, since
+     * batch four, in another workspace member. A walk that stopped reading one of
+     * the two roots leaves a parent named and unresolved, which is #215 over this
+     * population.
+     */
+    readonly chainParentNames: readonly string[];
+    readonly resolvedChainParentNames: readonly string[];
+    /** `@TransitivelyScoped` sites whose parent argument is not a string literal. */
+    readonly unreadableChainParents: readonly string[];
+    /** Chain parents that live in a module package — the signal's actual subject. */
+    readonly chainParentSubjects: readonly ChainParentSubject[];
+}
+/**
+ * Which walked file a relative specifier written in `fromKey` names, or `null`.
+ *
+ * Only relative specifiers: a bare one is a package boundary and is conjunct 1's
+ * business, not conjunct 2's.
+ */
+export declare function resolveRelative(fromKey: string, specifier: string, keys: ReadonlySet<string>): string | null;
+type ExportKind = 'value' | 'class' | 'entity' | 'function';
+/**
+ * What each name a file exports *is*, at module scope.
+ *
+ * The distinction that matters is `value` (one object, created when the module
+ * evaluates) against `function` / `class` (code, re-created identically by a
+ * second evaluation and only identity-bearing where somebody compares it —
+ * which is `identity-comparison`'s job). `entity` is a class the ORM keys its
+ * metadata on, so a second one is a lookup miss.
+ */
+export declare function exportedKinds(key: string, text: string): Map<string, ExportKind>;
+/** `<file>#<name>` — the identity of a binding, in one namespace. */
+export declare function bindingKey(file: string, name: string): string;
+/**
+ * Every binding the platform holds exactly one of, derived from the packages'
+ * own sources.
+ *
+ * Two derivations and no third, each naming the thing that holds the other copy:
+ * the **container** (`asValue` / `asFunction(() => x)` / `asClass`) and the
+ * **ORM** (a member of the `entities` array). Both are read as literal AST
+ * nodes, so a mention in a comment contributes nothing.
+ */
+export declare function composedSingletons(input: SingletonIdentityInput): Map<string, string>;
+/**
+ * Every class name a `@TransitivelyScoped` decorator names as a tenant parent,
+ * and the persisted children that name it.
+ *
+ * Read as literal AST nodes — a decorator on a class declaration, whose callee
+ * is that identifier and whose first argument is a string literal — so the files
+ * that merely *mention* the decorator in prose, in a contract's doc block or in
+ * a string fixture contribute nothing.
+ *
+ * **The child must also be `@Entity()`, and that conjunct is the population
+ * rather than a tidy-up.** Feature 050's classification is total over
+ * *persisted* entities, so a real chain's child is one; a `@TransitivelyScoped`
+ * on a plain class registers into the same in-process registry and never
+ * reaches ORM discovery. Measured on this tree, dropping the conjunct yields 31
+ * parent names of which 29 are the tenancy suite's own synthetic fixtures
+ * (`CycleA`, `DeepGlobalTerminus`, `AnEntityThisPlatformDoesNotHave`), each of
+ * which would put a name nothing declares into the reconciliation below. It is
+ * derived from the decorator rather than from a path exclusion on `test/` on
+ * purpose: a rule keyed on where a file sits stops being true the day a tree
+ * moves, which is what `moved-module-tree.test.ts` exists to refuse.
+ *
+ * `unreadable` is the other outcome and it is a refusal rather than a skip: a
+ * computed first argument (`@TransitivelyScoped(PARENT, 'fk')`) is a chain this
+ * walk cannot name, and a population quietly one shorter than it should be is
+ * the whole of issue #113.
+ */
+export interface TransitiveParentScan {
+    /** Parent class name → the child class names scoped through it. */
+    readonly parents: ReadonlyMap<string, readonly string[]>;
+    /** `<file>:<line>` for every decorator whose parent argument is not a literal. */
+    readonly unreadable: readonly string[];
+}
+export declare function transitiveParents(sources: ReadonlyMap<string, string>): TransitiveParentScan;
+/**
+ * Where each `@Entity()` class the walk read is declared, by class name.
+ *
+ * The independent half of the `tenant-chains` reconciliation: the decorator on
+ * the child names a parent, and this says whether the walk reached the file that
+ * declares it. Pre-filtered on the decorator's own text, so it parses the ~230
+ * files that hold an entity rather than all 3200.
+ */
+export declare function entityClassLocations(sources: ReadonlyMap<string, string>): Map<string, string[]>;
+/**
+ * A class whose duplication the platform **refuses** rather than tolerates.
+ *
+ * The intersection of two derivations, both off the artefacts: a class the ORM
+ * registered from a package's own `entities` array (conjunct 2, exactly as the
+ * named-binding signal asks it), and a class name some `@TransitivelyScoped`
+ * decorator names as a parent. `resolveTransitiveParent` keys the tenancy
+ * registry on the class **name** and refuses an ambiguous one rather than
+ * guessing (D-170), so a second registration of that name is
+ * `UnresolvableTenantParentError` at ORM init.
+ */
+export interface ChainParentSubject {
+    /** The file declaring the class — what a reach has to load to duplicate it. */
+    readonly file: string;
+    readonly className: string;
+    /** The package whose published artefact holds the first copy. */
+    readonly moduleId: string;
+    /** The `@TransitivelyScoped` children that name it, for the message. */
+    readonly children: readonly string[];
+}
+export declare function chainParentSubjects(input: SingletonIdentityInput, scan?: TransitiveParentScan, composed?: ReadonlyMap<string, string>): ChainParentSubject[];
+/** How a file reaches a chain parent: the hop count and the path it took. */
+export interface ChainParentHit {
+    readonly subject: ChainParentSubject;
+    /** Value-import hops from this file to the declaring one. 0 = it *is* it. */
+    readonly hops: number;
+    /** The shortest path, declaring file last. */
+    readonly via: readonly string[];
+}
+/**
+ * For every walked file, the chain parents its own value-import closure loads.
+ *
+ * A **reverse** breadth-first walk from each subject rather than a forward one
+ * per reach: the subjects are few and the reaches are many, so this is one BFS
+ * per duplicated class over the whole edge set instead of one per site, and it
+ * yields the *shortest* path for free — which is what the message prints, and
+ * what makes the depth question answerable rather than assumed.
+ *
+ * **No depth limit**, and the measurement rather than the taste is the reason:
+ * over this repository the real hits sit at 1 and 2 hops, and the walk to
+ * exhaustion costs 0.1 s of a 13 s run (feature 080, T061a). A cap would be a
+ * number written down that the next service extraction — one more file between
+ * the test and the entity — would silently step past, which is the failure mode
+ * this check's own header spends four paragraphs on.
+ */
+export declare function chainParentReaches(edges: ReadonlyMap<string, readonly string[]>, subjects: readonly ChainParentSubject[]): Map<string, ChainParentHit[]>;
+/** The whole analysis, pure over {@link SingletonIdentityInput}. */
+export declare function checkSingletonIdentity(input: SingletonIdentityInput, allowed: Readonly<Record<string, string>>): SingletonIdentityResult;
+/**
+ * Every TypeScript source under `dir`, with the rule's own directory prunes.
+ *
+ * Exported because the population is part of the rule: two hosts computing
+ * "which files this check reads" two ways is the shape that lets one of them go
+ * half-blind.
+ */
+export declare function collectSingletonSources(dir: string, out?: string[]): string[];
+/**
+ * Which module packages the committed ORM registry imports an `entities` array
+ * from — the independent derivation the walk is reconciled against (issue #244).
+ *
+ * It is a second author's answer to the same question: the registry is generated
+ * from a filesystem walk of the packages' `exports` maps and names each package
+ * by its bare specifier, while this check derives entities from each package's
+ * own source. A walk that stopped reading a package's sources makes the two
+ * disagree in the same run.
+ */
+export declare function packagesInEntitiesRegistry(source: string, npmNames: ReadonlySet<string>): string[];
+export {};
+//# sourceMappingURL=singleton-identity.d.ts.map

package/dist/rules/singleton-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton-identity.d.ts","sourceRoot":"","sources":["../../src/rules/singleton-identity.ts"],"names":[],"mappings":"AA2MA,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACpD;AAED,MAAM,MAAM,4BAA4B,GACpC,0BAA0B,GAC1B,oBAAoB,GACpB,kBAAkB,GAClB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACvD,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,wBAAwB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrD,iFAAiF;IACjF,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IACnD,iFAAiF;IACjF,QAAQ,CAAC,mBAAmB,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC7D;AAyCD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GACxB,MAAM,GAAG,IAAI,CAKf;AAED,KAAK,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;AAa5D;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAmBhF;AAgCD,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,sBAAsB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA0DrF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IACzD,kFAAkF;IAClF,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,oBAAoB,CAgC5F;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAYvB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,sBAAsB,EAC7B,IAAI,GAAE,oBAAuD,EAC7D,QAAQ,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAA6B,GAChE,kBAAkB,EAAE,CAYtB;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EAC7C,QAAQ,EAAE,SAAS,kBAAkB,EAAE,GACtC,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAiC/B;AAwKD,oEAAoE;AACpE,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACxC,uBAAuB,CAmIzB;AAID;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAuBjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAOlG"}