stonyx 0.2.3-alpha.61 → 0.2.3-alpha.63

package/README.md

@@ -27,7 +27,19 @@ stonyx test     # Bootstrap + run tests
 stonyx help     # Show all available commands
 ```
 
-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.
+Stonyx reads `config/environment.ts` (preferred) or `config/environment.js`, initializes all `@stonyx/*` modules from your `devDependencies`, and runs your application.
+
+## Exports
+
+| Import path | What it exports |
+|-------------|-----------------|
+| `stonyx` | `Stonyx` class (default), `waitForModule(name)` |
+| `stonyx/config` | Live reference to the Stonyx config (default) |
+| `stonyx/log` | Live reference to the Chronicle logger (default) |
+| `stonyx/lifecycle` | `runStartupHooks(modules)`, `runShutdownHooks(modules)` |
+| `stonyx/test-helpers` | `setupIntegrationTests(hooks)` |
+
+`stonyx/config` and `stonyx/log` throw if read before Stonyx is initialized. See the [API Reference](docs/api.md) for details.
 
 ## Documentation
 

package/dist/cli/new.js

@@ -167,12 +167,8 @@ export function generatePackageJson(name, selectedModules, coreVersion = readCor
         tsx: '^4.21.0',
         typescript: '^5.8.3'
     };
-    // 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`.
+    // Modules are discovered from devDependencies (see docs/modules.md), and are
+    // requested on the core's own release line rather than at `latest`.
     for (const mod of selectedModules) {
         devDependencies[mod.package] = moduleTag;
     }

package/dist/modules.d.ts

@@ -2,29 +2,4 @@ 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,38 +8,6 @@ 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, because only the
-// current manifest can answer for the current boot — a name declared by an
-// earlier load must not answer for this one.
-//
-// It is NOT symmetric with `modulePromises`, and the asymmetry is worth
-// stating because the obvious reading of the line above is that it is.
-// `modulePromises` has no reset: no `delete`, no reassignment, no clear, at
-// any commit on `dev`. It accumulates the union of every `loadModules` call in
-// the process while this set is replaced per call. Measured over three loads
-// in one process at c87826b: load A declares and installs
-// `@stonyx/probe-life`; load B declares it with the package absent, so
-// discovery warns and `continue`s and registers nothing — and
-// `waitForModule('probe-life')` still RESOLVES, off load A's stale entry.
-// That is the "reports success for a module never loaded, silently" outcome
-// the registration loop below calls worse than the hang; T23 forecloses that
-// remedy WITHIN one call and no test sees across calls.
-//
-// Inherited, not introduced here — `modulePromises` was never reset at base
-// 5693744 either — and deliberately not closed here, because giving it a
-// per-call lifetime has a blast radius of its own and is filed separately.
-// Production reachability is nil: one `loadModules` call site, guarded by the
-// `Stonyx.instance` early return. The suite is held safe by the
-// unique-module-name-per-test rule in this file's test header, not by this.
-let declaredModuleNames = new Set();
 // Configure module-specific logging
 function configureLog(chronicle, module, config) {
     const { logColor, logMethod, logTimestamp } = config;
@@ -50,38 +18,8 @@ function configureLog(chronicle, module, config) {
 function initializeModule(moduleName, moduleClass, modules, initPromises) {
     const moduleInstance = new moduleClass();
     modules.push(moduleInstance);
-    // 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 pass / 1 fail at f575a3c
-    // with T24 the sole failure. The SHA is the point; see the aggregate
-    // convention noted at the `declaredDependencies` union below. 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, …)`,
-    // and `projectName` is never a key in `modulePromises`.
-    if (!moduleInstance.init) {
-        modulePromises[moduleName]?.resolve();
+    if (!moduleInstance.init)
         return;
-    }
     initPromises.push((async () => {
         await moduleInstance.init();
         modulePromises[moduleName]?.resolve();
@@ -140,55 +78,21 @@ export default async function loadModules(config, rootPath, chronicle) {
     const modules = [];
     const initPromises = [];
     const rootPackage = await readFile(`${rootPath}/package.json`, { json: true });
-    // DISCOVERY SOURCE (abofs/stonyx#106 rule 3).
-    //
-    // This local used to be named `dependencies` while holding `devDependencies`
-    // and nothing else. That name is the ruled root cause of #106: every reader
-    // of this function — including its own docs — believed discovery scanned
-    // both maps, because the identifier said so. It did not. An installed stonyx
-    // module declared in `dependencies` was invisible, which is precisely how the
-    // published fleet pins the core, so the loader could not see its own
-    // siblings.
-    //
-    // 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 — 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. 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 || {}),
-    };
+    const dependencies = (rootPackage.devDependencies || {});
     const projectName = typeof rootPackage.name === 'string' ? rootPackage.name : '';
     // Expose rootPath to public configuration
     config.rootPath = rootPath;
-    // The `@stonyx/` prefix filter STAYS (#106 keeps it explicitly). Widening it
-    // to `@` — or dropping it — makes the loader warn on every non-Stonyx
-    // dependency and leaves their `modulePromises` entries permanently
-    // 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);
+    const moduleDependencies = Object.keys(dependencies).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 dependency
+    // `@stonyx/*` is a NAME test, not a membership test: a scoped devDependency
     // 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
@@ -215,86 +119,6 @@ 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 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.
-    //
-    //   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
-    // 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 the hang-becomes-throw change and the named cause; the PR body names
-    // them. ("Halves" is avoided here because T13 uses that word for its own
-    // input-domain split — the `devDependencies` half it covers and the
-    // `dependencies` half it hands to T23.)
-    //
-    // 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 where its class HAS an `init()` its promise
-    // is resolved only once that `init()` has settled — the qualifier matters,
-    // because two of the three resolve sites named above settle without any
-    // `init()` running. 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
-    //     c87826b       HUNG, 3002 ms — re-measured at the head this ships from,
-    //                   because the rows above stop before three commits that
-    //                   touch this file and a reader at head cannot tell from a
-    //                   truncated table whether the row still applies
-    // 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
-    // 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
@@ -353,41 +177,10 @@ 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(declaredModuleNames.has(fullName)
-            ? `Could wait for module: ${fullName}. It IS declared in this project's dependencies or ` +
-                'devDependencies, 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;
+    if (!modulePromise)
+        throw new Error(`Could wait for module: ${fullName}. Module was not registered in project dependencies`);
+    await modulePromises[fullName].ready;
 }

package/dist/util/duplicate-core.js

@@ -265,8 +265,7 @@ 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 `dependencies` or
- * `devDependencies` (abofs/stonyx#106 rule 3: the loader scans the union),
+ * `moduleName` is narrower — it is a key from the app's own `devDependencies`,
  * 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
@@ -298,7 +297,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/*` dependency key is far short of it,
+ * the tight default; a scoped `@stonyx/*` devDependency key is far short of it,
  * so a real name is sanitised and never shortened either.
  */
 const PATH_LIMIT = 1024;
@@ -369,46 +368,10 @@ 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, 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 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 need declare. A copy no ' +
-            'module\'s ' +
-            'walk reaches first is not counted, and one further up a walk is hidden by a nearer one.',
+            '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.',
     ].join('\n');
 }

package/package.json

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