@callidescope/graph 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,2119 @@
+import { CallableDocumentation } from '@callidescope/core';
+import { CallableId } from '@callidescope/core';
+import { CallableKind } from '@callidescope/core';
+import { CallableNode } from '@callidescope/core';
+import { CallableSignature } from '@callidescope/core';
+import { CallEdge } from '@callidescope/core';
+import { ConsoleLogger } from '@nestjs/common';
+import { default as default_2 } from 'typescript';
+import { EntryPoint } from '@callidescope/core';
+import pino from 'pino';
+import { ResolvedCallidescopeEntryPoints } from '@callidescope/configuration';
+import { SourceLocation } from '@callidescope/core';
+import { StackFrame } from '@callidescope/core';
+import { UnresolvedCall } from '@callidescope/core';
+import { UnresolvedReason } from '@callidescope/core';
+
+/**
+ * Enumerates every simple path above or below one callable.
+ *
+ * `PathsService` materializes a single deepest path below an entry point,
+ * which is the right answer when the question is "how deep can this go".
+ * An address-centered lookup asks a different question — everything that
+ * calls this, everything this calls — so it walks every path in each
+ * direction instead of folding them into one, using `calleeIdsByCaller` for
+ * what lies below and `callerIdsByCallee` for what lies above.
+ *
+ * The walk is iterative, on an explicit stack of partly consumed frames,
+ * rather than recursive: the same reasoning `ComponentsService` gives for
+ * condensing on an explicit stack applies here, and a widely-called utility
+ * can sit many frames deep in a caller chain.
+ */
+export declare class AddressDepthService {
+    private readonly pathsService;
+    constructor(pathsService: PathsService);
+    /** Follows one neighbor: closes a cycle, stops at an unknown id, or descends. */
+    private follow;
+    /** True when a path holds a frame with an unresolved call beneath it. */
+    private isLowerBound;
+    /** Advances one traversal frame: closes it, follows a neighbor, or backtracks. */
+    private step;
+    /** Turns one raw id path into the frames a report can print. */
+    private toStack;
+    /**
+     * Walks every simple path from `startId` through `adjacency`, capped at
+     * `MAXIMUM_CALL_ADDRESS_STACKS`.
+     *
+     * A neighbor already on the current path closes a cycle rather than being
+     * followed again: the path so far, plus that repeated neighbor, is emitted
+     * as one complete stack, and the walk backtracks instead of looping forever.
+     */
+    private traverse;
+    /** Traces every path from `startId` down to a leaf. */
+    buildDownwardStacks(args: BuildCallAddressStacksArguments): CallAddressTreeResult;
+    /** Traces every path from a root caller up to `startId`. */
+    buildUpwardStacks(args: BuildCallAddressStacksArguments): CallAddressTreeResult;
+}
+
+/**
+ * Resolves a human-typed callable address to the callable it names.
+ *
+ * The address format is the file path plus the qualified name callidescope
+ * already prints in every stack, joined by `#`, the same shape a Python
+ * traceback or an ESLint rule id uses to point at one symbol in one file —
+ * `src/foo.service.ts#FooService.bar`. It is matched against display names
+ * rather than the internal `file#offset` id, because that id is never printed
+ * anywhere a person seeing this tool's own output would have it to type back
+ * in. An optional `:<line>` suffix disambiguates the rare case where a file
+ * holds more than one declaration under the same qualified name — two
+ * differently-typed overloads, or two callbacks bound to the same property in
+ * different branches.
+ */
+export declare class AddressService {
+    constructor();
+    /** Counts how many candidates were declared on each line. */
+    private countCandidatesByLine;
+    /** States the accepted shape, in front of whatever went wrong. */
+    private describeInvalidAddress;
+    /** Finds every discovered callable matching the parsed address. */
+    private findMatches;
+    /** Splits a raw address into its file path and symbol path, if well formed. */
+    private parseAddress;
+    /** Splits a `:<line>` disambiguator off the end of a symbol path, if present. */
+    private parseSymbolPath;
+    /** Writes one callable as the address that names it, with no disambiguator. */
+    private toAddress;
+    /** Turns matched callables into the candidates an ambiguous result names. */
+    private toCandidates;
+    /** Resolves a file path, relative to the workspace root, to POSIX form. */
+    private toWorkspaceRelative;
+    /**
+     * Names what an ambiguous address could have meant, and how to pick one.
+     *
+     * Each candidate is written as the address that would have picked it —
+     * built from the declared address, whose file path and qualified name every
+     * candidate already agrees on, since that agreement is what made it
+     * ambiguous — so the fix is a copy away rather than a file location to go
+     * translate back into an address. Any `:<line>` already on the declared
+     * address is replaced rather than doubled up.
+     *
+     * Two declarations on one line are the case no address can separate: the
+     * matcher filters on the line, so every candidate carries the same one and
+     * the same address would be printed twice. Those name their column instead,
+     * which locates them without pretending to be an address, and the advice
+     * changes to the only fix there is.
+     *
+     * Rendered here rather than by each caller, so the refusal a run prints for
+     * a declared entry point and the one `depth` and `breadth` print for an
+     * address typed at a prompt are one rendering of one concept.
+     */
+    describeCandidates(args: {
+        address: string;
+        candidates: readonly CallableAddressCandidate[];
+    }): string;
+    /**
+     * Every callable a run discovered, written as an address that resolves to it.
+     *
+     * Rendered here rather than by whoever offers the list, so the shape written
+     * out and the shape parsed back in are one class's business and cannot
+     * drift. A pair that occurs more than once in a file carries its `:<line>`
+     * already, so nothing this returns can come back ambiguous — which is what
+     * makes the list safe to pick from blind.
+     */
+    listAddresses(callablesById: ReadonlyMap<string, DiscoveredCallable>): string[];
+    /** Resolves a callable address against every callable a run discovered. */
+    resolve(args: ResolveAddressArguments): CallableAddressResolution;
+}
+
+/** Name given to a function literal nothing else names. */
+export declare const ANONYMOUS_MEMBER_NAME = "anonymous";
+
+/** The call graph, its cycle condensation, and its depth and breadth measurements. */
+export declare interface AssembledGraph {
+    readonly breadthMeasurement: BreadthMeasurement;
+    readonly condensed: CondensedGraph;
+    readonly graph: CallGraph;
+    readonly measurement: DepthMeasurement;
+}
+
+/** Arguments for assembling the call graph and everything derived from it. */
+export declare interface AssembleGraphArguments {
+    readonly callablesById: ReadonlyMap<CallableId, DiscoveredCallable>;
+    readonly excludeCallees: readonly string[];
+    readonly includeConstructorEdges: boolean;
+    readonly workspaceRoot: string;
+}
+
+/** File a package's public surface is declared in. */
+export declare const BARREL_FILE_SUFFIX = "/src/index.ts";
+
+/** File a project's runtime entry point lives in. */
+export declare const BOOTSTRAP_FILE_SUFFIX = "/src/main.ts";
+
+/** Functions a module bootstraps itself through. */
+export declare const BOOTSTRAP_FUNCTION_NAMES: Set<string>;
+
+/** Breadth for every callable measured. */
+export declare interface BreadthMeasurement {
+    readonly byCallable: ReadonlyMap<CallableId, CallableBreadth>;
+}
+
+/**
+ * Measures how many distinct callables each callable calls directly.
+ *
+ * Unlike depth, this needs no condensation: a callable's breadth is well
+ * defined even when it sits in a cycle, since it only ever looks at its own
+ * row in `calleeIdsByCaller` — which `GraphService.assemble` has already
+ * deduped and stripped of self-edges.
+ */
+export declare class BreadthService {
+    constructor();
+    /** Names the callables reached by a list of ids, dropping unknown ones. */
+    private toReferences;
+    /** Names one callable's direct callees and direct callers. */
+    describeDirectCalls(args: {
+        callablesById: ReadonlyMap<CallableId, DiscoveredCallable>;
+        graph: CallGraph;
+        id: CallableId;
+    }): CallableDirectCalls;
+    /** Measures the breadth of every named callable. */
+    measure(args: MeasureBreadthArguments): BreadthMeasurement;
+}
+
+/** Arguments for tracing every path in one direction from a callable. */
+export declare interface BuildCallAddressStacksArguments {
+    readonly callablesById: ReadonlyMap<CallableId, DiscoveredCallable>;
+    readonly graph: CallGraph;
+    readonly startId: CallableId;
+}
+
+/** Arguments for turning every callable's body into edges. */
+export declare interface BuildEdgesArguments {
+    readonly callablesById: ReadonlyMap<CallableId, DiscoveredCallable>;
+    readonly excludeCallees: readonly string[];
+    readonly includeConstructorEdges: boolean;
+    readonly workspaceRoot: string;
+}
+
+/** Arguments for building the set of paths a run will not trace. */
+export declare interface BuildExclusionsArguments {
+    readonly exclude: readonly string[];
+    readonly excludeFrom: readonly string[];
+    readonly workspaceRoot: string;
+}
+
+/** Arguments for building the class-hierarchy index. */
+export declare interface BuildHierarchyArguments {
+    readonly programs: readonly ProjectProgram[];
+}
+
+/** Arguments for building a program for every project in a closure. */
+export declare interface BuildProgramsArguments {
+    /**
+     * The projects a run was asked to trace. Every one of them gets a program,
+     * and so does every project their imports transitively reach.
+     */
+    readonly startingProjects: readonly WorkspaceProject[];
+    /**
+     * Every project the workspace holds, which is what lets a file one program
+     * pulled in name the project that owns it — including a project no starting
+     * root mentions. Nothing here is built unless the closure reaches it.
+     */
+    readonly workspaceProjects: readonly WorkspaceProject[];
+    readonly workspaceRoot: string;
+}
+
+/** Arguments for layering each project's own exclusions over a run's. */
+export declare interface BuildProjectFileFilterArguments {
+    /**
+     * The globs each project declared for itself, keyed by project name, exactly
+     * as that project's own configuration file wrote them.
+     *
+     * A project that declared none is absent rather than present with an empty
+     * array, so an empty map means no project in the run excludes anything and
+     * the run's own filter is handed straight back.
+     */
+    readonly excludeByProject: ReadonlyMap<string, readonly string[]>;
+    /** The run's own filter, which every project's globs are layered over. */
+    readonly fileFilter: FileFilter;
+    /**
+     * Every project the run reached, so a file is judged by the project that
+     * owns it rather than by whichever declaring root happens to contain it.
+     */
+    readonly projects: readonly WorkspaceProject[];
+}
+
+/** One declaration an ambiguous address could have meant. */
+export declare interface CallableAddressCandidate {
+    readonly id: CallableId;
+    readonly location: SourceLocation;
+}
+
+/**
+ * What resolving a callable address produced.
+ *
+ * A union rather than an optional id: the four outcomes are told apart by
+ * what a caller does next — proceed, or print exactly one of four different
+ * messages — and a single `id: CallableId | undefined` cannot carry which of
+ * the three failures happened.
+ */
+export declare type CallableAddressResolution = {
+    readonly candidates: readonly CallableAddressCandidate[];
+    readonly kind: "ambiguous";
+} | {
+    readonly id: CallableId;
+    readonly kind: "resolved";
+} | {
+    readonly kind: "invalid";
+    readonly reason: string;
+} | {
+    readonly kind: "not-found";
+};
+
+/**
+ * How many callables one callable calls directly, and which ones.
+ *
+ * `calleeIds` holds the distinct callables reached, not call sites: `assemble`
+ * already dedupes repeat calls and drops self-edges when it builds
+ * `calleeIdsByCaller`, so breadth inherits both properties for free.
+ */
+export declare interface CallableBreadth {
+    readonly breadth: number;
+    readonly calleeIds: readonly CallableId[];
+}
+
+/** Everything the walk over owned files produced. */
+export declare interface CallableCollection {
+    readonly byId: ReadonlyMap<CallableId, DiscoveredCallable>;
+    readonly fileCount: number;
+    /** How many files each project contributed, for its own report. */
+    readonly fileCountByProject: ReadonlyMap<string, number>;
+}
+
+/** Any declaration the tool treats as a frame on a call stack. */
+export declare type CallableDeclaration = default_2.ArrowFunction | default_2.ConstructorDeclaration | default_2.FunctionDeclaration | default_2.FunctionExpression | default_2.GetAccessorDeclaration | default_2.MethodDeclaration | default_2.SetAccessorDeclaration;
+
+/** The direct callees and direct callers of one addressed callable. */
+export declare interface CallableDirectCalls {
+    readonly callees: readonly CallableReference[];
+    readonly callers: readonly CallableReference[];
+}
+
+/**
+ * Gives every callable a stable identifier and a name a report can print.
+ *
+ * The identifier is the file path plus the declaration's start offset, not its
+ * line. Two callables share a line often — an arrow property and the statement
+ * holding it do — but exactly one declaration can begin at one offset, so an
+ * offset cannot collide the way a line can.
+ */
+export declare class CallableIdentityService {
+    constructor();
+    /**
+     * Names a function literal by the call it was passed to.
+     *
+     * `ExampleService.load → map(…)` reads far better in a stack than
+     * `anonymous`, and it is the only name a callback ever really has.
+     */
+    private describeCallbackArgument;
+    /** Reads the name a property, variable, or parameter declaration binds. */
+    private readBindingName;
+    /**
+     * Classifies a function literal by whatever binds it.
+     *
+     * A literal has no shape of its own worth naming — what it is depends
+     * entirely on where it was written down.
+     */
+    private readBoundKind;
+    /** Builds the identifier for one declaration. */
+    buildId(args: {
+        declaration: CallableDeclaration;
+        workspaceRelativePath: string;
+    }): string;
+    /** Counts the statements in a body, as a proxy for how much it does. */
+    countStatements(declaration: CallableDeclaration): number;
+    /**
+     * True when a declaration is reachable from outside its own file.
+     *
+     * Three shapes carry the keyword, and only one of them carries it on the
+     * declaration the graph holds. A method's `export` sits on its class, and an
+     * arrow constant's sits on the variable statement above the arrow — the shape
+     * a React component, an anchor builder, and most barrel exports are written
+     * in. Reading the arrow's own modifiers alone leaves every one of them
+     * looking unexported, and so promoted as an orphan rather than classified as
+     * the barrel export it is.
+     */
+    isExported(declaration: CallableDeclaration): boolean;
+    /** Builds the qualified name a report prints for a callable. */
+    readDisplayName(declaration: CallableDeclaration): string;
+    /** Names the class or interface a declaration is a member of, if any. */
+    readEnclosingTypeName(declaration: CallableDeclaration): string | undefined;
+    /** Classifies a declaration by the shape it was written in. */
+    readKind(declaration: CallableDeclaration): CallableKind;
+    /** Reads the one-based line and column a declaration starts at. */
+    readLocation(args: {
+        declaration: CallableDeclaration;
+        workspaceRelativePath: string;
+    }): SourceLocation;
+    /** Reads the member name, falling back to the shape it was written in. */
+    readMemberName(declaration: CallableDeclaration): string;
+}
+
+/** One callable named alongside where it is declared. */
+export declare interface CallableReference {
+    readonly displayName: string;
+    readonly id: CallableId;
+    readonly location: SourceLocation;
+}
+
+/**
+ * Provides discovery and naming of every callable in the workspace.
+ */
+export declare class CallablesModule {
+}
+
+/**
+ * Walks every owned file and collects the callables a call stack can hold.
+ *
+ * Overload signatures are skipped in favour of the one declaration with a body:
+ * a signature is a promise about a call, not a frame the runtime ever pushes.
+ */
+export declare class CallablesService {
+    private readonly callableIdentityService;
+    private readonly programService;
+    private readonly workspaceService;
+    constructor(callableIdentityService: CallableIdentityService, programService: ProgramService, workspaceService: WorkspaceService);
+    /** Collects every callable declaration in one source file. */
+    private collectFromFile;
+    /**
+     * Walks the files one program owns, skipping the ones it does not.
+     *
+     * Iterating the program's own source files rather than looking each owned
+     * path up in it. A workspace reached through a symlink — a macOS temp
+     * directory, a pnpm store — hands the program one spelling of a path and the
+     * ownership map another, and a lookup would then quietly find nothing rather
+     * than fail.
+     */
+    private collectFromProgram;
+    /** Turns one declaration into a fully described node. */
+    private describe;
+    /** True when a node is a declaration this tool treats as a frame. */
+    private isCallableDeclaration;
+    /** Returns the workspace-relative path, or nothing when unowned. */
+    private readOwnedPath;
+    /**
+     * Walks every owned file and returns the callables found, keyed by id.
+     *
+     * Each file is walked by the one program that owns it, so a package shared by
+     * several projects contributes its callables once rather than once per
+     * dependent.
+     */
+    collect(args: CollectCallablesArguments): CallableCollection;
+}
+
+/** One simple path traced above or below an addressed callable. */
+export declare interface CallAddressStack {
+    readonly frames: readonly StackFrame[];
+    /**
+     * True when a frame on this path holds an unresolved call, making the path
+     * a floor rather than a complete picture of what lies beyond it.
+     */
+    readonly isLowerBound: boolean;
+}
+
+/** Every path traced in one direction, and whether the walk was capped. */
+export declare interface CallAddressTreeResult {
+    readonly stacks: readonly CallAddressStack[];
+    /** True when `MAXIMUM_CALL_ADDRESS_STACKS` was reached before the walk finished. */
+    readonly truncated: boolean;
+}
+
+/** The assembled call graph, indexed both ways. */
+export declare interface CallGraph {
+    readonly calleeIdsByCaller: ReadonlyMap<CallableId, readonly CallableId[]>;
+    readonly callerIdsByCallee: ReadonlyMap<CallableId, readonly CallableId[]>;
+    readonly edges: readonly CallEdge[];
+    /** Callables holding at least one call that could not be followed. */
+    readonly unresolvedCallerIds: ReadonlySet<CallableId>;
+    readonly unresolvedCalls: readonly UnresolvedCall[];
+}
+
+/** A call expression found inside one callable's own body. */
+export declare interface CallSite {
+    readonly expression: default_2.CallExpression | default_2.NewExpression;
+    /** Function literals passed as arguments, each its own frame. */
+    readonly functionArguments: readonly default_2.SignatureDeclaration[];
+}
+
+/**
+ * Finds the calls one callable makes, without descending into nested bodies.
+ *
+ * A function literal inside a body is its own frame, not part of the enclosing
+ * one, so the walk stops at it. Descending would attribute a callback's calls
+ * to whichever function happened to contain the callback's text, which is how
+ * a shallow orchestrator ends up looking like the deepest thing in the file.
+ */
+export declare class CallSitesService {
+    constructor();
+    /** True when a node opens a new frame and the walk should stop. */
+    private isNestedBody;
+    /** Collects the function literals passed as arguments to one call. */
+    private readFunctionArguments;
+    /** Collects every call this declaration's own body makes. */
+    collect(declaration: CallableDeclaration): CallSite[];
+}
+
+/**
+ * Provides the lookups edge resolution consults for every call site.
+ */
+export declare class ClassesModule {
+}
+
+/**
+ * Resolves an interface or abstract member to the classes that implement it.
+ *
+ * The language service can answer this directly, and answering it that way
+ * costs milliseconds per call site — minutes across a repository. This builds
+ * one index up front instead, and answers from it in constant time.
+ *
+ * The index has to be structural, not just nominal. Classes in this repository
+ * routinely satisfy an interface without writing `implements`, and the
+ * interface members themselves are usually arrow-typed properties rather than
+ * method signatures. An index that only followed `implements` clauses would
+ * find none of them.
+ */
+export declare class ClassesService {
+    private readonly externalService;
+    constructor(externalService: ExternalService);
+    private readonly checkerByClass;
+    /** Every traced class that declares a member of a given name. */
+    private readonly classesByMemberName;
+    /** Classes naming a base in an `implements` or `extends` clause. */
+    private readonly derivedByBaseName;
+    private readonly lookupCache;
+    /**
+     * Walks the whole inheritance chain below a base, not just its children.
+     *
+     * An abstract base is often extended by another abstract class, with the
+     * concrete implementation another level down. Following only direct
+     * subclasses finds the intermediate one, discards it for still being
+     * abstract, and reports that nothing implements the member.
+     */
+    private collectDerived;
+    /** Keeps only classes whose instance type satisfies the declaring type. */
+    private filterAssignable;
+    /** Records one class under every base type it names. */
+    private indexHeritage;
+    /** Records one class under every member name it declares. */
+    private indexMembers;
+    /** Reads one member's concrete declarations off a candidate class. */
+    private readMemberDeclarations;
+    /** Walks every traced class once, recording members and heritage. */
+    build(args: BuildHierarchyArguments): void;
+    /** Indexes the classes one program owns. */
+    indexProgram(projectProgram: ProjectProgram): void;
+    /**
+     * Finds the concrete declarations one interface member resolves to.
+     *
+     * Nominal implementers are preferred; when a base names none — the common
+     * case here — every class declaring a member of that name is tested for
+     * assignability instead. Filtering by member name first is what keeps that
+     * sweep cheap enough to run.
+     */
+    resolveImplementations(args: {
+        checker: default_2.TypeChecker;
+        memberName: string;
+        ownerName: string;
+        ownerSymbol: default_2.Symbol;
+    }): ImplementationLookup;
+}
+
+/** Arguments for collecting every callable a run will trace. */
+export declare interface CollectCallablesArguments {
+    readonly fileFilter: FileFilter;
+    /** What a project that declared no entry-point rules of its own is judged by. */
+    readonly includeTests: boolean;
+    /**
+     * The answer each project declared for itself, keyed by project name.
+     *
+     * A project absent here is judged by `includeTests`, exactly the way a
+     * project absent from `entryPointsByProject` is judged by the run's own
+     * entry-point rules — this is the same declaration read at the one layer
+     * that can act on it, since which files a run even looks at is settled here
+     * rather than when roots are chosen.
+     */
+    readonly includeTestsByProject: ReadonlyMap<string, boolean>;
+    readonly ownerByFilePath: ReadonlyMap<string, ProjectProgram>;
+    readonly workspaceRoot: string;
+}
+
+/** The method a decorated command class exposes to its runner. */
+export declare const COMMAND_RUNNER_METHOD_NAME = "run";
+
+/**
+ * Builds compiler hosts that share parsed source files across programs.
+ *
+ * Every project's program pulls in the same lib files and the same workspace
+ * dependencies, so without sharing, one run re-reads `lib.es2023.d.ts` once per
+ * project and the shared packages roughly one and a half times over. Caching is
+ * the difference between a ten-second run and a five-second one, and it costs
+ * nothing in correctness as long as the cache key names the script target.
+ */
+export declare class CompilerHostService {
+    constructor();
+    private readonly moduleResolutionCaches;
+    /**
+     * Keyed on file name and script target together.
+     *
+     * The target has to be part of the key. A source file parsed at ES2023 has a
+     * different tree from the same text parsed at ES5, so handing a cached one to
+     * a program that asked for another target is silently wrong.
+     */
+    private readonly sourceFileCache;
+    /** Returns the module resolution cache for one working directory. */
+    private resolveModuleCache;
+    /** Drops every cached source file, for a host that outlives one run. */
+    clear(): void;
+    /**
+     * Creates a compiler host that reuses already-parsed source files.
+     *
+     * `setParentNodes` is on because the rest of the package reads `node.parent`
+     * and `node.getStart()`, neither of which works on a tree parsed without it,
+     * and neither of which `createProgram` turns on by itself for files it pulls
+     * in rather than files it was handed.
+     */
+    createHost(args: {
+        options: default_2.CompilerOptions;
+        workspaceRoot: string;
+    }): default_2.CompilerHost;
+}
+
+/** Memoized longest-path result for one component. */
+export declare interface ComponentDepth {
+    /** The successor lying on the deepest path, for O(depth) reconstruction. */
+    readonly deepestSuccessor: number | undefined;
+    readonly depth: number;
+    /** True when the deepest path runs through an unfollowable call. */
+    readonly reachesUnresolved: boolean;
+}
+
+/**
+ * Collapses every cycle in the call graph into a single node.
+ *
+ * Longest path is only defined on an acyclic graph, so recursion has to be
+ * dealt with before depth is measured rather than during it. The obvious
+ * alternative — detecting a repeat visit while walking — makes the memoized
+ * depth depend on which path happened to arrive first, so the same function
+ * reports different depths from different entry points and between runs. A
+ * linter whose numbers move on their own is not usable as a gate.
+ *
+ * Condensing instead gives every cycle one cost, counted once: three functions
+ * calling each other in a ring contribute three frames, which is an honest
+ * floor on a stack that has no ceiling.
+ *
+ * The traversal is iterative because the graph is deep enough that a recursive
+ * one risks blowing the JavaScript stack while measuring stack depth.
+ */
+export declare class ComponentsService {
+    constructor();
+    /**
+     * Closes a completed node, emitting a component when it is a root.
+     *
+     * A node whose low link never moved below its own discovery order is the
+     * entry point of a strongly connected component, and everything above it on
+     * the pending stack belongs to that component.
+     */
+    private closeNode;
+    /** Pops a finished frame, emitting its component and lifting its low link. */
+    private finishFrame;
+    /** Propagates a finished child's low link into its parent. */
+    private liftLowLink;
+    /** Records the discovery order of a node and pushes it onto the stack. */
+    private openNode;
+    /** Advances the traversal by one step from the given frame. */
+    private step;
+    /** Descends into one successor, or folds it back if already seen. */
+    private visitSuccessor;
+    /** Lifts the callable-level edges onto the condensed components. */
+    buildSuccessors(args: {
+        componentIdByCallable: ReadonlyMap<CallableId, number>;
+        graph: CallGraph;
+        memberIdsByComponent: readonly (readonly CallableId[])[];
+    }): ReadonlySet<number>[];
+    /** Condenses the graph, returning components in reverse topological order. */
+    condense(args: {
+        callableIds: Iterable<CallableId, undefined, undefined>;
+        graph: CallGraph;
+    }): CondensedGraph;
+}
+
+/** A call through a computed member name, which nothing can follow. */
+export declare const COMPUTED_MEMBER_CALL: ResolvedCallSite;
+
+/**
+ * The graph with each cycle collapsed into one node.
+ *
+ * Longest path is only well defined on an acyclic graph, so recursion is
+ * condensed away before depth is computed rather than special-cased during it.
+ */
+export declare interface CondensedGraph {
+    readonly componentIdByCallable: ReadonlyMap<CallableId, number>;
+    readonly memberIdsByComponent: readonly (readonly CallableId[])[];
+    readonly successorsByComponent: readonly ReadonlySet<number>[];
+}
+
+/** The tag that marks a callable as on its way out. */
+export declare const DEPRECATED_TAG = "deprecated";
+
+/** Depth for every component in the condensation. */
+export declare interface DepthMeasurement {
+    readonly byComponent: readonly ComponentDepth[];
+}
+
+/** Arguments for naming one declaration. */
+export declare interface DescribeCallableArguments {
+    readonly declaration: CallableDeclaration;
+    readonly projectProgram: ProjectProgram;
+    readonly workspaceRelativePath: string;
+}
+
+/** One discovered callable, kept alongside the node it was found at. */
+export declare interface DiscoveredCallable {
+    readonly declaration: CallableDeclaration;
+    readonly node: CallableNode;
+    readonly projectProgram: ProjectProgram;
+}
+
+/** Arguments for discovering the projects a run will trace. */
+export declare interface DiscoverProjectsArguments {
+    /**
+     * Project directories to trace, workspace-relative or absolute. Every
+     * directory under the workspace root holding its own `tsconfig.json`
+     * when empty.
+     */
+    readonly directories: readonly string[];
+    /**
+     * Decides which projects a run will not trace, judged on the
+     * `tsconfig.json` that would identify each one.
+     *
+     * Applied here rather than only to the files a program yields, because a
+     * `tsconfig.json` an exclusion already names should never be read at all —
+     * one that does not parse, belonging to a directory nobody asked to trace,
+     * is not a reason for the run to say anything.
+     */
+    readonly fileFilter?: FileFilter | undefined;
+    readonly workspaceRoot: string;
+}
+
+/**
+ * Provides the prose a report prints beneath a frame.
+ */
+export declare class DocumentationModule {
+}
+
+/**
+ * Reads what a callable's documentation comment says about it.
+ *
+ * Read through the type checker rather than the comment trivia above the node,
+ * which is what makes it right on the shapes this repository writes. An
+ * overload's comment sits on the signature rather than the implementation the
+ * graph points at, and an arrow-typed member's sits on the property rather than
+ * the arrow — the checker resolves both to the same symbol, and scanning
+ * trivia would find neither.
+ */
+export declare class DocumentationService {
+    constructor();
+    /**
+     * Collapses a documentation comment onto one line, in full.
+     *
+     * Nothing is shortened here. A comment is what it is, and how much of it
+     * fits is a question about the thing being rendered into — an indented tree
+     * in a terminal has an answer, and a JSON report consumed by a machine does
+     * not. Shortening at the point of reading would impose the terminal's answer
+     * on every consumer, so `ReportService` decides instead.
+     */
+    private readSummary;
+    /** Resolves the symbol a declaration's documentation hangs off. */
+    private readSymbol;
+    /**
+     * Reads the documentation comment, if the callable has one.
+     *
+     * A comment that is nothing but tags — `@deprecated` on its own — leaves the
+     * summary empty, so the tags are read separately rather than inferred from
+     * whether there was any prose to find.
+     */
+    read(args: ReadDocumentationArguments): CallableDocumentation | undefined;
+}
+
+/** A call whose callee could not be identified at all. */
+export declare const DYNAMIC_CALL: ResolvedCallSite;
+
+/** Every edge a run resolved, and every call site it could not. */
+export declare interface EdgeCollection {
+    readonly edges: readonly CallEdge[];
+    readonly unresolvedCalls: readonly UnresolvedCall[];
+}
+
+/**
+ * Provides call-site discovery and resolution into call-graph edges.
+ */
+export declare class EdgesModule {
+}
+
+/**
+ * Turns every callable's body into edges in the call graph.
+ *
+ * Only calls landing on traced code become edges. A call into a dependency is a
+ * leaf: whether `Array.prototype.map` is deeply implemented is not a fact about
+ * whether this repository's layering is too deep, and counting it would make
+ * every reported number move on an unrelated upgrade.
+ */
+export declare class EdgesService {
+    private readonly callSitesService;
+    private readonly externalService;
+    private readonly programService;
+    private readonly symbolResolutionService;
+    private readonly workspaceService;
+    private readonly logger;
+    constructor(callSitesService: CallSitesService, externalService: ExternalService, programService: ProgramService, symbolResolutionService: SymbolResolutionService, workspaceService: WorkspaceService, logger: LoggerService);
+    /** Turns one call site into the edges and non-resolutions it produced. */
+    private buildSiteEdges;
+    /** Records the function literals one call site passes as arguments. */
+    private collectCallbackEdges;
+    /**
+     * Whether a callee's own display name matches a configured exclusion glob.
+     *
+     * Matched against `Type.member` rather than against a path: a
+     * cross-cutting callable like a logger
+     * has no single file worth naming, but every one of its call sites shares
+     * the same display name.
+     */
+    private isExcludedCallee;
+    /** Reads the one-based position of a node, for a report. */
+    private readLocation;
+    /**
+     * Maps a resolved declaration to the callable it belongs to.
+     *
+     * A resolution can land on a property or variable declaration whose
+     * initializer is the real function, which is how this repository writes both
+     * arrow-typed class members and object-literal methods.
+     */
+    private resolveCallableId;
+    /** Resolves one call site, choosing the right strategy for its shape. */
+    private resolveSite;
+    /** Builds every edge in the graph, and records the calls it could not. */
+    build(args: BuildEdgesArguments): EdgeCollection;
+}
+
+/**
+ * Provides the rules deciding which callables root a call stack.
+ */
+export declare class EntriesModule {
+}
+
+/**
+ * Decides which callables are the roots of a call stack.
+ *
+ * This is where the tool is most likely to be wrong, and the numbers it reports
+ * are only as meaningful as this list. Most code in a repository like this one
+ * is never called by anything inside it — a framework calls it. So the roots
+ * have to be named, and anything missed would silently vanish from every
+ * measurement rather than fail loudly.
+ *
+ * A configuration can also name a root outright, by the same address the
+ * lookup commands take, for the surface no rule here can infer. Those are
+ * additive: they never turn a rule off.
+ *
+ * Orphan promotion is the guard against exactly that. After the named rules
+ * run, anything with no caller left in the graph becomes a root anyway, so a
+ * rule this list is missing shows up as an orphan instead of as a hole.
+ */
+export declare class EntriesService {
+    private readonly addressService;
+    private readonly logger;
+    constructor(addressService: AddressService, logger: LoggerService);
+    /** Classifies a callable's declaration, or leaves it unrooted. */
+    private classify;
+    /** Roots every callable one of the entry-point rules recognizes. */
+    private classifyEveryCallable;
+    /** True when a node carries one of the configured framework decorators. */
+    private hasConfiguredDecorator;
+    /** True when a function is a module's own runtime entry point. */
+    private isBootstrapFunction;
+    /** True when a method is the entry point of a decorated command class. */
+    private isCommandRunnerMethod;
+    /**
+     * Every configuration whose declared addresses a run must resolve, paired
+     * with the project that wrote it.
+     *
+     * The workspace configuration is one of them and has no project to name, so
+     * it is listed once under `undefined` rather than repeated for each project
+     * that inherits it — which would resolve one address as many times as there
+     * are projects, and report one mistake as several.
+     */
+    private listDeclaringConfigurations;
+    /** Roots whatever neither a rule nor a declaration claimed, and nothing calls. */
+    private promoteOrphans;
+    /** Reads the names of the decorators applied to a node. */
+    private readDecoratorNames;
+    /**
+     * The rules the project owning a callable is judged by.
+     *
+     * Positional rather than an options object, unlike almost everything else
+     * here: it is asked once per callable in each of two passes, and building an
+     * argument object for every one of them is thousands of allocations to say
+     * what two names already say.
+     */
+    private readRules;
+    /**
+     * Roots one declared address, or reports why it named no single callable.
+     *
+     * Resolved through the service the `depth` and `breadth` commands use, so
+     * the `:<line>` disambiguator and every refusal behave here exactly as they
+     * do at a prompt. An address landing on a callable something already
+     * claimed adds no second root: the two are one callable under two
+     * spellings, and roots are deduplicated by the callable, never by the text.
+     */
+    private rootDeclaredAddress;
+    /** Roots every declared address, collecting the ones that resolved to nothing. */
+    private rootDeclaredAddresses;
+    /** Reads one configuration's entry-point rules into what classification needs. */
+    private toRules;
+    /**
+     * Resolves every root a run will measure depth from.
+     *
+     * Three passes, in this order. The rules run first, so a callable one of
+     * them already rooted keeps the kind saying *why* something calls it.
+     * Declared addresses run next, rooting whatever the rules did not reach.
+     * Orphan promotion runs last, over what neither claimed.
+     *
+     * Every pass reads the rules of the project owning the callable, so a
+     * package's own entry points hold wherever the run started from — a leaf
+     * pulled in through another project's dependency closure is judged by its
+     * own configuration, not by whoever reached it.
+     */
+    resolve(args: ResolveEntriesArguments): EntryPointCollection;
+}
+
+/** The roots a run will measure depth from. */
+export declare interface EntryPointCollection {
+    readonly entryPoints: readonly EntryPoint[];
+    /**
+     * Every declared address that named no callable, or more than one.
+     *
+     * Returned rather than logged or skipped: a declared address that stops
+     * resolving is a root silently leaving the measurement, which lowers the
+     * project's depth and loosens its gate with nothing in the output to say so.
+     * The caller is what turns these into a refusal.
+     */
+    readonly unresolvedAddresses: readonly UnresolvedEntryPointAddress[];
+}
+
+/**
+ * Directory names a project scan never descends into.
+ *
+ * Each one either holds no source of its own (`node_modules`, dependency and
+ * build caches) or is generated output (`dist`, `build`, `coverage`) — walking
+ * into any of them either finds nothing or finds a `tsconfig.json` that
+ * belongs to a dependency, not a project this run should trace.
+ */
+export declare const EXCLUDED_SCAN_DIRECTORY_NAMES: readonly ["node_modules", ".git", ".nx", ".conformetry", "dist", "build", "coverage", "out"];
+
+/** A call that left the traced code: no edge, and no gap to report either. */
+export declare const EXTERNAL_CALL: ResolvedCallSite;
+
+/**
+ * Decides whether a declaration lives outside the code being traced.
+ *
+ * This is the filter the whole tool rests on. Most call sites in any real file
+ * resolve into `lib.es5.d.ts` or a dependency; without this, every `.map()` and
+ * `.trim()` becomes a frame, and the deepest stack in the repository turns out
+ * to be somewhere inside a standard-library type declaration.
+ *
+ * The verdict is memoized per source file rather than per call site because it
+ * is asked tens of thousands of times per run and the answer only ever depends
+ * on the file.
+ */
+export declare class ExternalService {
+    constructor();
+    private ownedFilePaths;
+    private readonly verdicts;
+    private workspaceRoot;
+    /** Works out whether a file is outside the traced set. */
+    private computeVerdict;
+    /** Points the predicate at one run's workspace and owned-file set. */
+    configure(args: {
+        ownedFilePaths: ReadonlySet<string>;
+        workspaceRoot: string;
+    }): void;
+    /** True when a declaration's file is not part of the traced code. */
+    isExternal(sourceFile: default_2.SourceFile): boolean;
+    /** True when a file is one this run walks declarations in. */
+    isOwned(realPath: string): boolean;
+}
+
+/** Decides whether a file is traced. */
+export declare interface FileFilter {
+    /** True when the file should be left out of the graph. */
+    readonly isExcluded: (workspaceRelativePath: string) => boolean;
+}
+
+/**
+ * Decides which files a run leaves out of the graph.
+ *
+ * Its own service rather than more of `WorkspaceService`, because a run builds
+ * two filters at two different moments and only one of them can exist before
+ * the projects are known. The run's own exclusions are settled from the file
+ * the run was pointed at, so they are what project discovery is judged by; a
+ * project's own exclusions are written in a file sitting at a project root, so
+ * nothing can read them until that root has been discovered. Layering the two
+ * is this service's whole subject.
+ */
+export declare class FileFilterService {
+    private readonly workspaceService;
+    private readonly logger;
+    constructor(workspaceService: WorkspaceService, logger: LoggerService);
+    /**
+     * True when the project owning a file excludes it with a glob of its own.
+     *
+     * The project that *owns* the file rather than any project containing it, so
+     * a project nested under another answers for its own files: a parent's globs
+     * stop at the nested root exactly the way every other per-project answer
+     * does. `WorkspaceService.resolveOwningProject` is asked rather than a second
+     * containment rule written here, because a file with two answers about which
+     * project it belongs to is worse than a file with none.
+     *
+     * The glob is matched against the path *relative to the owning project's
+     * root*, which is what keeps a project's globs inside that project. See
+     * `buildProjectFileFilter` for why that anchoring rather than the run's.
+     */
+    private isExcludedByOwningProject;
+    /**
+     * Asks git which tracked files an ignore file excludes.
+     *
+     * Delegating to git rather than reimplementing gitignore matching is what
+     * makes `.callidescopeignore` behave the way its syntax promises. The
+     * argument vector form of `execFileSync` keeps a configured path out of a
+     * shell.
+     */
+    private listIgnoredFiles;
+    /**
+     * Builds the predicate deciding which files stay out of the graph.
+     *
+     * Exclusion globs are matched with Node's own `path.matchesGlob` rather than
+     * a dependency, and gitignore-syntax files are resolved through git itself.
+     *
+     * This is the *run's* filter and nothing else: its globs come from the file
+     * the run was pointed at, and they are written workspace-relative because
+     * that file describes a whole workspace. It is what project discovery is
+     * judged by, which is the reason the per-project layer is a second call
+     * rather than another argument here — a project's globs cannot be read until
+     * the project has been discovered, and discovery is what this filter decides.
+     */
+    buildFileFilter(args: BuildExclusionsArguments): FileFilter;
+    /**
+     * Layers every project's own exclusion globs over the run's filter.
+     *
+     * **A project's globs are anchored to that project's root**, never to the
+     * workspace: `exclude: ["*.generated.ts"]` in `packages/thing`'s own
+     * configuration names `packages/thing/*.generated.ts` and can name nothing
+     * else. Three reasons, in the order they matter:
+     *
+     * - It is what makes "a project excludes its own files" true by
+     *   construction rather than by a rule somebody has to enforce. A
+     *   project-relative glob is only ever matched against paths under that
+     *   project's root, so there is no spelling of one that reaches a sibling.
+     * - A file at a project root describes that project, and every other file
+     *   that sits there is already read that way — a `tsconfig.json`'s own
+     *   `include` and `exclude` are project-relative, and so is the path in a
+     *   `package.json`. A field that looked identical to the workspace file's
+     *   and quietly meant something narrower is the trap this avoids.
+     * - The run's own `exclude` keeps its workspace-relative meaning untouched.
+     *   One field name read two ways in one file would be indefensible; one
+     *   read differently in two files, each way matching what its file is
+     *   about, is the distinction the two files already are.
+     *
+     * The run's filter is layered *under*, never replaced: a project cannot
+     * un-exclude what the run excluded, which keeps `exclude` and `excludeFrom`
+     * in the workspace file exactly as authoritative as they were.
+     *
+     * A run in which no project declared anything gets its own filter handed
+     * straight back, so the ownership lookup this otherwise does per file costs
+     * nothing at all in the workspaces — every one of them today — where no
+     * project excludes anything.
+     */
+    buildProjectFileFilter(args: BuildProjectFileFilterArguments): FileFilter;
+}
+
+/**
+ * Builds the call graph, its cycle condensation, and its depth measurement.
+ *
+ * Groups the four collaborators a full call-graph assembly needs behind one
+ * call, so a consumer that wants "the graph and everything derived from it"
+ * does not have to know the assembly order or re-wire them itself.
+ */
+export declare class GraphAssemblyService {
+    private readonly breadthService;
+    private readonly componentsService;
+    private readonly depthService;
+    private readonly edgesService;
+    private readonly graphService;
+    constructor(breadthService: BreadthService, componentsService: ComponentsService, depthService: GraphDepthService, edgesService: EdgesService, graphService: GraphService);
+    /** Builds the call graph and everything derived from it. */
+    assemble(args: AssembleGraphArguments): AssembledGraph;
+}
+
+/**
+ * Measures the longest call stack below every component.
+ *
+ * The traversal is iterative and post-order. Because it runs on the
+ * condensation, which is acyclic, a memo entry is final once written — there is
+ * no path along which a node could be revisited and get a different answer.
+ */
+export declare class GraphDepthService {
+    constructor();
+    /** Folds every successor's result into one component's own. */
+    private combine;
+    /** Picks the deepest successor of one component out of the memo. */
+    private foldSuccessors;
+    /** True when any member of a component holds an unfollowable call. */
+    private hasUnresolved;
+    /** Measures every component, deepest-first, in one iterative pass. */
+    measure(args: MeasureDepthArguments): DepthMeasurement;
+}
+
+/**
+ * Provides graph assembly, cycle condensation, and depth and breadth measurement.
+ */
+export declare class GraphModule {
+}
+
+/**
+ * Assembles the resolved edges into a graph indexed in both directions.
+ *
+ * Callers are indexed as well as callees because addressing one callable asks
+ * who calls it as often as it asks what it calls, and answering that from an
+ * index costs nothing once the edges exist.
+ */
+export declare class GraphService {
+    constructor();
+    /** Appends a value to the list stored under a key. */
+    private append;
+    /** Builds the two-way index over one run's edges. */
+    assemble(collection: EdgeCollection): CallGraph;
+}
+
+/** What resolving an interface member to implementations produced. */
+export declare interface ImplementationLookup {
+    /** Concrete member declarations, empty when none could be resolved. */
+    readonly declarations: readonly default_2.Declaration[];
+    /** True when the candidate set was larger than the cap. */
+    readonly exceededCandidateLimit: boolean;
+}
+
+/**
+ * Low link a node starts from when its entry is somehow missing.
+ *
+ * Never reached by the traversal — every node is opened before it is lifted —
+ * but `Map.get` reads as possibly undefined, and zero is the value an unopened
+ * node would have had anyway.
+ */
+export declare const INITIAL_LOW_LINK = 0;
+
+/**
+ * Methods a framework calls on a class it manages.
+ *
+ * Nothing in a repository calls these, so without naming them every one would
+ * be promoted as an orphan and reported with an entry-point kind that says
+ * nothing about why it runs.
+ */
+export declare const LIFECYCLE_METHOD_NAMES: Set<string>;
+
+/**
+ * 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.
+ */
+declare interface LogData {
+    [key: string]: unknown;
+    /** How many things the operation handled. */
+    count?: number;
+    /** Wall-clock milliseconds the operation took. */
+    durationMs?: number;
+    /** Completion between 0 and 100. */
+    percent?: number;
+    /** How many things the operation set out to handle. */
+    total?: number;
+}
+
+/**
+ * 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 });
+ * ```
+ */
+declare @Injectable({ scope: Scope.TRANSIENT })
+class LoggerService extends ConsoleLogger {
+    // 🏗 Dependency Injection
+
+    constructor() {
+        super();
+    }
+
+    // 🔐 Private Fields
+
+    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.
+     */
+    private static rootLogger: pino.Logger | undefined;
+
+    /** Whether lines go to standard error instead of standard output. */
+    private static writesToStandardError = false;
+
+    private child: pino.Logger = LoggerService.root;
+
+    // 🔑 Public Fields
+
+    // 🔏 Private Methods
+
+    /** Build the pino instance for production or local development output. */
+    private static createRootLogger(): pino.Logger {
+        const level = process.env["LOG_LEVEL"] ?? "info";
+
+        if (LoggerService.isProduction) {
+            return LoggerService.writesToStandardError
+            ? pino({ level }, pino.destination(STANDARD_ERROR_DESCRIPTOR))
+            : pino({ level });
+        }
+
+        return pino({
+            level,
+            transport: {
+                options: {
+                    colorize: true,
+                    destination: LoggerService.writesToStandardError
+                    ? STANDARD_ERROR_DESCRIPTOR
+                    : STANDARD_OUTPUT_DESCRIPTOR,
+                    // The emoji is a field, not part of the message, so the console can
+                    // show it while telemetry stores unadorned prose. `ignore` then keeps
+                    // it from being printed a second time in the trailing object.
+                    ignore: "pid,hostname,emoji",
+                    messageFormat: "{emoji} {msg}",
+                    singleLine: true,
+                },
+                target: "pino-pretty",
+            },
+        });
+    }
+
+    /**
+     * 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.
+     */
+    static logToStandardError(): void {
+        if (LoggerService.rootLogger !== undefined) {
+            process.emitWarning(
+            "LoggerService.logToStandardError() was called after the first log line, so log lines still go to standard output and anything piping that stream will read them as data. Call it as the first statement of the application's bootstrap.",
+            );
+            return;
+        }
+
+        LoggerService.writesToStandardError = true;
+    }
+
+    /**
+     * 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.
+     */
+    private assertConventionalMessage(args: {
+        context: string | undefined;
+        parsed: ParsedLogMessage;
+    }): void {
+        if (
+        LoggerService.isProduction ||
+        this.shouldSkipConventionalMessageValidation(args.context)
+        ) {
+            return;
+        }
+
+        const violation = this.getConventionalMessageViolation(args.parsed);
+
+        if (violation !== undefined) {
+            throw new Error(violation);
+        }
+    }
+
+    /** Assembles the object pino merges into the line. */
+    private buildBindings(args: {
+        context: string | undefined;
+        data: LogData | undefined;
+        parsed: ParsedLogMessage;
+    }): Record<string, unknown> {
+        this.assertConventionalMessage({
+            context: args.context,
+            parsed: args.parsed,
+        });
+
+        return {
+            ...args.data,
+            context: args.context,
+            // Telemetry gets prose; only the console-bound transport reads this.
+            ...(LoggerService.isProduction ? {} : { emoji: args.parsed.emoji }),
+        };
+    }
+
+    /** Returns a human-readable explanation when the message format is invalid. */
+    private getConventionalMessageViolation(
+    parsed: ParsedLogMessage,
+    ): string | undefined {
+        const emoji = parsed.emoji;
+        const text = parsed.text;
+
+        if (emoji === undefined) {
+            return `Log message must start with an emoji naming its subject, then a verb: "${text}"`;
+        }
+
+        const firstWord = FIRST_WORD_PATTERN.exec(text)?.[1];
+
+        if (firstWord === undefined || !this.isConventionalVerb(firstWord)) {
+            return `Log message must begin with a verb in present progressive or past tense, got "${firstWord ?? ""}": "${emoji} ${text}"`;
+        }
+
+        return undefined;
+    }
+
+    /**
+     * 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.
+     */
+    private isConventionalVerb(word: string): boolean {
+        const lowercased = word.toLowerCase();
+
+        return (
+        lowercased.endsWith("ing") ||
+        lowercased.endsWith("ed") ||
+        IRREGULAR_PAST_VERBS.has(lowercased)
+        );
+    }
+
+    /** Splits a leading emoji off a message, leaving prose behind. */
+    private parseMessage(message: unknown): ParsedLogMessage {
+        const text = String(message);
+        const match = LEADING_EMOJI_PATTERN.exec(text);
+        const emoji = match?.[1];
+
+        return emoji === undefined
+        ? { emoji: undefined, text }
+        : { emoji, text: text.slice(match?.[0].length) };
+    }
+
+    /** Whether a context is intentionally exempt from the validation rule. */
+    private shouldSkipConventionalMessageValidation(
+    context: string | undefined,
+    ): boolean {
+        return context !== undefined && UNVALIDATED_LOG_CONTEXTS.has(context);
+    }
+
+    // 🌎 Public Methods
+
+    /** The pino instance every logger's child is taken from. */
+    private static get root(): pino.Logger {
+        LoggerService.rootLogger ??= LoggerService.createRootLogger();
+
+        return LoggerService.rootLogger;
+    }
+
+    /** Normalizes unknown errors into a stable message and timestamped log line. */
+    buildErrorLogEntry(
+    context: string,
+    error: unknown,
+    ): { errorMessage: string; logLine: string } {
+        const errorMessage =
+        error instanceof Error ? error.stack || error.message : String(error);
+
+        return {
+            errorMessage,
+            logLine: `[${new Date().toISOString()}] ${context}: ${errorMessage}\n`,
+        };
+    }
+
+    /** Builds a timestamped output log file path and ensures the output directory exists. */
+    createTimestampedOutputLogFilePath(filePrefix: string): string {
+        const outputDirectory = path.join(process.cwd(), "output");
+        if (!existsSync(outputDirectory)) {
+            mkdirSync(outputDirectory, { recursive: true });
+        }
+
+        return path.join(
+        outputDirectory,
+        `${filePrefix}-${new Date().toISOString().replaceAll(/[:.]/g, "-")}.log`,
+        );
+    }
+
+    /** Logs a debug message at the `debug` level. */
+    override debug(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.debug(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+
+    /**
+     * 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.
+     */
+    override error(
+    message: unknown,
+    stackOrContext?: string,
+    contextOrData?: LogData | string,
+    ): void {
+        const parsed = this.parseMessage(message);
+        const data = typeof contextOrData === "object" ? contextOrData : undefined;
+        const context =
+        typeof contextOrData === "string" ? contextOrData : this.context;
+
+        this.child.error(
+            {
+            ...this.buildBindings({ context, data, parsed }),
+            stack: stackOrContext,
+        },
+        parsed.text,
+        );
+    }
+
+    /** Logs an informational message at the `info` level. */
+    info(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.info(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+
+    /**
+     * 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.
+     */
+    override log(message: unknown, context?: string, data?: LogData): void {
+        this.info(message, context, data);
+    }
+
+    /** Sets the context label included in every subsequent log line. */
+    override setContext(context: string): void {
+        super.setContext(context);
+        this.child = LoggerService.root.child({ context });
+    }
+
+    /** Logs a verbose message at the `trace` level. */
+    override verbose(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.trace(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+
+    /** Logs a warning message at the `warn` level. */
+    override warn(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.warn(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+}
+
+/**
+ * How many paths `AddressDepthService` enumerates in one direction before it
+ * stops.
+ *
+ * A single deepest path, which is all `PathsService` ever materializes, is
+ * bounded by construction. Enumerating every path is not: a callable reached
+ * from a dozen places whose callees fan out just as wide multiplies those
+ * branches together, so a cap is what keeps a widely-called utility from
+ * making the walk run away instead of returning.
+ */
+export declare const MAXIMUM_CALL_ADDRESS_STACKS = 200;
+
+/**
+ * Concrete implementations one interface member may resolve to before the call
+ * is recorded as unresolved instead.
+ *
+ * Not a limit on what a run judges — it is the threshold at which structural
+ * interface resolution stops guessing. Where an interface member has no
+ * nominal implementers, the type checker is asked which classes are assignable
+ * to it, and a member named `run`, `emit`, or `sync` structurally matches
+ * dozens of unrelated classes in a real workspace. Expanding all of them
+ * manufactures call stacks no execution ever takes, so past the cap the whole
+ * expansion is dropped rather than narrowed to a favorite.
+ *
+ * A constant rather than a configuration field. Removing it outright would
+ * follow every candidate and move every depth measurement upward
+ * unpredictably; making it configurable asks every project to hold an opinion
+ * about a noise control none of them varies. Eight is the number every
+ * configuration in this repository already used.
+ */
+export declare const MAXIMUM_IMPLEMENTATION_CANDIDATES = 8;
+
+/**
+ * Arguments for measuring breadth across the graph.
+ *
+ * No condensation is needed: unlike depth, a callable's breadth is well
+ * defined even when it sits in a cycle, so breadth reads `graph` directly.
+ */
+export declare interface MeasureBreadthArguments {
+    readonly callableIds: readonly CallableId[];
+    readonly graph: CallGraph;
+}
+
+/** Arguments for measuring depth across the graph. */
+export declare interface MeasureDepthArguments {
+    readonly condensed: CondensedGraph;
+    readonly graph: CallGraph;
+}
+
+/** An interface member nothing in the traced code implements. */
+export declare const NO_IMPLEMENTATION_CALL: ResolvedCallSite;
+
+/** A call whose callee has no symbol the checker will name. */
+export declare const NO_SYMBOL_CALL: ResolvedCallSite;
+
+/** A message split into the emoji the console shows and the prose telemetry stores. */
+declare interface ParsedLogMessage {
+    emoji: string | undefined;
+    text: string;
+}
+
+/**
+ * Rebuilds the single deepest call stack below an entry point.
+ *
+ * Only one path per entry point is ever materialized, by following the
+ * successor each component already recorded as its deepest. Enumerating every
+ * root-to-leaf path instead would be the same answer arrived at by walking a
+ * number of paths that grows with the product of the branching factors, and
+ * then discarding all but one of them.
+ */
+export declare class PathsService {
+    private readonly documentationService;
+    private readonly signaturesService;
+    constructor(documentationService: DocumentationService, signaturesService: SignaturesService);
+    /**
+     * Orders one component's members so the entered one comes first.
+     *
+     * Within a cycle there is no single true order, but starting at the member
+     * the caller actually reached makes the printed stack match how execution
+     * got there.
+     */
+    private orderMembers;
+    /** Walks the deepest chain below one callable and returns its frames. */
+    buildDeepestPath(args: {
+        callablesById: ReadonlyMap<CallableId, DiscoveredCallable>;
+        condensed: CondensedGraph;
+        entryPointId: CallableId;
+        measurement: DepthMeasurement;
+    }): StackFrame[];
+    /**
+     * Turns one callable into a frame a report can print.
+     *
+     * Public so any traversal over the same `DiscoveredCallable` map — not only
+     * this service's own deepest-path walk — can render a frame the same way,
+     * rather than reading documentation and a signature by a second route.
+     */
+    buildFrame(args: {
+        callable: DiscoveredCallable;
+        isCycle: boolean;
+    }): StackFrame;
+}
+
+/**
+ * Raised when a project's `tsconfig.json` cannot be read.
+ *
+ * Fatal to the whole run rather than skipped, and deliberately so. A host
+ * writes its report before it weighs its findings, so a run that stepped over
+ * the project would publish depths measured through a graph missing it and
+ * only then fail — and on a default branch that means committing wrong numbers
+ * that failing afterwards does not take back. Ending the run leaves every
+ * destination exactly as it found it.
+ *
+ * Raised for a directory a run was told to trace that holds no
+ * `tsconfig.json` at all, as well as for one whose configuration will not
+ * parse. Both are the same mistake seen from two sides — the run was pointed
+ * at something it cannot build a program from — and both used to be stepped
+ * over, which is how a run came to pass a gate for having traced nothing.
+ *
+ * A project that should not be read at all is a different question, answered
+ * by an exclusion: `WorkspaceService.discoverProjects` drops it before its
+ * configuration is ever opened.
+ */
+export declare class ProgramConfigurationError extends Error {
+    constructor(args: {
+        configurationPath: string;
+        messages: string[];
+    });
+}
+
+/**
+ * Provides TypeScript programs and type checkers, one per project.
+ */
+export declare class ProgramModule {
+}
+
+/**
+ * Turns each project's `tsconfig.json` into a program and a type checker.
+ *
+ * One program per project rather than one merged program, and that is a
+ * correctness decision rather than a performance one. The projects here
+ * disagree about `jsx`, `lib`, `types`, and `paths`; merging their options
+ * changes which globals exist and how modules resolve, so the checker starts
+ * answering with different symbols and the call graph silently gains wrong
+ * edges. Paying for twenty-odd programs buys the right answer.
+ */
+export declare class ProgramService {
+    private readonly compilerHostService;
+    private readonly logger;
+    private readonly workspaceService;
+    constructor(compilerHostService: CompilerHostService, logger: LoggerService, workspaceService: WorkspaceService);
+    /**
+     * Assigns each file to the program whose project root contains it.
+     *
+     * Projects overlap: a project that nests a second `tsconfig.json` beneath
+     * it can list the same file as its parent, when the parent's own `include`
+     * is broad enough to reach it too. Containment settles that overlap by the
+     * file's location on disk rather than by which program asked first, which
+     * is what keeps a reported depth the same however a run is scoped — a
+     * closure that starts programs in a different order reaches the same
+     * answer. A file none of `programs`' projects contains is left out of the
+     * map rather than guessed at; `readOwnedPath` in `CallablesService` then
+     * walks it through no program at all.
+     */
+    private assignOwnership;
+    /** Builds one project's program, checker, and owned-file set. */
+    private buildProgram;
+    /**
+     * Reads and fully resolves one project's compiler options.
+     *
+     * The configuration file name is passed as the fifth argument because that is
+     * what makes TypeScript follow the `extends` chain to the shared base config
+     * and report diagnostics against the right file.
+     */
+    private parseConfiguration;
+    /**
+     * Reports the workspace-relative paths one program pulled in.
+     *
+     * `getSourceFiles()` rather than the parsed configuration's `fileNames`,
+     * and the difference is the whole point: `fileNames` is what a project's own
+     * `tsconfig.json` listed, which by definition never mentions the packages it
+     * imports. `getSourceFiles()` is what the compiler actually had to read to
+     * type the project, so a workspace package reached through an import is in
+     * there — and in a pnpm workspace it is reached through a symlink, which is
+     * why every path goes through `toRealPath` before it is made relative.
+     *
+     * A path under `node_modules` is dropped rather than reported. It is a real
+     * dependency rather than workspace code, and the workspace root is itself a
+     * project whose root contains every such path — so reporting one would walk
+     * `lib.es5.d.ts` back to the root project and pull the entire workspace into
+     * every closure.
+     */
+    private readPulledInPaths;
+    /**
+     * Builds a program for every project in the starting projects' dependency
+     * closure, and decides which one owns each file.
+     *
+     * The apparent circularity — the closure names the projects to build, but
+     * naming them means asking what each one pulled in, which means building it
+     * — is only apparent. Finding project *roots* is a filesystem walk that
+     * builds nothing; finding what a project *reaches* is what needs a program.
+     * So the closure walk is driven from here, and the callback it asks for a
+     * project's files is what builds that project's program. The traversal asks
+     * exactly once per project it reaches, and the programs built along the way
+     * are kept rather than discarded — they are precisely the set the run goes
+     * on to trace with, so rebuilding them afterwards would build the whole
+     * closure twice.
+     *
+     * A project nothing reaches is never asked about and so never built, which
+     * is what keeps a run scoped to one package from compiling the workspace.
+     * Neither is a project reached only as a directory of shared settings, nor
+     * the workspace root itself — `WorkspaceService.isClosureDestination`
+     * refuses those and holds the reasoning. An unscoped run passes every
+     * project as a
+     * starting project, so its closure is every project, both rules are moot,
+     * and nothing about it changes.
+     *
+     * A project whose configuration cannot be parsed ends the run rather than
+     * being stepped over — see `ProgramConfigurationError` for why a partial
+     * graph is the worse outcome. A project that should not be read at all is
+     * kept out by an exclusion, which `WorkspaceService.discoverProjects`
+     * applies to both lists before this ever sees them, so an unreadable
+     * fixture an ignore file names is not in `workspaceProjects` and no closure
+     * can reach it.
+     */
+    buildPrograms(args: BuildProgramsArguments): ProgramSet;
+    /** Resolves a path through symlinks, which is how pnpm workspaces link. */
+    toRealPath(filePath: string): string;
+}
+
+/** The programs a run built, and the ownership decisions behind them. */
+export declare interface ProgramSet {
+    /** Absolute real path to the program that owns it. */
+    readonly ownerByFilePath: ReadonlyMap<string, ProjectProgram>;
+    readonly programs: readonly ProjectProgram[];
+}
+
+/**
+ * The file whose presence in a directory makes it a project.
+ *
+ * Named once rather than spelled at each site, so the file a whole-workspace
+ * scan looks for and the file an exclusion is judged against can never drift
+ * apart — a project excluded by a path that is not the one discovery reads
+ * would be excluded from nothing.
+ */
+export declare const PROJECT_CONFIGURATION_NAME = "tsconfig.json";
+
+/**
+ * One project's program, its checker, and the files it owns.
+ *
+ * A file's declarations are walked exactly once, in the program that owns it.
+ * Files pulled in as dependencies are still reachable through the checker, but
+ * walking them here as well would double every callable in the graph.
+ */
+export declare interface ProjectProgram {
+    readonly checker: default_2.TypeChecker;
+    /** Absolute real paths this program is responsible for walking. */
+    readonly ownedFilePaths: ReadonlySet<string>;
+    readonly program: default_2.Program;
+    readonly project: WorkspaceProject;
+}
+
+/** Arguments for reading the documentation comment above a callable. */
+export declare interface ReadDocumentationArguments {
+    readonly checker: default_2.TypeChecker;
+    readonly declaration: CallableDeclaration;
+}
+
+/** Arguments for reading what a callable takes and returns. */
+export declare interface ReadSignatureArguments {
+    readonly checker: default_2.TypeChecker;
+    readonly declaration: CallableDeclaration;
+}
+
+/** Arguments for resolving one callable address string. */
+export declare interface ResolveAddressArguments {
+    readonly address: string;
+    readonly callablesById: ReadonlyMap<CallableId, DiscoveredCallable>;
+    readonly workspaceRoot: string;
+}
+
+/** What resolving one call site produced. */
+export declare interface ResolvedCallSite {
+    readonly declarations: readonly default_2.Declaration[];
+    readonly reason: undefined | UnresolvedReason;
+    readonly resolution: "alias" | "direct" | "implementation" | "super";
+}
+
+/** Arguments for deciding which callables root a call stack. */
+export declare interface ResolveEntriesArguments {
+    readonly callablesById: ReadonlyMap<CallableId, DiscoveredCallable>;
+    /**
+     * The rules a project with no configuration of its own is judged by — the
+     * workspace configuration's.
+     */
+    readonly entryPoints: ResolvedCallidescopeEntryPoints;
+    /**
+     * The rules a project declared for itself, keyed by project name. A project
+     * absent here is judged by `entryPoints`.
+     */
+    readonly entryPointsByProject: ReadonlyMap<string, ResolvedCallidescopeEntryPoints>;
+    readonly graph: CallGraph;
+    readonly workspaceRoot: string;
+}
+
+/**
+ * Reports the workspace-relative paths one project's program pulled in.
+ *
+ * How that project came to have a program at all — built fresh for this
+ * traversal, reused from an earlier one — is entirely the implementation's
+ * concern. `walkImportedProjectClosure` reads only the paths that come back.
+ */
+declare type ResolveProjectFilesFunction = (project: WorkspaceProject) => readonly string[];
+
+/**
+ * How TypeScript renders the types in a signature.
+ *
+ * Aliases defined elsewhere are kept by name rather than expanded, because
+ * `MeasureArguments` tells a reader more in one word than the object it stands
+ * for does in forty.
+ */
+export declare const SIGNATURE_FORMAT_FLAGS = ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope;
+
+/**
+ * Provides the parameters and return type a report prints beside a frame.
+ */
+export declare class SignaturesModule {
+}
+
+/**
+ * Reads what a callable takes and what it gives back.
+ *
+ * Resolved through the type checker rather than read off the syntax, which is
+ * what makes it useful on the shapes the graph actually points at. A callback
+ * passed to `map` declares no types at all and gets them from the parameter it
+ * was passed to; a destructured parameter has no name in the source; an
+ * inferred return type is written down nowhere.
+ */
+export declare class SignaturesService {
+    constructor();
+    /** Describes one parameter, including how it may be left out. */
+    private readParameter;
+    /** Reads the parameters and return type of a callable. */
+    read(args: ReadSignatureArguments): CallableSignature | undefined;
+}
+
+/**
+ * Resolves one call expression to the declarations it can reach.
+ *
+ * The fast path is asking the checker for the symbol at the member name, which
+ * already answers the case this tool exists for: a call on a constructor-
+ * injected property. The parameter property carries the service's type, the
+ * checker follows it, and no dependency-injection machinery is needed to trace
+ * a NestJS call graph. Everything below that is the long tail.
+ */
+export declare class SymbolResolutionService {
+    private readonly classHierarchyService;
+    private readonly externalService;
+    constructor(classHierarchyService: ClassesService, externalService: ExternalService);
+    /** True when a declaration is a signature rather than an implementation. */
+    private isAbstractMember;
+    /**
+     * True when a declaration is a function form that can carry a body.
+     *
+     * Spelled out rather than using `ts.isFunctionLike`, which also admits bare
+     * call and construct signatures — those have no body to push a frame for, and
+     * narrowing to them makes `.body` unreadable.
+     */
+    private isBodyCarrying;
+    /** Keeps the declarations that actually have a body to execute. */
+    private readBodied;
+    /** Reads the name node a call's callee is identified by. */
+    private readCalleeName;
+    /**
+     * Names the type a member is declared on, and where that name is written.
+     *
+     * The name node comes back alongside the text because the checker needs a
+     * location to resolve the owning symbol from, and fetching it separately
+     * would mean checking twice that the owner exists at all.
+     */
+    private readOwner;
+    /** Names how a resolved call reached its target. */
+    private readResolution;
+    /**
+     * Resolves an already-identified callee symbol to its declarations.
+     *
+     * Split from `resolve` so that identifying the callee and following it stay
+     * separately readable — and separately testable, since the shapes that fail
+     * to identify a callee are nothing like the shapes that fail to follow one.
+     */
+    private resolveSymbol;
+    /** Expands an interface or abstract member to its implementations. */
+    private resolveThroughHierarchy;
+    /** Unwraps an import alias to the symbol it actually names. */
+    private unwrapAlias;
+    /** Resolves a call expression to every declaration it can reach. */
+    resolve(args: {
+        checker: default_2.TypeChecker;
+        expression: default_2.CallExpression;
+    }): ResolvedCallSite;
+    /** Resolves a `new` expression to the constructor it runs, if any. */
+    resolveConstructor(args: {
+        checker: default_2.TypeChecker;
+        expression: default_2.NewExpression;
+    }): ResolvedCallSite;
+}
+
+/**
+ * The bookkeeping Tarjan's algorithm carries.
+ *
+ * Threaded as one object so the traversal can be split into small steps
+ * without any of them taking a long parameter list.
+ */
+export declare interface TarjanState {
+    readonly componentIdByCallable: Map<CallableId, number>;
+    readonly frames: TraversalFrame[];
+    readonly lowLink: Map<CallableId, number>;
+    readonly memberIdsByComponent: CallableId[][];
+    readonly onStack: Set<CallableId>;
+    readonly order: Map<CallableId, number>;
+    readonly pending: CallableId[];
+    sequence: number;
+}
+
+/**
+ * Directory holding a project's test scaffolding.
+ *
+ * Its files are not named like tests — `mocks.ts`, `setup.ts` — but they exist
+ * only for tests, and a report that counted them would describe a package's
+ * fixtures as its control flow.
+ */
+export declare const TEST_DIRECTORY_SEGMENT = "testing";
+
+/** Matches a test file, whatever tier it declares. */
+export declare const TEST_FILE_PATTERN: RegExp;
+
+/** An interface member too many classes implement to be worth following. */
+export declare const TOO_MANY_IMPLEMENTATIONS_CALL: ResolvedCallSite;
+
+/** One frame of the explicit stack the iterative traversal walks. */
+export declare interface TraversalFrame {
+    readonly callableId: CallableId;
+    /** How many successors of this node have been visited so far. */
+    successorIndex: number;
+}
+
+/**
+ * A resolution that did not name exactly one callable.
+ *
+ * Derived from `CallableAddressResolution` rather than restated, so anything
+ * acting on a failure keeps covering every way one can happen.
+ */
+export declare type UnresolvedCallableAddress = Exclude<CallableAddressResolution, {
+    readonly kind: "resolved";
+}>;
+
+/** A declared entry-point address that did not name exactly one callable. */
+export declare interface UnresolvedEntryPointAddress {
+    readonly address: string;
+    /**
+     * The project whose configuration declared it. Absent when the workspace
+     * configuration did, which has no project to name.
+     */
+    readonly projectName: string | undefined;
+    /** Why it named no single callable, and what it could have meant instead. */
+    readonly resolution: UnresolvedCallableAddress;
+}
+
+/** Arguments for walking the projects a set of starting roots' imports reach. */
+declare interface WalkImportedProjectClosureArguments {
+    /** Reports the workspace-relative paths one project's program pulled in. */
+    readonly resolveProjectFiles: ResolveProjectFilesFunction;
+    /** Project roots the traversal begins from. Always present in the result. */
+    readonly startingProjects: readonly WorkspaceProject[];
+    /**
+     * Every project known to the workspace, not only the ones reached so far —
+     * this is what lets a pulled-in file resolve to a project the traversal has
+     * not visited yet.
+     */
+    readonly workspaceProjects: readonly WorkspaceProject[];
+}
+
+/**
+ * Provides project discovery, module identity, and file exclusion.
+ */
+export declare class WorkspaceModule {
+}
+
+/** One project discovered from a directory holding its own `tsconfig.json`. */
+export declare interface WorkspaceProject {
+    /** Absolute path to the project's `tsconfig.json`. */
+    readonly configurationPath: string;
+    /**
+     * Whether the project's root holds a `package.json`, read once when the
+     * project is discovered.
+     *
+     * A fact about the directory rather than a policy about it — what it is
+     * used for is `WorkspaceService.isClosureDestination`, and
+     * `PACKAGE_MANIFEST_NAME` holds why. Carried on the project so the closure
+     * traversal is a walk over data rather than over the filesystem: it is
+     * consulted once per pulled-in *path*, and a project reached late would
+     * otherwise be stat-ed thousands of times before it was reached at all.
+     */
+    readonly hasPackageManifest: boolean;
+    /** Same as `root`: the project's own directory is its identity. */
+    readonly name: string;
+    /** Workspace-relative project root, POSIX separators. */
+    readonly root: string;
+}
+
+/** Finds the projects a run traces, and says which one owns a file. */
+export declare class WorkspaceService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /** Walks the whole workspace for every directory holding a `tsconfig.json`. */
+    private findAllProjectDirectories;
+    /**
+     * Walks a directory recursively, collecting every subdirectory that holds
+     * its own `tsconfig.json`.
+     *
+     * Descends into a `tsconfig.json`-holding directory too rather than
+     * stopping there: a project nesting a second program under it — a
+     * `testing/tsconfig.json`, a generated subpackage — is not a reason to miss
+     * everything below it, and the directories this skips already keep the walk
+     * from wandering into a dependency or a build artifact.
+     */
+    private findProjectDirectories;
+    /**
+     * True when a project may be pulled into another project's closure.
+     *
+     * Two roots are refused. One holding no `package.json` is a directory of
+     * shared settings rather than a package — `PACKAGE_MANIFEST_NAME` holds that
+     * reasoning, and what it costs. The workspace root is refused whatever it
+     * holds: a project whose root contains every other project cannot be a
+     * meaningful dependency of any of them, and admitting it is the same
+     * explosion reached from a root-level file — a `codometer.config.ts`, a
+     * `scripts/` directory — rather than from a shared settings one.
+     */
+    private isClosureDestination;
+    /**
+     * True when a project's root is a path-segment prefix of a file's path.
+     *
+     * A plain `startsWith` on the raw strings would let `packages/callidescope`
+     * falsely contain `packages/ic-suite/callidescope/callidescope-graph/...` — the empty root is the
+     * one exception, since the workspace root itself contains every file.
+     */
+    private isContainedByRoot;
+    /**
+     * True for a directory a whole-workspace scan should never descend into.
+     *
+     * A name holding `{{`/`}}` is a scaffolding template's own placeholder
+     * directory, never a real one — its `tsconfig.json`, if it has one, is
+     * written for a generator to fill in later and cannot build a program on
+     * its own.
+     */
+    private isExcludedFromScan;
+    /** True when an exclusion already names the project's own `tsconfig.json`. */
+    private isExcludedProject;
+    /**
+     * Resolves the project directories a run will trace.
+     *
+     * Each of `args.directories` is trusted as a project root outright rather
+     * than searched for a `tsconfig.json` beneath it: naming a directory is
+     * the caller saying exactly what it means to trace. Passing none is what
+     * asks for the whole workspace instead, found by walking it for every
+     * `tsconfig.json` there is — the only case that needs a search at all.
+     *
+     * A project an exclusion names is dropped here, before its `tsconfig.json`
+     * is ever opened. Excluding later — once the files a program yielded are
+     * being filtered — is too late to help: reading the configuration is itself
+     * what fails on a `tsconfig.json` written to be unreadable, so an exclusion
+     * that only reaches the files cannot keep the run away from it.
+     *
+     * A named directory holding no `tsconfig.json` ends the run through
+     * `ProgramConfigurationError`, the same way one holding an unreadable
+     * `tsconfig.json` does. Naming a directory is the caller saying it should be
+     * traced, so a run that quietly traced one fewer project than it was asked
+     * to would report depths for a workspace nobody described — and a typo in a
+     * `--directories` list would pass every gate for having looked at less. The
+     * whole-workspace walk cannot reach this: it only ever yields directories a
+     * `tsconfig.json` was found in.
+     */
+    discoverProjects(args: DiscoverProjectsArguments): WorkspaceProject[];
+    /** True when a path names a test file, or scaffolding written for tests. */
+    isTestFile(filePath: string): boolean;
+    /**
+     * Names the traced project whose root most narrowly contains a file.
+     *
+     * "Contains" means the deepest of `args.projects` whose root is a
+     * path-segment prefix of `args.workspaceRelativePath` — never a shallower
+     * ancestor, and never a sibling that merely shares a string prefix. This is
+     * what settles a project that nests a second `tsconfig.json` beneath it (a
+     * `testing/tsconfig.json`, a generated subpackage): the nested root is more
+     * specific than the parent's, so a file under it belongs to the nested
+     * project even when the parent's own configuration also lists that file.
+     *
+     * Returns `undefined` when none of `args.projects` contains the file at
+     * all — impossible for a whole-workspace run, since the workspace root
+     * itself is always a traced project, but reachable when a run is scoped to
+     * a handful of directories that do not include it.
+     */
+    resolveOwningProject(args: {
+        projects: readonly WorkspaceProject[];
+        workspaceRelativePath: string;
+    }): undefined | WorkspaceProject;
+    /** Rewrites an absolute path as workspace-relative with POSIX separators. */
+    toWorkspaceRelative(args: {
+        absolutePath: string;
+        workspaceRoot: string;
+    }): string;
+    /**
+     * Walks the projects a set of starting roots' imports transitively reach —
+     * a starting project's dependency closure — asking
+     * `args.resolveProjectFiles` about each one exactly once.
+     *
+     * Named for the imports it follows rather than for dependency in general,
+     * because `ProjectsService.resolveDependencyClosure` in `@callidescope/nx`
+     * resolves a closure too, from the edges the Nx graph declares. Both are
+     * real closures over different edges, and the two sets are not the same.
+     *
+     * `args.resolveProjectFiles` reports the workspace-relative paths one
+     * project's program pulled in; this method owns only the fixed-point walk
+     * over those reports, never how a program comes to exist. Each reported
+     * path is walked back to its owning project through `resolveOwningProject`
+     * against `args.workspaceProjects`, so a path `node_modules` holds, or one
+     * no traced project's root contains, resolves to `undefined` and never
+     * manufactures a project that is not there. A project already reached is
+     * never asked again, which is what makes a cycle between two projects
+     * terminate instead of looping forever. A resolved owner that is not a
+     * closure *destination* is dropped as though nothing owned the path —
+     * `isClosureDestination` says which projects those are, and why.
+     *
+     * Every starting project is asked about, even one whose program pulls in
+     * nothing outside itself and even one no closure could have reached, and a
+     * project's dependents never are — nothing here walks from a file to
+     * whoever imports it, only from a project to what its own program reaches.
+     *
+     * The callback's invocations are the whole result, which is why nothing is
+     * returned: the closure is exactly the set of projects the callback was
+     * asked about, and handing that set back as well would be a second
+     * representation of it, free to drift from whatever the caller collected
+     * while it answered. Ordering belongs to the caller for the same reason —
+     * `ProgramService.buildPrograms` sorts the programs it collected, so the
+     * order a report reads in is decided once, over the things a report is
+     * really made of.
+     */
+    walkImportedProjectClosure(args: WalkImportedProjectClosureArguments): void;
+}
+
+export { }