@r-machine/testing 1.0.0-alpha.11

package/lib/verify-resource-atlas.js

@@ -0,0 +1,345 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import nodePath from "node:path";
+import { pathToFileURL } from "node:url";
+import { CONFIG_ACCESSOR } from "r-machine";
+import { ResLayoutResolver, validateResModule, } from "r-machine/core";
+import { RMachineUsageError } from "r-machine/errors";
+import { ERR_VERIFY_SETUP_INVALID } from "#r-machine/testing/errors";
+// ─── Cross-package dev-loader flag ──────────────────────────────────────
+// Setting this symbol on `globalThis` signals tools like
+// `@r-machine/next/createNextDevImport` to force their dev importer (jiti)
+// active regardless of the usual `typeof window === "undefined"` gate.
+// Lets `verifyResourceAtlas` run in jsdom environments (vitest's default
+// for many web examples) without requiring the user to add the
+// `// @vitest-environment node` pragma.
+//
+// Contract: the symbol is `Symbol.for(...)` (registry symbol) so identity
+// is stable across realms and across packages without sharing code. Refer
+// to `@r-machine/next/dev/create-next-dev-import.ts` for the consumer.
+const FORCE_DEV_LOADER_FLAG = Symbol.for("@r-machine:force-dev-loader");
+function acquireForceDevLoaderFlag() {
+    const slot = globalThis;
+    slot[FORCE_DEV_LOADER_FLAG] = (slot[FORCE_DEV_LOADER_FLAG] ?? 0) + 1;
+}
+function releaseForceDevLoaderFlag() {
+    const slot = globalThis;
+    const next = (slot[FORCE_DEV_LOADER_FLAG] ?? 0) - 1;
+    if (next <= 0) {
+        delete slot[FORCE_DEV_LOADER_FLAG];
+    }
+    else {
+        slot[FORCE_DEV_LOADER_FLAG] = next;
+    }
+}
+// ─── Cross-package observation flags (read from @r-machine/next) ────────
+// `@r-machine/next`'s `createNextDevImport` writes these to signal whether
+// the dev importer (jiti) was attempted and whether it activated. We reset
+// them at the start of every verify call and inspect them at the end to
+// emit an actionable hint when a Next setup is detected but jiti didn't
+// start.
+const DEV_LOADER_ATTEMPTED_FLAG = Symbol.for("@r-machine:dev-loader-attempted");
+const DEV_LOADER_ENABLED_FLAG = Symbol.for("@r-machine:dev-loader-enabled");
+function clearDevLoaderObservationFlags() {
+    const slot = globalThis;
+    delete slot[DEV_LOADER_ATTEMPTED_FLAG];
+    delete slot[DEV_LOADER_ENABLED_FLAG];
+}
+function isDevLoaderAttempted() {
+    return globalThis[DEV_LOADER_ATTEMPTED_FLAG] === true;
+}
+function isDevLoaderEnabled() {
+    return globalThis[DEV_LOADER_ENABLED_FLAG] === true;
+}
+function hasLoaderRelatedIssue(issues) {
+    return issues.some((i) => i.kind === "loader-error" || i.kind === "missing-resource" || i.kind === "invalid-module-shape");
+}
+export async function verifyResourceAtlas(setupFile, options) {
+    const absoluteSetupFile = nodePath.resolve(setupFile);
+    const strategyExportName = options?.strategyExportName ?? "strategy";
+    // ─── Static phase: extract atlas keys via TS Compiler API ──────────────
+    let extractedKeys;
+    try {
+        extractedKeys = await extractAtlasKeys(absoluteSetupFile, options?.tsconfig);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            setupFile: absoluteSetupFile,
+            totalChecks: 0,
+            issues: [{ kind: "atlas-extraction-failed", reason: errorMessage(err) }],
+        };
+    }
+    // Reset observation flags so a previous verification in the same worker
+    // doesn't leak its "Next setup" signal into this one.
+    clearDevLoaderObservationFlags();
+    // Reference-counted: safe under concurrent `verifyResourceAtlas` calls in
+    // the same worker. Wraps both the runtime import of `setupFile` and the
+    // verification loop so any nested loader call also sees the flag.
+    acquireForceDevLoaderFlag();
+    try {
+        // ─── Runtime phase: import setup, reach the config via CONFIG_ACCESSOR ─
+        let config;
+        try {
+            const module = (await import(__rewriteRelativeImportExtension(pathToFileURL(absoluteSetupFile).href)));
+            const strategy = module[strategyExportName];
+            if (strategy === undefined || strategy === null) {
+                throw new RMachineUsageError(ERR_VERIFY_SETUP_INVALID, `Setup file does not export "${strategyExportName}".`);
+            }
+            const accessor = strategy[CONFIG_ACCESSOR];
+            if (typeof accessor !== "function") {
+                throw new RMachineUsageError(ERR_VERIFY_SETUP_INVALID, `Export "${strategyExportName}" does not expose CONFIG_ACCESSOR — make sure it is a r-machine Strategy or RMachine instance.`);
+            }
+            config = accessor.call(strategy);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                setupFile: absoluteSetupFile,
+                totalChecks: 0,
+                issues: [{ kind: "config-access-failed", reason: errorMessage(err) }],
+            };
+        }
+        // ─── Verification phase: enumerate keys × locales ────────────────────
+        const resolver = new ResLayoutResolver(config.layout);
+        const issues = [];
+        let totalChecks = 0;
+        for (const extracted of extractedKeys) {
+            const { key, sourceLocation } = extracted;
+            // Atlas keys may start with `#` to mark them as internal (consumer-hidden).
+            // The runtime sees only the bare form — `getNamespace` strips the marker
+            // when building kit/priority/bridgeGears. Mirror that here so resolver and
+            // loader receive the same namespace shape they would in production. The
+            // original `#`-prefixed key is preserved in issue reports.
+            const namespace = stripInternalMarker(key);
+            let kind;
+            try {
+                kind = resolver.resolveLayoutEntryType(namespace);
+            }
+            catch (err) {
+                // Key declared in atlas but no layout entry covers its prefix.
+                totalChecks++;
+                issues.push({
+                    kind: "loader-error",
+                    key,
+                    error: serializeError(err),
+                    sourceLocation,
+                });
+                continue;
+            }
+            if (kind === "shell") {
+                for (const locale of config.locales) {
+                    totalChecks++;
+                    await runCheck(key, namespace, locale, kind, config, resolver, sourceLocation, issues);
+                }
+            }
+            else if (kind === "shell(mono)") {
+                totalChecks++;
+                await runCheck(key, namespace, config.defaultLocale, kind, config, resolver, sourceLocation, issues);
+            }
+            else {
+                totalChecks++;
+                await runCheck(key, namespace, undefined, kind, config, resolver, sourceLocation, issues);
+            }
+        }
+        // If we hit any loader-related issue inside a Next setup that didn't
+        // activate jiti, surface the most likely root cause so the user is not
+        // left chasing per-resource errors.
+        if (hasLoaderRelatedIssue(issues) && isDevLoaderAttempted() && !isDevLoaderEnabled()) {
+            issues.push({
+                kind: "dev-loader-not-active",
+                reason: "The @r-machine/next dev importer was invoked but jiti did not activate — most likely jiti is not installed. " +
+                    "Install it as a dev dependency: `pnpm add -D jiti` (or the equivalent for your package manager).",
+            });
+        }
+        return {
+            ok: issues.length === 0,
+            setupFile: absoluteSetupFile,
+            totalChecks,
+            issues,
+        };
+    }
+    finally {
+        releaseForceDevLoaderFlag();
+    }
+}
+async function runCheck(key, namespace, locale, kind, config, resolver, sourceLocation, issues) {
+    const localePart = locale !== undefined ? { locale, isCanonical: locale === config.defaultLocale } : {};
+    const bareNamespace = namespace;
+    let modulePath;
+    let loaderOptions;
+    try {
+        modulePath = resolver.resolvePath(bareNamespace, locale, kind);
+        const namespaceParts = resolver.resolveNamespaceParts(bareNamespace);
+        const prefix = namespaceParts[0];
+        loaderOptions = {
+            namespace: bareNamespace,
+            namespaceParts,
+            pathParts: [prefix, modulePath.slice(prefix.length)],
+            locale,
+        };
+    }
+    catch (err) {
+        issues.push({
+            kind: "loader-error",
+            key,
+            ...localePart,
+            error: serializeError(err),
+            sourceLocation,
+        });
+        return;
+    }
+    let result;
+    try {
+        result = await config.load(modulePath, loaderOptions);
+    }
+    catch (err) {
+        issues.push({
+            kind: "loader-error",
+            key,
+            ...localePart,
+            error: serializeError(err),
+            sourceLocation,
+        });
+        return;
+    }
+    if (result === undefined || result === null) {
+        issues.push({
+            kind: "missing-resource",
+            key,
+            ...localePart,
+            sourceLocation,
+        });
+        return;
+    }
+    const validationError = validateResModule(result);
+    if (validationError) {
+        issues.push({
+            kind: "invalid-module-shape",
+            key,
+            ...localePart,
+            reason: validationError.message,
+            sourceLocation,
+        });
+    }
+}
+// ─── Static extraction via TS Compiler API ──────────────────────────────
+async function extractAtlasKeys(setupFile, tsconfigPath) {
+    const tsModule = await loadTypeScript();
+    const compilerOptions = readCompilerOptions(tsModule, setupFile, tsconfigPath);
+    const program = tsModule.createProgram([setupFile], compilerOptions);
+    const checker = program.getTypeChecker();
+    const sourceFile = program.getSourceFile(setupFile);
+    if (!sourceFile) {
+        throw new RMachineUsageError(ERR_VERIFY_SETUP_INVALID, `Could not load source file: ${setupFile}`);
+    }
+    const atlasClass = findResourceAtlasClass(tsModule, sourceFile, checker, new Set());
+    if (!atlasClass) {
+        throw new RMachineUsageError(ERR_VERIFY_SETUP_INVALID, `Could not locate a "ResourceAtlas" class reachable from ${setupFile}. The check follows the import graph starting from the setup file.`);
+    }
+    const classType = checker.getTypeAtLocation(atlasClass);
+    const shapeProp = checker.getPropertiesOfType(classType).find((s) => s.name === "shape");
+    if (!shapeProp) {
+        throw new RMachineUsageError(ERR_VERIFY_SETUP_INVALID, `The "ResourceAtlas" class has no "shape" property — is it built from defineLayout()?`);
+    }
+    const shapeType = checker.getTypeOfSymbolAtLocation(shapeProp, atlasClass);
+    const result = [];
+    for (const prop of checker.getPropertiesOfType(shapeType)) {
+        const decl = prop.declarations?.[0];
+        const sourceLocation = decl ? extractSourceLocation(decl) : { file: setupFile, line: 0, column: 0 };
+        result.push({ key: prop.name, sourceLocation });
+    }
+    return result;
+}
+function findResourceAtlasClass(tsModule, sourceFile, checker, visited) {
+    if (visited.has(sourceFile.fileName))
+        return undefined;
+    visited.add(sourceFile.fileName);
+    let local;
+    tsModule.forEachChild(sourceFile, (node) => {
+        if (tsModule.isClassDeclaration(node) && node.name?.text === "ResourceAtlas") {
+            local = node;
+        }
+    });
+    if (local)
+        return local;
+    for (const stmt of sourceFile.statements) {
+        if (!tsModule.isImportDeclaration(stmt))
+            continue;
+        const moduleSpec = stmt.moduleSpecifier;
+        if (!tsModule.isStringLiteral(moduleSpec))
+            continue;
+        const moduleSymbol = checker.getSymbolAtLocation(moduleSpec);
+        const imported = moduleSymbol?.declarations?.[0]?.getSourceFile();
+        if (!imported)
+            continue;
+        const found = findResourceAtlasClass(tsModule, imported, checker, visited);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+function readCompilerOptions(tsModule, setupFile, tsconfigPath) {
+    const configPath = tsconfigPath ?? tsModule.findConfigFile(nodePath.dirname(setupFile), tsModule.sys.fileExists, "tsconfig.json");
+    if (!configPath)
+        return {};
+    const configFile = tsModule.readConfigFile(configPath, tsModule.sys.readFile);
+    if (!configFile.config)
+        return {};
+    const parsed = tsModule.parseJsonConfigFileContent(configFile.config, tsModule.sys, nodePath.dirname(configPath));
+    return parsed.options;
+}
+function extractSourceLocation(node) {
+    const sourceFile = node.getSourceFile();
+    const pos = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    return {
+        file: sourceFile.fileName,
+        line: pos.line + 1,
+        column: pos.character + 1,
+    };
+}
+async function loadTypeScript() {
+    try {
+        return (await import("typescript")).default;
+    }
+    catch (err) {
+        throw new RMachineUsageError(ERR_VERIFY_SETUP_INVALID, `verifyResourceAtlas requires the "typescript" package as a peer dependency. Install it in your project.`, err instanceof Error ? err : undefined);
+    }
+}
+function stripInternalMarker(name) {
+    return name.charCodeAt(0) === 0x23 /* '#' */ ? name.slice(1) : name;
+}
+// ─── Error utilities ────────────────────────────────────────────────────
+function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+function serializeError(err) {
+    if (err instanceof Error) {
+        return {
+            name: err.name || "Error",
+            message: err.message,
+            ...(err.stack !== undefined ? { stack: err.stack } : {}),
+        };
+    }
+    return { name: "UnknownError", message: String(err) };
+}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@r-machine/testing",
+  "version": "1.0.0-alpha.11",
+  "description": "Testing utilities for R-Machine — one type-checked substitution primitive across gears, shells, and vertex-scoped state.",
+  "author": "Sergio Turolla <hello@codecarvings.com>",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "homepage": "https://rmachine.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codecarvings/r-machine.git"
+  },
+  "bugs": "https://github.com/codecarvings/r-machine/issues",
+  "keywords": [
+    "typescript",
+    "type-safe",
+    "typesafe",
+    "uniformity-under-change",
+    "refactor-safe",
+    "resource-layer",
+    "i18n",
+    "internationalization",
+    "dependency-injection",
+    "state-management",
+    "reactive",
+    "testable",
+    "ai-friendly",
+    "llm-friendly",
+    "react",
+    "nextjs",
+    "no-codegen",
+    "intellisense",
+    "shell",
+    "gear",
+    "plug"
+  ],
+  "sideEffects": false,
+  "files": [
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs",
+    "**/*.d.ts",
+    "**/*.d.mts",
+    "**/*.d.cts"
+  ],
+  "main": "./lib/index.cjs",
+  "types": "./lib/index.d.cts",
+  "module": "./lib/index.js",
+  "zshy": {
+    "exports": {
+      "./errors": "./src/errors/index.ts",
+      ".": "./src/lib/index.ts"
+    },
+    "conditions": {
+      "@r-machine/source": "src"
+    }
+  },
+  "exports": {
+    "./errors": {
+      "@r-machine/source": "./src/errors/index.ts",
+      "types": "./errors/index.d.cts",
+      "import": "./errors/index.js",
+      "require": "./errors/index.cjs"
+    },
+    ".": {
+      "@r-machine/source": "./src/lib/index.ts",
+      "types": "./lib/index.d.cts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.cjs"
+    }
+  },
+  "imports": {
+    "#r-machine/testing/errors": {
+      "@r-machine/source": "./src/errors/index.ts",
+      "types": "./errors/index.d.cts",
+      "default": "./errors/index.js"
+    },
+    "#r-machine/testing": {
+      "@r-machine/source": "./src/lib/index.ts",
+      "types": "./lib/index.d.cts",
+      "default": "./lib/index.js"
+    }
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0",
+    "r-machine": "1.0.0-alpha.11"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "clean": "git clean -xdf . -e node_modules",
+    "build": "zshy --project tsconfig.build.json",
+    "postbuild": "pnpm biome check --write .",
+    "test": "pnpm vitest run --typecheck",
+    "test:watch": "pnpm vitest watch --typecheck"
+  }
+}