@codometer/measurement 0.0.77 → 0.0.79

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 0.0.79 (2026-11-11)
+
+### 🚀 Features
+
+- **codometer:** ✨ tighten the comment budgets and shorten every comment over them ([#2262](https://github.com/organizzolini/codebase/pull/2262), [#2261](https://github.com/organizzolini/codebase/issues/2261))
+
+### 🧱 Updated Dependencies
+
+- Updated codometer-configuration to 0.0.79
+- Updated codometer-languages to 0.0.79
+- Updated codometer-core to 0.0.79
+
+## 0.0.78 (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 codometer-configuration to 0.0.78
+- Updated codometer-languages to 0.0.78
+- Updated codometer-core to 0.0.78
+
 ## 0.0.77 (2026-11-10)
 
 ### 🧱 Updated Dependencies

package/dist/src/index.d.ts

@@ -32,14 +32,9 @@ declare interface CreateIgnoreScopeArguments {
 /** Input to the custom statistics step. */
 export declare interface CustomizationInput {
     /**
-     * Every `comment`-selector counter's own measurements, keyed by its
-     * statistic's label.
+     * Each `comment` counter's measurements, keyed by its statistic's label.
      *
-     * Built by measuring the counters `buildCommentCounters` returns, then
-     * merging the two results back together by label — the languages package
-     * measures a counter naming a declaration kind and one naming a language
-     * through two different calls, but a label belongs to exactly one custom
-     * statistic either way.
+     * Merged by label from both measurers, since a label names exactly one statistic.
      */
     commentCounts: Record<string, CommentMeasurement[]>;
     /** Every file of the target being counted over. */
@@ -56,50 +51,26 @@ export declare class CustomizationModule {
 }
 
 /**
- * Counts the conventions a repository holds itself to.
+ * Counts the conventions a repository holds itself to. Which counters apply comes from configuration, not this package.
  *
- * The languages a repository is written in are the same everywhere; what a
- * `*.service.ts` means, or whether a static method is something to keep an
- * eye on, is not — which is why these counters come from the configuration
- * rather than from this package.
- *
- * A counter measures files by path, declarations by shape, or a comment
- * budget by length. The file half is done here; the declaration half is
- * tallied by the TypeScript analyzer during the walk it already makes, and
- * the comment half by `@codometer/languages`' comment services — both arrive
- * here as counts to be labelled.
+ * Files are measured here; declaration and comment counts arrive from `@codometer/languages`.
  */
 export declare class CustomizationService {
     constructor();
     /** Turn a `comment`-selector statistic's own breaches into its result. */
     private buildCommentResult;
     /**
-     * Counts the target's files that at least one of the globs claims.
-     *
-     * A file matching several globs of the same counter is one file, not
-     * several: the counter asks how many files there are, not how many times
-     * they matched.
+     * Counts the files claimed by at least one glob; a file matching several globs counts once.
      */
     private countMatches;
     /** Count every configured statistic over the discovered files. */
     analyze({ commentCounts, files, statistics, symbolCounts, }: CustomizationInput): CustomStatisticResult[];
     /**
-     * Pick out the counters `@codometer/languages`' comment services have to
-     * measure.
-     *
-     * Handed to those services rather than measured again here: a `comment`
-     * selector names a language or a documentable kind, and turning that into a
-     * budget is this package's business, not the tokenizer's. One list, mirroring
-     * the selector field for field — which counter a given measurer takes is
-     * decided by each measurer, which selects from the list by reading `kind`.
+     * Picks the counters `@codometer/languages`' comment services measure. Each measurer selects its own by `kind`.
      */
     buildCommentCounters(statistics: CustomizationInput["statistics"]): CommentCounter[];
     /**
-     * Pick out the counters the TypeScript analyzer has to tally.
-     *
-     * Handed to that analyzer rather than parsed again here: it already walks
-     * every source file, and a second walk would double the slowest part of a
-     * run to learn what the first one passed straight over.
+     * Picks the counters the TypeScript analyzer tallies during its existing walk, rather than walking files again.
      */
     buildSymbolCounters(statistics: CustomizationInput["statistics"]): TypescriptSymbolCounter[];
 }
@@ -143,91 +114,45 @@ export declare class DiscoveryService {
     private readonly logger;
     constructor(ignoreRulesService: IgnoreRulesService, logger: LoggerService);
     /**
-     * Folds a directory's own `.gitignore` into the rule sets already in force.
-     *
-     * Appended last so its patterns outrank the ones above it, which is how git
-     * resolves a nested ignore file: the closest one to the file wins.
+     * Folds a directory's `.gitignore` into the rule sets in force, appended last so its patterns outrank the ones above.
      */
     private applyDirectoryIgnoreFile;
     /** Selects the discovered files whose extension belongs to a category. */
     private filterByExtension;
     /**
-     * Whether any exclusion glob claims the given repository-relative path.
-     *
-     * Matched with `path.matchesGlob` rather than by substring, so a glob naming
-     * a `dist` directory removes build output and leaves a `redistribute`
-     * directory alone.
+     * Whether any exclusion glob claims the path. Matched by glob, not substring, so a `dist` glob leaves `redistribute` alone.
      */
     private isExcluded;
     /**
-     * Whether every file beneath a directory is excluded by a glob already.
-     *
-     * A pattern ending in `/**` claims every descendant without exception, so a
-     * directory matching the pattern with that suffix removed cannot contribute
-     * a single file and never has to be read. This is a shortcut and not a rule
-     * of its own: the same files would be dropped one by one afterwards either
-     * way. It matters in a directory with no `.gitignore` to prune
-     * `node_modules`, where reading it dwarfs reading the codebase.
+     * Whether a `/**` glob excludes every file beneath the directory, so the walk can skip reading it. Matters for an unignored `node_modules`.
      */
     private isExhaustivelyExcluded;
     /**
-     * Whether either set of ignore rules claims a path.
-     *
-     * The two sets are answered independently and the answers combined, rather
-     * than merged into one set. A configured ignore file subtracts from what the
-     * repository's own `.gitignore` files leave behind, exactly as the two git
-     * invocations this replaced did; a negation in one cannot resurrect a file
-     * the other removed.
+     * Whether either ignore rule set claims the path. Checked separately, so a negation in one cannot resurrect a file the other removed.
      */
     private isIgnoredPath;
     /**
-     * Lists every measurable file in the given directory, in sorted order.
-     *
-     * Sorted because the walk visits directories in whatever order the
-     * filesystem reports them, and every consumer downstream deserves the same
-     * list from the same tree on any machine.
+     * Lists every measurable file under the working directory, sorted so every consumer sees the same order on any machine.
      */
     private listDiscoveredFiles;
     /**
-     * Reads a directory's entries, or none when the directory cannot be read.
-     *
-     * A directory can vanish or refuse to open partway through a walk — one
-     * being cleaned up by another process, a mount the caller has no permission
-     * on. Shelling out to git never failed for either reason, so letting one
-     * unreadable directory abort the whole measurement would be a regression:
-     * warn, skip it, and keep counting the rest.
+     * Reads a directory's entries, or none when it cannot be read, so one vanished directory does not abort the walk.
      */
     private readDirectoryEntries;
     /**
-     * Reads the configured ignore files into rule sets anchored at the root.
-     *
-     * A missing file is a warning rather than a failure: a repository that has
-     * renamed its ignore file should hear about it, but a report is still worth
-     * more than a crash.
+     * Reads the configured ignore files as rules anchored at the root. A missing file only warns, since a report beats a crash.
      */
     private readExcludeFromScopes;
     /**
-     * Collects every measurable file under one directory.
-     *
-     * Walked directory by directory rather than matched by a single recursive
-     * glob, because an ignored directory then costs one decision instead of an
-     * enumeration: `node_modules/` is pruned where it is named, not discovered
-     * in full and thrown away.
+     * Collects every measurable file under one directory. Walking directory by directory prunes ignored trees such as `node_modules/` at their root.
      */
     private walkDirectory;
     /**
-     * Descends into one subdirectory, or skips it when nothing there counts.
-     *
-     * The trailing slash is what makes a `coverage/` pattern claim the directory
-     * itself: without it the pattern only ever matches a file of that name.
+     * Descends into a subdirectory unless nothing there counts. The trailing slash lets a `coverage/` pattern claim the directory itself.
      */
     private walkSubdirectory;
     /**
-     * Sorts a list of file paths into the categories the analyzers ask for.
-     *
-     * Separate from the walk so that any target's files can be categorized, not
-     * only the ones this service found itself: a target naming its files by glob
-     * is analyzed by the same language analyzers as the codebase around it.
+     * Sorts file paths into analyzer categories. Separate from the walk, so any target's files can be categorized.
      */
     categorize(files: string[]): DiscoveryResult;
     /** Returns categorized file path lists for the given codebase root. */
@@ -241,25 +166,18 @@ declare interface DuplicateTargetFinding {
 }
 
 /**
- * Raised when a target carrying a limit matched no files at all.
+ * Raised when a target carrying a limit matched no files.
  *
- * Writing a limit asserts the files exist, so nothing to measure means a glob
- * that no longer matches or a build that never ran — either way a number that
- * would pass every limit written against it. A target nobody limited is left
- * alone: there it is simply zero, and unremarkable.
+ * A limit asserts its files exist, so an empty match means a stale glob or a
+ * build that never ran, and a zero would pass every limit.
+ *
+ * Targets nobody limited are left alone.
  */
 export declare class EmptyTargetError extends Error {
     constructor(target: string, metric: string);
 }
 
-/**
- * What one limit found once it was pointed at its metric.
- *
- * A breach is one of these carrying `breached`, and it reports everything a
- * breach has to: which metric, held to what, and what the metric actually
- * measured. A limit that held is reported the same way, so a report can show
- * the headroom rather than only the failures.
- */
+/** One limit's result against its metric; a breach sets `breached`. */
 export declare interface EvaluatedLimit {
     /** Whether the measured value came out above the limit. */
     breached: boolean;
@@ -280,61 +198,29 @@ declare interface EvaluateLimitsArguments {
 }
 
 /**
- * Reads and applies gitignore-syntax rule sets without invoking git.
- *
- * Codometer used to hand this problem to `git ls-files`, which meant it could
- * only measure a directory that was a git repository. Reading the syntax here
- * is what lets it measure any directory at all, and it is the only reading of
- * that syntax in the tool — there is no git fast path to disagree with.
+ * Reads and applies gitignore-syntax rule sets without invoking git, so any directory can be measured. It is the only reader of that syntax.
  */
 declare class IgnoreRulesService {
     constructor();
     /**
-     * The path a rule set sees, or nothing when the path lies outside it.
-     *
-     * A rule set anchored at `projects/affirmancy` matches its patterns
-     * against `output/one.md`, not against the full path, because that is what
-     * the patterns in that directory's ignore file were written against.
+     * The path relative to a rule set's directory, or nothing when it lies outside. Patterns match against this, not the full path.
      */
     private toScopedPath;
     /**
-     * Builds a rule set from patterns already in hand.
-     *
-     * Case-sensitive on every platform, deliberately. Git decides that from the
-     * filesystem it happens to be on, so the same ignore file can claim a
-     * different set of files on a developer's Mac and on Linux CI. A measurement
-     * that disagrees with itself between machines is worse than a strict one.
+     * Builds a rule set from patterns in hand. Always case-sensitive, so one ignore file claims the same files on every platform.
      */
     createScope(args: CreateIgnoreScopeArguments): IgnoreScope;
     /**
-     * Whether the rule sets ignore a path, the innermost one deciding.
-     *
-     * gitignore resolution is nested rather than additive: a rule set in a
-     * subdirectory overrides the one above it, which is what lets a `!pattern`
-     * re-include a file its parent excluded. Reading the scopes outermost first
-     * and keeping the last decision reproduces that ordering.
-     *
-     * A directory is passed with a trailing slash, so a `build/` pattern claims
-     * the directory rather than only a file that happens to be named `build`.
+     * Whether the rule sets ignore a path, the innermost deciding. Scopes apply outermost first, so a nested `!pattern` can re-include a file.
      */
     isIgnored(scopes: readonly IgnoreScope[], relativePath: string): boolean;
     /**
-     * Reads a rule set out of a gitignore-syntax file.
-     *
-     * Returns nothing when the file is absent, so a configured ignore file that
-     * was renamed is reported by the caller rather than silently behaving as an
-     * empty one.
+     * Reads a rule set from a gitignore-syntax file, or nothing when it is absent so the caller can report it.
      */
     readScope(args: ReadIgnoreScopeArguments): IgnoreScope | undefined;
 }
 
-/**
- * A gitignore-syntax rule set together with the directory it is anchored to.
- *
- * The directory matters because gitignore patterns are relative to the file
- * they were written in: `/output` in a project's own ignore file claims that
- * project's `output`, not the one at the repository root.
- */
+/** `.gitignore` rules and the directory their patterns are relative to. */
 declare interface IgnoreScope {
     /** Directory the patterns are relative to, `/`-separated from the walk root. `""` is the root itself. */
     directory: string;
@@ -344,12 +230,7 @@ declare interface IgnoreScope {
 /** What a directory entry counts as while an input's tree is walked. */
 export declare type InputEntryKind = "directory" | "file" | "other";
 
-/**
- * What every analysis declared for one input reported over its files.
- *
- * An analysis an input did not ask for reports `undefined` rather than a zero,
- * so an input nobody measured the size of is never mistaken for an empty one.
- */
+/** One input's analysis results; skipped ones are `undefined`, not zero. */
 export declare interface InputMeasurement {
     /** How many files the input's globs claimed. */
     files: number;
@@ -359,14 +240,9 @@ export declare interface InputMeasurement {
 }
 
 /**
- * Raised when an input's directory reaches outside the repository.
+ * Raised when an input reaches beyond the repository holding it.
  *
- * An input may name its way out of the folder being measured — that is how a
- * project reaches build output written above it — but not out of the
- * repository holding both. Beyond that boundary a configuration file could
- * read any file on the machine and report its size, which is not a measurement
- * anybody asked for and is exactly what a tool published as a shared action
- * must not be able to do.
+ * An input may leave the measured folder, but reading outside the repository would let a shared action measure any file on the machine.
  */
 export declare class InputOutsideRepositoryError extends Error {
     constructor(input: string, directory: string, boundary: string);
@@ -389,56 +265,31 @@ export declare class InputsService {
     private readonly logger;
     constructor(logger: LoggerService);
     /**
-     * Whether a directory can hold anything the input's globs claim.
-     *
-     * A hidden directory is only entered when a glob spells it out. That is what
-     * every glob library means by excluding dot files, and it is also what stops
-     * an input over the whole tree from reading the repository's git database.
+     * Whether a directory can hold anything the input's globs claim. A hidden directory is entered only when a glob names it.
      */
     private canDescend;
     /**
-     * The furthest out an input is allowed to reach, from where the run started.
-     *
-     * The repository holding the measured directory, or that directory itself
-     * when nothing above it looks like one. Found by marker rather than by
-     * asking git, which is never invoked here, and generic to every repository —
-     * it says where measuring stops, not how any tree beneath it is arranged.
+     * The furthest an input may reach: the repository above the measured directory, found by marker files, or the directory itself.
      */
     private findBoundary;
     /** Whether the last segment of a path starts with a dot. */
     private isHidden;
     /**
-     * Whether a symbolic link points at a file.
-     *
-     * Links are followed, as every glob library does. Only to files, though: a
-     * link pointing back at one of its own ancestors would otherwise be walked
-     * until the stack ran out.
+     * Whether a symbolic link points at a file. Links are followed only to files, so a link back to an ancestor cannot recurse.
      */
     private isLinkedFile;
     /**
-     * Whether the input claims a file.
-     *
-     * Both lists are answered in full rather than in order, so where a pattern
-     * sits within either of them cannot change the answer.
+     * Whether the input claims a file. Both lists are answered in full, so pattern order cannot change the answer.
      */
     private isMatched;
     /** Whether the directory is on the way down to a glob's literal prefix. */
     private leadsToBase;
     /**
-     * Reads a directory's entries, or none when the directory cannot be read.
-     *
-     * An input naming a directory that was never built is an ordinary state
-     * rather than a failure — it holds no files, and what that means is decided
-     * by whoever asked for the measurement.
+     * Reads a directory's entries, or none when it cannot be read. An input naming a directory not yet built simply holds no files.
      */
     private readEntries;
     /**
-     * The measured-directory-relative prefix every matched path carries.
-     *
-     * Empty when the input starts where the run does. Otherwise it is the walk
-     * root written relative to the measured directory — `../../dist` and the
-     * like — so that every path leaving this service is relative to the same
-     * directory whether or not the input reached outside it.
+     * The prefix every matched path carries, relative to the measured directory. Empty when the input starts where the run does.
      */
     private readInputPrefix;
     /** What a directory entry counts as, once any link has been followed. */
@@ -448,52 +299,25 @@ export declare class InputsService {
     /** Whether a directory is the boundary or sits somewhere beneath it. */
     private sitsInsideBoundary;
     /**
-     * The literal path prefix of a glob, up to its first magic character.
-     *
-     * `dist/projects/common/observability/**` can only match inside `dist/projects/common/observability`, so
-     * that is the only branch of the tree worth reading — the difference between
-     * measuring one build directory and enumerating every dependency to find it.
+     * The literal path prefix of a glob, up to its first magic character. Only that branch of the tree needs reading.
      */
     private toIncludeBase;
     /** Collects every file one directory of the input's tree contributes. */
     private walk;
     /**
-     * Lists the files an input holds, sorted, relative to the measured directory.
-     *
-     * The walk starts at the input's own directory, which is the measured one
-     * unless the input named a way out of it. Where a repository builds is a
-     * convention its configuration states and this service is told, never one
-     * inferred here from a project's position — but the reach is bounded: a
-     * directory landing outside the repository fails the input by name rather
-     * than measuring whatever it found there.
-     *
-     * Sorted because the walk visits directories in whatever order the
-     * filesystem reports them, and a size is a sum of every file either way —
-     * but a list nobody can predict is one nobody can compare.
+     * Lists the files an input holds, sorted, relative to the measured directory. The walk may reach outside it, but never beyond the repository.
      */
     matchFiles(args: MatchInputFilesArguments): string[];
 }
 
-/**
- * One limit that could not be held against anything.
- *
- * Collected rather than thrown. A configuration carrying three limits that
- * bind to nothing is three mistakes to fix, and reporting only the first turns
- * one repair into three runs.
- */
+/** A limit that bound to nothing, collected rather than thrown. */
 declare interface LimitFailure {
     /** The dotted path exactly as the limit was written. */
     metric: string;
     reason: string;
 }
 
-/**
- * What every declared limit found, alongside the ones that bound to nothing.
- *
- * Both lists are always present. A limit that could not be bound is neither a
- * breach nor a pass, and reporting it as either would be a gate whose verdict
- * nobody could trust.
- */
+/** Every limit's result, with unbound limits neither breached nor passed. */
 declare interface LimitsEvaluation {
     failures: LimitFailure[];
     limits: EvaluatedLimit[];
@@ -508,10 +332,9 @@ export declare class LimitsModule {
 /**
  * Holds measured metrics to the limits declared against them.
  *
- * Every metric is addressable, whichever analysis produced it, by a dotted
- * path of target name and metric path. Nothing here decides what a breach
- * costs: it reports which limits were exceeded and how badly, and what that is
- * worth is the caller's to say.
+ * Every metric is addressable by a dotted path of target and metric name.
+ * Nothing here decides what a breach costs: it reports which limits were
+ * exceeded and by how much; the caller decides the rest.
  */
 export declare class LimitsService {
     constructor();
@@ -524,56 +347,24 @@ export declare class LimitsService {
     /** Names every measured target, for an error that has to list them. */
     private describeTargets;
     /**
-     * Every metric a written path could mean.
-     *
-     * Each target is asked whether the path starts with its name, rather than
-     * the path being split at its first dot: a target's name may hold a dot of
-     * its own, and so may the metric path that follows it. Whatever the shapes
-     * involved, every reading is collected and none of them is preferred.
+     * Every metric a written path could mean. Targets match by name prefix, never by splitting at the first dot.
      */
     private findCandidates;
     /**
-     * What the path would mean read as the default target's, if one is set.
-     *
-     * A default target that was never measured is refused rather than ignored:
-     * ignoring it would turn every unqualified path in the configuration into an
-     * unresolvable one, and report the paths instead of the reason.
+     * The path read as the default target's metric, if one is set. An unmeasured default is refused, not ignored.
      */
     private findDefaultCandidate;
     /**
-     * Points one written path at exactly one measured metric.
-     *
-     * Ambiguity is refused rather than settled by a rule about which reading
-     * wins. Any such rule would be invisible in the configuration file, and a
-     * limit holding a metric nobody meant to limit reads exactly like one that
-     * works.
+     * Points one written path at exactly one measured metric. Ambiguity is refused, never settled by a hidden rule.
      */
     private resolve;
     /**
-     * Holds every declared limit against the metric it addresses.
-     *
-     * Returns what each limit found rather than a verdict. Severity is carried
-     * through untouched: whether a breach stops the run is a decision about the
-     * run, not about the measurement.
-     *
-     * A limit that binds to nothing joins `failures` and the rest are evaluated
-     * anyway, so one run names every path in a configuration that binds to
-     * nothing instead of the first one and nothing after it.
+     * Holds every declared limit against its metric, returning what each found. Unbound limits are collected, not thrown.
      */
     evaluate(args: EvaluateLimitsArguments): LimitsEvaluation;
 }
 
-/**
- * Structured values that belong beside a log line rather than inside it.
- *
- * Counts, percentages, and durations are the values that change on every
- * occurrence, so they are carried as fields: the message stays constant and
- * groupable in telemetry, and the numbers stay queryable instead of having to
- * be parsed back out of prose.
- *
- * The named members are the recurring ones; the index signature keeps the
- * argument open for whatever a given call site needs to attach.
- */
+/** Values beside the log line, kept as queryable fields. */
 declare interface LogData {
     [key: string]: unknown;
     /** How many things the operation handled. */
@@ -587,20 +378,10 @@ declare interface LogData {
 }
 
 /**
- * Transient-scoped logger so each injecting class gets its own instance.
- * Each consumer calls `setContext(ClassName.name)` to tag every log line
- * with the originating class. Backed by pino for structured JSON output in
- * production and human-readable pretty-print in development.
- *
- * Messages follow one grammar: an emoji naming the subject, a verb in present
- * progressive or past tense, then the object. Values that vary per call —
- * counts, percentages, durations — go in the `data` argument rather than the
- * message, so the message stays constant enough for telemetry to group on.
- *
- * ```ts
- * this.logger.info("📥 Downloading CSEL sources", undefined, { total: 428 });
- * this.logger.info("📥 Downloaded CSEL sources", undefined, { count: 412 });
- * ```
+ * Transient logger, so each injecting class gets its own instance. Consumers
+ * call `setContext(ClassName.name)`. Backed by pino: JSON in production,
+ * pretty-printed in development. Messages start with an emoji naming the subject,
+ * then a present or past-tense verb. Varying values such as counts go in `data`.
  */
 declare @Injectable({ scope: Scope.TRANSIENT })
 class LoggerService
@@ -618,12 +399,7 @@ implements LoggerServiceContract
     private static readonly isProduction =
     process.env["NODE_ENV"] === "production";
 
-    /**
-     * Built on first use, not when this file is evaluated.
-     *
-     * A destination fixed at import time could only ever be chosen by this
-     * package, since every consumer's own code runs after its imports.
-     */
+    /** Built lazily, so `logToStandardError` can still set the destination. */
     private static rootLogger: pino.Logger | undefined;
 
     /** Whether lines go to standard error instead of standard output. */
@@ -666,18 +442,8 @@ implements LoggerServiceContract
     }
 
     /**
-     * Sends every subsequent line to standard error instead of standard output.
-     *
-     * For a command-line application whose standard output *is* its result. A log
-     * line sharing that stream is not a diagnostic beside the data, it is a
-     * corruption of it. Call it before anything logs — the first statement of the
-     * application's bootstrap.
-     *
-     * A call after the first line warns and changes nothing: the destination is
-     * fixed when the pino instance is built, and tearing down a transport
-     * somebody is writing through would be worse than refusing. The warning is
-     * the point — silently leaving the lines on standard output is how a caller
-     * would ship a corrupted pipe without ever being told.
+     * Sends later lines to standard error, for a command whose stdout is its
+     * result. Call it first; later calls warn and change nothing.
      */
     static logToStandardError(): void {
         if (LoggerService.rootLogger !== undefined) {
@@ -691,10 +457,8 @@ implements LoggerServiceContract
     }
 
     /**
-     * Fails a malformed message in development, and never in production.
-     *
-     * A logger that throws in production turns an observability call into an
-     * outage, so the check runs only where a developer is present to fix it.
+     * Fails a malformed message in development only, since a throw in production
+     * would turn logging into an outage.
      */
     private assertConventionalMessage(args: {
         context: string | undefined;
@@ -754,11 +518,8 @@ implements LoggerServiceContract
     }
 
     /**
-     * Whether a word is a verb in one of the two tenses the convention allows.
-     *
-     * Present progressive means the operation is under way; past means it
-     * finished. Regular morphology covers both, so a new verb needs no
-     * registration anywhere — only irregular pasts are enumerated.
+     * Whether a word is a present-progressive or past-tense verb. Only irregular
+     * pasts need listing; regular morphology covers the rest.
      */
     private isConventionalVerb(word: string): boolean {
         const lowercased = word.toLowerCase();
@@ -834,11 +595,8 @@ implements LoggerServiceContract
     }
 
     /**
-     * Logs an error message at the `error` level, optionally including a stack trace.
-     *
-     * `ConsoleLogger.error` spends a third slot on a context string that the
-     * other levels do not have, so this one accepts either: a string keeps
-     * NestJS's meaning, an object is structured data like everywhere else.
+     * Logs at the `error` level. The second argument is a stack, the third a
+     * context string or structured data.
      */
     override error(
     message: unknown,
@@ -869,12 +627,8 @@ implements LoggerServiceContract
     }
 
     /**
-     * Logs an informational message at the `info` level.
-     *
-     * NestJS and `nest-commander` call this method directly as part of the
-     * framework's own `LoggerService` contract, so it must keep working
-     * exactly as before. Application code should call `info` instead — the
-     * same behavior under a name that says what level it logs at.
+     * Logs at the `info` level, as NestJS and `nest-commander` call it.
+     * Application code should call `info` instead.
      */
     override log(message: unknown, context?: string, data?: LogData): void {
         this.info(message, context, data);
@@ -905,7 +659,7 @@ implements LoggerServiceContract
     }
 }
 
-/** The public logger shape used to type test doubles without importing its service. */
+/** Public logger shape, for test doubles without the service. */
 declare interface LoggerServiceContract extends ConsoleLogger {
     /** Normalizes unknown errors into a stable message and timestamped log line. */
     buildErrorLogEntry(
@@ -934,21 +688,13 @@ export declare interface MeasureArguments {
     /**
      * Files codometer writes itself, relative to the measured directory.
      *
-     * Never measured, whether or not this particular run writes them: a run that
-     * measured a different tree depending on its flags could not tell a stale
-     * report from a report written by a differently-flagged run.
+     * Never measured, so flags never change what is measured.
      */
     outputPaths: readonly string[];
     workingDirectory: string;
 }
 
-/**
- * What one target measured, as the limits layer reads it.
- *
- * Declared here rather than imported from the measurement pipeline: gating a
- * number needs the number and its target's name, and nothing about how either
- * was produced.
- */
+/** One target's measurements, as the limits layer reads them. */
 declare interface MeasuredTarget {
     files: number;
     language: CodeStatisticsResult | undefined;
@@ -956,21 +702,12 @@ declare interface MeasuredTarget {
     size: SizeResult | undefined;
 }
 
-/**
- * Everything one run measured, input by input.
- *
- * `statistics` is the `codebase` input's own language metrics, which is the
- * report every consumer renders today. It is the same object that input
- * carries, held out separately so nothing downstream has to know which input
- * it came from.
- */
+/** Everything one run measured, input by input; `statistics` stands apart. */
 export declare interface MeasurementResult {
     /**
-     * Whatever the run could not do, collected rather than thrown.
+     * What the run could not do, collected rather than thrown.
      *
-     * An input that will not measure and a limit that binds to nothing are both
-     * recorded here and stepped over, so one run names every one of them instead
-     * of stopping at the first and hiding the rest behind it.
+     * One run names every failure rather than stopping at the first.
      */
     failures: ReportFailure[];
     /** Every metric each measured input counted, addressable by dotted path. */
@@ -978,24 +715,18 @@ export declare interface MeasurementResult {
     /** Every input measured, in the order `inputs` declared them. */
     inputs: InputMeasurement[];
     /**
-     * What every declared limit found, in the order they were declared.
+     * What every declared limit found, in declaration order.
      *
-     * Empty when nothing declared one, which is the ordinary case: a metric with
-     * no limit is measured and reported like every other, and gated by nothing.
+     * Empty when none is declared, which is the ordinary case.
      */
     limits: EvaluatedLimit[];
     statistics: CodeStatisticsResult;
 }
 
 /**
- * Wires every analyzer a measurement run joins, and the service that joins
- * them.
+ * Wires every analyzer a measurement run joins, and the service that joins them.
  *
- * The one module a host has to import to measure anything: discovery finds the
- * files, the language and size analyzers count them, the custom counters add
- * whatever a configuration declared, and the limits layer holds the result to
- * what the configuration gates. None of the five imports another, which is why
- * the join lives here rather than inside one of them.
+ * Discovery, language, size, custom counters, and limits; none imports another, so the join lives here.
  */
 export declare class MeasureModule {
 }
@@ -1003,12 +734,7 @@ export declare class MeasureModule {
 /**
  * Aggregates every analyzer's report into a single set of statistics.
  *
- * The one place the discovery, language, size, and customization analyzers
- * meet. None of the four imports another, so joining them has to happen
- * somewhere, and a call-stack trace reports that join as module spread against
- * `measureInput` and `analyzeFiles` — the two methods that personally name
- * three of the four. That is the arrangement working, not drifting: pushing the
- * join down into one of the analyzers is what would couple them to each other.
+ * The one place the analyzers meet. None imports another, so the join lives here.
  */
 export declare class MeasureService {
     private readonly discoveryService;
@@ -1020,17 +746,7 @@ export declare class MeasureService {
     private readonly metricIndexService;
     constructor(discoveryService: DiscoveryService, languagesService: LanguagesService, customizationService: CustomizationService, inputsService: InputsService, sizeService: SizeService, limitsService: LimitsService, metricIndexService: MetricIndexService);
     /**
-     * Run every analyzer over one set of files and shape the result.
-     *
-     * Three analyzers, not one: the language analyzers, the size analyzer that
-     * produces the headline byte total, and the custom counters a configuration
-     * declares. Named for the file set rather than for any of the three, because
-     * this sits directly above `LanguagesService.analyze` in every measurement
-     * stack — named for a language it reads there as a forwarding layer instead
-     * of as the place all three are joined.
-     *
-     * Takes the files it is given rather than finding them, so the codebase and
-     * an input naming compiled output are counted by exactly the same analyzers.
+     * Runs every analyzer over one file set and shapes the result. Takes the files it is given, so codebase and input are counted identically.
      */
     private analyzeFiles;
     /** Project the TypeScript analyzer's counters onto the JavaScript group. */
@@ -1040,22 +756,11 @@ export declare class MeasureService {
     /** Reads whatever an input's measurement threw as a printable sentence. */
     private describeFailure;
     /**
-     * Discovers one input's files, minus the ones codometer writes itself.
-     *
-     * The built-in `codebase` input is discovered by whatever its ignore files
-     * leave behind rather than by matching its own `include`/`exclude` globs —
-     * those stay placeholders for that one input, exactly as
-     * `@codometer/configuration` documents. Every other input's files are
-     * whatever its globs claim.
+     * Discovers one input's files, minus codometer's own outputs. The built-in `codebase` input uses its ignore files, not its globs.
      */
     private discoverInputFiles;
     /**
-     * Drops the files codometer writes from a list of measured ones.
-     *
-     * Codometer's reports are made of what it measured, so measuring them makes
-     * every report an input to the next one: a badge block changes the markdown
-     * counters, which changes the badges. Removing them is what makes a second
-     * run over an untouched tree produce the same bytes as the first.
+     * Drops codometer's own report files from measured ones, so a second run over an untouched tree yields the same bytes.
      */
     private excludeOutputPaths;
     /**
@@ -1063,11 +768,7 @@ export declare class MeasureService {
      */
     private getFolderCount;
     /**
-     * Measure one declared input with whichever analyses it asked for.
-     *
-     * An analysis nobody asked for is not run at all. Compressing a source tree
-     * to answer a question nobody put costs more than every other analysis put
-     * together.
+     * Measures one declared input with only the analyses it asked for. An analysis nobody requested is never run.
      */
     private measureInput;
     /** Restates the limits layer's failures in the report's own vocabulary. */
@@ -1075,14 +776,7 @@ export declare class MeasureService {
     /** Whether an input asked for one of the analyses. */
     private runsAnalysis;
     /**
-     * Measure every input the configuration declares.
-     *
-     * The built-in `codebase` input is not special-cased here — resolution
-     * already prepends it unless a configuration replaces it by name, so this
-     * simply measures whichever inputs it was handed, in the order given. An
-     * input that cannot be measured — a glob pointing at a directory that
-     * vanished, a file that will not open — is recorded and stepped over, so one
-     * unreadable file never takes the whole run with it.
+     * Measures every declared input in declaration order. A failing input is recorded and skipped, so one bad file cannot end the run.
      */
     measure(args: MeasureArguments): MeasurementResult;
 }
@@ -1097,62 +791,39 @@ declare interface MetricIndexResult {
 /**
  * Makes every measured number addressable by a dotted path.
  *
- * The same index answers two questions that used to be one layer's private
- * business: which metric a limit is written against, and which metrics the
- * report has to list. Both need every number a target measured, named the same
- * way, so the naming lives here rather than in either caller.
+ * One index answers both which metric a limit targets and which metrics the
+ * report lists. Both need every number named the same way, so the naming lives
+ * here, not in either caller.
  */
 export declare class MetricIndexService {
     constructor();
     /**
-     * Records one metric, or marks its path as answered by more than one.
-     *
-     * Two counters sharing a path is a configuration mistake rather than a
-     * measurement one — two statistics with the same label — and it is caught
-     * here so that a limit addressing that path is refused instead of being
-     * given whichever counter was indexed first.
+     * Records one metric. A path already answered is marked ambiguous, so a limit addressing it is refused rather than given the first counter.
      */
     private addMetric;
     /**
-     * Indexes every metric one target measured, by its path within that target.
-     *
-     * An analysis the target never ran contributes nothing, so a limit written
-     * against it is refused rather than being compared against a zero the target
-     * never reported.
+     * Indexes every metric one target measured, by path. An analysis the target never ran is refused, not compared as zero.
      */
     private buildTargetIndex;
     /**
-     * Explains a name two measured targets both answered to.
-     *
-     * Written where the collision is found rather than raised as an error: the
-     * run carries on with the first target of that name, and this is what the
-     * report says about the one it had to drop.
+     * Explains a name two measured targets both answered to. The second target is dropped; the run continues with the first.
      */
     private describeDuplicate;
     /** Indexes a group of counters, descending into the nested ones. */
     private indexCounters;
     /**
-     * Indexes everything language analysis counted.
-     *
-     * Configured counters are indexed under a prefix rather than beside the
-     * built-in ones, so a counter labelled `files` cannot take the path the file
-     * count already answers to.
+     * Indexes everything language analysis counted. Configured counters sit under a prefix, so a counter named `files` cannot shadow the file count.
      */
     private indexLanguage;
     /** Whether a statistics entry holds counters of its own. */
     private isCounterGroup;
     /**
-     * Indexes every measured target, by name.
-     *
-     * A repeated name is collected rather than thrown, so a run reports every
-     * naming collision it found instead of the first one. The later target is
-     * dropped: a metric is addressed by its target's name, so a name answering
-     * to two targets can address neither.
+     * Indexes every measured target by name. A repeated name is collected rather than thrown, and the later target is dropped.
      */
     index(targets: readonly MeasuredTarget[]): MetricIndexResult;
 }
 
-/** A message split into the emoji the console shows and the prose telemetry stores. */
+/** Message split into emoji and the prose telemetry stores. */
 declare interface ParsedLogMessage {
     emoji: string | undefined;
     text: string;
@@ -1175,9 +846,7 @@ export declare interface SizeResult {
     /**
      * Total bytes the target's files occupy under the chosen compression.
      *
-     * A sum of separately compressed files rather than one compression of all of
-     * them: a browser fetches each file on its own, so compressing them together
-     * would report a number no client ever receives.
+     * A sum of separately compressed files, as browsers fetch them.
      */
     bytes: number;
     compression: CodometerCompression;
@@ -1189,28 +858,15 @@ export declare class SizeService {
     private readonly logger;
     constructor(logger: LoggerService);
     /**
-     * Compresses one file's contents and reports the resulting byte count.
-     *
-     * Written as a lookup rather than a switch so that a compression added to
-     * the configuration without an implementation here fails to compile, instead
-     * of falling through to whichever branch happened to be last.
+     * Compresses one file's contents and returns the byte count. A lookup, not a switch, so a missing compressor fails to compile.
      */
     private compress;
     /**
-     * Measures one file, or fails the run.
-     *
-     * A file can vanish between being matched and being read — a build running
-     * beside the measurement is enough. Skipping it would report a total short
-     * by that file while still counting it, which is a number that looks
-     * consistent and lets a real breach through. Failing is the lesser harm.
+     * Measures one file, or fails the run. Skipping a vanished file would understate the total, so failing is the lesser harm.
      */
     private measureFile;
     /**
-     * Measures every file of a target and sums the results.
-     *
-     * Each file is compressed on its own. Compressing them together would let
-     * one file's dictionary shrink the next, reporting a total smaller than
-     * anything that will ever be transferred.
+     * Measures every file of a target and sums the results. Each file is compressed alone, since shared compression would shrink later files.
      */
     analyze(args: AnalyzeSizeArguments): SizeResult;
 }
@@ -1220,20 +876,14 @@ export declare interface TargetMetricIndex {
     /**
      * Paths more than one metric answers to, which no limit may address.
      *
-     * Two configured counters sharing a label is the way this happens. Either
-     * metric would be a defensible binding, which is exactly why neither is.
+     * Two counters sharing a label cause this.
      */
     ambiguous: Set<string>;
     files: number;
     /**
-     * Where each metric's per-instance measurements were found, keyed by the
-     * same dotted path `metrics` uses.
+     * Per-instance measurements of each metric, keyed by its dotted path.
      *
-     * Only a metric a per-instance selector produced has an entry here — a
-     * `comment` selector today, and any future selector that measures more
-     * than a count. A metric with no entry counted matches and nothing more,
-     * so a consumer reading this map can tell the two apart without reading
-     * the configuration that produced either.
+     * Present only for metrics a per-instance selector produced.
      */
     instances: Map<string, CustomStatisticResultInstance[]>;
     metrics: Map<string, number>;
@@ -1242,10 +892,9 @@ export declare interface TargetMetricIndex {
 /**
  * Raised when a limit's dotted path does not name exactly one metric.
  *
- * Both halves of that are failures worth stopping for. A path naming nothing
- * gates nothing while looking like a gate, and a path naming several would
- * have to pick one — and a limit quietly holding the wrong metric is a limit
- * nobody would ever discover was wrong.
+ * A path naming nothing gates nothing while looking like a gate. A path naming
+ * several would have to pick one, and a limit quietly holding the wrong metric
+ * would never be discovered.
  */
 export declare class UnboundMetricError extends Error {
     constructor(path: string, reason: string);
@@ -1254,11 +903,11 @@ export declare class UnboundMetricError extends Error {
 /**
  * Raised when a file a target matched cannot be read.
  *
- * Louder than the unreadable *directory* discovery tolerates, and deliberately
- * so: a directory nobody can read narrows what was measured, while a matched
- * file nobody can read makes the reported total wrong by definition. Size
- * analysis exists to gate, and a number quietly short by one file lets a real
- * breach pass.
+ * Louder than discovery's directory tolerance, on purpose: an unreadable
+ * directory narrows the measurement, while an unreadable matched file makes the
+ * total wrong.
+ *
+ * Quietly short by one file, a number would let a breach pass.
  */
 export declare class UnreadableTargetFileError extends Error {
     constructor(filePath: string, reason: string);
@@ -1281,8 +930,7 @@ export declare interface WalkInputArguments {
     /**
      * The literal path prefix of each include glob.
      *
-     * A glob's prefix is where its matches can begin, so a directory neither
-     * leading to a prefix nor sitting inside one holds nothing the input wants.
+     * A directory holding nothing under that prefix can be skipped.
      */
     includeBases: readonly string[];
     input: ResolvedCodometerInput;

package/package.json

@@ -4,9 +4,9 @@
     "url": "https://github.com/organizzolini/codebase/issues"
   },
   "dependencies": {
-    "@codometer/configuration": "0.0.77",
-    "@codometer/core": "0.0.77",
-    "@codometer/languages": "0.0.77",
+    "@codometer/configuration": "0.0.79",
+    "@codometer/core": "0.0.79",
+    "@codometer/languages": "0.0.79",
     "@nestjs/common": "^11.1.21 || ^12.0.1",
     "ignore": "7.0.14",
     "pino": "^10.3.1",
@@ -64,5 +64,5 @@
     "strict": true
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.0.77"
+  "version": "0.0.79"
 }