Merge branch 'npm:main' into main

.gitignore

@@ -40,5 +40,6 @@
 !/test/
 !/tsconfig.json
 !/webpack.config.js
+!cli-cache.json
 tap-testdir*/
 !/cli/

.prettierignore

@@ -5,3 +5,4 @@
 /.reuse/
 .nyc_output/
 coverage/
+cli-cache.json

cli-cache.json

@@ -0,0 +1,6 @@
+{
+  "v8": "aa8fff11cdab94fff1a2160ee5241f5f4632e96b",
+  "v9": "64763a341e7aa5b456e696f956759bf9b3440dc1",
+  "v10": "a3041941586b6fb8ed7403fe3c24d81138a96005",
+  "v11": "ab9ddc0413374fbf4879da535f82e03bc4e62cf3"
+}

cli/bin/build.js

@@ -2,6 +2,7 @@ const {resolve, relative, join} = require('path')
 const {spawnSync} = require('child_process')
 const build = require('../lib/build.js')
 const {nwo} = require('../lib/gh')
+const {CacheVersionSha} = require('../lib/cache.js')
 
 // check only build with the current versions instead of checking the registry
 // and also fails if any changes are detected. this is used in CI to make sure
@@ -24,21 +25,23 @@ const checkContent = () => {
   }
 }
 
-build({
-  releases: require('../releases.json'),
-  loglevel: process.argv.includes('--debug') || process.env.CI ? 'verbose' : 'info',
-  prerelease: false,
-  useCurrent: checkOnly,
-  contentPath,
-  navPath,
-})
-  .then(() => {
+;(async () => {
+  try {
+    await build({
+      cache: await CacheVersionSha.load(join(ROOT, 'cli-cache.json')),
+      releases: require('../releases.json'),
+      loglevel: process.argv.includes('--debug') || process.env.CI ? 'verbose' : 'info',
+      prerelease: false,
+      useCurrent: checkOnly,
+      contentPath,
+      navPath,
+    })
     if (checkOnly) {
       checkContent()
     }
     return console.log('DONE')
-  })
-  .catch(e => {
+  } catch (e) {
     console.error(e)
     process.exit(1)
-  })
+  }
+})()

cli/lib/build.js

@@ -55,7 +55,7 @@ const getCurrentVersions = nav => {
   }
 }
 
-const main = async ({loglevel, releases: rawReleases, useCurrent, navPath, contentPath, prerelease}) => {
+const main = async ({loglevel, releases: rawReleases, useCurrent, navPath, contentPath, prerelease, cache}) => {
   /* istanbul ignore next */
   if (loglevel) {
     log.on(loglevel)
@@ -113,10 +113,18 @@ const main = async ({loglevel, releases: rawReleases, useCurrent, navPath, conte
     }
   })
 
+  /**
+   * this voids the cache when a new version is added to release.json / not in the cli-cache.json
+   * this is done so that the previous major versions nav can be reset to legacy and pages can be droped from its variant
+   */
+  cache?.voidOnNewKey(releases.map(v => v.id))
+
   const updates = await Promise.all(
-    releases.map(r => extractRelease(r, {contentPath, baseNav: navData, prerelease})),
+    releases.map(r => extractRelease(r, {cache, contentPath, baseNav: navData, prerelease})),
   ).then(r => r.filter(Boolean))
 
+  await cache?.save()
+
   await updateNav(updates, {nav: navDoc, path: navPath})
 }
 

cli/lib/cache.js

@@ -0,0 +1,55 @@
+const fs = require('fs/promises')
+
+/** cache npm cli version shas to NOT pull down changes we already have */
+class CacheVersionSha {
+  shouldVoid = false
+
+  constructor(cache, path) {
+    this.cache = cache
+    this.path = path
+  }
+
+  static async load(path) {
+    return new CacheVersionSha(JSON.parse(await fs.readFile(path, 'utf-8')), path)
+  }
+
+  get keys() {
+    return Object.keys(this.cache)
+  }
+
+  voidOnNewKey(keys) {
+    if (keys.length !== this.keys.length || !keys.every(key => this.keys.includes(key))) {
+      this.shouldVoid = true
+    }
+  }
+
+  async save() {
+    const sortedCache = {}
+    Object.keys(this.cache)
+      .sort((a, b) => {
+        const numA = parseInt(a.replace('v', ''), 10)
+        const numB = parseInt(b.replace('v', ''), 10)
+        return numA - numB
+      })
+      .forEach(key => {
+        sortedCache[key] = this.cache[key]
+      })
+    this.cache = sortedCache
+    await fs.writeFile(this.path, JSON.stringify(this.cache, null, 2))
+    return this
+  }
+
+  set(id, sha) {
+    this.cache[id] = sha
+    return this
+  }
+
+  same(id, value) {
+    if (this.shouldVoid) return false
+    return this.cache[id] === value
+  }
+}
+
+module.exports = {
+  CacheVersionSha,
+}

cli/lib/extract.js

@@ -138,7 +138,16 @@ const writeChangelog = async ({release, nav, cwd, srcPath, contentPath}) => {
   })
 }
 
