depcurfew 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -1,19 +1,7 @@
-declare const EXIT_OK = 0;
-declare const EXIT_FAILURE = 1;
-declare const EXIT_USAGE = 2;
-interface CliIo {
-  stdout(text: string): void;
-  stderr(text: string): void;
-  /** Whether each stream may be colored (see color.ts); absent means plain text. */
-  colors?: {
-    stdout: boolean;
-    stderr: boolean;
-  };
-}
-declare function run(argv: readonly string[], output: CliIo): Promise<number>;
-declare function getVersion(): string;
-type ToolId = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'deno' | 'renovate' | 'dependabot';
+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. */
+type Ecosystem = 'npm' | 'pypi';
 interface Evidence$1<T> {
   value: T;
   /** URL of official documentation or changelog. */
@@ -95,6 +83,8 @@ interface SourcesKnowledge {
 interface WorkspaceDeclaration {
   files: readonly string[];
   key: string;
+  /** Key of a list of patterns that exclude packages, next to the package list; such patterns win. */
+  excludeKey?: string;
 }
 /** Facts for recognising a package manager in a repository. */
 interface ProjectKnowledge {
@@ -102,25 +92,127 @@ interface ProjectKnowledge {
   lockfiles: Fact<Versioned<readonly string[]>>;
   /** Files that make a directory a project or a workspace package for this tool. */
   manifests: Fact<readonly string[]>;
-  workspaces: Fact<WorkspaceDeclaration>;
+  /** `null` when the tool has no workspaces. In TOML files the key is a dotted path to a table. */
+  workspaces: Fact<WorkspaceDeclaration | null>;
   /** Key of the package list when the workspace declaration is an object instead of a list; `null` if only lists are accepted. */
   workspacesObjectKey: Fact<string | null>;
 }
+/** A platform family for user-level paths. */
+type UserPlatform = 'linux' | 'darwin' | 'win32';
+/** A base directory for a user-level file. */
+interface UserDirectory {
+  /**
+   * Where it starts: an environment variable (used only when it is set and not empty, and with `absolute` only when
+   * it is an absolute path), or the home directory (HOME on Linux and macOS, USERPROFILE on Windows). With
+   * `relativeToCwd` the tool takes a relative value as it is, so it reads the file relative to the directory each
+   * command runs in; without it and without `absolute`, what the tool does with a relative value is not known.
+   */
+  from: {
+    env: string;
+    absolute?: boolean;
+    relativeToCwd?: boolean;
+  } | 'home';
+  /** Path below it, with / separators; empty for the directory itself. */
+  path: string;
+  /** Use this directory only when it already exists (pip on macOS). */
+  ifExists?: boolean;
+  /** Skip this directory while this environment variable is set and not empty (pip 26.2+ on macOS and XDG_DATA_HOME). */
+  unlessEnv?: string;
+}
+/** Where the user file is on some platforms: the first directory that applies is used. */
+interface UserLocation {
+  platforms: readonly UserPlatform[];
+  directories: readonly UserDirectory[];
+  file: string;
+}
+/** The user-level configuration file of a range of versions. */
+interface UserFile {
+  format: 'ini' | 'yaml' | 'toml';
+  locations: readonly UserLocation[];
+  /** INI only: the [sections] whose keys the tool reads, '' for the keys above the first header; absent: every key. */
+  sections?: readonly string[];
+  /** Other user-level files this version reads the same settings from, whose keys win over this file's. */
+  overriddenBy?: readonly UserFile[];
+  /** INI only: the tool reads a key with underscores as the same key with dashes (pip: only_binary is only-binary). */
+  underscoresAsDashes?: boolean;
+  /** YAML only: the tool's loader applies merge keys (<<: *defaults), so merged keys count as keys of the map. */
+  mergeKeys?: boolean;
+}
+/** What depcurfew writes with a user-level setting. */
+type UserSettingPurpose = 'cooldown' | 'cooldownExclude' | 'cooldownStrict' | 'scriptsAllow' | 'scriptsStrict' | 'buildsDeny' | 'buildsAllow' | 'sourceGit' | 'sourceRemote' | 'sourceFile' | 'sourceDirectory' | 'sourcesExotic';
+/** A setting the tool reads from its user file: the key there and the versions that read it from that file. */
+interface UserSetting {
+  purpose: UserSettingPurpose;
+  key: string;
+  since: string;
+  /** First version that no longer reads it from the user file. */
+  until?: string;
+}
+/**
+ * The values of a switch that turns a protection off, given by the values the tool reads as off: every other value
+ * turns it on (fail closed), so a string "false" or "yes" that the tool takes for true is not missed. In INI files and
+ * environment variables values are compared as text after trimming, elsewhere with their type (false, 0, null, "").
+ */
+interface UnlessOff<T> {
+  except: readonly T[];
+}
+/** A value in the user file that weakens every project that does not set the key itself (doctor --user). */
+interface UserWeakening {
+  key: string;
+  /** 'any' for every value, the values that weaken, or every value except those the tool reads as off. */
+  values: 'any' | readonly (string | number | boolean)[] | UnlessOff<string | number | boolean | null>;
+  /** What it does, for the message. */
+  effect: string;
+}
+/** An environment variable that bypasses or overrides the user file or the policy (doctor --user). */
+interface UserVariable {
+  /** The variable name; matched without regard to case when `anyCase`. */
+  name: string;
+  anyCase?: boolean;
+  /** 'any' when every value matters, the values that weaken, or every value except those the tool reads as off. */
+  values: 'any' | readonly string[] | UnlessOff<string>;
+  effect: string;
+  /** First version that reads the variable; every version when absent. */
+  since?: string;
+  /** First version that no longer reads it. */
+  until?: string;
+  /** The file the tool reads when the variable is unset, from the home directory (~/.npmrc): naming it changes nothing. */
+  defaultPath?: string;
+}
+/** 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>>;
+  /** 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. */
+  unknownKeys: Fact<'ignore' | 'warn' | 'fail'>;
+  /** Whether a value the installed version cannot parse makes every command fail; depcurfew then needs the exact version. */
+  invalidValueFails: Fact<boolean>;
+  /** Values in the user file that weaken projects. */
+  weakening: Fact<readonly UserWeakening[]>;
+  /** Environment variables that move or skip the user file or override settings. */
+  variables: Fact<readonly UserVariable[]>;
+}
 interface ToolKnowledge {
   id: ToolId;
   name: string;
   kind: ToolKind;
+  /** Package managers only; `npm` when absent. */
+  ecosystem?: Ecosystem;
   cooldown: CooldownKnowledge;
   installScripts: InstallScriptsKnowledge;
   /** Package managers only: bots do not resolve dependency sources themselves. */
   sources?: SourcesKnowledge;
-  /** Package managers only: how to recognise the tool in a repository. */
+  /** Package managers only: how to recognize the tool in a repository. */
   project?: ProjectKnowledge;
+  /** Package managers only: the user-level configuration (`--user`). */
+  user?: UserConfigKnowledge;
   /** Further sourced facts that matter for generators and `doctor`, keyed by a short name. */
   extra?: Readonly<Record<string, Fact<unknown>>>;
 }
-/** A tool that environment facts refer to: Node.js or a package manager. */
-type RuntimeOrTool = 'node' | ToolId;
+/** A tool that environment facts refer to: Node.js, Python or a package manager. */
+type RuntimeOrTool = 'node' | 'python' | ToolId;
 interface PackageManagerFieldKnowledge {
   /** Key in package.json, e.g. `packageManager`. */
   key: string;
@@ -174,6 +266,122 @@ interface StopCommandsKnowledge {
   stop: string;
   resume: string;
 }
+/** The public npm registry, as depcurfew check reads it. */
+interface NpmRegistryKnowledge {
+  url: string;
+  /** Path of a package document; scoped names have their slash escaped as %2f. */
+  packagePath: string;
+  /** Field of the full document that maps versions to publish times; the abbreviated install document lacks it. */
+  timeField: string;
+  /** Field of the document that maps tags (latest, next) to versions. */
+  distTagsField: string;
+  /** The tag every package has, which a spec without a version installs. */
+  defaultTag: string;
+  /** Field of the document that maps versions to their version objects. */
+  versionsField: string;
+  /** Field of a version object with the lifecycle scripts of its package.json. */
+  scriptsField: string;
+  /** Field of a version object that holds the deprecation message. */
+  deprecatedField: string;
+  /** Lifecycle scripts a package runs when it is installed as a dependency. */
+  installScripts: readonly string[];
+}
+/** How the Python interpreter runs a module (python -m pip) or a command string. */
+interface PythonInterpreterKnowledge {
+  /** Executable names; versioned names such as python3.12 are the same. */
+  executables: readonly string[];
+  /** Runs the named module as a script; the options end there. */
+  moduleOption: string;
+  /** Runs a command string; the options end there. */
+  commandOption: string;
+  /** Other options followed by a separate value. */
+  valueOptions: readonly string[];
+  /**
+   * One-letter options may be grouped after one dash (-Im pip): flags, then perhaps an option with a value, which is
+   * the rest of the word or the next word.
+   */
+  groupedShortOptions: boolean;
+}
+/** The JSON form of the simple repository API of a Python package index (PEP 691, PEP 700, PEP 792). */
+interface PypiIndexKnowledge {
+  /** Base URL; a project's page is the normalized name followed by a slash. */
+  url: string;
+  /** Accept header that asks for the JSON form. */
+  accept: string;
+  /** Status of a project the index does not know. */
+  notFoundStatus: number;
+  /** Key of the list of distribution files, and the keys of a file. */
+  filesField: string;
+  filenameField: string;
+  /** ISO 8601 upload time in UTC; optional, since API version 1.1. */
+  uploadTimeField: string;
+  /** true or a reason string when the file is yanked. */
+  yankedField: string;
+  /** Key of the list of all versions of the project, since API version 1.1. */
+  versionsField: string;
+  /** Key of the project status object, its status and its reason, since API version 1.4. */
+  statusField: string;
+  statusValueField: string;
+  statusReasonField: string;
+}
+/** Project status markers (PEP 792): which mean that no file may be downloaded, and which installers may warn about. */
+interface ProjectStatusKnowledge {
+  /** The index offers no file of the project. */
+  blocked: readonly string[];
+  /** Installers may warn about the project. */
+  warned: readonly string[];
+}
+/** Claude Code hooks that run before a tool call and can block it (used by depcurfew check --hook claude-code). */
+interface ClaudeCodeHooksKnowledge {
+  /** Project settings file that can be committed. */
+  settingsFile: string;
+  event: string;
+  /** Separates the tool names of a matcher that lists several, each matched exactly. */
+  matcherSeparator: string;
+  /** Fields of the JSON a command hook reads on stdin. */
+  input: {
+    event: string;
+    tool: string;
+    command: string;
+    cwd: string;
+  };
+  /** Fields of the JSON object a hook prints to decide. */
+  output: {
+    container: string;
+    event: string;
+    decision: string;
+    reason: string;
+  };
+  decisions: {
+    deny: string;
+    ask: string;
+  };
+  /** A command hook that exits with this code blocks the call; stderr is the reason. */
+  blockingExitCode: number;
+  /** The handler field that blocks the call when the hook fails or times out, and the version that has it. */
+  onFailure: {
+    field: string;
+    value: string;
+    since: string;
+  };
+  /** Placeholder for the project root in a hook command. */
+  projectDir: string;
+  /** Keys of a settings file: the hooks map, a matcher group and a command handler run without a shell. */
+  settings: {
+    hooks: string;
+    matcher: string;
+    handlers: string;
+    type: string;
+    commandType: string;
+    command: string;
+    args: string;
+  };
+}
+/** 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';
+}
 /**
  * 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`.
@@ -198,10 +406,56 @@ interface AnnotationLimitsKnowledge {
   perJob: number;
 }
 /** 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;
+  apiVersion: string;
+  /** The workflow permission the token needs. */
+  permission: Record<string, string>;
+  /** Limit of output.summary, in characters. */
+  summaryMaxLength: number;
+  /** Variables the runner sets: API URL, owner/name, commit and the event payload file. */
+  variables: {
+    apiUrl: string;
+    repository: string;
+    sha: string;
+    eventPath: string;
+  };
+  /** Path in the event payload of the commit a pull request check belongs to (GITHUB_SHA is the merge commit there). */
+  pullRequestHeadSha: readonly string[];
+}
 interface StepSummaryKnowledge {
   variable: string;
   maxBytes: number;
 }
+interface GitIgnoreKnowledge {
+  /** The per-directory pattern file, e.g. .gitignore. */
+  file: string;
+  /** The repository's own pattern file, relative to the working tree. */
+  excludeFile: string;
+  /** The index, whose entries are the tracked files. */
+  indexFile: string;
+  /** Whether a pattern also hides a file git already tracks (it does not). */
+  trackedFilesIgnored: boolean;
+}
+/** npm's shims for the programs of packages on Windows. */
+interface CommandShimsKnowledge {
+  /** The files written next to each program (besides a sh script). */
+  extensions: readonly string[];
+  /** The shim cmd.exe runs, which passes its arguments on with `argumentsVariable`, so they are read once more. */
+  batchExtension: string;
+  argumentsVariable: string;
+}
+/** The git setting that makes .gitignore patterns and index lookups ignore case. */
+interface GitIgnoreCaseKnowledge {
+  /** The repository's configuration file, relative to the working tree. */
+  configFile: string;
+  section: string;
+  key: string;
+  /** Values read as true (case-insensitive); a key without a value is true too. */
+  trueValues: readonly string[];
+}
 interface EnvironmentKnowledge {
   corepack: {
     packageManagerField: Fact<PackageManagerFieldKnowledge>;
@@ -228,14 +482,72 @@ interface EnvironmentKnowledge {
     pnpmSetup: Fact<SetupActionKnowledge>;
     setupBun: Fact<SetupActionKnowledge>;
     setupDeno: Fact<SetupActionKnowledge>;
+    setupPython: Fact<SetupActionKnowledge>;
+    setupUv: Fact<SetupActionKnowledge>;
+    /** Third-party actions that install Poetry; Poetry has no official action. */
+    installPoetry: Fact<SetupActionKnowledge>;
+    actionsPoetry: Fact<SetupActionKnowledge>;
     codeScanningUpload: Fact<CodeScanningUploadKnowledge>;
     stopCommands: Fact<StopCommandsKnowledge>;
     annotations: Fact<AnnotationsKnowledge>;
     annotationLimits: Fact<AnnotationLimitsKnowledge>;
     stepSummary: Fact<StepSummaryKnowledge>;
+    checkRuns: Fact<CheckRunsKnowledge>;
+  };
+  npmRegistry: {
+    api: Fact<NpmRegistryKnowledge>;
+    notFoundStatus: Fact<number>;
+    /** Search endpoint, its result limit and the field with weekly downloads. */
+    search: Fact<{
+      path: string;
+      maxSize: number;
+      weeklyDownloadsField: string;
+    }>;
+  };
+  pypiIndex: {
+    api: Fact<PypiIndexKnowledge>;
+    projectStatus: Fact<ProjectStatusKnowledge>;
+  };
+  claudeCode: {
+    hooks: Fact<ClaudeCodeHooksKnowledge>;
+    /** The tools whose PreToolUse events carry a shell command in the hooks fact's input.command. */
+    shellTools: Fact<readonly ClaudeCodeShellTool[]>;
+  };
+  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>;
+  };
+  windows: {
+    commandShims: Fact<CommandShimsKnowledge>;
+    /** Files whose arguments PowerShell hands to cmd.exe as a raw command line. */
+    batchArguments: Fact<{
+      extensions: readonly string[];
+    }>;
+  };
+  python: {
+    /** How Python package names are compared: lowercased, with every run of these characters replaced by `replacement`. */
+    nameNormalization: Fact<{
+      separators: string;
+      replacement: string;
+    }>;
+    /** Python package names: ASCII letters and digits, `.`, `_` and `-`, starting and ending with a letter or digit. */
+    namePattern: Fact<string>;
+    /** The project file of a Python project, whose [tool.<name>] tables hold tool settings. */
+    projectFile: Fact<string>;
+    /** The file extension of a wheel, a built distribution that installs without running package code. */
+    wheelExtension: Fact<string>;
+    /** File extensions of source distributions on an index, which are built when installed. */
+    sourceDistributionExtensions: Fact<readonly string[]>;
+    interpreter: Fact<PythonInterpreterKnowledge>;
+    /** Hatch, which has no supply-chain settings of its own: how a project shows it uses Hatch. */
+    hatch: Fact<{
+      pyprojectTable: string;
+      configFile: string;
+    }>;
   };
 }
-type PackageManagerId = Extract<ToolId, 'npm' | 'pnpm' | 'yarn' | 'bun' | 'deno'>;
+type PackageManagerId = Extract<ToolId, 'npm' | 'pnpm' | 'yarn' | 'bun' | 'deno' | 'uv' | 'pip' | 'poetry' | 'pdm' | 'pipenv'>;
 type BotId = Extract<ToolId, 'renovate' | 'dependabot'>;
 /** Why a package manager is considered in use. Ordered from the strongest signal. */
 type EvidenceKind = 'lockfile' | 'packageManager' | 'devEngines' | 'config' | 'ci' | 'default';
@@ -244,7 +556,8 @@ interface Evidence {
   /** Repository-relative path with `/` separators. */
   file: string;
 }
-type VersionSource = 'packageManager' | 'devEngines' | 'volta' | 'tool-versions' | 'github-actions';
+/** 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). */
 type VersionDeclaration = ({
   version: string;
@@ -296,6 +609,50 @@ interface Detection {
   workflows: string[];
   warnings: DetectionWarning[];
 }
+interface UserEnvironment {
+  platform: NodeJS.Platform;
+  /** HOME on Linux and macOS, USERPROFILE on Windows: what os.homedir() returns. */
+  home: string;
+  env: Readonly<Record<string, string | undefined>>;
+  /** The current directory, against which a tool resolves a relative XDG_CONFIG_HOME (relativeToCwd); process.cwd() by default. */
+  cwd?: string;
+  /** Whether a directory exists; replaceable in tests. */
+  isDirectory?: (path: string) => boolean;
+}
+type FetchLike = (url: string, init: {
+  headers: Record<string, string>;
+  signal: AbortSignal;
+  redirect?: 'manual';
+}) => Promise<Response>;
+declare const EXIT_OK = 0;
+declare const EXIT_FAILURE = 1;
+declare const EXIT_USAGE = 2;
+interface CliIo {
+  stdout(text: string): void;
+  stderr(text: string): void;
+  /** Whether each stream may be colored (see color.ts); absent means plain text. */
+  colors?: {
+    stdout: boolean;
+    stderr: boolean;
+  };
+  /** Whether each stream is a terminal; absent means it is not. */
+  terminal?: {
+    stdout: boolean;
+    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;
+}
+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;
@@ -366,6 +723,7 @@ declare const policyShape: Shape<{
   installScripts?: {
     default: "allow" | "deny";
     allow?: readonly string[];
+    deny?: readonly string[];
   };
   sources?: {
     git?: "allow" | "deny";
@@ -386,6 +744,7 @@ declare const policyShape: Shape<{
   installScripts?: {
     default: "allow" | "deny";
     allow: readonly string[];
+    deny: readonly string[];
   };
   sources?: {
     git?: "allow" | "deny";
@@ -398,6 +757,82 @@ declare const policyShape: Shape<{
 type Policy = Input<typeof policyShape>;
 /** The policy after validation: defaults filled in, durations parsed. */
 type ResolvedPolicy = Output<typeof policyShape>;
+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 '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.";
+  readonly 'version-unknown': "apply --user: the installed version of a tool cannot be read from its files, and a value it does not understand would stop every command, so nothing is written for it.";
+  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-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.";
+  readonly 'cooldown-shortened': "A release-age delay set outside depcurfew's markers (in JSON files also one an earlier apply wrote) is longer than the policy, and apply replaces it with the shorter one.";
+  readonly 'cooldown-environment-only': "pip reads no project configuration, so the release-age delay has to be set in the environment where pip runs.";
+  readonly 'exclude-pattern-unsupported': "A cooldown exception uses a wildcard the tool does not support, so it is not written.";
+  readonly 'exclude-unsupported': "The tool has no setting for cooldown exceptions, so the release-age delay applies to every package.";
+  readonly 'allow-pattern-unsupported': "An installScripts.allow entry is a pattern, but the tool takes package names only, so it is not written.";
+  readonly 'deny-pattern-unsupported': "An installScripts.deny entry is a pattern, but the tool records denials by package name only, so it is not written.";
+  readonly 'allow-all-unsupported': "The tool has no setting that allows every install script, so installScripts \"allow\" is not written.";
+  readonly 'allow-all-replaced': "A setting that allowed every install script (with any value the tool reads as true, also one that a YAML merge key brings in, or pnpm 10's dangerously-allow-all-builds in .npmrc) was set to false, because the policy denies install scripts.";
+  readonly 'allow-list-entry-outside-policy': "An install-script allow-list in the repository (with apply --user, in a user file) lets a package run scripts the policy does not allow; apply does not remove it.";
+  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 '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.";
+  readonly 'source-switch-indirect-only': "The pnpm setting for git and tarball sources stops them only for indirect dependencies.";
+  readonly 'source-switch-combined': "One pnpm setting covers git and tarball sources, so denying one denies both.";
+  readonly 'forced-source-build': "Python packages on the allow-list are always built from source, because no tool can only allow a build.";
+  readonly 'build-switch-scope': "The tool's switch forbids building only packages from an index; git, local and archive dependencies are still built.";
+  readonly 'build-switch-install-only': "Poetry applies its build switch when installing; poetry lock may still build source distributions.";
+  readonly 'build-switch-environment-only': "The tool has no project setting that forbids building from source, so it has to be set in the environment where the tool runs.";
+  readonly 'requirements-file-missing': "There is no requirements file to write pip options into.";
+  readonly 'manifest-missing': "A setting belongs in a project manifest (package.json, deno.json, pyproject.toml, Pipfile) that does not exist, and apply does not create manifests.";
+  readonly 'lockfile-out-of-date': "The lockfile records, or is checked against, a setting apply changed, so it has to be locked again.";
+  readonly 'file-ignored-by-git': "A file apply writes matches a .gitignore rule, so the change may never reach the repository.";
+  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 'security-delay-unsupported': "Dependabot cannot delay security updates, so securityUpdates \"delay\" is not applied.";
+};
+declare const APPLY_ERRORS: {
+  readonly 'cannot-edit': "A file cannot be read or edited safely (invalid syntax, a symlink, a style depcurfew does not edit), so nothing is written.";
+  readonly 'cannot-write': "A file cannot be written (no permission, a read-only file system, a full disk, a directory or symlink in its place); the files already written are put back, so nothing changes.";
+  readonly 'policy-missing': "The directory has no depcurfew.json.";
+  readonly 'policy-invalid': "depcurfew.json does not follow the schema; issues lists the problems.";
+  readonly 'policy-unreadable': "depcurfew.json cannot be read.";
+  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 '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 tool it concerns, when there is one. */
+  tool?: ToolId;
+  /** The file it concerns, when there is one, and the line when it is known. */
+  location?: {
+    file: string;
+    line?: number;
+  };
+  /** What happened, for people; it starts with the tool's name when it concerns one. */
+  message: string;
+  /** What to do about it, when there is something to do. */
+  fix?: string;
+}
+/** A warning as one line of text, as ApplyReport.warnings has it. */
+declare function warningText(warning: ApplyWarning): string;
 interface FileChange {
   /** Repository-relative path with `/` separators. */
   file: string;
@@ -405,6 +840,30 @@ interface FileChange {
   before: string | null;
   after: string;
 }
+/**
+ * A file could not be written. writeChanges has removed its temporary files and put back the files it had already
+ * replaced, so nothing changed, except for the files in `unrestored` (whose earlier text is in `backups` when it could
+ * be written) and the temporary files in `leftovers`. The message says why, without the file name.
+ */
+declare class WriteFailed extends Error {
+  readonly file: string;
+  /** Why, in plain words. */
+  readonly reason: string;
+  /** Files already replaced that could not be put back (normally none). */
+  readonly unrestored: string[];
+  /** For files in `unrestored`: the temporary file, next to it, that holds its earlier text. */
+  readonly backups: Readonly<Record<string, string>>;
+  /** Temporary files that could not be removed, named like `file` (relative to the root, or as WriteOptions.name says). */
+  readonly leftovers: string[];
+  /** Another program holds the file, or (on Windows) it is read-only. */
+  readonly busy: boolean;
+  readonly platform: NodeJS.Platform;
+  constructor(file: string, error: unknown, unrestored: string[], details?: {
+    platform?: NodeJS.Platform;
+    backups?: Record<string, string>;
+    leftovers?: string[];
+  });
+}
 interface Snippet {
   tool: ToolId;
   file: string;
@@ -418,7 +877,10 @@ interface EditFailure {
 }
 interface ApplyReport {
   changes: FileChange[];
+  /** The warnings as one line of text each. */
   warnings: string[];
+  /** The same warnings with a code, the tool, the file and what to do (apply --json). */
+  warningDetails: ApplyWarning[];
   snippets: Snippet[];
   /** Files that could not be edited, as messages. When there are any, nothing is written. */
   errors: string[];
@@ -431,18 +893,153 @@ declare function botDuration(policy: Duration, managerMinutes: readonly number[]
 declare function planApply(root: string, policy: ResolvedPolicy, detection: Detection, tools?: readonly ToolKnowledge[]): ApplyReport;
 declare class PolicyError extends Error {
   readonly issues: string[];
-  constructor(message: string, 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 message and what to do, as one line of text. */
+  get text(): string;
 }
 declare function loadPolicy(root: string): ResolvedPolicy;
+/**
+ * A file could not be written (code cannot-write). The files apply had already replaced were put back, so the
+ * repository is as it was, unless `unrestored` lists files. `report` is the plan that was being written.
+ */
+declare class ApplyWriteError extends Error {
+  readonly code: "cannot-write";
+  /** The file that could not be written, relative to the repository. */
+  readonly file: string;
+  /** What to do. */
+  readonly fix: string;
+  /** Files already replaced that could not be put back (normally none). */
+  readonly unrestored: string[];
+  readonly report: ApplyReport;
+  /**
+   * `command` is what the fix tells the user to run again (depcurfew apply --user for user files), and
+   * `versionControl` whether the files may be in version control, to restore them from.
+   */
+  constructor(failure: WriteFailed, report: ApplyReport, options?: {
+    command?: string;
+    versionControl?: boolean;
+  });
+}
 /**
  * Reads the policy, detects the project, plans the changes and (unless told otherwise) writes them. If any file
  * could not be edited, nothing is written, so a run either applies the whole policy or leaves the repository as it was.
+ * A file that cannot be written throws ApplyWriteError after the files already written are put back.
  */
 declare function applyProject(root: string, options?: {
   write?: boolean;
 }): ApplyReport;
-/** A unified diff with three lines of context; empty when the texts are equal. `before` is null for a new file. */
-declare function unifiedDiff(file: string, before: string | null, after: string, context?: number): 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;
+interface SimilarName {
+  /** The popular package the name resembles. */
+  match: string;
+  /** edit: a letter or two differ; separators: only -, _ or . differ. */
+  reason: 'edit' | 'separators';
+}
+declare class PopularNames {
+  #private;
+  constructor(names: readonly string[]);
+  has(name: string): boolean;
+  /** The popular package `name` resembles, or undefined (also when `name` is itself popular). */
+  similar(name: string): SimilarName | undefined;
+}
+type SpecKind = 'registry' | 'git' | 'remoteTarball' | 'file' | 'directory' | 'workspace' | 'other';
+type FindingCode = 'invalid-spec' | 'forbidden-source' | 'unchecked-source' | 'unverified' | 'not-found' | 'no-version' | 'too-young' | 'install-scripts' | 'similar-name' | 'deprecated' | 'yanked' | 'archived' | 'quarantined' | 'insecure-registry';
+interface CheckFinding {
+  level: 'error' | 'warning';
+  code: FindingCode;
+  message: string;
+  /** What to do about it. */
+  fix: string;
+}
+interface PackageReport {
+  spec: string;
+  kind: SpecKind | 'invalid';
+  name?: string;
+  version?: string;
+  publishedAt?: string;
+  latest?: {
+    version: string;
+    publishedAt?: string;
+  };
+  /** npm: the dist-tag the version was picked by, when it is not the default one (--tag, npm_config_tag, tag in .npmrc). */
+  tag?: string;
+  /** Python: pre-releases allowed or forbidden by the command. */
+  prereleases?: 'allow' | 'deny';
+  /** Python: the command builds the package from source (true) or installs wheels only (false). */
+  buildFromSource?: boolean;
+  findings: CheckFinding[];
+}
+/** A spec with what the install command changes about the version or the build. */
+interface CheckRequest {
+  spec: string;
+  /** 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. */
+  ignoresConfigTag?: boolean;
+  /** Python: pre-releases allowed or forbidden; PEP 440's default when left out. */
+  prereleases?: 'allow' | 'deny';
+  /** Python: the package is built from source even when it has wheels (true), or only wheels are used (false). */
+  buildFromSource?: boolean;
+}
+interface CheckOptions {
+  policy: ResolvedPolicy;
+  fetch: FetchLike;
+  now: Date;
+  registry: string;
+  popular: PopularNames;
+  /** Registries the project assigns to scopes (@scope:registry in .npmrc); those packages are not looked up. */
+  scopeRegistries?: ReadonlyMap<string, string>;
+  /** The Python package index pypi: packages are looked up in; PyPI when not given. */
+  index?: string;
+  /** Popular Python projects, by normalized name, for look-alike names. */
+  popularPython?: PopularNames;
+  /** npm: the dist-tag npm prefers when a request names none (tag in .npmrc); the registry's default when left out. */
+  defaultTag?: string;
+  /**
+   * Whether a finding about install scripts quotes them (the default) or names them only, for the hook: their body is
+   * written by the package's publisher and should not reach the model as part of depcurfew's reason.
+   */
+  scriptBodies?: 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. */
+declare function checkSpecs(specs: readonly (string | CheckRequest)[], options: CheckOptions): Promise<PackageReport[]>;
+interface InstallRequest {
+  tool: ToolId;
+  /** The command as written, for messages. */
+  command: string;
+  spec: string;
+  /** npm: the dist-tag the command makes npm prefer (--tag, npm_config_tag). */
+  tag?: string;
+  /** Python: the command allows pre-releases of the package, or forbids them; left out, the tool's default applies. */
+  prereleases?: 'allow' | 'deny';
+  /** Python: the command makes the tool build the package from source (true) or install wheels only (false). */
+  buildFromSource?: boolean;
+}
+interface CommandScan {
+  requests: InstallRequest[];
+  /** Why an install command could not be read; undefined when every one could. */
+  unreadable: string | undefined;
+}
+interface ScanOptions {
+  /** The shell that runs the line: a POSIX shell (the default; also Git Bash) or PowerShell. */
+  shell?: 'posix' | 'powershell';
+}
+/** The packages a command line installs or downloads to run with npm, pnpm, Yarn, Bun, Deno, pip, uv, Poetry, PDM, Pipenv or pipx. */
+declare function scanCommandLine(line: string, options?: ScanOptions): CommandScan;
 /**
  * Describes the repository at `root`. Never executes anything from the repository and never leaves it;
  * problems with individual files become warnings.
@@ -452,9 +1049,13 @@ 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. */
@@ -465,6 +1066,8 @@ declare class Repository {
   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. */
@@ -474,6 +1077,8 @@ interface Location {
   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;
@@ -505,6 +1110,8 @@ interface Rule {
   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. */
@@ -515,11 +1122,43 @@ interface Rule {
   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;
-  policy: 'valid' | 'missing';
+  /** 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[];
@@ -535,11 +1174,21 @@ declare function countLevels(findings: readonly Finding[]): Record<'error' | 'wa
 declare function renderText(report: DoctorReport, rules: readonly Rule[], colors?: Paint): 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;
-declare function toSarif(report: DoctorReport, rules: readonly Rule[], version: string, readLine?: LineReader): object;
-/** Runs the rules on a repository. Throws PolicyError when depcurfew.json exists but is invalid. */
+/** Why doctor could not run, with a stable code. */
+interface SarifError {
+  code: string;
+  message: string;
+  fix?: string;
+}
+declare function toSarif(report: DoctorReport, rules: readonly Rule[], version: string, readLine?: LineReader, errors?: readonly SarifError[]): object;
+/**
+ * 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.
+ */
 declare function runDoctor(root: string, options?: {
   rules?: readonly Rule[];
   tools?: readonly ToolKnowledge[];
+  invalidPolicy?: 'throw' | 'report';
 }): DoctorReport;
 type NumericDelayUnit = Exclude<DelayUnit, 'duration-string'>;
 declare const DURATION_STRING_UNITS: readonly ["minutes", "hours", "days", "weeks"];
@@ -559,6 +1208,7 @@ type CooldownConversion = {
   ok: false;
   tool: ToolId;
   reason: string;
+  fix: string;
 };
 declare function convertMinutes(minutes: number, unit: NumericDelayUnit): Converted<number>;
 /** Writes minutes as a duration string such as `36 hours` or `3 days`. */
@@ -583,6 +1233,7 @@ declare const DEFAULT_POLICY: {
   readonly installScripts: {
     readonly default: "deny";
     readonly allow: readonly [];
+    readonly deny: readonly [];
   };
   readonly sources: {
     readonly git: "deny";
@@ -606,4 +1257,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 { type ApplyReport, type CliIo, 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 Level, type Location, type Notice, type NumericDelayUnit, POLICY_FILE, type PackageManagerInfo, type Policy, PolicyError, type PolicyIssue, type PolicyResult, RULES, type ResolvedPolicy, type Rule, SCHEMA_URL, type Snippet, type VersionDeclaration, applyProject, botDuration, convertCooldown, convertMinutes, countLevels, detectProject, formatDuration, formatIssue, getVersion, loadPolicy, parseDuration, parsePolicy, planApply, renderPolicy, renderText, run, runDoctor, toDurationString, toSarif, unifiedDiff, validatePolicy };
+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 };