@conformetry/configuration 0.0.79 → 0.0.81

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.0.81 (2026-11-10)
+
+### 🚀 Features
+
+- **codometer:** ✨ gate JSDoc on every declaration kind and shorten long comments ([#2227](https://github.com/organizzolini/codebase/pull/2227), [#2226](https://github.com/organizzolini/codebase/issues/2226))
+
+### 🧱 Updated Dependencies
+
+- Updated conformetry-core to 0.0.79
+
+## 0.0.80 (2026-11-10)
+
+### 🩹 Fixes
+
+- **codependix,conformetry,infrastructure,installation,persistence,testing,configuration,caelundas,dependencies:** 🐛 gap ([#2223](https://github.com/organizzolini/codebase/pull/2223), [#2221](https://github.com/organizzolini/codebase/issues/2221))
+
+### 🧱 Updated Dependencies
+
+- Updated conformetry-core to 0.0.78
+
 ## 0.0.79 (2026-11-10)
 
 ### 🧱 Updated Dependencies

package/dist/src/index.d.ts

@@ -7,25 +7,15 @@ 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.
+ * The `validate --templates` value meaning every template. Supplying it skips
+ * the prompt omitting it would show; no template may use this name.
  */
 export declare const ALL_TEMPLATES_SELECTION = "all";
 
 /**
- * Reads what each placeholder value in `templateText` stands for in
- * `instanceText`.
+ * Reads what each placeholder value in `templateText` stands for in `instanceText`.
  *
- * The template text is a pattern: its literal parts must match exactly and
- * each placeholder value captures a non-empty run of text. Returns `undefined`
- * when the template text holds no placeholder value or the instance text does
- * not fit the pattern, so a caller keeps its own equality check as it was.
+ * Returns `undefined` when the instance text does not fit the template pattern.
  */
 export declare function capturePlaceholderValues(args: {
     instanceText: string;
@@ -35,12 +25,7 @@ export declare function capturePlaceholderValues(args: {
 /**
  * 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.
+ * Only `ConfigurationService` is exported; a consumer injects it and nothing else from this package.
  */
 export declare class ConfigurationModule {
 }
@@ -48,10 +33,7 @@ export declare class ConfigurationModule {
 /**
  * Raised when a run names no configuration file.
  *
- * There is no default file and no filename search: the path is the one thing a
- * run cannot infer, and a guessed file is a silently wrong configuration. The
- * surface is how the caller spells the thing the person left unset — a flag, an
- * option, a registration — so the message points at the fix where they are.
+ * There is no default file and no filename search, since a guessed file would be silently wrong.
  */
 export declare class ConfigurationPathRequiredError extends Error {
     constructor(surface: string);
@@ -59,22 +41,9 @@ export declare class ConfigurationPathRequiredError extends Error {
 }
 
 /**
- * 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.
+ * The single entry point for configuration questions: load a config file, find templates and instances, and prompt for inputs.
  *
- * 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.
+ * Callers inject this service and nothing else from this package. The collaborators are kept as separate classes so each one stays a single job.
  */
 export declare class ConfigurationService {
     private readonly inputPromptingService;
@@ -87,8 +56,7 @@ export declare class ConfigurationService {
     /**
      * 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.
+     * A generator with no inputs or instances is legal.
      */
     private applyGeneratorDefaults;
     /**
@@ -97,10 +65,9 @@ export declare class ConfigurationService {
      */
     private applyHookDefaults;
     /**
-     * Walks upward from the process cwd looking for the workspace manifest.
+     * Walks upward from the cwd to find 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.
+     * Lets a config path resolve from a nested directory.
      */
     private findWorkspaceRoot;
     /** Loads a config module, choosing the reader by extension. */
@@ -125,9 +92,7 @@ export declare class ConfigurationService {
     /**
      * 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.
+     * Throws for an unsupported extension or a malformed registry, so a bad config fails loudly.
      */
     loadConformetryConfiguration(configurationPath: string): Promise<ConformetryConfiguration>;
     /** Resolves every instance to the template, or templates, that explain it. */
@@ -157,22 +122,15 @@ export declare class ConfigurationService {
     /** Renders a template path with mustache. */
     renderPath(args: Parameters<RenderingService["renderPath"]>[0]): string;
     /**
-     * Returns the configuration path a run was given, or refuses.
+     * Returns the configuration path, or throws when it is absent or blank.
      *
-     * Every host asks here, so "a path is required" and what the refusal says
-     * have one home. `surface` names where the caller expected the path to be
-     * set, for example the `--config` flag.
-     *
-     * Throws `ConfigurationPathRequiredError` for an absent or blank value.
+     * `surface` names where the path was expected.
      */
     requireConfigurationPath(value: string | undefined, surface: string): string;
     /**
-     * Resolves a config path to the absolute file `loadConformetryConfiguration`
-     * reads: against the cwd first, then the workspace root.
+     * Resolves a config path to the file `loadConformetryConfiguration` reads.
      *
-     * Public because the directory a hook builds its paths from is that file's
-     * parent, and only this resolution knows which file was read. A host that
-     * worked it out from the flag alone would miss the workspace-root fallback.
+     * Public so hosts resolve the same file, including the workspace-root fallback.
      */
     resolveConfigurationPath(configurationPath: string): Promise<string>;
     /** Resolves generator inputs from raw command-line arguments. */
@@ -186,10 +144,8 @@ export declare class ConfigurationService {
 }
 
 /**
- * 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.
+ * The loaded configuration: one entry per generator. An array, since a
+ * generator's name is already a field and a record would state it twice.
  */
 export declare type ConformetryConfiguration = ConformetryGeneratorDefinition[];
 
@@ -197,34 +153,23 @@ export declare type ConformetryConfiguration = ConformetryGeneratorDefinition[];
 export declare interface ConformetryGeneratorDefinition {
     description?: string;
     /**
-     * Functions run around generation: `preGenerate` before anything is written,
-     * `postGenerate` after the template is rendered. Optional, and left off the
-     * loaded definition when a generator declares none, so a host forwards
-     * exactly what the configuration said.
+     * Functions run around generation: `preGenerate` before writing, `postGenerate`
+     * after rendering. Left off when a generator declares none.
      */
     hooks?: GeneratorHooks;
-    /**
-     * 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.
-     */
+    /** Values substituted into the template, each a JSON Schema fragment. */
     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.
+     * Where this generator's output already lives. Validation expands these to
+     * find what to check; generation reads them to place new instances.
      */
     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.
+     * Lowest passing conformance score, 0 to 1. Unset rather than defaulted, so a
+     * run-level `--threshold` can still apply.
      */
     threshold?: number;
 }
@@ -240,69 +185,47 @@ export declare type ConformetryGeneratorInputDefinition = Record<string, unknown
  */
 export declare interface ConformetryInstanceGroup {
     /**
-     * Workspace-relative globs naming paths that are never instances, applied
-     * whether or not the group has tags. A directory or file the patterns found
-     * is dropped when one of these matches it — how vendored or generated code,
-     * such as shadcn components, is left out of validation.
+     * Workspace-relative globs naming paths that are never instances, such as
+     * vendored shadcn components. Applies whether or not the group has tags.
      */
     exclude?: string[] | undefined;
     /**
-     * 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.
+     * Globs locating this group's instances, workspace-relative unless a host
+     * resolves `tags` against each selected host. A group with only `tags` 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.
+     * Values for every placeholder the template uses. A missing one renders as
+     * empty rather than failing, so it is a silent hole.
      */
     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.
+     * Labels selecting the hosts this group applies to, carried uninterpreted
+     * here; `conformetry-nx` reads them as Nx project tags. No tags means 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.
+     * Lowest passing score for this group's instances, overriding the generator's
+     * threshold. It lets one directory migrate at a lower bar.
      */
     threshold?: number | undefined;
 }
 
 /**
- * Creates a random stand-in for a placeholder nothing supplied.
- *
- * Validation renders it in place of the missing value, so the comparison can
- * find where the instance holds the real one and capture it.
+ * Creates a random stand-in for a placeholder nothing supplied, so validation can find the real value.
  */
 export declare function createPlaceholderValue(): string;
 
 /** Arguments for expanding instance globs into instances. */
 export declare interface FindInstancesArguments {
-    /**
-     * Globs, relative to the working directory, naming paths that are never
-     * instances: a directory or file a pattern found is dropped when one of
-     * these matches it.
-     */
+    /** Globs naming paths that are never instances. A matching directory or file is dropped. */
     readonly exclude?: string[] | undefined;
     /** 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.
+     * Applied to every instance these patterns produce. Callers needing per-project
+     * values 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. */
@@ -344,10 +267,9 @@ declare class InputOptionsService {
     /** Reads the option name from `--flag` or `--flag=value`. */
     private readOptionName;
     /**
-     * Reads an option's value from either `--flag=value` or `--flag value`.
+     * Reads an option's value from `--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.
+     * A valueless flag does not swallow the option after it.
      */
     private readOptionValue;
     /** Matches an option name to a schema property, in camel or kebab form. */
@@ -355,8 +277,7 @@ declare class InputOptionsService {
     /**
      * 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.
+     * Unknown flags are ignored, since the command's own options share the argument list.
      */
     collectGeneratorInputs(args: {
         rawArguments: string[];
@@ -367,23 +288,9 @@ declare class InputOptionsService {
 }
 
 /**
- * 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.
+ * Asks the user for input values interactively, and for the template to run.
  *
- * 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.
+ * Refuses rather than prompting when nobody can answer, so a non-terminal run cannot hang.
  */
 declare class InputPromptingService {
     private readonly inputSchemaService;
@@ -393,9 +300,7 @@ declare class InputPromptingService {
     /**
      * 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.
+     * `prompts` would otherwise exit 0 with nothing generated.
      */
     private assertCanPrompt;
     /** Renders one template as a choice, omitting an absent description. */
@@ -403,11 +308,7 @@ declare class InputPromptingService {
     /**
      * 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.
+     * `isTTY` is tested as falsy: it is `undefined` off a terminal, despite its `boolean` type.
      */
     isAtTerminal(): boolean;
     /**
@@ -416,21 +317,13 @@ declare class InputPromptingService {
      */
     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.
+     * Asks which single template to run, with autocomplete since template names are long.
      */
     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.
+     * Asks which templates to narrow a run to, offering the `all` sentinel alongside them.
      *
-     * 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.
+     * Ticking nothing means no narrowing, not an empty one.
      */
     promptForTemplates(templates: readonly TemplateChoice[]): Promise<string[] | undefined>;
 }
@@ -466,8 +359,7 @@ declare class InputSchemaService {
     /**
      * 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.
+     * An empty value fails only when the input is required.
      */
     validateValue(args: {
         input: SchemaInput;
@@ -495,10 +387,7 @@ declare class InputService {
     /**
      * 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.
+     * Without a terminal, a required input is refused and an optional one is skipped.
      */
     private resolveMissingValue;
     /** Splits a comma-delimited filter option into its values. */
@@ -513,9 +402,7 @@ declare class InputService {
     /**
      * 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.
+     * Rejected rather than clamped: `--threshold 90` would otherwise read as always passing.
      */
     parseThresholdOption(value: string | undefined): number | undefined;
     /** Resolves generator inputs from raw command-line arguments. */
@@ -525,39 +412,27 @@ declare class InputService {
 }
 
 /**
- * A place a template's tree is rendered into, plus the name it renders with.
+ * A place a template's tree is rendered into, with 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.
+ * The host's glob expansion supplies it.
  */
 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.
+     * Absolute paths narrowing the match, or `undefined` for the whole tree. A file
+     * glob narrows this, so a template describing those files fits better.
      */
     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.
+     * Directory the template's tree is laid over: for a folder-producing template,
+     * the folder's parent; for loose files, their directory.
      */
     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.
+     * Caller-supplied substitutions beyond the derived name variants, such as
+     * `type`. Mustache renders a missing placeholder as empty, so each one must
+     * arrive here.
      */
     readonly substitutions?: Substitutions;
     /**
@@ -577,15 +452,9 @@ export declare interface Instance {
 declare class InstanceDiscoveryLocatingService {
     constructor();
     /**
-     * Derives the substitutions an instance's own location answers.
+     * Derives location substitutions, such as `type`.
      *
-     * `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.
+     * `type` is the top-level directory; a configured value still wins.
      */
     private deriveLocationSubstitutions;
     /** Expands one pattern, leaving out every path an exclude glob matches. */
@@ -593,33 +462,21 @@ declare class InstanceDiscoveryLocatingService {
     /** Whether an exclude glob matches a found path, workspace-relative. */
     private isExcluded;
     /**
-     * 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.
+     * Returns the literal suffix a pattern ends with, or `""` if none.
      *
-     * 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.
+     * A file's name is what the glob did not spell out.
      */
     private resolveGlobSuffix;
     /**
-     * Derives the name an instance's substitutions are built from.
+     * Derives an instance's name.
      *
-     * 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.
+     * Minus the glob's suffix, `differences.service.ts` and `differences.service.unit.test.ts` both give `differences`.
      */
     private resolveNameStem;
     /**
-     * Expands every pattern and returns one instance per distinct path, name,
-     * and scope kind.
+     * Expands every pattern into 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.
+     * Same-name file matches merge into one scoped instance.
      */
     findInstances(args: FindInstancesArguments): Instance[];
 }
@@ -636,57 +493,37 @@ declare class InstanceDiscoveryMatchingService {
     private readonly renderingService;
     constructor(templateDiscoveryService: TemplateDiscoveryService, renderingService: RenderingService);
     /**
-     * Orders template matches best-first.
+     * Orders 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.
+     * Coverage ratio leads, so a large template cannot win a weak partial match.
+     * Ties break on count, then name.
      */
     private compareMatches;
     /**
-     * Gives every placeholder the substitutions leave out a random stand-in.
+     * Gives each placeholder the substitutions leave out a random stand-in.
      *
-     * Only validation matches instances, and there a missing value is something
-     * to infer from the instance rather than an error: generation renders
-     * without this and still refuses a placeholder nobody supplied. `name` and its
-     * variants are always supplied, so they are never stood in for.
+     * Validation infers the stand-in's value from the instance; generation refuses to render one.
      */
     private fillPlaceholders;
     /**
      * 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.
+     * Caller-supplied values are spread last, so an explicit `type` 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.
+     * Resolves every instance to the template, or templates, that explain it.
      *
-     * 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.
+     * Unexplained or partially tied instances are reported as unmatched, not dropped.
      */
     matchInstances(args: {
         instances: Instance[];
         templates: TemplateDefinition[];
     }): ResolvedInstances;
     /**
-     * Weighs every template that shares at least one file with the instance,
-     * best-first.
+     * Weighs every template sharing a 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.
+     * Public so callers can explain an ambiguous or unmatched outcome.
      */
     matchTemplates(args: {
         instance: Instance;
@@ -711,11 +548,9 @@ declare class InstanceDiscoveryService {
     private readonly templateDiscoveryService;
     constructor(instanceDiscoveryLocatingService: InstanceDiscoveryLocatingService, instanceDiscoveryMatchingService: InstanceDiscoveryMatchingService, instanceGroupService: InstanceGroupService, templateDiscoveryService: TemplateDiscoveryService);
     /**
-     * The globs an inventory expands: the configured groups' patterns and
-     * exclusions, or an explicit pattern list replacing both.
+     * The globs an inventory expands.
      *
-     * One expansion rather than one per group, so an instance two groups locate
-     * is listed once; every group's exclusions therefore apply to all of them.
+     * One expansion covers all groups, so an instance two groups locate is listed once.
      */
     private readInventoryGlobs;
     /** Weighs one instance against every template, best fit first. */
@@ -737,24 +572,9 @@ declare class InstanceDiscoveryService {
      */
     prepareDocuments(args: PrepareDocumentsArguments): PreparedInstanceDocuments[];
     /**
-     * Keeps the groups a host with no project graph can actually locate.
+     * Keeps the groups this host can locate: those without `tags`.
      *
-     * 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.
+     * Tagged groups need a project graph, which this host lacks.
      */
     readWorkspaceGroups(groups: readonly ConformetryInstanceGroup[]): ConformetryInstanceGroup[];
     /** Lists every file a matched instance's template requires it to have. */
@@ -762,16 +582,13 @@ declare class InstanceDiscoveryService {
     /**
      * 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.
+     * `templateNames` narrows the pairing, dropping unexplained instances.
      */
     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.
+     * `instancePatterns` narrows which instances count.
      */
     resolveInventoriedTemplates(args: ResolveInventoryArguments): InventoriedTemplate[];
     /** Weighs every instance the globs find against every declared template. */
@@ -794,36 +611,22 @@ export declare interface InstanceFile {
 /**
  * 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.
+ * Both hosts must agree on which groups are project-scoped, so the reading lives here.
  */
 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.
+     * Empty `tags` selects nothing, so it reads as the workspace form.
      */
     isProjectScoped(group: ConformetryInstanceGroup): boolean;
 }
 
 /**
- * Minimal JSON Schema fragment used to discover a generator's inputs.
+ * Minimal JSON Schema fragment for 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.
+ * Only `properties` and `required` are modelled, since those are what conformetry reads.
  */
 export declare interface JsonSchemaDefinition {
     [key: string]: unknown;
@@ -836,9 +639,8 @@ export declare interface MatchedInstance {
     /** How many of the template's files the instance already has. */
     readonly matchedFileCount: number;
     /**
-     * The random stand-in rendered for each placeholder nothing supplied, keyed
-     * by placeholder. Validation replaces each with the text the instance holds
-     * there. Absent or empty when every placeholder was supplied.
+     * Random stand-ins for placeholders nothing supplied, keyed by placeholder.
+     * Validation swaps each for the instance's own text there.
      */
     readonly placeholderValues?: Substitutions;
     /** Every value the template renders with, stand-ins included. */
@@ -847,14 +649,8 @@ export declare interface MatchedInstance {
 }
 
 /**
- * A run that names no directory, and has nothing else to place its output by.
- *
- * Both hosts refuse this with the same words, which is why it lives here: the
- * command-line host always needs `--directory`, and the Nx plugin needs it
- * only when no `project` or `type` locates the output, so each decides when to
- * raise it and neither words it. A silent fallback is what this replaces —
- * output written somewhere the caller never chose, reported as success. The
- * optional `hint` carries a remedy only one host has.
+ * Refuses a run that gives no output directory. Both hosts share these words;
+ * `hint` carries a remedy only one host has.
  */
 export declare const missingDirectoryError: (args: {
     generatorName: string | undefined;
@@ -862,24 +658,15 @@ export declare const missingDirectoryError: (args: {
 }) => InputError;
 
 /**
- * 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.
+ * Input that cannot be asked for: stdin is not a terminal. `prompts` would hang
+ * and exit 0, so the message names the flag.
  */
 export declare const missingInputError: (inputName: string) => InputError;
 
 /**
- * Raised when a template interpolates a placeholder nobody supplied a value
- * for.
+ * 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.
+ * Refusing is the only outcome that cannot pass for success: generation and validation would otherwise lose the same value and agree.
  */
 export declare class MissingSubstitutionError extends Error {
     constructor(args: {
@@ -916,29 +703,18 @@ declare class RenderingService {
     /**
      * 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.
+     * Explicit inputs with the same key override these.
      */
     buildNameSubstitutions(name: string): Substitutions;
     /**
      * 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.
+     * Mustache's own parser decides what counts, so comments and partials are not placeholders.
      */
     collectInterpolatedNames(template: string): string[];
     /**
-     * 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.
+     * Renders template contents with mustache, HTML escaping disabled. Throws
+     * `MissingSubstitutionError` for a placeholder with no value; `subject` names the template.
      */
     renderContent(args: {
         subject?: string;
@@ -946,12 +722,9 @@ declare class RenderingService {
         templateContent: string;
     }): string;
     /**
-     * Renders a template path with mustache, the same way contents are rendered.
+     * Renders a template path with mustache.
      *
-     * 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.
+     * Uses the same placeholders as contents, so a dunder such as `__init__` is never read as one.
      */
     renderPath(args: {
         subject?: string;
@@ -981,8 +754,7 @@ declare interface ResolveInputsFromValuesArguments {
 /**
  * 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.
+ * Both filters narrow the pairing, so an entry that survives neither drops out.
  */
 export declare interface ResolveInventoryArguments {
     readonly configuration: ConformetryConfiguration;
@@ -1001,20 +773,15 @@ declare interface SchemaInput {
 }
 
 /**
- * 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.
+ * Placeholder values for rendering a template. Derived name variants are merged
+ * under the caller's inputs, which always win.
  */
 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.
+ * Only the name and description are passed, so prompting does not depend on the configuration's shape.
  */
 export declare interface TemplateChoice {
     readonly description?: string | undefined;
@@ -1030,9 +797,8 @@ export declare interface TemplateDefinition {
     /** The template's directory name, used to identify it. */
     readonly name: string;
     /**
-     * Every placeholder the template's files and file paths interpolate. Read
-     * once here so validation knows which ones nothing supplied without
-     * reading the template again per instance. Absent means none.
+     * Every placeholder the template's files and paths interpolate. Read once
+     * here, so validation knows which nothing supplied. Absent means none.
      */
     readonly placeholderNames?: string[];
     /**
@@ -1045,15 +811,8 @@ export declare interface TemplateDefinition {
 /**
  * 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.
+ * A template's tree is laid over the instance path verbatim, so a template creates a folder by containing it.
+ * Rendering goes through `RenderingService` so validation substitutes exactly as generation did.
  */
 declare class TemplateDiscoveryService {
     private readonly renderingService;
@@ -1074,11 +833,7 @@ declare class TemplateDiscoveryService {
         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.
+     * Reads every configured generator's template folder, resolving each path once.
      */
     collectTemplates(args: {
         configuration: ConformetryConfiguration;
@@ -1087,9 +842,7 @@ declare class TemplateDiscoveryService {
     /**
      * 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.
+     * A file scope limits the count to the files it lists.
      */
     countMatchingFiles(args: {
         fileScope?: string[] | undefined;
@@ -1100,9 +853,7 @@ declare class TemplateDiscoveryService {
     /**
      * 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.
+     * Returns `undefined` when the instance is missing, which the file-existence pass reports instead.
      */
     prepareDocument(args: {
         instancePath: string;
@@ -1122,10 +873,7 @@ declare class TemplateDiscoveryService {
 /**
  * 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.
+ * `matchRatio` measures fit by file presence alone, not conformance score.
  */
 export declare interface TemplateMatch {
     readonly matchedFileCount: number;
@@ -1152,11 +900,8 @@ export declare interface UnmatchedInstance {
 }
 
 /**
- * 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.
+ * Why an instance went unmatched. Reported, not skipped: a glob asserts the
+ * directory is an instance, so no match is a finding.
  */
 export declare type UnmatchedReason = "ambiguous" | "no-match";
 

package/package.json

@@ -4,7 +4,7 @@
     "url": "https://github.com/organizzolini/codebase/issues"
   },
   "dependencies": {
-    "@conformetry/core": "0.0.77",
+    "@conformetry/core": "0.0.79",
     "@nestjs/common": "^11.1.21 || ^12.0.1",
     "jiti": "^2.7.0",
     "jsonc-parser": "^3.3.1",
@@ -24,9 +24,9 @@
     "@types/mustache": "^4.2.6",
     "@types/node": "^26.5.1",
     "@types/prompts": "^2.4.9",
-    "@vitest/coverage-v8": "^5.0.0",
+    "@vitest/coverage-v8": "^5.1.0",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.0"
+    "vitest": "^5.1.0"
   },
   "exports": {
     ".": {
@@ -68,5 +68,5 @@
     "strict": true
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.0.79"
+  "version": "0.0.81"
 }