yeoman-environment 6.3.0 → 7.1.0

package/dist/environment-base.d.ts

@@ -9,7 +9,7 @@ import { type FilePipelineTransform } from '@yeoman/transform';
 import { type YeomanNamespace } from '@yeoman/namespace';
 import { type ConflicterOptions } from '@yeoman/conflicter';
 import { ComposedStore } from './composed-store.ts';
-import Store from './store.ts';
+import Store, { type StoreGeneratorMeta } from './store.ts';
 import type YeomanCommand from './util/command.ts';
 import { type LookupOptions } from './generator-lookup.ts';
 import { type InstallTask } from './package-manager.ts';
@@ -27,6 +27,13 @@ export type EnvironmentOptions = ConflicterOptions & BaseEnvironmentOptions & Om
     arboristRegistry?: string;
     nodePackageManager?: string;
     generatorLookupOptions?: Pick<EnvironmentLookupOptions, 'customizeNamespace' | 'lookups'>;
+    /**
+     * Generators store to use instead of a new one, to share looked up and registered generators with other
+     * environments. Generators registered through this environment are added to it.
+     *
+     * @experimental
+     */
+    store?: Store;
 };
 /**
  * Copy and remove null and undefined values
@@ -62,6 +69,13 @@ export default class EnvironmentBase extends EventEmitter implements BaseEnviron
         feature: any;
     }>;
     applyTransforms(transformStreams: FilePipelineTransform[], options?: ApplyTransformsOptions): Promise<void>;
+    /**
+     * The meta of a generator of the store for this environment.
+     */
+    protected bindMeta<M extends StoreGeneratorMeta>(meta: M): M & GeneratorMeta;
+    protected bindMeta<M extends StoreGeneratorMeta>(meta: M | undefined): (M & GeneratorMeta) | undefined;
+    private getStoreMeta;
+    protected asEnvironment(): BaseEnvironment;
     /**
      * @param   namespaceOrPath
      * @return the generator meta registered under the namespace

package/dist/environment-base.js

@@ -1,8 +1,7 @@
 import EventEmitter from 'node:events';
 import { createRequire } from 'node:module';
-import { basename, isAbsolute, join, relative, resolve } from 'node:path';
+import { isAbsolute, join, relative, resolve } from 'node:path';
 import process from 'node:process';
-import { realpathSync } from 'node:fs';
 import { QueuedAdapter } from '@yeoman/adapter';
 import { create as createMemFs } from 'mem-fs';
 import {} from 'mem-fs-editor';
@@ -16,9 +15,9 @@ import chalk from 'chalk';
 import {} from '@yeoman/conflicter';
 import { defaults, pick } from 'lodash-es';
 import { ComposedStore } from "./composed-store.js";
-import Store from "./store.js";
+import Store, {} from "./store.js";
 import { asNamespace, defaultLookups } from "./util/namespace.js";
-import { lookupGenerators } from "./generator-lookup.js";
+import {} from "./generator-lookup.js";
 import { UNKNOWN_NAMESPACE, UNKNOWN_RESOLVED, defaultQueues } from "./constants.js";
 import { resolveModulePath } from "./util/resolve.js";
 import { commitSharedFsTask } from "./commit.js";
@@ -107,12 +106,12 @@ export default class EnvironmentBase extends EventEmitter {
     constructor(options = {}) {
         super();
         this.setMaxListeners(100);
-        const { cwd = process.cwd(), logCwd = cwd, sharedFs = createMemFs(), command, yeomanRepository, arboristRegistry, sharedOptions = {}, experimental, console: adapterConsole, stdin, stderr, stdout, adapter = new QueuedAdapter({ console: adapterConsole, stdin, stdout, stderr }), ...remainingOptions } = options;
+        const { cwd = process.cwd(), logCwd = cwd, sharedFs = createMemFs(), command, yeomanRepository, arboristRegistry, sharedOptions = {}, experimental, console: adapterConsole, stdin, stderr, stdout, adapter = new QueuedAdapter({ console: adapterConsole, stdin, stdout, stderr }), store, ...remainingOptions } = options;
         this.options = remainingOptions;
         this.adapter = adapter;
         this.cwd = resolve(cwd);
         this.logCwd = logCwd;
-        this.store = new Store(this);
+        this.store = store ?? new Store(this);
         this.command = command;
         this.runLoop = new GroupedQueue(defaultQueues, false);
         this.composedStore = new ComposedStore({ log: this.adapter.log });
@@ -155,6 +154,15 @@ export default class EnvironmentBase extends EventEmitter {
             ]);
         }, { name, disabled: !(options?.log ?? true) });
     }
+    bindMeta(meta) {
+        return this.store.bindMeta(meta, { env: this.asEnvironment() });
+    }
+    getStoreMeta(namespace) {
+        return this.store.getMeta(namespace, { env: this.asEnvironment() });
+    }
+    asEnvironment() {
+        return this;
+    }
     /**
      * @param   namespaceOrPath
      * @return the generator meta registered under the namespace
@@ -167,16 +175,16 @@ export default class EnvironmentBase extends EventEmitter {
         const parsed = toNamespace(namespaceOrPath);
         if (typeof namespaceOrPath !== 'string' || parsed) {
             const ns = parsed.namespace;
-            return this.store.getMeta(ns) ?? this.store.getMeta(this.alias(ns));
+            return this.getStoreMeta(ns) ?? this.getStoreMeta(this.alias(ns));
         }
-        const maybeMeta = this.store.getMeta(namespaceOrPath) ?? this.store.getMeta(this.alias(namespaceOrPath));
+        const maybeMeta = this.getStoreMeta(namespaceOrPath) ?? this.getStoreMeta(this.alias(namespaceOrPath));
         if (maybeMeta) {
             return maybeMeta;
         }
         try {
             const resolved = resolveModulePath(namespaceOrPath);
             if (resolved) {
-                return this.store.add({ resolved, namespace: this.namespace(resolved) });
+                return this.store.add({ resolved, namespace: this.namespace(resolved) }, undefined, { env: this.asEnvironment() });
             }
         }
         catch {
@@ -241,7 +249,9 @@ export default class EnvironmentBase extends EventEmitter {
     }
     instantiate(constructor, ...arguments_) {
         const composeOptions = arguments_.length > 0 ? getInstantiateOptions(...arguments_) : {};
-        const { namespace = UNKNOWN_NAMESPACE, resolved = UNKNOWN_RESOLVED, _meta } = constructor;
+        const { namespace = UNKNOWN_NAMESPACE, resolved = UNKNOWN_RESOLVED } = constructor;
+        // The generator class keeps the meta of the store, which may be shared: the generator gets the one of this environment.
+        const _meta = this.bindMeta(constructor._meta);
         const environmentOptions = { env: this, resolved, namespace, _meta };
         const generator = new constructor(composeOptions.generatorArgs ?? [], {
             ...this.sharedOptions,
@@ -416,49 +426,12 @@ export default class EnvironmentBase extends EventEmitter {
      * registered as `dummy:yo` generator.
      */
     async lookup(options) {
-        const { registerToScope, customizeNamespace = this.options.generatorLookupOptions?.customizeNamespace ?? ((ns) => ns), lookups = this.lookups, ...remainingOptions } = options ?? { localOnly: false };
-        options = {
-            ...remainingOptions,
-            lookups,
-        };
-        const generators = [];
-        await lookupGenerators(options, ({ packagePath, filePath, lookups }) => {
-            let repositoryPath = join(packagePath, '..');
-            if (basename(repositoryPath).startsWith('@')) {
-                // Scoped package
-                repositoryPath = join(repositoryPath, '..');
-            }
-            let namespace = customizeNamespace(asNamespace(relative(repositoryPath, filePath), { lookups }));
-            try {
-                const resolved = realpathSync(filePath);
-                if (!namespace) {
-                    namespace = customizeNamespace(asNamespace(resolved, { lookups }));
-                }
-                namespace = namespace;
-                if (registerToScope && !namespace.startsWith('@')) {
-                    namespace = `@${registerToScope}/${namespace}`;
-                }
-                const meta = this.store.add({ namespace, packagePath, resolved });
-                if (meta) {
-                    generators.push({
-                        ...meta,
-                        registered: true,
-                    });
-                    return Boolean(options?.singleResult);
-                }
-            }
-            catch (error) {
-                console.error('Unable to register %s (Error: %s)', filePath, error);
-            }
-            generators.push({
-                resolved: filePath,
-                namespace: namespace,
-                packagePath,
-                registered: false,
-            });
-            return false;
+        return this.store.lookupSync({
+            customizeNamespace: this.options.generatorLookupOptions?.customizeNamespace,
+            lookups: this.lookups,
+            ...(options ?? { localOnly: false }),
+            env: this.asEnvironment(),
         });
-        return generators;
     }
     /**
      * Verify if a package namespace already have been registered.
@@ -487,7 +460,14 @@ export default class EnvironmentBase extends EventEmitter {
         if (!meta) {
             return;
         }
-        return { ...meta };
+        // A copy with the functions bound to this environment, the bound meta itself delegates to the meta of the store.
+        const boundMeta = this.bindMeta(meta);
+        return {
+            ...meta,
+            importGenerator: boundMeta.importGenerator,
+            instantiate: boundMeta.instantiate,
+            instantiateHelp: boundMeta.instantiateHelp,
+        };
     }
     alias(match, value) {
         if (match && value) {
@@ -662,9 +642,9 @@ export default class EnvironmentBase extends EventEmitter {
         // Generator is already registered and matches the current namespace.
         const generatorMeta = this.store.getMeta(namespace);
         if (generatorMeta && generatorMeta.resolved === generatorPath) {
-            return generatorMeta;
+            return this.bindMeta(generatorMeta);
         }
-        const meta = this.store.add({ namespace, resolved: generatorPath, packagePath });
+        const meta = this.store.add({ namespace, resolved: generatorPath, packagePath }, undefined, { env: this.asEnvironment() });
         debug('Registered %s (%s) on package %s (%s)', namespace, generatorPath, meta.packageNamespace, packagePath);
         return meta;
     }
@@ -685,7 +665,7 @@ export default class EnvironmentBase extends EventEmitter {
         if (typeof namespace !== 'string') {
             throw new TypeError('You must provide a namespace to register.');
         }
-        const meta = this.store.add({ namespace, resolved, packagePath }, Generator);
+        const meta = this.store.add({ namespace, resolved, packagePath }, Generator, { env: this.asEnvironment() });
         debug('Registered %s (%s) on package (%s)', namespace, resolved, packagePath);
         return meta;
     }

package/dist/environment-full.d.ts

@@ -1,4 +1,4 @@
-import type { BaseGeneratorConstructor, BaseGeneratorOptions, GeneratorEnvironmentOptions } from '@yeoman/types';
+import type { BaseGeneratorConstructor, BaseGeneratorOptions, GeneratorEnvironmentOptions, GeneratorMeta } from '@yeoman/types';
 import { type LookupOptions } from './generator-lookup.ts';
 import EnvironmentBase, { type EnvironmentOptions } from './environment-base.ts';
 declare class FullEnvironment extends EnvironmentBase {
@@ -34,7 +34,7 @@ declare class FullEnvironment extends EnvironmentBase {
      * Returns stored generators meta
      * @return {Object}
      */
-    getGeneratorsMeta(): Record<string, import("@yeoman/types").GeneratorMeta>;
+    getGeneratorsMeta(): Record<string, GeneratorMeta>;
     /**
      * @protected
      * Get registered generators names

package/dist/environment-full.js

@@ -99,7 +99,7 @@ class FullEnvironment extends EnvironmentBase {
      * @return {Object}
      */
     getGeneratorsMeta() {
-        return this.store.getGeneratorsMeta();
+        return this.store.getGeneratorsMeta({ env: this.asEnvironment() });
     }
     /**
      * @protected
@@ -167,7 +167,6 @@ class FullEnvironment extends EnvironmentBase {
             try {
                 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
                 // @ts-ignore
-                // eslint-disable-next-line import-x/no-unresolved
                 const { default: Generator } = await import('yeoman-generator');
                 return Generator;
             }

package/dist/generator-lookup.d.ts

@@ -31,12 +31,12 @@ export declare const defaultExtensions: string[];
  * @param {string|Array} [options.packagePatterns='generator-*'] - Package pattern to look for.
  * @param {boolean}      [options.singleResult=false] - Set true to stop lookup on the first match.
  * @param {Number}       [options.globbyDeep] - Deep option to be passed to globby.
- * @return {Promise<Object[]>} List of generators
+ * @return {Object[]} List of generators
  */
-export declare function lookupGenerators(options?: LookupOptions, register?: (meta: LookupMeta) => boolean): Promise<{
+export declare function lookupGeneratorsSync(options?: LookupOptions, register?: (meta: LookupMeta) => boolean): {
     filePath: string;
     packagePath: string;
-}[]>;
+}[];
 /**
  * Lookup for a specific generator.
  *

package/dist/generator-lookup.js

@@ -2,7 +2,8 @@ import { extname, isAbsolute, join, posix } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { requireNamespace, toNamespace } from '@yeoman/namespace';
 import { findPackagesIn, getNpmPaths, moduleLookupSync } from "./module-lookup.js";
-import { asNamespace, defaultLookups } from "./util/namespace.js";
+import { defaultLookups } from "./util/namespace.js";
+import Store from "./store.js";
 export const defaultExtensions = ['.ts', '.cts', '.mts', '.js', '.cjs', '.mjs'];
 /**
  * Search for generators and their sub generators.
@@ -26,9 +27,9 @@ export const defaultExtensions = ['.ts', '.cts', '.mts', '.js', '.cjs', '.mjs'];
  * @param {string|Array} [options.packagePatterns='generator-*'] - Package pattern to look for.
  * @param {boolean}      [options.singleResult=false] - Set true to stop lookup on the first match.
  * @param {Number}       [options.globbyDeep] - Deep option to be passed to globby.
- * @return {Promise<Object[]>} List of generators
+ * @return {Object[]} List of generators
  */
-export async function lookupGenerators(options = {}, register) {
+export function lookupGeneratorsSync(options = {}, register) {
     const { lookups = defaultLookups } = options;
     options = {
         // Js generators should be after, last will override registered one.
@@ -53,33 +54,27 @@ export async function lookupGenerators(options = {}, register) {
 }
 export function lookupGenerator(namespace, options) {
     options = typeof options === 'boolean' ? { localOnly: options } : (options ?? {});
-    options.singleResult = options.singleResult ?? true;
-    options.filePatterns = options.filePatterns ?? defaultLookups.map(prefix => join(prefix, '*/index.{js,ts}'));
+    const { packagePath: returnPackagePath, generatorPath: returnGeneratorPath, singleResult = true, ...lookupOptions } = options;
     const ns = requireNamespace(namespace);
-    options.packagePatterns = options.packagePatterns ?? [ns.generatorHint];
-    options.npmPaths = options.npmPaths ?? getNpmPaths({ localOnly: options.localOnly }).toReversed();
-    options.packagePatterns = options.packagePatterns ?? ['generator-*'];
-    options.packagePaths = options.packagePaths ?? findPackagesIn(options.npmPaths, options.packagePatterns);
-    let paths = options.singleResult ? undefined : [];
-    moduleLookupSync(options, ({ files, packagePath }) => {
-        for (const filename of files) {
-            const fileNs = asNamespace(filename, { lookups: defaultLookups });
-            const ns = toNamespace(fileNs);
-            if (namespace === fileNs || (options.packagePath && namespace === ns?.packageNamespace)) {
-                // Version 2.6.0 returned pattern instead of modulePath for options.packagePath
-                const returnPath = options.packagePath ? packagePath : options.generatorPath ? posix.join(filename, '../../') : filename;
-                if (options.singleResult) {
-                    paths = returnPath;
-                    return filename;
-                }
-                paths.push(returnPath);
-            }
-        }
-        return;
-    });
-    if (options.singleResult) {
-        const generatorPath = paths;
-        return generatorPath && isAbsolute(generatorPath) ? pathToFileURL(generatorPath).toString() : generatorPath;
+    lookupOptions.packagePatterns = lookupOptions.packagePatterns ?? [ns.generatorHint];
+    if (!lookupOptions.packagePaths) {
+        // Looking the npm paths up runs the package managers, skip it when the packages are given.
+        lookupOptions.npmPaths = lookupOptions.npmPaths ?? getNpmPaths({ localOnly: lookupOptions.localOnly }).toReversed();
+        lookupOptions.packagePaths = findPackagesIn(lookupOptions.npmPaths, lookupOptions.packagePatterns);
     }
-    return paths.map(gen => (isAbsolute(gen) ? pathToFileURL(gen).toString() : gen));
+    // The generators are looked up by a store of their own, which keeps the ones asked for.
+    const generators = new Store().lookupSync({
+        filePatterns: defaultLookups.map(prefix => join(prefix, '*/index.{js,ts}')),
+        reverse: false,
+        ...lookupOptions,
+        lookups: defaultLookups,
+        singleResult,
+        filter: generator => generator.namespace === namespace || Boolean(returnPackagePath && toNamespace(generator.namespace)?.packageNamespace === namespace),
+    });
+    const paths = generators.map(({ filePath, packagePath }) => {
+        // Version 2.6.0 returned pattern instead of modulePath for options.packagePath
+        const returnPath = returnPackagePath ? packagePath : returnGeneratorPath ? posix.join(filePath, '../../') : filePath;
+        return isAbsolute(returnPath) ? pathToFileURL(returnPath).toString() : returnPath;
+    });
+    return singleResult ? paths[0] : paths;
 }

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { type EnvironmentOptions } from './environment-base.ts';
 import Environment from './environment-full.ts';
 export { default } from './environment-full.ts';
 export { default as EnvironmentBase, type EnvironmentOptions } from './environment-base.ts';
+export { default as Store, type StoreEnvironmentOptions, type StoreGeneratorMeta, type StoreLookupGeneratorMeta, type StoreLookupOptions, } from './store.ts';
 export declare const createEnv: (options?: EnvironmentOptions) => Environment;
 export declare const enforceUpdate: () => void;
 export * from './commands.ts';

package/dist/index.js

@@ -2,6 +2,8 @@ import {} from "./environment-base.js";
 import Environment from "./environment-full.js";
 export { default } from "./environment-full.js";
 export { default as EnvironmentBase } from "./environment-base.js";
+// Experimental: the Store API is not stable yet.
+export { default as Store, } from "./store.js";
 export const createEnv = (options) => new Environment(options);
 // Backward compatibility
 export const enforceUpdate = () => { };

package/dist/store.d.ts

@@ -1,36 +1,98 @@
-import type { BaseEnvironment, BaseGeneratorMeta, GeneratorMeta, GetGeneratorConstructor } from '@yeoman/types';
+import type { BaseEnvironment, BaseGenerator, BaseGeneratorConstructorMeta, BaseGeneratorMeta, GeneratorMeta, GetGeneratorConstructor } from '@yeoman/types';
+import { type LookupOptions } from './generator-lookup.ts';
+type FoundGenerator = {
+    namespace: string;
+    /** Path of the generator as it was found, `resolved` is its real path. */
+    filePath: string;
+    packagePath: string;
+};
+/** The environment to import or instantiate a generator in. */
+export type StoreEnvironmentOptions = {
+    env?: BaseEnvironment;
+};
+export type StoreLookupOptions = LookupOptions & StoreEnvironmentOptions & {
+    registerToScope?: string;
+    customizeNamespace?: (ns?: string) => string | undefined;
+    /** Generators to keep, the others are neither registered nor returned. */
+    filter?: (generator: FoundGenerator) => boolean;
+};
+/** A generator found by a lookup, `registered` tells if it was added to the store. */
+export type StoreLookupGeneratorMeta = FoundGenerator & ((StoreGeneratorMeta & {
+    registered: true;
+}) | (Required<BaseGeneratorMeta> & {
+    registered: false;
+}));
+/**
+ * Generator meta as the store keeps it. `importGenerator`, `instantiate` and `instantiateHelp` take the environment
+ * to use as `{ env }`, falling back to the one the meta is bound to: the environment the store was created with, if
+ * any, or the one passed to the store method that returned the meta.
+ */
+export type StoreGeneratorMeta = Omit<GeneratorMeta, 'importGenerator' | 'instantiate' | 'instantiateHelp'> & {
+    importGenerator: <G extends BaseGenerator = BaseGenerator>(options?: StoreEnvironmentOptions) => Promise<GetGeneratorConstructor<G> & BaseGeneratorConstructorMeta> | (GetGeneratorConstructor<G> & BaseGeneratorConstructorMeta);
+    instantiate: <G extends BaseGenerator = BaseGenerator>(arguments_?: string[], options?: any, environmentOptions?: StoreEnvironmentOptions) => Promise<G>;
+    instantiateHelp: <G extends BaseGenerator = BaseGenerator>(options?: StoreEnvironmentOptions) => Promise<G>;
+};
 /**
  * The Generator store
  * This is used to store generator (npm packages) reference and instantiate them when
  * requested.
- * @constructor
- * @private
+ *
+ * A store does not need an environment: generators are looked up and registered on their own, and the environment
+ * that imports or instantiates one is passed at that time. The same store can then serve several environments: the
+ * methods returning metas take `{ env }` and return metas bound to it.
+ *
+ * @experimental The Store API is not stable yet and may change in a minor release.
  */
 export default class Store {
     private readonly _meta;
     private readonly _packagesJson;
     private readonly _packagesPaths;
     private readonly _packagesNS;
-    private readonly environment;
-    constructor(environment: BaseEnvironment);
+    private readonly _boundMetas;
+    /** The environment used when none is passed to `importGenerator` or `instantiate`. */
+    readonly environment?: BaseEnvironment;
+    constructor(environment?: BaseEnvironment);
     /**
      * Store a module under the namespace key
      * @param meta
      * @param generator - A generator module or a module path
+     * @param options.env - The environment to bind the returned meta to
+     */
+    add<M extends BaseGeneratorMeta>(meta: M, Generator?: unknown, { env }?: StoreEnvironmentOptions): StoreGeneratorMeta & M;
+    /**
+     * The meta bound to an environment: its functions default to it. The meta of the environment the store was created
+     * with is the meta itself, as it already defaults to it. A meta is bound once by environment, and delegates to the
+     * meta of the store instead of copying it, so it keeps showing what the store has.
+     */
+    bindMeta<M extends StoreGeneratorMeta>(meta: M, options?: StoreEnvironmentOptions): M;
+    bindMeta<M extends StoreGeneratorMeta>(meta: M | undefined, options?: StoreEnvironmentOptions): M | undefined;
+    /**
+     * Search for generators and their sub generators, and add them to the store.
+     *
+     * A generator is a `:lookup/:name/index.js` file placed inside an npm package.
+     *
+     * Defaults lookups are:
+     *   - ./
+     *   - generators/
+     *   - lib/generators/
+     *
+     * So this index file `node_modules/generator-dummy/lib/generators/yo/index.js` would be
+     * registered as `dummy:yo` generator.
      */
-    add<M extends BaseGeneratorMeta>(meta: M, Generator?: unknown): GeneratorMeta & M;
+    lookupSync(options?: StoreLookupOptions): StoreLookupGeneratorMeta[];
     /**
      * Get the module registered under the given namespace
      * @param  {String} namespace
+     * @param  options.env - The environment to import the generator in
      * @return {Module}
      */
-    get(namespace: string): Promise<GetGeneratorConstructor | undefined>;
+    get(namespace: string, options?: StoreEnvironmentOptions): Promise<GetGeneratorConstructor | undefined>;
     /**
-     * Get the module registered under the given namespace
+     * Get the meta registered under the given namespace
      * @param  {String} namespace
-     * @return {Module}
+     * @param  options.env - The environment to bind the meta to
      */
-    getMeta(namespace: string): GeneratorMeta | undefined;
+    getMeta(namespace: string, options?: StoreEnvironmentOptions): StoreGeneratorMeta | undefined;
     /**
      * Returns the list of registered namespace.
      * @return {Array} Namespaces array
@@ -38,9 +100,10 @@ export default class Store {
     namespaces(): string[];
     /**
      * Get the stored generators meta data
+     * @param  options.env - The environment to bind the metas to
      * @return {Object} Generators metadata
      */
-    getGeneratorsMeta(): Record<string, GeneratorMeta>;
+    getGeneratorsMeta(options?: StoreEnvironmentOptions): Record<string, StoreGeneratorMeta>;
     /**
      * Store a package under the namespace key
      * @param {String}     packageNS - The key under which the generator can be retrieved
@@ -66,6 +129,11 @@ export default class Store {
      * Read a package.json from packagePath. Parsed results are cached by packagePath.
      */
     private getPackageJson;
+    /**
+     * The functions of a meta that need an environment, defaulting to the given one.
+     */
+    private bindMetaFunctions;
     private getFactory;
     private _getGenerator;
 }
+export {};

package/dist/store.js

@@ -7,19 +7,25 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { pathToFileURL } from 'node:url';
-import { extname, join } from 'node:path';
+import { basename, extname, join, relative } from 'node:path';
 import { createRequire } from 'node:module';
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import { toNamespace } from '@yeoman/namespace';
 import createDebug from 'debug';
+import { lookupGeneratorsSync } from "./generator-lookup.js";
+import { asNamespace, defaultLookups } from "./util/namespace.js";
 const debug = createDebug('yeoman:environment:store');
 const require = createRequire(import.meta.url);
 /**
  * The Generator store
  * This is used to store generator (npm packages) reference and instantiate them when
  * requested.
- * @constructor
- * @private
+ *
+ * A store does not need an environment: generators are looked up and registered on their own, and the environment
+ * that imports or instantiates one is passed at that time. The same store can then serve several environments: the
+ * methods returning metas take `{ env }` and return metas bound to it.
+ *
+ * @experimental The Store API is not stable yet and may change in a minor release.
  */
 export default class Store {
     _meta = {};
@@ -29,6 +35,9 @@ export default class Store {
     _packagesPaths = {};
     // Store packages ns
     _packagesNS = [];
+    // Metas bound to an environment, by the meta of the store.
+    _boundMetas = new WeakMap();
+    /** The environment used when none is passed to `importGenerator` or `instantiate`. */
     environment;
     constructor(environment) {
         this.environment = environment;
@@ -37,8 +46,9 @@ export default class Store {
      * Store a module under the namespace key
      * @param meta
      * @param generator - A generator module or a module path
+     * @param options.env - The environment to bind the returned meta to
      */
-    add(meta, Generator) {
+    add(meta, Generator, { env } = {}) {
         if (typeof meta.resolved === 'string') {
             if (extname(meta.resolved)) {
                 meta.resolved = join(meta.resolved);
@@ -74,52 +84,72 @@ export default class Store {
                 }
             };
         }
-        let importPromise;
+        let moduleImport;
+        const importGeneratorModule = () => {
+            if (!importModule || Generator) {
+                return undefined;
+            }
+            if (moduleImport) {
+                return moduleImport;
+            }
+            const maybeModule = importModule();
+            if (maybeModule.then) {
+                moduleImport = maybeModule
+                    .then((module_) => {
+                    Generator = module_;
+                })
+                    .finally(() => {
+                    moduleImport = undefined;
+                });
+                return moduleImport;
+            }
+            Generator = maybeModule;
+            return undefined;
+        };
         // eslint-disable-next-line prefer-const
         let generatorMeta;
-        const importGenerator = () => {
-            const handleImport = () => {
-                if (importModule && !Generator) {
-                    const maybeModule = importModule();
-                    if (maybeModule.then) {
-                        importPromise = maybeModule;
-                        return maybeModule
-                            .then((mod) => {
-                            Generator = mod;
-                        })
-                            .finally(() => {
-                            importPromise = undefined;
-                        });
-                    }
-                    else {
-                        Generator = maybeModule;
-                    }
-                }
-            };
-            const handleModule = () => {
-                const factory = this.getFactory(Generator);
-                if (typeof factory === 'function') {
-                    importPromise = factory(this.environment);
-                    return Promise.resolve(importPromise).then((mod) => {
-                        const generator = this._getGenerator(mod, meta, generatorMeta);
-                        Generator = generator;
-                        importPromise = undefined;
-                        return generator;
-                    });
-                }
-                return this._getGenerator(Generator, meta, generatorMeta);
-            };
-            if (importPromise) {
-                return importPromise.then(() => Promise.resolve(handleImport()).then(() => handleModule()));
+        // A generator exported as a class is the same for every environment.
+        let generatorConstructor;
+        // A `createGenerator(environment)` factory builds the generator for an environment, so its result is kept by environment.
+        const createdGenerators = new WeakMap();
+        const getGenerator = (environment) => {
+            if (generatorConstructor) {
+                return generatorConstructor;
+            }
+            const factory = this.getFactory(Generator);
+            if (typeof factory !== 'function') {
+                generatorConstructor = this._getGenerator(Generator, meta, generatorMeta);
+                return generatorConstructor;
+            }
+            if (!environment) {
+                throw new Error(`An environment is required to create the generator ${meta.namespace}`);
             }
-            const maybeImportPromise = handleImport();
-            if (maybeImportPromise?.then) {
-                return maybeImportPromise.then(() => handleModule());
+            const created = createdGenerators.get(environment);
+            if (created) {
+                return created;
+            }
+            const creating = Promise.resolve(factory(environment)).then((module_) => {
+                const generator = this._getGenerator(module_, meta, generatorMeta);
+                createdGenerators.set(environment, generator);
+                return generator;
+            });
+            createdGenerators.set(environment, creating);
+            return creating;
+        };
+        const importGenerator = (({ env: environment = this.environment } = {}) => {
+            const importing = importGeneratorModule();
+            return importing ? importing.then(() => getGenerator(environment)) : getGenerator(environment);
+        });
+        const instantiate = async (arguments_ = [], options = {}, { env: environment = this.environment } = {}) => {
+            if (!environment) {
+                throw new Error(`An environment is required to instantiate the generator ${meta.namespace}`);
             }
-            return handleModule();
+            return environment.instantiate(await importGenerator({ env: environment }), {
+                generatorArgs: arguments_,
+                generatorOptions: options,
+            });
         };
-        const instantiate = async (arguments_ = [], options = {}) => this.environment.instantiate(await importGenerator(), { generatorArgs: arguments_, generatorOptions: options });
-        const instantiateHelp = async () => instantiate([], { help: true });
+        const instantiateHelp = async (options) => instantiate([], { help: true }, options);
         const getPackageJson = () => this.getPackageJson(meta.packagePath);
         const { packageNamespace } = toNamespace(meta.namespace) ?? {};
         generatorMeta = {
@@ -138,23 +168,91 @@ export default class Store {
                 this.addPackage(packageNamespace, meta.packagePath);
             }
         }
-        return generatorMeta;
+        return this.bindMeta(generatorMeta, { env });
+    }
+    bindMeta(meta, { env } = {}) {
+        if (!meta || !env || env === this.environment) {
+            return meta;
+        }
+        let boundMetas = this._boundMetas.get(meta);
+        if (!boundMetas) {
+            boundMetas = new WeakMap();
+            this._boundMetas.set(meta, boundMetas);
+        }
+        let boundMeta = boundMetas.get(env);
+        if (!boundMeta) {
+            boundMeta = Object.assign(Object.create(meta), this.bindMetaFunctions(meta, env));
+            boundMetas.set(env, boundMeta);
+        }
+        return boundMeta;
+    }
+    /**
+     * Search for generators and their sub generators, and add them to the store.
+     *
+     * A generator is a `:lookup/:name/index.js` file placed inside an npm package.
+     *
+     * Defaults lookups are:
+     *   - ./
+     *   - generators/
+     *   - lib/generators/
+     *
+     * So this index file `node_modules/generator-dummy/lib/generators/yo/index.js` would be
+     * registered as `dummy:yo` generator.
+     */
+    lookupSync(options) {
+        const { registerToScope, customizeNamespace = (ns) => ns, filter, env, lookups = defaultLookups, ...remainingOptions } = options ?? { localOnly: false };
+        const lookupOptions = { ...remainingOptions, lookups };
+        const generators = [];
+        lookupGeneratorsSync(lookupOptions, ({ packagePath, filePath, lookups }) => {
+            let repositoryPath = join(packagePath, '..');
+            if (basename(repositoryPath).startsWith('@')) {
+                // Scoped package
+                repositoryPath = join(repositoryPath, '..');
+            }
+            let namespace = customizeNamespace(asNamespace(relative(repositoryPath, filePath), { lookups }));
+            try {
+                const resolved = realpathSync(filePath);
+                if (!namespace) {
+                    namespace = customizeNamespace(asNamespace(resolved, { lookups }));
+                }
+                namespace = namespace;
+                if (registerToScope && !namespace.startsWith('@')) {
+                    namespace = `@${registerToScope}/${namespace}`;
+                }
+                if (filter && !filter({ namespace, filePath, packagePath })) {
+                    return false;
+                }
+                const meta = this.add({ namespace, packagePath, resolved });
+                if (meta) {
+                    const boundFunctions = env && env !== this.environment ? this.bindMetaFunctions(meta, env) : {};
+                    generators.push({ ...meta, ...boundFunctions, filePath, packagePath, registered: true });
+                    return Boolean(lookupOptions.singleResult);
+                }
+            }
+            catch (error) {
+                console.error('Unable to register %s (Error: %s)', filePath, error);
+            }
+            generators.push({ resolved: filePath, namespace: namespace, filePath, packagePath, registered: false });
+            return false;
+        });
+        return generators;
     }
     /**
      * Get the module registered under the given namespace
      * @param  {String} namespace
+     * @param  options.env - The environment to import the generator in
      * @return {Module}
      */
-    async get(namespace) {
-        return this.getMeta(namespace)?.importGenerator();
+    async get(namespace, options) {
+        return this.getMeta(namespace)?.importGenerator(options);
     }
     /**
-     * Get the module registered under the given namespace
+     * Get the meta registered under the given namespace
      * @param  {String} namespace
-     * @return {Module}
+     * @param  options.env - The environment to bind the meta to
      */
-    getMeta(namespace) {
-        return this._meta[namespace];
+    getMeta(namespace, options) {
+        return this.bindMeta(this._meta[namespace], options);
     }
     /**
      * Returns the list of registered namespace.
@@ -165,10 +263,22 @@ export default class Store {
     }
     /**
      * Get the stored generators meta data
+     * @param  options.env - The environment to bind the metas to
      * @return {Object} Generators metadata
      */
-    getGeneratorsMeta() {
-        return this._meta;
+    getGeneratorsMeta(options) {
+        const env = options?.env;
+        if (!env || env === this.environment) {
+            return this._meta;
+        }
+        // Bound as they are read. It is a view of the record of the store, as the record itself is what is returned
+        // otherwise: what is set goes to the store.
+        return new Proxy(this._meta, {
+            get: (target, property, receiver) => {
+                const meta = Reflect.get(target, property, receiver);
+                return typeof property === 'string' && meta ? this.bindMeta(meta, { env }) : meta;
+            },
+        });
     }
     /**
      * Store a package under the namespace key
@@ -235,6 +345,16 @@ export default class Store {
         }
         return this._packagesJson.get(packagePath);
     }
+    /**
+     * The functions of a meta that need an environment, defaulting to the given one.
+     */
+    bindMetaFunctions(meta, env) {
+        return {
+            importGenerator: (({ env: environment = env } = {}) => meta.importGenerator({ env: environment })),
+            instantiate: (arguments_, options, { env: environment = env } = {}) => meta.instantiate(arguments_, options, { env: environment }),
+            instantiateHelp: ({ env: environment = env } = {}) => meta.instantiateHelp({ env: environment }),
+        };
+    }
     getFactory(module) {
         // CJS is imported in default, for backward compatibility we support a Generator exported as `module.exports = { default }`
         return module.createGenerator ?? module.default?.createGenerator ?? module.default?.default?.createGenerator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yeoman-environment",
-  "version": "6.3.0",
+  "version": "7.1.0",
   "description": "Handles the lifecyle and bootstrapping of generators in a specific environment",
   "keywords": [
     "development",
@@ -41,77 +41,68 @@
   ],
   "scripts": {
     "prebuild": "rimraf dist",
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "doc": "npm run doc:generate && npm run doc:fix && npm run doc:prettier",
     "doc:fix": "sed -i -e 's:^[[:space:]]*<!--[[:space:]]*$::g' -e 's:^[[:space:]]*-->[[:space:]]*$::g' $npm_package_config_doc_path/global.html || true",
     "doc:generate": "jsdoc -c jsdoc.json -d $npm_package_config_doc_path",
     "doc:prettier": "prettier $npm_package_config_doc_path --write --ignore-path .prettierignore-doc",
     "fix": "eslint --fix && prettier . --write",
     "prepare": "npm run build",
-    "pretest": "eslint && prettier . --check && tsc -p tsconfig.test.json",
+    "pretest": "eslint && prettier . --check && tsc",
     "test": "c8 --include 'src/**' esmocha --forbid-only"
   },
   "config": {
     "doc_path": "./yeoman-environment-doc"
   },
   "dependencies": {
-    "@yeoman/adapter": "^4.0.2",
-    "@yeoman/conflicter": "^4.1.0",
+    "@yeoman/adapter": "^5.0.0",
+    "@yeoman/conflicter": "^4.2.0",
     "@yeoman/namespace": "^2.1.0",
-    "@yeoman/transform": "^2.1.1",
-    "@yeoman/types": "^1.11.1",
+    "@yeoman/transform": "^2.1.2",
+    "@yeoman/types": "^1.13.1",
     "arrify": "^3.0.0",
-    "chalk": "^5.6.2",
-    "commander": "^14.0.3",
+    "chalk": "^6.0.0",
+    "commander": "^15.0.0",
     "debug": "^4.4.3",
-    "execa": "^9.6.1",
+    "execa": "^10.0.1",
     "fly-import": "^1.0.0",
-    "globby": "^16.2.0",
+    "globby": "^16.2.4",
     "grouped-queue": "^2.1.0",
     "locate-path": "^8.0.0",
     "lodash-es": "^4.18.1",
-    "mem-fs": "^4.1.4",
-    "mem-fs-editor": "^12.0.4",
-    "semver": "^7.7.4",
+    "mem-fs": "^6.0.0",
+    "mem-fs-editor": "^12.0.9",
+    "semver": "^7.8.5",
     "slash": "^5.1.0",
     "untildify": "^6.0.0",
     "which-package-manager": "^1.0.1"
   },
   "devDependencies": {
-    "@node-loaders/esbuild": "^2.0.0",
     "@types/debug": "^4.1.13",
     "@types/lodash-es": "^4.17.12",
-    "@types/node": "^20.19.35",
-    "@types/semver": "^7.7.1",
+    "@types/node": "^26.4.1",
+    "@types/semver": "^7.8.0",
     "@yeoman/eslint": "1.1.0",
     "c8": "^12.0.0",
-    "eslint": "10.2.1",
+    "eslint": "10.10.0",
     "esmocha": "^5.0.0",
     "jsdoc": "^4.0.5",
-    "prettier": "3.8.3",
+    "prettier": "3.9.6",
     "prettier-plugin-packagejson": "^3.0.2",
     "rimraf": "^6.1.3",
+    "simple-git": "^3.36.0",
     "strip-ansi": "^7.2.0",
     "typescript": "6.0.3",
     "yeoman-environment": "file:./",
-    "yeoman-test": "^11.3.1"
+    "yeoman-test": "^11.8.0"
   },
   "peerDependencies": {
-    "@yeoman/adapter": "^4.0.2",
+    "@yeoman/adapter": "^5.0.0",
     "@yeoman/types": "^1.10.3",
     "mem-fs": "^4.1.4 || ^6.0.0"
   },
   "engines": {
-    "node": "^20.17.0 || >=22.9.0"
-  },
-  "acceptDependencies": {
-    "@yeoman/adapter": ">=4.0.2 || ^5.0.0"
-  },
-  "overrides": {
-    "@inquirer/type": "4.0.7",
-    "@yeoman-environment/generator-tests": {
-      "yeoman-environment": "file:./"
-    }
+    "node": "^22.18.0 || >=24.11.0"
   },
   "workspaces": [
     "test/generators"