1package npmpackage
2
3import (
4 "strings"
5 "net"
6 "list"
7 "cue.dev/x/npmjs/eslint"
8 "cue.dev/x/npmjs/prettier"
9 "cue.dev/x/npmjs/stylelint"
10 "cue.dev/x/npmjs/ava"
11 "cue.dev/x/semanticrelease"
12 "cue.dev/x/npmjs/jscpd"
13 "cue.dev/x/npmjs/madge"
14 "cue.dev/x/npmjs/nodemon"
15 "cue.dev/x/npmjs/quikrun"
16)
17
18// JSON schema for NPM package.json files
19#Schema: {
20 @jsonschema(schema="http://json-schema.org/draft-07/schema#")
21 _schema
22 _schema: {
23 @jsonschema(id="https://json.schemastore.org/package.json")
24 {[=~"^_"]: _}
25
26 // The name of the package.
27 name?: strings.MaxRunes(214) & strings.MinRunes(1)
28
29 // Version must be parsable by node-semver, which is bundled with npm as a dependency.
30 version?: string
31
32 // This helps people discover your package, as it's listed in 'npm search'.
33 description?: string
34
35 // This helps people discover your package as it's listed in 'npm search'.
36 keywords?: [...string]
37
38 // The url to the project homepage.
39 homepage?: string
40
41 // The url to your project's issue tracker and / or the email address to which
42 // issues should be reported. These are helpful for people who encounter issues
43 // with your package.
44 bugs?: string | {
45 // The url to your project's issue tracker.
46 url?: net.AbsURL
47
48 // The email address to which issues should be reported.
49 email?: string
50 ...
51 }
52 license?: #license
53
54 // DEPRECATED: Instead, use SPDX expressions, like this: { "license": "ISC" } or
55 // { "license": "(MIT OR Apache-2.0)" } see:
56 // 'https://docs.npmjs.com/files/package.json#license'.
57 licenses?: [...{
58 type?: #license
59 url?: net.AbsURL
60 ...
61 }]
62 author?: #person
63
64 // A list of people who contributed to this package.
65 contributors?: [...#person]
66
67 // A list of people who maintains this package.
68 maintainers?: [...#person]
69
70 // The 'files' field is an array of files to include in your project. If you
71 // name a folder in the array, then it will also include the files inside that
72 // folder.
73 files?: [...string]
74
75 // The main field is a module ID that is the primary entry point to your program.
76 main?: string
77
78 // The "exports" field is used to restrict external access to non-exported
79 // module files, also enables a module to import itself using "name".
80 exports?: matchN(1, [
81 #packageExportsEntryPath,
82 close({
83 "."?: #packageExportsEntryOrFallback
84
85 {[=~"^\\./.+"]: #packageExportsEntryOrFallback}
86 }),
87 #packageExportsEntryObject,
88 #packageExportsFallback
89 ])
90
91 // The "imports" field is used to create private mappings that only apply to
92 // import specifiers from within the package itself.
93 imports?: close({
94
95 {[=~"^#.+$"]: #packageImportsEntryOrFallback}})
96 bin?: string | {[string]: string}
97
98 // When set to "module", the type field allows a package to specify all .js
99 // files within are ES modules. If the "type" field is omitted or set to
100 // "commonjs", all .js files are treated as CommonJS.
101 type?: "commonjs" | "module"
102
103 // Set the types property to point to your bundled declaration file.
104 types?: string
105
106 // Note that the "typings" field is synonymous with "types", and could be used as well.
107 typings?: string
108
109 // The "typesVersions" field is used since TypeScript 3.1 to support features
110 // that were only made available in newer TypeScript versions.
111 typesVersions?: [string]: close({
112 // Maps all file paths to the file paths specified in the array.
113 "*"?: [...=~"^[^*]*(?:\\*[^*]*)?$"]
114
115 {[=~"^[^*]+$"]: [...string]}
116
117 {[=~"^[^*]*\\*[^*]*$"]: [...=~"^[^*]*(?:\\*[^*]*)?$"]}
118 })
119
120 // Specify either a single file or an array of filenames to put in place for the
121 // man program to find.
122 man?: string | [...string]
123 directories?: {
124 // If you specify a 'bin' directory, then all the files in that folder will be
125 // used as the 'bin' hash.
126 bin?: string
127
128 // Put markdown files in here. Eventually, these will be displayed nicely, maybe, someday.
129 doc?: string
130
131 // Put example scripts in here. Someday, it might be exposed in some clever way.
132 example?: string
133
134 // Tell people where the bulk of your library is. Nothing special is done with
135 // the lib folder in any way, but it's useful meta info.
136 lib?: string
137
138 // A folder that is full of man pages. Sugar to generate a 'man' array by walking the folder.
139 man?: string
140 test?: string
141 ...
142 }
143
144 // Specify the place where your code lives. This is helpful for people who want to contribute.
145 repository?: string | {
146 type?: string
147 url?: string
148 directory?: string
149 ...
150 }
151 funding?: matchN(1, [
152 #fundingUrl,
153 #fundingWay,
154 list.MinItems(1) & list.UniqueItems() & [...matchN(1, [#fundingUrl, #fundingWay])]
155 ])
156
157 // The 'scripts' member is an object hash of script commands that are run at
158 // various times in the lifecycle of your package. The key is the lifecycle
159 // event, and the value is the command to run at that point.
160 scripts?: {
161 // Run code quality tools, e.g. ESLint, TSLint, etc.
162 lint?: string
163
164 // Run BEFORE the package is published (Also run on local npm install without any arguments).
165 prepublish?: string
166
167 // Runs BEFORE the package is packed, i.e. during "npm publish" and "npm pack",
168 // and on local "npm install" without any arguments. This is run AFTER
169 // "prepublish", but BEFORE "prepublishOnly".
170 prepare?: string
171
172 // Run BEFORE the package is prepared and packed, ONLY on npm publish.
173 prepublishOnly?: string
174
175 // run BEFORE a tarball is packed (on npm pack, npm publish, and when installing git dependencies).
176 prepack?: string
177
178 // Run AFTER the tarball has been generated and moved to its final destination.
179 postpack?: string
180
181 // Publishes a package to the registry so that it can be installed by name. See
182 // https://docs.npmjs.com/cli/v8/commands/npm-publish
183 publish?: string
184 postpublish?: #scriptsPublishAfter
185
186 // Run BEFORE the package is installed.
187 preinstall?: string
188 install?: #scriptsInstallAfter
189 postinstall?: #scriptsInstallAfter
190 preuninstall?: #scriptsUninstallBefore
191 uninstall?: #scriptsUninstallBefore
192
193 // Run AFTER the package is uninstalled.
194 postuninstall?: string
195 preversion?: #scriptsVersionBefore
196 version?: #scriptsVersionBefore
197
198 // Run AFTER bump the package version.
199 postversion?: string
200 pretest?: #scriptsTest
201 test?: #scriptsTest
202 posttest?: #scriptsTest
203 prestop?: #scriptsStop
204 stop?: #scriptsStop
205 poststop?: #scriptsStop
206 prestart?: #scriptsStart
207 start?: #scriptsStart
208 poststart?: #scriptsStart
209 prerestart?: #scriptsRestart
210 restart?: #scriptsRestart
211 postrestart?: #scriptsRestart
212
213 // Start dev server to serve application files
214 serve?: string
215 {[!~"^(lint|prepublish|prepare|prepublishOnly|prepack|postpack|publish|postpublish|preinstall|install|postinstall|preuninstall|uninstall|postuninstall|preversion|version|postversion|pretest|test|posttest|prestop|stop|poststop|prestart|start|poststart|prerestart|restart|postrestart|serve)$"]: string}
216 }
217
218 // A 'config' hash can be used to set configuration parameters used in package
219 // scripts that persist across upgrades.
220 config?: {...}
221 dependencies?: #dependency
222 devDependencies?: #devDependency
223 optionalDependencies?: #optionalDependency
224 peerDependencies?: #peerDependency
225 peerDependenciesMeta?: #peerDependencyMeta
226
227 // Array of package names that will be bundled when publishing the package.
228 bundleDependencies?: matchN(1, [[...string], bool])
229
230 // DEPRECATED: This field is honored, but "bundleDependencies" is the correct
231 // field name. Ignored if "bundleDependencies" is also present.
232 bundledDependencies?: matchN(1, [[...string], bool])
233
234 // Resolutions is used to support selective version resolutions using yarn,
235 // which lets you define custom package versions or ranges inside your
236 // dependencies. For npm, use overrides instead. See:
237 // https://yarnpkg.com/configuration/manifest#resolutions
238 resolutions?: {...}
239
240 // Overrides is used to support selective version overrides using npm, which
241 // lets you define custom package versions or ranges inside your dependencies.
242 // For yarn, use resolutions instead. See:
243 // https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides
244 overrides?: {...}
245
246 // Defines which package manager is expected to be used when working on the
247 // current project. This field is currently experimental and needs to be
248 // opted-in; see https://nodejs.org/api/corepack.html
249 packageManager?: matchN(1, [=~"(npm|pnpm|yarn|bun|aube|nub)@\\d+\\.\\d+\\.\\d+(-.+)?", "bun"])
250 engines?: {
251 node?: string
252
253 // Specifies which JavaScript runtimes (like Node.js, Deno, Bun) are supported.
254 // Values should use WinterCG Runtime Keys (see
255 // https://runtime-keys.proposal.wintercg.org/).
256 runtime?: matchN(1, [#runtimeEngineDependency, [...#runtimeEngineDependency]])
257 {[!~"^(node|runtime)$"]: string}
258 }
259
260 // Defines which tools and versions are expected to be used when Volta is installed.
261 volta?: {
262 // The value of that entry should be a path to another JSON file which also has a "volta" section
263 extends?: string
264
265 {[=~"(node|npm|pnpm|yarn)"]: string}
266 ...
267 }
268 engineStrict?: bool
269
270 // Specify which operating systems your module will run on.
271 os?: [...string]
272
273 // Specify that your code only runs on certain cpu architectures.
274 cpu?: [...string]
275
276 // Define the runtime and package manager for developing the current project.
277 devEngines?: {
278 // Specifies which operating systems are supported for development
279 os?: matchN(1, [#devEngineDependency, [...#devEngineDependency]])
280
281 // Specifies which CPU architectures are supported for development
282 cpu?: matchN(1, [#devEngineDependency, [...#devEngineDependency]])
283
284 // Specifies which C standard libraries are supported for development
285 libc?: matchN(1, [#devEngineDependency, [...#devEngineDependency]])
286
287 // Specifies which JavaScript runtimes (like Node.js, Deno, Bun) are supported
288 // for development. Values should use WinterCG Runtime Keys (see
289 // https://runtime-keys.proposal.wintercg.org/)
290 runtime?: matchN(1, [#devEngineDependency, [...#devEngineDependency]])
291
292 // Specifies which package managers are supported for development
293 packageManager?: matchN(1, [#devEngineDependency, [...#devEngineDependency]])
294 ...
295 }
296
297 // DEPRECATED: This option used to trigger an npm warning, but it will no longer
298 // warn. It is purely there for informational purposes. It is now recommended
299 // that you install any binaries as local devDependencies wherever possible.
300 preferGlobal?: bool
301
302 // If set to true, then npm will refuse to publish it.
303 private?: matchN(1, [bool, "false" | "true"])
304 publishConfig?: {
305 access?: "public" | "restricted"
306 tag?: string
307 registry?: net.AbsURL
308 provenance?: bool
309 ...
310 }
311 dist?: {
312 shasum?: string
313 tarball?: string
314 ...
315 }
316 readme?: string
317
318 // An ECMAScript module ID that is the primary entry point to your program.
319 module?: string
320
321 // A module ID with untranspiled code that is the primary entry point to your program.
322 esnext?: string | {
323 main?: string
324 browser?: string
325 {[!~"^(main|browser)$"]: string}
326 }
327
328 // Allows packages within a directory to depend on one another using direct
329 // linking of local files. Additionally, dependencies within a workspace are
330 // hoisted to the workspace root when possible to reduce duplication. Note:
331 // It's also a good idea to set "private" to true when using this feature.
332 workspaces?: matchN(>=1, [
333 [...string],
334 {
335 // Workspace package paths. Glob patterns are supported.
336 packages?: [...string]
337
338 // Packages to block from hoisting to the workspace root. Currently only supported in Yarn only.
339 nohoist?: [...string]
340 ...
341 }
342 ])
343 jspm?: _schema
344 eslintConfig?: eslint.#Schema
345 "prettier"?: prettier.#Schema
346 "stylelint"?: stylelint.#Schema
347 "ava"?: ava.#Schema
348 release?: semanticrelease.#Schema
349 "jscpd"?: jscpd.#Schema
350 "madge"?: madge.#Schema
351 nodemonConfig?: nodemon.#Schema
352 "quikrun"?: quikrun.#Schema
353
354 // Defines pnpm specific configuration.
355 pnpm?: close({
356 // Used to override any dependency in the dependency graph.
357 overrides?: {...}
358
359 // Used to extend the existing package definitions with additional information.
360 packageExtensions?: close({
361
362 {
363 [=~"^.+$"]: close({
364 dependencies?: #dependency
365 optionalDependencies?: #optionalDependency
366 peerDependencies?: #peerDependency
367 peerDependenciesMeta?: #peerDependencyMeta
368 })
369 }})
370 peerDependencyRules?: close({
371 // pnpm will not print warnings about missing peer dependencies from this list.
372 ignoreMissing?: [...string]
373
374 // Unmet peer dependency warnings will not be printed for peer dependencies of the specified range.
375 allowedVersions?: {...}
376
377 // Any peer dependency matching the pattern will be resolved from any version,
378 // regardless of the range specified in "peerDependencies".
379 allowAny?: [...string]
380 })
381
382 // A list of dependencies to run builds for.
383 neverBuiltDependencies?: [...string]
384
385 // A list of package names that are allowed to be executed during installation.
386 onlyBuiltDependencies?: [...string]
387
388 // Specifies a JSON file that lists the only packages permitted to run
389 // installation scripts during the pnpm install process.
390 onlyBuiltDependenciesFile?: string
391
392 // A list of package names that should not be built during installation.
393 ignoredBuiltDependencies?: [...string]
394
395 // A list of deprecated versions that the warnings are suppressed.
396 allowedDeprecatedVersions?: {...}
397
398 // A list of dependencies that are patched.
399 patchedDependencies?: {...}
400
401 // When true, installation won't fail if some of the patches from the
402 // "patchedDependencies" field were not applied.
403 allowNonAppliedPatches?: bool
404
405 // When true, installation won't fail if some of the patches from the
406 // "patchedDependencies" field were not applied.
407 allowUnusedPatches?: bool
408 updateConfig?: close({
409 // A list of packages that should be ignored when running "pnpm outdated" or "pnpm update --latest".
410 ignoreDependencies?: [...string]
411 })
412
413 // Configurational dependencies are installed before all the other types of
414 // dependencies (before 'dependencies', 'devDependencies',
415 // 'optionalDependencies').
416 configDependencies?: {...}
417 auditConfig?: close({
418 // A list of CVE IDs that will be ignored by "pnpm audit".
419 ignoreCves?: [...=~"^CVE-\\d{4}-\\d{4,7}$"]
420
421 // A list of GHSA Codes that will be ignored by "pnpm audit".
422 ignoreGhsas?: [...=~"^GHSA(-[23456789cfghjmpqrvwx]{4}){3}$"]
423 })
424
425 // A list of scripts that must exist in each project.
426 requiredScripts?: [...string]
427
428 // Specifies architectures for which you'd like to install optional
429 // dependencies, even if they don't match the architecture of the system
430 // running the install.
431 supportedArchitectures?: close({
432 os?: [...string]
433 cpu?: [...string]
434 libc?: [...string]
435 })
436
437 // A list of optional dependencies that the install should be skipped.
438 ignoredOptionalDependencies?: [...string]
439 executionEnv?: close({
440 // Specifies which exact Node.js version should be used for the project's runtime.
441 nodeVersion?: string
442 })
443 })
444
445 // Defines the StackBlitz configuration for the project.
446 stackblitz?: close({
447 // StackBlitz automatically installs npm dependencies when opening a project.
448 installDependencies?: bool
449
450 // A terminal command to be executed when opening the project, after installing npm dependencies.
451 startCommand?: bool | string
452
453 // The compileTrigger option controls how file changes in the editor are written
454 // to the WebContainers in-memory filesystem.
455 compileTrigger?: "auto" | "keystroke" | "save"
456
457 // A map of default environment variables that will be set in each top-level shell process.
458 env?: {...}
459 })
460
461 // Records which dependencies are permitted to run install scripts (preinstall,
462 // install, postinstall, and prepare for non-registry sources). Maintained via
463 // the "npm approve-scripts" command, which enforces a default-deny policy:
464 // install scripts for any dependency without a matching entry are silently
465 // skipped. Keys are package identifiers — either name-only (e.g. "pkg") or
466 // pinned with a version (e.g. "pkg@1.2.3"); by default entries are pinned so
467 // approval is version-specific. A value of true allows the dependency's
468 // install scripts to run, while false explicitly denies them (existing false
469 // entries are never silently overridden).
470 allowScripts?: [string]: bool
471
472 // Provides hints to the Webpack compiler, denoting which files in your project
473 // are "pure" and therefore safe to prune if unused.
474 sideEffects?: matchN(1, [bool, list.UniqueItems() & [...string]])
475 // Dependencies are specified with a simple hash of package name to version
476 // range. The version range is a string which has one or more space-separated
477 // descriptors. Dependencies can also be identified with a tarball or git URL.
478 #dependency: [string]: string
479
480 // Specifies dependencies that are required for the development and testing of
481 // the project. These dependencies are not needed in the production
482 // environment.
483 #devDependency: [string]: string
484
485 // Specifies requirements for development environment components such as
486 // operating systems, runtimes, or package managers. Used to ensure consistent
487 // development environments across the team.
488 #devEngineDependency: {
489 // The name of the dependency, with allowed values depending on the parent field
490 name!: string
491
492 // The version range for the dependency
493 version?: string
494
495 // What action to take if validation fails
496 onFail?: "ignore" | "warn" | "error" | "download"
497 ...
498 }
499
500 // URL to a website with details about how to fund the package.
501 #fundingUrl: net.AbsURL
502
503 // Used to inform about ways to help fund development of the package.
504 #fundingWay: close({
505 url!: #fundingUrl
506
507 // The type of funding or the platform through which funding can be provided,
508 // e.g. patreon, opencollective, tidelift or github.
509 type?: string
510 })
511
512 #license: matchN(>=1, [
513 string,
514 "AGPL-3.0-only" |
515 "Apache-2.0" |
516 "BSD-2-Clause" |
517 "BSD-3-Clause" |
518 "BSL-1.0" |
519 "CC0-1.0" |
520 "CDDL-1.0" |
521 "CDDL-1.1" |
522 "EPL-1.0" |
523 "EPL-2.0" |
524 "GPL-2.0-only" |
525 "GPL-3.0-only" |
526 "ISC" |
527 "LGPL-2.0-only" |
528 "LGPL-2.1-only" |
529 "LGPL-2.1-or-later" |
530 "LGPL-3.0-only" |
531 "LGPL-3.0-or-later" |
532 "MIT" |
533 "MPL-2.0" |
534 "MS-PL" |
535 "UNLICENSED",
536 ])
537
538 // Specifies dependencies that are optional for your project. These dependencies
539 // are attempted to be installed during the npm install process, but if they
540 // fail to install, the installation process will not fail.
541 #optionalDependency: [string]: string
542
543 #packageExportsEntry: matchN(1, [#packageExportsEntryPath, #packageExportsEntryObject])
544
545 // Used to specify conditional exports, note that Conditional exports are
546 // unsupported in older environments, so it's recommended to use the fallback
547 // array option if support for those environments is a concern.
548 #packageExportsEntryObject: close({
549 require?: #packageExportsEntryOrFallback
550 import?: #packageExportsEntryOrFallback
551 "module-sync"?: #packageExportsEntryOrFallback
552 node?: #packageExportsEntryOrFallback
553 default?: #packageExportsEntryOrFallback
554 types?: #packageExportsEntryOrFallback
555
556 {[=~"^[^.0-9]+$"]: #packageExportsEntryOrFallback}
557
558 {[=~"^types@.+$"]: #packageExportsEntryOrFallback}
559 })
560
561 #packageExportsEntryOrFallback: matchN(1, [#packageExportsEntry, #packageExportsFallback])
562
563 // The module path that is resolved when this specifier is imported. Set to
564 // `null` to disallow importing this module.
565 #packageExportsEntryPath: null | =~"^\\./"
566
567 // Used to allow fallbacks in case this environment doesn't support the preceding entries.
568 #packageExportsFallback: [...#packageExportsEntry]
569
570 #packageImportsEntry: matchN(1, [#packageImportsEntryPath, #packageImportsEntryObject])
571
572 // Used to specify conditional exports, note that Conditional exports are
573 // unsupported in older environments, so it's recommended to use the fallback
574 // array option if support for those environments is a concern.
575 #packageImportsEntryObject: close({
576 require?: #packageImportsEntryOrFallback
577 import?: #packageImportsEntryOrFallback
578 node?: #packageImportsEntryOrFallback
579 default?: #packageImportsEntryOrFallback
580 types?: #packageImportsEntryOrFallback
581
582 {[=~"^[^.0-9]+$"]: #packageImportsEntryOrFallback}
583
584 {[=~"^types@.+$"]: #packageImportsEntryOrFallback}
585 })
586
587 #packageImportsEntryOrFallback: matchN(1, [#packageImportsEntry, #packageImportsFallback])
588
589 // The module path that is resolved when this specifier is imported. Set to
590 // `null` to disallow importing this module.
591 #packageImportsEntryPath: null | string
592
593 // Used to allow fallbacks in case this environment doesn't support the preceding entries.
594 #packageImportsFallback: [...#packageImportsEntry]
595
596 // Specifies dependencies that are required by the package but are expected to
597 // be provided by the consumer of the package.
598 #peerDependency: [string]: string
599
600 // When a user installs your package, warnings are emitted if packages specified
601 // in "peerDependencies" are not already installed. The "peerDependenciesMeta"
602 // field serves to provide more information on how your peer dependencies are
603 // utilized. Most commonly, it allows peer dependencies to be marked as
604 // optional. Metadata for this field is specified with a simple hash of the
605 // package name to a metadata object.
606 #peerDependencyMeta: [string]: {
607 // Specifies that this peer dependency is optional and should not be installed automatically.
608 optional?: bool
609 ...
610 }
611
612 // A person who has been involved in creating or maintaining this package.
613 #person: string | {
614 name!: string
615 url?: net.AbsURL
616 email?: string
617 ...
618 }
619
620 // Specifies a supported JavaScript runtime.
621 #runtimeEngineDependency: {
622 // The runtime name
623 name!: string
624
625 // The version range for the runtime
626 version?: string
627
628 // What action to take if runtime validation fails
629 onFail?: "ignore" | "warn" | "error" | "download"
630 ...
631 }
632
633 // Run AFTER the package is installed.
634 #scriptsInstallAfter: string
635
636 // Run AFTER the package is published.
637 #scriptsPublishAfter: string
638
639 // Run by the 'npm restart' command. Note: 'npm restart' will run the stop and
640 // start scripts if no restart script is provided.
641 #scriptsRestart: string
642
643 // Run by the 'npm start' command.
644 #scriptsStart: string
645
646 // Run by the 'npm stop' command.
647 #scriptsStop: string
648
649 // Run by the 'npm test' command.
650 #scriptsTest: string
651
652 // Run BEFORE the package is uninstalled.
653 #scriptsUninstallBefore: string
654
655 // Run BEFORE bump the package version.
656 #scriptsVersionBefore: string
657 ...
658 }
659}