depcurfew 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Readable, Writable } from "node:stream";
 type ToolId = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'deno' | 'uv' | 'pip' | 'poetry' | 'pdm' | 'pipenv' | 'renovate' | 'dependabot';
 type ToolKind = 'package-manager' | 'update-bot';
 /** The registry a package manager installs from; package names in the policy are compared per ecosystem. */
@@ -111,6 +112,7 @@ interface UserDirectory {
     env: string;
     absolute?: boolean;
     relativeToCwd?: boolean;
+    emptyCounts?: boolean;
   } | 'home';
   /** Path below it, with / separators; empty for the directory itself. */
   path: string;
@@ -179,10 +181,35 @@ interface UserVariable {
   /** The file the tool reads when the variable is unset, from the home directory (~/.npmrc): naming it changes nothing. */
   defaultPath?: string;
 }
+/**
+ * Directories of the user file that a library the tool calls decides, by the library's version (platformdirs for
+ * Poetry and PDM on macOS). depcurfew reads that version from the library's .dist-info next to the tool's own.
+ */
+interface LibraryDirectories {
+  /** The distribution name of the library, as its .dist-info folder spells it (platformdirs). */
+  library: string;
+  /** The platforms whose directories it decides; the other platforms keep those of `files`. */
+  platforms: readonly UserPlatform[];
+  /** The directories per library version, oldest first; they replace the directories of `files` on those platforms. */
+  directories: Versioned<readonly UserDirectory[]>;
+}
+/** The unit of the release-age setting in the user file, when it differs from the tool's own (`cooldown.unit`). */
+interface UserCooldownUnit {
+  key: string;
+  unit: 'seconds' | 'minutes' | 'hours' | 'days';
+  /** Only whole numbers count; depcurfew rounds up, to the longer delay. */
+  wholeNumbers: boolean;
+  /** What the tool does with any other value: ignores it without a word, or stops. */
+  otherValues: 'ignored' | 'fail';
+}
 /** The tool's user-level configuration, for `depcurfew apply --user` and `doctor --user`. */
 interface UserConfigKnowledge {
   /** The user file per version, oldest first; null for versions without a user file. */
   files: Fact<Versioned<UserFile | null>>;
+  /** Directories of the user file that depend on the version of a library the tool calls. */
+  libraryDirectories?: Fact<LibraryDirectories>;
+  /** The unit of the release-age setting there, when it is not the unit of the tool's project setting. */
+  cooldownUnit?: Fact<UserCooldownUnit>;
   /** Settings depcurfew can write there. */
   settings: Fact<readonly UserSetting[]>;
   /** What a version does with a key it does not know in the user file: ignore it, warn, or fail. */
@@ -211,6 +238,22 @@ interface ToolKnowledge {
   /** Further sourced facts that matter for generators and `doctor`, keyed by a short name. */
   extra?: Readonly<Record<string, Fact<unknown>>>;
 }
+/**
+ * The values with which a switch weakens a protection: `delay` is a release-age delay in the tool's unit
+ * (cooldown.unit) or a duration string (durationStrings), which depcurfew compares with the policy; `any` is every
+ * value; otherwise the values listed, or every value except those (fail closed). A flag without a value is "true".
+ */
+type OverrideValues = 'delay' | 'any' | readonly string[] | {
+  readonly except: readonly string[];
+};
+/** An option or environment variable of one command that weakens what depcurfew apply configured. */
+interface OverrideSwitch {
+  /** The option as the scanner resolves it (--name) or the variable, compared without regard to case. */
+  name: string;
+  /** The release-age delay, or the rule on dependency install scripts. */
+  weakens: 'delay' | 'scripts';
+  values: OverrideValues;
+}
 /** A tool that environment facts refer to: Node.js, Python or a package manager. */
 type RuntimeOrTool = 'node' | 'python' | ToolId;
 interface PackageManagerFieldKnowledge {
@@ -287,6 +330,18 @@ interface NpmRegistryKnowledge {
   installScripts: readonly string[];
 }
 /** How the Python interpreter runs a module (python -m pip) or a command string. */
+/**
+ * A Python virtual environment as venv creates it: `marker` is the file in the environment's directory, and the
+ * activation scripts sit in a binary directory right under it, per platform (bin on POSIX, Scripts on Windows).
+ */
+interface VirtualEnvironmentKnowledge {
+  marker: string;
+  scripts: readonly {
+    platform: 'posix' | 'windows';
+    directory: string;
+    names: readonly string[];
+  }[];
+}
 interface PythonInterpreterKnowledge {
   /** Executable names; versioned names such as python3.12 are the same. */
   executables: readonly string[];
@@ -377,11 +432,172 @@ interface ClaudeCodeHooksKnowledge {
     args: string;
   };
 }
+/** additionalContext in hookSpecificOutput of a PreToolUse hook: text Claude reads next to the tool result. */
+interface ClaudeCodeHookContextKnowledge {
+  field: string;
+  /** Whether the field works without a permission decision (which leaves the call to the normal permission flow). */
+  withoutDecision: boolean;
+  /** Longer text is written to a file and Claude gets its path with a preview. */
+  inlineLimit: number;
+}
+/** The SessionStart hook that can install the project, and what happens to a guard whose script is missing. */
+interface ClaudeCodeSessionStartKnowledge {
+  event: string;
+  /** The matchers for a new and a resumed session. */
+  matchers: readonly string[];
+  /** The variable a shell-form hook command reads for the project root. */
+  projectDirVariable: string;
+  /** Whether Claude's first response waits for SessionStart hooks to finish. */
+  firstResponseWaits: boolean;
+  /** What a PreToolUse hook with onFailure "block" does when its script is missing. */
+  missingScriptWithBlock: 'blocks';
+  /** The part of the error Claude Code shows then, before the output of the command that failed. */
+  blockedNotice: string;
+  /** Whether a cloud environment's setup script runs before Claude Code starts. */
+  cloudSetupScriptRunsBeforeClaudeCode: boolean;
+}
 /** A Claude Code tool that runs shell commands, by the name a matcher and the event use, and the shell it runs them in. */
 interface ClaudeCodeShellTool {
   tool: string;
   shell: 'bash' | 'powershell';
 }
+/** A shell tool call that carries another input in place of the command (a Monitor WebSocket watch). */
+interface ClaudeCodeCommandlessInputKnowledge {
+  tool: string;
+  /** The field of the event, next to the command field, that takes the place of the command. */
+  input: string;
+}
+/** Model Context Protocol revisions: the legacy ones open a session with initialize, the modern ones carry the version on every request. */
+interface McpRevisionsKnowledge {
+  /** Newest first. */
+  legacy: readonly string[];
+  /** Newest first. */
+  modern: readonly string[];
+}
+/** The initialize handshake of the legacy revisions. */
+interface McpLifecycleKnowledge {
+  initialize: string;
+  initialized: string;
+  ping: string;
+  /** Fields of the initialize request and result. */
+  request: {
+    protocolVersion: string;
+    capabilities: string;
+    clientInfo: string;
+  };
+  result: {
+    protocolVersion: string;
+    capabilities: string;
+    serverInfo: string;
+    instructions: string;
+  };
+}
+/** What a modern (stateless) request and result carry in `_meta`, and the discovery method. */
+interface McpStatelessKnowledge {
+  metaField: string;
+  protocolVersion: string;
+  clientCapabilities: string;
+  clientInfo: string;
+  serverInfo: string;
+  discover: string;
+  /** The fields of a discovery result. */
+  discoverResult: {
+    supportedVersions: string;
+    capabilities: string;
+    instructions: string;
+  };
+  /** Every modern result has this field, with `complete` for a finished result. */
+  resultType: {
+    field: string;
+    complete: string;
+  };
+  /** Caching hints that discovery and tools/list results must carry. */
+  caching: {
+    ttl: string;
+    scope: string;
+    publicScope: string;
+  };
+  /** The data of an unsupported-version error. */
+  unsupportedVersionData: {
+    supported: string;
+    requested: string;
+  };
+}
+/** Tools: the methods and the fields of a tool and of a call result. */
+interface McpToolsKnowledge {
+  list: string;
+  call: string;
+  capability: string;
+  /** The revision that added each optional field of a tool or a result; older clients do not know them. */
+  fieldsSince: {
+    annotations: string;
+    title: string;
+    structuredContent: string;
+  };
+}
+interface McpCancellationKnowledge {
+  method: string;
+  requestId: string;
+}
+/** The JSON-RPC error codes the server uses. */
+interface McpErrorCodesKnowledge {
+  parseError: number;
+  invalidRequest: number;
+  methodNotFound: number;
+  invalidParams: number;
+  internalError: number;
+  unsupportedProtocolVersion: number;
+}
+/** The id of an error response: required (a string or a number) in the schemas before `optionalSince`, optional from it. */
+interface McpErrorIdKnowledge {
+  optionalSince: string;
+}
+/** stdio: messages are UTF-8 JSON-RPC, one per line, without embedded newlines; stderr is free for logs. */
+interface McpStdioKnowledge {
+  delimiter: string;
+  /** Revisions whose servers must accept JSON-RPC batches (arrays). */
+  batchRevisions: readonly string[];
+}
+/** How Claude Code is told about a stdio server: `claude mcp add` and the project file. */
+interface McpClaudeCodeKnowledge {
+  /** claude mcp add [options] <name> -- <command> [args...] */
+  addCommand: readonly string[];
+  separator: string;
+  scopeOption: string;
+  projectScope: string;
+  transportOption: string;
+  stdioTransport: string;
+  projectFile: string;
+  serversKey: string;
+  /** Set in the server's environment to the project root; in command and args it needs a default. */
+  projectDirVariable: string;
+  projectDirReference: string;
+}
+/** Where Claude Desktop keeps its configuration, per platform, and the key of its servers. */
+interface McpClaudeDesktopKnowledge {
+  configFiles: {
+    darwin: string;
+    win32: string;
+    linux: string;
+  };
+  serversKey: string;
+}
+/** VS Code's own format (.vscode/mcp.json) and its command line. */
+interface McpVsCodeKnowledge {
+  file: string;
+  serversKey: string;
+  typeField: string;
+  stdioType: string;
+  cwdField: string;
+  workspaceFolder: string;
+  /** code --add-mcp '{"name": …, …}' adds a server to the user profile. */
+  addOption: string;
+}
+interface McpClientsKnowledge {
+  claudeCode: Fact<McpClaudeCodeKnowledge>;
+  claudeDesktop: Fact<McpClaudeDesktopKnowledge>;
+  vscode: Fact<McpVsCodeKnowledge>;
+}
 /**
  * Annotation workflow commands: `::{command} {property}={value},…::{message}` on a line of its own. Values are
  * escaped by replacing each character listed in `escape` (in order), properties also with `escapeProperty`.
@@ -408,13 +624,32 @@ interface AnnotationLimitsKnowledge {
 /** The Markdown job summary of a step: the environment variable naming its file and its size limit. */
 /** Creating a check run with the workflow token, so that the result shows in the pull request's Checks tab. */
 interface CheckRunsKnowledge {
-  /** POST endpoint, with {repository} as owner/name. */
-  endpoint: string;
+  /**
+   * Paths with {repository} as owner/name: create (POST), update (PATCH, {id} the check run), and list the check runs
+   * of a commit (GET, {ref} a SHA), which takes the query parameters checkName and filter (with the value latest).
+   */
+  endpoints: {
+    create: string;
+    update: string;
+    list: string;
+  };
+  query: {
+    checkName: string;
+    filter: string;
+    latest: string;
+  };
   apiVersion: string;
-  /** The workflow permission the token needs. */
+  /** The workflow permission the token needs; it covers the list endpoint too (write includes read). */
   permission: Record<string, string>;
   /** Limit of output.summary, in characters. */
   summaryMaxLength: number;
+  /** output.annotations: at most this many per request; further ones are appended by update requests. */
+  annotationsPerRequest: number;
+  /** annotation_level for each doctor level. */
+  annotationLevels: Record<'error' | 'warning' | 'note', string>;
+  /** Limits of an annotation: title in characters, message in bytes (64 KB, taken as 64000). */
+  annotationTitleMaxLength: number;
+  annotationMessageMaxBytes: number;
   /** Variables the runner sets: API URL, owner/name, commit and the event payload file. */
   variables: {
     apiUrl: string;
@@ -456,12 +691,153 @@ interface GitIgnoreCaseKnowledge {
   /** Values read as true (case-insensitive); a key without a value is true too. */
   trueValues: readonly string[];
 }
+/** The file in which Corepack records the version of each package manager it runs outside a project. */
+interface CorepackDefaultsKnowledge {
+  /** The first Corepack version with this layout. */
+  since: string;
+  /** Where the file is: the first directory that applies is used. */
+  locations: readonly UserLocation[];
+}
+/** The version of a tool each release of a runtime bundles, for one release line (Node.js 22, CPython 3.12). */
+interface BundledVersionsLine {
+  /** The release line: 22 for Node.js, 3.12 for CPython. */
+  line: string;
+  /** The newest release of the line on the day the fact was verified. */
+  latest: string;
+  /** [first release, bundled version]: the first release of the line that bundles each version, oldest first. */
+  bundles: readonly (readonly [string, string])[];
+}
+/** One Node.js release line in the release schedule. */
+interface ReleaseLineSchedule {
+  line: number;
+  /** The first release (YYYY-MM-DD). */
+  start: string;
+  /** When the line became LTS; absent for lines that never do. */
+  lts?: string;
+  /** End of life: no more releases, security fixes included. */
+  end: string;
+  /** The LTS codename in lower case, as nvm, setup-node and the node image tags write it. */
+  codename?: string;
+}
+/** Names of moving Node.js versions in a version file or a setup-node input. */
+interface NodeVersionNamesKnowledge {
+  /** Names of the newest release. */
+  newest: readonly string[];
+  /** The name of the newest LTS line. */
+  newestLts: string;
+  /** Followed by a codename: that LTS line (lts/jod). */
+  ltsPrefix: string;
+  /** Followed by a number n: the n-th LTS line before the newest one (lts/-1); absent when not supported. */
+  previousLtsPrefix?: string;
+}
+interface NvmrcKnowledge extends NodeVersionNamesKnowledge {
+  file: string;
+  /** Starts a comment that runs to the end of the line. */
+  comment: string;
+}
+/** How setup-node reads the file named by node-version-file. */
+interface SetupNodeVersionFileKnowledge {
+  /** A JSON manifest whose keys are read in order: dotted paths, devEngines.runtime means its entry named node. */
+  packageJson: string;
+  packageJsonOrder: readonly string[];
+  /** Any other file: the first line that matches (multiline), group "version"; otherwise the whole text, trimmed. */
+  textPattern: string;
+}
+/** How an image reference names the registry, the namespace and the tag when they are left out. */
+interface ImageReferenceKnowledge {
+  defaultHost: string;
+  /** Hosts that mean the default registry. */
+  hosts: readonly string[];
+  /** The namespace of the official images, implied when a Docker Hub name has no namespace. */
+  officialNamespace: string;
+  defaultTag: string;
+}
+/** The Dockerfile syntax the reader relies on. */
+interface DockerfileSyntaxKnowledge {
+  /** Starts a comment line, and a parser directive at the top of the file. */
+  comment: string;
+  /** The parser directive that sets the escape character, and the characters it accepts (the default first). */
+  escapeDirective: string;
+  escapeCharacters: readonly string[];
+  /** The only instruction allowed before the first FROM. */
+  globalArgInstruction: string;
+}
+/** An official runtime image: which tool version it ships and how its tags are built. */
+interface RuntimeImageKnowledge {
+  /** The repository name on Docker Hub, in the official namespace. */
+  image: string;
+  /** The tool the image ships as the runtime release bundles it, unchanged. */
+  bundles: 'npm' | 'pip';
+  /** Variant names a tag may carry after the version (22-alpine, 3.12-slim-bookworm), or on its own. */
+  variants: readonly string[];
+}
+/** Tags of an official image that move to another release line: tag (without variant) to release line. */
+interface MovingTagsKnowledge {
+  tags: Readonly<Record<string, string>>;
+}
 interface EnvironmentKnowledge {
   corepack: {
     packageManagerField: Fact<PackageManagerFieldKnowledge>;
     devEnginesSince: Fact<string>;
     envFileSince: Fact<string>;
     bundledWithNode: Fact<Versioned<boolean>>;
+    /** The npm package of Corepack, whose package.json declares the shims of the package managers (yarn, pnpm). */
+    package: Fact<string>;
+    /** The npm packages that install a package manager itself, for the tools Corepack knows. */
+    toolPackages: Fact<Readonly<Partial<Record<ToolId, readonly string[]>>>>;
+    /** lastKnownGood.json: the version of each package manager Corepack runs outside a project. */
+    defaults: Fact<CorepackDefaultsKnowledge>;
+    /** corepack enable installs an npm shim only when npm is named. */
+    enableNpm: Fact<{
+      command: string;
+      npmOnlyWhenNamed: boolean;
+    }>;
+  };
+  node: {
+    /** The npm each Node.js release bundles, per release line. */
+    bundledNpm: Fact<readonly BundledVersionsLine[]>;
+    releaseSchedule: Fact<readonly ReleaseLineSchedule[]>;
+    nvmrc: Fact<NvmrcKnowledge>;
+    /** The version file of nodenv, also read by fnm and setup-node. */
+    nodeVersionFile: Fact<{
+      file: string;
+    }>;
+    /** engines.node in package.json: the Node.js versions a package works with, advisory. */
+    engines: Fact<{
+      key: string;
+      runtimeKey: string;
+    }>;
+    /** The Node.js version files that version managers also use in subdirectories of their directory. */
+    inheritedVersionFiles: Fact<readonly string[]>;
+  };
+  docker: {
+    imageReference: Fact<ImageReferenceKnowledge>;
+    syntax: Fact<DockerfileSyntaxKnowledge>;
+    /** How COPY and ADD read a source path in the build context: from its root, with ../ and trailing slashes removed. */
+    copySources: Fact<{
+      relativeTo: 'context';
+      parentNavigation: 'removed';
+      trailingSlash: 'ignored';
+    }>;
+    /** ENV: variables for the later instructions of the stage and the stages that start from it (decision D-115). */
+    environment: Fact<{
+      instruction: string;
+      inheritedByStages: boolean;
+      spaceForm: boolean;
+    }>;
+    /** The default file name, and the suffix of other Dockerfiles (build.Dockerfile). */
+    dockerfileNames: Fact<{
+      defaultName: string;
+      suffix: string;
+    }>;
+    /** Dockerfile.<name>: a common convention without an official source. */
+    dockerfilePrefix: Fact<string>;
+    /** The file name Buildah and Podman read by default. */
+    containerfile: Fact<string>;
+    nodeImage: Fact<RuntimeImageKnowledge>;
+    nodeImageTags: Fact<MovingTagsKnowledge>;
+    pythonImage: Fact<RuntimeImageKnowledge>;
+    pythonImageTags: Fact<MovingTagsKnowledge>;
   };
   devEngines: Fact<DevEnginesKnowledge>;
   devEnginesSince: Fact<string>;
@@ -478,6 +854,23 @@ interface EnvironmentKnowledge {
   githubActions: {
     workflows: Fact<WorkflowsKnowledge>;
     setupNode: Fact<SetupActionKnowledge>;
+    /** The versions node-version accepts besides semver ranges. */
+    setupNodeVersions: Fact<NodeVersionNamesKnowledge>;
+    setupNodeVersionFile: Fact<SetupNodeVersionFileKnowledge>;
+    /**
+     * jobs.<job_id>.container: the image the job's run steps run in, as a string or under image, with its env
+     * (decision D-115).
+     */
+    jobContainer: Fact<{
+      key: string;
+      imageKey: string;
+      envKey: string;
+    }>;
+    /** The env maps of a workflow, a job and a step; the most specific one wins (decision D-115). */
+    environmentKeys: Fact<{
+      key: string;
+      levels: readonly ('workflow' | 'job' | 'step')[];
+    }>;
     pnpmActionSetup: Fact<SetupActionKnowledge>;
     pnpmSetup: Fact<SetupActionKnowledge>;
     setupBun: Fact<SetupActionKnowledge>;
@@ -512,11 +905,36 @@ interface EnvironmentKnowledge {
     hooks: Fact<ClaudeCodeHooksKnowledge>;
     /** The tools whose PreToolUse events carry a shell command in the hooks fact's input.command. */
     shellTools: Fact<readonly ClaudeCodeShellTool[]>;
+    sessionStart: Fact<ClaudeCodeSessionStartKnowledge>;
+    /** The field of a PreToolUse hook's output that adds text to Claude's context, with or without a decision. */
+    hookContext: Fact<ClaudeCodeHookContextKnowledge>;
+    /** Shell tool calls without a command: a Monitor WebSocket watch. */
+    commandlessInputs: Fact<readonly ClaudeCodeCommandlessInputKnowledge[]>;
+  };
+  /** The Model Context Protocol, for depcurfew mcp, and how its clients start a stdio server. */
+  mcp: {
+    revisions: Fact<McpRevisionsKnowledge>;
+    lifecycle: Fact<McpLifecycleKnowledge>;
+    stateless: Fact<McpStatelessKnowledge>;
+    tools: Fact<McpToolsKnowledge>;
+    cancellation: Fact<McpCancellationKnowledge>;
+    errorCodes: Fact<McpErrorCodesKnowledge>;
+    errorId: Fact<McpErrorIdKnowledge>;
+    stdio: Fact<McpStdioKnowledge>;
+    clients: McpClientsKnowledge;
   };
   git: {
     /** Where git reads the patterns of files it does not pick up, and the index that lists the tracked files. */
     ignore: Fact<GitIgnoreKnowledge>;
     ignoreCase: Fact<GitIgnoreCaseKnowledge>;
+    /**
+     * The entry at the root of a working tree that makes a directory a repository of its own: a .git directory, or in
+     * a submodule a .git file pointing to its git directory in the superproject (decision D-115).
+     */
+    repositoryEntry: Fact<{
+      entry: string;
+      submoduleEntry: 'file';
+    }>;
   };
   windows: {
     commandShims: Fact<CommandShimsKnowledge>;
@@ -540,6 +958,10 @@ interface EnvironmentKnowledge {
     /** File extensions of source distributions on an index, which are built when installed. */
     sourceDistributionExtensions: Fact<readonly string[]>;
     interpreter: Fact<PythonInterpreterKnowledge>;
+    /** A virtual environment made by venv: the file in its directory that marks it, and its activation scripts. */
+    virtualEnvironment: Fact<VirtualEnvironmentKnowledge>;
+    /** The pip each CPython release bundles in ensurepip, per release line. */
+    bundledPip: Fact<readonly BundledVersionsLine[]>;
     /** Hatch, which has no supply-chain settings of its own: how a project shows it uses Hatch. */
     hatch: Fact<{
       pyprojectTable: string;
@@ -556,18 +978,125 @@ interface Evidence {
   /** Repository-relative path with `/` separators. */
   file: string;
 }
-/** tool-config: a version the tool's own configuration requires, e.g. required-version in [tool.uv]. */
-type VersionSource = 'packageManager' | 'tool-config' | 'devEngines' | 'volta' | 'tool-versions' | 'github-actions';
-/** A version declared somewhere in the repository, as written (it may be a range or an expression). */
+/**
+ * tool-config: a version the tool's own configuration requires, e.g. required-version in [tool.uv]. nvmrc and
+ * node-version: the files .nvmrc and .node-version; engines: engines.node in package.json (a range of the Node.js
+ * versions the package works on, advisory); dockerfile: a Dockerfile (FROM node:22, RUN npm install -g npm@11).
+ */
+type VersionSource = 'packageManager' | 'tool-config' | 'devEngines' | 'volta' | 'tool-versions' | 'nvmrc' | 'node-version' | 'engines' | 'github-actions' | 'dockerfile';
+/**
+ * A version declared somewhere in the repository, as written (it may be a range or an expression). A CI step that
+ * names a version file has `versionFile`, and also `version` when depcurfew could read the version from that file.
+ */
 type VersionDeclaration = ({
   version: string;
+  versionFile?: string;
 } | {
   versionFile: string;
 }) & {
   source: VersionSource;
   file: string;
   line?: number;
+  /** github-actions: the key of the job under jobs. */
+  job?: string;
+  /** github-actions: the line of the step that sets the version up; installs after it and before the next such step use it. */
+  step?: number;
+  /** github-actions: the version is one value of this matrix key, from ${{ matrix.<key> }}; the line is the value's. */
+  matrix?: string;
+  /** Why depcurfew does not read the version written (a matrix with too many values); the version is then as written. */
+  unknown?: string;
+  /** dockerfile: the build stage, by its name or its number from 0. */
+  stage?: string;
+  /**
+   * github-actions: the image of jobs.<id>.container (node:20) the version comes from, read like a FROM of a Dockerfile
+   * (decision D-115); the line is the image's, and it stands for the job's steps until a setup step.
+   */
+  container?: string;
 };
+/**
+ * A command in a CI run step or a Dockerfile RUN instruction. install: installs packages with the tool (npm ci,
+ * npm install, pip install -r requirements.txt, pnpm install, yarn, bun add); upgrade: replaces the tool itself
+ * (npm install -g npm@11.17.0, pip install --upgrade pip, corepack enable npm). npm install -g with another package is
+ * neither: npm does not read the project .npmrc in global mode.
+ */
+interface ToolCommand {
+  kind: 'install' | 'upgrade';
+  /**
+   * pnpm, Yarn and Bun only install (their versions come from packageManager and the setup actions); poetry only
+   * upgrades: pipx install poetry==2.3.0 or pip install poetry==2.3.0 installs that Poetry (decision D-115).
+   */
+  tool: 'npm' | 'pip' | 'pnpm' | 'yarn' | 'bun' | 'poetry';
+  /** upgrade: the version asked for as written, latest when none is; absent when the command does not say (corepack enable npm). */
+  version?: string;
+  /** npm ci and its aliases, which install exactly the versions of package-lock.json (decision D-115). */
+  lockfile?: true;
+  /** npm runs it with dependency install scripts off (--ignore-scripts, npm_config_ignore_scripts=true; decision D-115). */
+  scriptsOff?: true;
+  /** pip install: the release-age delay it gets, as written (--uploaded-prior-to, PIP_UPLOADED_PRIOR_TO; decision D-115). */
+  delay?: string;
+  /** pip install: PIP_CONFIG_FILE names a file that may set the delay, or the value is a variable depcurfew does not read. */
+  delayUnknown?: true;
+  line: number;
+  /**
+   * github-actions: the working directory of the run step as written (working-directory of the step, or
+   * defaults.run.working-directory of the job or the workflow), without ./ and a trailing /, joined with the literal
+   * cd before the command (cd frontend && npm ci); absent for the root. dockerfile: the directory of a literal cd before
+   * the command, relative to the working directory of the instruction. A cd depcurfew does not follow ($DIR, an
+   * absolute path) gives a directory that is no project (decision D-115).
+   */
+  directory?: string;
+}
+/** A GitHub Actions job, with what its run steps do with npm and pip. */
+interface WorkflowJob {
+  file: string;
+  /** The key of the job under jobs. */
+  id: string;
+  line: number;
+  /** Installs and package manager changes, in order. */
+  commands: ToolCommand[];
+  /** A run step calls node, npm, npx, pnpm, yarn, bun or corepack, so the job uses the Node.js it sets up. */
+  runsNode: boolean;
+  /**
+   * A run step may change pip's configuration (pip config set, a pip.conf it writes, PIP_CONFIG_FILE in env), so the
+   * release-age delay of its pip installs cannot be told (decision D-115).
+   */
+  pipConfig?: true;
+}
+/** The official runtime image a build stage starts from. */
+interface StageRuntime {
+  tool: 'node' | 'python';
+  /** The tag as written after ARG substitution; absent when the image has none (latest, or a digest alone). */
+  tag?: string;
+  /** The version the tag names: 22, 22.11.0, lts, jod, latest (moving tags stay names); absent when it cannot be told. */
+  version?: string;
+  /** Why the version cannot be told. */
+  unknown?: string;
+}
+interface DockerStage {
+  /** The line of its FROM instruction. */
+  line: number;
+  /** The name after AS, in lower case. */
+  name?: string;
+  /** The image after ARG substitution; absent when an ARG it uses has no value. */
+  image?: string;
+  /** The earlier stage this one starts from (FROM <name>), by its number from 0. */
+  from?: number;
+  /** The official node or python image of this stage or of the stage it starts from. */
+  runtime?: StageRuntime;
+  commands: ToolCommand[];
+  /** A RUN may change pip's configuration (pip config set, a pip.conf it writes), as for jobs (decision D-115). */
+  pipConfig?: true;
+  /**
+   * The source paths of the stage's COPY and ADD instructions that copy from the build context (not --from), as
+   * written; absent when there are none. A root Dockerfile whose stage copies only files of one directory listed in
+   * projects builds that project (decision D-109). At most 256.
+   */
+  copies?: string[];
+}
+interface DockerfileInfo {
+  file: string;
+  stages: DockerStage[];
+}
 interface PackageManagerInfo {
   id: PackageManagerId;
   /** Yarn only: Berry (2+) or Classic (1.x). */
@@ -595,6 +1124,8 @@ interface DetectionWarning {
   code: string;
   message: string;
   files: string[];
+  /** The line in the first file the warning is about, when it names one (decision D-124). */
+  line?: number;
 }
 interface Detection {
   packageManagers: PackageManagerInfo[];
@@ -607,6 +1138,10 @@ interface Detection {
   npmrcFiles: string[];
   /** GitHub Actions workflow files that were read. */
   workflows: string[];
+  /** The jobs of those workflows. */
+  jobs: WorkflowJob[];
+  /** Dockerfiles and Containerfiles of the root, its direct subdirectories without a manifest, and workspace packages. */
+  dockerfiles: DockerfileInfo[];
   warnings: DetectionWarning[];
 }
 interface UserEnvironment {
@@ -624,6 +1159,25 @@ type FetchLike = (url: string, init: {
   signal: AbortSignal;
   redirect?: 'manual';
 }) => Promise<Response>;
+/**
+ * Lookups shared by the checks of one run, by registry or index and name: a command checked against two policies
+ * fetches and reads each document once (decision D-113).
+ */
+type LookupCache = Map<string, Promise<unknown>>;
+interface McpLimits {
+  /** The longest line, in bytes; a longer one is answered with an error and skipped. */
+  lineBytes: number;
+  /** The deepest nesting of arrays and objects in a message. */
+  depth: number;
+  /** Tool calls that run at once. */
+  concurrentCalls: number;
+  /** Tool calls that wait for one of them; a call beyond that gets a result that says to try again. */
+  queuedCalls: number;
+  /** Messages in one batch (2025-03-26 only). */
+  batch: number;
+  /** How long calls may still run after stdin ends before they are stopped. */
+  graceMs: number;
+}
 declare const EXIT_OK = 0;
 declare const EXIT_FAILURE = 1;
 declare const EXIT_USAGE = 2;
@@ -641,18 +1195,41 @@ interface CliIo {
     stderr: boolean;
   };
 }
-interface CheckDependencies {
-  fetch: FetchLike;
-  now: () => Date;
-  /** The whole of stdin, for hook mode. */
-  stdin: () => Promise<string>;
-  /** The user's home directory, with the user's .npmrc. */
-  home?: () => string;
-  /** --user: platform, home directory and environment variables (tests replace them). */
-  userEnvironment?: () => UserEnvironment;
+/** What the server talks over and the process around it; tests replace it. */
+interface McpProcess {
+  input: Readable;
+  output: Writable;
+  env: Readonly<Record<string, string | undefined>>;
+  cwd: string;
+  /** Calls `stop` on SIGINT and SIGTERM; returns what removes the handlers. Left out in tests. */
+  onSignal?: (stop: () => void) => () => void;
+  limits?: Partial<McpLimits>;
+}
+declare class Repository {
+  #private;
+  readonly root: string;
+  readonly warnings: DetectionWarning[];
+  /** Repository-relative paths of the files that were read, for the log of what doctor checked. */
+  readonly read: Set<string>;
+  constructor(root: string);
+  warn(code: string, message: string, files: readonly string[], line?: number): void;
+  isFile(path: string): boolean;
+  /** Whether the path exists in the repository as something other than a regular file or a directory (a named pipe, a socket, a device). */
+  isSpecialFile(path: string): boolean;
+  /** The text of a file, without a byte order mark; undefined (with a warning when useful) if it cannot be read. */
+  readText(path: string, limit?: number): string | undefined;
+  /** The first bytes of a file, e.g. to recognize a lockfile format without reading a large file. */
+  readHead(path: string, bytes?: number): string | undefined;
+  /** Names of the files in a directory (following symlinks only inside the repository). */
+  listFiles(path: string): string[];
+  /** Names of the subdirectories of a directory, skipping node_modules, .git and symlinks that lead outside. */
+  listDirectories(path: string): string[];
+  /** Parses a file with the given parser, reporting failures as warnings. */
+  parse<T>(path: string, parser: (text: string) => T): T | undefined;
+  /** Like parse, but each file is read and parsed once per parser: several rules read the same file. */
+  parseOnce<T>(path: string, parser: (text: string) => T): T | undefined;
+  relative(absolute: string): string;
 }
-declare function run(argv: readonly string[], output: CliIo, dependencies?: CheckDependencies): Promise<number>;
-declare function getVersion(): string;
 interface Duration {
   /** The duration as written in the policy. */
   text: string;
@@ -712,6 +1289,8 @@ interface Shape<In, Out = In> {
 }
 type Input<S> = S extends Shape<infer In, unknown> ? In : never;
 type Output<S> = S extends Shape<unknown, infer Out> ? Out : never;
+/** Which findings make depcurfew doctor exit with 1 (decision D-112). */
+declare const FAIL_ON_LEVELS: readonly ["error", "warning"];
 declare const policyShape: Shape<{
   version: 1;
   $schema?: string;
@@ -732,9 +1311,14 @@ declare const policyShape: Shape<{
     directory?: "allow" | "deny";
   };
   targets?: "auto" | readonly ToolId[];
+  projects?: readonly string[];
+  doctor?: {
+    failOn?: "error" | "warning";
+  };
 }, {
   version: 1;
   targets: "auto" | readonly ToolId[];
+  projects: readonly string[];
   $schema?: string;
   cooldown?: {
     minimum: Duration;
@@ -752,17 +1336,178 @@ declare const policyShape: Shape<{
     file?: "allow" | "deny";
     directory?: "allow" | "deny";
   };
+  doctor?: {
+    failOn?: "error" | "warning";
+  };
 }>;
 /** The policy as written in depcurfew.json. */
 type Policy = Input<typeof policyShape>;
 /** The policy after validation: defaults filled in, durations parsed. */
 type ResolvedPolicy = Output<typeof policyShape>;
+/** The SARIF levels: an error fails `doctor`, warnings and notes do not. */
+type Level = 'error' | 'warning' | 'note';
+interface Location {
+  /** Repository-relative path with `/` separators. */
+  file: string;
+  /** 1-based; absent when the finding concerns the whole file. */
+  line?: number;
+  /** 1-based column on `line`, when the problem has one (a syntax error); absent otherwise (decision D-116). */
+  column?: number;
+  /** doctor --user: the environment variable, as it is set, of a finding whose file is "environment". */
+  variable?: string;
+}
+interface Finding {
+  rule: string;
+  level: Level;
+  message: string;
+  location: Location;
+  /** A fix for this finding; the rule's general help applies when absent. */
+  fix?: string;
+}
+/**
+ * Something doctor could not check, such as an unreadable file. Not a problem in the repository itself, so it never
+ * fails doctor. It has the fields of a finding (decision D-116): the level, always note; a code, the rule that could not
+ * check something or the code of the warning or state that gave it; where it is; the message; and what to do.
+ */
+interface Notice {
+  level: 'note';
+  code: string;
+  message: string;
+  /** The file it concerns, the same as location.file; kept for programs that read it before location was added. */
+  file?: string;
+  /** The line, when the notice is about one (a CI run step or RUN instruction depcurfew did not follow, decision D-124). */
+  location?: {
+    file: string;
+    line?: number;
+  };
+  fix?: string;
+}
+interface RuleContext {
+  root: string;
+  repository: Repository;
+  detection: Detection;
+  /** undefined when the repository has no depcurfew.json. */
+  policy: ResolvedPolicy | undefined;
+  tools: readonly ToolKnowledge[];
+  report(finding: Omit<Finding, 'rule' | 'level'> & {
+    level?: Level;
+  }): void;
+  /** Something the rule could not check; its code is the rule's id (decision D-116). */
+  notice(message: string, file?: string, fix?: string): void;
+  /**
+   * Set when the rules run on a directory listed in projects in depcurfew.json (decision D-100): its path relative to
+   * the repository root. `root`, `repository` and `detection` are then the project's, and file names relative to it.
+   */
+  project?: string;
+  /**
+   * At the repository root: the directories listed in projects that could be read, for the rules that compare the
+   * bots, which are configured from the root, with the package managers of every project.
+   */
+  projects?: readonly ProjectView[];
+  /** How apply plans this directory, for the rules that compare with that plan (config-drift). */
+  plan?: PlanOptions;
+}
+/** A directory listed in projects, as the rules at the repository root see it. */
+interface ProjectView {
+  /** Relative to the repository root, as listed. */
+  directory: string;
+  /** The absolute path. */
+  root: string;
+  repository: Repository;
+  detection: Detection;
+}
+/** What a rule may look at to decide whether it concerns the project: the context without the reporting functions. */
+type RuleScope = Omit<RuleContext, 'report' | 'notice'>;
+interface Rule {
+  /** Stable kebab-case identifier, used in SARIF and in the documentation. */
+  id: string;
+  /** One sentence: what the rule finds. */
+  summary: string;
+  /** What the rule checks, said as what holds when it passes, for the list of what doctor checked. */
+  checks?: string;
+  /** Why it matters. */
+  description: string;
+  /** How to fix it in general. */
+  help: string;
+  /** Default level of its findings. */
+  level: Level;
+  /** Rules that compare the repository with depcurfew.json do not run without one. */
+  requiresPolicy: boolean;
+  /**
+   * Whether the rule concerns the project at all, from detection: the Python rules without a Python tool, the bot rules
+   * without a bot. false shows the rule as "not applicable" in the list of what doctor checked (decision D-098). It
+   * never changes findings: check still runs, and a rule that reports one has problems. Absent: it always applies.
+   */
+  applies?(scope: RuleScope): boolean;
+  check(context: RuleContext): void;
+}
+/** A package manager or bot doctor checked, with the version it checked against when one is known. */
+interface CheckedTool {
+  id: string;
+  name: string;
+  /** The directory listed in projects the tool was found in; absent for the repository root. */
+  project?: string;
+  version?: string;
+  /** Where the version comes from: a repository file, or PATH for doctor --user. */
+  versionFrom?: string;
+  /** A bot configuration in a directory listed in projects, which the bot does not read (it reads the root's, decision D-109). */
+  unread?: true;
+}
+/** One check of the list of what doctor checked: a rule and what came of it. */
+interface RuleResult {
+  rule: string;
+  /** What the rule checks, in plain words (Rule.check). */
+  check: string;
+  /**
+   * passed: it ran and found nothing; problems: it reported findings; skipped: it needs a policy that is missing or
+   * invalid; not-applicable: it does not concern the project, e.g. a Python rule without a Python tool (decision D-098).
+   */
+  result: 'passed' | 'problems' | 'skipped' | 'not-applicable';
+  errors: number;
+  warnings: number;
+  notes: number;
+}
+/** What doctor looked at, shown below the result, so that a clean report says what it covers. */
+interface Checked {
+  tools: CheckedTool[];
+  /** Files that were read, repository-relative (doctor) or as shown (~/.npmrc, doctor --user). */
+  files: string[];
+  /** Every rule, in the order it ran, with its result. */
+  rules: RuleResult[];
+  /** The policy that skipped rules need, as messages show it. */
+  policyFile: string;
+}
+interface DoctorReport {
+  schemaVersion: 1;
+  /** invalid: depcurfew.json does not follow the schema or cannot be read (only with invalidPolicy: 'report'). */
+  policy: 'valid' | 'missing' | 'invalid';
+  findings: Finding[];
+  notices: Notice[];
+  /** What was checked. */
+  checked?: Checked;
+}
+/** What a directory listed in projects takes from the repository root besides its CI installs (decision D-109). */
+interface RootPlaces {
+  /** The project; the stages of root Dockerfiles are then read for it (decision D-115). */
+  project?: string;
+  /** The root's Node.js version files (.nvmrc, .node-version, .tool-versions) of the kinds the project has none of. */
+  versions: readonly VersionDeclaration[];
+  /**
+   * Root Dockerfiles with the stages that build the project (they copy only its files, decision D-109) or install in its
+   * directory after copying the whole build context (cd frontend && npm ci, decision D-115).
+   */
+  dockerfiles: readonly {
+    file: DockerfileInfo;
+    stages: readonly number[];
+  }[];
+}
 declare const APPLY_WARNINGS: {
   readonly 'nothing-to-configure': "depcurfew found no supported package manager or bot, so nothing is configured.";
   readonly 'environment-overrides': "apply --user: an environment variable makes a tool read another user file or none, or overrides a value apply writes there.";
   readonly 'depcurfew-outdated': "The project installs a newer depcurfew than the one running, which may not know settings that version writes.";
   readonly 'file-unreadable': "A file that shows which tools a project uses cannot be read or parsed (too large, a symlink out of the repository, no read permission, invalid), so depcurfew may configure fewer tools than the project uses.";
   readonly 'tool-not-supported': "A detected or installed tool is not supported (Yarn Classic), so nothing is written for it.";
+  readonly 'target-not-found': "With projects, a package manager listed under targets is configured in each directory (the root or a project) that uses it, and none uses it, so nothing is written for it.";
   readonly 'tool-only-in-ci': "A tool appears only in a CI setup step, with no manifest, lockfile or configuration in the repository, so targets \"auto\" does not configure it.";
   readonly 'version-not-pinned': "No exact version of a package manager is pinned, so depcurfew configures for the latest version it knows.";
   readonly 'version-too-old': "The pinned version of a tool (with apply --user, the installed one) lacks a setting the policy needs, so that setting is not written.";
@@ -770,6 +1515,7 @@ declare const APPLY_WARNINGS: {
   readonly 'no-user-config': "apply --user: the tool has no user-level configuration file, so nothing is written for it.";
   readonly 'user-setting-project-only': "apply --user: the tool reads a part of the policy only from project files, so it is not written into the user file.";
   readonly 'user-directory-relative': "apply --user: the environment variable that names the directory of the user file (XDG_CONFIG_HOME, APPDATA) is a relative path, so the tool looks in another place from each directory, or where it looks then is not known; nothing is written for it.";
+  readonly 'user-file-uncertain': "apply --user: a library the tool calls decides where its user file is (platformdirs for Poetry and PDM on macOS), and its version cannot be read from files, so apply --user writes where the tool's docs say and names the other files the tool may read.";
   readonly 'user-setting-overridden': "apply --user: a file the tool reads ahead of its user file (~/.npmrc for pnpm 10) sets a key apply writes there to another value, so the value written has no effect.";
   readonly 'version-not-used': "apply --user: --for gives the version of a tool that apply --user does not configure (not in PATH with targets \"auto\", or not listed under targets).";
   readonly 'cooldown-not-written': "The release-age delay cannot be written for a tool.";
@@ -785,7 +1531,8 @@ declare const APPLY_WARNINGS: {
   readonly 'deny-conflicts-with-file': "An entry in a tool's own list lets a package of installScripts.deny run its install scripts, or blocks a package of installScripts.allow; apply does not change entries it did not write.";
   readonly 'unexpected-value': "A setting apply adds to has a value of a type the tool does not accept there, so apply leaves it as it is and writes nothing into it.";
   readonly 'built-in-list-replaced': "Bun's built-in list of trusted packages is replaced by the policy's allow-list.";
-  readonly 'scripts-not-enforceable': "The pinned (with apply --user, the installed) npm or pnpm runs every install script and has no allow-list, so \"deny\" cannot be enforced.";
+  readonly 'scripts-not-enforceable': "The pinned (with apply --user, the installed) npm or pnpm, or another npm the repository runs (one a declared Node.js comes with, or a CI job or Dockerfile installs), runs every install script and has no allow-list, so \"deny\" cannot be enforced; also given for an npm the repository runs whose version depcurfew cannot tell, which counts as one that runs them.";
+  readonly 'strict-allow-scripts-for-npm-in-use': "An npm the repository runs (the pinned one, one a CI job or Dockerfile installs, or one a declared Node.js comes with, for a project also through the root version files and root Dockerfiles that build it) is 11.16 to 11.x and runs install scripts the allow-list does not cover unless strict-allow-scripts is set, so apply writes strict-allow-scripts=true, which makes npm 12 stop the install at such a script; not given when that npm is the pinned one and no place runs npm 12.";
   readonly 'before-overrides-cooldown': "before= in .npmrc takes the place of the release-age delay apply writes, or makes npm stop with an error next to it (apply --user then does not write the delay).";
   readonly 'exact-version-gap': "The pinned (with apply --user, the installed) pnpm skips the release-age delay for packages requested by exact version.";
   readonly 'source-not-enforceable': "The tool has no setting for a dependency source the policy denies; doctor checks the lockfile instead.";
@@ -802,6 +1549,7 @@ declare const APPLY_WARNINGS: {
   readonly 'bot-config-missing': "A bot has no configuration file, and depcurfew does not create one.";
   readonly 'bot-config-not-edited': "A bot configuration file is in a place or format depcurfew does not edit; a snippet shows what to add.";
   readonly 'bot-entries-missing': "The Dependabot configuration has no entries for the package managers in use.";
+  readonly 'bot-rule-shortens-delay': "A Renovate packageRules entry apply does not manage gives every package of a registry, or some update types, a shorter release-age delay than the one apply writes; Renovate uses it, and apply does not change it.";
   readonly 'security-delay-unsupported': "Dependabot cannot delay security updates, so securityUpdates \"delay\" is not applied.";
 };
 declare const APPLY_ERRORS: {
@@ -813,12 +1561,21 @@ declare const APPLY_ERRORS: {
   readonly 'policy-exists': "depcurfew init found a depcurfew.json and writes it only with --force.";
   readonly 'directory-not-found': "The directory given on the command line does not exist or cannot be opened.";
   readonly 'not-a-directory': "The path given on the command line is a file, not a directory.";
+  readonly usage: "The command line is not valid: an unknown command, option or hook, a missing or extra argument, an option without its value or with one it does not take (such as a --registry that is not an http:// or https:// URL), or options that cannot go together (exit code 2); with --json the document holds only schemaVersion and this error.";
+  readonly 'project-not-found': "A directory listed in projects in depcurfew.json does not exist, so nothing is written.";
+  readonly 'project-not-a-directory': "A path listed in projects in depcurfew.json is a file, not a directory, so nothing is written.";
+  readonly 'project-symlink': "A directory listed in projects in depcurfew.json is a symlink or lies under one, which may lead out of the repository, so nothing is written.";
+  readonly 'project-has-policy': "A directory listed in projects has a depcurfew.json of its own, a second policy for the same files, so nothing is written.";
+  readonly 'project-is-repository': "A directory listed in projects is a separate git repository or lies in one (it has a .git of its own, as a git submodule does), whose files belong to that repository, so nothing is written.";
+  readonly 'project-in-workspace': "A directory listed in projects is, holds or lies in a workspace package of the repository root, which the root configuration already covers, so nothing is written.";
   readonly 'home-missing': "apply --user and init --user: the home directory (HOME, USERPROFILE on Windows) does not exist or is not an absolute path, so nothing is written.";
 };
 type ApplyWarningCode = keyof typeof APPLY_WARNINGS;
 type ApplyErrorCode = keyof typeof APPLY_ERRORS;
 interface ApplyWarning {
   code: ApplyWarningCode;
+  /** The directory listed in projects that the warning concerns; absent for the repository root. */
+  project?: string;
   /** The tool it concerns, when there is one. */
   tool?: ToolId;
   /** The file it concerns, when there is one, and the line when it is known. */
@@ -875,7 +1632,20 @@ interface EditFailure {
   file: string;
   message: string;
 }
+/** Why a directory listed in projects cannot be used; nothing is written and doctor reports it (invalid-project). */
+interface ProjectProblem {
+  code: Extract<ApplyErrorCode, `project-${string}`>;
+  /** The entry of projects it concerns. */
+  project: string;
+  location: {
+    file: string;
+    line?: number;
+  };
+  message: string;
+  fix: string;
+}
 interface ApplyReport {
+  /** Repository-relative paths, also for the files of the directories listed in projects. */
   changes: FileChange[];
   /** The warnings as one line of text each. */
   warnings: string[];
@@ -886,17 +1656,68 @@ interface ApplyReport {
   errors: string[];
   /** The same failures with the tool and the file. */
   failures: EditFailure[];
+  /**
+   * Directories listed in projects that cannot be used (decision D-100); their messages come first in `errors`, and
+   * nothing is written when there is one.
+   */
+  problems?: ApplyProblem[];
+}
+/** An error that concerns no file being edited (a directory listed in projects, the home directory of apply --user). */
+interface ApplyProblem {
+  code: ApplyErrorCode;
+  location: {
+    file: string;
+    line?: number;
+  };
+  message: string;
+  fix: string;
+}
+/** How a directory is planned in a repository with projects (decision D-100). */
+interface PlanOptions {
+  /** The directory is the project listed so in projects (relative to the repository root): bots are not configured there. */
+  project?: string;
+  /** The directory is the root of a repository with projects: what the projects configure, which bots serve too. */
+  projects?: {
+    managerMinutes: readonly number[];
+    targets: ReadonlySet<ToolId>;
+  };
+  /**
+   * The project's installs in CI jobs of the repository root (working-directory: frontend), with their Node.js setup
+   * steps, for the npm the project runs (decision D-105); jobsInProject gives them.
+   */
+  ci?: {
+    jobs: readonly WorkflowJob[];
+    versions: readonly VersionDeclaration[];
+  };
+  /**
+   * What the project takes from the repository root (decision D-109): the root's Node.js version files when it has none
+   * of its own, and the stages of root Dockerfiles that build it; rootPlaces gives them.
+   */
+  root?: RootPlaces;
 }
 /** The bots' delay: the policy's, or longer if a package manager rounded its delay up further. */
 declare function botDuration(policy: Duration, managerMinutes: readonly number[]): Duration;
-/** Computes every change without writing anything. */
-declare function planApply(root: string, policy: ResolvedPolicy, detection: Detection, tools?: readonly ToolKnowledge[]): ApplyReport;
+/**
+ * Computes every change of one directory without writing anything. With projects in the policy, `options` says which
+ * part of the repository this directory is (planRepository plans them all).
+ */
+declare function planApply(root: string, policy: ResolvedPolicy, detection: Detection, tools?: readonly ToolKnowledge[], options?: PlanOptions): ApplyReport;
+/**
+ * Plans the whole repository: the root as planApply does, and each directory listed in projects as a project of its
+ * own with the same policy (decision D-100). Bots are configured only from the root, with a delay at least as long
+ * as any package manager of any project gets. Every path is relative to the root. A listed directory that cannot be
+ * used is an error (`problems`), so that nothing is written; the other directories are still planned, so one run
+ * reports everything.
+ */
+declare function planRepository(root: string, policy: ResolvedPolicy, tools?: readonly ToolKnowledge[], rootDetection?: Detection): ApplyReport;
 declare class PolicyError extends Error {
   readonly issues: string[];
   readonly code: ApplyErrorCode;
   /** What to do, when the message does not say it. */
   readonly fix: string | undefined;
-  constructor(message: string, issues?: string[], code?: ApplyErrorCode, fix?: string);
+  /** The line of the policy file the first problem concerns, when it can be found (decision D-116). */
+  readonly line: number | undefined;
+  constructor(message: string, issues?: string[], code?: ApplyErrorCode, fix?: string, line?: number);
   /** The message and what to do, as one line of text. */
   get text(): string;
 }
@@ -930,18 +1751,8 @@ declare class ApplyWriteError extends Error {
  */
 declare function applyProject(root: string, options?: {
   write?: boolean;
+  beforeWrite?: () => void;
 }): ApplyReport;
-interface DiffOptions {
-  /** Shows the values of secrets as <redacted> in every line (redactSecrets), for a diff that people or logs see. */
-  redact?: boolean;
-}
-/**
- * A unified diff with three lines of context; empty when the texts are equal. `before` is null for a new file.
- * Control characters in the file name are shown as text (printable), so that a name cannot start a line of its own
- * and forge a header or a hunk. A file with an absolute path (a user file outside the home directory) is named as it
- * is, without the a/ and b/ of repository paths.
- */
-declare function unifiedDiff(file: string, before: string | null, after: string, context?: number, options?: DiffOptions): string;
 interface SimilarName {
   /** The popular package the name resembles. */
   match: string;
@@ -985,6 +1796,8 @@ interface PackageReport {
 /** A spec with what the install command changes about the version or the build. */
 interface CheckRequest {
   spec: string;
+  /** The package manager of the command, when a command names one (the hook): its own registry settings apply. */
+  tool?: ToolId;
   /** npm: the dist-tag npm prefers for a name without a version or with a range; the registry's default when left out. */
   tag?: string;
   /** The package manager is not npm, so tag= in .npmrc (CheckOptions.defaultTag) does not choose its version. */
@@ -993,6 +1806,11 @@ interface CheckRequest {
   prereleases?: 'allow' | 'deny';
   /** Python: the package is built from source even when it has wheels (true), or only wheels are used (false). */
   buildFromSource?: boolean;
+  /**
+   * npm: the command line has an option that may set workspaces (--no-workspaces, --workspaces=false), with which npm
+   * reads the .npmrc of a workspace package as its project configuration (decision D-124).
+   */
+  workspacesOption?: boolean;
 }
 interface CheckOptions {
   policy: ResolvedPolicy;
@@ -1013,10 +1831,155 @@ interface CheckOptions {
    * written by the package's publisher and should not reach the model as part of depcurfew's reason.
    */
   scriptBodies?: boolean;
+  /** Stops the lookups: checkSpecs then rejects with the signal's reason (a cancelled call of depcurfew mcp). */
+  signal?: AbortSignal;
+  /** Lookups shared with other checks of the same run (the two policies of the hook), by registry and name. */
+  lookups?: LookupCache;
+  /**
+   * npm packages not to look up: their scope's registry is set in a file depcurfew does not take (decision D-113), so
+   * the name may be private and the public registry may hold a look-alike. The package is reported as unverified.
+   */
+  skipLookup?: (name: string, tool: ToolId | undefined, request?: Omit<CheckRequest, 'spec'>) => boolean;
 }
 declare function checkSpec(request: string | CheckRequest, options: CheckOptions): Promise<PackageReport>;
-/** Checks the specs a few at a time; the reports keep the order of the specs. */
+/**
+ * Checks the specs a few at a time; the reports keep the order of the specs. When `options.signal` aborts, no further
+ * spec is looked up and the promise rejects with the signal's reason.
+ */
 declare function checkSpecs(specs: readonly (string | CheckRequest)[], options: CheckOptions): Promise<PackageReport[]>;
+interface Paint {
+  red(text: string): string;
+  yellow(text: string): string;
+  green(text: string): string;
+  cyan(text: string): string;
+  bold(text: string): string;
+  dim(text: string): string;
+}
+interface CheckDependencies {
+  fetch: FetchLike;
+  now: () => Date;
+  /** The whole of stdin, for hook mode. */
+  stdin: () => Promise<string>;
+  /** The user's home directory, with the user's .npmrc. */
+  home?: () => string;
+  /** The project root Claude Code gives hooks (CLAUDE_PROJECT_DIR); tests replace it. */
+  projectDir?: () => string | undefined;
+  /** --user: platform, home directory and environment variables (tests replace them). */
+  userEnvironment?: () => UserEnvironment;
+  /** depcurfew mcp: the streams the server talks over, its environment and signals (tests replace them). */
+  mcpProcess?: () => McpProcess;
+}
+declare function run(argv: readonly string[], output: CliIo, dependencies?: CheckDependencies): Promise<number>;
+declare function getVersion(): string;
+interface DiffOptions {
+  /** Shows the values of secrets as <redacted> in every line (redactSecrets), for a diff that people or logs see. */
+  redact?: boolean;
+}
+/**
+ * A unified diff with three lines of context; empty when the texts are equal. `before` is null for a new file.
+ * Control characters in the file name are shown as text (printable), so that a name cannot start a line of its own
+ * and forge a header or a hunk. A file with an absolute path (a user file outside the home directory) is named as it
+ * is, without the a/ and b/ of repository paths.
+ */
+declare function unifiedDiff(file: string, before: string | null, after: string, context?: number, options?: DiffOptions): string;
+/**
+ * Where a command runs, relative to the directory the command line starts in: the directories it changes to, in order
+ * (an absolute one starts over). `localPrefix`: npm --prefix names npm's local prefix, whose .npmrc npm reads without
+ * looking for a package.json above it. `entered`: the indexes of the steps that the shell changes to (cd, pushd,
+ * Set-Location), which fail and leave the shell where it was when the directory does not exist, so the hook checks that
+ * it does (decision D-119); a directory that a mkdir earlier on the line creates is left out. `physical`: the indexes of
+ * the steps resolved through symlinks (cd -P, set -P), as the system resolves them. `assumes`: directories the shell
+ * changed to earlier on the line and left again (cd -, popd, cd /path), each of which must exist for this directory to
+ * be right, as a change that fails leaves OLDPWD and the stack of pushd as they were (decision D-123); the hook checks
+ * their entered steps too.
+ */
+interface KnownDirectory {
+  steps: readonly string[];
+  localPrefix?: true;
+  entered?: readonly number[];
+  physical?: readonly number[];
+  assumes?: readonly KnownDirectory[];
+  /**
+   * In `assumes`: a Python virtual environment whose activation script the command runs with . or source, which the
+   * hook trusts not to change directory only when this directory holds pyvenv.cfg (decision D-123).
+   */
+  venv?: true;
+}
+/** A directory as KnownDirectory gives it, or why it cannot be told. */
+type CommandDirectory = KnownDirectory | {
+  unknown: string;
+};
+/** Why a relative directory that the shell finds when it gets to it (pushd -n) cannot be followed, by the variables of the line. */
+interface RelativeDoubt {
+  variables: ShellVariables;
+}
+/**
+ * A change of directory by one command (decision D-123 for the stack): cd; cd - (`back`, with `push` for pushd -);
+ * pushd dir (`keep`: pushd -n, which only puts dir on the stack; no path: Push-Location alone, which pushes the location
+ * without changing it); pushd without a directory (`swap`); pushd +N or -N (`rotate`, `fromRight` for -N); popd with
+ * +N or -N (`count`); dirs -c (`clear`); set -P or set +P (`mode`), which make later changes resolve the path physically
+ * or not. `physical`: cd -P or cd -L chose. `stack`: the stack of pushd is unknown too. `lasting`: the directory of every
+ * later command is unknown, whatever changes it later. `doubt`: the variables of the line, for a directory pushd -n put
+ * on the stack, which the shell finds relative to where it is when it gets to it. `activate`: . or source of the
+ * activation script of the virtual environment in `root`, which changes no directory when `root` holds pyvenv.cfg;
+ * `reason` is why the directory is unknown when it cannot be trusted (decision D-123).
+ */
+type Move = {
+  kind: 'cd';
+  path: string;
+  physical?: boolean;
+} | {
+  kind: 'back';
+  command: string;
+  push?: true;
+} | {
+  kind: 'push';
+  path: string | undefined;
+  keep?: true;
+} | {
+  kind: 'swap';
+  command: string;
+  doubt?: RelativeDoubt;
+} | {
+  kind: 'rotate';
+  command: string;
+  count: number;
+  fromRight: boolean;
+  keep: boolean;
+  doubt?: RelativeDoubt;
+} | {
+  kind: 'pop';
+  command: string;
+  count?: number;
+  fromRight?: boolean;
+  keep?: boolean;
+  doubt?: RelativeDoubt;
+} | {
+  kind: 'clear';
+} | {
+  kind: 'mode';
+  physical: boolean;
+} | {
+  kind: 'unknown';
+  reason: string;
+  stack?: true;
+  lasting?: true;
+} | {
+  kind: 'activate';
+  root: string;
+  reason: string;
+};
+/**
+ * Variables the command line sets that change where cd goes: CDPATH, OLDPWD (cd -), PWD and DIRSTACK (popd).
+ * `dynamic`: why a variable whose name the shell builds may be set, which may be any of them (decision D-123).
+ */
+interface ShellVariables {
+  cdPath: boolean;
+  oldPwd: boolean;
+  pwd: boolean;
+  dirStack: boolean;
+  dynamic?: string;
+}
 interface InstallRequest {
   tool: ToolId;
   /** The command as written, for messages. */
@@ -1028,11 +1991,36 @@ interface InstallRequest {
   prereleases?: 'allow' | 'deny';
   /** Python: the command makes the tool build the package from source (true) or install wheels only (false). */
   buildFromSource?: boolean;
+  /** Where the install runs, when the command changes directory before it or moves it with an option (decision D-118). */
+  directory?: CommandDirectory;
+}
+/** An option or variable of a command that weakens the release-age delay or the rule on install scripts (installOverrides). */
+interface Override {
+  tool: ToolId;
+  /** The command it is on, for messages. */
+  command: string;
+  /** As written: --min-release-age=0, npm_config_ignore_scripts=false. */
+  written: string;
+  weakens: OverrideSwitch['weakens'];
+  /** The delay it sets, to compare with the policy; left out when any value weakens it. */
+  delay?: string;
+  /** The shell expands its value. */
+  expanded?: boolean;
+  /** Where its command runs, when that is not where the command line starts (decision D-118). */
+  directory?: CommandDirectory;
 }
 interface CommandScan {
   requests: InstallRequest[];
   /** Why an install command could not be read; undefined when every one could. */
   unreadable: string | undefined;
+  /** Options and variables that weaken what depcurfew apply configured, to be compared with the policy. */
+  overrides?: Override[];
+  /** A command on the line changes the package manager's configuration; it counts when the line installs packages. */
+  changes?: string;
+  /** A package manager runs on the line, so variables that weaken it count. */
+  manager?: boolean;
+  /** How the command changes the directory of the shell that runs it (cd, pushd, eval 'cd …'), in order. */
+  moves?: Move[];
 }
 interface ScanOptions {
   /** The shell that runs the line: a POSIX shell (the default; also Git Bash) or PowerShell. */
@@ -1045,133 +2033,28 @@ declare function scanCommandLine(line: string, options?: ScanOptions): CommandSc
  * problems with individual files become warnings.
  */
 declare function detectProject(root: string, tools?: readonly ToolKnowledge[], environment?: EnvironmentKnowledge): Detection;
-declare class Repository {
-  #private;
-  readonly root: string;
-  readonly warnings: DetectionWarning[];
-  /** Repository-relative paths of the files that were read, for the log of what doctor checked. */
-  readonly read: Set<string>;
-  constructor(root: string);
-  warn(code: string, message: string, files: readonly string[]): void;
-  isFile(path: string): boolean;
-  /** Whether the path exists in the repository as something other than a regular file or a directory (a named pipe, a socket, a device). */
-  isSpecialFile(path: string): boolean;
-  /** The text of a file, without a byte order mark; undefined (with a warning when useful) if it cannot be read. */
-  readText(path: string, limit?: number): string | undefined;
-  /** The first bytes of a file, e.g. to recognize a lockfile format without reading a large file. */
-  readHead(path: string, bytes?: number): string | undefined;
-  /** Names of the files in a directory (following symlinks only inside the repository). */
-  listFiles(path: string): string[];
-  /** Names of the subdirectories of a directory, skipping node_modules, .git and symlinks that lead outside. */
-  listDirectories(path: string): string[];
-  /** Parses a file with the given parser, reporting failures as warnings. */
-  parse<T>(path: string, parser: (text: string) => T): T | undefined;
-  /** Like parse, but each file is read and parsed once per parser: several rules read the same file. */
-  parseOnce<T>(path: string, parser: (text: string) => T): T | undefined;
-  relative(absolute: string): string;
-}
-/** The SARIF levels: an error fails `doctor`, warnings and notes do not. */
-type Level = 'error' | 'warning' | 'note';
-interface Location {
-  /** Repository-relative path with `/` separators. */
-  file: string;
-  /** 1-based; absent when the finding concerns the whole file. */
-  line?: number;
-  /** doctor --user: the environment variable, as it is set, of a finding whose file is "environment". */
-  variable?: string;
-}
-interface Finding {
-  rule: string;
-  level: Level;
-  message: string;
-  location: Location;
-  /** A fix for this finding; the rule's general help applies when absent. */
-  fix?: string;
-}
-/** Something doctor could not check, such as an unreadable file. Not a problem in the repository itself. */
-interface Notice {
-  message: string;
-  file?: string;
-}
-interface RuleContext {
-  root: string;
-  repository: Repository;
-  detection: Detection;
-  /** undefined when the repository has no depcurfew.json. */
-  policy: ResolvedPolicy | undefined;
-  tools: readonly ToolKnowledge[];
-  report(finding: Omit<Finding, 'rule' | 'level'> & {
-    level?: Level;
-  }): void;
-  notice(message: string, file?: string): void;
-}
-interface Rule {
-  /** Stable kebab-case identifier, used in SARIF and in the documentation. */
-  id: string;
-  /** One sentence: what the rule finds. */
-  summary: string;
-  /** What the rule checks, said as what holds when it passes, for the list of what doctor checked. */
-  checks?: string;
-  /** Why it matters. */
-  description: string;
-  /** How to fix it in general. */
-  help: string;
-  /** Default level of its findings. */
-  level: Level;
-  /** Rules that compare the repository with depcurfew.json do not run without one. */
-  requiresPolicy: boolean;
-  check(context: RuleContext): void;
-}
-/** A package manager or bot doctor checked, with the version it checked against when one is known. */
-interface CheckedTool {
-  id: string;
-  name: string;
-  version?: string;
-  /** Where the version comes from: a repository file, or PATH for doctor --user. */
-  versionFrom?: string;
-}
-/** One check of the list of what doctor checked: a rule and what came of it. */
-interface RuleResult {
-  rule: string;
-  /** What the rule checks, in plain words (Rule.check). */
-  check: string;
-  /** passed: it ran and found nothing; problems: it reported findings; skipped: it needs a policy that is missing or invalid. */
-  result: 'passed' | 'problems' | 'skipped';
-  errors: number;
-  warnings: number;
-  notes: number;
-}
-/** What doctor looked at, shown below the result, so that a clean report says what it covers. */
-interface Checked {
-  tools: CheckedTool[];
-  /** Files that were read, repository-relative (doctor) or as shown (~/.npmrc, doctor --user). */
-  files: string[];
-  /** Every rule, in the order it ran, with its result. */
-  rules: RuleResult[];
-  /** The policy that skipped rules need, as messages show it. */
-  policyFile: string;
-}
-interface DoctorReport {
-  schemaVersion: 1;
-  /** invalid: depcurfew.json does not follow the schema or cannot be read (only with invalidPolicy: 'report'). */
-  policy: 'valid' | 'missing' | 'invalid';
-  findings: Finding[];
-  notices: Notice[];
-  /** What was checked. */
-  checked?: Checked;
-}
 /** Every doctor rule, in the order they are documented. unreadable-config runs last, after every other rule has read its files. */
 declare const RULES: readonly Rule[];
-interface Paint {
-  red(text: string): string;
-  yellow(text: string): string;
-  green(text: string): string;
-  cyan(text: string): string;
-  bold(text: string): string;
-  dim(text: string): string;
+type FailOn = (typeof FAIL_ON_LEVELS)[number];
+/** Where the setting came from: the command line (or the Action input), doctor.failOn of the policy, or neither. */
+type FailOnFrom = 'option' | 'policy' | 'default';
+interface FailOnSetting {
+  failOn: FailOn;
+  from: FailOnFrom;
+  /** from option: the option as given, "--strict" or "--fail-on warning". */
+  option?: string;
+  /** from policy: the policy file as messages show it, e.g. depcurfew.json. */
+  file?: string;
 }
 declare function countLevels(findings: readonly Finding[]): Record<'error' | 'warning' | 'note', number>;
-declare function renderText(report: DoctorReport, rules: readonly Rule[], colors?: Paint): string;
+/**
+ * `failOn`: which findings fail doctor and where that was set (decision D-112); when warnings make it fail, a line under
+ * the counts says why, with how to fail on errors only. `strict` alone (before D-112) adds STRICT_NOTE.
+ */
+declare function renderText(report: DoctorReport, rules: readonly Rule[], colors?: Paint, options?: {
+  strict?: boolean;
+  failOn?: FailOnSetting;
+}): string;
 /** The text of a line in a repository file, to give regions the end column GitHub asks for. */
 type LineReader = (file: string, line: number) => string | undefined;
 /** Why doctor could not run, with a stable code. */
@@ -1184,11 +2067,15 @@ declare function toSarif(report: DoctorReport, rules: readonly Rule[], version:
 /**
  * Runs the rules on a repository. When depcurfew.json exists but is invalid, it throws PolicyError, or with
  * invalidPolicy: 'report' runs the rules that need no policy and reports the problems as an invalid-policy finding.
+ * `policy` passes the policy in instead of reading depcurfew.json (null: run as without one). With projects in the
+ * policy, the rules also run on every listed directory with the same policy, and the report covers them all, with
+ * paths relative to the root (decision D-100).
  */
 declare function runDoctor(root: string, options?: {
   rules?: readonly Rule[];
   tools?: readonly ToolKnowledge[];
   invalidPolicy?: 'throw' | 'report';
+  policy?: ResolvedPolicy | null;
 }): DoctorReport;
 type NumericDelayUnit = Exclude<DelayUnit, 'duration-string'>;
 declare const DURATION_STRING_UNITS: readonly ["minutes", "hours", "days", "weeks"];
@@ -1242,6 +2129,9 @@ declare const DEFAULT_POLICY: {
     readonly directory: "allow";
   };
   readonly targets: "auto";
+  readonly doctor: {
+    readonly failOn: "warning";
+  };
 };
 declare function renderPolicy(policy: Policy): string;
 type PolicyIssue = Issue;
@@ -1257,4 +2147,4 @@ declare function validatePolicy(document: unknown, tools?: readonly ToolKnowledg
 /** Parses and validates the text of a policy file. */
 declare function parsePolicy(source: string, tools?: readonly ToolKnowledge[]): PolicyResult;
 declare function formatIssue(issue: PolicyIssue): string;
-export { APPLY_ERRORS, APPLY_WARNINGS, type ApplyErrorCode, type ApplyReport, type ApplyWarning, type ApplyWarningCode, ApplyWriteError, type CheckFinding, type CheckOptions, type CliIo, type CommandScan, type Converted, type CooldownConversion, DEFAULT_POLICY, type Detection, type DetectionWarning, type DoctorReport, type Duration, type DurationResult, type DurationStringUnit, EXIT_FAILURE, EXIT_OK, EXIT_USAGE, type FileChange, type Finding, type FindingCode, type InstallRequest, type Level, type Location, type Notice, type NumericDelayUnit, POLICY_FILE, type PackageManagerInfo, type PackageReport, type Policy, PolicyError, type PolicyIssue, type PolicyResult, PopularNames, RULES, type ResolvedPolicy, type Rule, SCHEMA_URL, type ScanOptions, type Snippet, type VersionDeclaration, applyProject, botDuration, checkSpec, checkSpecs, convertCooldown, convertMinutes, countLevels, detectProject, formatDuration, formatIssue, getVersion, loadPolicy, parseDuration, parsePolicy, planApply, renderPolicy, renderText, run, runDoctor, scanCommandLine, toDurationString, toSarif, unifiedDiff, validatePolicy, warningText };
+export { APPLY_ERRORS, APPLY_WARNINGS, type ApplyErrorCode, type ApplyProblem, type ApplyReport, type ApplyWarning, type ApplyWarningCode, ApplyWriteError, type CheckFinding, type CheckOptions, type CliIo, type CommandDirectory, type CommandScan, type Converted, type CooldownConversion, DEFAULT_POLICY, type Detection, type DetectionWarning, type DoctorReport, type Duration, type DurationResult, type DurationStringUnit, EXIT_FAILURE, EXIT_OK, EXIT_USAGE, type FileChange, type Finding, type FindingCode, type InstallRequest, type KnownDirectory, type Level, type Location, type Notice, type NumericDelayUnit, POLICY_FILE, type PackageManagerInfo, type PackageReport, type PlanOptions, type Policy, PolicyError, type PolicyIssue, type PolicyResult, PopularNames, type ProjectProblem, RULES, type ResolvedPolicy, type Rule, SCHEMA_URL, type ScanOptions, type Snippet, type VersionDeclaration, applyProject, botDuration, checkSpec, checkSpecs, convertCooldown, convertMinutes, countLevels, detectProject, formatDuration, formatIssue, getVersion, loadPolicy, parseDuration, parsePolicy, planApply, planRepository, renderPolicy, renderText, run, runDoctor, scanCommandLine, toDurationString, toSarif, unifiedDiff, validatePolicy, warningText };