@npmcli/template-oss 4.19.0 → 4.21.0

package/README.md

@@ -3,7 +3,11 @@
 This module bundles the npm CLI team's basics for package development into a
 single devDependency.
 
-**CAUTION: THESE CHANGES WILL OVERWRITE ANY LOCAL FILES AND SETTINGS**
+> [!WARNING]  
+> THESE CHANGES WILL OVERWRITE LOCAL FILES AND SETTINGS
+
+> [!IMPORTANT]  
+> This package does not follow semantic versioning for its API. This package is designed to be installed with `--save-exact` and therefore will make breaking API changes outside of major versions, including `engines` narrowing. Major versions are reserved for breaking changes to files written to a repo by this package.
 
 ### Configuration
 
@@ -60,21 +64,21 @@ any of the same settings in the root.
 ### Content
 
 All the templated content for this repo lives in
-[`lib/content/`](./lib/content/). The `index.js`[./lib/content/index.js] file
+[`lib/content/`](./lib/content/). The [`index.js`](./lib/content/index.js) file
 controls how and where this content is written.
 
 Content files can be overwritten or merged with the existing target file.
-Currently mergining is only supported for `package.json` files.
+Merging is only supported for some types of files (ini, yaml, json, package.json)
 
 Each content file goes through the following pipeline:
 
 1. It is read from its source location
