depcurfew 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,8 +1,11 @@
1
1
  import { Readable, Writable } from "node:stream";
2
- type ToolId = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'deno' | 'uv' | 'pip' | 'poetry' | 'pdm' | 'pipenv' | 'composer' | 'renovate' | 'dependabot';
2
+ type ToolId = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'deno' | 'uv' | 'pip' | 'poetry' | 'pdm' | 'pipenv' | 'composer' | 'bundler' | 'renovate' | 'dependabot';
3
3
  type ToolKind = 'package-manager' | 'update-bot';
4
- /** The registry a package manager installs from; package names in the policy are compared per ecosystem. */
5
- type Ecosystem = 'npm' | 'pypi' | 'packagist';
4
+ /**
5
+ * The registry a package manager installs from; package names in the policy are compared per ecosystem. rubygems
6
+ * (Bundler, decision D-152) has no prefix in the policy, so no name there belongs to it.
7
+ */
8
+ type Ecosystem = 'npm' | 'pypi' | 'packagist' | 'rubygems';
6
9
  interface Evidence$1<T> {
7
10
  value: T;
8
11
  /** URL of official documentation or changelog. */
@@ -41,9 +44,17 @@ type DelayUnit = 'seconds' | 'minutes' | 'hours' | 'days' | 'duration-string';
41
44
  type SecurityUpdateBehavior = 'bypass' | 'applies' | 'configurable';
42
45
  /** Whether dependency lifecycle scripts (preinstall/install/postinstall) run. */
43
46
  type ScriptPolicy = 'run' | 'run-with-warning' | 'deny' | 'deny-except-allowlist' | 'not-applicable';
47
+ /** A config file that takes the release-age delay under another key or in another unit than the tool's setting. */
48
+ interface CooldownFileSetting {
49
+ file: string;
50
+ setting: string;
51
+ unit: DelayUnit;
52
+ }
44
53
  interface CooldownKnowledge {
45
54
  setting: Fact<string | null>;
46
55
  configFiles: Fact<readonly string[]>;
56
+ /** The config files whose key or unit for the delay differ from setting and unit (Deno's .npmrc). */
57
+ fileSettings?: Fact<readonly CooldownFileSetting[]>;
47
58
  cliFlag: Fact<string | null>;
48
59
  unit: Fact<DelayUnit | null>;
49
60
  availableSince: Fact<string | null>;
@@ -118,8 +129,14 @@ interface UserDirectory {
118
129
  path: string;
119
130
  /** Use this directory only when it already exists (pip on macOS). */
120
131
  ifExists?: boolean;
121
- /** Skip this directory while this environment variable is set and not empty (pip 26.2+ on macOS and XDG_DATA_HOME). */
122
- unlessEnv?: string;
132
+ /**
133
+ * Skip this directory while this environment variable is set and not empty (pip 26.2 on macOS and XDG_DATA_HOME), or,
134
+ * with `absolute`, only while it is an absolute path (pip 26.3+, whose platformdirs ignores a relative value).
135
+ */
136
+ unlessEnv?: string | {
137
+ env: string;
138
+ absolute: true;
139
+ };
123
140
  }
124
141
  /** Where the user file is on some platforms: the first directory that applies is used. */
125
142
  interface UserLocation {
@@ -135,8 +152,16 @@ interface UserFile {
135
152
  sections?: readonly string[];
136
153
  /** Other user-level files this version reads the same settings from, whose keys win over this file's. */
137
154
  overriddenBy?: readonly UserFile[];
138
- /** INI only: the tool reads a key with underscores as the same key with dashes (pip: only_binary is only-binary). */
155
+ /**
156
+ * INI only: the tool reads a key without regard to case, with underscores as dashes and without a leading -- (pip:
157
+ * only_binary and --only-binary are only-binary).
158
+ */
139
159
  underscoresAsDashes?: boolean;
160
+ /**
161
+ * INI only: the tool stops on a file that has a section twice or a key twice in one section (Python's configparser in
162
+ * strict mode), comparing keys without regard to case, or as it reads them (`as-read`: underscoresAsDashes too).
163
+ */
164
+ duplicateKeys?: 'case-insensitive' | 'as-read';
140
165
  /** YAML only: the tool's loader applies merge keys (<<: *defaults), so merged keys count as keys of the map. */
141
166
  mergeKeys?: boolean;
142
167
  }
@@ -264,6 +289,14 @@ interface OverrideSwitch {
264
289
  */
265
290
  protects?: string;
266
291
  }
292
+ /**
293
+ * A layout of the tarball URLs of a registry (decision D-168): `path` with {scope}, {name}, {version} and {digest}; on
294
+ * `host` only, or at the end of any path (a registry mounted below the root) when there is none.
295
+ */
296
+ interface RegistryTarballLayoutKnowledge {
297
+ host?: string;
298
+ path: string;
299
+ }
267
300
  /** A tool that environment facts refer to: Node.js, Python or a package manager. */
268
301
  type RuntimeOrTool = 'node' | 'python' | ToolId;
269
302
  interface PackageManagerFieldKnowledge {
@@ -293,6 +326,11 @@ interface SetupActionInput {
293
326
  kind: 'version' | 'version-file' | 'runtime';
294
327
  /** The tool a `version` or `version-file` input refers to. */
295
328
  tool?: RuntimeOrTool;
329
+ /**
330
+ * Values of a `version` input that name no version but a way to choose one (ruby/setup-ruby's bundler input:
331
+ * Gemfile.lock, default, latest, none); such a value declares no version.
332
+ */
333
+ keywords?: readonly string[];
296
334
  }
297
335
  interface SetupActionKnowledge {
298
336
  /** `owner/name`, compared without case. */
@@ -455,6 +493,47 @@ interface OsvKnowledge {
455
493
  ecosystems: Fact<Readonly<Record<string, string>>>;
456
494
  /** How the API compares the version of a query with the versions of a record, by depcurfew's ecosystem (decision D-142). */
457
495
  versionMatching: Fact<Readonly<Record<string, OsvVersionMatchingKnowledge>>>;
496
+ /** The public export of the database, which depcurfew osv update downloads (decision D-150). */
497
+ dataExport: Fact<OsvExportKnowledge>;
498
+ /** How a record says which versions of a package it affects, and how they are evaluated (decision D-150). */
499
+ affected: Fact<OsvAffectedKnowledge>;
500
+ }
501
+ /** The public export of OSV.dev: one zip file per ecosystem, with one JSON file per record (decision D-150). */
502
+ interface OsvExportKnowledge {
503
+ /** Base URL of the bucket over HTTPS. */
504
+ url: string;
505
+ /** The path of the zip file of one ecosystem below url ({folder}). */
506
+ archivePath: string;
507
+ /** The folder of each ecosystem of depcurfew (npm, pypi, packagist). */
508
+ folders: Readonly<Record<string, string>>;
509
+ /** The name of the entry of one record in the zip file ({id}). */
510
+ recordEntry: string;
511
+ /** Whether the zip files hold withdrawn records too. */
512
+ withdrawnIncluded: boolean;
513
+ }
514
+ /** The fields of affected[] of an OSV record and the evaluation of its ranges (the OSV schema). */
515
+ interface OsvAffectedKnowledge {
516
+ affectedField: string;
517
+ packageField: string;
518
+ nameField: string;
519
+ ecosystemField: string;
520
+ versionsField: string;
521
+ rangesField: string;
522
+ typeField: string;
523
+ eventsField: string;
524
+ /** The range types whose events are versions of the package: SEMVER and ECOSYSTEM (the third type holds commits). */
525
+ versionRangeTypes: readonly string[];
526
+ /** The keys of the events. */
527
+ events: {
528
+ introduced: string;
529
+ fixed: string;
530
+ lastAffected: string;
531
+ limit: string;
532
+ };
533
+ /** introduced "0": before every version. */
534
+ earliest: string;
535
+ /** limit "*": no limit. */
536
+ unlimited: string;
458
537
  }
459
538
  /** What OSV.dev leaves out of a version before it compares it. */
460
539
  interface OsvVersionMatchingKnowledge {
@@ -731,7 +810,13 @@ interface CheckRunsKnowledge {
731
810
  repository: string;
732
811
  sha: string;
733
812
  eventPath: string;
813
+ eventName: string;
734
814
  };
815
+ /**
816
+ * The events whose GITHUB_SHA is the merge commit of the pull request, so the check goes on its head commit from the
817
+ * payload. For other events (pull_request_target: the last commit of the base branch) it goes on GITHUB_SHA.
818
+ */
819
+ mergeCommitEvents: readonly string[];
735
820
  /** Path in the event payload of the commit a pull request check belongs to (GITHUB_SHA is the merge commit there). */
736
821
  pullRequestHeadSha: readonly string[];
737
822
  }
@@ -817,6 +902,40 @@ interface SetupNodeVersionFileKnowledge {
817
902
  packageJsonOrder: readonly string[];
818
903
  /** Any other file: the first line that matches (multiline), group "version"; otherwise the whole text, trimmed. */
819
904
  textPattern: string;
905
+ /**
906
+ * A file that is no JSON but TOML (mise.toml, decision D-173): the key of `table`, a string, or a table whose
907
+ * `versionKey` is a string; any other value names no version. Tried before textPattern.
908
+ */
909
+ toml?: {
910
+ table: string;
911
+ key: string;
912
+ versionKey: string;
913
+ };
914
+ }
915
+ /**
916
+ * mise (decision D-173): the files of a directory it reads its [tools] from, the one that wins first, and how a tool's
917
+ * request is written there (a string, a list whose first entry is the default, or a table with the request under
918
+ * versionKey); `tools` maps the names of [tools] to the runtimes depcurfew reads.
919
+ */
920
+ interface MiseConfigKnowledge {
921
+ files: readonly string[];
922
+ table: string;
923
+ versionKey: string;
924
+ tools: Readonly<Record<string, RuntimeOrTool>>;
925
+ }
926
+ /**
927
+ * jdx/mise-action (decision D-173): the step installs the tools of the mise configuration of its working directory
928
+ * (or of the TOML text of `inlineConfig`, which it writes to mise.toml) and puts them on PATH for the later steps,
929
+ * unless `install` is false.
930
+ */
931
+ interface MiseActionKnowledge {
932
+ action: string;
933
+ inputs: {
934
+ install: string;
935
+ inlineConfig: string;
936
+ workingDirectory: string;
937
+ };
938
+ inlineFile: string;
820
939
  }
821
940
  /** How an image reference names the registry, the namespace and the tag when they are left out. */
822
941
  interface ImageReferenceKnowledge {
@@ -880,7 +999,42 @@ interface InstallScriptPackageKnowledge {
880
999
  after: 'clone';
881
1000
  };
882
1001
  }
1002
+ /**
1003
+ * An ecosystem whose package manager has no release-age delay depcurfew configures, so that depcurfew delays new
1004
+ * versions there only through the update bots (decision D-151): Cargo, Go modules, Maven, Gradle and NuGet.
1005
+ */
1006
+ type BotOnlyEcosystemId = 'cargo' | 'gomod' | 'maven' | 'gradle' | 'nuget';
1007
+ /** The files that show an ecosystem updated by bots only, in a project directory. */
1008
+ interface BotOnlyProjectKnowledge {
1009
+ /** The ecosystem as messages name it: Cargo, Go modules. */
1010
+ name: string;
1011
+ /** The package manager as messages name it: Cargo, Go. */
1012
+ client: string;
1013
+ /** Paths relative to a project directory (gradle/libs.versions.toml). */
1014
+ files: readonly string[];
1015
+ /** File name endings that show it (the project files of NuGet: .csproj). */
1016
+ extensions?: readonly string[];
1017
+ }
1018
+ /** The release-age delay of the package manager itself. */
1019
+ interface ClientDelayKnowledge {
1020
+ /** The setting; null when the package manager has none. */
1021
+ setting: string | null;
1022
+ /** The first version with the setting; null without one. */
1023
+ since: string | null;
1024
+ /** What the version belongs to, for messages: Cargo, .NET SDK. */
1025
+ product?: string;
1026
+ /** The setting holds back only the versions an update picks, not what an install or restore takes. */
1027
+ updatesOnly?: boolean;
1028
+ /** The file the setting is written in. */
1029
+ file?: string;
1030
+ }
1031
+ interface BotOnlyEcosystemKnowledge {
1032
+ project: Fact<BotOnlyProjectKnowledge>;
1033
+ releaseAge: Fact<ClientDelayKnowledge>;
1034
+ }
883
1035
  interface EnvironmentKnowledge {
1036
+ /** Ecosystems whose new versions only the update bots delay (decision D-151). */
1037
+ botOnlyEcosystems: Readonly<Record<BotOnlyEcosystemId, BotOnlyEcosystemKnowledge>>;
884
1038
  corepack: {
885
1039
  packageManagerField: Fact<PackageManagerFieldKnowledge>;
886
1040
  devEnginesSince: Fact<string>;
@@ -925,6 +1079,14 @@ interface EnvironmentKnowledge {
925
1079
  }>;
926
1080
  /** The Node.js version files that version managers also use in subdirectories of their directory. */
927
1081
  inheritedVersionFiles: Fact<readonly string[]>;
1082
+ /** How Node.js sends fetch() through the proxy of HTTPS_PROXY and HTTP_PROXY: only when this variable or option asks. */
1083
+ environmentProxy: Fact<{
1084
+ variable: string;
1085
+ value: string;
1086
+ option: string;
1087
+ since: readonly string[];
1088
+ proxyVariables: readonly string[];
1089
+ }>;
928
1090
  };
929
1091
  docker: {
930
1092
  imageReference: Fact<ImageReferenceKnowledge>;
@@ -941,6 +1103,18 @@ interface EnvironmentKnowledge {
941
1103
  inheritedByStages: boolean;
942
1104
  spaceForm: boolean;
943
1105
  }>;
1106
+ /**
1107
+ * ARG: a variable of the later RUN instructions of the stage and of the stages that start from it, with its default
1108
+ * when no --build-arg gives one; one declared before the first FROM only through an ARG without a value in a stage;
1109
+ * an ENV of the same name wins (decision D-166).
1110
+ */
1111
+ buildArguments: Fact<{
1112
+ instruction: string;
1113
+ runEnvironment: boolean;
1114
+ inheritedByStages: boolean;
1115
+ globalNeedsDeclaration: boolean;
1116
+ environmentWins: boolean;
1117
+ }>;
944
1118
  /** The default file name, and the suffix of other Dockerfiles (build.Dockerfile). */
945
1119
  dockerfileNames: Fact<{
946
1120
  defaultName: string;
@@ -967,6 +1141,10 @@ interface EnvironmentKnowledge {
967
1141
  /** Plugin names mapped to the tools they install. */
968
1142
  plugins: Fact<Readonly<Record<string, RuntimeOrTool>>>;
969
1143
  };
1144
+ /** mise.toml and the files beside it that pin tool versions (decision D-173). */
1145
+ mise: {
1146
+ config: Fact<MiseConfigKnowledge>;
1147
+ };
970
1148
  githubActions: {
971
1149
  workflows: Fact<WorkflowsKnowledge>;
972
1150
  /** The ids GitHub accepts as keys of jobs, as a regular expression (decision D-135). */
@@ -991,6 +1169,17 @@ interface EnvironmentKnowledge {
991
1169
  key: string;
992
1170
  levels: readonly ('workflow' | 'job' | 'step')[];
993
1171
  }>;
1172
+ /**
1173
+ * The GITHUB_ENV file: NAME=value lines a run step writes there are variables of the later steps of the job, over
1174
+ * the env of the workflow and the job, under the env of a step (decision D-166).
1175
+ */
1176
+ environmentFile: Fact<{
1177
+ variable: string;
1178
+ format: string;
1179
+ multilineMarker: string;
1180
+ laterSteps: boolean;
1181
+ stepEnvironmentWins: boolean;
1182
+ }>;
994
1183
  /** Whether workflows may use YAML anchors and aliases, which GitHub expands (decision D-141). */
995
1184
  yamlAliases: Fact<{
996
1185
  accepted: boolean;
@@ -1001,9 +1190,14 @@ interface EnvironmentKnowledge {
1001
1190
  setupDeno: Fact<SetupActionKnowledge>;
1002
1191
  setupPython: Fact<SetupActionKnowledge>;
1003
1192
  setupUv: Fact<SetupActionKnowledge>;
1193
+ /** pdm-project/setup-pdm: the PDM of its version input (decision D-173). */
1194
+ setupPdm: Fact<SetupActionKnowledge>;
1195
+ /** jdx/mise-action: the tools of the mise configuration (decision D-173). */
1196
+ miseAction: Fact<MiseActionKnowledge>;
1004
1197
  /** Third-party actions that install Poetry; Poetry has no official action. */
1005
1198
  installPoetry: Fact<SetupActionKnowledge>;
1006
1199
  actionsPoetry: Fact<SetupActionKnowledge>;
1200
+ setupRuby: Fact<SetupActionKnowledge>;
1007
1201
  codeScanningUpload: Fact<CodeScanningUploadKnowledge>;
1008
1202
  stopCommands: Fact<StopCommandsKnowledge>;
1009
1203
  annotations: Fact<AnnotationsKnowledge>;
@@ -1020,6 +1214,11 @@ interface EnvironmentKnowledge {
1020
1214
  maxSize: number;
1021
1215
  weeklyDownloadsField: string;
1022
1216
  }>;
1217
+ /** The tarball URLs of GitHub Packages, which name the package and the version but not as npm's layout does. */
1218
+ githubPackagesTarballs: Fact<RegistryTarballLayoutKnowledge>;
1219
+ /** The tarball URLs of GitLab's npm registry and of Artifactory, whose file name keeps the scope. */
1220
+ gitlabTarballs: Fact<RegistryTarballLayoutKnowledge>;
1221
+ artifactoryTarballs: Fact<RegistryTarballLayoutKnowledge>;
1023
1222
  };
1024
1223
  pypiIndex: {
1025
1224
  api: Fact<PypiIndexKnowledge>;
@@ -1095,7 +1294,7 @@ interface EnvironmentKnowledge {
1095
1294
  }>;
1096
1295
  };
1097
1296
  }
1098
- type PackageManagerId = Extract<ToolId, 'npm' | 'pnpm' | 'yarn' | 'bun' | 'deno' | 'uv' | 'pip' | 'poetry' | 'pdm' | 'pipenv' | 'composer'>;
1297
+ type PackageManagerId = Extract<ToolId, 'npm' | 'pnpm' | 'yarn' | 'bun' | 'deno' | 'uv' | 'pip' | 'poetry' | 'pdm' | 'pipenv' | 'composer' | 'bundler'>;
1099
1298
  type BotId = Extract<ToolId, 'renovate' | 'dependabot'>;
1100
1299
  /** Why a package manager is considered in use. Ordered from the strongest signal. */
1101
1300
  type EvidenceKind = 'lockfile' | 'packageManager' | 'devEngines' | 'config' | 'ci' | 'default';
@@ -1105,11 +1304,15 @@ interface Evidence {
1105
1304
  file: string;
1106
1305
  }
1107
1306
  /**
1108
- * tool-config: a version the tool's own configuration requires, e.g. required-version in [tool.uv]. nvmrc and
1307
+ * yarnPath: the version of the Yarn release yarnPath in .yarnrc.yml names (yarn-4.9.2.cjs), which every Yarn from 1.18
1308
+ * runs instead of itself, so it comes before packageManager (decision D-165). tool-config: a version the tool's own
1309
+ * configuration requires, e.g. required-version in [tool.uv]. lockfile: the
1310
+ * version of the tool that wrote the lockfile, which the tool switches to (BUNDLED WITH in Gemfile.lock). nvmrc and
1109
1311
  * node-version: the files .nvmrc and .node-version; engines: engines.node in package.json (a range of the Node.js
1110
- * versions the package works on, advisory); dockerfile: a Dockerfile (FROM node:22, RUN npm install -g npm@11).
1312
+ * versions the package works on, advisory); dockerfile: a Dockerfile (FROM node:22, RUN npm install -g npm@11); mise:
1313
+ * [tools] of mise.toml and the files beside it (decision D-173).
1111
1314
  */
1112
- type VersionSource = 'packageManager' | 'tool-config' | 'devEngines' | 'volta' | 'tool-versions' | 'nvmrc' | 'node-version' | 'engines' | 'github-actions' | 'dockerfile';
1315
+ type VersionSource = 'yarnPath' | 'packageManager' | 'tool-config' | 'lockfile' | 'devEngines' | 'volta' | 'tool-versions' | 'mise' | 'nvmrc' | 'node-version' | 'engines' | 'github-actions' | 'dockerfile';
1113
1316
  /**
1114
1317
  * A version declared somewhere in the repository, as written (it may be a range or an expression). A CI step that
1115
1318
  * names a version file has `versionFile`, and also `version` when depcurfew could read the version from that file.
@@ -1138,6 +1341,11 @@ type VersionDeclaration = ({
1138
1341
  * (decision D-115); the line is the image's, and it stands for the job's steps until a setup step.
1139
1342
  */
1140
1343
  container?: string;
1344
+ /**
1345
+ * github-actions: mise reads the version (jdx/mise-action), so it is a mise request (24 is a 24.x release), not a
1346
+ * version of setup-node (decision D-173).
1347
+ */
1348
+ reader?: 'mise';
1141
1349
  };
1142
1350
  /**
1143
1351
  * A command in a CI run step or a Dockerfile RUN instruction. install: installs packages with the tool (npm ci,
@@ -1149,10 +1357,16 @@ interface ToolCommand {
1149
1357
  kind: 'install' | 'upgrade';
1150
1358
  /**
1151
1359
  * pnpm, Yarn and Bun only install (their versions come from packageManager and the setup actions); poetry only
1152
- * upgrades: pipx install poetry==2.3.0 or pip install poetry==2.3.0 installs that Poetry (decision D-115).
1360
+ * upgrades: pipx install poetry==2.3.0 or pip install poetry==2.3.0 installs that Poetry (decision D-115). bundler:
1361
+ * bundle install, update, lock, add and cache resolve the Gemfile, and gem install bundler -v 4.0.23 upgrades (decision
1362
+ * D-152). pdm, pipenv and uv only upgrade too: pip install pipenv==2025.0.4, pipx install pdm==2.20.1, uv tool install
1363
+ * pdm==2.20.1, pip install uv==0.8.22 (decision D-173).
1364
+ */
1365
+ tool: 'npm' | 'pip' | 'pnpm' | 'yarn' | 'bun' | 'poetry' | 'pdm' | 'pipenv' | 'uv' | 'bundler';
1366
+ /**
1367
+ * upgrade: the version asked for as written, latest when none is; absent when the command does not say (corepack
1368
+ * enable npm). A bundler install: the version bundle _4.0.12_ install runs (decision D-159).
1153
1369
  */
1154
- tool: 'npm' | 'pip' | 'pnpm' | 'yarn' | 'bun' | 'poetry';
1155
- /** upgrade: the version asked for as written, latest when none is; absent when the command does not say (corepack enable npm). */
1156
1370
  version?: string;
1157
1371
  /** npm ci and its aliases, which install exactly the versions of package-lock.json (decision D-115). */
1158
1372
  lockfile?: true;
@@ -1168,6 +1382,8 @@ interface ToolCommand {
1168
1382
  delay?: string;
1169
1383
  /** pip install: PIP_CONFIG_FILE names a file that may set the delay, or the value is a variable depcurfew does not read. */
1170
1384
  delayUnknown?: true;
1385
+ /** bundler: the delay comes from the command line (--cooldown), not from BUNDLE_COOLDOWN (decision D-152). */
1386
+ delayOption?: true;
1171
1387
  line: number;
1172
1388
  /**
1173
1389
  * A command that installs or runs Corepack comes before it in the same job (an earlier run step, or earlier in its
@@ -1200,6 +1416,13 @@ interface WorkflowJob {
1200
1416
  pipConfig?: true;
1201
1417
  /** The line of the first run step command that installs Corepack (npm install -g corepack) or runs it (decision D-128). */
1202
1418
  corepack?: number;
1419
+ /** The values of PIP_CONFIG_FILE in the env of its run steps, as written (decision D-173); absent when none sets it. */
1420
+ pipConfigFiles?: string[];
1421
+ /**
1422
+ * The working directories of its run steps, as ToolCommand.directory writes them ('' for the root), each once and at
1423
+ * most 64, for the project a job works in (decision D-173); absent when every run step works in the root.
1424
+ */
1425
+ directories?: string[];
1203
1426
  }
1204
1427
  /** The official runtime image a build stage starts from. */
1205
1428
  interface StageRuntime {
@@ -1225,6 +1448,8 @@ interface DockerStage {
1225
1448
  commands: ToolCommand[];
1226
1449
  /** A RUN may change pip's configuration (pip config set, a pip.conf it writes), as for jobs (decision D-115). */
1227
1450
  pipConfig?: true;
1451
+ /** The values of PIP_CONFIG_FILE its pip installs see (ENV, ARG, also of a stage it starts from), as written (decision D-173). */
1452
+ pipConfigFiles?: string[];
1228
1453
  /** The line of the first RUN command that installs Corepack (npm install -g corepack) or runs it (decision D-128). */
1229
1454
  corepack?: number;
1230
1455
  /**
@@ -1253,6 +1478,15 @@ interface BotInfo {
1253
1478
  id: BotId;
1254
1479
  configFiles: string[];
1255
1480
  }
1481
+ /**
1482
+ * An ecosystem whose new versions depcurfew delays only through the update bots (decision D-151): its package manager
1483
+ * has no release-age delay depcurfew configures.
1484
+ */
1485
+ interface BotEcosystemInfo {
1486
+ id: BotOnlyEcosystemId;
1487
+ /** The files that show it, from the root, the direct subdirectories, workspace packages and projects; sorted. */
1488
+ files: string[];
1489
+ }
1256
1490
  interface WorkspaceInfo {
1257
1491
  declarations: {
1258
1492
  file: string;
@@ -1281,6 +1515,8 @@ interface Detection {
1281
1515
  versions: VersionDeclaration[];
1282
1516
  };
1283
1517
  bots: BotInfo[];
1518
+ /** Cargo, Go modules, Maven, Gradle and NuGet, whose new versions only the bots delay (decision D-151); absent when none. */
1519
+ botEcosystems?: BotEcosystemInfo[];
1284
1520
  workspaces: WorkspaceInfo | null;
1285
1521
  /** `.npmrc` files in the root and in workspace packages; several tools read them. */
1286
1522
  npmrcFiles: string[];
@@ -1315,72 +1551,6 @@ type FetchLike = (url: string, init: {
1315
1551
  * fetches and reads each document once (decision D-113).
1316
1552
  */
1317
1553
  type LookupCache = Map<string, Promise<unknown>>;
1318
- interface McpLimits {
1319
- /** The longest line, in bytes; a longer one is answered with an error and skipped. */
1320
- lineBytes: number;
1321
- /** The deepest nesting of arrays and objects in a message. */
1322
- depth: number;
1323
- /** Tool calls that run at once. */
1324
- concurrentCalls: number;
1325
- /** Tool calls that wait for one of them; a call beyond that gets a result that says to try again. */
1326
- queuedCalls: number;
1327
- /** Messages in one batch (2025-03-26 only). */
1328
- batch: number;
1329
- /** How long calls may still run after stdin ends before they are stopped. */
1330
- graceMs: number;
1331
- }
1332
- export declare const EXIT_OK = 0;
1333
- export declare const EXIT_FAILURE = 1;
1334
- export declare const EXIT_USAGE = 2;
1335
- interface CliIo {
1336
- stdout(text: string): void;
1337
- stderr(text: string): void;
1338
- /** Whether each stream may be colored (see color.ts); absent means plain text. */
1339
- colors?: {
1340
- stdout: boolean;
1341
- stderr: boolean;
1342
- };
1343
- /** Whether each stream is a terminal; absent means it is not. */
1344
- terminal?: {
1345
- stdout: boolean;
1346
- stderr: boolean;
1347
- };
1348
- }
1349
- /** What the server talks over and the process around it; tests replace it. */
1350
- interface McpProcess {
1351
- input: Readable;
1352
- output: Writable;
1353
- env: Readonly<Record<string, string | undefined>>;
1354
- cwd: string;
1355
- /** Calls `stop` on SIGINT and SIGTERM; returns what removes the handlers. Left out in tests. */
1356
- onSignal?: (stop: () => void) => () => void;
1357
- limits?: Partial<McpLimits>;
1358
- }
1359
- declare class Repository {
1360
- #private;
1361
- readonly root: string;
1362
- readonly warnings: DetectionWarning[];
1363
- /** Repository-relative paths of the files that were read, for the log of what doctor checked. */
1364
- readonly read: Set<string>;
1365
- constructor(root: string);
1366
- warn(code: string, message: string, files: readonly string[], line?: number): void;
1367
- isFile(path: string): boolean;
1368
- /** Whether the path exists in the repository as something other than a regular file or a directory (a named pipe, a socket, a device). */
1369
- isSpecialFile(path: string): boolean;
1370
- /** The text of a file, without a byte order mark; undefined (with a warning when useful) if it cannot be read. */
1371
- readText(path: string, limit?: number): string | undefined;
1372
- /** The first bytes of a file, e.g. to recognize a lockfile format without reading a large file. */
1373
- readHead(path: string, bytes?: number): string | undefined;
1374
- /** Names of the files in a directory (following symlinks only inside the repository). */
1375
- listFiles(path: string): string[];
1376
- /** Names of the subdirectories of a directory, skipping node_modules, .git and symlinks that lead outside. */
1377
- listDirectories(path: string): string[];
1378
- /** Parses a file with the given parser, reporting failures as warnings. */
1379
- parse<T>(path: string, parser: (text: string) => T): T | undefined;
1380
- /** Like parse, but each file is read and parsed once per parser: several rules read the same file. */
1381
- parseOnce<T>(path: string, parser: (text: string) => T): T | undefined;
1382
- relative(absolute: string): string;
1383
- }
1384
1554
  interface Duration {
1385
1555
  /** The duration as written in the policy. */
1386
1556
  text: string;
@@ -1444,6 +1614,12 @@ type Output<S> = S extends Shape<unknown, infer Out> ? Out : never;
1444
1614
  declare const FAIL_ON_LEVELS: readonly ["error", "warning"];
1445
1615
  declare const policyShape: Shape<{
1446
1616
  version: 1;
1617
+ $schema?: string;
1618
+ cooldown?: {
1619
+ minimum: string;
1620
+ exclude?: readonly string[];
1621
+ securityUpdates?: "bypass" | "delay";
1622
+ };
1447
1623
  installScripts?: {
1448
1624
  default: "allow" | "deny";
1449
1625
  allow?: readonly string[];
@@ -1455,12 +1631,6 @@ declare const policyShape: Shape<{
1455
1631
  file?: "allow" | "deny";
1456
1632
  directory?: "allow" | "deny";
1457
1633
  };
1458
- $schema?: string;
1459
- cooldown?: {
1460
- minimum: string;
1461
- exclude?: readonly string[];
1462
- securityUpdates?: "bypass" | "delay";
1463
- };
1464
1634
  targets?: "auto" | readonly ToolId[];
1465
1635
  projects?: readonly string[];
1466
1636
  doctor?: {
@@ -1470,6 +1640,12 @@ declare const policyShape: Shape<{
1470
1640
  version: 1;
1471
1641
  targets: "auto" | readonly ToolId[];
1472
1642
  projects: readonly string[];
1643
+ $schema?: string;
1644
+ cooldown?: {
1645
+ minimum: Duration;
1646
+ exclude: readonly string[];
1647
+ securityUpdates: "bypass" | "delay";
1648
+ };
1473
1649
  installScripts?: {
1474
1650
  default: "allow" | "deny";
1475
1651
  allow: readonly string[];
@@ -1481,12 +1657,6 @@ declare const policyShape: Shape<{
1481
1657
  file?: "allow" | "deny";
1482
1658
  directory?: "allow" | "deny";
1483
1659
  };
1484
- $schema?: string;
1485
- cooldown?: {
1486
- minimum: Duration;
1487
- exclude: readonly string[];
1488
- securityUpdates: "bypass" | "delay";
1489
- };
1490
1660
  doctor?: {
1491
1661
  failOn?: "error" | "warning";
1492
1662
  };
@@ -1518,6 +1688,11 @@ interface CheckFinding {
1518
1688
  message: string;
1519
1689
  /** What to do about it. */
1520
1690
  fix: string;
1691
+ /**
1692
+ * known-malicious: where the answer comes from, api.osv.dev (--osv) or the local copy of the OSV.dev data that
1693
+ * depcurfew osv update writes (decision D-150).
1694
+ */
1695
+ source?: 'osv-api' | 'osv-local';
1521
1696
  }
1522
1697
  interface PackageReport {
1523
1698
  spec: string;
@@ -1579,6 +1754,11 @@ interface CheckRequest {
1579
1754
  * the root composer.json, for a file of a parent directory that Composer may not use (decision D-142).
1580
1755
  */
1581
1756
  rootStability?: false;
1757
+ /**
1758
+ * npm link (decision D-172): the package is installed from the registry only when the global space has no package
1759
+ * of that name, so a name the registry does not have is a warning; npm link then links the global one or fails.
1760
+ */
1761
+ linked?: true;
1582
1762
  }
1583
1763
  interface CheckOptions {
1584
1764
  policy: ResolvedPolicy;
@@ -1586,8 +1766,13 @@ interface CheckOptions {
1586
1766
  now: Date;
1587
1767
  registry: string;
1588
1768
  popular: PopularNames;
1589
- /** Registries the project assigns to scopes (@scope:registry in .npmrc); those packages are not looked up. */
1769
+ /**
1770
+ * Registries the project assigns to scopes (@scope:registry in .npmrc); those packages are not looked up, unless the
1771
+ * registry depcurfew asks is the scope's (decision D-168).
1772
+ */
1590
1773
  scopeRegistries?: ReadonlyMap<string, string>;
1774
+ /** Where each of them is set, for messages: @acme:registry= in .npmrc, line 2. */
1775
+ scopeWhere?: ReadonlyMap<string, string>;
1591
1776
  /** The Python package index pypi: packages are looked up in; PyPI when not given. */
1592
1777
  index?: string;
1593
1778
  /** Popular Python projects, by normalized name, for look-alike names. */
@@ -1624,14 +1809,27 @@ interface OsvPackage {
1624
1809
  name: string;
1625
1810
  version: string;
1626
1811
  }
1627
- /** What OSV.dev says about one version: the ids of its MAL- records (none: no known malware), or why it was not checked. */
1812
+ /**
1813
+ * Where an answer about known malicious versions comes from: api.osv.dev (--osv), or the local copy of the OSV.dev data
1814
+ * that depcurfew osv update writes (decision D-150).
1815
+ */
1816
+ type OsvSource = 'osv-api' | 'osv-local';
1817
+ /**
1818
+ * What OSV.dev says about one version: the ids of its MAL- records (none: no known malware), or why it was not checked.
1819
+ * `source`: where the answer comes from; api.osv.dev when left out.
1820
+ */
1628
1821
  type OsvVerdict = {
1629
1822
  status: 'checked';
1630
1823
  malicious: string[];
1824
+ source?: OsvSource;
1631
1825
  } | {
1632
1826
  status: 'unchecked';
1633
1827
  reason: string;
1634
1828
  };
1829
+ /** The local copy of the OSV.dev data (LocalOsvData of src/osv/data.ts): the MAL- ids for a version, undefined without data for its ecosystem. */
1830
+ interface OsvLocalLookup {
1831
+ lookup(pkg: OsvPackage): string[] | undefined;
1832
+ }
1635
1833
  interface OsvOptions {
1636
1834
  fetch: FetchLike;
1637
1835
  signal?: AbortSignal | undefined;
@@ -1648,6 +1846,175 @@ interface OsvOptions {
1648
1846
  * wrong), so every version left is unchecked with that reason. When `options.signal` aborts, the promise rejects.
1649
1847
  */
1650
1848
  export declare function queryOsv(packages: readonly OsvPackage[], options: OsvOptions): Promise<OsvVerdict[]>;
1849
+ /** The user whose files these are, for the check of owners. */
1850
+ interface PosixUser {
1851
+ uid: number;
1852
+ /** The user's primary group. */
1853
+ gid: number;
1854
+ }
1855
+ /**
1856
+ * A directory other users can write: every user may (its mode lets others write, sticky or not: they can still add
1857
+ * files), the members of its group may (a group other than the user's own primary group, which on systems with a
1858
+ * private group per user and umask 002 holds only the user), or it belongs to another user than the user and root.
1859
+ * `own` says whether it belongs to the user, who can then take the access away; `id` is the group or the owner.
1860
+ */
1861
+ interface CacheWriteProblem {
1862
+ directory: string;
1863
+ kind: 'everyone' | 'group' | 'owner';
1864
+ own: boolean;
1865
+ id?: number;
1866
+ }
1867
+ /** The ecosystems osv update downloads, in this order. */
1868
+ declare const OSV_DATA_ECOSYSTEMS: readonly ["npm", "pypi", "packagist"];
1869
+ type OsvDataEcosystem = (typeof OSV_DATA_ECOSYSTEMS)[number];
1870
+ /**
1871
+ * What depcurfew osv update keeps of an export, and what the lookups read (decision D-156). The real exports of
1872
+ * 2026-11-03 had at most 1 affected[] entry per MAL- record, 232 versions of a package in one record (npm; 86 for
1873
+ * PyPI), 2 ranges and 4 events in a range, 2 records of one package, a package line of 3,320 bytes and a data file of
1874
+ * 17.9 MB (npm), each far below its limit. A record past a limit of a record, or one that would give a package more
1875
+ * records or a longer line than the limits allow, is left out whole and counted (tooLarge in the result of osv
1876
+ * update), never kept in part; data larger than fileBytes is not written, and the old data stays.
1877
+ */
1878
+ interface OsvDataLimits {
1879
+ /** Most affected[] entries of a record. */
1880
+ affectedEntries: number;
1881
+ /** Most versions of a record for one package, its entries together. */
1882
+ versions: number;
1883
+ /** Most ranges of a record for one package. */
1884
+ ranges: number;
1885
+ /** Most events of one range. */
1886
+ events: number;
1887
+ /** Most records of one package. */
1888
+ recordsPerPackage: number;
1889
+ /** Longest package line, in bytes, written and read. */
1890
+ lineBytes: number;
1891
+ /** Largest data file, in bytes, written and read. */
1892
+ fileBytes: number;
1893
+ }
1894
+ /** The state of the local data of one ecosystem. */
1895
+ type OsvDataState = {
1896
+ status: 'missing';
1897
+ file: string;
1898
+ } | {
1899
+ status: 'unreadable';
1900
+ file: string;
1901
+ reason: string;
1902
+ } | {
1903
+ status: 'ready';
1904
+ file: string;
1905
+ downloadedAt: string;
1906
+ exportedAt: string | null;
1907
+ records: number;
1908
+ };
1909
+ interface LocalOsvDataOptions {
1910
+ /**
1911
+ * The directories other users must not be able to write, from the top (osvDataDirectories of src/user/cache-path.ts
1912
+ * for the user cache directory); by default the directory of the data alone.
1913
+ */
1914
+ guarded?: readonly string[];
1915
+ /** The user, for the owners of those directories: by default the user of this process, none on Windows. Tests replace it. */
1916
+ user?: PosixUser | undefined;
1917
+ }
1918
+ /** Looks versions up in the local data; reads the file of an ecosystem once, when it is first needed. */
1919
+ export declare class LocalOsvData {
1920
+ #private;
1921
+ /** The directory of the local data; undefined when depcurfew has no user cache directory. */
1922
+ readonly directory: string | undefined;
1923
+ constructor(directory: string | undefined, options?: LocalOsvDataOptions);
1924
+ /**
1925
+ * A directory of the data that other users can write (decision D-156), checked once; undefined when there is none.
1926
+ * The lookups still use the data then: without it they would find nothing at all, and the warning says what to do.
1927
+ */
1928
+ writeProblem(): CacheWriteProblem | undefined;
1929
+ /** Whether the file of an ecosystem exists, readable or not. */
1930
+ exists(ecosystem: string): boolean;
1931
+ /** Whether the file of any ecosystem exists: without one, depcurfew osv update was never run (or failed every time). */
1932
+ any(): boolean;
1933
+ state(ecosystem: string): OsvDataState;
1934
+ /**
1935
+ * The ids of the MAL- records of the local data that affect the version, each once; undefined when there is no
1936
+ * readable data for its ecosystem. A package line that cannot be read makes the data of the ecosystem unreadable.
1937
+ */
1938
+ lookup(pkg: OsvPackage): string[] | undefined;
1939
+ }
1940
+ interface McpLimits {
1941
+ /** The longest line, in bytes; a longer one is answered with an error and skipped. */
1942
+ lineBytes: number;
1943
+ /** The deepest nesting of arrays and objects in a message. */
1944
+ depth: number;
1945
+ /** Tool calls that run at once. */
1946
+ concurrentCalls: number;
1947
+ /** Tool calls that wait for one of them; a call beyond that gets a result that says to try again. */
1948
+ queuedCalls: number;
1949
+ /** Messages in one batch (2025-03-26 only). */
1950
+ batch: number;
1951
+ /** How long calls may still run after stdin ends before they are stopped. */
1952
+ graceMs: number;
1953
+ }
1954
+ export declare const EXIT_OK = 0;
1955
+ export declare const EXIT_FAILURE = 1;
1956
+ export declare const EXIT_USAGE = 2;
1957
+ interface CliIo {
1958
+ stdout(text: string): void;
1959
+ stderr(text: string): void;
1960
+ /** Whether each stream may be colored (see color.ts); absent means plain text. */
1961
+ colors?: {
1962
+ stdout: boolean;
1963
+ stderr: boolean;
1964
+ };
1965
+ /** Whether each stream is a terminal; absent means it is not. */
1966
+ terminal?: {
1967
+ stdout: boolean;
1968
+ stderr: boolean;
1969
+ };
1970
+ }
1971
+ /** What the server talks over and the process around it; tests replace it. */
1972
+ interface McpProcess {
1973
+ input: Readable;
1974
+ output: Writable;
1975
+ env: Readonly<Record<string, string | undefined>>;
1976
+ cwd: string;
1977
+ /** Calls `stop` on SIGINT and SIGTERM; returns what removes the handlers. Left out in tests. */
1978
+ onSignal?: (stop: () => void) => () => void;
1979
+ limits?: Partial<McpLimits>;
1980
+ }
1981
+ declare class Repository {
1982
+ #private;
1983
+ readonly root: string;
1984
+ readonly warnings: DetectionWarning[];
1985
+ /** Repository-relative paths of the files that were read, for the log of what doctor checked. */
1986
+ readonly read: Set<string>;
1987
+ constructor(root: string);
1988
+ warn(code: string, message: string, files: readonly string[], line?: number): void;
1989
+ isFile(path: string): boolean;
1990
+ /** Whether the path exists in the repository as something other than a regular file or a directory (a named pipe, a socket, a device). */
1991
+ isSpecialFile(path: string): boolean;
1992
+ /**
1993
+ * The text of a file, without a byte order mark; undefined (with a warning when useful) if it cannot be read. The
1994
+ * limit is that of lockfiles for a lockfile and that of configuration files for the rest (readLimitFor).
1995
+ */
1996
+ readText(path: string, limit?: number): string | undefined;
1997
+ /** The first bytes of a file, e.g. to recognize a lockfile format without reading a large file. */
1998
+ readHead(path: string, bytes?: number): string | undefined;
1999
+ /**
2000
+ * Names of the files in a directory (following symlinks only inside the repository). With `accept`, only the names it
2001
+ * accepts, and only those are resolved and stat-ed (decision D-157): a directory of many files costs one readdir.
2002
+ */
2003
+ listFiles(path: string, accept?: (name: string) => boolean): string[];
2004
+ /** Names of the subdirectories of a directory, skipping node_modules, .git and symlinks that lead outside; `accept` as in listFiles. */
2005
+ listDirectories(path: string, accept?: (name: string) => boolean): string[];
2006
+ /**
2007
+ * The real path of a file or directory of the repository, or undefined if it is missing or leads outside. A directory
2008
+ * known to have no symlink on the way, such as one just listed, costs nothing; the walk of workspace patterns keys
2009
+ * the directories it visited by it, so that a symlink back up does not make it walk them again (decision D-161).
2010
+ */
2011
+ realPath(path: string): string | undefined;
2012
+ /** Parses a file with the given parser, reporting failures as warnings. */
2013
+ parse<T>(path: string, parser: (text: string) => T): T | undefined;
2014
+ /** Like parse, but each file is read and parsed once per parser: several rules read the same file. */
2015
+ parseOnce<T>(path: string, parser: (text: string) => T): T | undefined;
2016
+ relative(absolute: string): string;
2017
+ }
1651
2018
  /** The SARIF levels: an error fails `doctor`, warnings and notes do not. */
1652
2019
  type Level = 'error' | 'warning' | 'note';
1653
2020
  interface Location {
@@ -1667,6 +2034,16 @@ interface Finding {
1667
2034
  location: Location;
1668
2035
  /** A fix for this finding; the rule's general help applies when absent. */
1669
2036
  fix?: string;
2037
+ /**
2038
+ * "default": the repository has no depcurfew.json, and a rule that needs a policy found this by comparing it with the
2039
+ * policy depcurfew init would write (decision D-149). Such a finding is always a note. Absent otherwise.
2040
+ */
2041
+ policy?: 'default';
2042
+ /**
2043
+ * known-malicious: where the answer comes from, api.osv.dev (--osv) or the local copy of the OSV.dev data that
2044
+ * depcurfew osv update writes (decision D-150).
2045
+ */
2046
+ source?: OsvSource;
1670
2047
  }
1671
2048
  /**
1672
2049
  * Something doctor could not check, such as an unreadable file. Not a problem in the repository itself, so it never
@@ -1690,8 +2067,14 @@ interface RuleContext {
1690
2067
  root: string;
1691
2068
  repository: Repository;
1692
2069
  detection: Detection;
1693
- /** undefined when the repository has no depcurfew.json. */
2070
+ /** undefined when the repository has no depcurfew.json (and the rule does not need one). */
1694
2071
  policy: ResolvedPolicy | undefined;
2072
+ /**
2073
+ * true when `policy` is the policy depcurfew init would write, because the repository has no depcurfew.json (decision
2074
+ * D-149): every finding becomes a note that says so, and a rule may word its findings for that (config-drift groups
2075
+ * them by file).
2076
+ */
2077
+ defaultPolicy?: true;
1695
2078
  tools: readonly ToolKnowledge[];
1696
2079
  report(finding: Omit<Finding, 'rule' | 'level'> & {
1697
2080
  level?: Level;
@@ -1714,13 +2097,43 @@ interface RuleContext {
1714
2097
  osv?: OsvDoctor;
1715
2098
  }
1716
2099
  /**
1717
- * What known-malicious gets with --osv: a list to fill with the locked versions (the first run, before OSV.dev is
1718
- * asked), or the answers of OSV.dev by osvKey (the second run, which reports).
2100
+ * What known-malicious gets: a list to fill with the locked versions (the first run, before OSV.dev is asked or the
2101
+ * local data is read), or the answers by osvKey (the second run, which reports). With `local` the answers come from
2102
+ * the local OSV.dev data of depcurfew osv update, without --osv (decision D-150), and `local` says, by ecosystem of
2103
+ * depcurfew, whether there is such data and how old it is. `unavailable`: neither --osv nor any local data, so the
2104
+ * rule only says how to get them.
1719
2105
  */
1720
2106
  type OsvDoctor = {
1721
2107
  collect: OsvPackage[];
1722
2108
  } | {
1723
2109
  answers: ReadonlyMap<string, OsvVerdict>;
2110
+ local?: OsvLocalDoctor;
2111
+ } | {
2112
+ unavailable: true;
2113
+ };
2114
+ /** The local OSV.dev data of each ecosystem, as known-malicious reports it (decision D-150). */
2115
+ interface OsvLocalDoctor {
2116
+ ecosystems: Readonly<Record<string, OsvLocalEcosystem>>;
2117
+ /**
2118
+ * Other users can write a directory of the data (decision D-156): which one and how, and what to do. The rule warns
2119
+ * for each lockfile it checks against the data, which it still uses.
2120
+ */
2121
+ shared?: {
2122
+ reason: string;
2123
+ fix: string;
2124
+ };
2125
+ }
2126
+ /** missing, unreadable with the reason, or ready with its date, its age in days and whether that gives a note or a warning. */
2127
+ type OsvLocalEcosystem = {
2128
+ status: 'missing';
2129
+ } | {
2130
+ status: 'unreadable';
2131
+ reason: string;
2132
+ } | {
2133
+ status: 'ready';
2134
+ date: string;
2135
+ days: number;
2136
+ staleness: 'fresh' | 'note' | 'warning';
1724
2137
  };
1725
2138
  /** A directory listed in projects, as the rules at the repository root see it. */
1726
2139
  interface ProjectView {
@@ -1748,6 +2161,19 @@ interface Rule {
1748
2161
  level: Level;
1749
2162
  /** Rules that compare the repository with depcurfew.json do not run without one. */
1750
2163
  requiresPolicy: boolean;
2164
+ /**
2165
+ * A rule that runs without depcurfew.json but finds more with one: what a policy needs from the package manager
2166
+ * version, or a file that only the rules that need a policy read. Without depcurfew.json it runs once more against
2167
+ * the default policy with those rules, and the errors and warnings it finds only there are notes like theirs
2168
+ * (decision D-154).
2169
+ */
2170
+ alsoWithDefaultPolicy?: true;
2171
+ /**
2172
+ * A rule that runs without a policy and reports facts of the files, not differences from a policy (known-malicious):
2173
+ * without depcurfew.json it also runs in the projects depcurfew init would list, the ones compared with the default
2174
+ * policy, and what it finds there keeps its level, as in the root (decision D-161).
2175
+ */
2176
+ alsoInComparedProjects?: true;
1751
2177
  /**
1752
2178
  * Whether the rule concerns the project at all, from detection: the Python rules without a Python tool, the bot rules
1753
2179
  * without a bot. false shows the rule as "not applicable" in the list of what doctor checked (decision D-098). It
@@ -1783,6 +2209,8 @@ interface RuleResult {
1783
2209
  errors: number;
1784
2210
  warnings: number;
1785
2211
  notes: number;
2212
+ /** "default": the rule needs a policy and ran against the policy depcurfew init would write (decision D-149). */
2213
+ policy?: 'default';
1786
2214
  }
1787
2215
  /** What doctor looked at, shown below the result, so that a clean report says what it covers. */
1788
2216
  interface Checked {
@@ -1798,6 +2226,11 @@ interface DoctorReport {
1798
2226
  schemaVersion: 1;
1799
2227
  /** invalid: depcurfew.json does not follow the schema or cannot be read (only with invalidPolicy: 'report'). */
1800
2228
  policy: 'valid' | 'missing' | 'invalid';
2229
+ /**
2230
+ * The policy the rules that need one ran against (decision D-149): "file" for depcurfew.json, "default" for the policy
2231
+ * depcurfew init would write when there is no depcurfew.json, null when they did not run. Absent in doctor --user.
2232
+ */
2233
+ policySource?: 'file' | 'default' | null;
1801
2234
  findings: Finding[];
1802
2235
  notices: Notice[];
1803
2236
  /** What was checked. */
@@ -1828,6 +2261,7 @@ export declare const APPLY_WARNINGS: {
1828
2261
  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.";
1829
2262
  readonly 'version-not-pinned': "No exact version of a package manager is pinned, so depcurfew configures for the latest version it knows.";
1830
2263
  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.";
2264
+ readonly 'version-in-use-too-old': "Another npm the repository runs than the pinned one (one a declared Node.js comes with, such as Node.js 24 in .nvmrc, or a CI job or Dockerfile installs) lacks a setting apply writes for the release-age delay or a dependency source, so that setting has no effect there; doctor reports the same places as manager-version-too-old. A place that only runs npm ci needs no delay.";
1831
2265
  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.";
1832
2266
  readonly 'no-user-config': "apply --user: the tool has no user-level configuration file, so nothing is written for it.";
1833
2267
  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.";
@@ -1835,27 +2269,31 @@ export declare const APPLY_WARNINGS: {
1835
2269
  readonly 'user-file-uncertain': "apply --user: a library the tool calls decides where its user file is (platformdirs for Poetry and PDM on macOS), and its version cannot be read from files, so apply --user writes where the tool's docs say and names the other files the tool may read.";
1836
2270
  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.";
1837
2271
  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).";
1838
- readonly 'cooldown-not-written': "The release-age delay cannot be written for a tool.";
1839
- 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.";
2272
+ readonly 'cooldown-not-written': "The release-age delay cannot be written for a tool (for Bundler: a source call of the Gemfile apply does not edit, no source \"https://rubygems.org\", or a Gemfile depcurfew cannot read as Ruby does from the line given on, which it then does not edit at all; for pnpm 12.15 and later: include in pnpm-workspace.yaml gives minimumReleaseAge to a config dependency or to a file outside the directory).";
2273
+ 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; a fixed date of uv, PDM or Deno counts as the time since that date.";
1840
2274
  readonly 'cooldown-environment-only': "pip reads no project configuration, so the release-age delay has to be set in the environment where pip runs.";
1841
2275
  readonly 'exclude-pattern-unsupported': "A cooldown exception uses a wildcard the tool does not support, so it is not written.";
1842
- readonly 'exclude-unsupported': "The tool has no setting for cooldown exceptions, so the release-age delay applies to every package.";
2276
+ readonly 'exclude-unsupported': "The tool has no setting for cooldown exceptions, so the release-age delay applies to every package (Bundler: also because the policy has no names for Ruby gems).";
1843
2277
  readonly 'exclude-not-written': "The setting that holds the cooldown exceptions (Composer's config.policy.cooldown.ignore) has a value of a type the tool does not accept there, so apply leaves it as it is and does not add the exceptions; the release-age delay is written.";
1844
2278
  readonly 'exclude-entry-outside-policy': "A cooldown exception in a file without depcurfew's markers (Composer's config.policy.cooldown.ignore) exempts a package that cooldown.exclude does not; apply removes only the entries it wrote, recognised by their reason, and leaves this one.";
1845
2279
  readonly 'allow-pattern-unsupported': "An installScripts.allow entry is a pattern, but the tool takes package names only, so it is not written.";
1846
2280
  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.";
1847
2281
  readonly 'allow-all-unsupported': "The tool has no setting that allows every install script, so installScripts \"allow\" is not written.";
1848
2282
  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, or replaced with the policy's allow-list where the setting is the list itself (Deno's allowScripts, Composer's allow-plugins, which then may be {}), because the policy denies install scripts.";
1849
- 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.";
2283
+ 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, or will once the tool reads the list (Deno before 2.6.0 does not read allowScripts); apply does not remove it.";
1850
2284
  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.";
1851
2285
  readonly 'deny-needs-optional-dependencies': "A package of installScripts.deny takes its binary from an optional dependency (esbuild), but npm leaves optional dependencies out (omit=optional or optional=false in .npmrc, --omit=optional or --no-optional on an install of a CI job or Dockerfile, NPM_CONFIG_OMIT=optional), so the package cannot find its binary after that install.";
1852
2286
  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.";
1853
2287
  readonly 'built-in-list-replaced': "Bun's built-in list of trusted packages is replaced by the policy's allow-list.";
1854
- readonly 'scripts-not-enforceable': "The pinned (with apply --user, the installed) npm or pnpm, or another npm the repository runs (one a declared Node.js comes with, or a CI job or Dockerfile installs), runs every install script and has no allow-list, so \"deny\" cannot be enforced; also given for an npm the repository runs whose version depcurfew cannot tell, which counts as one that runs them.";
2288
+ readonly 'scripts-not-enforceable': "The pinned (with apply --user, the installed) npm or pnpm, or another npm the repository runs (one a declared Node.js comes with, or a CI job or Dockerfile installs), runs every install script and has no allow-list, so \"deny\" cannot be enforced; also given for an npm the repository runs whose version depcurfew cannot tell, which counts as one that runs them, and for Bundler, which builds the native extensions of gems at install time and has no setting that stops it.";
1855
2289
  readonly 'strict-allow-scripts-for-npm-in-use': "An npm the repository runs (the pinned one, one a CI job or Dockerfile installs, or one a declared Node.js comes with, for a project also through the root version files and root Dockerfiles that build it) is 11.16 to 11.x and runs install scripts the allow-list does not cover unless strict-allow-scripts is set, so apply writes strict-allow-scripts=true, which makes npm 12 stop the install at such a script; not given when that npm is the pinned one and no place runs npm 12.";
1856
2290
  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).";
1857
2291
  readonly 'exact-version-gap': "The pinned (with apply --user, the installed) pnpm skips the release-age delay for packages requested by exact version.";
1858
- readonly 'source-not-enforceable': "The tool has no setting for a dependency source the policy denies; doctor checks the lockfile instead.";
2292
+ readonly 'setting-owned-elsewhere': "pnpm 12.15 and later: include in pnpm-workspace.yaml gives a setting the policy needs to a config dependency or to a file outside the directory, so apply does not write it (pnpm refuses a setting with two owners, ERR_PNPM_DUPLICATE_SETTING) and cannot check its value; the release-age delay itself gives cooldown-not-written.";
2293
+ readonly 'source-not-enforceable': "The tool has no setting for a dependency source the policy denies; doctor checks the lockfile instead, where it reads it (not Gemfile.lock).";
2294
+ readonly 'source-loosened': "A dependency-source setting outside depcurfew's markers is stricter than the policy (npm's allow-file or allow-directory none or root, pnpm's blockExoticSubdeps true, a Yarn approvedGitRepositories list without **), and apply replaces it with the value the policy's \"allow\" gives.";
2295
+ readonly 'security-delay-removed': "Renovate delays security updates (vulnerabilityAlerts.minimumReleaseAge), but cooldown.securityUpdates is \"bypass\", so apply sets it to null and Renovate proposes them at once.";
2296
+ readonly 'exclusion-dropped': "A cooldown exception set outside depcurfew's markers (an entry of npm's min-release-age-exclude, pnpm's minimumReleaseAgeExclude, Yarn's npmPreapprovedPackages, Bun's minimumReleaseAgeExcludes, Deno's minimumDependencyAge.exclude, uv's exclude-newer-package, PDM's exclude-newer-override, Poetry's min-release-age-exclude or Dependabot's cooldown.exclude) is not in cooldown.exclude, so apply comments it out (removes it in JSON), and the package waits again.";
1859
2297
  readonly 'source-switch-indirect-only': "The pnpm setting for git and tarball sources stops them only for indirect dependencies.";
1860
2298
  readonly 'source-switch-combined': "One pnpm setting covers git and tarball sources, so denying one denies both.";
1861
2299
  readonly 'forced-source-build': "Python packages on the allow-list are always built from source, because no tool can only allow a build.";
@@ -1863,18 +2301,20 @@ export declare const APPLY_WARNINGS: {
1863
2301
  readonly 'build-switch-install-only': "Poetry applies its build switch when installing; poetry lock may still build source distributions.";
1864
2302
  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.";
1865
2303
  readonly 'requirements-file-missing': "There is no requirements file to write pip options into.";
1866
- readonly 'manifest-missing': "A setting belongs in a project manifest (package.json, deno.json, pyproject.toml, Pipfile, composer.json) that does not exist, and apply does not create manifests.";
2304
+ readonly 'build-switch-undone': "A line of a requirements file pip reads (requirements.txt or a file it includes with -r or -c) has --no-binary or --only-binary=:none:, which undoes the --only-binary=:all: apply writes, and apply cannot comment it out: the option follows a requirement, shares its line with other options or continues on the next line.";
2305
+ readonly 'requirements-include-unread': "A requirements file pip reads includes another one (-r, -c) that apply cannot check for lines that undo --only-binary=:all: (a URL, a path outside the directory configured, a missing file, or a file it cannot read).";
2306
+ readonly 'manifest-missing': "A setting belongs in a project manifest (package.json, deno.json, pyproject.toml, Pipfile, composer.json, Gemfile) that does not exist, and apply does not create manifests.";
1867
2307
  readonly 'lockfile-out-of-date': "The lockfile records, or is checked against, a setting apply changed, so it has to be locked again.";
1868
2308
  readonly 'file-ignored-by-git': "A file apply writes matches a .gitignore rule, so the change may never reach the repository.";
1869
2309
  readonly 'bot-config-missing': "A bot has no configuration file, and depcurfew does not create one.";
1870
2310
  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.";
1871
2311
  readonly 'bot-entries-missing': "The Dependabot configuration has no entries for the package managers in use.";
1872
2312
  readonly 'bot-config-unreadable': "The Dependabot configuration uses a YAML alias, which Dependabot does not accept, so it reads no configuration from the file (the cooldown apply writes included), and depcurfew does not read the delays the file sets.";
1873
- readonly 'bot-rule-shortens-delay': "A Renovate packageRules entry apply does not manage gives every package of a registry, Renovate manager or category in use, or the actions of the workflows, or some update types of them, a shorter release-age delay than the one apply writes; Renovate uses it, and apply does not change it.";
2313
+ readonly 'bot-rule-shortens-delay': "A Renovate packageRules entry apply does not manage gives every package of a registry, Renovate manager or category in use, the actions of the workflows or the dependencies of an ecosystem updated by bots only (Cargo, Go modules, Maven, Gradle, NuGet), or some update types of them, a shorter release-age delay than the one apply writes; or a Dependabot updates entry apply writes the cooldown into has a cooldown.include list, which limits the cooldown to the dependencies it names, or keeps a cooldown.exclude list that matches every dependency (an entry for actions, Ruby gems or an ecosystem updated by bots only, whose list apply does not replace). The bot uses these, and apply does not change them.";
1874
2314
  readonly 'security-delay-unsupported': "Dependabot cannot delay security updates, so securityUpdates \"delay\" is not applied.";
1875
2315
  };
1876
2316
  export declare const APPLY_ERRORS: {
1877
- 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.";
2317
+ readonly 'cannot-edit': "A file cannot be read or edited safely (invalid syntax, a symlink, a style depcurfew does not edit, a file over the size depcurfew reads, 1 MiB for configuration and 64 MiB for lockfiles, also one that the change would make larger than that), so nothing is written.";
1878
2318
  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.";
1879
2319
  readonly 'policy-missing': "The directory has no depcurfew.json.";
1880
2320
  readonly 'policy-invalid': "depcurfew.json does not follow the schema; issues lists the problems.";
@@ -1942,6 +2382,11 @@ declare class WriteFailed extends Error {
1942
2382
  leftovers?: string[];
1943
2383
  });
1944
2384
  }
2385
+ /** The owner a replaced file keeps when depcurfew runs as root, or a new file gets (WriteOptions.ownerOfNew). */
2386
+ interface Owner {
2387
+ uid: number;
2388
+ gid: number;
2389
+ }
1945
2390
  interface Snippet {
1946
2391
  tool: ToolId;
1947
2392
  file: string;
@@ -2017,6 +2462,12 @@ interface PlanOptions {
2017
2462
  * of its own, and the stages of root Dockerfiles that build it; rootPlaces gives them.
2018
2463
  */
2019
2464
  root?: RootPlaces;
2465
+ /**
2466
+ * The versions root CI jobs set up for a package manager of the project: the setup steps of jobs whose run steps all
2467
+ * work in its directory (working-directory: backend, decision D-173); rootCiVersions gives them. They count after the
2468
+ * project's own declarations.
2469
+ */
2470
+ pins?: Readonly<Partial<Record<ToolId, readonly VersionDeclaration[]>>>;
2020
2471
  }
2021
2472
  /** The bots' delay: the policy's, or longer if a package manager rounded its delay up further. */
2022
2473
  export declare function botDuration(policy: Duration, managerMinutes: readonly number[]): Duration;
@@ -2108,6 +2559,11 @@ interface CheckDependencies {
2108
2559
  platform?: () => NodeJS.Platform;
2109
2560
  /** depcurfew mcp: the streams the server talks over, its environment and signals (tests replace them). */
2110
2561
  mcpProcess?: () => McpProcess;
2562
+ /**
2563
+ * The directory of the local OSV.dev data that depcurfew osv update writes (decision D-150); undefined for none. By
2564
+ * default the one in depcurfew's user cache directory; tests replace it.
2565
+ */
2566
+ osvData?: () => string | undefined;
2111
2567
  }
2112
2568
  export declare function run(argv: readonly string[], output: CliIo, dependencies?: CheckDependencies): Promise<number>;
2113
2569
  export declare function getVersion(): string;
@@ -2242,6 +2698,11 @@ interface InstallRequest {
2242
2698
  word: string;
2243
2699
  command: string;
2244
2700
  };
2701
+ /**
2702
+ * npm link: the command links the package into the project, and installs it from the registry only when the global
2703
+ * space has no package of that name (decision D-172).
2704
+ */
2705
+ linked?: true;
2245
2706
  }
2246
2707
  /** An option or variable of a command that weakens the release-age delay or the rule on install scripts (installOverrides). */
2247
2708
  interface Override {
@@ -2268,6 +2729,13 @@ interface CommandScan {
2268
2729
  requests: InstallRequest[];
2269
2730
  /** Why an install command could not be read; undefined when every one could. */
2270
2731
  unreadable: string | undefined;
2732
+ /**
2733
+ * scanCommandLine: the packages of the line read once more with the options that point a tool at another registry,
2734
+ * index or configuration file read like any other option (decision D-155) and the words the shell expands among the
2735
+ * arguments of an install passed over (decision D-160), when such an option or word left a command out. They are not
2736
+ * checked against a registry; the hook looks up the versions they name exactly in the local OSV.dev data.
2737
+ */
2738
+ aside?: InstallRequest[];
2271
2739
  /** Options and variables that weaken what depcurfew apply configured, to be compared with the policy. */
2272
2740
  overrides?: Override[];
2273
2741
  /** A command on the line changes the package manager's configuration; it counts when the line installs packages. */
@@ -2286,13 +2754,27 @@ interface ScanOptions {
2286
2754
  */
2287
2755
  windows?: boolean;
2288
2756
  }
2289
- /** The packages a command line installs or downloads to run with npm, pnpm, Yarn, Bun, Deno, pip, uv, Poetry, PDM, Pipenv or pipx. */
2757
+ /**
2758
+ * The packages a command line installs or downloads to run with npm, pnpm, Yarn, Bun, Deno, pip, uv, Poetry, PDM, Pipenv
2759
+ * or pipx. When an option that points a tool at another registry, index or configuration file, or a word the shell
2760
+ * expands among the arguments of an install, left a command out, the line is read once more with such options read like
2761
+ * any other and such words passed over, and its packages are `aside` (decisions D-155 and D-160).
2762
+ */
2290
2763
  export declare function scanCommandLine(line: string, options?: ScanOptions): CommandScan;
2291
2764
  interface DetectOptions {
2292
2765
  /** The directories listed in projects in depcurfew.json, relative to the root (decision D-137). */
2293
2766
  projects?: readonly string[];
2294
2767
  }
2768
+ /**
2769
+ * Describes the repository at `root`. Never executes anything from the repository and never leaves it;
2770
+ * problems with individual files become warnings.
2771
+ */
2295
2772
  export declare function detectProject(root: string, tools?: readonly ToolKnowledge[], environment?: EnvironmentKnowledge, options?: DetectOptions): Detection;
2773
+ declare class Detections {
2774
+ #private;
2775
+ /** detectProject(root, tools, undefined, options), the first time for this directory, these tools and these projects. */
2776
+ detect(root: string, tools?: readonly ToolKnowledge[], options?: DetectOptions): Detection;
2777
+ }
2296
2778
  /** Every doctor rule, in the order they are documented. unreadable-config runs last, after every other rule has read its files. */
2297
2779
  export declare const RULES: readonly Rule[];
2298
2780
  type FailOn = (typeof FAIL_ON_LEVELS)[number];
@@ -2329,7 +2811,13 @@ export declare function toSarif(report: DoctorReport, rules: readonly Rule[], ve
2329
2811
  * invalidPolicy: 'report' runs the rules that need no policy and reports the problems as an invalid-policy finding.
2330
2812
  * `policy` passes the policy in instead of reading depcurfew.json (null: run as without one). With projects in the
2331
2813
  * policy, the rules also run on every listed directory with the same policy, and the report covers them all, with
2332
- * paths relative to the root (decision D-100).
2814
+ * paths relative to the root (decision D-100). `defaultPolicy`, for a repository without depcurfew.json: the policy
2815
+ * depcurfew init would write (initialResolvedPolicy), which the rules that need a policy then run against; every
2816
+ * finding of theirs is a note with `policy: "default"` (decision D-149). Without it those rules do not run.
2817
+ * `detections`: the detections to share with the caller, e.g. with comparedPolicy; the runs of one call share
2818
+ * theirs anyway, so each directory is detected once (decision D-157). With `defaultPolicy`, a rule with
2819
+ * alsoInComparedProjects (known-malicious) also runs in the projects of that policy, and its findings there keep their
2820
+ * level (decision D-161).
2333
2821
  */
2334
2822
  export declare function runDoctor(root: string, options?: {
2335
2823
  rules?: readonly Rule[];
@@ -2337,12 +2825,86 @@ export declare function runDoctor(root: string, options?: {
2337
2825
  invalidPolicy?: 'throw' | 'report';
2338
2826
  policy?: ResolvedPolicy | null;
2339
2827
  osv?: OsvDoctor;
2828
+ defaultPolicy?: ResolvedPolicy;
2829
+ detections?: Detections;
2340
2830
  }): DoctorReport;
2341
2831
  /**
2342
2832
  * runDoctor with known-malicious: the locked versions are looked up in OSV.dev first. Throws PolicyError as runDoctor
2343
2833
  * does for an invalid depcurfew.json, unless asked to report it.
2344
2834
  */
2345
- export declare function runDoctorWithOsv(root: string, options: Omit<Parameters<typeof runDoctor>[1] & object, 'osv'>, osv: OsvOptions): Promise<DoctorReport>;
2835
+ export declare function runDoctorWithOsv(root: string, options: Omit<Parameters<typeof runDoctor>[1] & object, 'osv'>, osv: OsvOptions & {
2836
+ local?: OsvLocalLookup | undefined;
2837
+ }): Promise<DoctorReport>;
2838
+ /**
2839
+ * runDoctor without --osv: with the local OSV.dev data when any exists, else with the note that says how to get it
2840
+ * (decision D-150). Nothing leaves the machine.
2841
+ */
2842
+ export declare function runDoctorWithLocalOsv(root: string, options: Omit<Parameters<typeof runDoctor>[1] & object, 'osv'>, local: LocalOsvData, now: Date): DoctorReport;
2843
+ interface ZipLimits {
2844
+ /** Most entries in the central directory. */
2845
+ entries: number;
2846
+ /** Largest central directory, in bytes. */
2847
+ centralDirectoryBytes: number;
2848
+ /** Largest compressed entry that is inflated. */
2849
+ entryCompressedBytes: number;
2850
+ /** Largest entry, inflated. */
2851
+ entryBytes: number;
2852
+ /** Most bytes an entry may inflate to per compressed byte. */
2853
+ ratio: number;
2854
+ /** Most bytes all the entries read may inflate to together. */
2855
+ totalBytes: number;
2856
+ }
2857
+ /** The codes of the errors of depcurfew osv update. */
2858
+ type OsvUpdateCode = 'osv-download-failed' | 'osv-export-unreadable' | 'osv-export-shrunk' | 'osv-data-not-written' | 'osv-cache-missing';
2859
+ type OsvUpdateResult = {
2860
+ ecosystem: OsvDataEcosystem;
2861
+ status: 'updated';
2862
+ /** The file written. */
2863
+ file: string;
2864
+ url: string;
2865
+ downloadedAt: string;
2866
+ exportedAt: string | null;
2867
+ /** MAL- records kept, left out as withdrawn, and left out because they cannot be read or name no version of a package of the ecosystem. */
2868
+ records: number;
2869
+ withdrawn: number;
2870
+ skipped: number;
2871
+ /** MAL- records left out because they hold more than depcurfew keeps (OSV_DATA_LIMITS, decision D-156). */
2872
+ tooLarge: number;
2873
+ /** The size of the export downloaded. */
2874
+ bytes: number;
2875
+ } | {
2876
+ ecosystem: OsvDataEcosystem;
2877
+ status: 'failed';
2878
+ file: string;
2879
+ url: string;
2880
+ code: OsvUpdateCode;
2881
+ message: string;
2882
+ fix: string;
2883
+ };
2884
+ interface OsvUpdateOptions {
2885
+ /** The directory of the local data. */
2886
+ directory: string;
2887
+ ecosystems: readonly OsvDataEcosystem[];
2888
+ fetch: FetchLike;
2889
+ now: () => Date;
2890
+ signal?: AbortSignal;
2891
+ /** Largest export; MAX_EXPORT_BYTES when left out. */
2892
+ maxBytes?: number;
2893
+ timeoutMs?: number;
2894
+ zipLimits?: ZipLimits;
2895
+ /** What is kept; OSV_DATA_LIMITS when left out. */
2896
+ dataLimits?: Readonly<OsvDataLimits>;
2897
+ /** Replace the data also with an export that has fewer than half of its records (--accept-fewer, decision D-156). */
2898
+ acceptFewer?: boolean;
2899
+ /**
2900
+ * Who gets the directories and the data file osv update creates, by their real paths (ownerOfNewUnderHome): the owner
2901
+ * of the home directory when root runs it there for another user (decision D-168); left out, they are the running
2902
+ * user's.
2903
+ */
2904
+ ownerOfNew?: (path: string) => Owner | undefined;
2905
+ }
2906
+ /** Updates the local data of each ecosystem in turn; one that fails does not stop the others. */
2907
+ export declare function updateOsvData(options: OsvUpdateOptions): Promise<OsvUpdateResult[]>;
2346
2908
  type NumericDelayUnit = Exclude<DelayUnit, 'duration-string'>;
2347
2909
  declare const DURATION_STRING_UNITS: readonly ["minutes", "hours", "days", "weeks"];
2348
2910
  type DurationStringUnit = (typeof DURATION_STRING_UNITS)[number];
@@ -2413,4 +2975,4 @@ export declare function validatePolicy(document: unknown, tools?: readonly ToolK
2413
2975
  /** Parses and validates the text of a policy file. */
2414
2976
  export declare function parsePolicy(source: string, tools?: readonly ToolKnowledge[]): PolicyResult;
2415
2977
  export declare function formatIssue(issue: PolicyIssue): string;
2416
- export type { ApplyErrorCode, ApplyProblem, ApplyReport, ApplyWarning, ApplyWarningCode, CheckFinding, CheckOptions, CliIo, CommandDirectory, CommandScan, Converted, CooldownConversion, DetectOptions, Detection, DetectionWarning, DoctorReport, Duration, DurationResult, DurationStringUnit, FileChange, Finding, FindingCode, InstallRequest, KnownDirectory, Level, Location, Notice, NumericDelayUnit, OsvOptions, OsvPackage, OsvVerdict, PackageManagerInfo, PackageReport, PlanOptions, Policy, PolicyIssue, PolicyResult, ProjectProblem, ResolvedPolicy, Rule, ScanOptions, Snippet, VersionDeclaration };
2978
+ export type { ApplyErrorCode, ApplyProblem, ApplyReport, ApplyWarning, ApplyWarningCode, CheckFinding, CheckOptions, CliIo, CommandDirectory, CommandScan, Converted, CooldownConversion, DetectOptions, Detection, DetectionWarning, DoctorReport, Duration, DurationResult, DurationStringUnit, FileChange, Finding, FindingCode, InstallRequest, KnownDirectory, Level, LocalOsvDataOptions, Location, Notice, NumericDelayUnit, OsvDataLimits, OsvDataState, OsvOptions, OsvPackage, OsvSource, OsvUpdateOptions, OsvUpdateResult, OsvVerdict, PackageManagerInfo, PackageReport, PlanOptions, Policy, PolicyIssue, PolicyResult, ProjectProblem, ResolvedPolicy, Rule, ScanOptions, Snippet, VersionDeclaration };