-const unpackRelease = async (release, {contentPath, baseNav, prerelease = false}) => {
+const unpackRelease = async (release, {cache, contentPath, baseNav, prerelease = false}) => {
+  if (cache) {
+    const sha = await gh.getCurrentSha(release.branch)
+    if (cache.same(release.id, sha)) {
+      log.info(`Skipping ${release.id} due to cache`)
+      return
+    }
+    cache.set(release.id, sha)
+  }
+
   if (release.prerelease && !prerelease) {
     log.info(`Skipping ${release.id} due to prerelease ${release.version}`)
     return

cli/lib/gh.js

@@ -1,14 +1,32 @@
 const {posix, sep} = require('node:path')
+const {execSync} = require('node:child_process')
 
 if (!process.env.GITHUB_TOKEN) {
-  throw new Error('GITHUB_TOKEN env var is required to build CLI docs')
+  try {
+    // this allows people to run this locally
+    process.env.GITHUB_TOKEN = execSync('gh auth token', {encoding: 'utf8'}).trim()
+  } catch (err) {
+    throw new Error('GITHUB_TOKEN env var is required to build CLI docs')
+  }
 }
 
 let octokit
 const owner = 'npm'
 const repo = 'cli'
 const opts = {owner, repo}
 
+const getCurrentSha = async branch => {
+  if (!octokit) {
+    const {Octokit} = await import('@octokit/rest')
+    octokit = new Octokit({auth: process.env.GITHUB_TOKEN})
+  }
+  const {data} = await octokit.repos.getBranch({
+    ...opts,
+    branch,
+  })
+  return data.commit.sha
+}
+
 const getFile = async ({sha, ref, path}) => {
   if (!octokit) {
     const {Octokit} = await import('@octokit/rest')
@@ -51,5 +69,6 @@ const pathExists = async (ref, path) => {
 module.exports = {
   getFile,
   pathExists,
+  getCurrentSha,
   nwo: `${owner}/${repo}`,
 }

cli/package.json

@@ -23,15 +23,15 @@
     "front-matter": "^4.0.2",
     "minimatch": "^10.0.1",
     "minipass": "^7.0.4",
-    "pacote": "^20.0.0",
+    "pacote": "^21.0.0",
     "proc-log": "^5.0.0",
     "semver": "^7.5.4",
     "tar": "^7.0.1",
     "yaml": "^2.3.4"
   },
   "devDependencies": {
     "@npmcli/eslint-config": "^5.0.0",
-    "@npmcli/template-oss": "4.23.4",
+    "@npmcli/template-oss": "4.23.6",
     "tap": "^21.0.0"
   },
   "author": "GitHub Inc.",
@@ -40,7 +40,7 @@
   },
   "templateOSS": {
     "//@npmcli/template-oss": "This file is partially managed by @npmcli/template-oss. Edits may be overwritten.",
-    "version": "4.23.4",
+    "version": "4.23.6",
     "content": "./scripts/template-oss"
   },
   "files": [

cli/releases.json

@@ -1,12 +1,4 @@
 [
-  {
-    "id": "v6",
-    "branch": "release/v6"
-  },
-  {
-    "id": "v7",
-    "branch": "release/v7"
-  },
   {
     "id": "v8",
     "branch": "release/v8"
@@ -17,6 +9,10 @@
   },
   {
     "id": "v10",
+    "branch": "release/v10"
+  },
+  {
+    "id": "v11",
     "branch": "latest"
   }
 ]

cli/test/index.js

@@ -66,6 +66,7 @@ const mockBuild = async (t, {releases = getReleases(), packument = {}, testdir:
     return yaml.stringify(children).replace(new RegExp(`/cli/${id}/`, 'g'), '/')
   }
 
+  let shaCounter = 0
   const build = t.mockRequire('../lib/build', {
     pacote: {
       ...pacote,
@@ -83,6 +84,10 @@ const mockBuild = async (t, {releases = getReleases(), packument = {}, testdir:
     },
     '@prettier/sync': {format: s => s},
     '../lib/gh.js': {
+      getCurrentSha: async () => {
+        shaCounter = shaCounter + 1
+        return 'abc' + shaCounter
+      },
       getFile: async ({ref}) => navSection(ref),
       pathExists: async (ref, p) => {
         if (ref.includes('v6') && p.includes('docs/lib/content')) {

content/cli/v10/commands/index.mdx

@@ -2,29 +2,16 @@
 title: CLI Commands
 shortName: Commands
 github_repo: npm/cli
-github_branch: latest
+github_branch: release/v10
 github_path: docs/lib/content/nav.yml
 redirect_from:
-  - /cli-commands
-  - /cli-commands/index
-  - /cli-documentation/cli
-  - /cli-documentation/cli-commands
-  - /cli-documentation/cli-commands/index
-  - /cli-documentation/commands
-  - /cli-documentation/commands/index
   - /cli-documentation/v10/cli-commands
   - /cli-documentation/v10/cli-commands/index
   - /cli-documentation/v10/commands
   - /cli-documentation/v10/commands/index
-  - /cli/cli-commands
-  - /cli/cli-commands/index
-  - /cli/commands
-  - /cli/commands/index
   - /cli/v10/cli-commands
   - /cli/v10/cli-commands/index
   - /cli/v10/commands/index
-  - /commands
-  - /commands/index
 ---
 
 <Index depth="1" />

content/cli/v10/commands/npm-access.mdx

@@ -3,36 +3,20 @@ title: npm-access
 section: 1
 description: Set access level on published packages
 github_repo: npm/cli
-github_branch: latest
+github_branch: release/v10
 github_path: docs/lib/content/commands/npm-access.md
 redirect_from:
-  - /cli-commands/access
-  - /cli-commands/npm-access
-  - /cli-documentation/access
-  - /cli-documentation/cli-commands/access
-  - /cli-documentation/cli-commands/npm-access
-  - /cli-documentation/commands/access
-  - /cli-documentation/commands/npm-access
-  - /cli-documentation/npm-access
   - /cli-documentation/v10/access
   - /cli-documentation/v10/cli-commands/access
   - /cli-documentation/v10/cli-commands/npm-access
   - /cli-documentation/v10/commands/access
   - /cli-documentation/v10/commands/npm-access
   - /cli-documentation/v10/npm-access
-  - /cli/access
-  - /cli/cli-commands/access
-  - /cli/cli-commands/npm-access
-  - /cli/commands/access
-  - /cli/commands/npm-access
-  - /cli/npm-access
   - /cli/v10/access
   - /cli/v10/cli-commands/access
   - /cli/v10/cli-commands/npm-access
   - /cli/v10/commands/access
   - /cli/v10/npm-access
-  - /commands/access
-  - /commands/npm-access
 ---
 
 ### Synopsis

content/cli/v10/commands/npm-adduser.mdx

@@ -3,36 +3,20 @@ title: npm-adduser
 section: 1
 description: Add a registry user account
 github_repo: npm/cli
-github_branch: latest
+github_branch: release/v10
 github_path: docs/lib/content/commands/npm-adduser.md
 redirect_from:
-  - /cli-commands/adduser
-  - /cli-commands/npm-adduser
-  - /cli-documentation/adduser
-  - /cli-documentation/cli-commands/adduser
-  - /cli-documentation/cli-commands/npm-adduser
-  - /cli-documentation/commands/adduser
-  - /cli-documentation/commands/npm-adduser
-  - /cli-documentation/npm-adduser
   - /cli-documentation/v10/adduser
   - /cli-documentation/v10/cli-commands/adduser
   - /cli-documentation/v10/cli-commands/npm-adduser
   - /cli-documentation/v10/commands/adduser
   - /cli-documentation/v10/commands/npm-adduser
   - /cli-documentation/v10/npm-adduser
-  - /cli/adduser
-  - /cli/cli-commands/adduser
-  - /cli/cli-commands/npm-adduser
-  - /cli/commands/adduser
-  - /cli/commands/npm-adduser
-  - /cli/npm-adduser
   - /cli/v10/adduser
   - /cli/v10/cli-commands/adduser
   - /cli/v10/cli-commands/npm-adduser
   - /cli/v10/commands/adduser
   - /cli/v10/npm-adduser
-  - /commands/adduser
-  - /commands/npm-adduser
 ---
 
 ### Synopsis