@conformetry/nx 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,1094 @@
+import { ConfigurationService } from '@conformetry/configuration';
+import { ConformetryGeneratorDefinition } from '@conformetry/configuration';
+import { ConformetryInstanceGroup } from '@conformetry/configuration';
+import { ConsoleLogger } from '@nestjs/common';
+import { CreateNodes } from '@nx/devkit';
+import { FileSystemAdapter } from '@conformetry/generation';
+import { FormatterAdapter } from '@conformetry/generation';
+import { GenerationService } from '@conformetry/generation';
+import { Instance } from '@conformetry/configuration';
+import pino from 'pino';
+import { ReportingService } from '@conformetry/output';
+import { Tree } from '@nx/devkit';
+import { ValidationService } from '@conformetry/validation';
+
+/**
+ * Provides the `Tree`-backed adapters generation writes through.
+ *
+ * Separate from the plugin module so that a host with a different virtual
+ * filesystem can supply its own adapters without rewriting the runner.
+ */
+export declare class AdapterModule {
+}
+
+/**
+ * Backs generation with an Nx `Tree` instead of the filesystem.
+ *
+ * This is what makes `nx g --dry-run` and Nx's change preview work: the
+ * generic generation service writes through whatever adapter it is handed, and
+ * a `Tree` records writes without touching disk until Nx flushes them. Running
+ * the CLI as a subprocess, which is what this package used to do, wrote
+ * straight to disk and made both features lie.
+ */
+export declare class AdapterService {
+    constructor();
+    /**
+     * Lists a directory through the tree when it is inside the workspace, and
+     * through the filesystem otherwise.
+     *
+     * Templates usually live inside the workspace, so reading them through the
+     * tree means a generator run sees edits an earlier generator in the same run
+     * made — which is what a caller expects from a composed generator.
+     */
+    private listDirectory;
+    /** Reads a file through the tree when possible, the filesystem otherwise. */
+    private readFile;
+    /**
+     * Converts an absolute path to the workspace-relative form a `Tree` uses,
+     * or returns `undefined` when the path lies outside the workspace.
+     */
+    private resolveTreePath;
+    /**
+     * Builds the adapters one generator run writes through.
+     *
+     * `makeDirectory` is a no-op because a `Tree` has no directories of its own —
+     * writing `a/b/c.ts` implies them. The formatter defers to Nx so generated
+     * files are formatted by the workspace's own configuration.
+     */
+    createAdapters(args: CreateAdaptersArguments): TreeAdapters;
+}
+
+/**
+ * Emits the generator plugin and puts it where Nx will find it.
+ *
+ * Run from a `postinstall`, which is what makes the emitted plugin a build
+ * artifact rather than a committed one. `GeneratorService.emitPlugin` is called
+ * directly rather than through `nx sync`, which builds the whole project graph
+ * before it emits anything — too slow to pay for on every install, and it would
+ * fail the install itself whenever any project in the workspace momentarily
+ * fails to load.
+ */
+export declare function bootstrapPlugin(workspaceRoot: string): Promise<EmittedFile[]>;
+
+/**
+ * The conformetry configuration as this plugin reads it.
+ *
+ * Authors type their config as this rather than as `ConformetryConfiguration`
+ * to have their instance groups checked against what Nx can actually resolve.
+ */
+export declare type ConformetryNxConfiguration = ConformetryNxGeneratorDefinition[];
+
+/** One generator, whose instance groups this plugin resolves against Nx. */
+export declare interface ConformetryNxGeneratorDefinition extends Omit<ConformetryGeneratorDefinition, "instances"> {
+    instances?: ConformetryNxInstanceGroup[] | undefined;
+}
+
+/**
+ * One instance group, read as either a workspace glob or a project selector.
+ *
+ * The two forms are told apart by `tags`, so a generator says where it belongs
+ * in exactly one place. There is no second field that could disagree with this
+ * one, which is what the single key buys: a separate scope that excluded a
+ * project the globs reached narrowed validation silently, and validation
+ * cannot notice instances it was never offered.
+ */
+export declare type ConformetryNxInstanceGroup = ConformetryNxProjectInstanceGroup | ConformetryNxWorkspaceInstanceGroup;
+
+/** Instances located by project tag, with globs read inside each project. */
+export declare interface ConformetryNxProjectInstanceGroup extends ConformetryInstanceGroup {
+    /**
+     * Globs relative to each matching project's root, or `.` for the project
+     * itself.
+     *
+     * Omitted selects the projects without locating anything in them, which is
+     * what a template with no instances yet wants: `nx g` is still confined to
+     * the projects the template suits.
+     */
+    patterns?: string[] | undefined;
+    /** Nx project tags a project must carry. A project must carry all of them. */
+    tags: string[];
+}
+
+/** Instances located by workspace-relative globs, as any host resolves them. */
+export declare interface ConformetryNxWorkspaceInstanceGroup extends ConformetryInstanceGroup {
+    patterns: string[];
+    /** Absent: this is the form a host with no project graph also uses. */
+    tags?: undefined;
+}
+
+declare const conformetryPlugin: {
+    createNodes: CreateNodes;
+    name: string;
+};
+export default conformetryPlugin;
+
+/** Options accepted from this plugin's `nx.json` registration. */
+export declare interface ConformetryPluginOptions {
+    /** Where the conformetry configuration lives, workspace-root relative. */
+    readonly configurationPath: string;
+    /** Name of the inferred per-project validation target. */
+    readonly validateTargetName: string;
+}
+
+/** Arguments for building the adapters that back one generator run. */
+declare interface CreateAdaptersArguments {
+    readonly tree: Tree;
+    readonly workspaceRoot: string;
+}
+
+/** Arguments for emitting the consumer's generator plugin. */
+declare interface EmitPluginArguments {
+    readonly configurationPath: string;
+    /** Directory the plugin is written to, relative to the workspace root. */
+    readonly outputPath: string;
+    /** Package name the emitted plugin is addressed by, as in `nx g <name>:x`. */
+    readonly packageName: string;
+    /**
+     * The workspace's projects, used to enumerate a scoped generator's choices.
+     *
+     * Passed in rather than read here so emitting stays pure with respect to the
+     * filesystem: the graph, the sync generator, and the install-time bootstrap
+     * each know how to list projects, and they do not agree on how.
+     */
+    readonly projects?: readonly ProjectScope[] | undefined;
+}
+
+/** One file the generator emits, with its workspace-relative path. */
+declare interface EmittedFile {
+    readonly content: string;
+    readonly filePath: string;
+}
+
+/** Arguments for collecting the instances that belong to one project. */
+declare interface FindProjectInstancesArguments {
+    readonly configurationPath: string;
+    readonly project: ProjectScope;
+    readonly workspaceRoot: string;
+}
+
+/**
+ * Derives an Nx generator plugin from the conformetry configuration.
+ *
+ * Nx needs a `generators.json`, a factory function per generator, and a JSON
+ * schema per generator — none of which it will accept as runtime data. The
+ * generators a workspace has are a property of its configuration, so rather
+ * than hand-maintaining three files per generator, they are emitted from the
+ * configuration and kept honest by `nx sync:check`.
+ */
+declare class GeneratorService {
+    private readonly configurationService;
+    private readonly scopeService;
+    constructor(configurationService: ConfigurationService, scopeService: ScopeService);
+    /**
+     * Builds the module Nx calls into for one generator.
+     *
+     * One file per generator, each exporting a single `generate`, because Nx
+     * does not pass a generator its own name — the name has to be bound at the
+     * call site. Binding it per file rather than per export in a shared module
+     * means a generator's factory sits next to the schema of the same name, and
+     * removing a generator removes a file rather than editing one.
+     */
+    private buildGeneratorModule;
+    /**
+     * Builds the `generators.json` Nx reads.
+     *
+     * Schemas are referenced by a path inside the emitted plugin, never one that
+     * escapes it — a schema path pointing outside the package resolves to
+     * nothing once the package is installed somewhere else.
+     */
+    private buildGeneratorsManifest;
+    /**
+     * Builds one generator's JSON schema from its configured inputs.
+     *
+     * Every input is required: a conformetry generator substitutes each of its
+     * placeholders, and mustache renders a missing one as empty rather than
+     * failing, so an optional input would silently produce a hole.
+     */
+    private buildSchema;
+    /**
+     * Builds the schema's properties, narrowing the project input to the scope.
+     *
+     * An `enum` is what makes `nx g` offer only the projects a generator suits,
+     * and what makes it reject one it does not — Nx builds its prompt from the
+     * schema, so constraining the schema constrains the prompt. Left untouched
+     * when the generator names no scope, or when the scope matches nothing: an
+     * empty `enum` would leave the prompt with nothing to pick and read as a
+     * broken generator rather than an unscoped one.
+     */
+    private buildSchemaProperties;
+    /**
+     * The projects a generator's tagged groups admit, or nothing when it has
+     * none.
+     */
+    private resolveScopedProjectNames;
+    /** Serializes emitted JSON the way the workspace formatter would. */
+    private stringify;
+    /**
+     * Returns every file the consumer's generator plugin consists of.
+     *
+     * Pure with respect to the filesystem: the caller writes these through an Nx
+     * `Tree`, which is what lets `nx sync:check` compare them against what is on
+     * disk without touching it.
+     */
+    emitPlugin(args: EmitPluginArguments): Promise<EmittedFile[]>;
+}
+
+/** A target this plugin infers onto a project. */
+declare interface InferredTarget {
+    readonly cache: boolean;
+    readonly executor: string;
+    /** Files whose change must invalidate the cached result. */
+    readonly inputs?: string[];
+    readonly options: Record<string, unknown>;
+}
+
+/** One project's inferred targets, keyed by target name. */
+declare type InferredTargets = Record<string, InferredTarget>;
+
+/** Arguments for inferring targets across every project in a workspace. */
+declare interface InferTargetsArguments {
+    readonly options: unknown;
+    /** Every `project.json` Nx matched, workspace-root relative. */
+    readonly projectConfigurationFiles: readonly string[];
+    readonly workspaceRoot: string;
+}
+
+/**
+ * Provides Nx-aware expansion of the configured instance globs.
+ *
+ * Imports the generic discovery module rather than globbing here, so the
+ * plugin and the CLI resolve instances by exactly the same rules.
+ */
+export declare class InstancesModule {
+}
+
+/**
+ * Turns Nx project knowledge into the instances conformetry validates.
+ *
+ * This is the whole reason the plugin exists: the generic packages take a list
+ * of paths, and deciding which paths belong to which project — and which
+ * projects a configured instance group applies to — is Nx-shaped knowledge
+ * that would otherwise have to live inside them.
+ */
+export declare class InstancesService {
+    private readonly configurationService;
+    private readonly scopeService;
+    constructor(configurationService: ConfigurationService, scopeService: ScopeService);
+    /**
+     * Returns whether an instance belongs to a project.
+     *
+     * Tested against the instance itself — the instance path joined with the
+     * name — not the instance path alone. A project-level instance's path is
+     * the directory *holding* projects, so testing that would place every
+     * project's own instance outside it.
+     */
+    private isInsideProject;
+    /**
+     * Expands every instance group that applies to a project, keeping only the
+     * instances that live inside it.
+     *
+     * The globs stay workspace-relative rather than being rewritten per project:
+     * a pattern such as `packages/*` is the author describing the workspace, and
+     * rewriting it into a project-relative form would change what it means.
+     */
+    findProjectInstances(args: FindProjectInstancesArguments): Promise<Instance[]>;
+}
+
+/**
+ * Structured values that belong beside a log line rather than inside it.
+ *
+ * Counts, percentages, and durations are the values that change on every
+ * occurrence, so they are carried as fields: the message stays constant and
+ * groupable in telemetry, and the numbers stay queryable instead of having to
+ * be parsed back out of prose.
+ *
+ * The named members are the recurring ones; the index signature keeps the
+ * argument open for whatever a given call site needs to attach.
+ */
+declare interface LogData {
+    [key: string]: unknown;
+    /** How many things the operation handled. */
+    count?: number;
+    /** Wall-clock milliseconds the operation took. */
+    durationMs?: number;
+    /** Completion between 0 and 100. */
+    percent?: number;
+    /** How many things the operation set out to handle. */
+    total?: number;
+}
+
+/**
+ * Transient-scoped logger so each injecting class gets its own instance.
+ * Each consumer calls `setContext(ClassName.name)` to tag every log line
+ * with the originating class. Backed by pino for structured JSON output in
+ * production and human-readable pretty-print in development.
+ *
+ * Messages follow one grammar: an emoji naming the subject, a verb in present
+ * progressive or past tense, then the object. Values that vary per call —
+ * counts, percentages, durations — go in the `data` argument rather than the
+ * message, so the message stays constant enough for telemetry to group on.
+ *
+ * ```ts
+ * this.logger.info("📥 Downloading CSEL sources", undefined, { total: 428 });
+ * this.logger.info("📥 Downloaded CSEL sources", undefined, { count: 412 });
+ * ```
+ */
+declare @Injectable({ scope: Scope.TRANSIENT })
+class LoggerService extends ConsoleLogger {
+    // 🏗 Dependency Injection
+
+    constructor() {
+        super();
+    }
+
+    // 🔐 Private Fields
+
+    private static readonly isProduction =
+    process.env["NODE_ENV"] === "production";
+
+    /**
+     * Built on first use, not when this file is evaluated.
+     *
+     * A destination fixed at import time could only ever be chosen by this
+     * package, since every consumer's own code runs after its imports.
+     */
+    private static rootLogger: pino.Logger | undefined;
+
+    /** Whether lines go to standard error instead of standard output. */
+    private static writesToStandardError = false;
+
+    private child: pino.Logger = LoggerService.root;
+
+    // 🔑 Public Fields
+
+    // 🔏 Private Methods
+
+    /** Build the pino instance for production or local development output. */
+    private static createRootLogger(): pino.Logger {
+        const level = process.env["LOG_LEVEL"] ?? "info";
+
+        if (LoggerService.isProduction) {
+            return LoggerService.writesToStandardError
+            ? pino({ level }, pino.destination(STANDARD_ERROR_DESCRIPTOR))
+            : pino({ level });
+        }
+
+        return pino({
+            level,
+            transport: {
+                options: {
+                    colorize: true,
+                    destination: LoggerService.writesToStandardError
+                    ? STANDARD_ERROR_DESCRIPTOR
+                    : STANDARD_OUTPUT_DESCRIPTOR,
+                    // The emoji is a field, not part of the message, so the console can
+                    // show it while telemetry stores unadorned prose. `ignore` then keeps
+                    // it from being printed a second time in the trailing object.
+                    ignore: "pid,hostname,emoji",
+                    messageFormat: "{emoji} {msg}",
+                    singleLine: true,
+                },
+                target: "pino-pretty",
+            },
+        });
+    }
+
+    /**
+     * Sends every subsequent line to standard error instead of standard output.
+     *
+     * For a command-line application whose standard output *is* its result. A log
+     * line sharing that stream is not a diagnostic beside the data, it is a
+     * corruption of it. Call it before anything logs — the first statement of the
+     * application's bootstrap.
+     *
+     * A call after the first line warns and changes nothing: the destination is
+     * fixed when the pino instance is built, and tearing down a transport
+     * somebody is writing through would be worse than refusing. The warning is
+     * the point — silently leaving the lines on standard output is how a caller
+     * would ship a corrupted pipe without ever being told.
+     */
+    static logToStandardError(): void {
+        if (LoggerService.rootLogger !== undefined) {
+            process.emitWarning(
+            "LoggerService.logToStandardError() was called after the first log line, so log lines still go to standard output and anything piping that stream will read them as data. Call it as the first statement of the application's bootstrap.",
+            );
+            return;
+        }
+
+        LoggerService.writesToStandardError = true;
+    }
+
+    /**
+     * Fails a malformed message in development, and never in production.
+     *
+     * A logger that throws in production turns an observability call into an
+     * outage, so the check runs only where a developer is present to fix it.
+     */
+    private assertConventionalMessage(args: {
+        context: string | undefined;
+        parsed: ParsedLogMessage;
+    }): void {
+        if (
+        LoggerService.isProduction ||
+        this.shouldSkipConventionalMessageValidation(args.context)
+        ) {
+            return;
+        }
+
+        const violation = this.getConventionalMessageViolation(args.parsed);
+
+        if (violation !== undefined) {
+            throw new Error(violation);
+        }
+    }
+
+    /** Assembles the object pino merges into the line. */
+    private buildBindings(args: {
+        context: string | undefined;
+        data: LogData | undefined;
+        parsed: ParsedLogMessage;
+    }): Record<string, unknown> {
+        this.assertConventionalMessage({
+            context: args.context,
+            parsed: args.parsed,
+        });
+
+        return {
+            ...args.data,
+            context: args.context,
+            // Telemetry gets prose; only the console-bound transport reads this.
+            ...(LoggerService.isProduction ? {} : { emoji: args.parsed.emoji }),
+        };
+    }
+
+    /** Returns a human-readable explanation when the message format is invalid. */
+    private getConventionalMessageViolation(
+    parsed: ParsedLogMessage,
+    ): string | undefined {
+        const emoji = parsed.emoji;
+        const text = parsed.text;
+
+        if (emoji === undefined) {
+            return `Log message must start with an emoji naming its subject, then a verb: "${text}"`;
+        }
+
+        const firstWord = FIRST_WORD_PATTERN.exec(text)?.[1];
+
+        if (firstWord === undefined || !this.isConventionalVerb(firstWord)) {
+            return `Log message must begin with a verb in present progressive or past tense, got "${firstWord ?? ""}": "${emoji} ${text}"`;
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Whether a word is a verb in one of the two tenses the convention allows.
+     *
+     * Present progressive means the operation is under way; past means it
+     * finished. Regular morphology covers both, so a new verb needs no
+     * registration anywhere — only irregular pasts are enumerated.
+     */
+    private isConventionalVerb(word: string): boolean {
+        const lowercased = word.toLowerCase();
+
+        return (
+        lowercased.endsWith("ing") ||
+        lowercased.endsWith("ed") ||
+        IRREGULAR_PAST_VERBS.has(lowercased)
+        );
+    }
+
+    /** Splits a leading emoji off a message, leaving prose behind. */
+    private parseMessage(message: unknown): ParsedLogMessage {
+        const text = String(message);
+        const match = LEADING_EMOJI_PATTERN.exec(text);
+        const emoji = match?.[1];
+
+        return emoji === undefined
+        ? { emoji: undefined, text }
+        : { emoji, text: text.slice(match?.[0].length) };
+    }
+
+    /** Whether a context is intentionally exempt from the validation rule. */
+    private shouldSkipConventionalMessageValidation(
+    context: string | undefined,
+    ): boolean {
+        return context !== undefined && UNVALIDATED_LOG_CONTEXTS.has(context);
+    }
+
+    // 🌎 Public Methods
+
+    /** The pino instance every logger's child is taken from. */
+    private static get root(): pino.Logger {
+        LoggerService.rootLogger ??= LoggerService.createRootLogger();
+
+        return LoggerService.rootLogger;
+    }
+
+    /** Normalizes unknown errors into a stable message and timestamped log line. */
+    buildErrorLogEntry(
+    context: string,
+    error: unknown,
+    ): { errorMessage: string; logLine: string } {
+        const errorMessage =
+        error instanceof Error ? error.stack || error.message : String(error);
+
+        return {
+            errorMessage,
+            logLine: `[${new Date().toISOString()}] ${context}: ${errorMessage}\n`,
+        };
+    }
+
+    /** Builds a timestamped output log file path and ensures the output directory exists. */
+    createTimestampedOutputLogFilePath(filePrefix: string): string {
+        const outputDirectory = path.join(process.cwd(), "output");
+        if (!existsSync(outputDirectory)) {
+            mkdirSync(outputDirectory, { recursive: true });
+        }
+
+        return path.join(
+        outputDirectory,
+        `${filePrefix}-${new Date().toISOString().replaceAll(/[:.]/g, "-")}.log`,
+        );
+    }
+
+    /** Logs a debug message at the `debug` level. */
+    override debug(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.debug(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+
+    /**
+     * Logs an error message at the `error` level, optionally including a stack trace.
+     *
+     * `ConsoleLogger.error` spends a third slot on a context string that the
+     * other levels do not have, so this one accepts either: a string keeps
+     * NestJS's meaning, an object is structured data like everywhere else.
+     */
+    override error(
+    message: unknown,
+    stackOrContext?: string,
+    contextOrData?: LogData | string,
+    ): void {
+        const parsed = this.parseMessage(message);
+        const data = typeof contextOrData === "object" ? contextOrData : undefined;
+        const context =
+        typeof contextOrData === "string" ? contextOrData : this.context;
+
+        this.child.error(
+            {
+            ...this.buildBindings({ context, data, parsed }),
+            stack: stackOrContext,
+        },
+        parsed.text,
+        );
+    }
+
+    /** Logs an informational message at the `info` level. */
+    info(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.info(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+
+    /**
+     * Logs an informational message at the `info` level.
+     *
+     * NestJS and `nest-commander` call this method directly as part of the
+     * framework's own `LoggerService` contract, so it must keep working
+     * exactly as before. Application code should call `info` instead — the
+     * same behavior under a name that says what level it logs at.
+     */
+    override log(message: unknown, context?: string, data?: LogData): void {
+        this.info(message, context, data);
+    }
+
+    /** Sets the context label included in every subsequent log line. */
+    override setContext(context: string): void {
+        super.setContext(context);
+        this.child = LoggerService.root.child({ context });
+    }
+
+    /** Logs a verbose message at the `trace` level. */
+    override verbose(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.trace(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+
+    /** Logs a warning message at the `warn` level. */
+    override warn(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.warn(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+}
+
+/**
+ * Root module of the plugin's application context.
+ *
+ * Built once per process and cached — the Nx daemon is long-lived, so paying
+ * for a NestJS context on every generator invocation would make the plugin the
+ * slowest thing in the graph.
+ */
+export declare class MainModule {
+}
+
+/**
+ * Provides resolution of the options Nx passes this plugin.
+ *
+ * Kept apart from the modules that consume them so that adding an option
+ * touches one service rather than every call site that reads `nx.json`.
+ */
+export declare class OptionsModule {
+}
+
+/**
+ * Narrows the untyped options object Nx hands a plugin.
+ *
+ * Nx passes whatever the consumer wrote in `nx.json` with no validation, so
+ * every field is checked before use rather than cast. A bad value falls back
+ * to its default: a typo in a target name should not stop the project graph
+ * from being built.
+ */
+export declare class OptionsService {
+    constructor();
+    /** Narrows an untrusted value to an array without widening it to `any`. */
+    private isUnknownArray;
+    /** Reads this plugin's `configurationPath` out of an `nx.json`, if it names one. */
+    private readRegisteredConfigurationPath;
+    /** Reads a string field from an untrusted record, or `undefined`. */
+    private readString;
+    /**
+     * Resolves the configuration path a workspace means, without assuming one.
+     *
+     * Nx passes plugin options to `createNodes` and to executors, but not to a
+     * global sync generator or to anything run outside Nx entirely, such as the
+     * install-time bootstrap. Those read the registration themselves rather than
+     * assuming a path, so a workspace that keeps its configuration somewhere
+     * other than the root is not silently read from nothing.
+     *
+     * With no registration, the conventional root filenames are tried in order.
+     * `exists` is supplied by the caller rather than reached for here, because
+     * the callers do not agree on what a filesystem is: two of them read disk
+     * and the sync generator reads an Nx `Tree`.
+     */
+    resolveConfigurationPath(args: {
+        exists: (candidatePath: string) => boolean;
+        nxConfiguration: unknown;
+    }): string;
+    /**
+     * Extracts the generator inputs from an Nx options object.
+     *
+     * Nx hands a generator every option the consumer passed, including the ones
+     * that configure this plugin rather than the generator. Those are dropped so
+     * a template placeholder is never accidentally filled with a config path,
+     * and non-string values are dropped because substitutions are text.
+     */
+    resolveGeneratorInputs(options: unknown): Record<string, string | undefined>;
+    /**
+     * Resolves the effective plugin options from an untrusted value.
+     *
+     * Falls back to the most conventional configuration filename rather than
+     * discovering which one is present, which needs a filesystem; callers that
+     * have one resolve the path with `resolveConfigurationPath` first and pass
+     * the result in.
+     */
+    resolvePluginOptions(options: unknown): ConformetryPluginOptions;
+}
+
+/** A message split into the emoji the console shows and the prose telemetry stores. */
+declare interface ParsedLogMessage {
+    emoji: string | undefined;
+    text: string;
+}
+
+/**
+ * Decides where a generator writes, by reading the workspace it writes into.
+ *
+ * `conformetry-generation` takes a destination and renders into it; it has no
+ * opinion about layout, exactly as `conformetry-validation` takes instances
+ * and has no opinion about how they were found. Layout is Nx-shaped knowledge,
+ * so it is answered here — and answered by looking at the projects and module
+ * folders that already exist, rather than by a configured convention that
+ * would go stale the moment one project deviated.
+ */
+declare class PathsService {
+    private readonly instancesService;
+    private readonly configurationService;
+    private readonly scopeService;
+    constructor(instancesService: InstancesService, configurationService: ConfigurationService, scopeService: ScopeService);
+    /**
+     * Locates a named module, refusing one the project does not have.
+     *
+     * Naming a module means writing into one that exists. Placing the files at a
+     * made-up path instead scattered a stray directory across the project root
+     * and reported success, which reads as the generator having worked.
+     */
+    private requireModulePath;
+    /**
+     * Infers where a project keeps its modules, from where its modules already
+     * are.
+     *
+     * The directory holding the most of them wins, which is what makes this
+     * robust: one stray directory alongside `src/modules` does not move new
+     * modules next to it. Returns `undefined` for a project with no modules yet,
+     * because there is then nothing to infer from and guessing a convention is
+     * how a generic package acquires one repository's layout.
+     */
+    private resolveModuleParentPath;
+    /**
+     * Finds the directory holding an existing module of the given name.
+     *
+     * Used when a generator adds files to a module rather than creating one —
+     * `nestjs-service-file` writes a service into a module that already exists,
+     * so the module has to be located rather than placed.
+     */
+    private resolveModulePath;
+    /**
+     * Places a project that does not exist yet, which is why no project lookup
+     * can answer this. An unrecognized type is used verbatim, so the first
+     * project of a new type still lands somewhere sensible.
+     */
+    private resolveNewProjectPath;
+    /**
+     * The folder a generator's scope places new instances in, if it names one.
+     *
+     * Preferred over inferring from existing instances, because a scope is the
+     * author stating where instances belong — inference only guesses it, and
+     * guesses nothing at all in a project that has none yet.
+     */
+    private resolveScopedDirectory;
+    /**
+     * Infers the workspace directory a new project of a given type belongs in,
+     * from where projects of that type already live.
+     *
+     * `type: "packages"` resolves to whichever directory actually holds the
+     * workspace's packages, so the answer stays right in a workspace that calls
+     * it something else.
+     */
+    private resolveTypeDirectoryPath;
+    /**
+     * Resolves the absolute directory a generator's template tree is laid over.
+     *
+     * This is the *parent* of anything the template creates, because a template
+     * that produces a folder contains that folder. Falls back to the workspace
+     * root when the inputs name nothing to locate.
+     */
+    resolveGenerationPath(args: ResolveGenerationPathArguments): Promise<string>;
+}
+
+/**
+ * Wires the generic conformetry packages into one Nx-facing service.
+ *
+ * The plugin owns no generation or validation logic of its own; it supplies
+ * the Nx-shaped inputs — project roots, tags, a `Tree` — that the generic
+ * packages cannot know about.
+ */
+export declare class PluginModule {
+}
+
+/**
+ * The plugin's whole surface: infer targets, generate, validate.
+ *
+ * Every entry point resolves the plugin's options and the conformetry
+ * configuration itself rather than taking them apart, so the Nx-facing
+ * functions in `index.ts` stay thin wrappers with no logic of their own.
+ */
+export declare class PluginService {
+    private readonly adapterService;
+    private readonly instancesService;
+    private readonly configurationService;
+    private readonly generatorService;
+    private readonly generationService;
+    private readonly optionsService;
+    private readonly pathsService;
+    private readonly projectsService;
+    private readonly reportingService;
+    private readonly validationService;
+    private readonly logger;
+    constructor(adapterService: AdapterService, instancesService: InstancesService, configurationService: ConfigurationService, generatorService: GeneratorService, generationService: GenerationService, optionsService: OptionsService, pathsService: PathsService, projectsService: ProjectsService, reportingService: ReportingService, validationService: ValidationService, logger: LoggerService);
+    /**
+     * Fails when the emitted Nx plugin no longer matches the configuration.
+     *
+     * `generators.json` and its schemas are derived from `conformetry.config.ts`,
+     * so an edit to the configuration that is not followed by `nx sync` leaves Nx
+     * offering generators that no longer exist, or hiding ones that do. Comparing
+     * here rather than trusting `nx sync:check` means the plugin's own commands
+     * cannot run against a stale plugin.
+     */
+    private assertEmittedPluginCurrent;
+    /** Fails fast when the plugin would run against a stale or broken setup. */
+    private assertPluginInSync;
+    /**
+     * Fails when a configured generator points at a template that is not there.
+     *
+     * Template contents never reach `generators.json`, so a missing template
+     * directory is invisible to the drift check above: the emitted plugin still
+     * matches the configuration, and the failure only surfaces later as an empty
+     * generation or an instance matching nothing.
+     */
+    private assertTemplatesExist;
+    /** Reads the workspace's `nx.json`, or nothing when there is none. */
+    private readNxConfiguration;
+    /**
+     * Resolves this plugin's options against the workspace's registration.
+     *
+     * Nx passes plugin options to `createNodes` but not to a generator or to an
+     * inferred target's executor, which see only what the caller typed. Reading
+     * `nx.json` here rather than trusting a default is what lets a workspace keep
+     * its configuration somewhere other than the conventional path: the
+     * registration is the base, and anything Nx did pass wins over it.
+     */
+    private resolveOptions;
+    /**
+     * Builds one input glob per configured generator's template folder.
+     *
+     * A template's own files are not part of `configurationPath` or the emitted
+     * plugin, so without this an instance's validate target would keep a stale
+     * cache hit across an edit to the very template it is measured against —
+     * which is exactly how a broken template placeholder once reached every
+     * matched instance's `package.json` unnoticed.
+     */
+    private resolveTemplateInputs;
+    /** Reads every configured generator's template folder. */
+    private resolveTemplates;
+    /**
+     * Infers a validation target onto every project that holds at least one
+     * instance.
+     *
+     * Projects with nothing to validate get no target at all, rather than a
+     * target that trivially passes — an empty target still costs a task in every
+     * `run-many`, and it makes `nx show project` claim a capability the project
+     * does not have.
+     */
+    inferTargets(args: InferTargetsArguments): Promise<Map<string, InferredTargets>>;
+    /**
+     * Runs one configured generator against an Nx tree.
+     *
+     * Nothing is written to disk here — the tree records the writes and Nx
+     * decides whether to flush them, which is what makes `--dry-run` honest.
+     */
+    runGenerator(args: RunGeneratorArguments): Promise<string[]>;
+    /** Validates one project's instances and renders the report. */
+    runValidation(args: RunValidationArguments): Promise<RunValidationResult>;
+}
+
+/** One Nx project, reduced to what instance scoping needs. */
+export declare interface ProjectScope {
+    readonly name: string;
+    /** Project root, relative to the workspace root. */
+    readonly root: string;
+    readonly tags: string[];
+}
+
+/**
+ * Reads the workspace's projects straight from their `project.json` files.
+ *
+ * Not from the project graph, because two of the callers have none: inferring
+ * targets is part of *building* that graph, and the install-time bootstrap
+ * runs with no Nx at all. One implementation shared by every caller is what
+ * keeps the emitted plugin byte-identical however it was produced — the drift
+ * check compares those bytes, and would fire on any disagreement.
+ */
+declare class ProjectsService {
+    constructor();
+    /** Narrows an untrusted value to an array without widening it to `any`. */
+    private isUnknownArray;
+    /**
+     * Walks a directory for `project.json` files.
+     *
+     * Hidden directories and dependencies are skipped: the emitted plugin lives
+     * in one of the former, and walking the latter would take longer than every
+     * other part of an emit put together.
+     */
+    private listProjectConfigurationFiles;
+    /**
+     * Reads the paths `.nxignore` excludes from project discovery.
+     *
+     * Honored because a `project.json` inside a generator template is not a
+     * project — it is a file the template will one day render — and `.nxignore`
+     * is where a workspace already says so. Reading it keeps this walk agreeing
+     * with the graph Nx itself builds.
+     */
+    private readIgnoredPaths;
+    /**
+     * Every project in the workspace, as a scope a generator can be matched to.
+     *
+     * Sorted by name so that anything derived from this list — the choices an
+     * emitted schema offers, above all — is stable between runs.
+     */
+    listWorkspaceProjects(workspaceRoot: string): ProjectScope[];
+    /** Reads one project's name, root, and tags from its `project.json`. */
+    readProjectScope(args: ReadProjectScopeArguments): ProjectScope;
+}
+
+/** Arguments for reading one project's configuration. */
+declare interface ReadProjectScopeArguments {
+    readonly projectConfigurationFile: string;
+    readonly workspaceRoot: string;
+}
+
+/** Arguments for deciding where a generator writes. */
+declare interface ResolveGenerationPathArguments {
+    readonly configurationPath: string;
+    /**
+     * The generator being run, used to find the scope it is confined to.
+     *
+     * Optional so a caller with no generator in hand — anything resolving a path
+     * outside a generator run — still gets the inferred layout.
+     */
+    readonly generatorName?: string | undefined;
+    /** The generator's own inputs, such as `project`, `module`, and `name`. */
+    readonly inputs: Record<string, string | undefined>;
+    readonly tree: Tree;
+    readonly workspaceRoot: string;
+}
+
+/** Resolves the service backing target inference, generation, and validation. */
+export declare function resolvePluginService(): Promise<PluginService>;
+
+/**
+ * Bootstraps the plugin, warning rather than failing the install.
+ *
+ * A `postinstall` that exits non-zero fails `pnpm install` itself, which would
+ * leave an unrelated dependency change uninstallable for as long as the
+ * conformetry configuration is mid-edit. Nothing is lost by warning: every
+ * conformetry command re-checks the emitted plugin against the configuration
+ * and refuses to run against a stale one.
+ */
+export declare function runBootstrapCli(workspaceRoot: string): Promise<void>;
+
+/**
+ * Runs one configured generator against an Nx tree.
+ *
+ * This is the machinery a consumer's generated generator wrappers call. The
+ * published package deliberately declares no generators of its own: which
+ * generators exist is a property of the consumer's configuration, not of this
+ * package, so `nx g @conformetry/nx:anything` resolves nothing by
+ * design.
+ */
+export declare function runConformetryGenerator(args: {
+    generatorName: string;
+    options?: Record<string, unknown>;
+    tree: Tree;
+}): Promise<string[]>;
+
+/** Arguments for running one generator against an Nx tree. */
+declare interface RunGeneratorArguments {
+    readonly generatorName: string;
+    readonly options: Record<string, unknown>;
+    readonly tree: Tree;
+    readonly workspaceRoot: string;
+}
+
+/** Arguments for validating one project. */
+declare interface RunValidationArguments {
+    readonly languageNames?: string[];
+    readonly options: unknown;
+    readonly project: ProjectScope;
+    /** Run-level conformance floor; the weakest of the three threshold levels. */
+    readonly threshold?: number;
+    readonly workspaceRoot: string;
+}
+
+/** The outcome of validating one project. */
+declare interface RunValidationResult {
+    readonly ok: boolean;
+    readonly report: string;
+}
+
+/**
+ * Provides the reading and matching of a generator's project scope.
+ *
+ * Depends only on the dependency-free `ConfigurationModule`, for the one rule
+ * that says whether a group is project-scoped at all: a scope is otherwise
+ * answered from the configuration and a list of projects the caller already
+ * has, so this stays usable from the graph, from a generator, and from the
+ * install-time bootstrap alike.
+ */
+export declare class ScopeModule {
+}
+
+/**
+ * Reads an instance group as Nx resolves it.
+ *
+ * A group carrying `tags` selects projects and reads its globs inside each
+ * one; a group without them is a workspace glob, which is what a host with no
+ * project graph writes. Telling the two apart by a field the group already has
+ * is what keeps a generator's location stated once — nothing else can
+ * contradict it, and so nothing can silently narrow it.
+ *
+ * Which of the two a group is, is the configuration layer's to say. The groups
+ * this plugin claims and the ones `@conformetry/configuration` reads on its own
+ * must be exact complements, and nothing fails if they are not — a group both
+ * hosts skipped is simply never validated. One rule, read from one place, is
+ * what rules that out.
+ */
+export declare class ScopeService {
+    private readonly configurationService;
+    constructor(configurationService: ConfigurationService);
+    /** Whether a group locates its instances by project tag. */
+    private isProjectGroup;
+    /**
+     * Returns whether a group applies to a project.
+     *
+     * A group with no tags applies everywhere — tags narrow a group, they do not
+     * opt it in, so a configuration that never mentions them still reaches every
+     * project. A project must carry every tag the group names, so a second tag
+     * narrows the group further rather than widening it.
+     */
+    matchesProject(args: {
+        group: ConformetryInstanceGroup;
+        project: ProjectScope;
+    }): boolean;
+    /**
+     * Resolves one group against a project, into workspace-relative globs.
+     *
+     * A tagged group's globs are read inside the project, so `src/modules/*`
+     * means the same thing in every project it selects. An untagged group is
+     * returned as written, which is how a host with no projects resolves it.
+     * Either way the result is indistinguishable downstream from a hand-written
+     * glob — discovery, validation, and layout inference need know nothing.
+     */
+    resolveGroup(args: {
+        group: ConformetryInstanceGroup;
+        project: ProjectScope;
+    }): ConformetryInstanceGroup[];
+    /**
+     * The folder a group's first glob points at, with any wildcard trimmed off.
+     *
+     * `src/modules/*` places a new module in `src/modules`; a glob that starts
+     * with a wildcard places nothing, and layout falls back to being inferred.
+     */
+    resolveScopedDirectory(groups: ConformetryInstanceGroup[]): string | undefined;
+    /**
+     * The projects a generator's groups admit, by name and sorted.
+     *
+     * Sorted because the emitted schema is compared byte for byte by the drift
+     * check, and an unstable order would report drift on every re-emit. A
+     * generator with no tagged group admits nothing here, which the caller reads
+     * as "do not constrain the prompt at all".
+     */
+    resolveScopedProjectNames(args: {
+        groups: ConformetryInstanceGroup[];
+        projects: ProjectScope[];
+    }): string[];
+}
+
+/** The filesystem and formatter adapters one generator run writes through. */
+declare interface TreeAdapters {
+    readonly filesystem: FileSystemAdapter;
+    readonly formatter: FormatterAdapter;
+}
+
+export { }