@r-machine/testing 1.0.0-alpha.11

package/lib/verify-resource-atlas.cjs

@@ -0,0 +1,384 @@
+"use strict";
+/**
+ * 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 __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyResourceAtlas = verifyResourceAtlas;
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const r_machine_1 = require("r-machine");
+const core_1 = require("r-machine/core");
+const errors_1 = require("r-machine/errors");
+const errors_2 = require("#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");
+}
+async function verifyResourceAtlas(setupFile, options) {
+    const absoluteSetupFile = node_path_1.default.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 Promise.resolve(`${__rewriteRelativeImportExtension((0, node_url_1.pathToFileURL)(absoluteSetupFile).href)}`).then(s => __importStar(require(s))));
+            const strategy = module[strategyExportName];
+            if (strategy === undefined || strategy === null) {
+                throw new errors_1.RMachineUsageError(errors_2.ERR_VERIFY_SETUP_INVALID, `Setup file does not export "${strategyExportName}".`);
+            }
+            const accessor = strategy[r_machine_1.CONFIG_ACCESSOR];
+            if (typeof accessor !== "function") {
+                throw new errors_1.RMachineUsageError(errors_2.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 core_1.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 = (0, core_1.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 errors_1.RMachineUsageError(errors_2.ERR_VERIFY_SETUP_INVALID, `Could not load source file: ${setupFile}`);
+    }
+    const atlasClass = findResourceAtlasClass(tsModule, sourceFile, checker, new Set());
+    if (!atlasClass) {
+        throw new errors_1.RMachineUsageError(errors_2.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 errors_1.RMachineUsageError(errors_2.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(node_path_1.default.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, node_path_1.default.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 Promise.resolve().then(() => __importStar(require("typescript")))).default;
+    }
+    catch (err) {
+        throw new errors_1.RMachineUsageError(errors_2.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/lib/verify-resource-atlas.d.cts

@@ -0,0 +1,64 @@
+/**
+ * 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
+ */
+export type SourceLocation = {
+    file: string;
+    line: number;
+    column: number;
+};
+export type VerifyIssue = {
+    kind: "missing-resource";
+    key: string;
+    locale?: string;
+    isCanonical?: boolean;
+    sourceLocation?: SourceLocation;
+} | {
+    kind: "loader-error";
+    key: string;
+    locale?: string;
+    isCanonical?: boolean;
+    error: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    sourceLocation?: SourceLocation;
+} | {
+    kind: "invalid-module-shape";
+    key: string;
+    locale?: string;
+    isCanonical?: boolean;
+    reason: string;
+    sourceLocation?: SourceLocation;
+} | {
+    kind: "atlas-extraction-failed";
+    reason: string;
+} | {
+    kind: "config-access-failed";
+    reason: string;
+} | {
+    kind: "dev-loader-not-active";
+    reason: string;
+};
+export type VerifyReport = {
+    ok: boolean;
+    setupFile: string;
+    totalChecks: number;
+    issues: VerifyIssue[];
+};
+export type VerifyResourceAtlasOptions = {
+    /** Named export on the setup file that exposes the strategy. Default: "strategy". */
+    strategyExportName?: string;
+    /** Path to a tsconfig.json used for the static analysis pass. Defaults to the nearest one to setupFile. */
+    tsconfig?: string;
+};
+export declare function verifyResourceAtlas(setupFile: string, options?: VerifyResourceAtlasOptions): Promise<VerifyReport>;

package/lib/verify-resource-atlas.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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
+ */
+export type SourceLocation = {
+    file: string;
+    line: number;
+    column: number;
+};
+export type VerifyIssue = {
+    kind: "missing-resource";
+    key: string;
+    locale?: string;
+    isCanonical?: boolean;
+    sourceLocation?: SourceLocation;
+} | {
+    kind: "loader-error";
+    key: string;
+    locale?: string;
+    isCanonical?: boolean;
+    error: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    sourceLocation?: SourceLocation;
+} | {
+    kind: "invalid-module-shape";
+    key: string;
+    locale?: string;
+    isCanonical?: boolean;
+    reason: string;
+    sourceLocation?: SourceLocation;
+} | {
+    kind: "atlas-extraction-failed";
+    reason: string;
+} | {
+    kind: "config-access-failed";
+    reason: string;
+} | {
+    kind: "dev-loader-not-active";
+    reason: string;
+};
+export type VerifyReport = {
+    ok: boolean;
+    setupFile: string;
+    totalChecks: number;
+    issues: VerifyIssue[];
+};
+export type VerifyResourceAtlasOptions = {
+    /** Named export on the setup file that exposes the strategy. Default: "strategy". */
+    strategyExportName?: string;
+    /** Path to a tsconfig.json used for the static analysis pass. Defaults to the nearest one to setupFile. */
+    tsconfig?: string;
+};
+export declare function verifyResourceAtlas(setupFile: string, options?: VerifyResourceAtlasOptions): Promise<VerifyReport>;