@npmcli/template-oss 2.0.0 → 2.3.1

package/README.md

@@ -9,22 +9,26 @@ single devDependency.
 
 These fields will be set in the project's `package.json`:
 
-```json
+```js
 {
-  "author": "GitHub Inc.",
-  "files": ["bin", "lib"],
-  "license": "ISC",
-  "templateVersion": "1.0.0",
-  "scripts": {
-    "lint": "eslint '**/*.js'",
-    "lintfix": "npm run lint -- --fix",
-    "preversion": "npm test",
-    "postversion": "npm publish",
-    "prepublishOnly": "git push origin --follow-tags",
-    "snap": "tap",
-    "test": "tap",
-    "posttest": "npm run lint",
-  }
+  author: 'GitHub Inc.',
+  files: ['bin', 'lib'],
+  license: 'ISC',
+  templateVersion: $TEMPLATE_VERSION,
+  scripts: {
+    lint: `eslint '**/*.js'`,
+    postlint: 'npm-template-check',
+    lintfix: 'npm run lint -- --fix',
+    preversion: 'npm test',
+    postversion: 'npm publish',
+    prepublishOnly: 'git push origin --follow-tags',
+    snap: 'tap',
+    test: 'tap',
+    posttest: 'npm run lint',
+  },
+  engines: {
+    node: '^12.13.0 || ^14.15.0 || >=16',
+  },
 }
 ```
 
@@ -34,9 +38,9 @@ action.
 
 #### Extending
 
-The `changes` constant located in `lib/package.js` should contain all patches
-for the `package.json` file. Be sure to correctly expand any object/array based
-values with the original package content.
+The `changes` constant located in `lib/postinstall/update-package.js` should contain
+all patches for the `package.json` file. Be sure to correctly expand any object/array
+based values with the original package content.
 
 ### Static files
 
@@ -47,8 +51,12 @@ These files will be copied, overwriting any existing files:
 
 - `.eslintrc.js`
 - `.github/workflows/ci.yml`
+- `.github/ISSUE_TEMPLATE/bug.yml`
+- `.github/ISSUE_TEMPLATE/config.yml`
+- `.github/CODEOWNERS`
 - `.gitignore`
 - `LICENSE.md`
+- `SECURITY.md`
 
 #### Extending
 
@@ -56,27 +64,16 @@ Place files in the `lib/content/` directory, use only the file name and remove
 any leading `.` characters (i.e. `.github/workflows/ci.yml` becomes `ci.yml`
 and `.gitignore` becomes `gitignore`).
 
-Modify the `content` object at the top of `lib/content/index.js` to include
+Modify the `content` object at the top of `lib/postinstall/copy-content.js` to include
 your new file. The object keys are destination paths, and values are source.
 
+### `package.json` checks
 
-### Package installation and removal
-
-These packages will be removed:
-
-- `eslint-plugin-import`
-- `eslint-plugin-promise`
-- `eslint-plugin-standard`
-- `@npmcli/lint`
-
-
-Afterwards, these packages will be installed as devDependencies:
-
-- `eslint`
-- `eslint-plugin-node`
-- `@npmcli/eslint-config`
-- `tap`
+`npm-template-check` is run by `postlint` and will error if the `package.json`
+is not configured properly, with steps to run to correct any problems.
 
 #### Extending
 
-Make changes to the `removeDeps` and `devDeps` arrays in `lib/install.js`.
+Add any unwanted packages to `unwantedPackages` in `lib/check.js`. Currently
+the best way to install any packages is to include them as `peerDependencies`
+in this repo.

package/bin/.gitattributes

@@ -0,0 +1,3 @@
+# Dont modify line endings of our bin scripts
+# so git status stays clean for windows tests
+*.js -crlf

package/bin/npm-template-check.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
-const check = require('../lib/check.js')
+const checkPackage = require('../lib/postlint/check-package.js')
+const checkGitIgnore = require('../lib/postlint/check-gitignore.js')
 
 const main = async () => {
   const {
@@ -11,7 +12,11 @@ const main = async () => {
     throw new Error('This package requires npm >7.21.1')
   }
 
-  const problems = await check(root)
+  const problems = [
+    ...(await checkPackage(root)),
+    ...(await checkGitIgnore(root)),
+  ]
+
   if (problems.length) {
     console.error('Some problems were detected:')
     console.error()

package/bin/postinstall.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-const copyContent = require('../lib/content/index.js')
-const patchPackage = require('../lib/package.js')
+const copyContent = require('../lib/postinstall/copy-content.js')
+const patchPackage = require('../lib/postinstall/update-package.js')
 
 const main = async () => {
   const {
@@ -19,12 +19,10 @@ const main = async () => {
     return
   }
 
-  return copyContent(root)
+  await copyContent(root)
 }
 
-// we export the promise so it can be awaited in tests, coverage is disabled
-// for the catch handler because it does so little it's not worth testing
-module.exports = main().catch(/* istanbul ignore next */ (err) => {
+module.exports = main().catch((err) => {
   console.error(err.stack)
   process.exitCode = 1
 })

package/lib/content/CODEOWNERS

@@ -0,0 +1 @@
+*	@npm/cli-team

package/lib/content/SECURITY.md

@@ -1 +1,3 @@
+<!-- This file is automatically added by @npmcli/template-oss. Do not edit. -->
+
 Please send vulnerability reports through [hackerone](https://hackerone.com/github).

package/lib/content/ci.yml

@@ -26,7 +26,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [12.13.0, 12.x, 14.15.0, 14.x, 16.x]
+        node-version: [12.13.0, 12.x, 14.15.0, 14.x, 16.13.0, 16.x]
         platform:
         - os: ubuntu-latest
           shell: bash
@@ -51,4 +51,3 @@ jobs:
       - run: npm i --prefer-online -g npm@latest
       - run: npm ci
       - run: npm test --ignore-scripts
-      - run: npm ls -a

package/lib/content/gitignore

@@ -9,10 +9,14 @@
 !**/.gitignore
 !/package.json
 !/package-lock.json
+!/docs
 !/bin
 !/lib
 !/map.js
 !/tap-snapshots
 !/test
+!/scripts
 !/README*
 !/LICENSE*
+!/SECURITY*
+!/CHANGELOG*

package/lib/{content/index.js → postinstall/copy-content.js}

@@ -1,32 +1,41 @@
-const { dirname, join } = require('path')
+const { dirname, join, resolve } = require('path')
 const fs = require('@npmcli/fs')
 
+const contentDir = resolve(__dirname, '..', 'content')
+
 // keys are destination paths in the target project
-// values are paths to contents relative to this file
+// values are paths to contents relative to '../content/'
 const content = {
   '.eslintrc.js': './eslintrc.js',
   '.github/workflows/ci.yml': './ci.yml',
   '.github/ISSUE_TEMPLATE/bug.yml': './bug.yml',
   '.github/ISSUE_TEMPLATE/config.yml': './config.yml',
+  '.github/CODEOWNERS': './CODEOWNERS',
   '.gitignore': './gitignore',
   'LICENSE.md': './LICENSE.md',
   'SECURITY.md': './SECURITY.md',
 }
 
+const filesToDelete = [
+  // remove any other license files
+  /^LICENSE*/,
+  // remove any eslint config files that aren't local to the project
+  /^\.eslintrc\.(?!(local\.)).*/,
+]
+
 // given a root directory, copy all files in the content map
-// after purging any non-local .eslintrc config files
+// after purging any files we need to delete
 const copyContent = async (root) => {
   const contents = await fs.readdir(root)
 
   for (const file of contents) {
-    // remove any eslint config files that aren't local to the project
-    if (file.startsWith('.eslintrc.') && !file.startsWith('.eslintrc.local.')) {
+    if (filesToDelete.some((p) => p.test(file))) {
       await fs.rm(join(root, file))
     }
   }
 
   for (let [target, source] of Object.entries(content)) {
-    source = join(__dirname, source)
+    source = join(contentDir, source)
     target = join(root, target)
     // if the target is a subdirectory of the root, mkdirp it first
     if (dirname(target) !== root) {

package/lib/{package.js → postinstall/update-package.js}

@@ -1,6 +1,9 @@
 const PackageJson = require('@npmcli/package-json')
 
-const TEMPLATE_VERSION = require('../package.json').version
+const {
+  version: TEMPLATE_VERSION,
+  name: TEMPLATE_NAME,
+} = require('../../package.json')
 
 const changes = {
   author: 'GitHub Inc.',
@@ -26,25 +29,38 @@ const changes = {
 const patchPackage = async (root) => {
   const pkg = await PackageJson.load(root)
 
+  // If we are running this on itself, we always run the script.
+  // We also don't set templateVersion in package.json because
+  // its not relavent and would cause git churn after running
+  // `npm version`.
+  const isDogfood = pkg.content.name === TEMPLATE_NAME
+
   // if the target package.json has a templateVersion field matching our own
   // current version, we return false here so the postinstall script knows to
   // exit early instead of running everything again
-  if (pkg.content.templateVersion === TEMPLATE_VERSION) {
+  if (pkg.content.templateVersion === TEMPLATE_VERSION && !isDogfood) {
     return false
   }
 
   // we build a new object here so our exported set of changes is not modified
-  pkg.update({
+  const update = {
     ...changes,
     scripts: {
       ...pkg.content.scripts,
       ...changes.scripts,
     },
-  })
+  }
+
+  if (isDogfood) {
+    delete update.templateVersion
+  }
+
+  pkg.update(update)
 
   await pkg.save()
   return true
 }
+
 patchPackage.changes = changes
 
 module.exports = patchPackage

package/lib/postlint/check-gitignore.js

@@ -0,0 +1,59 @@
+const path = require('path')
+const fs = require('fs')
+const { sync: which } = require('which')
+const { spawnSync } = require('child_process')
+
+// The problem we are trying to solve is when a new .gitignore file
+// is copied into an existing repo, there could be files already checked in
+// to git that are now ignored by new gitignore rules. We want to warn
+// about these files.
+const check = async (root) => {
+  const git = path.resolve(root, '.git')
+  const gitignore = path.resolve(root, '.gitignore')
+
+  if (!fs.existsSync(git)) {
+    return []
+  }
+
+  if (!fs.existsSync(gitignore)) {
+    throw new Error(`${gitignore} must exist to run npm-template-check`)
+  }
+
+  const res = spawnSync(which('git'), [
+    'ls-files',
+    '--cached',
+    '--ignored',
+    // The .gitignore file has already been placed by now with the postinstall
+    // script so when this script runs via postlint, it can use that file
+    `--exclude-from=${gitignore}`,
+  ], { encoding: 'utf-8', cwd: root })
+
+  const files = res.stdout
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+
+  if (!files.length) {
+    return []
+  }
+
+  const relativeGitignore = path.relative(root, gitignore)
+  const ignores = fs.readFileSync(gitignore)
+    .toString()
+    .split('\n')
+    .filter((l) => l && !l.trim().startsWith('#'))
+
+  const message = [
+    `The following files are tracked by git but matching a pattern in ${relativeGitignore}:`,
+    ...files.map((f) => `  ${f}`),
+  ].join('\n')
+
+  const solution = [
+    'Move files to not match one of these patterns:',
+    ...ignores.map((i) => `  ${i}`),
+  ].join('\n')
+
+  return [{ message, solution }]
+}
+
+module.exports = check

package/lib/{check.js → postlint/check-package.js}

@@ -1,7 +1,7 @@
-const { join } = require('path')
-const fs = require('@npmcli/fs')
+const PackageJson = require('@npmcli/package-json')
 
-const patchPackage = require('./package.js')
+const { name: TEMPLATE_NAME } = require('../../package.json')
+const patchPackage = require('../postinstall/update-package.js')
 
 const unwantedPackages = [
   '@npmcli/lint',
@@ -13,30 +13,29 @@ const unwantedPackages = [
 const hasOwn = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key)
 
 const check = async (root) => {
-  const pkgPath = join(root, 'package.json')
-  try {
-    var contents = await fs.readFile(pkgPath, { encoding: 'utf8' })
-  } catch (err) {
-    throw new Error('No package.json found')
-  }
+  const pkg = (await PackageJson.load(root)).content
 
-  const pkg = JSON.parse(contents)
+  // templateVersion doesn't apply if we're on this repo
+  // since we always run the scripts here
+  const changes = Object.entries(patchPackage.changes).filter(([key]) => {
+    if (pkg.name === TEMPLATE_NAME && key === 'templateVersion') {
+      return false
+    }
+    return true
+  })
 
   const problems = []
 
   const incorrectFields = []
   // 1. ensure package.json changes have been applied
-  for (const [key, value] of Object.entries(patchPackage.changes)) {
+  for (const [key, value] of changes) {
     if (!hasOwn(pkg, key)) {
       incorrectFields.push({
         name: key,
         found: pkg[key],
         expected: value,
       })
-      continue
-    }
-
-    if (value && typeof value === 'object') {
+    } else if (value && typeof value === 'object') {
       for (const [subKey, subValue] of Object.entries(value)) {
         if (!hasOwn(pkg[key], subKey) ||
           pkg[key][subKey] !== subValue) {
@@ -63,8 +62,15 @@ const check = async (root) => {
       message: [
         `The following package.json fields are incorrect:`,
         ...incorrectFields.map((field) => {
-          const { name, found, expected } = field
-          return `  Field: "${name}" Expected: "${expected}" Found: "${found}"`
+          const message = [
+            'Field:',
+            `${JSON.stringify(field.name)}`,
+            'Expected:',
+            `${JSON.stringify(field.expected)}`,
+            'Found:',
+            `${JSON.stringify(field.found)}`,
+          ].join(' ')
+          return `  ${message}`
         }),
       ].join('\n'),
       solution: 'npm rm @npmcli/template-oss && npm i -D @npmcli/template-oss',
@@ -81,8 +87,8 @@ const check = async (root) => {
     problems.push({
       message: [
         'The following unwanted packages were found:',
-        ...mustRemove,
-      ].join(' '),
+        ...mustRemove.map((p) => `  ${p}`),
+      ].join('\n'),
       solution: `npm rm ${mustRemove.join(' ')}`,
     })
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npmcli/template-oss",
-  "version": "2.0.0",
+  "version": "2.3.1",
   "description": "templated files used in npm CLI team oss projects",
   "main": "lib/index.js",
   "bin": {
@@ -13,7 +13,6 @@
     "postlint": "npm-template-check",
     "posttest": "npm run lint",
     "postversion": "npm publish",
-    "prelint": "ln -sf ../../bin/npm-template-check.js node_modules/.bin/npm-template-check",
     "prepublishOnly": "git push origin --follow-tags",
     "preversion": "npm test",
     "snap": "tap",
@@ -32,7 +31,7 @@
   "dependencies": {
     "@npmcli/fs": "^1.0.0",
     "@npmcli/package-json": "^1.0.1",
-    "@npmcli/promise-spawn": "^2.0.0"
+    "which": "^2.0.2"
   },
   "files": [
     "bin",
@@ -40,7 +39,9 @@
   ],
   "devDependencies": {
     "@npmcli/eslint-config": "*",
-    "eslint": "^7.32.0",
+    "@npmcli/promise-spawn": "^2.0.0",
+    "@npmcli/template-oss": "file:./",
+    "eslint": "^8.1.0",
     "eslint-plugin-node": "^11.1.0",
     "tap": "*"
   },
@@ -48,7 +49,9 @@
     "@npmcli/eslint-config": "^1.0.0",
     "tap": "^15.0.9"
   },
-  "templateVersion": "1.0.3",
+  "tap": {
+    "coverage-map": "map.js"
+  },
   "engines": {
     "node": "^12.13.0 || ^14.15.0 || >=16"
   }