@codependix/configuration 0.0.78 → 0.0.79

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.0.79 (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 codependix-core to 0.0.77
+
 ## 0.0.78 (2026-11-10)
 
 ### 🧱 Updated Dependencies

package/dist/src/index.d.ts

@@ -15,14 +15,8 @@ export declare interface ApplyOverridesArguments {
 export declare const CHECK_BOUNDARIES = "boundaries";
 
 /**
- * Everything `--check` accepts, in the order an error message lists them.
- *
- * Named here rather than spelled into each message, so the list a mistake is
- * measured against and the list it is told about can never drift apart. The
- * same arrangement `codometer` and `callidescope` both use, and `reports` is
- * deliberately their word spelled the same way: a configured destination has
- * gone stale is one finding across all three tools, and two names for it
- * would make the three reports unreadable together.
+ * Everything `--check` accepts, in error-message order. `reports` is the word
+ * `codometer` and `callidescope` use for stale output too.
  */
 export declare const CHECK_NAMES: string[];
 
@@ -39,23 +33,8 @@ export declare const CODEPENDIX_EXPORT_TARGETS: readonly ["both", "json", "markd
 export declare const CODEPENDIX_GRAPH_TYPES: readonly ["fileImports", "nestjsModules", "nxProjects"];
 
 /**
- * Every declared boundary rule, keyed by the graph level it judges.
- *
- * Keyed the same way `CodependixProjectConfiguration` is, and written out
- * field by field for the same reason: under `exactOptionalPropertyTypes`,
- * `Partial<Record<...>>` makes a field optional without widening its type to
- * include `undefined`, which then rejects the "unset" value every
- * default-resolution path needs to assign.
- *
- * A flat array with a `graph` discriminant would also work, and was rejected:
- * it forces a reader to know which selector keys are legal at which level,
- * which the key already says.
- *
- * `fileImports` nests by language rather than flattening to one rule array:
- * a Python file cannot import a TypeScript file or vice versa, so no edge
- * ever crosses languages, and the rule vocabularies genuinely differ (a
- * `*.types.ts` naming convention has no Python equivalent). `nestjsModules`
- * and `nxProjects` keep the flat shape every other level always had.
+ * Every declared boundary rule, keyed by the graph level it judges. Field by field, since
+ * `Partial<Record>` would reject the unset value.
  */
 export declare interface CodependixBoundariesConfiguration {
     fileImports?: CodependixFileImportsBoundariesConfiguration | undefined;
@@ -64,14 +43,8 @@ export declare interface CodependixBoundariesConfiguration {
 }
 
 /**
- * One rule stating which nodes may reach which, at one graph level.
- *
- * `forbid` reports every edge whose source matches `from` and whose target
- * matches `to`. `allow` reports the mirror image — an edge leaving `from` for
- * anywhere `to` does not claim — so it states a node's whole permitted
- * surface rather than one thing it may not touch. Written as two `kind`s of
- * one rule rather than two rule types, because a reader comparing them wants
- * to see the same three fields either way.
+ * One rule stating which nodes may reach which. `forbid` reports edges from `from` to `to`;
+ * `allow` reports edges from `from` to anything not `to`.
  */
 export declare interface CodependixBoundaryAccessRule {
     /**
@@ -84,10 +57,8 @@ export declare interface CodependixBoundaryAccessRule {
     from: CodependixBoundarySelector;
     kind: "allow" | "forbid";
     /**
-     * Why the rule exists, appended to the generated sentence.
-     *
-     * Appended rather than substituted, so no wording a configuration chooses
-     * can cost a report the rule that fired and both ends of what it fired on.
+     * Why the rule exists, appended to the generated sentence. Never substituted,
+     * so the rule and both its ends always appear in the report.
      */
     message?: string | undefined;
     /** How the rule is named in a report, and in whatever asks about it. */
@@ -97,12 +68,8 @@ export declare interface CodependixBoundaryAccessRule {
 }
 
 /**
- * One rule forbidding a cycle among a selected set of nodes.
- *
- * Deliberately narrow at TypeScript file level, where `dependency-cruiser`'s
- * `no-circular` is already the workspace's gate — see
- * `configuration/dependency-cruiser.cjs`. At Nx project level and NestJS
- * module level nothing else states it, which is where this earns its place.
+ * One rule forbidding a cycle among a selected set of nodes. Narrow at file level, where
+ * `dependency-cruiser`'s `no-circular` already gates.
  */
 export declare interface CodependixBoundaryAcyclicRule {
     kind: "acyclic";
@@ -111,36 +78,20 @@ export declare interface CodependixBoundaryAcyclicRule {
     /** How the rule is named in a report, and in whatever asks about it. */
     name: string;
     /**
-     * Selects the nodes the rule covers, defaulting to every node in the graph.
-     *
-     * A cycle is only reported when every node in it is selected: a rule scoped
-     * to one directory should not fail because of a cycle running through code
-     * it was never asked about.
+     * Selects the nodes the rule covers; every node by default. A cycle is
+     * reported only when all its nodes are selected.
      */
     nodes?: CodependixBoundarySelector | undefined;
 }
 
 /**
- * How a rule narrows which edges it judges.
- *
- * Separate from `CodependixBoundarySelector`, which picks the nodes at either
- * end: this is about the edge itself, and only the Nx level draws an edge with
- * an attribute worth narrowing on.
+ * How a rule narrows which edges it judges. Separate from the node selector: only the Nx level draws
+ * an edge worth narrowing on.
  */
 export declare interface CodependixBoundaryEdgeSelector {
     /**
-     * Judge only implicit edges, or only explicit ones.
-     *
-     * `false` is what makes a rule mean exactly what an
-     * `@nx/enforce-module-boundaries` `depConstraint` means: that rule reads
-     * import statements, so an `implicitDependencies` entry is invisible to it.
-     * `true` inverts it — useful for finding the edges declared in
-     * configuration that no import backs. Unset judges both, which is the
-     * stricter reading and the right default for a rule about what a project
-     * may depend on rather than about what it may import.
-     *
-     * Every level that is not `nx` draws only explicit edges, so a rule naming
-     * `implicit: true` there selects nothing.
+     * Judge only implicit (`true`) or only explicit (`false`) edges; unset judges
+     * both. Only the Nx level has implicit edges.
      */
     implicit?: boolean | undefined;
 }
@@ -149,18 +100,8 @@ export declare interface CodependixBoundaryEdgeSelector {
 export declare type CodependixBoundaryRule = CodependixBoundaryAccessRule | CodependixBoundaryAcyclicRule;
 
 /**
- * How a rule picks the nodes at one end of an edge.
- *
- * Four vocabularies, one node shape: an Nx project is selected by name or by
- * tag, a file by its project-relative path, a NestJS module only by its class
- * name — see `NestjsModuleGraph`, which carries no file path at all. Every
- * field is a list of globs, matched with `path.matchesGlob`, and a node
- * matches the selector when it matches every field the selector states.
- * Within one field, one glob matching is enough.
- *
- * A selector stating no field at all is refused rather than read as "every
- * node": the two are indistinguishable in a configuration file, and reading
- * it as everything turns a typo into a rule that judges the whole workspace.
+ * A rule's node picker: globs matched against each stated field. A selector stating no field is
+ * refused, not read as everything.
  */
 export declare interface CodependixBoundarySelector {
     /** Globs matched against the node's identifier. */
@@ -174,20 +115,12 @@ export declare interface CodependixBoundarySelector {
 }
 
 /**
- * Configuration authored in a `codependix.config.ts` file.
- *
- * Every field is optional: a workspace with no configuration file at all
- * resolves every graph type for every project to `target: "none"`, so
- * codependix produces nothing until it is told where to write.
+ * Configuration authored in a `codependix.config.ts`. Every field is optional: with none, codependix writes nothing.
  */
 export declare interface CodependixConfiguration {
     /**
-     * Rules every built graph is judged against, keyed by graph level.
-     *
-     * Separate from a project's own `codependix.config.ts`, which says where
-     * that project's export is written: a rule has no destination, and a
-     * violation is reported to the console and the exit code rather than
-     * published anywhere.
+     * Rules every built graph is judged against, keyed by graph level. A violation
+     * fails the run; it is never written to an export.
      */
     boundaries?: CodependixBoundariesConfiguration | undefined;
     /** Project names or roots excluded from every graph, as globs. */
@@ -195,48 +128,25 @@ export declare interface CodependixConfiguration {
     /** Project names or roots participating in graph export, as globs. */
     include?: string[] | undefined;
     /**
-     * How `nestjsModules` finds each application's container.
-     *
-     * Nothing about where an application's root module lives is assumed: a
-     * project this does not name is treated as a library.
+     * How `nestjsModules` finds each application's container. A project not
+     * named here is treated as a library.
      */
     nestjsModules?: CodependixNestjsModulesConfiguration | undefined;
     /**
-     * A project graph to read instead of resolving the working directory's.
-     *
-     * A path, relative to the workspace root, to the JSON `nx graph
-     * --file=graph.json` emits. Nx resolves a project graph from the process
-     * working directory and takes no directory argument, so this is the only
-     * way to graph a workspace the process is not standing in — a CI job that
-     * checked out one repository and graphs another, or a test with no Nx
-     * workspace under it.
-     *
-     * A supplied graph's node roots are workspace-relative and resolve against
-     * the same root every export path does.
+     * Path, relative to the workspace root, of an `nx graph --file` JSON to read
+     * instead of resolving the working directory's graph.
      */
     projectGraph?: string | undefined;
     /**
-     * Export configuration for the whole-workspace Workspace Graph.
-     *
-     * Separate from `defaults`/`projects`: the Workspace Graph is exported once
-     * for the entire repository rather than once per project, so it carries no
-     * per-project override and is unaffected by `include`/`exclude`.
-     *
-     * `--projects` and `--tags` do reach it: a run naming a selection narrows
-     * the graph's node set to the projects it named. Its destination is still
-     * read from `workspace` either way.
+     * Export configuration for the Workspace Graph, exported once for the whole
+     * repository. Unaffected by `include`/`exclude`; `--projects`/`--tags` narrow its nodes.
      */
     workspace?: CodependixWorkspaceConfiguration | undefined;
 }
 
 /**
- * Strict, per-field CLI overrides for a run's root configuration.
- *
- * Mirrors `@callidescope/configuration`'s override philosophy exactly: a
- * field may be overridden only when the configuration this run reads already
- * declared it — see `ConfigurationService.loadConfiguration`. An empty list is
- * read the same as the field being left off entirely, matching how
- * `--directories`/`--exclude` treat an empty list in callidescope.
+ * Strict per-field CLI overrides for a run's root configuration. A field may be overridden only when
+ * the file already declared it.
  */
 export declare interface CodependixConfigurationOverrides {
     /** Overrides `exclude` for this run. */
@@ -246,11 +156,8 @@ export declare interface CodependixConfigurationOverrides {
 }
 
 /**
- * Validates a codependix configuration file's contents.
- *
- * Zod strips unknown keys rather than rejecting them, so a configuration
- * written for a newer codependix still loads under an older one instead of
- * failing on a field it has no opinion about.
+ * Validates a codependix configuration file's contents. Unknown keys are
+ * stripped, not rejected, so newer configurations still load.
  */
 export declare const codependixConfigurationSchema: z.ZodObject<{
     boundaries: z.ZodOptional<z.ZodObject<{
@@ -448,21 +355,13 @@ export declare const codependixConfigurationSchema: z.ZodObject<{
 }, z.core.$strip>;
 
 /**
- * Where a graph type's export lands for a project.
- *
- * `both` writes the JSON and the Markdown export together. Named explicitly
- * rather than inferred from which destinations are configured, so a project
- * carrying a `json` destination it does not want written yet can leave it in
- * place with the target set to `markdown`.
+ * Where a graph type's export lands. Named explicitly rather than inferred, so
+ * a `json` path can stay configured while unused.
  */
 export declare type CodependixExportTarget = "both" | "json" | "markdown" | "none";
 
 /**
- * `boundaries.fileImports`'s rules, nested by language.
- *
- * Separate from `CodependixBoundariesConfiguration` so both the authored and
- * resolved shapes (see `ResolvedCodependixFileImportsBoundariesConfiguration`)
- * can name it once rather than repeating the two-field object inline.
+ * `boundaries.fileImports`'s rules, nested by language. Separate so authored and resolved shapes can both name it.
  */
 export declare interface CodependixFileImportsBoundariesConfiguration {
     python?: CodependixBoundaryRule[] | undefined;
@@ -485,13 +384,8 @@ export declare interface CodependixJsonOutput {
 }
 
 /**
- * Where a graph's Markdown export is written.
- *
- * Naming `anchor` places the export inside a named anchor block in the file at
- * `path` — an existing Markdown file such as a project's `README.md`, defaulted
- * to `README.md` when `path` is left out. Leaving `anchor` unset instead writes
- * the export as the whole contents of a standalone file, whose `path` must then
- * be given explicitly since there is no default worth guessing for it.
+ * Where a graph's Markdown export is written. With `anchor`, it splices into that block of `path`;
+ * without, `path` is standalone.
  */
 export declare interface CodependixMarkdownOutput {
     anchor?: string | undefined;
@@ -501,12 +395,8 @@ export declare interface CodependixMarkdownOutput {
 /** How the NestJS module graph finds the applications it explores. */
 export declare interface CodependixNestjsModulesConfiguration {
     /**
-     * The root module each NestJS application boots from, keyed by Nx project
-     * name.
-     *
-     * A project named here is an application, and its container is rooted in
-     * this module. A `framework:nestjs` project not named here is a library, and
-     * gets a synthetic root built from every module it defines instead.
+     * The root module of each NestJS application, keyed by Nx project name.
+     * A `framework:nestjs` project not named here is a library.
      */
     rootModules?: Record<string, CodependixNestjsRootModule> | undefined;
 }
@@ -520,12 +410,8 @@ export declare interface CodependixNestjsRootModule {
 }
 
 /**
- * A project's export configuration, keyed by graph type.
- *
- * Written out field by field rather than as `Partial<Record<...>>`: under
- * `exactOptionalPropertyTypes`, `Partial` makes a field optional without
- * widening its type to include `undefined`, which then rejects the very
- * "unset" value every default-resolution path needs to assign.
+ * A project's export configuration, keyed by graph type. Written field by field, since
+ * `Partial<Record>` would reject the unset value.
  */
 export declare interface CodependixProjectConfiguration {
     fileImports?: CodependixGraphOutput | undefined;
@@ -534,12 +420,8 @@ export declare interface CodependixProjectConfiguration {
 }
 
 /**
- * Validates a project's own `codependix.config.ts`, keyed by graph type.
- *
- * The same shape a project's own file spreads `projectDefaults` into, and the
- * same shape the root configuration's schema no longer carries — a project's
- * export configuration is validated from its own file rather than from a root
- * `projects` dict.
+ * Validates a project's own `codependix.config.ts`, keyed by graph type, since
+ * the root schema no longer carries project exports.
  */
 export declare const codependixProjectConfigurationSchema: z.ZodObject<{
     fileImports: z.ZodOptional<z.ZodObject<{
@@ -590,11 +472,8 @@ export declare const codependixProjectConfigurationSchema: z.ZodObject<{
 }, z.core.$strip>;
 
 /**
- * The `--projects` and `--tags` arguments as the command line captured them.
- *
- * Comma-separated strings rather than lists: the host captures raw option
- * text and hands it over, and splitting it is resolution, which belongs
- * beside the configuration file this package already parses.
+ * The `--projects` and `--tags` arguments as the command line captured them: comma-separated strings,
+ * split during resolution.
  */
 export declare interface CodependixSelectionArguments {
     /** `false` for `--no-dependencies` — see `ResolvedCodependixSelection`. */
@@ -604,12 +483,8 @@ export declare interface CodependixSelectionArguments {
 }
 
 /**
- * The Workspace Graph's export configuration, keyed by graph type.
- *
- * All three graph types are declared: `codependix-file-imports` and
- * `codependix-nestjs-modules` each build a whole-workspace aggregate graph the
- * same way `codependix-nx-projects` always has, spanning every project rather
- * than one — see each package's own `workspace-graph` module.
+ * The Workspace Graph's export configuration, keyed by graph type. All three graph types are declared,
+ * each spanning every project.
  */
 export declare interface CodependixWorkspaceConfiguration {
     fileImports?: CodependixGraphOutput | undefined;
@@ -618,11 +493,8 @@ export declare interface CodependixWorkspaceConfiguration {
 }
 
 /**
- * File names a project's own configuration may take, beside its root.
- *
- * Searched in order, so a project carrying both a TypeScript and a JSON
- * configuration file gets the TypeScript one. The main configuration is never
- * searched for: its path is always named.
+ * File names a project's own configuration may take beside its root, searched
+ * in order: TypeScript before JSON. The main configuration is never searched for.
  */
 export declare const CONFIGURATION_FILE_NAMES: readonly ["codependix.config.ts", "codependix.config.mts", "codependix.config.cts", "codependix.config.js", "codependix.config.mjs", "codependix.config.cjs", "codependix.config.json"];
 
@@ -643,21 +515,11 @@ declare class ConfigurationLoaderService {
     /** Reads what a configuration module exported, through either interop shape. */
     private readDefaultExport;
     /**
-     * Looks for a project's own configuration file, exactly at its root.
-     *
-     * This never walks upward: a project's own file must be colocated with it,
-     * and walking upward would find the workspace root's configuration — or
-     * another project's, in a nested layout — instead of correctly reporting
-     * that this project has none.
+     * Looks for a project's own configuration file at its root only, never upward, which would find the workspace's.
      */
     findProjectConfigurationFile(projectRoot: string): string | undefined;
     /**
-     * Walks upward from the process cwd looking for the workspace root.
-     *
-     * Used to resolve a configuration path given relative to that root even when
-     * the command was invoked from a nested directory, which is what a task
-     * runner does whenever it sets the cwd to a project rather than the
-     * workspace.
+     * Walks upward from the cwd to the workspace root, so a task runner's nested cwd still resolves configuration paths.
      */
     findWorkspaceRoot(): string | undefined;
     /** Loads a configuration module, choosing the reader by extension. */
@@ -668,10 +530,7 @@ declare class ConfigurationLoaderService {
     /** Loads and validates one configuration file at a resolved path. */
     parseConfigurationFile(resolvedPath: string): Promise<CodependixConfiguration>;
     /**
-     * Reads the main configuration file at the path it was told to.
-     *
-     * The path is required: nothing searches for a file, and no file is not a
-     * configuration that resolves every graph to `target: "none"`.
+     * Reads the main configuration file at the given path. The path is required: a missing file is an error, never an empty configuration.
      */
     readAuthoredConfiguration(args: {
         configurationPath: string;
@@ -681,14 +540,9 @@ declare class ConfigurationLoaderService {
 }
 
 /**
- * Provides everything one run is configured by: the configuration file, the
- * command line resolved over it, and each project's own resolved output.
- *
- * `ConfigurationService` is the only thing this module exports, and the only
- * service `@codependix/configuration` makes public. File loading, override
- * resolution, option parsing, and run-mode selection are providers here
- * rather than modules of their own, so a caller asking what a run is
- * configured to do has exactly one place to ask.
+ * Provides everything one run is configured by: the configuration file, the command line over it,
+ * and each project's own output. `ConfigurationService` is the only export; the rest are providers,
+ * so one place answers what a run does.
  */
 export declare class ConfigurationModule {
 }
@@ -705,14 +559,8 @@ export declare class ConfigurationPathRequiredError extends Error {
 }
 
 /**
- * Loads, validates, and resolves codependix configuration files.
- *
- * Loading and per-project resolution are kept apart on purpose: a project's
- * actual export configuration depends on both the global defaults and its own
- * name, so resolving it eagerly for every project in the workspace would mean
- * redoing that work for a workspace whose graphs run against a filtered subset
- * of projects. `resolveForProject` is called once per project that is
- * actually built instead.
+ * Loads, validates, and resolves codependix configuration. Per-project resolution is kept apart
+ * from loading, so it runs only for projects actually built.
  */
 export declare class ConfigurationService {
     private readonly configurationLoaderService;
@@ -727,79 +575,37 @@ export declare class ConfigurationService {
     /** Whether a project's name or its root matches at least one glob. */
     private matchesAnyName;
     /**
-     * Fills in every graph level a `boundaries` block may leave out.
-     *
-     * Every level resolves to a list rather than to `undefined`, so a caller
-     * walks all of them without asking which ones were configured — the same
-     * reason `include` resolves to a list nobody wrote. `fileImports` resolves
-     * both of its languages the same way, one level deeper.
+     * Fills in every graph level a `boundaries` block may omit, each as a list, so callers need not ask which were configured.
      */
     private resolveBoundaries;
     /** Applies defaults to one graph type's export configuration. */
     private resolveGraphOutput;
     /**
-     * Splits the `--projects` and `--tags` arguments into lists, and reads
-     * `--no-dependencies` as building over the selected projects alone.
-     *
-     * Empty entries are dropped, so a trailing comma and a doubled one are both
-     * read as the author meant them rather than as a glob matching nothing.
+     * Splits `--projects` and `--tags` into lists, and reads `--no-dependencies` as building over the selection alone. Blank entries are dropped.
      */
     private resolveSelection;
     /** Splits one comma-separated argument, trimming and dropping blanks. */
     private splitSelectionArgument;
     /**
-     * Whether a project participates in graph export at all.
-     *
-     * A project matches when something claims it — an `include` glob, a
-     * `--projects` glob, or a `--tags` tag — and no `exclude` glob claims its
-     * name or root. The command line **widens** what the configuration already
-     * selects rather than replacing it; `exclude` wins over all three, because
-     * a flag that could resurrect an excluded project would make `exclude`
-     * advisory.
-     *
-     * `projectRoot` and `projectTags` are optional: a caller with neither handy
-     * still resolves against globs written against project names.
+     * Whether a project takes part in graph export: matched by `include` or the command line, and not claimed by `exclude`.
+     * `exclude` wins over flags.
      */
     isProjectIncluded(args: ProjectSelectionArguments): boolean;
     /**
-     * Whether a project is in the set a run's command line narrowed to.
-     *
-     * A run naming no selection selects **everything**, which is what keeps the
-     * whole-workspace graph and the boundary gate judging every project by
-     * default. Naming one narrows both to what it named.
-     *
-     * This is where `--projects`/`--tags` differ from `include`: `include` is
-     * about which projects have exports written for them, and never reaches the
-     * workspace graph or the gate. A selection reaches all three.
+     * Whether a project is in the command line's selection. Naming none selects every project.
+     * `include` never reaches the graph or gate, only selections do.
      */
     isProjectSelected(args: ProjectSelectionArguments): boolean;
     /**
-     * Loads and validates a codependix configuration file.
-     *
-     * The path is required and must exist — a typo in a task runner's
-     * arguments should fail rather than quietly resolving every graph to
-     * `target: "none"`. Nothing is searched for.
+     * Loads and validates a configuration file. The path must exist; nothing is searched for, so a typo fails rather than resolving to nothing.
      */
     loadConfiguration(args: LoadConfigurationArguments): Promise<ResolvedCodependixConfiguration>;
     /**
-     * Loads and validates one project's own `codependix.config.ts`, or
-     * `undefined` when it has none.
-     *
-     * Searched for exactly at `projectRoot` — see
-     * `ConfigurationLoaderService.findProjectConfigurationFile` — rather than
-     * named by a path the way `loadConfiguration`'s file is: a project's file is either colocated with it or it does not
-     * exist, and a project with none produces no per-project output rather than
-     * inheriting one from a parent directory.
+     * Loads one project's own `codependix.config.ts`, or `undefined`. Searched for only at its root, never inherited from a parent.
      */
     loadProjectConfiguration(args: LoadProjectConfigurationArguments): Promise<CodependixProjectConfiguration | undefined>;
     /**
-     * Parses a comma-separated list option, dropping blank entries.
-     *
-     * One of the six command-line methods this service forwards to the
-     * `input` and flag-resolution providers it owns. They are stated here
-     * rather than exported alongside it because this package makes exactly one
-     * service public: a host asking what a run is configured to do — from its
-     * configuration file or from its flags — asks `ConfigurationService`.
+     * Parses a comma-separated list, dropping blanks. Forwarded here, since `ConfigurationService` is the one public service.
      */
     parseCommaDelimitedOption(value: string | undefined): string[];
     /** Parses a valueless boolean flag, which is present or it is not. */
@@ -809,48 +615,20 @@ export declare class ConfigurationService {
     /** Parses a path option that falls back to the working directory. */
     parsePathOption(value: string | undefined): string;
     /**
-     * Returns the main configuration path, refusing one that is missing.
-     *
-     * No file is searched for, so every host — the command line, the Nx
-     * executor, the Nx plugin — must be handed a path. `surface` names the
-     * setting the caller took it from (for example "`--config` flag"), which is
-     * what the refusal tells the user to fix. Absent and blank are the same.
+     * Returns the main configuration path, refusing a missing or blank one. `surface` names its source in the refusal.
      */
     requireConfigurationPath(configurationPath: string | undefined, surface: string): string;
     /**
-     * Fills in every field a configuration file may leave out.
-     *
-     * Exposed so a host embedding codependix can hand over a configuration
-     * object it assembled itself and get the same shape a configuration file
-     * produces.
+     * Fills in every field a configuration file may omit. Exposed so a host can pass an assembled configuration and get the file's shape.
      */
     resolveConfiguration(configuration: CodependixConfiguration, selection?: CodependixSelectionArguments): ResolvedCodependixConfiguration;
     /**
-     * Resolves one project's export configuration for one graph type.
-     *
-     * A project's own `codependix.config.ts`, when it has one, is read exactly
-     * as loaded — no merge against a workspace-wide default happens here, since
-     * spreading the root-exported `projectDefaults` already happened when the
-     * project's own file was authored. A project excluded by the configured
-     * `include`/`exclude` globs, or one that has no configuration file of its
-     * own at all, always resolves to `target: "none"`: the former because a
-     * project excluded from graph export should not need every field rewritten
-     * to `"none"` by hand, the latter because a project matched by `include`
-     * with no file of its own has nothing to export, even though it still
-     * contributes to the Workspace Graph and is judged by boundary rules.
+     * Resolves one project's export configuration for one graph type. An excluded project, or one without
+     * its own file, resolves to `target: "none"`.
      */
     resolveForProject(args: ResolveForProjectArguments): ResolvedCodependixGraphOutput;
     /**
-     * Resolves the Workspace Graph's export configuration for one graph type.
-     *
-     * A Workspace Graph is exported once for the whole repository rather than
-     * once per project, so it has no per-project override and is unaffected by
-     * `include`/`exclude` — those two apply only to `resolveForProject`.
-     *
-     * `--projects` and `--tags` do reach it, through the node set rather than
-     * through this: a run naming a selection draws the graph over the projects
-     * it named. Where that graph lands is still read from `workspace`, keyed by
-     * `graphType`.
+     * Resolves the Workspace Graph's export for one graph type. `include` and `exclude` never apply to it.
      */
     resolveForWorkspace(configuration: ResolvedCodependixConfiguration, graphType: CodependixGraphType): ResolvedCodependixGraphOutput;
     /**
@@ -868,12 +646,8 @@ export declare class ConfigurationService {
 export declare const DEFAULT_EXPORT_TARGET: CodependixExportTarget;
 
 /**
- * Projects that participate in graph export when a configuration names none.
- *
- * Deliberately empty: participation is always declared. A configuration that
- * names `defaults` but no `include` exports nothing rather than quietly
- * covering the whole workspace, which is what lets a later widening argument
- * mean something — a union with `["**"]` as its base can never add a project.
+ * Participating projects when a configuration names none. Deliberately empty:
+ * export must be declared, never silently widened to the whole workspace.
  */
 export declare const DEFAULT_INCLUDE_GLOBS: readonly [];
 
@@ -881,15 +655,9 @@ export declare const DEFAULT_INCLUDE_GLOBS: readonly [];
 export declare const DEFAULT_MARKDOWN_PATH = "README.md";
 
 /**
- * Reads the command line into what the run will do.
- *
- * Internal to the `configuration` module rather than a module of its own:
- * resolving the command line is half of answering "what is this run actually
- * configured to do", and `ConfigurationService` is the one public way to ask.
- * `codometer-cli` and `callidescope-cli` still carry a `run-plan` module of
- * this shape inside their hosts — and, deliberately, the same `--check
- * reports` spelling, since a stale configured destination is one finding
- * across all three.
+ * Reads the command line into what the run will do. Internal to this module, since
+ * `ConfigurationService` is the one public way to ask. The `--check reports` spelling matches the
+ * sibling CLIs, since a stale destination is one finding across all three.
  */
 declare class FlagResolutionService {
     private readonly inputService;
@@ -899,58 +667,33 @@ declare class FlagResolutionService {
     /** The mode nothing was selected for, so an error path has one to return. */
     private emptyMode;
     /**
-     * Asks which of the three things a run with no flags at all should do.
-     *
-     * Nothing is inferred: a session that cannot be asked fails rather than
-     * defaulting to a write nobody requested, and a run that quietly did
-     * nothing and exited 0 is worse than either.
+     * Asks what a run with no flags should do. Nothing is inferred: an unanswerable session fails rather
+     * than writing something nobody requested.
      */
     private promptForMode;
     /**
-     * Reads the `--check` value into the set of things the run fails on.
-     *
-     * A flag passed without a value arrives as `true` and is a mistake rather
-     * than a shorthand: read as "gate nothing" it would be a gate that cannot
-     * fail, and `--check "$GATES"` with the variable unset would pass forever
-     * over a workspace whose every rule was broken — worse than no gate at all,
-     * because it looks like protection.
+     * Reads `--check` into the things the run fails on. A bare `--check` is refused: a gate that cannot
+     * fail looks like protection.
      */
     private readCheckNames;
     /** Keeps the names `--check` knows and complains about the rest. */
     private validateCheckNames;
     /**
-     * Reads the flags into what the run writes and what it fails on.
-     *
-     * `--write --check reports` is refused rather than obeyed: nothing can be
-     * stale immediately after being written, so a run asking for both has
-     * misunderstood one of them and would pass whatever it was meant to catch.
-     * `--write --check boundaries` is legal for the mirror-image reason — a
-     * boundary has no destination to be stale, so writing every export and
-     * judging every graph in one run is two independent things, not a
-     * contradiction.
+     * Reads the flags into what the run writes and fails on. `--write --check reports` is refused:
+     * nothing is stale right after being written.
      */
     selectMode(options: MapCommandOptions): Promise<RunModeSelection>;
     /**
-     * Whether a run reads or rewrites the files its exports live in.
-     *
-     * `--check boundaries` alone reads no destination and writes nothing, so it
-     * leaves every committed export exactly as it found it — which is what
-     * makes it safe on a branch, where the exports are expected to be behind.
+     * Whether a run reads or rewrites its exports. `--check boundaries` alone touches no file, so it is
+     * safe on a branch.
      */
     touchesFiles(mode: RunMode): boolean;
 }
 
 /**
- * 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 attempted, and the fix is to retype the
- * flags. Only the wording varies, which is what the factories below do.
- *
- * Sits beside the constants because that is where every error class in this
- * repository lives — the project structure rule has no `errors` suffix, and
- * the Constant File Shape rule whitelists `class X extends Error` for exactly
- * this.
+ * Thrown when a command line cannot be turned into a run. One class rather than one per cause:
+ * every cause means nothing ran and the flags need retyping. Only the wording varies, by the
+ * factories below. Sits here because the constants rule whitelists error classes.
  */
 export declare class InputError extends Error {
     constructor(message: string);
@@ -968,38 +711,21 @@ declare class InputService {
     /** 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 did nothing
-     * reads as one that succeeded. `isTTY` is read as falsy rather than
-     * coerced: `@types/node` calls it a `boolean`, so lint rejects a coercion.
+     * Refuses a prompt nobody can answer: `prompts` would exit 0 on non-TTY stdin having done nothing.
      */
     private assertCanPrompt;
     /**
-     * Parses a comma-separated list option, dropping blank entries.
-     *
-     * Mirrors `@callidescope/configuration`'s `InputService` exactly: an absent
-     * flag resolves to an empty list rather than `undefined`, so a caller
-     * overriding a configured list treats "the flag was left off" and "the flag
-     * named nothing" the same way.
+     * Parses a comma-separated list, dropping blank entries. An absent flag is an empty list, so "left off" and "named nothing" behave the same.
      */
     parseCommaDelimitedOption(value: string | undefined): string[];
     /**
-     * Parses a valueless boolean flag, which is present or it is not.
-     *
-     * Commander passes `undefined` for a flag carrying no value, so the flag
-     * appearing at all is what makes it true; reading that as false would turn
-     * every such flag permanently off.
+     * Parses a valueless boolean flag: present means true. Commander passes `undefined`, so reading that as false would disable every such flag.
      */
     parseFlagOption(value: boolean | undefined): boolean;
     /** Trims an optional string option, treating blank as absent. */
     parseOptionalOption(value: string | undefined): string | undefined;
     /**
-     * Parses a path option that falls back to the working directory.
-     *
-     * Left unresolved: the caller resolves it against its own root, and
-     * resolving twice makes a relative path ambiguous about which it meant.
+     * Parses a path option, defaulting to the working directory. Left unresolved, since resolving twice makes a relative path ambiguous.
      */
     parsePathOption(value: string | undefined): string;
     /** Prompts for one value out of a fixed set of choices. */
@@ -1029,20 +755,14 @@ export declare interface LoadProjectConfigurationArguments {
 /** Command-line options `codependix` accepts. */
 export declare interface MapCommandOptions {
     /**
-     * The set of findings `--check` gates, unparsed.
-     *
-     * `true` is the flag written with no value at all, which is refused rather
-     * than read as a shorthand — see `ConfigurationService.selectMode`.
+     * The findings `--check` gates, unparsed. `true` (a bare flag) is refused,
+     * not read as a shorthand; see `ConfigurationService.selectMode`.
      */
     check?: string | true | undefined;
     config?: string | undefined;
     /**
-     * Whether `--projects`/`--tags` build over the named projects' dependency
-     * closure too — `false` for `--no-dependencies`.
-     *
-     * `undefined` when neither `--dependencies` nor `--no-dependencies` was
-     * given, which builds over the closure. Inert without a selection, since
-     * every project is then both built and judged.
+     * Whether `--projects`/`--tags` also build their dependency closure; `false`
+     * for `--no-dependencies`. Inert without a selection.
      */
     dependencies?: boolean | undefined;
     directory?: string | undefined;
@@ -1050,19 +770,12 @@ export declare interface MapCommandOptions {
     exclude?: string[] | undefined;
     /**
      * Builds, checks, and writes the `fileImports` graph type for this run.
-     *
-     * `undefined` when neither `--file-imports` nor `--no-file-imports` was
-     * given, which leaves the graph type enabled — the behavior every run had
-     * before this flag existed.
+     * Unset leaves it enabled.
      */
     fileImports?: boolean | undefined;
     /**
-     * What `--format` prints to standard output, unparsed.
-     *
-     * Defaults to `"markdown"` when the flag was left off entirely — unlike
-     * codometer's `--format`, which falls back to a resolved configuration
-     * field, codependix's configuration declares no such field, so the default
-     * is a fixed constant instead.
+     * What `--format` prints to standard output, unparsed. Defaults to
+     * `"markdown"`, a fixed constant rather than a configured field.
      */
     format?: string | undefined;
     /** Overrides `include` for this run. Refused when never configured. */
@@ -1073,10 +786,8 @@ export declare interface MapCommandOptions {
      */
     jsonOutput?: string | undefined;
     /**
-     * Writes every active graph type's rendered diagram, combined into one
-     * Markdown file at this path — each type's own anchor-spliced section,
-     * the same splicing `DeliveryService` applies per project, applied here to
-     * one shared destination instead.
+     * Writes every active graph type's rendered diagram into one Markdown file
+     * at this path, each as an anchor-spliced section.
      */
     markdownOutput?: string | undefined;
     /** Builds, checks, and writes the `nestjsModules` graph type for this run. */
@@ -1096,41 +807,21 @@ export declare interface MapCommandOptions {
 }
 
 /**
- * A required value 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. This refuses to become that silent
- * green no-op.
+ * A required value that cannot be asked for without a terminal. `prompts` would
+ * exit 0 having done nothing, so this refuses instead.
  */
 export declare const missingInputError: (subject: string) => InputError;
 
 /**
- * Applies strict, per-field CLI overrides to an already-resolved
- * configuration.
- *
- * Mirrors `@callidescope/configuration`'s `FlagResolutionService` philosophy
- * exactly: a flag may override a value the configuration already declares,
- * and is refused when the configuration never declared that field at all.
- * Kept apart from `ConfigurationService` so the resolution logic — and the
- * file-length budget it would otherwise share with loading, boundary
- * defaulting, and per-project resolution — is stated and tested once, on its
- * own.
+ * Applies strict, per-field CLI overrides to a resolved configuration. A flag may override a declared
+ * value, and is refused for a field the configuration never declared. Kept apart from
+ * `ConfigurationService` to keep that file within its length budget.
  */
 declare class OverrideResolutionService {
     constructor();
     /**
-     * Applies one list override, refusing it when the author never declared
-     * the field it names.
-     *
-     * Checked against `authored` — the configuration exactly as parsed, before
-     * `include`/`exclude` are defaulted — rather than against the resolved
-     * value: `ConfigurationService.resolveConfiguration` fills in
-     * `DEFAULT_INCLUDE_GLOBS`/`[]` for a field the author never wrote, so the
-     * resolved value is never itself `undefined`. Checking there would make
-     * every override legal regardless of what the configuration actually
-     * declared, which is the opposite of the precedence rule this mirrors.
-     *
-     * An empty override list is read the same as no override at all.
+     * Refuses an override for a field the author never declared. Checked against the authored config,
+     * since resolution fills defaults.
      */
     private resolveOverride;
     /**
@@ -1145,45 +836,30 @@ export declare interface ProjectSelectionArguments {
     configuration: ResolvedCodependixConfiguration;
     projectName: string;
     /**
-     * The project's root, relative to the workspace, as read from the Nx
-     * project graph.
-     *
-     * Optional so a caller with no root handy — a test, or a host that only
-     * knows a project by name — still resolves against `include`/`exclude`
-     * globs written against project names.
+     * The project's root, relative to the workspace. Optional for a caller that
+     * knows the project only by name.
      */
     projectRoot?: string | undefined;
     /**
-     * The project's own Nx tags, for matching `--tags`.
-     *
-     * Optional for the same reason `projectRoot` is: a caller that knows a
-     * project only by name still resolves against everything else.
+     * The project's own Nx tags, for matching `--tags`. Optional, as `projectRoot` is.
      */
     projectTags?: string[] | undefined;
 }
 
 /**
- * A prompt someone dismissed without answering.
- *
- * Worded apart from a prompt that resolved to something unrecognized:
- * pressing escape is ordinary, and reporting it as a crash sends the reader
- * debugging for nothing.
+ * A prompt dismissed without an answer. Worded apart from an unrecognized
+ * answer, since escape is ordinary, not a crash.
  */
 export declare const promptCancelledError: (subject: string) => InputError;
 
 /**
- * Marks the workspace root during an upward search from the process cwd.
- *
- * A package manifest is deliberately not one of them: every project in the
- * workspace carries one, so the search would stop at the nearest project
- * rather than the root a configuration path was written relative to.
+ * Root markers for an upward search from the cwd. Not package manifests: every
+ * project has one, so the search would stop early.
  */
 export declare const REPOSITORY_ROOT_MARKERS: readonly [".git", "pnpm-workspace.yaml"];
 
 /**
- * Every graph level's declared rules, with a level naming none resolved to an
- * empty list rather than left unset — so a caller iterates every level
- * without asking whether each one was configured.
+ * Every level's declared rules, resolved to an empty list when unset, so callers iterate every level unconditionally.
  */
 export declare interface ResolvedCodependixBoundariesConfiguration {
     fileImports: ResolvedCodependixFileImportsBoundariesConfiguration;
@@ -1192,13 +868,8 @@ export declare interface ResolvedCodependixBoundariesConfiguration {
 }
 
 /**
- * Configuration with every default applied.
- *
- * Carries no per-project state at all: a project's own export configuration
- * lives in its own colocated `codependix.config.ts`, loaded on demand by
- * `ConfigurationService.loadProjectConfiguration` and handed to
- * `resolveForProject` — which is also where `include` and `exclude` globs
- * are applied.
+ * Configuration with every default applied. Carries no per-project state: that lives in each project's
+ * own `codependix.config.ts`.
  */
 export declare interface ResolvedCodependixConfiguration {
     boundaries: ResolvedCodependixBoundariesConfiguration;
@@ -1209,12 +880,8 @@ export declare interface ResolvedCodependixConfiguration {
     /** A project graph to read instead of the working directory's, if named. */
     projectGraph: string | undefined;
     /**
-     * What `--projects` and `--tags` named, resolved.
-     *
-     * Carried on the resolved configuration rather than passed alongside it so
-     * that everything already handed a configuration — the export passes, the
-     * workspace graph, and the boundary gate — sees the same selection without
-     * a second argument threaded through each of them.
+     * What `--projects` and `--tags` named, resolved. Carried here so every
+     * consumer of the configuration sees the same selection.
      */
     selection: ResolvedCodependixSelection;
     workspace: CodependixWorkspaceConfiguration;
@@ -1243,21 +910,12 @@ export declare interface ResolvedCodependixMarkdownOutput {
 }
 
 /**
- * A run's project selection, split and trimmed.
- *
- * Both lists empty means no selection was made at all, which is not the same
- * as a selection that matches nothing: an absent selection leaves the
- * whole-workspace graph and the boundary gate judging every project, while a
- * selection naming something narrows both to what it names.
+ * A run's project selection, split and trimmed. Empty means no selection at all, not one matching nothing.
  */
 export declare interface ResolvedCodependixSelection {
     /**
-     * Whether graphs are built over the selected projects' dependency closure,
-     * or over the selected projects alone.
-     *
-     * `true` unless `--no-dependencies` was given. Either way only the selected
-     * projects are judged: a finding charged to a dependency is reported as a
-     * note rather than failing the run.
+     * Whether graphs build over the selected projects' dependency closure, or
+     * over them alone. Only selected projects are judged; dependencies get notes.
      */
     dependencies: boolean;
     /** Globs matched against a project's name or its workspace-relative root. */
@@ -1270,26 +928,15 @@ export declare interface ResolvedCodependixSelection {
 export declare interface ResolveForProjectArguments extends ProjectSelectionArguments {
     graphType: CodependixGraphType;
     /**
-     * The project's own loaded `codependix.config.ts`, or `undefined` when it
-     * has none — see `ConfigurationService.loadProjectConfiguration`.
-     *
-     * Read as-is rather than merged with anything else: a project's own file
-     * already spreads the root-exported `projectDefaults` at authoring time, so
-     * whatever `loadProjectConfiguration` returns is the complete statement of
-     * that project's export configuration. A project naming no file of its own
-     * resolves to `target: "none"` regardless of `include`/`exclude` — it
-     * simply has nothing to export.
+     * The project's own loaded `codependix.config.ts`, or `undefined` when it has
+     * none. Read as-is, never merged; no file means `target: "none"`.
      */
     projectConfiguration: CodependixProjectConfiguration | undefined;
 }
 
 /**
- * What a command line naming no mode at all is asked to choose between.
- *
- * Three choices rather than the two `--check`/`--write` used to offer, since
- * `--check` now names which finding it gates. Kept as a prompt rather than
- * defaulted to anything: a run that silently did nothing and exited 0 is the
- * failure this whole flag arrangement exists to prevent.
+ * Choices offered when no mode is named. Never defaulted: a silent no-op that
+ * exits 0 is the failure to avoid.
  */
 export declare const RUN_MODE_CHOICES: readonly ["boundaries", "reports", "write"];
 

package/package.json

@@ -4,7 +4,7 @@
     "url": "https://github.com/organizzolini/codebase/issues"
   },
   "dependencies": {
-    "@codependix/core": "0.0.76",
+    "@codependix/core": "0.0.77",
     "@nestjs/common": "^11.1.21 || ^12.0.1",
     "jiti": "^2.7.0",
     "prompts": "^2.4.2",
@@ -63,5 +63,5 @@
     "strict": true
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.0.78"
+  "version": "0.0.79"
 }