-1. It is are templated using Handlebars with the variables from each packages's
-   config (with some derived values generated in [`config.js`](./lib/config.js)
-1. It is parsed based on its file extension in
+2. It is compiled using [Handlebars](https://handlebarsjs.com/) with the variables from each packages's
+   config (with some derived values generated in [`config.js`](./lib/config.js))
+3. It is parsed based on its file extension in
    [`parser.js`](./lib/util/parser.js)
-1. Additional logic is applied by the parser
-1. It is written to its target location
+4. Additional logic is applied by the parser
+5. It is written to its target location
 
 ### Usage
 
@@ -82,7 +86,7 @@ This package provides two bin scripts:
 
 #### `template-oss-check`
 
-This will check if any of the applied files different from the target content,
+This will check if any of the applied files differ from the target content,
 or if any of the other associated checks fail. The diffs of each file or check
 will be reported with instructions on how to fix it.
 
@@ -92,7 +96,7 @@ This will write all source files to their target locations in the cwd. It will
 do nothing if `package.json#templateOSS.version` is the same as the version
 being run. This can be overridden by `--force`.
 
-This is the script that is run on `postinsall`.
+This is the script that is run on `postinstall`.
 
 ### Extending
 
@@ -100,7 +104,7 @@ This is the script that is run on `postinsall`.
 
 This directory is where all the logic for applying files lives. It should be
 possible to add new files without modifying anything in this directory. To add a
-file, add the templated file to `lib/content/$FILENAME` and add entry for it in
+file, add the templated file to `lib/content/$FILENAME` and an entry for it in
 `lib/content/index.js` depending on where and when it should be written (root vs
 workspace, repo vs module, add vs remove, etc).
 
@@ -119,3 +123,23 @@ trivial to swap out this content directory for a different one as it is only
 referenced in a single place in `lib/config.js`. However, it's not currently
 possible to change this value at runtime, but that might become possible in
 future versions of this package.
+
+### Testing
+
+The files `test/release/release-manager.js` and `test/release/release-please.js`
+use recorded `nock` fixtures to generate snapshots. To update these fixtures run:
+
+```sh
+GITHUB_TOKEN=$(gh auth token) npm run test:record --- test/release/release-{please,manager}.js
+```
+
+If you only need to update fixtures for one, it's best to only run that single
+test file.
+
+#### `test/release/release-please.js`
+
+This test file uses the repo `npm/npm-cli-release-please` to record its
+fixtures. It expects `https://github.com/npm/npm-cli-release-please` to be
+checked out in a sibling directory to this repo. It also needs the current
+branch set to `template-oss-mock-testing-branch-do-not-delete` before the tests
+are run.

package/bin/release-manager.js

@@ -1,277 +1,29 @@
 #!/usr/bin/env node
 
-const { Octokit } = require('@octokit/rest')
-const semver = require('semver')
-const mapWorkspaces = require('@npmcli/map-workspaces')
-const { join } = require('path')
+const core = require('@actions/core')
+const { parseArgs } = require('util')
+const ReleaseManager = require('../lib/release/release-manager')
 
-const log = (...logs) => console.error('LOG', ...logs)
-
-const ROOT = process.cwd()
-const pkg = require(join(ROOT, 'package.json'))
-
-const args = process.argv.slice(2).reduce((acc, a) => {
-  const [k, v] = a.replace(/^--/g, '').split('=')
-  acc[k] = v === 'true'
-  return acc
-}, {})
-
-/* eslint-disable max-len */
-const MANUAL_PUBLISH_STEPS = `
-1. Checkout the release branch and test
-
-    \`\`\`sh
-    gh pr checkout <PR-NUMBER> --force
-    npm ${args.lockfile ? 'ci' : 'update'}
-    npm test
-    gh pr checks <PR-NUMBER> -R {NWO} --watch
-    \`\`\`
-
-1. Publish workspaces
-
-    \`\`\`sh
-    npm publish -w <WS-PKG-N>
-    \`\`\`
-
-1. Publish
-
-    \`\`\`sh
-    npm publish <PUBLISH-FLAGS>
-    \`\`\`
-
-1. Merge release PR
-
-    \`\`\`sh
-    gh pr merge <PR-NUMBER> -R {NWO} --rebase
-    git checkout <BASE-BRANCH>
-    git fetch
-    git reset --hard origin/<BASE-BRANCH>
-    \`\`\`
-`
-
-const AUTO_PUBLISH_STEPS = `
-1. Merge release PR :rotating_light: Merging this will auto publish :rotating_light:
-
-    \`\`\`sh
-    gh pr merge <PR-NUMBER> -R {NWO} --rebase
-    \`\`\`
-`
-
-const DEFAULT_RELEASE_PROCESS = (args.publish ? AUTO_PUBLISH_STEPS : MANUAL_PUBLISH_STEPS) + `
-1. Check For Release Tags
-
-    Release Please will run on the just pushed release commit and create GitHub releases and tags for each package.
-
-    \`\`\`
-    gh run watch -R {NWO} $(gh run list -R {NWO} -w release -b <BASE-BRANCH> -L 1 --json databaseId -q ".[0].databaseId")
-    \`\`\`
-`
-/* eslint-enable max-len */
-
-const getReleaseProcess = async ({ owner, repo }) => {
-  const RELEASE_LIST_ITEM = /^\d+\.\s/gm
-
-  log(`Fetching release process from:`, owner, repo, 'wiki')
-
-  let releaseProcess = ''
-  try {
-    releaseProcess = await new Promise((resolve, reject) => {
-      require('https')
-        .get(`https://raw.githubusercontent.com/wiki/${owner}/${repo}/Release-Process.md`, resp => {
-          let d = ''
-          resp.on('data', c => (d += c))
-          resp.on('end', () => {
-            if (resp.statusCode !== 200) {
-              reject(new Error(`${resp.req.protocol + resp.req.host + resp.req.path}: ${d}`))
-            } else {
-              resolve(d)
-            }
-          })
-        })
-        .on('error', reject)
-    })
-  } catch (e) {
-    log('Release wiki not found', e.message)
-    log('Using default release process')
-    releaseProcess = DEFAULT_RELEASE_PROCESS.replace(/\{NWO\}/g, `${owner}/${repo}`).trim() + '\n'
-  }
-
-  // XXX: the release steps need to always be the last thing in the doc for this to work
-  const releaseLines = releaseProcess.split('\n')
-  const releaseStartLine = releaseLines.reduce((acc, line, index) =>
-    line.match(/^#+\s/) ? index : acc, 0)
-  const section = releaseLines.slice(releaseStartLine).join('\n')
-
-  return section.split({
-    [Symbol.split] (str) {
-      const [, ...matches] = str.split(RELEASE_LIST_ITEM)
-      log(`Found ${matches.length} release items`)
-      return matches.map((m) => `- [ ] <STEP_INDEX>. ${m}`.trim())
-    },
-  })
-}
-
-const getPrReleases = async (pr) => {
-  const RELEASE_SEPARATOR = /<details><summary>.*<\/summary>/g
-  const MONO_VERSIONS = /<details><summary>(?:(.*?):\s)?(.*?)<\/summary>/
-  const ROOT_VERSION = /\n##\s\[(.*?)\]/
-
-  const workspaces = [...await mapWorkspaces({ pkg: pkg, cwd: ROOT })].reduce((acc, [k]) => {
-    const wsComponentName = k.startsWith('@') ? k.split('/')[1] : k
-    acc[wsComponentName] = k
-    return acc
-  }, {})
-
-  const getReleaseInfo = ({ name, version: rawVersion }) => {
-    const version = semver.parse(rawVersion)
-    const prerelease = !!version.prerelease.length
-    const tag = `${name ? `${name}-` : ''}v${rawVersion}`
-    const workspace = workspaces[name]
-
-    return {
-      name,
-      tag,
-      prerelease,
-      version: rawVersion,
-      major: version.major,
-      url: `https://github.com/${pr.base.repo.full_name}/releases/tag/${tag}`,
-      flags: `${name ? `-w ${workspace}` : ''} ${prerelease ? `--tag prerelease` : ''}`.trim(),
-    }
-  }
-
-  const releases = pr.body.match(RELEASE_SEPARATOR)
-
-  if (!releases) {
-    log('Found no monorepo, checking for single root version')
-    const [, version] = pr.body.match(ROOT_VERSION) || []
-
-    if (!version) {
-      throw new Error('Could not find version with:', ROOT_VERSION)
-    }
-
-    log('Found version', version)
-    return [getReleaseInfo({ version })]
-  }
-
-  log(`Found ${releases.length} releases`)
-
-  return releases.reduce((acc, r) => {
-    const [, name, version] = r.match(MONO_VERSIONS)
-    const release = getReleaseInfo({ name, version })
-
-    if (!name) {
-      log('Found root', release)
-      acc[0] = release
-    } else {
-      log('Found workspace', release)
-      acc[1].push(release)
-    }
-
-    return acc
-  }, [null, []])
-}
-
-const appendToComment = async ({ github, commentId, title, body }) => {
-  if (!commentId) {
-    log(`No comment id, skipping append to comment`)
-    return
-  }
-
-  const { data: comment } = await github.rest.issues.getComment({
-    ...github.repo,
-    comment_id: commentId,
-  })
-
-  const hasAppended = comment.body.includes(title)
-
-  log('Found comment with id:', commentId)
-  log(hasAppended ? 'Comment has aready been appended, replacing' : 'Appending to comment')
-
-  const prefix = hasAppended
-    ? comment.body.split(title)[0]
-    : comment.body
-
-  return github.rest.issues.updateComment({
-    ...github.repo,
-    comment_id: commentId,
-    body: [prefix, title, body].join('\n\n'),
-  })
-}
-
-const main = async (env) => {
+ReleaseManager.run({
   // These env vars are set by the release.yml workflow from template-oss
-  const {
-    CI,
-    GITHUB_TOKEN,
-    GITHUB_REPOSITORY,
-    RELEASE_PR_NUMBER,
-    RELEASE_COMMENT_ID, // comment is optional for testing
-  } = env
-
-  if (!CI || !GITHUB_TOKEN || !GITHUB_REPOSITORY || !RELEASE_PR_NUMBER) {
-    throw new Error('This script is designed to run in CI. If you want to test it, set the ' +
-      `following env vars: \`CI, GITHUB_TOKEN, GITHUB_REPOSITORY, RELEASE_PR_NUMBER\``)
-  }
-
-  const [owner, repo] = GITHUB_REPOSITORY.split('/')
-  const github = new Octokit({ auth: GITHUB_TOKEN })
-  github.repo = { owner, repo }
-
-  const { data: pr } = await github.rest.pulls.get({
-    ...github.repo,
-    pull_number: RELEASE_PR_NUMBER,
+  token: process.env.GITHUB_TOKEN,
+  repo: process.env.GITHUB_REPOSITORY,
+  cwd: process.cwd(),
+  ...parseArgs({
+    options: {
+      pr: { type: 'string' },
+      backport: { type: 'string' },
+      defaultTag: { type: 'string' },
+      lockfile: { type: 'boolean' },
+      publish: { type: 'boolean' },
+    },
+  }).values,
+})
+  .then((result) => {
+    core.setOutput('result', result)
+    return null
   })
-
-  const [release, workspaces = []] = await getPrReleases(pr)
-
-  const RELEASE_OMIT_PRERELEASE = '> NOT FOR PRERELEASE'
-  const RELEASE_OMIT_WORKSPACES = 'Publish workspaces'
-  const releaseItems = (await getReleaseProcess({ owner, repo }))
-    .filter((item) => {
-      if (release.prerelease && item.includes(RELEASE_OMIT_PRERELEASE)) {
-        return false
-      }
-
-      if (!workspaces.length && item.includes(RELEASE_OMIT_WORKSPACES)) {
-        return false
-      }
-
-      return true
-    })
-    .map((item, index) => item.replace('<STEP_INDEX>', index + 1))
-
-  log(
-    `Filtered ${releaseItems.length} release process items:\n`,
-    releaseItems.map(r => r.split('\n')[0].replace('- [ ] ', '')).join(', ')
-  )
-
-  const releaseTitle = `### Release Checklist for ${release.tag}`
-  const releaseChecklist = releaseItems
-    .join('\n\n')
-    .replace(/<PR-NUMBER>/g, RELEASE_PR_NUMBER)
-    .replace(/<RELEASE-BRANCH>/g, pr.head.ref)
-    .replace(/<BASE-BRANCH>/g, pr.base.ref)
-    .replace(/<MAJOR>/g, release.major)
-    .replace(/<X\.Y\.Z>/g, release.version)
-    .replace(/<GITHUB-RELEASE-LINK>/g, release.url)
-    .replace(/<PUBLISH-FLAGS>/g, release.flags)
-    .replace(/^(\s*\S.*)(-w <WS-PKG-N>)$/gm, workspaces.map(w => `$1${w.flags}`).join('\n'))
-    .trim()
-
-  await appendToComment({
-    github,
-    commentId: RELEASE_COMMENT_ID,
-    title: releaseTitle,
-    body: releaseChecklist,
+  .catch(err => {
+    core.setFailed('Release Manager failed')
+    core.error(err)
   })
-
-  if (!RELEASE_COMMENT_ID) {
-    console.log(releaseChecklist)
-  }
-}
-
-main(process.env)
-  // This is part of the release CI and is for posting a release manager
-  // comment to the issue but we dont want it to ever fail the workflow so
-  // just log but dont set the error code
-  .catch(err => console.error(err))

package/bin/release-please.js

@@ -1,75 +1,40 @@
 #!/usr/bin/env node
 
 const core = require('@actions/core')
-const main = require('../lib/release-please/index.js')
+const { parseArgs } = require('util')
+const ReleasePlease = require('../lib/release/release-please.js')
 
-const dryRun = !process.env.CI
-const [branch, forcePullRequest] = process.argv.slice(2)
-
-const debugPr = (val) => {
-  if (dryRun) {
-    console.log('PR:', val.title.toString())
-    console.log('='.repeat(40))
-    console.log(val.body.toString())
-    console.log('='.repeat(40))
-    for (const update of val.updates.filter(u => u.updater.changelogEntry)) {
-      console.log('CHANGELOG:', update.path)
-      console.log('-'.repeat(40))
-      console.log(update.updater.changelogEntry)
-      console.log('-'.repeat(40))
-    }
-    for (const update of val.updates.filter(u => u.updater.rawContent)) {
-      console.log('package:', update.path)
-      console.log('-'.repeat(40))
-      console.log(JSON.parse(update.updater.rawContent).name)
-      console.log(JSON.parse(update.updater.rawContent).version)
-      console.log('-'.repeat(40))
-    }
-  }
-}
-
-const debugRelease = (val) => {
-  if (dryRun) {
-    console.log('ROOT RELEASE:', JSON.stringify(val, null, 2))
-  }
-}
-
-const debugReleases = (val) => {
-  if (dryRun) {
-    console.log('ALL RELEASES:', JSON.stringify(val, null, 2))
-  }
-}
-
-main({
+ReleasePlease.run({
   token: process.env.GITHUB_TOKEN,
   repo: process.env.GITHUB_REPOSITORY,
-  dryRun,
-  branch,
-  forcePullRequest: forcePullRequest ? +forcePullRequest : null,
-}).then(({ pr, release, releases }) => {
+  ...parseArgs({
+    options: {
+      branch: { type: 'string' },
+      backport: { type: 'string' },
+      defaultTag: { type: 'string' },
+    },
+  }).values,
+  // This is mostly for testing and debugging. Use environs with the format
+  // `RELEASE_PLEASE_<manfiestOverrideConfigName>`
+  // (eg`RELEASE_PLEASE_lastReleaseSha=<SHA>`) to set one-off config items for
+  // the release please run without needing to commit and push the config.
+  overrides: Object.fromEntries(Object.entries(process.env)
+    .filter(([k, v]) => k.startsWith('RELEASE_PLEASE_') && v != null)
+    .map(([k, v]) => [k.replace('RELEASE_PLEASE_', ''), v])),
+}).then(({ pr, releases }) => {
   if (pr) {
-    debugPr(pr)
     core.setOutput('pr', JSON.stringify(pr))
     core.setOutput('pr-branch', pr.headBranchName)
     core.setOutput('pr-number', pr.number)
     core.setOutput('pr-sha', pr.sha)
   }
 
-  if (release) {
-    debugRelease(release)
-    core.setOutput('release', JSON.stringify(release))
-  }
-
   if (releases) {
-    debugReleases(releases)
     core.setOutput('releases', JSON.stringify(releases))
   }
 
   return null
 }).catch(err => {
-  if (dryRun) {
-    console.error(err)
-  } else {
-    core.setFailed(`failed: ${err}`)
-  }
+  core.setFailed('Release Please failed')
+  core.error(err)
 })