stonyx 0.2.3-alpha.59 → 0.2.3-alpha.60

package/dist/modules.d.ts

@@ -2,4 +2,29 @@ import type { StoynxModule } from './lifecycle.js';
 import type Chronicle from '@stonyx/logs';
 export type StoynxConfig = Record<string, Record<string, unknown> | unknown>;
 export default function loadModules(config: StoynxConfig, rootPath: string, chronicle: Chronicle): Promise<StoynxModule[]>;
+/**
+ * Blocks until `@stonyx/<moduleName>` has finished initializing.
+ *
+ * TWO failure sentences, because one sentence stopped being able to carry both
+ * facts. Until PR #120 fix round 1 `modulePromises` held every DECLARED
+ * `@stonyx/*` name, so "absent from the map" and "absent from the manifest"
+ * were the same fact and the single inherited sentence was true. Registration
+ * is now scoped to the DISCOVERED set — which is what removes the boot hang,
+ * see the registration loop in `loadModules` — so absence from the map has two
+ * causes, and the inherited sentence is FALSE for one of them: it tells the
+ * operator the package is not in their dependencies while it is sitting in
+ * their manifest.
+ *
+ * Not hypothetical, and not a shape this repo has to imagine: `@stonyx/logs`
+ * ships without the `stonyx-module` keyword and is an ordinary `dependencies`
+ * entry of THIS package.json. An app in the same shape calling
+ * `waitForModule('logs')` would be sent to grep a manifest that already
+ * contains the answer. Naming the wrong cause is the defect abofs/stonyx#108
+ * was filed over, and it is not made acceptable by being one line long.
+ *
+ * The declared branch does not say WHICH of the two causes applies, because
+ * this function does not know. Discovery does, and it already `console.warn`s
+ * the specific reason at load time, so the message points at that warning
+ * rather than guessing between them.
+ */
 export declare function waitForModule(moduleName: string): Promise<void>;

package/dist/modules.js

@@ -8,6 +8,19 @@ import { mergeObject } from '@stonyx/utils/object';
 import { importConfig, CONFIG_NOT_FOUND_PREFIX, CONFIG_NOT_LOADABLE_PREFIX } from './util/import-config.js';
 import { findForeignCores, duplicateCoreMessage } from './util/duplicate-core.js';
 const modulePromises = {};
