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/README.md +249 -96
- package/dist/cli.js +1 -1
- package/dist/index.d.ts +671 -109
- package/dist/index.js +2 -2
- package/dist/{run-NcyQxpTd.js → run-CRuq8qDb.js} +35358 -22925
- package/package.json +4 -2
- package/schema.json +2 -1
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
|
-
/**
|
|
5
|
-
|
|
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
|
-
/**
|
|
122
|
-
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
1718
|
-
*
|
|
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 '
|
|
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 '
|
|
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,
|
|
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
|
-
/**
|
|
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
|
|
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 };
|