@callidescope/nx 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,698 @@
+import { AddressDepthService } from '@callidescope/graph';
+import { AddressLookupService } from '@callidescope/cli';
+import { AddressReportService } from '@callidescope/output';
+import { BreadthService } from '@callidescope/graph';
+import { CallidescopeOutputFormat } from '@callidescope/configuration';
+import { CallidescopeService } from '@callidescope/cli';
+import { ConfigurationService } from '@callidescope/configuration';
+import { CreateNodes } from '@nx/devkit';
+import { FileFilterService } from '@callidescope/graph';
+import { MarkdownReportService } from '@callidescope/output';
+import { ProjectGraph } from '@nx/devkit';
+import { ProjectReportsService } from '@callidescope/output';
+import { ResolvedCallidescopeConfiguration } from '@callidescope/configuration';
+
+/** Provides the `depth` and `breadth` lookups the executors run. */
+export declare class AddressModule {
+}
+
+/**
+ * Answers `depth` and `breadth` about the callables it is named, inside a
+ * resolved selection of Nx projects.
+ *
+ * The lookup itself is callidescope's — this only decides what it is asked
+ * about. What the plugin adds is the scope: the CLI resolves an address
+ * against the whole workspace, while here it is resolved against one project
+ * and its Nx dependencies, which is both faster and the set the address
+ * actually belongs to.
+ */
+export declare class AddressService {
+    private readonly addressLookupService;
+    private readonly addressReportService;
+    private readonly addressDepthService;
+    private readonly breadthService;
+    constructor(addressLookupService: AddressLookupService, addressReportService: AddressReportService, addressDepthService: AddressDepthService, breadthService: BreadthService);
+    /**
+     * Matches one address against an already-traced selection, or explains why
+     * it could not be.
+     *
+     * The explanation is returned rather than logged: an executor's product is
+     * what it writes to stdout, and a reader looking at a failed task needs the
+     * reason in the same place the report would have been.
+     */
+    private identify;
+    /**
+     * Traces the selection, then matches every address against it.
+     *
+     * All or nothing, the way the command line is: a task that printed the
+     * addresses it understood and skipped the rest would report a partial
+     * answer under a `success` nobody asked it to qualify.
+     */
+    private locate;
+    /** Prints each callable's direct callers and callees, side by side. */
+    runBreadth(args: LookupArguments): Promise<LookupResult>;
+    /** Prints every call stack above and below each callable. */
+    runDepth(args: LookupArguments): Promise<LookupResult>;
+}
+
+/** Name this plugin is registered under in a workspace's `nx.json`. */
+export declare const CALLIDESCOPE_NX_PLUGIN_NAME = "@callidescope/nx";
+
+declare const callidescopePlugin: {
+    createNodes: CreateNodes;
+    name: string;
+};
+export default callidescopePlugin;
+
+/** Options accepted from this plugin's `nx.json` registration. */
+export declare interface CallidescopePluginOptions {
+    /** Name of the inferred per-project breadth-lookup target. */
+    readonly breadthTargetName: string;
+    /** Where the callidescope configuration lives, workspace-root relative. */
+    readonly configurationPath: string;
+    /** Name of the inferred per-project depth-lookup target. */
+    readonly depthTargetName: string;
+    /** Name of the inferred per-project gate target. */
+    readonly gateTargetName: string;
+    /** Name of the inferred per-project trace target. */
+    readonly traceTargetName: string;
+}
+
+/** Name of the inferred per-project breadth-lookup target. */
+export declare const DEFAULT_BREADTH_TARGET_NAME = "breadth";
+
+/** Name of the inferred per-project depth-lookup target. */
+export declare const DEFAULT_DEPTH_TARGET_NAME = "depth";
+
+/**
+ * Name of the inferred per-project gate target.
+ *
+ * Named after what it decides rather than after what it measures. `trace`,
+ * `depth`, and `breadth` all print something a reader asked for; this one is
+ * the target here a pipeline is meant to read an exit code from, so it says
+ * `gate`.
+ */
+export declare const DEFAULT_GATE_TARGET_NAME = "gate";
+
+/**
+ * Names of the inferred per-project targets, when the registration names none.
+ *
+ * Short and unprefixed, so a run reads `nx run callidescope-nx:trace` rather
+ * than repeating the tool's name on both sides of the colon. Every one of them
+ * is overridable from the `nx.json` registration, which is the escape hatch
+ * for a workspace where a name this general would collide.
+ */
+export declare const DEFAULT_TRACE_TARGET_NAME = "trace";
+
+/** A target this plugin infers onto a project. */
+declare interface InferredTarget {
+    readonly cache: boolean;
+    readonly executor: string;
+    /** Files whose change must invalidate the cached result. */
+    readonly inputs?: string[];
+    readonly options: Record<string, unknown>;
+}
+
+/** One project's inferred targets, keyed by target name. */
+declare type InferredTargets = Record<string, InferredTarget>;
+
+/** Arguments for inferring targets across every project in a workspace. */
+declare interface InferTargetsArguments {
+    readonly options: unknown;
+    /** Every `project.json` Nx matched, workspace-root relative. */
+    readonly projectConfigurationFiles: readonly string[];
+    readonly workspaceRoot: string;
+}
+
+/** A loaded configuration, beside the path the loader settled on. */
+declare interface LoadedRunConfiguration {
+    readonly configuration: ResolvedCallidescopeConfiguration;
+    /**
+     * Where the configuration was read from, or nothing when none was found.
+     *
+     * The path the loader settled on rather than the one it was handed, since a
+     * search may have answered — and a run resolves a project's own
+     * configuration relative to it.
+     */
+    readonly path: string | undefined;
+}
+
+/** Arguments for loading the configuration one run is judged by. */
+declare interface LoadRunConfigurationArguments {
+    /** Resolved from this plugin's `nx.json` registration when omitted. */
+    readonly configurationPath?: string | undefined;
+    readonly workspaceRoot: string;
+}
+
+/** Arguments for looking callables up inside a resolved selection. */
+export declare interface LookupArguments {
+    /** Each `<file>#<qualified-name>`, the form every callidescope stack prints. */
+    readonly addresses: readonly string[];
+    readonly configurationPath?: string | undefined;
+    /** Workspace-relative directories the lookup resolves the address against. */
+    readonly directories: readonly string[];
+    readonly format?: CallidescopeOutputFormat | undefined;
+}
+
+/** What one lookup produced. */
+export declare interface LookupResult {
+    /** False when any address named nothing the run traced. */
+    readonly ok: boolean;
+    /**
+     * The rendered report, or the reason every address that failed could not be
+     * resolved.
+     */
+    readonly report: string;
+}
+
+/**
+ * Root module of the plugin's application context.
+ *
+ * Built once per process and cached — the Nx daemon is long-lived, so paying
+ * for a NestJS context on every inference or executor invocation would make
+ * this plugin the slowest thing in the graph.
+ */
+export declare class MainModule {
+}
+
+/**
+ * One Nx project, reduced to what a directory resolution needs of it.
+ *
+ * `codependix-nx-projects` declares a near-identical shape and reads it out of the
+ * graph the same way. They are deliberately not shared: the two packages sit
+ * in different toolchains, and `configuration/eslint.config.ts` lets this one
+ * depend on nothing but `logger` precisely so `@nx/devkit` cannot spread. A
+ * package extracted to hold both would have to be depended on by both, which
+ * is the coupling that rule exists to prevent.
+ */
+export declare interface NxProject {
+    readonly name: string;
+    /** Workspace-relative root, exactly as the Nx project graph states it. */
+    readonly root: string;
+    /** The tags `project.json` declares. Empty for a project declaring none. */
+    readonly tags: string[];
+}
+
+/** Provides the reader for this plugin's `nx.json` registration. */
+export declare class OptionsModule {
+}
+
+/**
+ * Narrows the untyped options object Nx hands a plugin.
+ *
+ * Nx passes whatever the consumer wrote in `nx.json` with no validation, so
+ * every field is checked before use rather than cast. A bad value falls back
+ * to its default: a typo in a target name should not stop the project graph
+ * from being built.
+ */
+export declare class OptionsService {
+    constructor();
+    /** Narrows an untrusted value to an array without widening it to `any`. */
+    private isUnknownArray;
+    /** Reads one `nx.json` plugin entry, if it is this plugin's registration. */
+    private readEntryConfigurationPath;
+    /** Reads this plugin's `configurationPath` out of an `nx.json`, if it names one. */
+    private readRegisteredConfigurationPath;
+    /** Reads a string field from an untrusted record, or `undefined`. */
+    private readString;
+    /**
+     * Narrows an untrusted output format to one callidescope renders.
+     *
+     * A target written by hand in a `project.json` bypasses the executor's
+     * `schema.json` enum, so an unrecognized value falls back to whatever the
+     * configuration chose rather than reaching the renderer.
+     */
+    readFormat(value: unknown): CallidescopeOutputFormat | undefined;
+    /**
+     * Reads a list of strings out of an executor's options.
+     *
+     * Nx validates an option against its `schema.json` before the executor sees
+     * it, but a target written by hand in a `project.json` reaches here
+     * unchecked, so a non-array or a list holding non-strings is narrowed rather
+     * than trusted. Entries are trimmed and the blanks dropped, so a trailing
+     * comma in `--projects a,b,` names two projects rather than three.
+     */
+    readStringList(value: unknown): string[];
+    /**
+     * Resolves the configuration path a workspace means, without assuming one.
+     *
+     * Nx passes plugin options to `createNodes` and to executors, but not to
+     * anything run outside Nx, so a caller that has a filesystem resolves the
+     * path itself rather than assuming a workspace keeps its configuration at
+     * the root. `exists` is supplied by the caller because the callers do not
+     * agree on what a filesystem is.
+     */
+    resolveConfigurationPath(args: {
+        exists: (candidatePath: string) => boolean;
+        nxConfiguration: unknown;
+    }): string;
+    /** Resolves the effective plugin options from an untrusted value. */
+    resolvePluginOptions(options: unknown): CallidescopePluginOptions;
+}
+
+/** Provides target inference and the trace the executor runs. */
+export declare class PluginModule {
+}
+
+/**
+ * Everything this plugin does, behind one injectable.
+ *
+ * Nx calls plugins from module-level functions with no injection of their own,
+ * so the bare entry points in `index.ts` and the executor build nothing
+ * themselves — they resolve this service and hand it the arguments.
+ */
+export declare class PluginService {
+    private readonly callidescopeService;
+    private readonly configurationService;
+    private readonly fileFilterService;
+    private readonly markdownReportService;
+    private readonly optionsService;
+    private readonly projectReportsService;
+    private readonly projectsService;
+    private readonly runConfigurationService;
+    constructor(callidescopeService: CallidescopeService, configurationService: ConfigurationService, fileFilterService: FileFilterService, markdownReportService: MarkdownReportService, optionsService: OptionsService, projectReportsService: ProjectReportsService, projectsService: ProjectsService, runConfigurationService: RunConfigurationService);
+    /**
+     * Builds the predicate deciding which projects the workspace configuration
+     * keeps out of every trace.
+     *
+     * The run's own filter, built from the same two fields
+     * `WorkspaceService.discoverProjects` builds it from and asked the same
+     * question it asks — is this project's `tsconfig.json` excluded — so
+     * inference and discovery can never disagree about which projects a run
+     * covers.
+     *
+     * A configuration that cannot be loaded excludes nothing. This runs while Nx
+     * is building the project graph, where a thrown error stops every command in
+     * the workspace rather than one task; the executor loads the same file again
+     * and refuses there, where a refusal is about the run that asked for it.
+     */
+    private buildExclusionFilter;
+    /**
+     * Builds one project's targets, gate included unless it is excluded.
+     *
+     * An excluded project gets the three that print something and not the one
+     * that decides an exit code. Its own code is never traced — discovery drops
+     * it before its `tsconfig.json` is opened — so a gate there would own no
+     * finding at all and report green for a project it never read.
+     * `packages/ic-suite/callidescope/callidescope-examples` is the case: its fixtures exist to breach
+     * the limits, which is why `.callidescopeignore` names it.
+     *
+     * That sentence is what `runTrace`'s exemption from the unread rule keeps
+     * true: such a project reads nothing of its own by definition, so a trace
+     * failing on that would hand it a permanently red target.
+     */
+    private buildInferredTargets;
+    /**
+     * The block a verdict owes the reader when its findings cannot explain it.
+     *
+     * Both targets print this and only one fails on it — see `judge` — because
+     * an unread project is a fact about the run either way. The unread projects
+     * come first when both apply: they name what went missing, where the
+     * whole-run reason can only say that something did.
+     */
+    private explainVerdict;
+    /** Whether a project's directory holds a TypeScript program to trace. */
+    private holdsProgram;
+    /**
+     * Whether the workspace configuration excludes this project outright.
+     *
+     * The project's own `tsconfig.json` is the path asked about, because that is
+     * the path `WorkspaceService.discoverProjects` asks about — a project is
+     * excluded when the file that makes it a project is.
+     *
+     * Joined with `path.posix` rather than `path.join`, unlike `holdsProgram`
+     * beside it: a filter matches the workspace-relative POSIX paths git and the
+     * exclusion globs are written in, where `holdsProgram` hands `existsSync` a
+     * native absolute path.
+     */
+    private isExcludedProject;
+    /**
+     * Decides whether a traced result passes, for every target that reads one.
+     *
+     * One predicate rather than the same expression beside each caller, so a
+     * rule added here cannot reach one verdict and miss the other.
+     *
+     * **Only the projects the run was scoped to are judged.** A trace reaches
+     * into the dependencies of what it was pointed at, so judging the whole
+     * run's findings would fail `alpha`'s task for a breach in `beta`. The same
+     * line the publishing side already draws, one step further along:
+     * measurement reaches into dependencies, publishing does not, and judging
+     * does not either. A dependency's breach is its own gate's business, and
+     * `nx affected` selects it too when it changes, so nothing escapes a verdict.
+     *
+     * **A judged project none of whose own files were read is named back**, the
+     * case `callidescope`'s own `reportEmptyTrace` fails for the same reason: a
+     * gate that passes because it never looked reports the project as clean.
+     * Asked of each judged project rather than of the whole run, because
+     * narrowing made those two different questions — a project with dependencies
+     * has a non-empty run whatever became of its own sources, so its own
+     * `exclude` over-matching would otherwise leave it owning no finding and
+     * passing green. The whole run is asked too, for a run judging no project at
+     * all.
+     *
+     * It is the one rule whose **consequence** is the caller's rather than this
+     * predicate's, and so the one thing `unreadProjectNames` is returned beside
+     * `ok` for: a `gate` fails on it and a `trace` prints it and passes. Every
+     * project the workspace configuration excludes reads nothing of its own and
+     * is denied a gate while keeping its trace, so failing the trace too would
+     * make that project's target permanently red for being configured exactly as
+     * it was asked to be. Finding the projects stays here either way, so the
+     * rule cannot be applied to one verdict and forgotten by the other.
+     *
+     * **Depth is judged always, breadth wherever a limit exists** — not two
+     * modes to be selected between. `maximumDepth` has a default and
+     * `maximumBreadth` has none at any level, so a project declaring no breadth
+     * limit can produce no breadth finding to fail on. Reading the findings
+     * rather than naming a check is what keeps that true without a decision.
+     */
+    private judge;
+    /**
+     * States what a selection asked for that the workspace does not have.
+     *
+     * Both kinds of mistake are named at once, each beside the vocabulary it
+     * was drawn from, so a command line with two typos in it is two typos to
+     * fix rather than two runs.
+     */
+    describeRefusedScope(scope: ResolvedTraceScope): string;
+    /**
+     * Infers this plugin's targets onto every project holding a `tsconfig.json`.
+     *
+     * A project with no program of its own is skipped rather than given a target
+     * that would trace nothing — `callidescope` warns and moves on, so an
+     * inferred target there would be a permanently empty report. The
+     * workspace-root project is skipped for the opposite reason: it contains
+     * every other project, so its target would trace the whole workspace under
+     * one uncacheable task.
+     *
+     * Asynchronous because the gate is only inferred onto a project the
+     * workspace configuration does not exclude, and only that file can say which
+     * projects those are — see `buildExclusionFilter`, which is read once here
+     * rather than once per project for the same reason the plugin options are.
+     */
+    inferTargets(args: InferTargetsArguments): Promise<Map<string, InferredTargets>>;
+    /**
+     * Resolves an executor's `projects`/`tags` selection into directories.
+     *
+     * The selection is widened along the Nx dependency graph unless asked not to
+     * be — see `ProjectsService.resolveDependencyClosure` for why a trace that
+     * stops at a project's own boundary measures the wrong thing. Two sets of
+     * directories come back for that reason: what the widened selection reads,
+     * and what the selection itself is answerable for.
+     */
+    resolveTraceScope(args: ResolveTraceScopeArguments): Promise<ResolvedTraceScope>;
+    /**
+     * Traces the resolved directories and judges what it found against the
+     * limits every project in scope declared.
+     *
+     * The verdict is `judge`'s, which is where the rules are written; this
+     * chooses what to print for it — the findings it judged, or, for a run that
+     * read nothing and so has none to show, the reason it failed instead.
+     *
+     * The one thing it adds to that verdict is the exit code for an unread
+     * judged project, which is the gate's alone — see `judge`.
+     */
+    runGate(args: RunGateArguments): Promise<RunTraceResult>;
+    /**
+     * Traces the resolved directories and renders the report.
+     *
+     * This is the whole of the "logic on top of core callidescope": the
+     * selection above is Nx's to resolve, and everything below this line is
+     * callidescope's own, reached through the same services the `callidescope`
+     * command uses rather than through a subprocess.
+     *
+     * Judged by the same predicate the gate is, so the two targets cannot come
+     * to disagree about what a passing run is. A run that read nothing keeps its
+     * report and gains the reason underneath it: a summary table of zeroes is
+     * what happened, not why it failed.
+     *
+     * The one rule the two act on differently: a judged project none of whose
+     * own files were read is **printed here and not failed on**, where a gate
+     * fails — see `judge` for why that is the one exemption.
+     */
+    runTrace(args: RunTraceArguments): Promise<RunTraceResult>;
+}
+
+/** Provides the Nx project-name to directory resolution. */
+export declare class ProjectsModule {
+}
+
+/**
+ * Resolves Nx project names to the directories a callidescope run traces.
+ *
+ * This is the whole of callidescope's Nx awareness. `callidescope-cli` and
+ * `callidescope-graph` know nothing about Nx and never read a project graph;
+ * they take directories. What an Nx workspace has that plain paths do not is
+ * a stable name for each of those directories, and turning one into the other
+ * is the only thing this package is for.
+ *
+ * The project graph is passed in rather than read here, so every resolution
+ * rule below is testable without a workspace to build a graph from —
+ * `readProjectGraph` is the one method that touches Nx at run time.
+ */
+export declare class ProjectsService {
+    constructor();
+    /** Every tag any project carries, sorted and deduplicated. */
+    private readTags;
+    /**
+     * Collects the names of every project carrying any of the given tags, and
+     * the tags nothing carries.
+     *
+     * Any of them rather than all of them. Nx tags come in families whose
+     * members are mutually exclusive on one project — nothing is both
+     * `type:application` and `type:package` — so requiring every tag would make
+     * the common selection resolve to nothing. Any is also the reading that
+     * composes: each tag widens the set, the way naming another project does.
+     */
+    private resolveTaggedNames;
+    /** Reads the workspace's Nx project graph. */
+    readProjectGraph(): Promise<ProjectGraph>;
+    /**
+     * Lists every project the graph knows, sorted by name.
+     *
+     * A project rooted at the workspace root is kept rather than filtered out.
+     * It resolves to `.`, which `--directories` accepts, and naming it is a
+     * caller saying they mean the root program — a different thing from
+     * omitting `--directories`, which walks the workspace for every
+     * `tsconfig.json` there is.
+     */
+    readProjects(graph: ProjectGraph): NxProject[];
+    /**
+     * Widens a set of project names to include everything they depend on.
+     *
+     * Dependencies, never dependents. A call stack runs downward — a command
+     * calls into the service it was injected with, which lives in a package it
+     * depends on — and those packages are what a trace of one project has to
+     * carry. Its dependents call *into* it and add no frames below it.
+     *
+     * This widens what the run is *scoped to*, not how far a stack runs:
+     * `WorkspaceService.walkImportedProjectClosure` already builds the program
+     * of every project the named directories transitively import. What the Nx
+     * graph adds is edges the compiler never read — an implicit dependency, or
+     * one that exists only at run time. Being scoped rather than merely reached
+     * costs nothing in this plugin, which writes nothing anywhere; it is the
+     * command-line host that acts on it, publishing a `README.md` section for a
+     * scoped project on a `--write` run.
+     *
+     * External `npm:` targets are dropped: they have no workspace directory to
+     * trace, and following them would mean tracing `node_modules`.
+     */
+    resolveDependencyClosure(args: {
+        graph: ProjectGraph;
+        projectNames: readonly string[];
+    }): string[];
+    /**
+     * Resolves Nx project names and tags to their workspace-relative roots.
+     *
+     * The two selections are unioned, not intersected: naming a project and
+     * naming a tag both widen what gets traced, and a project reached both ways
+     * is still one directory. Intersecting them would make `--tags` a filter on
+     * `--projects`, which would resolve to nothing whenever only one was given.
+     *
+     * Unknown names and unmatched tags are collected rather than dropped or
+     * thrown on, so one resolution reports every typo at once instead of one
+     * per run, and the caller decides whether a partial resolution is worth
+     * tracing.
+     */
+    resolveDirectories(args: {
+        graph: ProjectGraph;
+        projectNames?: readonly string[] | undefined;
+        tags?: readonly string[] | undefined;
+    }): ResolvedProjectDirectories;
+    /**
+     * Resolves names and tags to the project names they stand for.
+     *
+     * Separate from `resolveDirectories` because a directory is the last step,
+     * not the only one: widening a selection along the Nx dependency graph
+     * happens between the two, and it happens in names, which is the only
+     * vocabulary the project graph speaks.
+     */
+    resolveProjectNames(args: {
+        graph: ProjectGraph;
+        projectNames?: readonly string[] | undefined;
+        tags?: readonly string[] | undefined;
+    }): ResolvedProjectSelection;
+    /** Maps project names to their workspace-relative roots, sorted and deduplicated. */
+    toDirectories(args: {
+        graph: ProjectGraph;
+        projectNames: readonly string[];
+    }): string[];
+}
+
+/** Resolves the service backing the `depth` and `breadth` lookups. */
+export declare function resolveAddressService(): Promise<AddressService>;
+
+/** A resolved selection, mapped on to the directories a trace takes. */
+export declare interface ResolvedProjectDirectories extends ResolvedProjectSelection {
+    /**
+     * Workspace-relative roots of the names that resolved, sorted and
+     * deduplicated — the form `callidescope --directories` takes.
+     */
+    readonly directories: string[];
+}
+
+/** What a set of Nx project names and tags resolved to, before directories. */
+export declare interface ResolvedProjectSelection {
+    /**
+     * Every project name the graph knew, sorted — what a caller names back when
+     * refusing an unknown one.
+     */
+    readonly knownNames: string[];
+    /**
+     * Every tag any project in the workspace carries, sorted and deduplicated —
+     * what a caller names back when refusing one nothing carries.
+     */
+    readonly knownTags: string[];
+    /** The projects the selection reached, sorted and deduplicated. */
+    readonly projectNames: string[];
+    /**
+     * The names the project graph does not know, in the order they were given.
+     *
+     * Reported rather than dropped: a name nobody resolves is a trace that
+     * silently covers less than it was asked to, which is the one failure a
+     * report cannot show you.
+     */
+    readonly unknownNames: string[];
+    /**
+     * The tags no project in the workspace carries, in the order they were
+     * given.
+     *
+     * Refused for the same reason an unknown name is: a tag matching nothing is
+     * far more often a typo than an empty category, and either way the run it
+     * would produce covers less than it was asked to without saying so.
+     */
+    readonly unmatchedTags: string[];
+}
+
+/** What a selection of Nx projects resolved to before a trace runs. */
+export declare interface ResolvedTraceScope {
+    /** Workspace-relative directories to hand `callidescope --directories`. */
+    readonly directories: string[];
+    /** Every project name the workspace has, for naming an unknown one back. */
+    readonly knownNames: string[];
+    /** Every tag the workspace carries, for naming an unmatched one back. */
+    readonly knownTags: string[];
+    /** Every project the selection reached, including pulled-in dependencies. */
+    readonly projectNames: string[];
+    /**
+     * Directories of the projects the selection itself named, before the
+     * dependency widening.
+     *
+     * What a verdict covers, where `directories` is what a trace reads: a
+     * dependency pulled in to keep a stack from stopping at a package boundary
+     * is measured by this run and judged by its own.
+     */
+    readonly selectedDirectories: string[];
+    /** Names the workspace does not have. */
+    readonly unknownNames: string[];
+    /** Tags no project in the workspace carries. */
+    readonly unmatchedTags: string[];
+}
+
+/** Resolves the service that reads this plugin's registration in `nx.json`. */
+export declare function resolveOptionsService(): Promise<OptionsService>;
+
+/** Resolves the service backing target inference and the trace executor. */
+export declare function resolvePluginService(): Promise<PluginService>;
+
+/** Resolves the service that reads the workspace's Nx project graph. */
+export declare function resolveProjectsService(): Promise<ProjectsService>;
+
+/** Arguments for resolving what one executor invocation should trace. */
+declare interface ResolveTraceScopeArguments {
+    /** Names from the executor's `projects` option. Empty selects nothing. */
+    readonly projectNames: readonly string[];
+    /** Tags from the executor's `tags` option. Empty selects nothing. */
+    readonly tags: readonly string[];
+    /** Whether the selection widens along the Nx dependency graph. */
+    readonly withDependencies: boolean;
+}
+
+/**
+ * Finds and reads the callidescope configuration one run is judged by.
+ *
+ * Its own service rather than more of `PluginService`, because every target
+ * here starts by answering the same question — which configuration file is
+ * this run's — and none of them can be written until it is answered. Keeping
+ * it apart also keeps the verdict and the inference in `PluginService` beside
+ * each other, which is where the rules a reader comes looking for are.
+ */
+declare class RunConfigurationService {
+    private readonly configurationService;
+    private readonly optionsService;
+    constructor(configurationService: ConfigurationService, optionsService: OptionsService);
+    /**
+     * Reads the workspace's `nx.json`, so this plugin's own registration can be
+     * consulted for a configuration path an executor was not given.
+     *
+     * Unreadable or malformed is not an error: the caller falls back to the
+     * conventional filenames, which a workspace with no registration gets anyway.
+     */
+    private readNxConfiguration;
+    /**
+     * Resolves and loads the configuration one run is judged by.
+     *
+     * The file-aware load rather than the plain one: a run resolves a
+     * configuration beside every project it reaches, and skips whichever file is
+     * already serving as this run's own.
+     */
+    load(args: LoadRunConfigurationArguments): Promise<LoadedRunConfiguration>;
+}
+
+/**
+ * Arguments for gating one resolved selection against its limits.
+ *
+ * The trace's arguments without `format`: a gate's output is the findings that
+ * decided its exit code, so there is no second rendering of it to ask for.
+ */
+declare type RunGateArguments = Omit<RunTraceArguments, "format">;
+
+/** Arguments for tracing one resolved selection. */
+declare interface RunTraceArguments {
+    /** Resolved from this plugin's `nx.json` registration when omitted. */
+    readonly configurationPath?: string | undefined;
+    readonly directories: readonly string[];
+    /** What the run prints. Defaults to markdown when omitted. */
+    readonly format?: CallidescopeOutputFormat | undefined;
+    /**
+     * The projects whose findings decide the verdict.
+     *
+     * A subset of `directories`, which is what gets traced: a run reaches into
+     * the dependencies of what it was pointed at, and a finding there belongs
+     * to the task named after the project that owns it.
+     *
+     * Workspace-relative roots, because that is what callidescope calls a
+     * project name — `WorkspaceService.discoverProjects` names each project by
+     * the directory holding its `tsconfig.json`, and a report's `projectName`
+     * is that same string. An Nx project name would match nothing.
+     */
+    readonly judgedProjectNames: readonly string[];
+    readonly workspaceRoot: string;
+}
+
+/** The outcome of tracing one selection. */
+export declare interface RunTraceResult {
+    readonly ok: boolean;
+    readonly report: string;
+}
+
+export { }