stonyx 0.2.3-alpha.57 → 0.2.3-alpha.59

package/README.md

@@ -27,7 +27,7 @@ stonyx test     # Bootstrap + run tests
 stonyx help     # Show all available commands
 ```
 
-Stonyx reads `config/environment.ts` (preferred) or `config/environment.js`, initializes all `@stonyx/*` modules declared in your `dependencies` or `devDependencies`, and runs your application.
+Stonyx reads `config/environment.ts` (preferred) or `config/environment.js`, loads the `@stonyx/*` modules declared in your `dependencies` or `devDependencies` (initializing the async ones), and runs your application.
 
 ## Documentation
 

package/dist/cli/new.js

@@ -167,8 +167,12 @@ export function generatePackageJson(name, selectedModules, coreVersion = readCor
         tsx: '^4.21.0',
         typescript: '^5.8.3'
     };
-    // Modules are discovered from devDependencies (see docs/modules.md), and are
-    // requested on the core's own release line rather than at `latest`.
+    // The scaffolder writes modules to `devDependencies` because that remains
+    // the conventional placement for an application — NOT because it is the only
+    // one discovery sees. Since abofs/stonyx#106 rule 3 the loader scans the
+    // de-duplicated union of `dependencies` and `devDependencies`, so either
+    // placement is discovered (see docs/modules.md). Requested on the core's own
+    // release line rather than at `latest`.
     for (const mod of selectedModules) {
         devDependencies[mod.package] = moduleTag;
     }

package/dist/modules.js

@@ -18,8 +18,24 @@ function configureLog(chronicle, module, config) {
 function initializeModule(moduleName, moduleClass, modules, initPromises) {
     const moduleInstance = new moduleClass();
     modules.push(moduleInstance);
-    if (!moduleInstance.init)
+    // A module class with no `init()` has nothing to initialise, so it is ready
+    // the moment it is instantiated. Without this its registered promise dangles
+    // — the only resolve on this path lives inside the `init()` wrapper below,
+    // which is never created. Third of the three never-resolved paths named in
+    // #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.
+    //
+    // `?.` for the reason the resolve below carries it: `initializeModule` is
+    // also reached from the standalone path as `initializeModule(projectName, …)`,
+    // and `projectName` is never a key in `modulePromises`.
+    if (!moduleInstance.init) {
+        modulePromises[moduleName]?.resolve();
         return;
+    }
     initPromises.push((async () => {
         await moduleInstance.init();
         modulePromises[moduleName]?.resolve();
@@ -90,10 +106,17 @@ export default async function loadModules(config, rootPath, chronicle) {
     //
     // Rule 3 widens the source to the DE-DUPLICATED union of both maps. Object
     // spread IS the de-duplication and is load-bearing: a module declared in both
-    // maps collapses to one key, so it is registered once and instantiated once.
-    // A bare `[ ...Object.keys(deps), ...Object.keys(devDeps) ]` concat produces a
-    // byte-identical suite aggregate while instantiating such a module twice and
-    // running its `init()` twice — T22's instance-count assertion owns that kill.
+    // maps collapses to one key, so it is registered once and — for an async
+    // module — instantiated once. (A SYNC module is discovered once and
+    // instantiated zero times; the loader never imports its entry point. Measured
+    // on a dual-declared sync fixture: `modules.length === 0`.)
+    //
+    // 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.
     const declaredDependencies = {
         ...(rootPackage.dependencies || {}),
         ...(rootPackage.devDependencies || {}),
@@ -107,16 +130,10 @@ 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/'));
-    // Setup module promises prior to initialization
-    for (const moduleName of moduleDependencies) {
-        const promise = {};
-        modulePromises[moduleName] = promise;
-        promise.ready = new Promise(resolve => promise.resolve = resolve);
-    }
     // DISCOVERY, hoisted above the pre-flight.
     //
     // The pre-flight must check exactly what the loader loads, and no more.
-    // `@stonyx/*` is a NAME test, not a membership test: a scoped devDependency
+    // `@stonyx/*` is a NAME test, not a membership test: a scoped dependency
     // without the `stonyx-module` keyword is warned about and skipped below —
     // never imported, never configured, incapable of registering anything on any
     // singleton — and refusing to boot over its nested copy prescribed the MODULE
@@ -143,6 +160,41 @@ export default async function loadModules(config, rootPath, chronicle) {
             keywords,
         });
     }
+    // Setup module promises prior to initialization — over `discovered`, NOT
+    // over `moduleDependencies`.
+    //
+    // This loop used to run above discovery and consume the declared list. That
+    // was already the shape at base, but rule 3 widened what the declared list
+    // 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
+    // that is not there, and a package without the `stonyx-module` keyword.
+    // `@stonyx/logs` ships without that keyword and is an ordinary `dependencies`
+    // entry, so this is a shape the fleet actually has.
+    //
+    //   name in `dependencies`, not installed, another module awaits it
+    //     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.
+    //
+    // The alternative — resolving in each `continue` branch — also removes the
+    // hang and is worse: `waitForModule` would report success for a module that
+    // was never loaded, silently. T23 asserts the named rejection precisely so
+    // that remedy cannot pass.
+    //
+    // Ordering is safe: nothing between here and the old site touches
+    // `modulePromises`, discovery only reads manifests, and registration still
+    // completes before the first `init()` can run.
+    for (const { name: moduleName } of discovered) {
+        const promise = {};
+        modulePromises[moduleName] = promise;
+        promise.ready = new Promise(resolve => promise.resolve = resolve);
+    }
     // Pre-flight: invariant I1, "one core". Before ANY module entry point is
     // imported, because the point of the check is the module that would NOT
     // throw — it would load, initialise, and register its hooks on a second

package/dist/util/duplicate-core.js

@@ -265,7 +265,8 @@ export function findForeignCores(modules, core = undefined, report = IGNORE) {
  * NOTHING OFF DISK IS TRUSTED FOR DISPLAY — all three interpolated fields.
  *
  * `version` and the package root come from a manifest this app did not write.
- * `moduleName` is narrower — it is a key from the app's own `devDependencies`,
+ * `moduleName` is narrower — it is a key from the app's own `dependencies` or
+ * `devDependencies` (abofs/stonyx#106 rule 3: the loader scans the union),
  * so forging it is an app author forging their own diagnostic — but it is
  * rendered through the same `padEnd` table, and it caused the same two
  * symptoms: seeded with ANSI escapes and embedded newlines it FORGED A
@@ -297,7 +298,7 @@ export function findForeignCores(modules, core = undefined, report = IGNORE) {
  * nothing but its own wrap. The module name and the version are both inside
  * PADDED columns whose widths are the max over every row, so one long value
  * there pushes every other row's remaining columns off screen. Those two take
- * the tight default; a scoped `@stonyx/*` devDependency key is far short of it,
+ * the tight default; a scoped `@stonyx/*` dependency key is far short of it,
  * so a real name is sanitised and never shortened either.
  */
 const PATH_LIMIT = 1024;
@@ -368,10 +369,21 @@ export function duplicateCoreMessage(foreign) {
             'peerDependencies range, never as an exact dependency — @stonyx/discord is the reference shape. ' +
             consumerRemedy,
         '',
+        // THIS PARAGRAPH IS A CLAIM ABOUT WHAT THE LOADER SCANS, printed at the
+        // moment boot is refused. abofs/stonyx#106 rule 3 widened that scan to the
+        // 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
+        // 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.
         '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 devDependencies that carry the "stonyx-module" keyword — nothing else. A copy ' +
-            'dragged in by anything outside that set, including an @stonyx/* package declared in ' +
-            'dependencies rather than devDependencies, is not counted.',
+            '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.',
     ].join('\n');
 }

package/package.json

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