yeoman-environment 4.0.0-alpha.4 → 4.0.0-alpha.6

package/bin/bin.cjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+(async function () {
+  await import('../dist/cli/index.js');
+})();

package/dist/cli/index.d.ts

@@ -1,2 +1 @@
-#!/usr/bin/env node
 export {};

package/dist/cli/index.js

@@ -1,14 +1,17 @@
-#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import process from 'node:process';
-import YeomanCommand from '../util/command.js';
-import packageJson from '../package.json';
-import Env from '../index.js';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YeomanCommand, { addEnvironmentOptions } from '../util/command.js';
+import { createEnv } from '../index.js';
 import { printGroupedGenerator, environmentAction } from './utils.js';
 const program = new YeomanCommand();
+const packageJson = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '../../package.json')).toString());
 program.version(packageJson.version).allowExcessArguments(false).enablePositionalOptions();
-Env.addEnvironmentOptions(program
+addEnvironmentOptions(program
     .command('run <namespace>')
-    .description('Run a generator', { namespace: 'Generator to run' })
+    .description('Run a generator')
+    .argument('<namespace>', 'Generator to run')
     .passThroughOptions()
     .allowUnknownOption()
     .allowExcessArguments(true)
@@ -17,24 +20,24 @@ Env.addEnvironmentOptions(program
 program
     .command('find')
     .description('Find installed generators')
-    .action(() => {
-    const env = Env.createEnv();
-    const generators = env.lookup();
-    printGroupedGenerator(generators, env);
+    .action(async () => {
+    const env = createEnv();
+    const generators = await env.lookup();
+    printGroupedGenerator(generators);
 });
 program
     .command('list')
     .description('List generators available to be used')
-    .action(() => {
-    const env = Env.createEnv();
-    env.lookup();
-    printGroupedGenerator(Object.values(env.getGeneratorsMeta()), env);
+    .action(async () => {
+    const env = createEnv();
+    await env.lookup();
+    printGroupedGenerator(Object.values(env.getGeneratorsMeta()));
 });
 try {
     await program.parseAsync(process.argv);
 }
 catch (error) {
     console.log(error);
+    // eslint-disable-next-line unicorn/no-process-exit
     process.exit(1);
 }
-//# sourceMappingURL=index.js.map

package/dist/cli/utils.js

@@ -1,15 +1,15 @@
+import { requireNamespace } from '@yeoman/namespace';
 import { groupBy } from 'lodash-es';
 import createLogger from 'debug';
-import Environment from '../index.js';
-import { toNamespace } from '../util/namespace.js';
+import { createEnv } from '../index.js';
 const debug = createLogger('yeoman:yoe');
 export const printGroupedGenerator = (generators) => {
     const grouped = groupBy(generators, 'packagePath');
     for (const [packagePath, group] of Object.entries(grouped)) {
-        const namespace = toNamespace(group[0].namespace);
+        const namespace = requireNamespace(group[0].namespace);
         console.log(`  ${namespace.packageNamespace} at ${packagePath}`);
         for (const generator of group) {
-            const generatorNamespace = toNamespace(generator.namespace);
+            const generatorNamespace = requireNamespace(generator.namespace);
             console.log(`    :${generatorNamespace.generator || 'app'}`);
         }
         console.log('');
@@ -27,8 +27,7 @@ export const environmentAction = async function (generatorNamespace, options, co
     if (!generatorNamespace) {
         return;
     }
-    this.env = Environment.createEnv([], { ...options, command: this });
-    this.env.lookupLocalPackages();
+    this.env = createEnv({ ...options, command: this });
+    await this.env.lookupLocalPackages();
     return this.env.execute(generatorNamespace, command.args.splice(1));
 };
-//# sourceMappingURL=utils.js.map

package/dist/commands.d.ts

@@ -0,0 +1,23 @@
+import { type BaseGeneratorConstructor } from '@yeoman/types';
+import YeomanCommand from './util/command.js';
+export type CommandPreparation = {
+    resolved?: string;
+    command?: YeomanCommand;
+    generator?: BaseGeneratorConstructor;
+    namespace?: string;
+};
+/**
+ * Prepare a commander instance for cli support.
+ *
+ * @param {Command} command - Command to be prepared
+ * @param  generatorPath - Generator to create Command
+ * @return {Command} return command
+ */
+export declare const prepareGeneratorCommand: ({ command, resolved, generator, namespace, }: CommandPreparation) => Promise<YeomanCommand>;
+/**
+ * Prepare a commander instance for cli support.
+ *
+ * @param generatorPaht - Generator to create Command
+ * @return Return a Command instance
+ */
+export declare const prepareCommand: (options: CommandPreparation) => Promise<YeomanCommand>;

package/dist/commands.js

@@ -0,0 +1,45 @@
+import YeomanCommand, { addEnvironmentOptions } from './util/command.js';
+import { createEnv } from './index.js';
+/**
+ * Prepare a commander instance for cli support.
+ *
+ * @param {Command} command - Command to be prepared
+ * @param  generatorPath - Generator to create Command
+ * @return {Command} return command
+ */
+export const prepareGeneratorCommand = async ({ command = addEnvironmentOptions(new YeomanCommand()), resolved, generator, namespace, }) => {
+    const env = createEnv();
+    let meta;
+    if (generator && namespace) {
+        meta = env.register(generator, { namespace, resolved });
+    }
+    else if (resolved) {
+        meta = env.register(resolved, { namespace });
+    }
+    else {
+        throw new Error(`A generator with namespace or a generator path is required`);
+    }
+    command.env = env;
+    command.registerGenerator(await meta.instantiateHelp());
+    command.action(async function () {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        let rootCommand = this;
+        while (rootCommand.parent) {
+            rootCommand = rootCommand.parent;
+        }
+        const generator = await meta.instantiate(this.args, this.opts());
+        await env.runGenerator(generator);
+    });
+    return command;
+};
+/**
+ * Prepare a commander instance for cli support.
+ *
+ * @param generatorPaht - Generator to create Command
+ * @return Return a Command instance
+ */
+export const prepareCommand = async (options) => {
+    options.command = options.command ?? new YeomanCommand();
+    addEnvironmentOptions(options.command);
+    return prepareGeneratorCommand(options);
+};

package/dist/commit.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="node" resolution-mode="require"/>
+import type { PassThrough } from 'node:stream';
+import type { InputOutputAdapter } from '@yeoman/types';
+import { type ConflicterOptions } from '@yeoman/conflicter';
+import type { Store } from 'mem-fs';
+import { type MemFsEditorFile } from 'mem-fs-editor';
+/**
+ * Commits the MemFs to the disc.
+ * @param {Stream} [stream] - files stream, defaults to this.sharedFs.stream().
+ * @return {Promise}
+ */
+export declare const commitSharedFsTask: ({ adapter, conflicterOptions, sharedFs, stream, }: {
+    adapter: InputOutputAdapter;
+    conflicterOptions?: ConflicterOptions | undefined;
+    sharedFs: Store<MemFsEditorFile>;
+    stream?: PassThrough | undefined;
+}) => any;

package/dist/commit.js

@@ -0,0 +1,22 @@
+import { createConflicterTransform, createYoResolveTransform, forceYoFiles } from '@yeoman/conflicter';
+import { create as createMemFsEditor } from 'mem-fs-editor';
+// eslint-disable-next-line n/file-extension-in-import
+import { isFilePending } from 'mem-fs-editor/state';
+// eslint-disable-next-line n/file-extension-in-import
+import { createCommitTransform } from 'mem-fs-editor/transform';
+/**
+ * Commits the MemFs to the disc.
+ * @param {Stream} [stream] - files stream, defaults to this.sharedFs.stream().
+ * @return {Promise}
+ */
+export const commitSharedFsTask = ({ adapter, conflicterOptions, sharedFs, stream, }) => {
+    const fs = createMemFsEditor(sharedFs);
+    stream = stream ?? fs.store.stream({ filter: file => isFilePending(file) });
+    return fs.commit([
+        createYoResolveTransform(),
+        forceYoFiles(),
+        createConflicterTransform(adapter, conflicterOptions),
+        // Use custom commit transform due to out of order transform.
+        createCommitTransform(fs),
+    ], stream);
+};

package/dist/composed-store.d.ts

@@ -0,0 +1,26 @@
+import type { Logger, BaseGenerator } from '@yeoman/types';
+export declare class ComposedStore {
+    private readonly log?;
+    private readonly generators;
+    private readonly uniqueByPathMap;
+    private readonly uniqueGloballyMap;
+    private readonly uniqueFeatures;
+    constructor({ log }?: {
+        log?: Logger;
+    });
+    get customCommitTask(): true | (() => Promise<void>) | undefined;
+    get customInstallTask(): true | (() => Promise<void>) | undefined;
+    getGenerators(): Record<string, BaseGenerator>;
+    addGenerator(generator: any): {
+        uniqueBy: any;
+        added: boolean;
+        generator: BaseGenerator | undefined;
+        identifier?: undefined;
+    } | {
+        identifier: any;
+        added: boolean;
+        generator: any;
+        uniqueBy?: undefined;
+    };
+    getUniqueByPathMap(root: string): Map<string, BaseGenerator>;
+}

package/dist/composed-store.js

@@ -0,0 +1,68 @@
+import crypto from 'node:crypto';
+import { toNamespace } from '@yeoman/namespace';
+const uniqueFeatureValues = ['customCommitTask', 'customInstallTask'];
+export class ComposedStore {
+    log;
+    generators = {};
+    uniqueByPathMap = new Map();
+    uniqueGloballyMap = new Map();
+    uniqueFeatures = new Map();
+    constructor({ log } = {}) {
+        this.log = log;
+    }
+    get customCommitTask() {
+        return this.uniqueFeatures.get('customCommitTask');
+    }
+    get customInstallTask() {
+        return this.uniqueFeatures.get('customInstallTask');
+    }
+    getGenerators() {
+        return { ...this.generators };
+    }
+    addGenerator(generator) {
+        const features = generator.getFeatures?.() ?? {};
+        let { uniqueBy } = features;
+        const { uniqueGlobally } = features;
+        let identifier = uniqueBy;
+        if (!uniqueBy) {
+            const { namespace } = generator.options;
+            const instanceId = crypto.randomBytes(20).toString('hex');
+            let namespaceDefinition = toNamespace(namespace);
+            if (namespaceDefinition) {
+                namespaceDefinition = namespaceDefinition.with({ instanceId });
+                uniqueBy = namespaceDefinition.id;
+                identifier = namespaceDefinition.namespace;
+            }
+            else {
+                uniqueBy = `${namespace}#${instanceId}`;
+                identifier = namespace;
+            }
+        }
+        const generatorRoot = generator.destinationRoot();
+        const uniqueByMap = uniqueGlobally ? this.uniqueGloballyMap : this.getUniqueByPathMap(generatorRoot);
+        if (uniqueByMap.has(uniqueBy)) {
+            return { uniqueBy, added: false, generator: uniqueByMap.get(uniqueBy) };
+        }
+        uniqueByMap.set(uniqueBy, generator);
+        for (const featureName of uniqueFeatureValues) {
+            const feature = features[featureName];
+            if (feature) {
+                const existingFeature = this.uniqueFeatures.get(feature);
+                if (typeof existingFeature !== 'function') {
+                    this.uniqueFeatures.set(featureName, feature);
+                }
+                else if (typeof feature === 'function') {
+                    this.log?.info?.(`Multiple ${featureName} tasks found. Using the first.`);
+                }
+            }
+        }
+        this.generators[uniqueGlobally ? uniqueBy : `${generatorRoot}#${uniqueBy}`] = generator;
+        return { identifier, added: true, generator };
+    }
+    getUniqueByPathMap(root) {
+        if (!this.uniqueByPathMap.has(root)) {
+            this.uniqueByPathMap.set(root, new Map());
+        }
+        return this.uniqueByPathMap.get(root);
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const UNKNOWN_NAMESPACE = "unknownnamespace";
+export declare const UNKNOWN_RESOLVED = "unknown";
+export declare const defaultQueues: string[];

package/dist/constants.js

@@ -0,0 +1,17 @@
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const UNKNOWN_NAMESPACE = 'unknownnamespace';
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const UNKNOWN_RESOLVED = 'unknown';
+export const defaultQueues = [
+    'environment:run',
+    'initializing',
+    'prompting',
+    'configuring',
+    'default',
+    'writing',
+    'transform',
+    'conflicts',
+    'environment:conflicts',
+    'install',
+    'end',
+];

package/dist/environment-base.d.ts

@@ -0,0 +1,259 @@
+/// <reference types="node" resolution-mode="require"/>
+/// <reference types="node" resolution-mode="require"/>
+import EventEmitter from 'node:events';
+import { type Transform } from 'node:stream';
+import { QueuedAdapter, type TerminalAdapterOptions } from '@yeoman/adapter';
+import type { ApplyTransformsOptions, BaseEnvironment, BaseEnvironmentOptions, BaseGenerator, BaseGeneratorConstructor, BaseGeneratorMeta, ComposeOptions, GeneratorMeta, GetGeneratorConstructor, InputOutputAdapter, InstantiateOptions, LookupGeneratorMeta } from '@yeoman/types';
+import { type Store as MemFs } from 'mem-fs';
+import { type MemFsEditor, type MemFsEditorFile } from 'mem-fs-editor';
+import { FlyRepository } from 'fly-import';
+import GroupedQueue from 'grouped-queue';
+import { type YeomanNamespace } from '@yeoman/namespace';
+import { type ConflicterOptions } from '@yeoman/conflicter';
+import { ComposedStore } from './composed-store.js';
+import Store from './store.js';
+import type YeomanCommand from './util/command.js';
+import { type LookupOptions } from './generator-lookup.js';
+export type EnvironmentOptions = BaseEnvironmentOptions & Omit<TerminalAdapterOptions, 'promptModule'> & {
+    adapter?: InputOutputAdapter;
+    logCwd?: string;
+    command?: YeomanCommand;
+    yeomanRepository?: string;
+    arboristRegistry?: string;
+    nodePackageManager?: string;
+};
+export default class EnvironmentBase extends EventEmitter implements BaseEnvironment {
+    cwd: string;
+    adapter: QueuedAdapter;
+    sharedFs: MemFs<MemFsEditorFile>;
+    conflicterOptions?: ConflicterOptions;
+    protected logCwd: string;
+    protected readonly options: EnvironmentOptions;
+    protected readonly aliases: Array<{
+        match: RegExp;
+        value: string;
+    }>;
+    protected store: Store;
+    protected command?: YeomanCommand;
+    protected runLoop: GroupedQueue;
+    protected composedStore: ComposedStore;
+    protected fs: MemFsEditor;
+    protected lookups: string[];
+    protected sharedOptions: Record<string, any>;
+    protected repository: FlyRepository;
+    protected experimental: boolean;
+    protected _rootGenerator?: BaseGenerator;
+    protected compatibilityMode?: false | 'v4';
+    constructor(options?: EnvironmentOptions);
+    applyTransforms(transformStreams: Transform[], options?: ApplyTransformsOptions): Promise<void>;
+    /**
+     * Get a single generator from the registered list of generators. The lookup is
+     * based on generator's namespace, "walking up" the namespaces until a matching
+     * is found. Eg. if an `angular:common` namespace is registered, and we try to
+     * get `angular:common:all` then we get `angular:common` as a fallback (unless
+     * an `angular:common:all` generator is registered).
+     *
+     * @param   namespaceOrPath
+     * @return the generator registered under the namespace
+     */
+    get<C extends BaseGeneratorConstructor = BaseGeneratorConstructor>(namespaceOrPath: string | YeomanNamespace): Promise<C | undefined>;
+    /**
+     * Create is the Generator factory. It takes a namespace to lookup and optional
+     * hash of options, that lets you define `arguments` and `options` to
+     * instantiate the generator with.
+     *
+     * An error is raised on invalid namespace.
+     *
+     * @param namespaceOrPath
+     * @param instantiateOptions
+     * @return The instantiated generator
+     */
+    create<G extends BaseGenerator = BaseGenerator>(namespaceOrPath: string | GetGeneratorConstructor<G>, instantiateOptions?: InstantiateOptions<G>): Promise<G>;
+    /**
+     * Instantiate a Generator with metadatas
+     *
+     * @param  generator   Generator class
+     * @param instantiateOptions
+     * @return The instantiated generator
+     */
+    instantiate<G extends BaseGenerator = BaseGenerator>(generator: GetGeneratorConstructor<G>, instantiateOptions?: InstantiateOptions<G>): Promise<G>;
+    /**
+     * @protected
+     * Compose with the generator.
+     *
+     * @param {String} namespaceOrPath
+     * @return {Generator} The instantiated generator or the singleton instance.
+     */
+    composeWith<G extends BaseGenerator = BaseGenerator>(generator: string | GetGeneratorConstructor<G>, composeOptions?: ComposeOptions<G>): Promise<G>;
+    /**
+     * Given a String `filepath`, tries to figure out the relative namespace.
+     *
+     * ### Examples:
+     *
+     *     this.namespace('backbone/all/index.js');
+     *     // => backbone:all
+     *
+     *     this.namespace('generator-backbone/model');
+     *     // => backbone:model
+     *
+     *     this.namespace('backbone.js');
+     *     // => backbone
+     *
+     *     this.namespace('generator-mocha/backbone/model/index.js');
+     *     // => mocha:backbone:model
+     *
+     * @param {String} filepath
+     * @param {Array} lookups paths
+     */
+    namespace(filepath: string, lookups?: string[]): string;
+    /**
+     * Returns the environment or dependency version.
+     * @param  {String} packageName - Module to get version.
+     * @return {String} Environment version.
+     */
+    getVersion(): string;
+    getVersion(dependency: string): string | undefined;
+    /**
+     * Queue generator run (queue itself tasks).
+     *
+     * @param {Generator} generator Generator instance
+     * @param {boolean} [schedule=false] Whether to schedule the generator run.
+     * @return {Generator} The generator or singleton instance.
+     */
+    queueGenerator<G extends BaseGenerator = BaseGenerator>(generator: G, queueOptions?: {
+        schedule?: boolean;
+    }): Promise<G>;
+    /**
+     * Get the first generator that was queued to run in this environment.
+     *
+     * @return {Generator} generator queued to run in this environment.
+     */
+    rootGenerator<G extends BaseGenerator = BaseGenerator>(): G;
+    runGenerator(generator: BaseGenerator): Promise<void>;
+    /**
+     * Start Environment queue
+     * @param {Object} options - Conflicter options.
+     */
+    start(options: any): Promise<void>;
+    /**
+     * Registers a specific `generator` to this environment. This generator is stored under
+     * provided namespace, or a default namespace format if none if available.
+     *
+     * @param  name      - Filepath to the a generator or a npm package name
+     * @param  namespace - Namespace under which register the generator (optional)
+     * @param  packagePath - PackagePath to the generator npm package (optional)
+     * @return environment - This environment
+     */
+    register(filePath: string, meta?: Partial<BaseGeneratorMeta> | undefined): GeneratorMeta;
+    register(generator: unknown, meta: BaseGeneratorMeta): GeneratorMeta;
+    /**
+     * Queue tasks
+     * @param {string} priority
+     * @param {(...args: any[]) => void | Promise<void>} task
+     * @param {{ once?: string, startQueue?: boolean }} [options]
+     */
+    queueTask(priority: string, task: () => void | Promise<void>, options?: {
+        once?: string | undefined;
+        startQueue?: boolean | undefined;
+    } | undefined): void;
+    /**
+     * Add priority
+     * @param {string} priority
+     * @param {string} [before]
+     */
+    addPriority(priority: string, before?: string | undefined): void;
+    /**
+     * Search for generators and their sub generators.
+     *
+     * 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.
+     */
+    lookup(options?: LookupOptions & {
+        registerToScope?: string;
+    }): Promise<LookupGeneratorMeta[]>;
+    /**
+     * Verify if a package namespace already have been registered.
+     *
+     * @param  packageNS - namespace of the package.
+     * @return true if any generator of the package has been registered
+     */
+    isPackageRegistered(packageNamespace: string): boolean;
+    /**
+     * Get all registered packages namespaces.
+     *
+     * @return array of namespaces.
+     */
+    getRegisteredPackages(): string[];
+    /**
+     * Returns stored generators meta
+     * @param namespace
+     */
+    getGeneratorMeta(namespace: string): GeneratorMeta | undefined;
+    /**
+     * Get or create an alias.
+     *
+     * Alias allows the `get()` and `lookup()` methods to search in alternate
+     * filepath for a given namespaces. It's used for example to map `generator-*`
+     * npm package to their namespace equivalent (without the generator- prefix),
+     * or to default a single namespace like `angular` to `angular:app` or
+     * `angular:all`.
+     *
+     * Given a single argument, this method acts as a getter. When both name and
+     * value are provided, acts as a setter and registers that new alias.
+     *
+     * If multiple alias are defined, then the replacement is recursive, replacing
+     * each alias in reverse order.
+     *
+     * An alias can be a single String or a Regular Expression. The finding is done
+     * based on .match().
+     *
+     * @param {String|RegExp} match
+     * @param {String} value
+     *
+     * @example
+     *
+     *     env.alias(/^([a-zA-Z0-9:\*]+)$/, 'generator-$1');
+     *     env.alias(/^([^:]+)$/, '$1:app');
+     *     env.alias(/^([^:]+)$/, '$1:all');
+     *     env.alias('foo');
+     *     // => generator-foo:all
+     */
+    alias(match: string | RegExp, value: string): this;
+    alias(value: string): string;
+    /**
+     * Queue environment's commit task.
+     */
+    protected queueCommit(): void;
+    /**
+     * Queue environment's package manager install task.
+     */
+    protected queuePackageManagerInstall(): void;
+    /**
+     * Registers a specific `generator` to this environment. This generator is stored under
+     * provided namespace, or a default namespace format if none if available.
+     *
+     * @param   name      - Filepath to the a generator or a npm package name
+     * @param   namespace - Namespace under which register the generator (optional)
+     * @param   packagePath - PackagePath to the generator npm package (optional)
+     * @return  environment - This environment
+     */
+    protected registerGeneratorPath(generatorPath: string, namespace?: string, packagePath?: string): GeneratorMeta;
+    /**
+     * Register a stubbed generator to this environment. This method allow to register raw
+     * functions under the provided namespace. `registerStub` will enforce the function passed
+     * to extend the Base generator automatically.
+     *
+     * @param  Generator  - A Generator constructor or a simple function
+     * @param  namespace  - Namespace under which register the generator
+     * @param  resolved - The file path to the generator
+     * @param  packagePath - The generator's package path
+     */
+    protected registerStub(Generator: any, namespace: string, resolved?: string, packagePath?: string): GeneratorMeta;
+}