yeoman-environment 8.0.0 → 8.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, { type StoreGeneratorMeta } from './store.ts';
+import Store, { type StoreGeneratorMeta, type StoreSharedLookupOptions } from './store.ts';
 import type YeomanCommand from './util/command.ts';
 import { type LookupOptions } from './generator-lookup.ts';
 import { type InstallTask } from './package-manager.ts';
@@ -26,10 +26,22 @@ export type EnvironmentOptions = ConflicterOptions & BaseEnvironmentOptions & Om
     yeomanRepository?: string;
     arboristRegistry?: string;
     nodePackageManager?: string;
+    /**
+     * @deprecated Use `storeOptions`.
+     */
     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.
+     * Lookup options of the store of the environment, shared by every lookup. When a `store` is passed, the
+     * environment works on a clone of it with these options merged over its own.
+     *
+     * @experimental
+     */
+    storeOptions?: StoreSharedLookupOptions;
+    /**
+     * Generators store to start from instead of an empty one, to reuse the generators already looked up and registered
+     * in it. The environment works on a clone of it (see `Store#clone`), with `storeOptions` merged over its options:
+     * the generators the environment looks up or registers are added to its clone only, they are neither added to the
+     * store passed nor seen by the other environments created with it. The generators already imported are shared.
      *
      * @experimental
      */
@@ -57,7 +69,6 @@ export default class EnvironmentBase extends EventEmitter implements BaseEnviron
     protected command?: YeomanCommand;
     protected runLoop: GroupedQueue;
     protected composedStore: ComposedStore;
-    protected lookups: string[];
     protected repository: FlyRepository;
     protected experimental: boolean;
     protected _rootGenerator?: BaseGenerator;
@@ -141,6 +152,10 @@ export default class EnvironmentBase extends EventEmitter implements BaseEnviron
      * @param {Array} lookups paths
      */
     namespace(filepath: string, lookups?: string[]): string;
+    /**
+     * @deprecated Use the lookups of the store.
+     */
+    protected get lookups(): string[];
     /**
      * Returns the environment or dependency version.
      * @param  {String} packageName - Module to get version.

package/dist/environment-base.js

@@ -16,7 +16,6 @@ import {} from '@yeoman/conflicter';
 import { defaults, pick } from 'lodash-es';
 import { ComposedStore } from "./composed-store.js";
 import Store, {} from "./store.js";
-import { asNamespace, defaultLookups } from "./util/namespace.js";
 import {} from "./generator-lookup.js";
 import { UNKNOWN_NAMESPACE, UNKNOWN_RESOLVED, defaultQueues } from "./constants.js";
 import { resolveModulePath } from "./util/resolve.js";
@@ -97,7 +96,6 @@ export default class EnvironmentBase extends EventEmitter {
     command;
     runLoop;
     composedStore;
-    lookups;
     repository;
     experimental;
     _rootGenerator;
@@ -106,12 +104,14 @@ 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 }), store, ...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, storeOptions, ...remainingOptions } = options;
         this.options = remainingOptions;
         this.adapter = adapter;
         this.cwd = resolve(cwd);
         this.logCwd = logCwd;
-        this.store = store ?? new Store(this);
+        const lookupOptions = { ...remainingOptions.generatorLookupOptions, ...storeOptions };
+        // A store passed is cloned: what this environment looks up or registers does not change it.
+        this.store = store ? store.clone(this, lookupOptions) : new Store(this, lookupOptions);
         this.command = command;
         this.runLoop = new GroupedQueue(defaultQueues, false);
         this.composedStore = new ComposedStore({ log: this.adapter.log });
@@ -120,7 +120,6 @@ export default class EnvironmentBase extends EventEmitter {
         // Node won't complain about event listeners leaks.
         this.runLoop.setMaxListeners(0);
         this.sharedFs.setMaxListeners(0);
-        this.lookups = this.options.generatorLookupOptions?.lookups ?? defaultLookups;
         this.sharedOptions = sharedOptions;
         // Create a default sharedData.
         this.sharedOptions.sharedData = this.sharedOptions.sharedData ?? {};
@@ -297,8 +296,14 @@ export default class EnvironmentBase extends EventEmitter {
      * @param {String} filepath
      * @param {Array} lookups paths
      */
