depcurfew 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -1,35 +1,3 @@
-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;
-}
-declare function run(argv: readonly string[], output: CliIo, dependencies?: CheckDependencies): Promise<number>;
-declare function getVersion(): string;
 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. */
@@ -129,6 +97,103 @@ interface ProjectKnowledge {
   /** 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;
@@ -141,6 +206,8 @@ interface ToolKnowledge {
   sources?: SourcesKnowledge;
   /** 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>>>;
 }
@@ -339,6 +406,25 @@ 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;
@@ -406,6 +492,7 @@ interface EnvironmentKnowledge {
     annotations: Fact<AnnotationsKnowledge>;
     annotationLimits: Fact<AnnotationLimitsKnowledge>;
     stepSummary: Fact<StepSummaryKnowledge>;
+    checkRuns: Fact<CheckRunsKnowledge>;
   };
   npmRegistry: {
     api: Fact<NpmRegistryKnowledge>;
@@ -522,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;
@@ -592,6 +723,7 @@ declare const policyShape: Shape<{
   installScripts?: {
     default: "allow" | "deny";
     allow?: readonly string[];
+    deny?: readonly string[];
   };
   sources?: {
     git?: "allow" | "deny";
@@ -612,6 +744,7 @@ declare const policyShape: Shape<{
   installScripts?: {
     default: "allow" | "deny";
     allow: readonly string[];
+    deny: readonly string[];
   };
   sources?: {
     git?: "allow" | "deny";
@@ -626,24 +759,35 @@ type Policy = Input<typeof policyShape>;
 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 tool is not supported (Yarn Classic), so nothing is written for it.";
+  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 lacks a setting the policy needs, so that setting is not written.";
+  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 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 '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 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 '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.";
@@ -669,6 +813,7 @@ 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 '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;
@@ -708,7 +853,7 @@ declare class WriteFailed extends Error {
   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. */
+  /** 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;
@@ -769,7 +914,14 @@ declare class ApplyWriteError extends Error {
   /** Files already replaced that could not be put back (normally none). */
   readonly unrestored: string[];
   readonly report: ApplyReport;
-  constructor(failure: WriteFailed, 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
@@ -779,8 +931,17 @@ declare class ApplyWriteError extends Error {
 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;
@@ -888,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. */
@@ -912,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;
@@ -943,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. */
@@ -953,12 +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;
   /** 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[];
@@ -1033,6 +1233,7 @@ declare const DEFAULT_POLICY: {
   readonly installScripts: {
     readonly default: "deny";
     readonly allow: readonly [];
+    readonly deny: readonly [];
   };
   readonly sources: {
     readonly git: "deny";

package/dist/index.js

@@ -1 +1 @@
-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";
+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, i as RULES, P as SCHEMA_URL, g as applyProject, _ as botDuration, l as checkSpec, u as checkSpecs, D as convertCooldown, O as convertMinutes, a 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, o 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-BBZUJJq-.js";