depcurfew 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+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;
@@ -9,11 +14,26 @@ interface CliIo {
     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;
 }
-declare function run(argv: readonly string[], output: CliIo): Promise<number>;
+declare function run(argv: readonly string[], output: CliIo, dependencies?: CheckDependencies): 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 +115,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,7 +124,8 @@ 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>;
 }
@@ -110,17 +133,19 @@ 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;
   /** 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 +199,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`.
@@ -202,6 +343,33 @@ 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 +396,71 @@ 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>;
   };
+  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 +469,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;
@@ -398,6 +624,70 @@ 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 '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 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 lacks a setting the policy needs, so that setting is not written.";
+  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 '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 was replaced, because the policy denies install scripts.";
+  readonly 'allow-list-entry-outside-policy': "An install-script allow-list in the repository lets a package run scripts the policy does not allow; apply does not remove 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 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.";
+  readonly 'exact-version-gap': "The pinned 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.";
+};
+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 +695,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, relative to the root. */
+  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 +732,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 +748,137 @@ 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;
+  constructor(failure: WriteFailed, report: ApplyReport);
+}
 /**
  * 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 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.
@@ -465,6 +901,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. */
@@ -517,7 +955,8 @@ interface Rule {
 }
 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[];
 }
@@ -535,11 +974,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 +1008,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`. */
@@ -606,4 +1056,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 };

package/dist/index.js

@@ -1 +1 @@
-export { w as DEFAULT_POLICY, s as EXIT_FAILURE, c as EXIT_OK, l as EXIT_USAGE, T as POLICY_FILE, d as PolicyError, o as RULES, E as SCHEMA_URL, f as applyProject, p as botDuration, y as convertCooldown, b as convertMinutes, i as countLevels, O as detectProject, S as formatDuration, g as formatIssue, k as getVersion, m as loadPolicy, C as parseDuration, _ as parsePolicy, h as planApply, D as renderPolicy, a as renderText, t as run, n as runDoctor, x as toDurationString, r as toSarif, u as unifiedDiff, v as validatePolicy } from "./run-D7KMlsVh.js";
+export { b as APPLY_ERRORS, x as APPLY_WARNINGS, m as ApplyWriteError, M as DEFAULT_POLICY, d as EXIT_FAILURE, f as EXIT_OK, p as EXIT_USAGE, N as POLICY_FILE, h as PolicyError, s as PopularNames, o as RULES, P as SCHEMA_URL, g as applyProject, _ as botDuration, l as checkSpec, u as checkSpecs, D as convertCooldown, O as convertMinutes, i as countLevels, I as detectProject, A as formatDuration, w as formatIssue, L as getVersion, v as loadPolicy, j as parseDuration, T as parsePolicy, y as planApply, F as renderPolicy, a as renderText, t as run, n as runDoctor, c as scanCommandLine, k as toDurationString, r as toSarif, C as unifiedDiff, E as validatePolicy, S as warningText } from "./run-CvdVkFPn.js";