npm-packlist 10.0.4 → 11.1.0

package/README.md

@@ -30,11 +30,9 @@ arborist.loadActual().then((tree) => {
 This uses the following rules:
 
 1. If a `package.json` file is found, and it has a `files` list,
-   then ignore everything that isn't in `files`.  Always include the root
-   readme, license, licence and copying files, if they exist, as well
-   as the package.json file itself. Non-root readme, license, licence and
-   copying files are included by default, but can be excluded using the 
-   `files` list e.g. `"!readme"`.
+   then ignore everything that isn't matched by `files`.  Always include the
+   root readme, license, licence and copying files, if they exist, as well
+   as the package.json file itself.
 2. If there's no `package.json` file (or it has no `files` list), and
    there is a `.npmignore` file, then ignore all the files in the
    `.npmignore` file.
@@ -45,7 +43,7 @@ This uses the following rules:
    bundled dependency.  If it IS a bundled dependency, and it's a
    symbolic link, then the target of the link is included, not the
    symlink itself.
-4. Unless they're explicitly included (by being in a `files` list, or
+5. Unless they're explicitly included (by being in a `files` list, or
    a `!negated` rule in a relevant `.npmignore` or `.gitignore`),
    always ignore certain common cruft files:
 
@@ -58,48 +56,65 @@ This uses the following rules:
     6. Darwin's `.DS_Store` files because wtf are those even
     7. `npm-debug.log` files at the root of a project
 
-    You can explicitly re-include any of these with a `files` list in
-    `package.json` or a negated ignore file rule.
+    You can explicitly re-include most of these with a negated ignore file rule.
+    A small set of files are always ignored regardless of `files` rules:
+    `.git`, `.npmrc`, and `node_modules`.
 
 Only the `package.json` file in the very root of the project is ever
 inspected for a `files` list.  Below the top level of the root package,
 `package.json` is treated as just another file, and no package-specific
 semantics are applied.
 
-### Interaction between `package.json` and `.npmignore` rules
+### Interpretation of the `files` list
 
-In previous versions of this library, the `files` list in `package.json`
-was used as an initial filter to drive further tree walking. That is no
-longer the case as of version 6.0.0.
+Each entry in the `package.json` `files` list is interpreted as a glob
+pattern, expanded against the package root using node's built-in
+[`fs.globSync`](https://nodejs.org/api/fs.html#fsglobsyncpattern-options).
+Literal paths (`lib`, `src/index.js`) are valid globs and resolve to
+themselves; pattern entries (`dist-*`, `**/*.js`) resolve to every
+matching entry on disk; entries that match nothing are silently dropped.
 
-If you have a `package.json` file with a `files` array within, any top
-level `.npmignore` and `.gitignore` files *will be ignored*.
+When an entry matches a directory, the directory and all of its contents
+are included.  This is a documented convenience: writing
+`"files": ["dist"]` does not require also writing `"dist/**"`.
 
-If a _directory_ is listed in `files`, then any rules in nested `.npmignore` files within that directory will be honored.
+A leading `!` makes the entry a negation, removing matches from the
+result.  Negations are evaluated in order, so a later positive entry
+can re-include something a previous negation excluded.
 
-For example, with this package.json:
+#### Pattern semantics are anchored to the package root
 
-```json
-{
-  "files": [ "dir" ]
-}
-```
+Glob patterns are evaluated as paths relative to the package root, not as
+basename-anywhere matchers.  In particular:
 
-a `.npmignore` file at `dir/.npmignore` (and any subsequent
-sub-directories) will be honored.  However, a `.npmignore` at the root
-level will be skipped.
+* `"*.js"` matches `.js` files at the package root, not at every depth.
+  Use `"**/*.js"` to match at every depth.
+* `"!readme.md"` removes only the root `readme.md`.  Use
+  `"!**/readme.md"` to remove `readme.md` at every depth.
 
-Additionally, with this package.json:
+Negations only exclude paths that exist on disk at packlist time: a `!path`
+entry that matches nothing is silently dropped, same as a positive entry
+that matches nothing.  A typo'd negation has no effect.
 
-```
+#### Interaction with `.npmignore`
+
+If a `package.json` `files` array is present, any **top-level**
+`.npmignore` and `.gitignore` files are ignored: the `files` array is
+the sole source of inclusion at the package root.
+
+`.npmignore` files in subdirectories are still honored within their
+subtree.  For example, with this package.json:
+
+```json
 {
-  "files": ["dir/subdir"]
+  "files": [ "dir" ]
 }
 ```
 
-a `.npmignore` file at `dir/.npmignore` will be honored, as well as `dir/subdir/.npmignore`.
-
-Any specific file matched by an exact filename in the package.json `files` list will be included, and cannot be excluded, by any `.npmignore` files.
+a `.npmignore` at `dir/.npmignore` (and any nested subdirectory) will
+be applied.  This means a file listed both in `files` and excluded by a
+nested `.npmignore` will be excluded from the tarball; if you need such
+a file to ship, remove the `.npmignore` rule.
 
 ## API
 

package/lib/index.js

@@ -1,12 +1,14 @@
 'use strict'
 
 const { Walker: IgnoreWalker } = require('ignore-walk')
-const { lstatSync: lstat, readFileSync: readFile } = require('fs')
-const { basename, dirname, extname, join, relative, resolve, sep } = require('path')
+const { globSync } = require('glob')
+const { readFileSync: readFile } = require('node:fs')
+const { basename, dirname, extname, join, relative, resolve, sep } = require('node:path')
 const { log } = require('proc-log')
 
 // symbols used to represent synthetic rule sets
 const defaultRules = Symbol('npm-packlist.rules.default')
+const globalRules = Symbol('npm-packlist.rules.global')
 const strictRules = Symbol('npm-packlist.rules.strict')
 
 // There may be others, but :?|<> are handled by node-tar
@@ -83,13 +85,23 @@ class PackWalker extends IgnoreWalker {
       follow: false,
       // we path.resolve() here because ignore-walk doesn't do it and we want full paths
       path: resolve(opts?.path || tree.path).replace(/\\/g, '/'),
-      ignoreFiles: opts?.ignoreFiles || [
+      // globalRules belongs on the root walker only. Child walkers reach it through
+      // parent.filterEntry, where package.json rules can still override it; reapplying
+      // globalRules at the child level would defeat that override.
+      ignoreFiles: opts?.ignoreFiles || (opts?.parent ? [
         defaultRules,
         'package.json',
         '.npmignore',
         '.gitignore',
         strictRules,
-      ],
+      ] : [
+        defaultRules,
+        globalRules,
+        'package.json',
+        '.npmignore',
+        '.gitignore',
+        strictRules,
+      ]),
     }
 
     super(options)
@@ -97,7 +109,8 @@ class PackWalker extends IgnoreWalker {
     this.isPackage = options.isPackage
     this.seen = options.seen || new Set()
     this.tree = tree
-    this.requiredFiles = options.requiredFiles || []
+    this.globalIgnoreFile = options.globalIgnoreFile || null
+    this.globalIgnoreRules = options.globalIgnoreRules || null
 
     const additionalDefaults = []
     if (options.prefix && options.workspaces) {
@@ -124,13 +137,34 @@ class PackWalker extends IgnoreWalker {
     // go ahead and inject the default rules now
     this.injectRules(defaultRules, [...defaults, ...additionalDefaults])
 
+    // inject the global rules from the user's ignore file. positioned between
+    // defaultRules and package.json so an explicit entry in the package "files"
+    // field can still override. only the root walker carries globalRules in its
+    // ignoreFiles list; child walkers see global exclusions via parent.filterEntry,
+    // which is what lets the package.json `!/path/**` override win.
+    if (this.globalIgnoreRules === null && this.globalIgnoreFile) {
+      try {
+        this.globalIgnoreRules = readFile(this.globalIgnoreFile, { encoding: 'utf8' })
+      } catch (err) {
+        // istanbul ignore next -- only ENOENT is expected here
+        if (err.code !== 'ENOENT') {
+          throw err
+        }
+        this.globalIgnoreRules = ''
+      }
+    }
+    if (this.globalIgnoreRules) {
+      this.injectRules(globalRules, [this.globalIgnoreRules])
+      // istanbul ignore else -- globalIgnoreRules without a filename only happens when
+      // a caller pre-populates rules directly instead of going through globalIgnoreFile
+      if (this.globalIgnoreFile) {
+        log.silly('global-ignore-file', `applied rules from ${this.globalIgnoreFile}`)
+      }
+    }
+
     if (!this.isPackage) {
-      // if this instance is not a package, then place some strict default rules, and append
-      // known required files for this directory
-      this.injectRules(strictRules, [
-        ...strictDefaults,
-        ...this.requiredFiles.map((file) => `!${file}`),
-      ])
+      // if this instance is not a package, then place some strict default rules
+      this.injectRules(strictRules, [...strictDefaults])
     }
   }
 
@@ -234,15 +268,6 @@ class PackWalker extends IgnoreWalker {
     return {
       ...super.walkerOpt(entry, opts),
       ignoreFiles,
-      // we map over our own requiredFiles and pass ones that are within this entry
-      requiredFiles: this.requiredFiles
-        .map((file) => {
-          if (relative(file, entry) === '..') {
-            return relative(entry, file).replace(/\\/g, '/')
-          }
-          return false
-        })
-        .filter(Boolean),
     }
   }
 
@@ -295,46 +320,60 @@ class PackWalker extends IgnoreWalker {
       '/node_modules',
       '.npmrc',
       '/package-lock.json',
+      '/npm-shrinkwrap.json',
       '/yarn.lock',
       '/pnpm-lock.yaml',
       '/bun.lockb',
+      '/bun.lock',
     ]
 
     // if we have a files array in our package, we need to pull rules from it
     if (files) {
-      for (let file of files) {
-        // invert the rule because these are things we want to include
-        if (file.startsWith('./')) {
-          file = file.slice(1)
+      for (const entry of files) {
+        const isNegation = entry.startsWith('!')
+        // normalize: strip leading `!`s, `./`, a single leading `/`, and trailing slashes.
+        // trailing slashes confuse glob; the leading forms are equivalent to their stripped versions for glob expansion.
+        const pattern = (isNegation ? entry.replace(/^!+/, '') : entry)
+          .replace(/^\.?\//, '')
+          .replace(/\/+$/, '')
+        if (!pattern) {
+          continue
         }
-        if (file.endsWith('/*')) {
-          file += '*'
-        }
-        const inverse = `!${file}`
+
+        // expand the entry as a glob against the package root.
+        // literal paths (e.g. `lib`, `lib/foo.js`) are valid globs and resolve to themselves;
+        // patterns (e.g. `dist-*`, `**/*.js`) resolve to all matching entries;
+        // typos and non-existent entries resolve to nothing.
+        let matches = []
         try {
-          // if an entry in the files array is a specific file, then we need to include it as a
-          // strict requirement for this package. if it's a directory or a pattern, it's a default
-          // pattern instead. this is ugly, but we have to stat to find out if it's a file
-          const stat = lstat(join(this.path, file.replace(/^!+/, '')).replace(/\\/g, '/'))
-          // if we have a file and we know that, it's strictly required
-          if (stat.isFile()) {
-            strict.unshift(inverse)
-            this.requiredFiles.push(file.startsWith('/') ? file.slice(1) : file)
-          } else if (stat.isDirectory()) {
-            // otherwise, it's a default ignore, and since we got here we know it's not a pattern
-            // so we include the directory contents
-            ignores.push(inverse)
-            ignores.push(`${inverse}/**`)
+          matches = globSync(pattern, { cwd: this.path, withFileTypes: true, dot: true })
+        } catch {
+          // unparseable globs produce no matches and drop silently.
+          // (Pre-v11 instead fell through to push the raw entry as an ignore-walk pattern rule; we deliberately don't preserve that.)
+        }
+
+        // a positive entry produces `!path` rules (un-ignore from the surrounding `*` deny-all); a negation produces `path` rules (re-ignore them).
+        // directory matches expand to also include their contents; this is documented `files[]` behavior, not a glob hack.
+        const prefix = isNegation ? '' : '!'
+        for (const match of matches) {
+          const rel = match.relativePosix()
+          // istanbul ignore next -- defensive: glob with withFileTypes returns the cwd as an entry with an empty relative path; skip it.
+          if (!rel) {
+            continue
+          }
+          if (match.isDirectory()) {
+            ignores.push(`${prefix}/${rel}`)
+            ignores.push(`${prefix}/${rel}/**`)
+            continue
+          }
+          // istanbul ignore else -- non-file-non-dir matches (sockets, fifos, broken symlinks) drop silently.
+          if (match.isFile()) {
+            ignores.push(`${prefix}/${rel}`)
           }
-          // if the thing exists, but is neither a file or a directory, we don't want it at all
-        } catch (err) {
-          // if lstat throws, then we assume we're looking at a pattern and treat it as a default
-          ignores.push(inverse)
         }
       }
 
-      // we prepend a '*' to exclude everything, followed by our inverted file rules
-      // which now mean to include those
+      // we prepend a '*' to exclude everything, followed by our inverted file rules which now mean to include those
       this.injectRules('package.json', ['*', ...ignores])
     }
 

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "npm-packlist",
-  "version": "10.0.4",
+  "version": "11.1.0",
   "description": "Get a list of the files to add from a folder into an npm package",
   "directories": {
     "test": "test"
   },
   "main": "lib/index.js",
   "dependencies": {
-    "ignore-walk": "^8.0.0",
-    "proc-log": "^6.0.0"
+    "glob": "^13.0.6",
+    "ignore-walk": "^9.0.0",
+    "proc-log": "^7.0.0"
   },
   "author": "GitHub Inc.",
   "license": "ISC",
@@ -18,8 +19,8 @@
   ],
   "devDependencies": {
     "@npmcli/arborist": "^9.0.0",
-    "@npmcli/eslint-config": "^6.0.0",
-    "@npmcli/template-oss": "4.29.0",
+    "@npmcli/eslint-config": "^7.0.0",
+    "@npmcli/template-oss": "5.1.0",
     "mutate-fs": "^2.1.1",
     "tap": "^16.0.1"
   },
@@ -52,11 +53,12 @@
     ]
   },
   "engines": {
-    "node": "^20.17.0 || >=22.9.0"
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "templateOSS": {
     "//@npmcli/template-oss": "This file is partially managed by @npmcli/template-oss. Edits may be overwritten.",
-    "version": "4.29.0",
-    "publish": true
+    "version": "5.1.0",
+    "publish": true,
+    "updateNpm": false
   }
 }