@callidescope/configuration 0.0.0-stage → 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,1755 @@
+import { CallGraphResult } from '@callidescope/core';
+import { z } from 'zod';
+
+/**
+ * Options `depth` and `breadth` accept, scoping a lookup to one workspace.
+ *
+ * Every override that shapes the graph is here, and no other kind is. A lookup
+ * gates nothing and writes nothing, so a limit or a destination has nothing to
+ * act on — overriding one would change a number this command never reads.
+ */
+export declare interface AddressCommandOptions {
+    /**
+     * Callable addresses to report on, each `<file>#<qualified-name>`.
+     *
+     * Prompted for when empty. Required in the sense that a run cannot proceed
+     * without one — but asked for rather than refused, so the flag is only
+     * mandatory on a command line nobody is watching.
+     */
+    readonly addresses?: string[] | undefined;
+    readonly config?: string | undefined;
+    /** Project directories to trace. Every project in the workspace when omitted. */
+    readonly directories?: string[] | undefined;
+    /** Overrides `entryPoints.addresses` for this lookup. */
+    readonly entryPointAddresses?: string[] | undefined;
+    /** Overrides `entryPoints.decorators` for this lookup. */
+    readonly entryPointDecorators?: string[] | undefined;
+    /** Overrides `exclude` for this lookup. */
+    readonly exclude?: string[] | undefined;
+    /** Overrides `excludeCallees` for this lookup. */
+    readonly excludeCallees?: string[] | undefined;
+    /** `--format`, exactly as it was typed, for the resolver to judge. */
+    readonly format?: string | undefined;
+    /** Overrides `entryPoints.includeExportedFunctions`, as it was typed. */
+    readonly includeExportedFunctions?: string | true | undefined;
+    /** Overrides `entryPoints.includeOrphans`, as it was typed. */
+    readonly includeOrphans?: string | true | undefined;
+    /** Overrides `entryPoints.includeTests`, as it was typed. */
+    readonly includeTests?: string | true | undefined;
+}
+
+/** Every format a run may print, in the order a prompt offers them. */
+export declare const CALLIDESCOPE_OUTPUT_FORMATS: readonly ["markdown", "mermaid", "json"];
+
+/** Options the CLI accepts. */
+export declare interface CallidescopeCommandOptions {
+    /**
+     * The written `--check` set, or `true` for the flag passed without one.
+     *
+     * Kept as written rather than read into booleans here, so the one place that
+     * knows which names exist is the only place that decides what they mean.
+     */
+    readonly check?: string | true | undefined;
+    readonly config?: string | undefined;
+    /** Project directories to trace. Every project in the workspace when omitted. */
+    readonly directories?: string[] | undefined;
+    /** Overrides `entryPoints.addresses` for this run. */
+    readonly entryPointAddresses?: string[] | undefined;
+    /** Overrides `entryPoints.decorators` for this run. */
+    readonly entryPointDecorators?: string[] | undefined;
+    /** Overrides `exclude` for this run. */
+    readonly exclude?: string[] | undefined;
+    /** Overrides `excludeCallees` for this run. */
+    readonly excludeCallees?: string[] | undefined;
+    /**
+     * `--format`, exactly as it was typed.
+     *
+     * Left wide on purpose: a value nobody recognizes is refused by the one
+     * resolver that knows which formats exist, rather than rewritten to
+     * markdown before it ever gets there.
+     */
+    readonly format?: string | undefined;
+    /**
+     * Overrides `entryPoints.includeExportedFunctions`, exactly as it was typed.
+     *
+     * `true` is the flag written with no value at all, which is how commander
+     * reports its presence — not a value anybody typed.
+     */
+    readonly includeExportedFunctions?: string | true | undefined;
+    /** Overrides `entryPoints.includeOrphans`, exactly as it was typed. */
+    readonly includeOrphans?: string | true | undefined;
+    /** Overrides `entryPoints.includeTests`, exactly as it was typed. */
+    readonly includeTests?: string | true | undefined;
+    readonly json?: string | undefined;
+    readonly markdown?: string | undefined;
+    /** Overrides `limits.maximumBreadth`, exactly as it was typed. */
+    readonly maximumBreadth?: string | undefined;
+    /** Overrides `limits.maximumDepth`, exactly as it was typed. */
+    readonly maximumDepth?: string | undefined;
+    readonly mermaid?: string | undefined;
+    readonly write?: boolean | undefined;
+}
+
+/** The shape of a `callidescope.config.ts` default export. */
+export declare interface CallidescopeConfiguration {
+    /**
+     * Project directories to trace. Every directory holding its own
+     * `tsconfig.json`, found by walking the workspace, when omitted.
+     *
+     * Narrowing this is the difference between a one-second pre-commit check and
+     * a whole-workspace analysis, because each directory needs its own program.
+     */
+    directories?: string[] | undefined;
+    entryPoints?: CallidescopeEntryPoints | undefined;
+    exclude?: string[] | undefined;
+    /**
+     * Globs matched against a callable's display name (`Type.member`):
+     * calls landing on a match are dropped from the graph entirely, counting
+     * toward neither the caller's depth nor its breadth.
+     *
+     * For a cross-cutting callable like a logger, every call site is a fact
+     * about instrumentation, not about how deep or wide the code around it
+     * is — counting it would move every other callable's numbers on a change
+     * that has nothing to do with them.
+     */
+    excludeCallees?: string[] | undefined;
+    /** Gitignore-syntax files listing paths to leave untraced. */
+    excludeFrom?: string[] | undefined;
+    limits?: CallidescopeLimits | undefined;
+    write?: CallidescopeWriteConfiguration | undefined;
+}
+
+/**
+ * Validates the shape of a callidescope configuration file.
+ *
+ * Strict at every level, so a field nothing here names is refused rather than
+ * stripped. Stripping is the failure mode that leaves whoever wrote the field
+ * believing a limit, an exclusion, or a destination is in force that nothing
+ * reads — and every field this tool has ever retired arrives through that same
+ * door, along with every name somebody misspells.
+ *
+ * `ignoreCallees` and `output` are still named as `z.never()` rather than left
+ * to strictness, because a key the schema knows by name earns a message saying
+ * this field is gone rather than one saying it was never a field.
+ */
+export declare const callidescopeConfigurationSchema: z.ZodObject<{
+    directories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    entryPoints: z.ZodOptional<z.ZodObject<{
+        addresses: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        decorators: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        includeExportedFunctions: z.ZodOptional<z.ZodBoolean>;
+        includeOrphans: z.ZodOptional<z.ZodBoolean>;
+        includeTests: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excludeCallees: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excludeFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ignoreCallees: z.ZodOptional<z.ZodNever>;
+    limits: z.ZodOptional<z.ZodObject<{
+        maximumBreadth: z.ZodOptional<z.ZodNumber>;
+        maximumDepth: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    output: z.ZodOptional<z.ZodNever>;
+    write: z.ZodOptional<z.ZodObject<{
+        json: z.ZodOptional<z.ZodObject<{
+            indentation: z.ZodOptional<z.ZodNumber>;
+            path: z.ZodString;
+        }, z.core.$strict>>;
+        markdown: z.ZodOptional<z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+            endMarker: z.ZodOptional<z.ZodString>;
+            heading: z.ZodOptional<z.ZodString>;
+            path: z.ZodString;
+            previewCount: z.ZodOptional<z.ZodNumber>;
+            render: z.ZodOptional<z.ZodType<RenderMarkdownOutput, unknown, z.core.$ZodTypeInternals<RenderMarkdownOutput, unknown>>>;
+            startMarker: z.ZodOptional<z.ZodString>;
+            writeBlock: z.ZodOptional<z.ZodType<WriteMarkdownOutput, unknown, z.core.$ZodTypeInternals<WriteMarkdownOutput, unknown>>>;
+        }, z.core.$strict>>;
+        mermaid: z.ZodOptional<z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+            endMarker: z.ZodOptional<z.ZodString>;
+            heading: z.ZodOptional<z.ZodString>;
+            path: z.ZodString;
+            previewCount: z.ZodOptional<z.ZodNumber>;
+            render: z.ZodOptional<z.ZodType<RenderMarkdownOutput, unknown, z.core.$ZodTypeInternals<RenderMarkdownOutput, unknown>>>;
+            startMarker: z.ZodOptional<z.ZodString>;
+            writeBlock: z.ZodOptional<z.ZodType<WriteMarkdownOutput, unknown, z.core.$ZodTypeInternals<WriteMarkdownOutput, unknown>>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+/** Which callables are treated as the roots of a call stack. */
+export declare interface CallidescopeEntryPoints {
+    /**
+     * Callables this configuration declares as roots, written as
+     * `<file>#<qualified-name>` — the same address the `depth` and `breadth`
+     * commands accept and every stack frame prints, so one can be copied out of
+     * a report straight into here. A trailing `:<line>` disambiguates a file
+     * holding two declarations under one qualified name.
+     *
+     * Declared roots are additive: the rules below keep running, and orphan
+     * promotion still catches whatever nobody named. An address naming a
+     * callable a rule already rooted is one root, not two.
+     */
+    addresses?: string[] | undefined;
+    /**
+     * Decorators whose methods a framework invokes.
+     *
+     * Matched against the decorator's own name, then confirmed against the
+     * package that declares it, so a locally defined `Command` is not mistaken
+     * for nest-commander's.
+     */
+    decorators?: string[] | undefined;
+    /** Treat every `src/index.ts` export as a root. Defaults to true. */
+    includeExportedFunctions?: boolean | undefined;
+    /**
+     * Promote callables nothing in the repository calls. Defaults to true.
+     *
+     * This is the safety net that makes a wrong rule set visible: without it, a
+     * missing rule silently removes whole subtrees from every measurement.
+     */
+    includeOrphans?: boolean | undefined;
+    /** Trace test files too. Defaults to false. */
+    includeTests?: boolean | undefined;
+}
+
+/**
+ * The `--format` option every callidescope command shares.
+ *
+ * Stated as its own interface so `resolveFormatOption` can be generic over a
+ * command's whole options object and carry its other flags through unchanged.
+ *
+ * Held as written rather than as one of the formats a run can print: which
+ * values exist is `FlagResolutionService`'s to decide, and a type that
+ * narrowed here would leave a misspelled `--format` no way to reach the one
+ * place that refuses it.
+ */
+export declare interface CallidescopeFormatOptions {
+    readonly format?: string | undefined;
+}
+
+/** JSON output destination. */
+export declare interface CallidescopeJsonOutputConfiguration {
+    indentation?: number | undefined;
+    path: string;
+}
+
+/**
+ * The limits one command line overrode, and only those.
+ *
+ * Held apart from the resolved configuration because the two answer different
+ * questions. The configuration says what every limit is; this says which of
+ * them a flag chose, which is what lets the override reach the number each
+ * project is really gated by rather than stopping at the workspace file.
+ *
+ * A member is present only when a flag supplied it, so an override reaches a
+ * project's own declared limit without ever supplying one to a project that
+ * declared none.
+ */
+export declare interface CallidescopeLimitOverrides {
+    maximumBreadth?: number | undefined;
+    maximumDepth?: number | undefined;
+}
+
+/**
+ * Thresholds that decide what a run reports.
+ *
+ * Two, and both per project: how deep a stack may run, and how widely one
+ * callable may reach. Every limit this tool once had beyond these described a
+ * finding nobody acted on.
+ */
+export declare interface CallidescopeLimits {
+    /**
+     * Distinct callables a callable may call directly before it is reported.
+     *
+     * No default is applied: a project must configure this explicitly before
+     * `--check breadth` can run against it.
+     */
+    maximumBreadth?: number | undefined;
+    /** Frames a call stack may hold before it is reported. */
+    maximumDepth?: number | undefined;
+}
+
+/** Markdown output destination. */
+export declare interface CallidescopeMarkdownOutputConfiguration {
+    description?: string | undefined;
+    endMarker?: string | undefined;
+    /**
+     * Heading the block is written under, `# 🔭 Callidescope` by default.
+     *
+     * Configurable because a block is spliced into somebody's document, and it is
+     * the level rather than the words that usually needs changing: a block
+     * spliced into a file that already has a title needs an `##` here, or the
+     * file ends up with two first-level headings and every markdown linter
+     * rejects it. The subsection levels follow whatever this is set to, so the
+     * block stays a well-formed subtree of the document it lands in.
+     */
+    heading?: string | undefined;
+    path: string;
+    /**
+     * Stacks shown before the rest fold into a disclosure.
+     *
+     * A member of the destination rather than of the run, because it is a fact
+     * about the document the block lands in: a project's README wants three and
+     * a report file wants all of them, and one number for both could only ever
+     * be wrong for one of them.
+     */
+    previewCount?: number | undefined;
+    render?: RenderMarkdownOutput | undefined;
+    startMarker?: string | undefined;
+    writeBlock?: undefined | WriteMarkdownOutput;
+}
+
+/** How a run renders what it found. */
+export declare type CallidescopeOutputFormat = "json" | "markdown" | "mermaid";
+
+/**
+ * The complete shape of a project's own `callidescope.config.ts`.
+ *
+ * Every member is required. A project file is meant to be readable as the
+ * whole statement of how that project is traced and judged, which a shape with
+ * optional members cannot be: an absent field and a field set to the value it
+ * would have defaulted to look identical in the diff, and only one of them was
+ * a decision. A project spreads the workspace's `projectDefaults` and overrides
+ * what it means to, so completeness costs one line rather than twenty — the
+ * same arrangement this repository's codometer configuration files already run.
+ *
+ * A member is required, not non-empty: `undefined` is the value that says *no
+ * destination*, so a project with nothing worth publishing writes that rather
+ * than leaving the member out.
+ *
+ * This is enforced rather than advisory. Every traced project's file is checked
+ * against it as it is loaded, and a project leaving a field out is refused by
+ * name — as is a traced project with no file at all.
+ */
+export declare interface CallidescopeProjectConfiguration {
+    entryPoints: CallidescopeProjectEntryPoints;
+    /** Globs matched against paths relative to this project's own root. */
+    exclude: string[];
+    limits: CallidescopeProjectLimits;
+    write: CallidescopeProjectWriteConfiguration;
+}
+
+/** Which of a project's callables are treated as the roots of a call stack. */
+export declare interface CallidescopeProjectEntryPoints {
+    addresses: string[];
+    decorators: string[];
+    includeExportedFunctions: boolean;
+    includeOrphans: boolean;
+    includeTests: boolean;
+}
+
+/**
+ * The two limits a project is gated by.
+ *
+ * `maximumBreadth` is required and may be `undefined`, which is a project
+ * saying outright that it gates depth and not breadth — the one thing the
+ * absent field could never distinguish itself from a project that forgot.
+ */
+export declare interface CallidescopeProjectLimits {
+    maximumBreadth: number | undefined;
+    maximumDepth: number;
+}
+
+/**
+ * Where a project's own published section and diagram land.
+ *
+ * Both paths are read relative to the project's own root, so a project cannot
+ * write into a sibling by declaring one. The run's JSON report is absent by
+ * construction: it is the run's single output, not a project's to redirect.
+ *
+ * A destination is the shared markdown-block shape rather than a complete one
+ * of its own. What a project is *judged* by has to be written out; where the
+ * markers and the heading of its own block sit is presentation the tool has a
+ * working answer for, and requiring all seven members would make overriding a
+ * path cost six restatements of a default.
+ */
+export declare interface CallidescopeProjectWriteConfiguration {
+    markdown: CallidescopeMarkdownOutputConfiguration | undefined;
+    mermaid: CallidescopeMarkdownOutputConfiguration | undefined;
+}
+
+/**
+ * Every flag a callidescope command line may carry, as parsed and before any
+ * of it has met a configuration.
+ *
+ * One shape for every command rather than one per command: `depth` accepts a
+ * subset of what the workspace run accepts, and a subset is expressed by
+ * leaving fields out rather than by a second type that would have to be kept
+ * in step with this one.
+ *
+ * The mode flags are carried here even though resolution never merges them,
+ * so the rule they obey is stated where the other flags' rules are rather
+ * than left to be inferred from their absence.
+ *
+ * `--config` is deliberately absent: it chooses the file every other flag is
+ * resolved against, so by the time resolution runs it has already done its
+ * whole job.
+ */
+export declare interface CallidescopeRunFlags {
+    /** Mode. The written `--check` set, or `true` for the flag with no value. */
+    readonly check?: string | true | undefined;
+    /** Scope. `--directories`, already split on commas. */
+    readonly directories?: readonly string[] | undefined;
+    /** Judgement. `--entry-point-addresses`, already split on commas. */
+    readonly entryPointAddresses?: readonly string[] | undefined;
+    /** Judgement. `--entry-point-decorators`, already split on commas. */
+    readonly entryPointDecorators?: readonly string[] | undefined;
+    /** Judgement. `--exclude`, already split on commas. */
+    readonly exclude?: readonly string[] | undefined;
+    /** Judgement. `--exclude-callees`, already split on commas. */
+    readonly excludeCallees?: readonly string[] | undefined;
+    /** Presentation. `--format`, exactly as it was typed. */
+    readonly format?: string | undefined;
+    /**
+     * Judgement. `--include-exported-functions`, exactly as it was typed.
+     *
+     * A switch arrives here as written text rather than as a boolean for the
+     * same reason `--format` does: which values a switch accepts is this
+     * package's to decide, and a `--include-tests maybe` coerced to `true` on
+     * the way here could never be refused by the one place that knows better.
+     * `true` is the one exception, and it is not a coercion: a switch written
+     * with no value at all is how commander reports the flag's own presence.
+     */
+    readonly includeExportedFunctions?: string | true | undefined;
+    /** Judgement. `--include-orphans`, exactly as it was typed. */
+    readonly includeOrphans?: string | true | undefined;
+    /** Judgement. `--include-tests`, exactly as it was typed. */
+    readonly includeTests?: string | true | undefined;
+    /** Destination. `--json`, a path and nothing else. */
+    readonly json?: string | undefined;
+    /** Destination. `--markdown`, a path and nothing else. */
+    readonly markdown?: string | undefined;
+    /** Judgement. `--maximum-breadth`, exactly as it was typed. */
+    readonly maximumBreadth?: string | undefined;
+    /** Judgement. `--maximum-depth`, exactly as it was typed. */
+    readonly maximumDepth?: string | undefined;
+    /** Destination. `--mermaid`, a path and nothing else. */
+    readonly mermaid?: string | undefined;
+    /** Mode. `--write`. */
+    readonly write?: boolean | undefined;
+}
+
+/** Where a run writes its findings. */
+export declare interface CallidescopeWriteConfiguration {
+    json?: CallidescopeJsonOutputConfiguration | undefined;
+    markdown?: CallidescopeMarkdownOutputConfiguration | undefined;
+    /**
+     * A markdown block whose call stacks are drawn rather than printed.
+     *
+     * Its own destination rather than a mode on `markdown`, so a repository can
+     * publish both: the tree carries what each frame takes, returns, and
+     * documents, and the diagram carries the shape they make together. Neither
+     * one is the other with a flag flipped.
+     */
+    mermaid?: CallidescopeMarkdownOutputConfiguration | undefined;
+}
+
+/**
+ * What `--check breadth` asks the run to fail on: a callable calling too many
+ * other callables directly.
+ */
+export declare const CHECK_BREADTH = "breadth";
+
+/** What `--check depth` asks the run to fail on: a call stack that is too deep. */
+export declare const CHECK_DEPTH = "depth";
+
+/**
+ * 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.
+ */
+export declare const CHECK_NAMES: string[];
+
+/** What `--check reports` asks the run to fail on: a stale written report. */
+export declare const CHECK_REPORTS = "reports";
+
+/** How a `--check` value is written: one comma-separated set, no spaces needed. */
+export declare const CHECK_SEPARATOR = ",";
+
+/**
+ * Configuration file names, in the order they are searched for.
+ *
+ * TypeScript comes first because that is the form a repository gets type
+ * checking from, and the form every other configuration file in this workspace
+ * is written in.
+ */
+export declare const CONFIGURATION_FILE_NAMES: readonly ["callidescope.config.ts", "callidescope.config.mts", "callidescope.config.cts", "callidescope.config.js", "callidescope.config.mjs", "callidescope.config.cjs", "callidescope.config.json", "callidescope.config.jsonc"];
+
+/** Raised when an explicitly named configuration file does not exist. */
+export declare class ConfigurationFileNotFoundError extends Error {
+    constructor(filePath: string);
+}
+
+/**
+ * The two reads the collaborators behind `ConfigurationService` need from a
+ * configuration file loader.
+ *
+ * Narrow on purpose, and passed in rather than injected: it is what leaves the
+ * whole layer replaceable by a double at its one public surface, without the
+ * classes behind that surface pointing at each other. The overload pair
+ * mirrors the loader's own — naming a path guarantees one back.
+ *
+ * `ConfigurationService` hands over itself rather than the loader it holds,
+ * and it is the only class in this package that declares `implements` on this
+ * interface — `ConfigurationFileService` merely happens to have the same two
+ * methods. Callidescope resolves a call on `reader` through the declared type,
+ * so the one nominal implementer is what a traced stack lands on either way,
+ * which is why the choice measures the same depth. What it does decide is
+ * whether a caller stubbing the one public object has stubbed what these
+ * collaborators read. It has, which is the property publishing one object
+ * exists to give.
+ */
+declare interface ConfigurationFileReader {
+    findConfigurationFileAt(directory: string): string | undefined;
+    loadConfigurationFile(args: LoadConfigurationArguments & {
+        configurationPath: string;
+    }): Promise<LoadedCallidescopeConfigurationFile>;
+    loadConfigurationFile(args?: LoadConfigurationArguments): Promise<LoadedCallidescopeConfiguration>;
+}
+
+/**
+ * Loads, validates, and normalizes callidescope configuration files.
+ *
+ * This service owns loading only. What the configuration means — which files an
+ * exclusion glob removes, which decorator marks a stack root — belongs to the
+ * analyzers that read it, so that reading a configuration file stays free of any
+ * knowledge of the repository being traced.
+ */
+declare class ConfigurationFileService {
+    constructor();
+    /**
+     * Walks upward from a directory looking for a configuration file.
+     *
+     * Returns `undefined` when the search reaches the filesystem root without
+     * finding one: a repository that never wrote a configuration file is traced
+     * with the defaults rather than told to write one.
+     */
+    private findConfigurationFile;
+    /**
+     * Walks upward from the process cwd looking for the repository 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 the project rather than the workspace.
+     */
+    private findRepositoryRoot;
+    /** Loads a configuration module, choosing the reader by extension. */
+    private loadConfigurationModule;
+    /** Reads a JSON or JSONC configuration file. */
+    private loadJsonConfiguration;
+    /** Resolves a configuration path against the cwd, then the repository root. */
+    private resolveConfigurationPath;
+    /**
+     * Applies defaults to the entry-point rules.
+     *
+     * The authored object is defaulted to an empty one up front rather than
+     * optional-chained per field, which keeps this to one branch per option
+     * instead of two.
+     */
+    private resolveEntryPoints;
+    /**
+     * Applies the directories no repository wants traced, on top of a
+     * configuration's own.
+     *
+     * Additive rather than a replacement: the defaults are directories no
+     * repository wants traced, so a configuration naming its own noise should
+     * not have to restate them to keep them out.
+     */
+    private resolveExclude;
+    /** Applies defaults to the JSON output destination, if one was named. */
+    private resolveJsonOutput;
+    /** Applies defaults to every threshold. */
+    private resolveLimits;
+    /**
+     * Applies defaults to one anchored markdown destination, if it was named.
+     *
+     * Shared by `markdown` and `mermaid`: the two differ in what is written
+     * between the anchors, and in nothing this resolves.
+     */
+    private resolveMarkdownDestination;
+    /**
+     * Finds a configuration file sitting directly at one directory.
+     *
+     * No upward walk, which is what makes this the search a project root needs:
+     * walking up from one would find the workspace file and hand every project a
+     * copy of it.
+     */
+    findConfigurationFileAt(directory: string): string | undefined;
+    /**
+     * Loads and validates a callidescope configuration file.
+     *
+     * A path that was named explicitly must exist — a typo in a task runner's
+     * arguments should fail rather than quietly trace the repository with defaults
+     * it never asked for. A path that was not named is searched for, and its
+     * absence is legal.
+     */
+    loadConfiguration(args?: LoadConfigurationArguments): Promise<ResolvedCallidescopeConfiguration>;
+    /**
+     * Loads a configuration, and says what the file itself declared and which
+     * file answered.
+     *
+     * The same work as `loadConfiguration`, keeping two facts it throws away. The
+     * path is what tells a caller resolving a configuration beside every project
+     * which file it has already read as the run's own, so that one file is never
+     * given two roles. The authored object is what a refusal has to name fields
+     * from, since resolution manufactures the rest.
+     *
+     * Naming a path guarantees one back, which is why that case has an overload
+     * of its own: the alternative is every caller of the narrow case carrying a
+     * fallback that can never fire, and picking its own path when it does.
+     */
+    loadConfigurationFile(args: LoadConfigurationArguments & {
+        configurationPath: string;
+    }): Promise<LoadedCallidescopeConfigurationFile>;
+    loadConfigurationFile(args?: LoadConfigurationArguments): Promise<LoadedCallidescopeConfiguration>;
+    /**
+     * Fills in every field a configuration file may leave out.
+     *
+     * Exposed so a host embedding callidescope can hand over a configuration
+     * object it assembled itself and get the same shape a configuration file
+     * produces.
+     */
+    resolveConfiguration(configuration: CallidescopeConfiguration): ResolvedCallidescopeConfiguration;
+}
+
+/**
+ * Provides the configuration layer's one public service.
+ *
+ * `ProjectConfigurationService` is provided here, and the three modules above
+ * supply the other collaborators `ConfigurationService` is assembled from.
+ * None of them is exported: a consumer outside this package injects
+ * `ConfigurationService`, which is what makes this layer one entry point
+ * rather than four.
+ */
+export declare class ConfigurationModule {
+}
+
+/**
+ * The one answer to "what is this run actually configured to do".
+ *
+ * Every question a caller outside this package can ask about configuration is
+ * asked here: what a file declares, what a project is gated by, what a command
+ * line resolved to, and what to ask a person for when a flag was left off. A
+ * consumer therefore injects this and nothing else from this package, which is
+ * what makes the configuration layer one layer rather than a bag of
+ * collaborators a caller has to know the names of.
+ *
+ * Nearly every method here forwards and nothing more. Loading a file, judging
+ * a project's own file, planning a run from flags, and prompting are four
+ * different jobs and stay four classes in four files behind this one; what
+ * they stop being is four public entry points. A facade that implemented any
+ * of them would be a facade in name only, and the one-per-job split is what
+ * keeps each of them readable.
+ *
+ * `resolveFormatOption` is the exception, and a small one: deciding whether to
+ * offer a prompt at all is a policy over two collaborators rather than work
+ * either of them does, and it reads a constant the prompting service must not
+ * import. Its whole body is that decision.
+ */
+export declare class ConfigurationService implements ConfigurationFileReader {
+    private readonly configurationFileService;
+    private readonly inputService;
+    private readonly projectConfigurationService;
+    private readonly runPlanService;
+    constructor(configurationFileService: ConfigurationFileService, inputService: InputService, projectConfigurationService: ProjectConfigurationService, runPlanService: RunPlanService);
+    /** Finds a configuration file sitting directly at one directory. */
+    findConfigurationFileAt(directory: string): string | undefined;
+    /**
+     * Loads a configuration, and says what the file itself declared and which
+     * file answered.
+     */
+    loadConfigurationFile(args: LoadConfigurationArguments & {
+        configurationPath: string;
+    }): Promise<LoadedCallidescopeConfigurationFile>;
+    loadConfigurationFile(args?: LoadConfigurationArguments): Promise<LoadedCallidescopeConfiguration>;
+    /** Loads and validates every traced project's own configuration file. */
+    loadProjectConfigurations(args: LoadProjectConfigurationsArguments): Promise<LoadedProjectConfiguration[]>;
+    /** Splits a comma-separated flag value into its parts. */
+    parseCommaDelimitedOption(value: string | undefined): string[];
+    /** Reads a flag that may have been written without a value. */
+    parseOptionalOption(value: string | undefined): string | undefined;
+    /** Reads a lookup's scoping flags into a workspace root and a configuration. */
+    prepareLookup(options: AddressCommandOptions): Promise<PreparedLookup>;
+    /** Reads a command line and its configuration into what the run will do. */
+    prepareRun(options: CallidescopeCommandOptions): Promise<RunPreparation>;
+    /** Prompts for several values at once, completing the list as it is typed. */
+    promptForAutocompleteMultiselect(args: {
+        message: string;
+        subject: string;
+        suggestions: readonly string[];
+    }): Promise<string[]>;
+    /** Prompts for one value out of a fixed set of choices. */
+    promptForSelect<Choice extends string>(args: {
+        choices: readonly Choice[];
+        message: string;
+        subject: string;
+    }): Promise<Choice>;
+    /** Fills in every field a configuration file may leave out. */
+    resolveConfiguration(configuration: CallidescopeConfiguration): ResolvedCallidescopeConfiguration;
+    /**
+     * Returns the given options with `--format` filled in where one is wanted.
+     *
+     * Offered rather than required, which is the one place this differs from
+     * every other missing value: the caller applies its own default when
+     * nobody is at a terminal to ask, so a run proceeds with nothing typed.
+     * Demanding it would fail every scripted run — this repository's own
+     * per-project `gate` among them — over a flag those runs have never needed
+     * to pass.
+     *
+     * Generic over the caller's options type, so a command carries its own
+     * other flags through unchanged.
+     */
+    resolveFormatOption<Options extends CallidescopeFormatOptions>(options: Options): Promise<Options>;
+    /** Resolves the limits every traced project is judged against. */
+    resolveLimits(args: ResolveProjectLimitsArguments): ProjectLimitsLookup;
+    /** Whether a run reads or rewrites the files its reports live in. */
+    touchesFiles(mode: RunMode): boolean;
+}
+
+/** Decorators whose methods a framework invokes, making them stack roots. */
+export declare const DEFAULT_ENTRY_POINT_DECORATORS: readonly ["Command", "Cron", "Delete", "Get", "Mutation", "OnEvent", "Option", "Patch", "Post", "Put", "Query", "ResolveField", "SubscribeMessage"];
+
+/** Directories no repository wants traced, kept out even when unmentioned. */
+export declare const DEFAULT_EXCLUDE_GLOBS: readonly ["**/.conformetry/**", "**/.nx/**", "**/coverage/**", "**/dist/**", "**/node_modules/**", "**/output/**"];
+
+/** Spaces used to indent the JSON report. */
+export declare const DEFAULT_JSON_INDENTATION = 2;
+
+/** Closing anchor of the generated markdown block. */
+export declare const DEFAULT_MARKDOWN_END_MARKER = "<!-- callidescope:end -->";
+
+/** Opening anchor of the generated markdown block. */
+export declare const DEFAULT_MARKDOWN_START_MARKER = "<!-- callidescope:start -->";
+
+/**
+ * Frames allowed on a call stack before it is reported.
+ *
+ * Six is the issue's own example limit. It counts frames inclusive of the entry
+ * point, so a resolver calling a service calling a repository is three.
+ */
+export declare const DEFAULT_MAXIMUM_DEPTH = 6;
+
+/** What a run prints to standard output when nothing says otherwise. */
+export declare const DEFAULT_OUTPUT_FORMAT = "markdown";
+
+/** Stacks a README section shows before the rest fold into a disclosure. */
+export declare const DEFAULT_PREVIEW_COUNT = 3;
+
+/** Heading the section embedded in a project README is written under. */
+export declare const DEFAULT_PROJECT_README_HEADING = "## \uD83D\uDD2D Callidescope";
+
+/**
+ * Heading a whole-run markdown block is written under.
+ *
+ * First level, because the historical destination for this block is a file of
+ * its own that the block is the whole of. A block spliced into a file that
+ * already has a title sets `heading` to a deeper level instead.
+ */
+export declare const DEFAULT_RUN_HEADING = "# \uD83D\uDD2D Callidescope";
+
+/**
+ * The flags that name where a report goes, rather than whether one is written.
+ *
+ * Kept as a list so the refusal in `RunPlanService.selectMode` names every one
+ * the command line supplied, and so adding a destination flag without adding
+ * it here is the only way to reintroduce a flag that writes nothing silently.
+ */
+export declare const DESTINATION_FLAG_NAMES: readonly ["json", "markdown", "mermaid"];
+
+/**
+ * One refusal covering every flag a command line got wrong.
+ *
+ * An `InputError` rather than a class of its own: to whoever catches it this
+ * is the same event as any other unusable command line — nothing was
+ * attempted, and the fix is to retype the flags.
+ */
+export declare const flagResolutionError: (reasons: readonly string[]) => InputError;
+
+/**
+ * Combines a command line with the configuration it was resolved against,
+ * under one precedence rule.
+ *
+ * **The rule.** A flag that changes what a run judges or writes may only
+ * override a value the configuration already declares. A flag that selects
+ * mode or presentation is command-line only, because neither can make an
+ * under-configured run legal.
+ *
+ * `--check` and `--write` are the mode flags and `--format` is the
+ * presentation flag, so none of the three is merged into anything here — the
+ * format is validated and handed back beside the configuration rather than
+ * written into it. Every other flag is an override, so each replaces exactly
+ * the field it names and leaves every neighboring field as the configuration
+ * wrote it — including whatever resolution folded into that field, which is
+ * why `--exclude` keeps the default globs rather than the six of them being
+ * neighbors it discards. `--config` never reaches this call at all: it chooses
+ * the file the rest are resolved against.
+ *
+ * Every configured field has such an override, save one. `excludeFrom` names
+ * the ignore files a run reads, which is what the run *is* rather than a value
+ * it judges by, and it is workspace-only for the same reason — a project
+ * cannot redirect it either.
+ *
+ * The overrides are grouped rather than listed, one private method per nesting
+ * level of the configuration, because a single returned literal covering four
+ * levels was already the longest thing here at three fields and would not have
+ * survived thirteen.
+ *
+ * One service rather than a merge per command, because the four defects this
+ * replaced were each a different command combining one flag with one field
+ * its own way: an empty `--directories` beating the configured list, a
+ * `--markdown` path discarding the heading and markers beside it, a `--json`
+ * path discarding the configured indentation, and an unrecognized `--format`
+ * rewritten to markdown instead of refused.
+ */
+declare class FlagResolutionService {
+    constructor();
+    /**
+     * Reads one limit flag into the number it chose, or nothing.
+     *
+     * Nothing on every path but success — the flag left off, and both refusals —
+     * because the caller reads this as *what the command line overrode*, and a
+     * refused value reported as an override would be the typo silently winning
+     * the argument it just lost.
+     *
+     * Two refusals rather than one, because they are different mistakes: a value
+     * that is not a positive whole number is a typo, and a value with nothing to
+     * override is the precedence rule. Only `limits.maximumBreadth` can reach the
+     * second — it is the one judged value resolution supplies no default for, and
+     * a flag that could supply one would gate a workspace on a number no
+     * configuration ever chose.
+     */
+    private resolveCount;
+    /**
+     * Applies a path flag to one configured destination, and to nothing else.
+     *
+     * Spread over the configured object rather than resolved afresh from the
+     * path: a destination carries a heading, a description, its anchors, and
+     * its render and write hooks, and re-resolving from a path alone silently
+     * replaced every one of them with a default.
+     *
+     * An undeclared destination is refused rather than invented, which is the
+     * precedence rule itself: a flag may change where a declared report goes
+     * and may not ask for a report the configuration never declared.
+     */
+    private resolveDestination;
+    /**
+     * Applies the entry-point flags to the rules a run roots its stacks with.
+     *
+     * Grouped rather than spread into the caller, so the one returned literal
+     * there stays four fields long however many rules this level grows.
+     */
+    private resolveEntryPoints;
+    /**
+     * Reads `--exclude` the way the configured field beside it is read: over the
+     * top of the globs no repository wants traced, never instead of them.
+     *
+     * `exclude` is the one list resolution does not hand back as written —
+     * `resolveExclude` folds `DEFAULT_EXCLUDE_GLOBS` into it, so the array
+     * arriving here is the authored globs plus six directories nobody chose.
+     * Replacing that array wholesale, as every other list flag rightly does with
+     * its own field, therefore threw away the defaults too: `--exclude src/**`
+     * traced `node_modules` and `dist`. So the flag overrides what the
+     * configuration *authored* and the same additive resolution is re-run over
+     * it, which is what makes `--exclude` and an authored `exclude` mean the
+     * same thing.
+     */
+    private resolveExclude;
+    /**
+     * Reads `--format` into one of the formats a run can print.
+     *
+     * Anything else is refused rather than rewritten. A run that quietly
+     * printed markdown for `--format mermiad` exited 0 having taught its reader
+     * that the flag does nothing.
+     */
+    private resolveFormat;
+    /**
+     * Reads the limit flags into the numbers they chose, and nothing else.
+     *
+     * The overrides are what a flag really said, kept apart from the merged
+     * configuration below, because a limit is enforced per project: a project's
+     * own file declares the number its gate reads, so an override that stopped
+     * at the workspace's copy would be a flag no gate ever looks at. A member is
+     * absent unless a flag supplied it, which is what lets the override be
+     * applied to a declared limit without supplying one where none was declared.
+     */
+    private resolveLimitOverrides;
+    /**
+     * Applies the limit overrides to the numbers the run's own configuration
+     * declares.
+     *
+     * An absent breadth limit is left off the object rather than written as an
+     * explicit `undefined`: `maximumBreadth` is the one optional member here, and
+     * a key that is always present would say a configuration declared a breadth
+     * limit of nothing where resolution had simply never been given one.
+     */
+    private resolveLimits;
+    /**
+     * Reads one list flag, preferring it over the configuration when it named
+     * anything.
+     *
+     * An empty list is absent rather than a value: `--directories ""` and a
+     * `--directories` nobody typed arrive here as the same thing, and reading
+     * either as "trace nothing" — or, as this used to, as "trace everything" in
+     * defiance of a configuration that said otherwise — silently ignores what
+     * was configured. One rule for every list flag, so `--exclude ""` cannot
+     * mean something `--directories ""` does not.
+     */
+    private resolveList;
+    /**
+     * Reads one switch flag into the boolean it names.
+     *
+     * Anything but `true` or `false` is refused rather than coerced, for the
+     * reason `--format` is: a typo read as either answer changes what the run
+     * traces while looking like it was obeyed.
+     */
+    private resolveSwitch;
+    /** Applies the path flags to the destinations a run writes. */
+    private resolveWrite;
+    /**
+     * Resolves a whole command line against one configuration.
+     *
+     * Every complaint is collected rather than thrown at the first one, so a
+     * command line with two mistakes in it is two mistakes to fix rather than
+     * two runs. Nothing has been traced or written by the time this returns, so
+     * a caller that finds `errors` non-empty can refuse with the checkout
+     * untouched.
+     */
+    resolveRunFlags(args: {
+        configuration: ResolvedCallidescopeConfiguration;
+        flags: CallidescopeRunFlags;
+    }): ResolvedRunFlags;
+}
+
+/**
+ * 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 rather than in an `input.errors.ts`, the way
+ * `UnknownConfigurationFileTypeError` sits in `configuration.constants.ts`.
+ */
+export declare class InputError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Parses CLI option values and asks for the ones a command still needs.
+ *
+ * Shared by `callidescope`, `depth`, and `breadth` so the parsing rules for
+ * flags they hold in common — `--config`, `--directories`, `--format` — are
+ * stated once rather than duplicated per command. Mirrors
+ * `@codependix/configuration`'s `InputService`.
+ */
+declare class InputService {
+    constructor();
+    /** 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.
+     */
+    private assertCanPrompt;
+    /**
+     * Narrows a suggestion list to what has been typed so far.
+     *
+     * A method of its own rather than a closure inside the prompt, because this
+     * is the whole of the completion rule and it is worth stating — and testing
+     * — without a terminal anywhere near it.
+     *
+     * Matches on a substring rather than a prefix: a callable is addressed
+     * `<file>#<name>`, and the name is far more often what someone remembers
+     * than the path in front of it.
+     */
+    completeSuggestions(args: {
+        input: string;
+        suggestions: readonly string[];
+    }): string[];
+    /**
+     * Whether anybody is there to answer a question.
+     *
+     * The one place this is decided, so the value that refuses to be asked for
+     * and the value that is merely offered cannot drift apart on what counts as
+     * a terminal. `isTTY` is read as falsy rather than coerced: `@types/node`
+     * calls it a `boolean` while it is `undefined` off a terminal, so lint
+     * rejects the coercion that would say so.
+     *
+     * Public so that `ConfigurationService.resolveFormatOption` can ask it: the
+     * facade owns the policy of whether to offer a prompt, and this class owns
+     * the question it is deciding on. Package-internal all the same — nothing
+     * outside this package can reach this class at all.
+     */
+    isAtTerminal(): boolean;
+    /**
+     * Splits `--directories`, a comma-separated list of project directories.
+     *
+     * Kept relative rather than resolved here: each entry is later resolved
+     * against the workspace root, which is always the working directory, so
+     * resolving here as well would only make a relative entry ambiguous about
+     * which root it was ever relative to.
+     */
+    parseCommaDelimitedOption(value: string | undefined): string[];
+    /** Trims an optional string option, treating blank as absent. */
+    parseOptionalOption(value: string | undefined): string | undefined;
+    /**
+     * Prompts for several values at once, completing the list as it is typed.
+     *
+     * The multiselect sibling of `promptForAutocomplete`, and it shares that
+     * method's completion rule so a name typed here narrows the list the same
+     * way it would there.
+     *
+     * Selecting nothing is refused rather than read as an empty list: the
+     * caller asked because it needs at least one value, and `prompts` returns
+     * `[]` both for a deliberate empty selection and for a prompt escaped out
+     * of, which are the same thing to whoever has to act on it.
+     */
+    promptForAutocompleteMultiselect(args: {
+        message: string;
+        subject: string;
+        suggestions: readonly string[];
+    }): Promise<string[]>;
+    /** Prompts for one value out of a fixed set of choices. */
+    promptForSelect<Choice extends string>(args: {
+        choices: readonly Choice[];
+        message: string;
+        subject: string;
+    }): Promise<Choice>;
+}
+
+/** Arguments accepted by the configuration loader. */
+export declare interface LoadConfigurationArguments {
+    configurationPath?: string | undefined;
+    searchDirectory?: string | undefined;
+}
+
+/**
+ * A resolved configuration, what the file itself declared, and which file it
+ * was.
+ *
+ * Both objects are kept because they answer different questions. A refusal has
+ * to name the fields the file set, which resolution would otherwise
+ * manufacture; anything judging a project reads values only resolution
+ * supplies. The path is what nothing downstream of the search can still tell,
+ * and what keeps one file from being given two roles in a run.
+ */
+export declare interface LoadedCallidescopeConfiguration {
+    /** The file's own object, before a single default was applied. */
+    authored: CallidescopeConfiguration;
+    configuration: ResolvedCallidescopeConfiguration;
+    /** `undefined` when no configuration file was found at all. */
+    path: string | undefined;
+}
+
+/**
+ * What a load reports when the caller named the file, so a path is certain.
+ *
+ * The search may find nothing and legally say so; a named path either resolves
+ * or refuses, and never comes back as `undefined`.
+ */
+export declare interface LoadedCallidescopeConfigurationFile extends LoadedCallidescopeConfiguration {
+    path: string;
+}
+
+/** One project's own configuration file, and the project it configures. */
+export declare interface LoadedProjectConfiguration {
+    /** The file's own object, before a single default was applied. */
+    authored: CallidescopeConfiguration;
+    configuration: ResolvedCallidescopeConfiguration;
+    path: string;
+    /** Workspace-relative root of the project the file sits at. */
+    project: string;
+}
+
+/** Arguments accepted by the project configuration loader. */
+export declare interface LoadProjectConfigurationsArguments {
+    /** Workspace-relative project roots to look beside. */
+    projects: readonly string[];
+    /**
+     * The file already loaded as the run's own workspace configuration, either
+     * absolute or relative to `workspaceRoot` — resolved against that root, the
+     * same way every project path here is, so the two are comparable by
+     * construction rather than by convention.
+     *
+     * One file, one role per run: a configuration that a run was pointed at is
+     * not additionally read as the configuration of whichever project happens to
+     * hold it. A package whose Nx target names its own file is exactly that case,
+     * and treating the file as both would refuse it for the workspace-only fields
+     * it legitimately sets.
+     */
+    workspaceConfigurationPath?: string | undefined;
+    workspaceRoot: string;
+}
+
+/** Splicing helpers handed to a configured `writeBlock` function. */
+export declare interface MarkdownAnchorHelpers {
+    endMarker: string;
+    startMarker: string;
+    /**
+     * Splices the anchored block into a file, appending it when the markers are
+     * absent, and creating the file when it does not exist.
+     *
+     * In check mode nothing is written and the return value reports whether the
+     * file already holds the current block. Defaults to the rendered content and
+     * the configured path; pass either to override.
+     */
+    syncAnchoredBlock: (overrides?: {
+        content?: string | undefined;
+        path?: string | undefined;
+    }) => boolean;
+    /** The content wrapped in the configured markers, ready to place anywhere. */
+    wrapInAnchors: (content?: string) => string;
+}
+
+/**
+ * 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.
+ */
+export declare const missingInputError: (subject: string) => InputError;
+
+/**
+ * What a lookup command line and its configuration resolved to.
+ *
+ * Everything a run resolves except the mode: `depth` and `breadth` never
+ * write or compare a destination, so they have no `--check` or `--write` set
+ * to select and nothing about one to reject.
+ */
+export declare interface PreparedLookup {
+    readonly authoredLimits: CallidescopeLimits | undefined;
+    /** The configuration, with the scope a `--directories` flag named applied. */
+    readonly configuration: ResolvedCallidescopeConfiguration;
+    readonly configurationPath: string | undefined;
+    readonly format: CallidescopeOutputFormat;
+    readonly workspaceRoot: string;
+}
+
+/** What a command line and its configuration resolved to. */
+export declare interface PreparedRun {
+    /**
+     * The limits the workspace file itself wrote down, exactly as authored.
+     *
+     * Carried beside the resolved configuration because resolution manufactures
+     * a default for every limit, so only this can say which numbers that file
+     * really chose — and the workspace row names a file only when one did.
+     */
+    readonly authoredLimits: CallidescopeLimits | undefined;
+    /**
+     * The configuration every flag override has already been applied to.
+     *
+     * The scope a run traces and the destinations it writes are read from here
+     * rather than from the options, so nothing downstream has to remember which
+     * of a flag and a configured value won.
+     */
+    readonly configuration: ResolvedCallidescopeConfiguration;
+    /**
+     * The file the configuration was read from, or `undefined` when the search
+     * found none and the run is on the tool's defaults.
+     *
+     * The trace resolves a configuration beside every project it reaches, and
+     * skips this one: a file a run was pointed at is already that run's workspace
+     * configuration, and reading it again as a project's would refuse it for the
+     * workspace-only fields it is entitled to set.
+     */
+    readonly configurationPath: string | undefined;
+    /**
+     * What the run prints to standard output.
+     *
+     * A presentation choice a command line makes for this one invocation, never
+     * a value a configuration file writes down.
+     */
+    readonly format: CallidescopeOutputFormat;
+    /**
+     * The limits this command line overrode, if any.
+     *
+     * Carried past the resolved configuration because a limit is enforced per
+     * project: each project's own file declares the number its gate reads, so an
+     * override left in the workspace's copy alone would be a flag no gate looks
+     * at.
+     */
+    readonly limitOverrides: CallidescopeLimitOverrides;
+    readonly mode: RunMode;
+    readonly workspaceRoot: string;
+}
+
+/**
+ * Raised when a project's own configuration file cannot be read or parsed.
+ *
+ * Names the project rather than only the path, because a run resolves a file
+ * per project and the failure has to say which one to go and fix. The original
+ * failure is kept as `cause` so nothing a reader would need is thrown away.
+ */
+export declare class ProjectConfigurationError extends Error {
+    constructor(args: {
+        cause: unknown;
+        configurationPath: string;
+        project: string;
+    });
+}
+
+/**
+ * Raised when a project's own configuration sets a field only the workspace
+ * configuration may set.
+ *
+ * Names the project, the offending field, and the four fields a project
+ * configuration may set, so the message is actionable without opening a
+ * README.
+ */
+export declare class ProjectConfigurationFieldNotPermittedError extends Error {
+    constructor(args: {
+        field: string;
+        project: string;
+    });
+}
+
+/**
+ * Raised when a traced project's configuration leaves a field out.
+ *
+ * Names the field as a reader has to type it to fix the file — `write.mermaid`
+ * rather than `write` — and points at the spread that supplies every field a
+ * project has no opinion about, because the fix is almost always that one line
+ * rather than a field written out by hand.
+ */
+export declare class ProjectConfigurationIncompleteError extends Error {
+    constructor(args: {
+        field: string;
+        project: string;
+    });
+}
+
+/**
+ * Raised when a traced project has no configuration file at all.
+ *
+ * A project that is traced is judged, and what it is judged by is written in
+ * its own file or nowhere. Inheriting everything in silence is the arrangement
+ * this replaces: it left a project's numbers resolvable only by reading two
+ * files and knowing which one won.
+ */
+export declare class ProjectConfigurationMissingError extends Error {
+    constructor(project: string);
+}
+
+/**
+ * Resolves the configuration file sitting beside each traced project.
+ *
+ * Its own service rather than more of `ConfigurationFileService`, because the two
+ * answer different questions: one loads the file a run was pointed at, and this
+ * one asks which of a run's projects configure themselves. Every refusal a
+ * project configuration can earn belongs here, where the project it names is
+ * already in hand.
+ */
+declare class ProjectConfigurationService {
+    constructor();
+    /**
+     * Refuses a project configuration that leaves any field out.
+     *
+     * Walked against `authored`, the file exactly as written, for the same reason
+     * the permission check is: resolution manufactures every field for every
+     * project, so asking the resolved object whether a field is missing can never
+     * say yes.
+     */
+    private assertComplete;
+    /**
+     * Refuses a project configuration that sets a field only the workspace
+     * configuration may set.
+     */
+    private assertNoForbiddenFields;
+    /**
+     * Reads the limits one project's own configuration declares.
+     *
+     * The whole object comes from that one file, because completeness means both
+     * numbers were written in it. There is nothing left to fall back to and
+     * nothing to fall back per field: a project that declared no breadth limit
+     * wrote `maximumBreadth: undefined`, which is a decision rather than a gap.
+     */
+    private buildProjectLimits;
+    /**
+     * Reads the limits the workspace file itself declares.
+     *
+     * These are the numbers `projectDefaults` carries into every project's file,
+     * and the ones the directory holding the workspace configuration is judged
+     * by — that being the one project which cannot write a file of its own.
+     *
+     * The file is named only when it really wrote a limit. `maximumDepth` is
+     * defaulted during resolution, so a path stamped unconditionally would name a
+     * file for a number that file never mentions.
+     */
+    private buildWorkspaceLimits;
+    /**
+     * Finds the first field a project's own configuration sets that only the
+     * workspace configuration may set.
+     *
+     * Checked against `authored`, the file exactly as written, never against the
+     * resolved configuration: resolution manufactures every field for every
+     * project, so asking the resolved object whether it "has" a field can never
+     * say no.
+     *
+     * The file's own fields are walked and each is asked whether it is
+     * permitted, rather than a list of forbidden ones being looked for. That is
+     * what makes the check fail closed: a field nothing classifies — a tenth one
+     * added upstream, a name somebody misspelled — is refused by name instead of
+     * being accepted and then quietly doing nothing.
+     */
+    private findForbiddenField;
+    /**
+     * Finds the first member a project set inside a field classified one member
+     * at a time.
+     *
+     * The dotted name is what comes back — `write.json` rather than `write` —
+     * because the field alone would send a reader to delete a block half of
+     * which they are entitled to keep.
+     *
+     * A value that is not an object at all is refused under the field's own
+     * name. The schema has already rejected every such file by the time this
+     * runs, so this is the guard that makes the walk total rather than a branch
+     * with a story behind it.
+     */
+    private findForbiddenMember;
+    /**
+     * Finds the first name a project's configuration leaves out.
+     *
+     * A field is checked for presence rather than for a value, so a project
+     * writing `maximumBreadth: undefined` or `mermaid: undefined` has spoken.
+     * Those two are the whole reason presence and value are kept apart: each is a
+     * project saying it gates no breadth, or publishes no diagram, and an absent
+     * field could never distinguish either from a project that forgot.
+     *
+     * A field present but not an object is reported under its own name, which is
+     * unreachable through the schema and is what makes the walk total.
+     */
+    private findMissingField;
+    /**
+     * Reads one project's configuration file.
+     *
+     * Every failure the read can produce — a file nothing can parse, a shape the
+     * schema rejects — is rethrown naming the project, because a run resolves a
+     * file per project and a bare parse error says nothing about which one to go
+     * and fix.
+     */
+    private loadProjectConfiguration;
+    /**
+     * Applies one command-line limit override to one project's declared limit.
+     *
+     * The precedence rule, at the level a limit is actually enforced: a project
+     * that declared the limit is judged by the flag instead, and a project that
+     * declared none keeps no limit at all. A flag may override what a project chose
+     * and may not choose for a project that chose nothing — which for breadth is
+     * the whole difference between a run `--check breadth` can gate and one it
+     * refuses.
+     */
+    private overrideLimit;
+    /** The name of a whole field a project may not set, or nothing when it may. */
+    private readForbiddenField;
+    /**
+     * Resolves the configuration file sitting at each project's own root — the
+     * directory holding the `tsconfig.json` that makes it a project.
+     *
+     * A traced project with no file of its own is refused. That is the whole
+     * point of the arrangement: what a project is judged by is written in that
+     * project's own file, so a project with no file has nothing written down and
+     * a reader has no second file to go and resolve it against.
+     *
+     * The file must also be complete — every field present, `undefined` written
+     * where a project means to publish nothing or gate nothing. A project spreads
+     * the workspace's `projectDefaults` to get there in one line, which is what
+     * makes completeness cheap enough to require. What it may **not** spread is
+     * the workspace configuration itself: that object carries fields only the
+     * workspace may set, and `findForbiddenField` below refuses the file for the
+     * first one it finds.
+     *
+     * The file a run was pointed at is skipped, and the project holding it is
+     * exempt from the two rules above, because that file is already serving as
+     * the run's workspace configuration. One file, one role per run — reading it
+     * a second time as a project's would refuse it for the workspace-only fields
+     * it legitimately sets, and no second file can sit beside it under a name
+     * discovery would find. That project is judged by the workspace's own limits,
+     * which `resolveLimits` reports for it.
+     */
+    loadProjectConfigurations(args: LoadProjectConfigurationsArguments, reader: ConfigurationFileReader): Promise<LoadedProjectConfiguration[]>;
+    /**
+     * Resolves the depth and breadth limits every traced project is judged
+     * against, each carrying the file its number was written in.
+     *
+     * Every number comes from the project's own file, because loading refuses a
+     * project whose file is absent or incomplete. Nothing is inherited and
+     * nothing is merged — the workspace's numbers reach a project by being
+     * spread into its file, where a reader can see them, rather than by being
+     * resolved behind one.
+     *
+     * The one project handed the workspace's own limits is the directory holding
+     * the workspace configuration, which cannot write a second file under a name
+     * discovery would find.
+     *
+     * One resolver rather than one per reader. A gate and a listing that each
+     * worked this out for themselves could disagree about the same number, and a
+     * limit two answers can be given for is worse than no limit.
+     */
+    resolveLimits(args: ResolveProjectLimitsArguments): ProjectLimitsLookup;
+}
+
+/** Whether a project's own configuration may set one field, or one member. */
+export declare type ProjectFieldPermission = "forbidden" | "permitted";
+
+/**
+ * The two limits one project is gated by, and the file both were written in.
+ *
+ * Only depth and breadth: every other limit shapes how the call graph itself is
+ * built, which has to stay one answer for the whole workspace.
+ *
+ * One `path` for the pair rather than one apiece, because there is only one
+ * file left for either to have come from. Every traced project's configuration
+ * is complete, so both numbers are written in that project's own file or the
+ * file is refused — there is no longer a state in which a project took one
+ * limit from itself and the other from somewhere else.
+ */
+export declare interface ProjectLimits {
+    /** Absent when the project declared no breadth limit, which most do not. */
+    maximumBreadth: number | undefined;
+    maximumDepth: number;
+    /**
+     * The file both numbers were written in.
+     *
+     * Absent only on a workspace row a file never wrote: `maximumDepth` is
+     * defaulted during resolution, so a path stamped unconditionally would name
+     * a file for a number that file never mentions.
+     */
+    path: string | undefined;
+}
+
+/**
+ * The limits every traced project is judged against.
+ *
+ * `byProject` holds an entry for every project a run reached, so a caller
+ * listing the workspace's limits reads this and nothing else. `workspace` is
+ * what the workspace file itself declares — the numbers `projectDefaults`
+ * carries into each project's file, and the ones the directory holding that
+ * very file is judged by, it being the one project that cannot write a
+ * configuration of its own.
+ */
+export declare interface ProjectLimitsLookup {
+    /** Keyed by workspace-relative project root. */
+    byProject: ReadonlyMap<string, ProjectLimits>;
+    workspace: ProjectLimits;
+}
+
+/**
+ * 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.
+ */
+export declare const promptCancelledError: (subject: string) => InputError;
+
+/** What a `render` function is handed. */
+export declare interface RenderMarkdownArguments {
+    /** The configured description, for a renderer that wants to place it itself. */
+    description: string | undefined;
+    /**
+     * The built-in table rendering of these same findings.
+     *
+     * Call it to add to the default report rather than replace it.
+     */
+    renderTables: () => string;
+    result: CallGraphResult;
+}
+
+/** Turns the traced findings into the markdown that will be written. */
+export declare type RenderMarkdownOutput = (args: RenderMarkdownArguments) => string;
+
+/**
+ * Files that mark a repository root.
+ *
+ * `package.json` is deliberately absent: every package in a workspace has one,
+ * so it would stop the upward walk at the first project rather than the root.
+ */
+export declare const REPOSITORY_ROOT_MARKERS: readonly [".git", "pnpm-workspace.yaml"];
+
+/**
+ * Configuration with every default applied.
+ *
+ * Consumers read this shape rather than the authored one, so no analyzer has to
+ * know which fields a configuration file may omit.
+ */
+export declare interface ResolvedCallidescopeConfiguration {
+    directories: string[];
+    entryPoints: ResolvedCallidescopeEntryPoints;
+    exclude: string[];
+    excludeCallees: string[];
+    excludeFrom: string[];
+    limits: ResolvedCallidescopeLimits;
+    write: ResolvedCallidescopeWriteConfiguration;
+}
+
+/** Entry-point rules with defaults applied. */
+export declare interface ResolvedCallidescopeEntryPoints {
+    addresses: string[];
+    decorators: string[];
+    includeExportedFunctions: boolean;
+    includeOrphans: boolean;
+    includeTests: boolean;
+}
+
+/** JSON output destination with defaults applied. */
+export declare interface ResolvedCallidescopeJsonOutputConfiguration {
+    indentation: number;
+    path: string;
+}
+
+/** Thresholds with defaults applied. */
+export declare interface ResolvedCallidescopeLimits {
+    /**
+     * Distinct callables a callable may call directly before it is reported.
+     *
+     * Stays optional even after resolution: unlike every other limit, this one
+     * has no default, so its absence is a fact a `--check breadth` run must act
+     * on rather than something resolution can paper over.
+     */
+    maximumBreadth?: number | undefined;
+    maximumDepth: number;
+}
+
+/**
+ * Markdown output destination with defaults applied.
+ *
+ * `render` and `writeBlock` stay `undefined` when the configuration supplies
+ * neither: the built-in implementations live in the CLI that calls them, so
+ * "unset" is what selects them rather than a default named here.
+ */
+export declare interface ResolvedCallidescopeMarkdownOutputConfiguration {
+    description: string | undefined;
+    endMarker: string;
+    heading: string;
+    path: string;
+    previewCount: number;
+    render: RenderMarkdownOutput | undefined;
+    startMarker: string;
+    writeBlock: undefined | WriteMarkdownOutput;
+}
+
+/**
+ * Output destinations with defaults applied.
+ *
+ * Both stay `undefined` when unconfigured, which is the normal case: a run that
+ * names no destination reports to the console and exits on violations, so
+ * nothing it writes can go stale.
+ */
+export declare interface ResolvedCallidescopeWriteConfiguration {
+    json: ResolvedCallidescopeJsonOutputConfiguration | undefined;
+    markdown: ResolvedCallidescopeMarkdownOutputConfiguration | undefined;
+    mermaid: ResolvedCallidescopeMarkdownOutputConfiguration | undefined;
+}
+
+/** What a command line and the configuration it was resolved against produced. */
+export declare interface ResolvedRunFlags {
+    /**
+     * The configuration every override has been applied to.
+     *
+     * The scope and the destinations a run acts on are read from here rather
+     * than from the flags, so nothing downstream has to remember which of the
+     * two won.
+     */
+    readonly configuration: ResolvedCallidescopeConfiguration;
+    /**
+     * Every reason the command line could not be resolved, collected rather
+     * than thrown one at a time, so a command line with two mistakes in it is
+     * two mistakes to fix rather than two runs.
+     */
+    readonly errors: readonly string[];
+    /** What the run prints. The default whenever the flag was left off. */
+    readonly format: CallidescopeOutputFormat;
+    /**
+     * The limits a flag chose, and only those.
+     *
+     * Carried beside the configuration rather than only inside it because a
+     * limit is enforced per project: each project's own file declares the number
+     * its gate reads, so an override applied only to the workspace's copy would
+     * be a flag no gate ever looks at. Empty whenever no limit flag was given.
+     */
+    readonly limitOverrides: CallidescopeLimitOverrides;
+}
+
+/** Arguments accepted by the per-project limit resolver. */
+export declare interface ResolveProjectLimitsArguments {
+    /**
+     * The limits this run's command line overrode, if any.
+     *
+     * Applied to every project that declared the limit being overridden, because
+     * a project's own number is the one its gate reads — an override that stopped
+     * at the workspace file would be a flag that changed nothing any gate looks
+     * at. A project that declared no breadth limit is left without one: the flag
+     * overrides, and never supplies.
+     */
+    limitOverrides?: CallidescopeLimitOverrides | undefined;
+    /** The configuration files projects declared for themselves. */
+    projectConfigurations: readonly LoadedProjectConfiguration[];
+    /** Workspace-relative root of every project the run reached. */
+    projects: readonly string[];
+    /**
+     * The limits the workspace file itself wrote down, exactly as authored.
+     *
+     * Presence is what decides whether the workspace row names a file: the
+     * resolved configuration below manufactures `maximumDepth` for every run, so
+     * a path stamped from it alone would name a file for a number that file
+     * never wrote.
+     */
+    workspaceAuthoredLimits: CallidescopeLimits | undefined;
+    /** The run's own configuration, which the workspace row reads its numbers from. */
+    workspaceConfiguration: ResolvedCallidescopeConfiguration;
+    /** The file that configuration was read from, when one was found. */
+    workspaceConfigurationPath: string | undefined;
+}
+
+/**
+ * What the run does with what it traces.
+ *
+ * The four are independent. Writing gates on `writes` alone, staleness on
+ * `checksReports` alone, a stack that is too deep on `checksDepth` alone, and
+ * a callable calling too many things on `checksBreadth` alone, so no flag
+ * ever quietly turns another one on.
+ */
+export declare interface RunMode {
+    readonly checksBreadth: boolean;
+    readonly checksDepth: boolean;
+    readonly checksReports: boolean;
+    readonly writes: boolean;
+}
+
+/**
+ * What the command line asked the run to do, and what it could not make sense of.
+ *
+ * Every complaint is collected before any of them is reported, so a command
+ * line with two mistakes in it is two mistakes to fix rather than two runs.
+ */
+declare interface RunModeSelection {
+    readonly errors: readonly string[];
+    readonly mode: RunMode;
+}
+
+/**
+ * Reads a command line and its configuration into what the run will do.
+ *
+ * A collaborator rather than more of `ConfigurationService`, for the reason
+ * every other one here is: resolving flags against a loaded file is its own
+ * job, with its own vocabulary of checks and destinations, and a facade that
+ * implemented it would be a facade in name only. What the layer publishes is
+ * still one object — `ConfigurationService` fronts this the same way it
+ * fronts the file loader, the project loader, and prompting.
+ *
+ * The file read arrives as an argument rather than an injected collaborator,
+ * and the facade hands over itself. That is what keeps the whole layer
+ * replaceable by a double at its one public object: a caller that stubs
+ * `ConfigurationService.loadConfigurationFile` has stubbed what a run plan
+ * reads, rather than only what it would have read by asking the facade
+ * directly. It is a type-only import, so nothing points back at the facade at
+ * module level.
+ */
+declare class RunPlanService {
+    private readonly flagResolutionService;
+    constructor(flagResolutionService: FlagResolutionService);
+    /** States what `--check` accepts, in front of whatever went wrong. */
+    private describeAcceptedCheckNames;
+    /**
+     * 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: it used to mean "fail on a deep stack and on a stale
+     * report at once", and a set with nothing in it looks exactly like the flag
+     * having been left off.
+     */
+    private readCheckNames;
+    /** Keeps the names `--check` knows and complains about the rest. */
+    private validateCheckNames;
+    /**
+     * Reads `depth` and `breadth`'s scoping flags into a workspace root and a
+     * resolved configuration, with no `--check`/`--write` mode to select.
+     *
+     * A lookup command never writes or compares a destination, so it has no
+     * mode to reject in the first place — only the workspace to trace and the
+     * format to print in, both of which every run already resolves the same
+     * way `prepareRun` does.
+     *
+     * A refused command line is thrown rather than returned: unlike a run,
+     * every caller here needs the resolved workspace to do anything at all, so
+     * there is no half-prepared lookup to hand back. `InputError` is the class
+     * every command already reports as a rejected command line.
+     */
+    prepareLookup(options: AddressCommandOptions, reader: ConfigurationFileReader): Promise<PreparedLookup>;
+    /**
+     * Reads the command line and configuration into what the run will do.
+     *
+     * Hands back whatever could not be made sense of rather than reporting it:
+     * two gates can refuse — what `--check` and `--write` mean together, decided
+     * from the command line alone, and whether a destination flag has anything
+     * to override, which needs the configuration loaded first — and both belong
+     * to the host to say out loud, under one headline.
+     */
+    prepareRun(options: CallidescopeCommandOptions, reader: ConfigurationFileReader): Promise<RunPreparation>;
+    /**
+     * 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.
+     */
+    selectMode(options: CallidescopeCommandOptions): RunModeSelection;
+    /**
+     * Whether a run reads or rewrites the files its reports live in.
+     *
+     * A run that neither writes nor compares leaves every destination alone: it
+     * prints what it traced and nothing else. That is what makes a bare run safe
+     * to use at a prompt inside somebody's checkout.
+     */
+    touchesFiles(mode: RunMode): boolean;
+}
+
+/**
+ * What one command line resolved to, and what could not be made sense of.
+ *
+ * Both together rather than one or the other, because refusing is the host's
+ * act rather than this layer's: resolving a run is deciding what it would do,
+ * and saying so on a terminal is what the command-line host is for. Every
+ * complaint is collected before any of them is reported, so a command line
+ * with two mistakes in it is two mistakes to fix rather than two runs.
+ */
+export declare interface RunPreparation {
+    readonly errors: readonly string[];
+    /** Absent exactly when `errors` is not empty. */
+    readonly run: PreparedRun | undefined;
+}
+
+/** Extensions the configuration loader knows how to read. */
+export declare const SUPPORTED_CONFIGURATION_EXTENSIONS: Set<string>;
+
+/** Raised when a configuration file has an extension nothing can read. */
+export declare class UnknownConfigurationFileTypeError extends Error {
+    constructor(filePath: string);
+}
+
+/** What a `writeBlock` function is handed. */
+export declare interface WriteMarkdownArguments {
+    /** True when nothing may be written and staleness is the only question. */
+    check: boolean;
+    /** The rendered markdown, before any anchoring. */
+    content: string;
+    helpers: MarkdownAnchorHelpers;
+    path: string | undefined;
+    result: CallGraphResult;
+}
+
+/**
+ * Decides which file the rendered markdown lands in, and how.
+ *
+ * Return `false` to report the destination as stale — in check mode that is
+ * what fails the command. Anything else counts as up to date.
+ */
+export declare type WriteMarkdownOutput = (args: WriteMarkdownArguments) => boolean;
+
+export { }