@conformetry/configuration 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,1034 @@
+import { InventoriedInstance } from '@conformetry/core';
+import { InventoriedPairing } from '@conformetry/core';
+import { InventoriedTemplate } from '@conformetry/core';
+import { PreparedValidationDocument } from '@conformetry/core';
+
+/**
+ * How a caller says "every template" to `validate --templates`.
+ *
+ * A sentinel rather than a second flag, because supplying a value is how this
+ * command line opts out of being prompted: omitting `--templates` in a
+ * terminal asks, and passing `all` decides without narrowing. It lives beside
+ * the other command-line vocabulary because that is what it is — the word a
+ * caller types — and `assertNoCollisions` reads it from here so a template can
+ * never be named the same thing.
+ */
+export declare const ALL_TEMPLATES_SELECTION = "all";
+
+/**
+ * Provides the configuration layer's one public service.
+ *
+ * The five modules above supply the collaborators `ConfigurationService` is
+ * assembled from, and none of them is re-exported: a consumer outside this
+ * package injects `ConfigurationService` and nothing else, which is what makes
+ * this layer one entry point rather than a bag of services a caller has to
+ * know the names of. The three sibling ic-suite toolchains publish exactly
+ * this pair, and conformetry now reads as the same shape.
+ */
+export declare class ConfigurationModule {
+}
+
+/**
+ * The one answer to "what is this run actually configured to do".
+ *
+ * Every question a caller outside this package can ask about configuration is
+ * asked here: what a config file declares, which templates it points at, which
+ * instances exist and what explains them, what a placeholder renders to, and
+ * what to ask a person for when an input was left off. A consumer therefore
+ * injects this and nothing else from this package, which is what makes the
+ * configuration layer one layer rather than a bag of collaborators a caller
+ * has to know the names of — the shape callidescope, codependix and codometer
+ * already publish.
+ *
+ * Loading a config file is the one job held here rather than delegated;
+ * everything below it is a one-line hand-off. Prompting, option parsing,
+ * rendering, template discovery, instance discovery and instance-group reading
+ * stay six classes in their own files, because they are six different jobs.
+ * What they stop being is six public entry points.
+ */
+export declare class ConfigurationService {
+    private readonly inputPromptingService;
+    private readonly inputService;
+    private readonly instanceDiscoveryService;
+    private readonly instanceGroupService;
+    private readonly renderingService;
+    private readonly templateDiscoveryService;
+    constructor(inputPromptingService: InputPromptingService, inputService: InputService, instanceDiscoveryService: InstanceDiscoveryService, instanceGroupService: InstanceGroupService, renderingService: RenderingService, templateDiscoveryService: TemplateDiscoveryService);
+    /**
+     * Fills in the optional halves of one parsed generator entry.
+     *
+     * A generator with no inputs and no instances is legal — it renders a fixed
+     * template nobody validates — so both default to empty rather than failing.
+     */
+    private applyGeneratorDefaults;
+    /**
+     * Walks upward from the process cwd looking for the workspace manifest.
+     *
+     * Used to resolve a config path given relative to the workspace root even
+     * when the command was invoked from a nested directory.
+     */
+    private findWorkspaceRoot;
+    /** Loads a config module, choosing the reader by extension. */
+    private loadConfigurationModule;
+    /** Reads a JSON or JSONC config file. */
+    private loadJsonConfiguration;
+    /**
+     * Resolves a config path against the cwd, falling back to the workspace root.
+     */
+    private resolveConfigurationPath;
+    /** Derives the case variants every template can reference from one name. */
+    buildNameSubstitutions(name: string): Substitutions;
+    /** Reads one template folder. */
+    collectTemplate(args: Parameters<TemplateDiscoveryService["collectTemplate"]>[0]): TemplateDefinition;
+    /** Reads every configured generator's template folder. */
+    collectTemplates(args: {
+        configuration: ConformetryConfiguration;
+        workingDirectory: string;
+    }): TemplateDefinition[];
+    /** Expands instance globs into the instances that exist. */
+    findInstances(args: FindInstancesArguments): Instance[];
+    /** Whether anybody is there to answer a question. */
+    isAtTerminal(): boolean;
+    /** Whether a group locates its instances inside the hosts its tags select. */
+    isProjectScoped(group: ConformetryInstanceGroup): boolean;
+    /**
+     * Loads, validates, and normalizes a conformetry configuration file.
+     *
+     * Throws `UnknownConfigurationFileTypeError` for an unreadable extension, and
+     * propagates the Zod error for a malformed registry — a bad config should
+     * fail loudly rather than silently validate nothing.
+     */
+    loadConformetryConfiguration(configurationPath: string): Promise<ConformetryConfiguration>;
+    /** Resolves every instance to the template, or templates, that explain it. */
+    matchInstances(args: {
+        instances: Instance[];
+        templates: TemplateDefinition[];
+    }): ResolvedInstances;
+    /** Splits a comma-delimited filter option into its values. */
+    parseCommaDelimitedOption(value: string | undefined): string[] | undefined;
+    /** Trims an optional string option, treating blank as absent. */
+    parseOptionalOption(value: string | undefined): string | undefined;
+    /** Parses a threshold option as a ratio from 0 to 1. */
+    parseThresholdOption(value: string | undefined): number | undefined;
+    /**
+     * Prepares the rendered template and instance document pairs for each matched
+     * instance, restricted to the extensions the caller's languages claim.
+     */
+    prepareDocuments(args: PrepareDocumentsArguments): PreparedInstanceDocuments[];
+    /** Asks which single template to run, filtering as the caller types. */
+    promptForTemplate(templates: Parameters<InputPromptingService["promptForTemplate"]>[0]): Promise<string | undefined>;
+    /** Asks which templates to narrow a run to. */
+    promptForTemplates(templates: Parameters<InputPromptingService["promptForTemplates"]>[0]): Promise<string[] | undefined>;
+    /** Keeps the groups a host with no project graph can actually locate. */
+    readWorkspaceGroups(groups: readonly ConformetryInstanceGroup[]): ConformetryInstanceGroup[];
+    /** Renders template contents with mustache. */
+    renderContent(args: Parameters<RenderingService["renderContent"]>[0]): string;
+    /** Renders a template path with mustache. */
+    renderPath(args: Parameters<RenderingService["renderPath"]>[0]): string;
+    /** Resolves generator inputs from raw command-line arguments. */
+    resolveGeneratorInputs(args: ResolveGeneratorInputsArguments): Promise<Record<string, string>>;
+    /** Lists every file a matched instance's template requires it to have. */
+    resolveInstanceFiles(instances: MatchedInstance[]): InstanceFile[];
+    /** Lists every instance found, paired with the templates that explain it. */
+    resolveInventoriedInstances(args: ResolveInventoryArguments): ReturnType<InstanceDiscoveryService["resolveInventoriedInstances"]>;
+    /** Lists every template declared, paired with the instances it explains. */
+    resolveInventoriedTemplates(args: ResolveInventoryArguments): ReturnType<InstanceDiscoveryService["resolveInventoriedTemplates"]>;
+}
+
+/**
+ * The loaded configuration: one entry per generator.
+ *
+ * An array rather than a keyed record because a generator's name is already a
+ * field, and a record made the name true in two places at once.
+ */
+export declare type ConformetryConfiguration = ConformetryGeneratorDefinition[];
+
+/** One generator, with the template it renders and the instances it governs. */
+export declare interface ConformetryGeneratorDefinition {
+    description?: string;
+    /**
+     * The values this generator substitutes, as JSON Schema fragments. Named for
+     * what the implementation calls them everywhere else — a generator takes
+     * inputs and renders a template with them.
+     */
+    inputs: Record<string, ConformetryGeneratorInputDefinition>;
+    /**
+     * Where this generator's output already lives in the workspace. Validation
+     * expands these to find what to check; generation reads them to learn where
+     * a new instance belongs.
+     */
+    instances: ConformetryInstanceGroup[];
+    name: string;
+    /** The template folder, relative to the workspace root. */
+    templatePath: string;
+    /**
+     * Lowest conformance score, from 0 to 1, an instance of this template may
+     * have and still pass.
+     *
+     * Left undefined when unset rather than defaulted to 1, so a run-level
+     * `--threshold` still has somewhere to apply. The default is reached only
+     * when no level supplies a value.
+     */
+    threshold?: number;
+}
+
+/** One configurable input, expressed as a JSON Schema fragment. */
+export declare type ConformetryGeneratorInputDefinition = Record<string, unknown>;
+
+/**
+ * One set of instance globs and the substitutions their template renders with.
+ *
+ * Directory and file patterns behave differently on purpose — see
+ * `Instance.path`.
+ */
+export declare interface ConformetryInstanceGroup {
+    /**
+     * Globs locating this group's instances.
+     *
+     * Workspace-relative on their own. A host that resolves `tags` may instead
+     * read them relative to each labelled host it selects — see
+     * `ConformetryNxInstanceGroup` in `@conformetry/nx` — which is why a group
+     * naming only tags is legal: it selects without locating.
+     */
+    patterns?: string[] | undefined;
+    /**
+     * Values every placeholder this generator's template uses must be given.
+     * Mustache renders an unknown placeholder as empty, so a missing entry shows
+     * up as a silent hole rather than an error.
+     */
+    substitutions?: Record<string, string> | undefined;
+    /**
+     * Labels selecting the hosts this group applies to.
+     *
+     * The base configuration carries them uninterpreted, because it has no
+     * notion of a host to match them against; `conformetry-nx` reads them as Nx
+     * project tags, and another host is free to read them as something else. A
+     * group with no tags applies everywhere.
+     */
+    tags?: string[] | undefined;
+    /**
+     * Lowest conformance score the instances in this group may have, overriding
+     * the generator's own threshold.
+     *
+     * This is what makes a migration bearable: one directory being brought onto
+     * a new template can be held to a lower bar while every other instance of
+     * the same template stays strict.
+     */
+    threshold?: number | undefined;
+}
+
+/** Arguments for expanding instance globs into instances. */
+export declare interface FindInstancesArguments {
+    /** Glob patterns, resolved against the working directory. */
+    readonly patterns: string[];
+    /**
+     * Applied to every instance these patterns produce. Callers that need
+     * per-project values, such as an Nx plugin supplying `type`, call once per
+     * project rather than passing a lookup table.
+     */
+    readonly substitutions?: Substitutions;
+    /** Applied to every instance these patterns produce, when the group sets one. */
+    readonly threshold?: number;
+    readonly workingDirectory: string;
+}
+
+/**
+ * Thrown when a command line cannot be turned into a run.
+ *
+ * One class rather than one per cause: every cause is the same event to
+ * whoever catches it — nothing was generated, and the fix is to retype the
+ * flags. Only the wording varies, which is what the factory below does.
+ */
+export declare class InputError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Parses command-line options into generator inputs.
+ *
+ * Generator inputs are not declared as CLI flags ahead of time — they come
+ * from whichever generator the user selected — so they are scanned out of the
+ * raw argument list and matched against the generator's schema.
+ */
+declare class InputOptionsService {
+    constructor();
+    /**
+     * Reads one option into the accumulating input map and reports how many
+     * argument tokens it consumed, so the caller can advance past its value.
+     */
+    private collectOneInput;
+    /** Reads the option name from `--flag` or `--flag=value`. */
+    private readOptionName;
+    /**
+     * Reads an option's value from either `--flag=value` or `--flag value`.
+     *
+     * Returns `undefined` when the next token is another flag, so a valueless
+     * flag does not swallow the option that follows it.
+     */
+    private readOptionValue;
+    /** Matches an option name to a schema property, in camel or kebab form. */
+    private resolvePropertyName;
+    /**
+     * Scans raw arguments for flags matching the generator's schema.
+     *
+     * Unknown flags are ignored rather than rejected: the argument list also
+     * carries the command's own options, which are handled elsewhere.
+     */
+    collectGeneratorInputs(args: {
+        rawArguments: string[];
+        schema: JsonSchemaDefinition;
+    }): Record<string, string>;
+    /** Coerces mixed-typed runtime options into string inputs. */
+    normalizeRuntimeOptions(options: Record<string, unknown>): Record<string, string | undefined>;
+    /**
+     * Resolves where generated files should land: an explicit output option, a
+     * resolved project root, or a directory named after the generator.
+     */
+    resolveTargetDirectoryPath(args: {
+        defaultGeneratedOutputDirectory?: string;
+        generatorName: string;
+        options: Record<string, unknown>;
+        resolveProjectRootPath?: (projectName: string) => string | undefined;
+    }): string;
+}
+
+/**
+ * Asks the user for input values interactively.
+ *
+ * Whether anybody *can* be asked is decided here rather than by the caller,
+ * and `promptForInput` refuses rather than draws itself when nobody can. That
+ * used to be the caller's job, behind a `--no-interactive` flag; a flag is a
+ * poor place for it, because forgetting to consult it is what hung this CLI
+ * in non-interactive environments.
+ *
+ * `isAtTerminal` stays public because some callers genuinely need the question
+ * rather than the refusal: an **optional** input nobody can be asked about is
+ * left out where a required one is refused, and the two template pickers below
+ * are only ever reached once a command has already asked it.
+ *
+ * Those pickers widen this service's remit from "values a schema declares" to
+ * "also, which template to run". That is a deliberate trade: one prompting
+ * seam is easier to keep honest than two, and a second one would have to read
+ * the terminal for itself.
+ */
+declare class InputPromptingService {
+    private readonly inputSchemaService;
+    constructor(inputSchemaService: InputSchemaService);
+    /** Overridable so tests never touch a real terminal. */
+    private readonly promptRunner;
+    /**
+     * Refuses to draw a prompt nobody can answer.
+     *
+     * `prompts` does not fail on a non-terminal stdin — it renders the menu,
+     * never resolves, and lets the process exit 0, so a run that generated
+     * nothing reads as one that succeeded.
+     */
+    private assertCanPrompt;
+    /** Renders one template as a choice, omitting an absent description. */
+    private describeChoice;
+    /**
+     * Whether anybody is there to answer a question.
+     *
+     * The one place the terminal is read, so the refusal in front of a prompt
+     * and the caller's decision to skip an optional input cannot disagree about
+     * what counts as interactive. `isTTY` is read as falsy rather than coerced:
+     * `@types/node` calls it a `boolean` while it is `undefined` off a terminal,
+     * so lint rejects the coercion that would say so.
+     */
+    isAtTerminal(): boolean;
+    /**
+     * Prompts for one value, offering a choice list when the schema declares an
+     * `enum` and free text otherwise.
+     */
+    promptForInput(input: SchemaInput): Promise<string | undefined>;
+    /**
+     * Asks which single template to run, filtering as the caller types.
+     *
+     * Autocomplete rather than a plain select because a template name is long
+     * by design — `nestjs-service-module` — and typing a fragment is what makes
+     * that cheap. Whether anybody can be asked at all is the caller's decision,
+     * already taken by the time this is reached.
+     */
+    promptForTemplate(templates: readonly TemplateChoice[]): Promise<string | undefined>;
+    /**
+     * Asks which templates to narrow a run to, offering the `all` sentinel
+     * alongside them so the picker can express everything the flag can.
+     *
+     * Ticking nothing resolves to no selection rather than an empty one: an
+     * empty narrowing would validate nothing at all, where the caller plainly
+     * declined to narrow.
+     */
+    promptForTemplates(templates: readonly TemplateChoice[]): Promise<string[] | undefined>;
+}
+
+/**
+ * Reads and enforces the JSON Schema fragments that describe generator inputs.
+ *
+ * Every accessor tolerates a malformed or absent schema: a generator with no
+ * declared parameters should still run, and an author's typo should not crash
+ * the CLI before it can report anything useful.
+ */
+declare class InputSchemaService {
+    constructor();
+    /** Reads one property off a schema fragment when it is an object. */
+    private readSchemaProperty;
+    /** Validates a value against a schema `enum`, when one is declared. */
+    private validateEnum;
+    /** Validates a value against `minLength` and `maxLength`. */
+    private validateLength;
+    /** Validates a value against a schema `pattern`. */
+    private validatePattern;
+    /** Describes one input, resolving its schema fragment and required flag. */
+    describeInput(args: {
+        inputName: string;
+        schema: JsonSchemaDefinition;
+    }): SchemaInput;
+    /** Reads the string members of a schema `enum`. */
+    readEnumValues(propertySchema: unknown): string[];
+    /** Reads a schema `description`, falling back to a generic prompt. */
+    readPromptMessage(input: SchemaInput): string;
+    /** Lists the input names a schema declares. */
+    readPropertyNames(schema: JsonSchemaDefinition): string[];
+    /**
+     * Validates a value, returning `true` or the reason it failed.
+     *
+     * An empty value is only an error when the input is required, so optional
+     * inputs can be skipped by pressing enter at a prompt.
+     */
+    validateValue(args: {
+        input: SchemaInput;
+        value: unknown;
+    }): string | true;
+}
+
+/**
+ * Resolves generator inputs from the command line, asking for what is missing.
+ *
+ * Nobody passes a "may I prompt" boolean any more. It used to be threaded
+ * through every method here from a `--no-interactive` flag, which put the one
+ * decision that can hang the process in the hands of each caller in turn;
+ * `InputPromptingService` owns it now and refuses at the prompt itself.
+ */
+declare class InputService {
+    private readonly inputOptionsService;
+    private readonly inputPromptingService;
+    private readonly inputSchemaService;
+    constructor(inputOptionsService: InputOptionsService, inputPromptingService: InputPromptingService, inputSchemaService: InputSchemaService);
+    /** Validates a value the caller already had, throwing if it is invalid. */
+    private acceptProvidedValue;
+    /** Walks a schema, taking each value from the resolver or a prompt. */
+    private resolveInputs;
+    /**
+     * Obtains one missing value by prompting.
+     *
+     * With nobody at a terminal the two kinds of input part ways: an optional
+     * one is left out, and a required one is refused. Prompting anyway is what
+     * used to hang the process, and refusing an optional input would fail runs
+     * that never needed the value at all.
+     */
+    private resolveMissingValue;
+    /** Splits a comma-delimited filter option into its values. */
+    parseCommaDelimitedOption(value: string | undefined): string[] | undefined;
+    /** Trims an optional string option, treating blank as absent. */
+    parseOptionalOption(value: string | undefined): string | undefined;
+    /** Trims a required string option, rejecting blank values. */
+    parseRequiredOption(args: {
+        optionName: string;
+        value: string;
+    }): string;
+    /**
+     * Parses a threshold option as a ratio from 0 to 1.
+     *
+     * Rejected loudly rather than clamped: `--threshold 90` is someone meaning
+     * 90%, and silently reading it as "always passes" would turn a typo into a
+     * validation run that can never fail.
+     */
+    parseThresholdOption(value: string | undefined): number | undefined;
+    /** Resolves generator inputs from raw command-line arguments. */
+    resolveGeneratorInputs(args: ResolveGeneratorInputsArguments): Promise<Record<string, string>>;
+    /** Resolves inputs from values the caller already parsed. */
+    resolveInputsFromValues(args: ResolveInputsFromValuesArguments): Promise<Record<string, string>>;
+}
+
+/**
+ * A place a template's tree is rendered into, plus the name it renders with.
+ *
+ * Instances come from the caller's glob expansion. Nothing here knows how they
+ * were found — that is the host's job, because globbing a workspace and
+ * reading project labels is workspace knowledge, not template knowledge.
+ */
+export declare interface Instance {
+    /**
+     * Absolute paths the match is restricted to, or `undefined` for the whole
+     * directory tree.
+     *
+     * This is what lets a two-file template like `nestjs-service-file` win. A
+     * directory glob leaves the scope open and the largest fitting template
+     * wins; a file glob narrows the scope to the matched files, so a template
+     * describing exactly those files fits better than one describing the whole
+     * directory.
+     */
+    readonly fileScope?: string[];
+    /** Drives the name substitutions — a directory basename or a filename stem. */
+    readonly nameStem: string;
+    /**
+     * Absolute path to the directory the template's tree is laid over.
+     *
+     * A template that produces a folder contains that folder, so this is the
+     * folder's *parent*: `nestjs-service-module` holds `{{nameKebabCase}}/…`,
+     * and its path is `…/src/modules`. A template that produces loose files
+     * holds them at its root, and its path is the directory those files sit in.
+     */
+    readonly path: string;
+    /**
+     * Substitutions the caller supplies on top of the derived name variants,
+     * such as `type` from the project graph. Mustache renders an unknown
+     * placeholder as empty, so anything a template references must arrive here.
+     */
+    readonly substitutions?: Substitutions;
+    /**
+     * Lowest conformance score this instance may have, from the instance group
+     * that located it. The narrowest of the three levels, so it wins.
+     */
+    readonly threshold?: number;
+}
+
+/**
+ * Expands instance glob patterns into instances.
+ *
+ * The globs are the author's assertion of what was generated from a template;
+ * nothing is inferred from directory names or marker files, which is what the
+ * previous matcher did and what made it repo-specific.
+ */
+declare class InstanceDiscoveryLocatingService {
+    constructor();
+    /**
+     * Derives the substitutions an instance's own location answers.
+     *
+     * `type` is the top-level directory the instance sits in — `packages` for
+     * `packages/widgets` — because that is what a project template's own
+     * `project.json` renders into its paths. Derived rather than configured for
+     * the same reason the name variants are: it is a fact about where the
+     * instance is, and restating it per glob is how the two drift apart. A
+     * configured value still wins, which is what a workspace nesting its
+     * projects deeper needs.
+     */
+    private deriveLocationSubstitutions;
+    /**
+     * Returns the literal filename suffix a pattern ends with, such as
+     * `.service.ts` for `**\/*.service.ts`, or `""` when the pattern's last
+     * segment holds no wildcard.
+     *
+     * This is what a file instance's name is derived from: the part of the
+     * filename the glob did not spell out is the name.
+     */
+    private resolveGlobSuffix;
+    /**
+     * Derives the name an instance's substitutions are built from.
+     *
+     * A directory is named by itself. A file is named by what remains once the
+     * glob's literal suffix is removed, so `differences.service.ts` matched by
+     * `*.service.ts` and `differences.service.unit.test.ts` matched by
+     * `*.service.unit.test.ts` both yield `differences` — which is what collapses the
+     * two into a single two-file instance.
+     */
+    private resolveNameStem;
+    /**
+     * Expands every pattern and returns one instance per distinct path, name,
+     * and scope kind.
+     *
+     * A directory match leaves the file scope open, so the largest fitting
+     * template wins. File matches for the same name are unioned into one scoped
+     * instance, so a template describing exactly those files wins instead. A
+     * directory and a file instance for the same name stay separate on purpose:
+     * both run, and deduplication reports the finding from the smaller template.
+     */
+    findInstances(args: FindInstancesArguments): Instance[];
+}
+
+/**
+ * Decides which template an instance directory was generated from.
+ *
+ * Nothing declares the answer — an instance is ordinary code with no marker
+ * saying where it came from — so the template is inferred from how much of its
+ * structure the instance already has.
+ */
+declare class InstanceDiscoveryMatchingService {
+    private readonly templateDiscoveryService;
+    private readonly renderingService;
+    constructor(templateDiscoveryService: TemplateDiscoveryService, renderingService: RenderingService);
+    /**
+     * Orders template matches best-first.
+     *
+     * Coverage ratio leads, because absolute count alone lets a large template
+     * win on a weak partial match — a module directory matching three of a
+     * seven-file GraphQL template would beat nothing, and used to. Absolute
+     * count breaks ratio ties, so a five-file module template beats a two-file
+     * service-file template when both match completely. Name makes it
+     * deterministic.
+     */
+    private compareMatches;
+    /**
+     * Builds the substitutions an instance's template is rendered with.
+     *
+     * Name variants come from the instance's stem; caller-supplied values are
+     * spread last so an explicit `type` or `description` always wins.
+     */
+    buildSubstitutions(instance: Instance): Substitutions;
+    /**
+     * Resolves every instance to the template — or templates — that explain it.
+     *
+     * An instance matching nothing, or matching two templates equally well but
+     * only partially, is returned as unmatched rather than dropped: the caller
+     * asserted these are instances, so silence would hide both a drifted
+     * instance and a pair of indistinguishable templates.
+     *
+     * A complete tie is different, and is matched against every tied template. A
+     * module holding both a command and a service really is an instance of both
+     * `nestjs-command-module` and `nestjs-service-module`; calling that ambiguous
+     * would demand the author narrow a glob that is not wrong.
+     */
+    matchInstances(args: {
+        instances: Instance[];
+        templates: TemplateDefinition[];
+    }): ResolvedInstances;
+    /**
+     * Weighs every template that shares at least one file with the instance,
+     * best-first.
+     *
+     * Public because a caller may need the ranking itself and not just the
+     * verdict: nothing records which template an instance came from, so an
+     * ambiguous or unmatched outcome is only explainable by showing what was
+     * weighed and how well each template fitted.
+     */
+    matchTemplates(args: {
+        instance: Instance;
+        substitutions: Substitutions;
+        templates: TemplateDefinition[];
+    }): TemplateMatch[];
+}
+
+/**
+ * Finds the generated code a workspace holds, and decides what explains it.
+ *
+ * This is the workspace-facing half of discovery: the template-discovery module
+ * reads the templates root, and this one reads the tree those templates were
+ * rendered into. Matching lives here because every answer it produces is
+ * instance-shaped — a matched instance, an unmatched one, or a ranking of
+ * templates against one path.
+ */
+declare class InstanceDiscoveryService {
+    private readonly instanceDiscoveryLocatingService;
+    private readonly instanceDiscoveryMatchingService;
+    private readonly instanceGroupService;
+    private readonly templateDiscoveryService;
+    constructor(instanceDiscoveryLocatingService: InstanceDiscoveryLocatingService, instanceDiscoveryMatchingService: InstanceDiscoveryMatchingService, instanceGroupService: InstanceGroupService, templateDiscoveryService: TemplateDiscoveryService);
+    /** Weighs one instance against every template, best fit first. */
+    private weighInstance;
+    /** Builds the substitutions an instance's template is rendered with. */
+    buildSubstitutions(instance: Instance): ReturnType<InstanceDiscoveryMatchingService["buildSubstitutions"]>;
+    /** Expands instance globs into the instances that exist. */
+    findInstances(args: FindInstancesArguments): Instance[];
+    /** Resolves every instance to the template, or templates, that explain it. */
+    matchInstances(args: {
+        instances: Instance[];
+        templates: TemplateDefinition[];
+    }): ResolvedInstances;
+    /** Ranks every template that shares a file with one instance, best first. */
+    matchTemplates(args: Parameters<InstanceDiscoveryMatchingService["matchTemplates"]>[0]): ReturnType<InstanceDiscoveryMatchingService["matchTemplates"]>;
+    /**
+     * Prepares the rendered template and instance document pairs for each matched
+     * instance, restricted to the extensions the caller's languages claim.
+     */
+    prepareDocuments(args: PrepareDocumentsArguments): PreparedInstanceDocuments[];
+    /**
+     * Keeps the groups a host with no project graph can actually locate.
+     *
+     * A group carrying `tags` reads its globs *inside each project the tags
+     * select*, so `src/modules/*` has no meaning until a project root is joined
+     * to it. This package has no notion of a project, so such a group is not
+     * addressed to it and is left out rather than expanded from the working
+     * directory — which would match whatever happened to sit at the same
+     * relative path and measure it against a template scoped to other projects.
+     * `@conformetry/nx` resolves those groups first, so what reaches discovery
+     * from there is already workspace-relative and untagged groups are all that
+     * is left to read.
+     *
+     * Dropping them is deliberately silent here and reported by the caller: this
+     * is a question about one group, and only a command knows whether the run it
+     * was asked for has been left with nothing.
+     *
+     * Which groups those are is `InstanceGroupService`'s to say, so that this and
+     * the set `@conformetry/nx` claims stay exact complements.
+     */
+    readWorkspaceGroups(groups: readonly ConformetryInstanceGroup[]): ConformetryInstanceGroup[];
+    /** Lists every file a matched instance's template requires it to have. */
+    resolveInstanceFiles(instances: MatchedInstance[]): InstanceFile[];
+    /**
+     * Lists every instance found, paired with the templates that explain it.
+     *
+     * `templateNames` narrows the pairing rather than the search, so an instance
+     * that no named template explains drops out entirely.
+     */
+    resolveInventoriedInstances(args: ResolveInventoryArguments): InventoriedInstance[];
+    /**
+     * Lists every template declared, paired with the instances it explains.
+     *
+     * `instancePatterns` narrows which instances are considered, which is what
+     * turns this into "which templates explain this path". A path can legitimately
+     * belong to several templates, so every one that fits is reported.
+     */
+    resolveInventoriedTemplates(args: ResolveInventoryArguments): InventoriedTemplate[];
+    /** Weighs every instance the globs find against every declared template. */
+    takeInventory(args: ResolveInventoryArguments): {
+        templates: TemplateDefinition[];
+        weighed: {
+            instance: Instance;
+            pairings: InventoriedPairing[];
+        }[];
+    };
+}
+
+/** A file a matched template requires its instance to have. */
+export declare interface InstanceFile {
+    readonly instance: MatchedInstance;
+    readonly instanceFilePath: string;
+    readonly templateFilePath: string;
+}
+
+/**
+ * Reads an instance group's own fields, for every host that resolves one.
+ *
+ * `ConformetryInstanceGroup` is declared beside this, and how its `tags` are
+ * read decides which host owns a group — so the reading lives here rather than
+ * in either host. `@conformetry/nx` resolves project-scoped groups against the
+ * project graph; a host without one leaves them alone. The two answers must be
+ * complements, and nothing would fail if they stopped being: each host would
+ * simply take a different set of groups to be its own, and validation would
+ * quietly measure the wrong tree.
+ *
+ * Dependency-free on purpose. Every host reaches it through
+ * `ConfigurationService`, so nothing has to be wired up to ask this question —
+ * including the install-time bootstrap, which has no project graph to hand
+ * anybody.
+ */
+declare class InstanceGroupService {
+    constructor();
+    /**
+     * Whether a group locates its instances inside the hosts its tags select.
+     *
+     * Non-empty `tags` is the whole rule. An empty array is not a selector — it
+     * selects nothing and would silence the group entirely — so it reads as the
+     * workspace form, the same as omitting the field.
+     */
+    isProjectScoped(group: ConformetryInstanceGroup): boolean;
+}
+
+/**
+ * Minimal JSON Schema fragment used to discover a generator's inputs.
+ *
+ * Only the parts conformetry actually reads are modelled — `properties` for
+ * the input names, and `required` for which ones must be supplied.
+ */
+export declare interface JsonSchemaDefinition {
+    [key: string]: unknown;
+    properties?: Record<string, unknown>;
+}
+
+/** An instance paired with the template that best explains it. */
+export declare interface MatchedInstance {
+    readonly instance: Instance;
+    /** How many of the template's files the instance already has. */
+    readonly matchedFileCount: number;
+    readonly substitutions: Substitutions;
+    readonly template: TemplateDefinition;
+}
+
+/**
+ * A required input that cannot be asked for, because stdin is not a terminal.
+ *
+ * `prompts` does not fail there — it draws its menu, never resolves, and the
+ * process exits 0 having done nothing, which is exactly how this CLI used to
+ * hang in non-interactive environments. Naming the flag to pass is the whole
+ * remedy, so the message carries it.
+ */
+export declare const missingInputError: (inputName: string) => InputError;
+
+/**
+ * Raised when a template interpolates a placeholder nobody supplied a value
+ * for.
+ *
+ * Refusing is the only outcome that cannot be mistaken for success: mustache
+ * would render the placeholder as an empty string, and because generation and
+ * validation render identically, both halves of the loop would lose the same
+ * value and agree that nothing was wrong. Section tags are exempt, and why is
+ * in this package's README.
+ */
+export declare class MissingSubstitutionError extends Error {
+    constructor(args: {
+        placeholders: readonly string[];
+        subject: string;
+    });
+}
+
+/** Documents prepared for one matched instance. */
+export declare interface PreparedInstanceDocuments {
+    readonly documents: PreparedValidationDocument[];
+    readonly instance: MatchedInstance;
+}
+
+/** Arguments for preparing comparison documents for matched instances. */
+export declare interface PrepareDocumentsArguments {
+    readonly fileExtensions: string[];
+    readonly instances: MatchedInstance[];
+}
+
+/**
+ * Renders conformetry template placeholders.
+ *
+ * This is the single owner of template rendering across the workspace.
+ * Generation renders templates to create files; validation renders the same
+ * templates to compare them against existing files. Both must substitute
+ * identically or validation would flag files the generator itself produced,
+ * so neither reimplements this.
+ */
+declare class RenderingService {
+    constructor();
+    /** Refuses to render a template asking for a value nobody supplied. */
+    private assertEverySubstitutionSupplied;
+    /**
+     * Every placeholder a template interpolates, deduplicated.
+     *
+     * Mustache's own parser reads them, so an interpolation is told from a
+     * comment, a partial, and a delimiter change the way mustache tells them.
+     * Section names are skipped and their bodies still walked — `{{#field}}` and
+     * `{{^field}}` are conditionals, so absence is an answer there — as is the
+     * implicit iterator `{{.}}`, which names no field.
+     */
+    private collectInterpolatedNames;
+    /**
+     * Derives the case variants every template can reference from one name.
+     *
+     * Callers merge their own inputs over this result, so an explicit input of
+     * the same key always wins over the derived variant.
+     */
+    buildNameSubstitutions(name: string): Substitutions;
+    /**
+     * Renders template contents with mustache.
+     *
+     * Full mustache is available — sections, inverted sections, partials — with
+     * HTML escaping disabled so substituted values cannot corrupt source code.
+     *
+     * An interpolated placeholder nobody supplied raises
+     * `MissingSubstitutionError`. `subject` is what that error names, so pass
+     * the template's path when there is one.
+     */
+    renderContent(args: {
+        subject?: string;
+        substitutions: Substitutions;
+        templateContent: string;
+    }): string;
+    /**
+     * Renders a template path with mustache, the same way contents are rendered.
+     *
+     * Paths once used a `__field__` syntax of their own, on the assumption that
+     * braces were not portable across filesystems. They are — and the separate
+     * syntax could not tell a placeholder from a Python dunder, so a template
+     * shipping `__init__.py` depended on `init` never being a substitution.
+     */
+    renderPath(args: {
+        subject?: string;
+        substitutions: Substitutions;
+        templatePath: string;
+    }): string;
+}
+
+/** The outcome of resolving a set of instances against a set of templates. */
+export declare interface ResolvedInstances {
+    readonly matched: MatchedInstance[];
+    readonly unmatched: UnmatchedInstance[];
+}
+
+/** Arguments for resolving generator inputs from raw CLI arguments. */
+export declare interface ResolveGeneratorInputsArguments {
+    rawArguments: string[];
+    schema: JsonSchemaDefinition;
+}
+
+/** Arguments for resolving inputs from values the caller already has. */
+declare interface ResolveInputsFromValuesArguments {
+    providedInputs: Record<string, string | undefined>;
+    schema: JsonSchemaDefinition;
+}
+
+/**
+ * Arguments for taking an inventory of templates and instances.
+ *
+ * Both filters narrow the pairing rather than the search, so an entry that
+ * survives neither drops out entirely.
+ */
+export declare interface ResolveInventoryArguments {
+    readonly configuration: ConformetryConfiguration;
+    /** Globs narrowing which instances count; the configured ones when absent. */
+    readonly instancePatterns?: string[] | undefined;
+    /** Template names narrowing which templates count; all of them when absent. */
+    readonly templateNames?: string[] | undefined;
+    readonly workingDirectory: string;
+}
+
+/** One schema-backed input being resolved. */
+declare interface SchemaInput {
+    readonly inputName: string;
+    readonly isRequired: boolean;
+    readonly propertySchema: unknown;
+}
+
+/**
+ * Placeholder values applied when rendering a template.
+ *
+ * Built from the generator name by `RenderingService.buildNameSubstitutions`
+ * and then merged with the caller's own inputs, so an explicit input always
+ * wins over a derived name variant.
+ */
+export declare type Substitutions = Record<string, string>;
+
+/**
+ * One template a picker can offer.
+ *
+ * Deliberately not `ConformetryGeneratorDefinition`: the picker needs only the
+ * name it returns and the description it shows, and asking for the whole
+ * definition would tie prompting to the configuration's shape.
+ */
+export declare interface TemplateChoice {
+    readonly description?: string | undefined;
+    readonly name: string;
+}
+
+/** One template: a directory of mustache files under the templates root. */
+export declare interface TemplateDefinition {
+    /** Absolute path to the template's own directory. */
+    readonly directoryPath: string;
+    /** Absolute paths of every file in the template, sorted. */
+    readonly filePaths: string[];
+    /** The template's directory name, used to identify it. */
+    readonly name: string;
+    /**
+     * Lowest conformance score an instance of this template may have, from the
+     * generator that owns it. Undefined when the generator sets none.
+     */
+    readonly threshold?: number;
+}
+
+/**
+ * Reads template folders and maps their files onto instance files.
+ *
+ * A template's tree is laid over the instance path verbatim, so a template
+ * that should produce a folder contains that folder — `{{nameKebabCase}}/…` —
+ * rather than the runtime inventing one. That keeps the shape of the output
+ * visible in the template itself, and lets one template produce a folder while
+ * another produces loose files, with nothing but their contents to say so.
+ *
+ * Rendering goes through `RenderingService` so a template is substituted here
+ * exactly as it was when the generator wrote the file — otherwise validation
+ * would report differences the generator itself introduced.
+ */
+declare class TemplateDiscoveryService {
+    private readonly renderingService;
+    constructor(renderingService: RenderingService);
+    /** Lists every file under a directory, recursively and sorted. */
+    private collectFilePaths;
+    /**
+     * Reads one template folder.
+     *
+     * The folder is the whole definition — nothing but the files it contains is
+     * needed to validate against it.
+     */
+    collectTemplate(args: {
+        name: string;
+        templatePath: string;
+        threshold?: number | undefined;
+    }): TemplateDefinition;
+    /**
+     * Reads every configured generator's template folder.
+     *
+     * Every host needs this before it can match anything, and each was resolving
+     * the configured paths itself. Resolving them once here keeps one answer to
+     * where a generator's template lives.
+     */
+    collectTemplates(args: {
+        configuration: ConformetryConfiguration;
+        workingDirectory: string;
+    }): TemplateDefinition[];
+    /**
+     * Counts how many of a template's files the instance path already has.
+     *
+     * When a file scope is given, only files inside it count — that is what lets
+     * a file glob select a template describing exactly those files rather than
+     * the larger template describing the whole directory.
+     */
+    countMatchingFiles(args: {
+        fileScope?: string[] | undefined;
+        instancePath: string;
+        substitutions: Substitutions;
+        template: TemplateDefinition;
+    }): number;
+    /**
+     * Pairs one template file with its instance, rendering the template.
+     *
+     * Returns `undefined` when the instance does not exist — that is a missing
+     * file, which the file-existence pass reports; a language validator has nothing
+     * to compare and should not see the pair at all.
+     */
+    prepareDocument(args: {
+        instancePath: string;
+        substitutions: Substitutions;
+        templateDirectoryPath: string;
+        templateFilePath: string;
+    }): PreparedValidationDocument | undefined;
+    /** Maps a template file path to the instance file path it governs. */
+    resolveInstanceFilePath(args: {
+        instancePath: string;
+        substitutions: Substitutions;
+        templateDirectoryPath: string;
+        templateFilePath: string;
+    }): string;
+}
+
+/**
+ * One template weighed against an instance during matching.
+ *
+ * `matchRatio` measures which template *fits*, by file presence alone. It is
+ * deliberately not called a score: an instance's conformance score measures
+ * how well the matched template's contents are honoured, which is a different
+ * number arrived at a different way.
+ */
+export declare interface TemplateMatch {
+    readonly matchedFileCount: number;
+    /** Share of the template's files the instance already has, 0 to 1. */
+    readonly matchRatio: number;
+    readonly template: TemplateDefinition;
+}
+
+/** Raised when the configuration path points to an unsupported file type. */
+export declare class UnknownConfigurationFileTypeError extends Error {
+    constructor(filePath: string);
+}
+
+/** An instance no template explains well enough to validate against. */
+export declare interface UnmatchedInstance {
+    readonly instance: Instance;
+    readonly reason: UnmatchedReason;
+    /** Templates that tied, when the reason is `ambiguous`. */
+    readonly tiedTemplateNames: string[];
+}
+
+/**
+ * Why an instance could not be matched.
+ *
+ * Both are reported rather than skipped: a glob is the caller asserting these
+ * directories are instances, so an instance matching nothing is a real finding,
+ * and a tie means two templates are indistinguishable.
+ */
+export declare type UnmatchedReason = "ambiguous" | "no-match";
+
+export { }