+// The `@stonyx/*` names this app DECLARED — which since PR #120 fix round 1 is
+// a strictly WIDER set than the keys of `modulePromises`. Registration is now
+// scoped to what discovery admitted, so a declared name whose manifest is
+// missing, or whose manifest carries no `stonyx-module` keyword, is in this set
+// and not in that map. `waitForModule`'s failure branch is the only consumer,
+// and this is the only question it needs answered: "is this name in the
+// manifest?" is exactly what `modulePromises` stopped being able to answer.
+//
+// Reassigned per `loadModules` call rather than accumulated, so it tracks the
+// manifest of the most recent load exactly as `modulePromises` tracks that
+// load's discovery — one derived fact, one lifetime, rather than a second
+// singleton drifting away from the first.
+let declaredModuleNames = new Set();
 // Configure module-specific logging
 function configureLog(chronicle, module, config) {
     const { logColor, logMethod, logTimestamp } = config;
@@ -25,9 +38,22 @@ function initializeModule(moduleName, moduleClass, modules, initPromises) {
     // #120, and the one that scoping registration to `discovered` does NOT close,
     // because such a module IS discovered — measured, not reasoned: with only
     // the registration fix applied the suite read 180/1 with T24 the sole
-    // failure. Resolving here is truthful, because the module really did load,
-    // and that is what separates it from resolving on a discovery `continue`,
-    // where there is no module to be ready.
+    // failure. Resolving here is readiness BY DEFINITION — there is no `init()`,
+    // so there is nothing to wait for — and that is what separates it from
+    // resolving on a discovery `continue`, where there is no module to be ready
+    // at all.
+    //
+    // It is deliberately NOT the stronger claim that the module initialised.
+    // `waitForModule` is documented as blocking until a module "finishes
+    // initializing", and a `static async init()` typo — which TypeScript cannot
+    // catch, since `init?()` is optional in lifecycle.ts — presents to the loader
+    // as a class with no `init()`. This resolves it, and the waiter proceeds
+    // against a module whose own initialisation never ran; measured, the waiter
+    // observes the module's ready flag still false. The loader cannot tell that
+    // typo from a legitimate no-`init()` module, and a no-`init()` module is a
+    // supported shape, so resolving is the only non-hanging answer available and
+    // availability over a silent hang is the right trade. The claim is what is
+    // narrowed here, not the behaviour.
     //
     // `?.` for the reason the resolve below carries it: `initializeModule` is
     // also reached from the standalone path as `initializeModule(projectName, …)`,
@@ -114,9 +140,17 @@ export default async function loadModules(config, rootPath, chronicle) {
     // A bare `[ ...Object.keys(deps), ...Object.keys(devDeps) ]` concat instantiates
     // a dual-declared module twice and runs its `init()` twice. That WOULD be
     // invisible to the suite aggregate were T22 not armed; T22's instance-count
-    // assertion is what makes it visible. Measured at this head with the concat
-    // seeded: 178/1 with T22 the sole failure, both of its counts reading actual 2
-    // against expected 1.
+    // assertion is what makes it visible. With the concat seeded, T22 is the SOLE
+    // failure and both of its counts read actual 2 against expected 1 — measured
+    // 180 pass / 1 fail at f575a3c, out of a 181-test suite.
+    //
+    // The SHA is not decoration. This sentence replaced one that round 1 found
+    // false, and its replacement carried a figure measured at the PREVIOUS head
+    // under the words "at this head": 178/1, which cannot reconcile against a
+    // 181-test suite at all. Four reviewers caught it independently. A bare
+    // aggregate has no author and no date, so it rots silently on the next commit
+    // that adds a test; an aggregate with the SHA it was taken at stays true
+    // forever and tells the next reader exactly what to re-run.
     const declaredDependencies = {
         ...(rootPackage.dependencies || {}),
         ...(rootPackage.devDependencies || {}),
@@ -130,6 +164,7 @@ export default async function loadModules(config, rootPath, chronicle) {
     // unresolved. T3 owns that kill. What is a module is decided below, by the
     // `stonyx-module` keyword; this is only a name test that bounds the scan.
     const moduleDependencies = Object.keys(declaredDependencies).filter((moduleName) => moduleName.startsWith('@stonyx/'));
+    declaredModuleNames = new Set(moduleDependencies);
     // DISCOVERY, hoisted above the pre-flight.
     //
     // The pre-flight must check exactly what the loader loads, and no more.
@@ -168,8 +203,16 @@ export default async function loadModules(config, rootPath, chronicle) {
     // contains, and the widening turned a fast named throw into an unbounded
     // boot hang. A name registered here but never resolved leaves
     // `waitForModule` pending forever; discovery `continue`s past two kinds of
-    // name without reaching either of this file's two resolve sites — a manifest
+    // name without reaching ANY of this file's three resolve sites — a manifest
     // that is not there, and a package without the `stonyx-module` keyword.
+    // Three, not the two this sentence claimed when it was written: the
+    // no-`init()` early return in `initializeModule` is a resolve site and the
+    // commit that wrote this sentence is the commit that added it. The sites are
+    // named rather than numbered by line, because the comment above
+    // `initializeModule` reasons from this inventory and a stale count sends the
+    // next dangling-promise audit one site short — they are the no-`init()`
+    // early return, the `init()` wrapper, and the sync-module `continue` in the
+    // load loop.
     // `@stonyx/logs` ships without that keyword and is an ordinary `dependencies`
     // entry, so this is a shape the fleet actually has.
     //
@@ -177,10 +220,38 @@ export default async function loadModules(config, rootPath, chronicle) {
     //     base 5693744  throws "…was not registered in project dependencies", 3 ms
     //     a57045e       one console.warn, then loadModules never settles
     //
-    // Registering only what discovery admitted restores the fail-fast for both,
-    // and for `devDependencies`-declared names too — that half is INHERITED, not
-    // introduced here, and it is a real behaviour change: hang becomes throw.
-    // T13 pins it, and the PR body names it.
+    // Registering only what discovery admitted restores the fail-fast for both
+    // of those DISCOVERY FAILURES, and for `devDependencies`-declared names too
+    // — that half is INHERITED, not introduced here, and it is a real behaviour
+    // change: hang becomes throw — and the throw names the right cause, because
+    // `modulePromises` is no longer the app's declared list and `waitForModule`
+    // below branches on that difference rather than asserting the old one. T13
+    // pins both halves, and the PR body names them.
+    //
+    // SCOPED DELIBERATELY, because the sentence above would otherwise read as a
+    // closure statement for the whole never-settling-promise family and it is
+    // not one. What it closes is names that FAIL discovery. A name that PASSES
+    // discovery is registered, and its promise is resolved only once its own
+    // `init()` has settled — so two discovered modules whose `init()`s await
+    // each other through `waitForModule` are both registered, reach no resolve
+    // site, and leave `await Promise.all(initPromises)` at the end of this
+    // function pending forever. Measured on a cross-map mutual wait
+    // (`@stonyx/c1-a` in `dependencies`, `@stonyx/c1-b` in `devDependencies`,
+    // each `init()` awaiting the other), 3000 ms cap:
+    //     base 5693744  threw in 3 ms — the `dependencies` half was never
+    //                   discovered, so it failed fast for the wrong reason
+    //     a57045e       HUNG, 3001 ms
+    //     f575a3c       HUNG, 3003 ms — scoping registration does not touch it
+    // Rule 3 moves that shape from fail-fast to deadlock and nothing in this
+    // file closes it.
+    //
+    // NO DETECTION IS ATTEMPTED, and that is a decision rather than an
+    // oversight. `waitForModule` is told which module is being waited FOR and
+    // never which module is waiting, so a cycle is not observable without
+    // caller attribution that does not exist here, and this framework sets no
+    // boot timeout to hang a fallback off. A wait cycle is an authoring error in
+    // the modules; docs/modules.md's `waitForModule` section records the hazard
+    // so it is documented rather than merely known.
     //
     // The alternative — resolving in each `continue` branch — also removes the
     // hang and is worse: `waitForModule` would report success for a module that
@@ -253,10 +324,40 @@ export default async function loadModules(config, rootPath, chronicle) {
     await Promise.all(initPromises);
     return modules;
 }
+/**
+ * Blocks until `@stonyx/<moduleName>` has finished initializing.
+ *
+ * TWO failure sentences, because one sentence stopped being able to carry both
+ * facts. Until PR #120 fix round 1 `modulePromises` held every DECLARED
+ * `@stonyx/*` name, so "absent from the map" and "absent from the manifest"
+ * were the same fact and the single inherited sentence was true. Registration
+ * is now scoped to the DISCOVERED set — which is what removes the boot hang,
+ * see the registration loop in `loadModules` — so absence from the map has two
+ * causes, and the inherited sentence is FALSE for one of them: it tells the
+ * operator the package is not in their dependencies while it is sitting in
+ * their manifest.
+ *
+ * Not hypothetical, and not a shape this repo has to imagine: `@stonyx/logs`
+ * ships without the `stonyx-module` keyword and is an ordinary `dependencies`
+ * entry of THIS package.json. An app in the same shape calling
+ * `waitForModule('logs')` would be sent to grep a manifest that already
+ * contains the answer. Naming the wrong cause is the defect abofs/stonyx#108
+ * was filed over, and it is not made acceptable by being one line long.
+ *
+ * The declared branch does not say WHICH of the two causes applies, because
+ * this function does not know. Discovery does, and it already `console.warn`s
+ * the specific reason at load time, so the message points at that warning
+ * rather than guessing between them.
+ */
 export async function waitForModule(moduleName) {
     const fullName = `@stonyx/${moduleName}`;
     const modulePromise = modulePromises[fullName];
-    if (!modulePromise)
-        throw new Error(`Could wait for module: ${fullName}. Module was not registered in project dependencies`);
-    await modulePromises[fullName].ready;
+    if (!modulePromise) {
+        throw new Error(declaredModuleNames.has(fullName)
+            ? `Could wait for module: ${fullName}. It IS declared in this project's dependencies, but the ` +
+                'loader did not load it: either it is not installed under node_modules, or its package.json ' +
+                'does not carry the "stonyx-module" keyword. loadModules warned which one at load time.'
+            : `Could wait for module: ${fullName}. Module was not registered in project dependencies`);
+    }
+    await modulePromise.ready;
 }

package/dist/util/duplicate-core.js

@@ -374,16 +374,40 @@ export function duplicateCoreMessage(foreign) {
         // de-duplicated union of `dependencies` and `devDependencies`, and until
         // PR #120 fix round 1 this sentence still said `devDependencies` only —
         // so a refusal could name `seen by "@stonyx/x"` for a package declared
-        // ONLY in `dependencies` and then, seven lines later, tell the operator
+        // ONLY in `dependencies` and then, a few lines later, tell the operator
         // that such a declaration is not counted. Reproduced verbatim before the
         // fix. That sends them to search `devDependencies`, where there is nothing.
         // If the scan source ever changes again, this string changes with it;
         // `duplicate-core-test.ts` D4 asserts the claim, not just the header.
+        //
+        // FIX ROUND 2 corrects the closing sentence for the same reason. It used to
+        // exclude "a copy dragged in by ... a package without the keyword", which
+        // is false for the commonest shape there is: `npm install -g stonyx` plus
+        // `stonyx new` writes `stonyx` into the app's own `dependencies`
+        // (`src/cli/new.ts`), `stonyx/package.json` carries no `keywords` field at
+        // all, and every discovered module's ESM walk reaches
+        // `<app>/node_modules/stonyx` — so that copy is counted and PRINTED in the
+        // `seen by` row this sentence sits under. It is the exact case the
+        // duplicate-INSTALL remedy branch above was written for. The sentence now
+        // names what is ENUMERATED — the resolution walk — instead of closing a set
+        // of packages, because the enumeration is a property the code has and the
+        // set is not. D20 pins it against a fixture that counts such a copy.
+        //
+        // "FIRST copy that walk finds" is not padding, and it is the round-2
+        // rewrite's own near-miss: `coreSeenBy` returns on the first `asCore` hit,
+        // so a second copy further up the same walk is SHADOWED and never counted.
+        // Written as "a copy owned by any package on that walk is counted" this
+        // sentence would have been false in the same shape as the one it replaces —
+        // over-closing in the other direction. The shadowing case is stated because
+        // it is the reason the fail-open note below matters.
         'Scope of this check: it compares physical package ROOTS only. It does not check that the ' +
-            'single surviving copy is a compatible version, and it looks at @stonyx/* packages declared in ' +
-            'this app\'s dependencies or devDependencies that carry the "stonyx-module" keyword — nothing ' +
-            'else. Either placement counts: the loader scans the de-duplicated union of both maps. A copy ' +
-            'dragged in by anything outside that set — a transitive dependency, a package without the ' +
-            'keyword, or one not declared in this app\'s manifest at all — is not counted.',
+            'single surviving copy is a compatible version, and the modules it starts from are the ' +
+            '@stonyx/* packages declared in this app\'s dependencies or devDependencies that carry the ' +
+            '"stonyx-module" keyword — nothing else. Either placement counts: the loader scans the ' +
+            'de-duplicated union of both maps. What it then reports is not those packages\' own copies but ' +
+            'the copy each of them would IMPORT: for every one it follows Node\'s ESM resolution walk up ' +
+            'from that module\'s own directory and takes the FIRST copy that walk finds, whoever owns it — ' +
+            'including this app\'s own node_modules/stonyx, which no module declares. A copy no module\'s ' +
+            'walk reaches first is not counted, and one further up a walk is hidden by a nearer one.',
     ].join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonyx",
-  "version": "0.2.3-alpha.59",
+  "version": "0.2.3-alpha.60",
   "description": "Base stonyx framework module",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",