-    namespace(filepath, lookups = this.lookups) {
-        return asNamespace(filepath, { lookups });
+    namespace(filepath, lookups) {
+        return this.store.namespace(filepath, lookups);
+    }
+    /**
+     * @deprecated Use the lookups of the store.
+     */
+    get lookups() {
+        return this.store.lookups;
     }
     getVersion(packageName) {
         if (packageName && packageName !== 'yeoman-environment') {
@@ -426,12 +431,7 @@ export default class EnvironmentBase extends EventEmitter {
      * registered as `dummy:yo` generator.
      */
     async lookup(options) {
-        return this.store.lookupSync({
-            customizeNamespace: this.options.generatorLookupOptions?.customizeNamespace,
-            lookups: this.lookups,
-            ...(options ?? { localOnly: false }),
-            env: this.asEnvironment(),
-        });
+        return this.store.lookupSync({ ...options, env: this.asEnvironment() });
     }
     /**
      * Verify if a package namespace already have been registered.

package/dist/environment-full.js

@@ -264,7 +264,7 @@ class FullEnvironment extends EnvironmentBase {
                 // Build filePatterns to look specifically for the namespace.
                 const genPath = ns.generator.split(':').join('/');
                 let filePatterns = [`${genPath}/index.?s`, `${genPath}.?s`];
-                const lookups = options.lookups ?? this.lookups;
+                const lookups = options.lookups ?? this.store.lookups;
                 filePatterns = lookups.flatMap(prefix => filePatterns.map(pattern => join(prefix, pattern)));
                 nsOptions.filePatterns = filePatterns;
                 nsOptions.singleResult = true;

package/dist/index.d.ts

@@ -2,11 +2,11 @@ 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 { default as Store, type StoreEnvironmentOptions, type StoreGeneratorMeta, type StoreLookupGeneratorMeta, type StoreLookupOptions, type StoreSharedLookupOptions, } from './store.ts';
 export declare const createEnv: (options?: EnvironmentOptions) => Environment;
 export declare const enforceUpdate: () => void;
-export * from './commands.ts';
-export * from './util/command.ts';
-export * from './package-manager.ts';
-export * from './commit.ts';
+export { type CommandPreparation, prepareCommand, prepareGeneratorCommand } from './commands.ts';
+export { addEnvironmentOptions } from './util/command.ts';
+export { type InstallTask, type PackageManagerInstallTaskOptions, packageManagerInstallTask } from './package-manager.ts';
+export { commitSharedFsTask } from './commit.ts';
 export { lookupGenerator } from './generator-lookup.ts';

package/dist/index.js

@@ -7,8 +7,8 @@ export { default as Store, } from "./store.js";
 export const createEnv = (options) => new Environment(options);
 // Backward compatibility
 export const enforceUpdate = () => { };
-export * from "./commands.js";
-export * from "./util/command.js";
-export * from "./package-manager.js";
-export * from "./commit.js";
+export { prepareCommand, prepareGeneratorCommand } from "./commands.js";
+export { addEnvironmentOptions } from "./util/command.js";
+export { packageManagerInstallTask } from "./package-manager.js";
+export { commitSharedFsTask } from "./commit.js";
 export { lookupGenerator } from "./generator-lookup.js";

package/dist/store.d.ts

@@ -13,9 +13,16 @@ export type StoreEnvironmentOptions = {
 export type StoreLookupOptions = LookupOptions & StoreEnvironmentOptions & {
     registerToScope?: string;
     customizeNamespace?: (ns?: string) => string | undefined;
+    /** Derive the namespace from the name in the package.json instead of the package directory. */
+    usePackageName?: boolean;
     /** Generators to keep, the others are neither registered nor returned. */
     filter?: (generator: FoundGenerator) => boolean;
 };
+/**
+ * Lookup options shared by every lookup of a store, the options passed to a lookup take precedence.
+ * What to look up (paths, package patterns and `singleResult`) is given by each lookup.
+ */
+export type StoreSharedLookupOptions = Pick<StoreLookupOptions, 'lookups' | 'localOnly' | 'filterPaths' | 'customizeNamespace' | 'filter' | 'usePackageName'>;
 /** A generator found by a lookup, `registered` tells if it was added to the store. */
 export type StoreLookupGeneratorMeta = FoundGenerator & ((StoreGeneratorMeta & {
     registered: true;
@@ -53,7 +60,39 @@ export default class Store {
     private readonly _boundMetas;
     /** The environment used when none is passed to `importGenerator` or `instantiate`. */
     readonly environment?: BaseEnvironment;
-    constructor(environment?: BaseEnvironment);
+    /** Options passed to every lookup, so consecutive lookups share the same configuration. */
+    readonly lookupOptions: StoreSharedLookupOptions;
+    constructor(environment?: BaseEnvironment, lookupOptions?: StoreSharedLookupOptions);
+    /** The lookups shared by the store, or the default ones. */
+    get lookups(): string[];
+    /**
+     * Given a String `filepath`, tries to figure out the relative namespace.
+     *
+     * ### Examples:
+     *
+     *     store.namespace('backbone/all/index.js');
+     *     // => backbone:all
+     *
+     *     store.namespace('generator-backbone/model');
+     *     // => backbone:model
+     *
+     *     store.namespace('backbone.js');
+     *     // => backbone
+     *
+     *     store.namespace('generator-mocha/backbone/model/index.js');
+     *     // => mocha:backbone:model
+     *
+     * @param filepath
+     * @param lookups - The lookups of the store if omitted
+     */
+    namespace(filepath: string, lookups?: string[]): string;
+    /**
+     * A copy of the store with the same generators, packages and lookup options, whose metas default to the given
+     * environment. The generators already imported are shared, what is added after cloning goes only to its store.
+     * @param environment - The environment of the clone, the environment of the store if omitted
+     * @param options - Lookup options of the clone, merged over the ones of the store
+     */
+    clone(environment?: BaseEnvironment | undefined, options?: StoreSharedLookupOptions): Store;
     /**
      * Store a module under the namespace key
      * @param meta
@@ -65,6 +104,7 @@ export default class Store {
      * 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.
+     * The meta of the store a clone was created from, as the one a generator class keeps, is the meta of the clone.
      */
     bindMeta<M extends StoreGeneratorMeta>(meta: M, options?: StoreEnvironmentOptions): M;
     bindMeta<M extends StoreGeneratorMeta>(meta: M | undefined, options?: StoreEnvironmentOptions): M | undefined;
@@ -80,6 +120,8 @@ export default class Store {
      *
      * So this index file `node_modules/generator-dummy/lib/generators/yo/index.js` would be
      * registered as `dummy:yo` generator.
+     *
+     * The options are merged over the lookup options the store was created with.
      */
     lookupSync(options?: StoreLookupOptions): StoreLookupGeneratorMeta[];
     /**
@@ -131,10 +173,19 @@ export default class Store {
      * Read a package.json from packagePath. Parsed results are cached by packagePath.
      */
     private getPackageJson;
+    /**
+     * The meta of the store sharing its operations with the given meta, coming from the store it was cloned from or from
+     * one of its clones, or the given meta.
+     */
+    private ownMeta;
     /**
      * The functions of a meta that need an environment, defaulting to the given one.
      */
     private bindMetaFunctions;
+    /**
+     * The functions of a meta, running its operations in the environment passed as `{ env }`, or the default one.
+     */
+    private createMetaFunctions;
     private getFactory;
     private _getGenerator;
 }

package/dist/store.js

@@ -16,6 +16,10 @@ 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 operations of a meta, kept on the meta itself: the meta of a clone has the operations of the meta it was cloned from.
+const operationsKey = Symbol('operations');
+const setOperations = (meta, operations) => Object.defineProperty(meta, operationsKey, { value: operations });
+const getOperations = (meta) => meta[operationsKey];
 /**
  * The Generator store
  * This is used to store generator (npm packages) reference and instantiate them when
@@ -39,8 +43,60 @@ export default class Store {
     _boundMetas = new WeakMap();
     /** The environment used when none is passed to `importGenerator` or `instantiate`. */
     environment;
-    constructor(environment) {
+    /** Options passed to every lookup, so consecutive lookups share the same configuration. */
+    lookupOptions;
+    constructor(environment, lookupOptions = {}) {
         this.environment = environment;
+        this.lookupOptions = lookupOptions;
+    }
+    /** The lookups shared by the store, or the default ones. */
+    get lookups() {
+        return this.lookupOptions.lookups ?? defaultLookups;
+    }
+    /**
+     * Given a String `filepath`, tries to figure out the relative namespace.
+     *
+     * ### Examples:
+     *
+     *     store.namespace('backbone/all/index.js');
+     *     // => backbone:all
+     *
+     *     store.namespace('generator-backbone/model');
+     *     // => backbone:model
+     *
+     *     store.namespace('backbone.js');
+     *     // => backbone
+     *
+     *     store.namespace('generator-mocha/backbone/model/index.js');
+     *     // => mocha:backbone:model
+     *
+     * @param filepath
+     * @param lookups - The lookups of the store if omitted
+     */
+    namespace(filepath, lookups = this.lookups) {
+        return asNamespace(filepath, { lookups });
+    }
+    /**
+     * A copy of the store with the same generators, packages and lookup options, whose metas default to the given
+     * environment. The generators already imported are shared, what is added after cloning goes only to its store.
+     * @param environment - The environment of the clone, the environment of the store if omitted
+     * @param options - Lookup options of the clone, merged over the ones of the store
+     */
+    clone(environment = this.environment, options) {
+        const store = new Store(environment, { ...this.lookupOptions, ...options });
+        for (const [namespace, meta] of Object.entries(this._meta)) {
+            const operations = getOperations(meta);
+            store._meta[namespace] = setOperations({
+                ...meta,
+                ...store.createMetaFunctions(operations, () => store.environment),
+                getPackageJson: () => store.getPackageJson(meta.packagePath),
+            }, operations);
+        }
+        for (const [packageNamespace, packagePaths] of Object.entries(this._packagesPaths)) {
+            store._packagesPaths[packageNamespace] = [...packagePaths];
+        }
+        store._packagesNS.push(...this._packagesNS);
+        return store;
     }
     /**
      * Store a module under the namespace key
@@ -138,32 +194,31 @@ export default class Store {
             createdGenerators.set(environment, creating);
             return creating;
         };
-        const importGenerator = (({ env: environment = this.environment } = {}) => {
+        const importGenerator = (environment) => {
             const importing = importGeneratorModule();
             return importing ? importing.then(() => getGenerator(environment)) : getGenerator(environment);
-        });
-        const instantiate = async (arguments_ = [], options = {}, { env: environment = this.environment } = {}) => {
+        };
+        const instantiate = async (arguments_ = [], options = {}, environment) => {
             if (!environment) {
                 throw new Error(`An environment is required to instantiate the generator ${meta.namespace}`);
             }
-            return environment.instantiate(await importGenerator({ env: environment }), {
+            return environment.instantiate(await importGenerator(environment), {
                 generatorArgs: arguments_,
                 generatorOptions: options,
             });
         };
-        const instantiateHelp = async (options) => instantiate([], { help: true }, options);
+        const operations = { importGenerator, instantiate };
         const getPackageJson = () => this.getPackageJson(meta.packagePath);
         const { packageNamespace } = toNamespace(meta.namespace) ?? {};
         generatorMeta = {
             ...meta,
-            importGenerator,
+            ...this.createMetaFunctions(operations, () => this.environment),
             requireModule,
             importModule,
-            instantiate,
-            instantiateHelp,
             getPackageJson,
             packageNamespace,
         };
+        setOperations(generatorMeta, operations);
         this._meta[meta.namespace] = generatorMeta;
         if (packageNamespace) {
             this.addPackageNamespace(packageNamespace);
@@ -174,6 +229,7 @@ export default class Store {
         return this.bindMeta(generatorMeta, { env });
     }
     bindMeta(meta, { env } = {}) {
+        meta = this.ownMeta(meta);
         if (!meta || !env || env === this.environment) {
             return meta;
         }
@@ -201,18 +257,28 @@ export default class Store {
      *
      * So this index file `node_modules/generator-dummy/lib/generators/yo/index.js` would be
      * registered as `dummy:yo` generator.
+     *
+     * The options are merged over the lookup options the store was created with.
      */
     lookupSync(options) {
-        const { registerToScope, customizeNamespace = (ns) => ns, filter, env, lookups = defaultLookups, ...remainingOptions } = options ?? { localOnly: false };
+        const { registerToScope, customizeNamespace = (ns) => ns, usePackageName, filter, env, lookups = this.lookups, ...remainingOptions } = { ...this.lookupOptions, ...options };
         const lookupOptions = { ...remainingOptions, lookups };
         const generators = [];
         lookupGeneratorsSync(lookupOptions, ({ packagePath, filePath, lookups }) => {
-            let repositoryPath = join(packagePath, '..');
-            if (basename(repositoryPath).startsWith('@')) {
-                // Scoped package
-                repositoryPath = join(repositoryPath, '..');
+            const packageName = usePackageName ? this.getPackageJson(packagePath)?.name : undefined;
+            let namespacePath;
+            if (packageName) {
+                namespacePath = join(packageName, relative(packagePath, filePath));
             }
-            let namespace = customizeNamespace(asNamespace(relative(repositoryPath, filePath), { lookups }));
+            else {
+                let repositoryPath = join(packagePath, '..');
+                if (basename(repositoryPath).startsWith('@')) {
+                    // Scoped package
+                    repositoryPath = join(repositoryPath, '..');
+                }
+                namespacePath = relative(repositoryPath, filePath);
+            }
+            let namespace = customizeNamespace(asNamespace(namespacePath, { lookups }));
             try {
                 const resolved = realpathSync(filePath);
                 if (!namespace) {
@@ -348,14 +414,31 @@ export default class Store {
         }
         return this._packagesJson.get(packagePath);
     }
+    /**
+     * The meta of the store sharing its operations with the given meta, coming from the store it was cloned from or from
+     * one of its clones, or the given meta.
+     */
+    ownMeta(meta) {
+        if (!meta) {
+            return meta;
+        }
+        const own = this._meta[meta.namespace];
+        return own && own !== meta && getOperations(own) === getOperations(meta) ? own : meta;
+    }
     /**
      * The functions of a meta that need an environment, defaulting to the given one.
      */
     bindMetaFunctions(meta, env) {
+        return this.createMetaFunctions(getOperations(meta), () => env);
+    }
+    /**
+     * The functions of a meta, running its operations in the environment passed as `{ env }`, or the default one.
+     */
+    createMetaFunctions(operations, getEnvironment) {
         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 }),
+            importGenerator: (({ env = getEnvironment() } = {}) => operations.importGenerator(env)),
+            instantiate: async (arguments_, options, { env = getEnvironment() } = {}) => operations.instantiate(arguments_, options, env),
+            instantiateHelp: async ({ env = getEnvironment() } = {}) => operations.instantiate([], { help: true }, env),
         };
     }
     getFactory(module) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yeoman-environment",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "Handles the lifecyle and bootstrapping of generators in a specific environment",
   "keywords": [
     "development",