chore: update snapshot tests for new docs

.github/workflows/ci-docs.yml → .github/workflows/ci-npmcli-docs.yml

@@ -1,6 +1,6 @@
 # This file is automatically added by @npmcli/template-oss. Do not edit.
 
-name: CI - docs
+name: CI - @npmcli/docs
 
 on:
   workflow_dispatch:
@@ -71,9 +71,9 @@ jobs:
       - name: Reset Deps
         run: node . run resetdeps
       - name: Lint
-        run: node . run lint --ignore-scripts -w docs
+        run: node . run lint --ignore-scripts -w @npmcli/docs
       - name: Post Lint
-        run: node . run postlint --ignore-scripts -w docs
+        run: node . run postlint --ignore-scripts -w @npmcli/docs
 
   test:
     name: Test - ${{ matrix.platform.name }} - ${{ matrix.node-version }}
@@ -114,7 +114,7 @@ jobs:
       - name: Add Problem Matcher
         run: echo "::add-matcher::.github/matchers/tap.json"
       - name: Test
-        run: node . test --ignore-scripts -w docs
+        run: node . test --ignore-scripts -w @npmcli/docs
       - name: Check Git Status
         if: matrix && matrix.platform.os != 'windows-latest'
         run: node scripts/git-dirty.js

DEPENDENCIES.md

@@ -117,6 +117,7 @@ graph LR;
   npm-->npmcli-arborist["@npmcli/arborist"];
   npm-->npmcli-ci-detect["@npmcli/ci-detect"];
   npm-->npmcli-config["@npmcli/config"];
+  npm-->npmcli-docs["@npmcli/docs"];
   npm-->npmcli-eslint-config["@npmcli/eslint-config"];
   npm-->npmcli-fs["@npmcli/fs"];
   npm-->npmcli-git["@npmcli/git"];
@@ -193,6 +194,10 @@ graph LR;
   npmcli-config-->proc-log;
   npmcli-config-->read-package-json-fast;
   npmcli-config-->semver;
+  npmcli-docs-->ignore-walk;
+  npmcli-docs-->npmcli-eslint-config["@npmcli/eslint-config"];
+  npmcli-docs-->npmcli-fs["@npmcli/fs"];
+  npmcli-docs-->npmcli-template-oss["@npmcli/template-oss"];
   npmcli-fs-->semver;
   npmcli-git-->npm-pick-manifest;
   npmcli-git-->npmcli-promise-spawn["@npmcli/promise-spawn"];
@@ -388,19 +393,6 @@ graph LR;
   detab-->repeat-string;
   dezalgo-->asap;
   dezalgo-->wrappy;
-  docs-->cmark-gfm;
-  docs-->front-matter;
-  docs-->ignore-walk;
-  docs-->isaacs-string-locale-compare["@isaacs/string-locale-compare"];
-  docs-->jsdom;
-  docs-->marked-man;
-  docs-->mdx-js-mdx["@mdx-js/mdx"];
-  docs-->mkdirp;
-  docs-->npmcli-eslint-config["@npmcli/eslint-config"];
-  docs-->npmcli-fs["@npmcli/fs"];
-  docs-->npmcli-template-oss["@npmcli/template-oss"];
-  docs-->tap;
-  docs-->yaml;
   domexception-->webidl-conversions;
   encoding-->iconv-lite;
   end-of-stream-->once;
@@ -701,7 +693,6 @@ graph LR;
   npm-->cli-columns;
   npm-->cli-table3;
   npm-->columnify;
-  npm-->docs;
   npm-->fastest-levenshtein;
   npm-->fs-minipass;
   npm-->glob;
@@ -745,6 +736,7 @@ graph LR;
   npm-->npmcli-arborist["@npmcli/arborist"];
   npm-->npmcli-ci-detect["@npmcli/ci-detect"];
   npm-->npmcli-config["@npmcli/config"];
+  npm-->npmcli-docs["@npmcli/docs"];
   npm-->npmcli-eslint-config["@npmcli/eslint-config"];
   npm-->npmcli-fs["@npmcli/fs"];
   npm-->npmcli-git["@npmcli/git"];
@@ -855,6 +847,19 @@ graph LR;
   npmcli-config-->semver;
   npmcli-config-->walk-up-path;
   npmcli-disparity-colors-->ansi-styles;
+  npmcli-docs-->cmark-gfm;
+  npmcli-docs-->front-matter;
+  npmcli-docs-->ignore-walk;
+  npmcli-docs-->isaacs-string-locale-compare["@isaacs/string-locale-compare"];
+  npmcli-docs-->jsdom;
+  npmcli-docs-->marked-man;
+  npmcli-docs-->mdx-js-mdx["@mdx-js/mdx"];
+  npmcli-docs-->mkdirp;
+  npmcli-docs-->npmcli-eslint-config["@npmcli/eslint-config"];
+  npmcli-docs-->npmcli-fs["@npmcli/fs"];
+  npmcli-docs-->npmcli-template-oss["@npmcli/template-oss"];
+  npmcli-docs-->tap;
+  npmcli-docs-->yaml;
   npmcli-fs-->gar-promisify["@gar/promisify"];
   npmcli-fs-->semver;
   npmcli-git-->lru-cache;
@@ -1109,6 +1114,6 @@ packages higher up the chain.
  - pacote, libnpmaccess, libnpmhook, libnpmorg, libnpmsearch, libnpmteam, npm-profile
  - npm-registry-fetch, libnpmversion
  - @npmcli/git, make-fetch-happen, @npmcli/config, init-package-json
- - @npmcli/installed-package-contents, @npmcli/map-workspaces, cacache, npm-pick-manifest, @npmcli/run-script, npm-packlist, read-package-json, @npmcli/query, readdir-scoped-modules, promzard
- - npm-bundled, read-package-json-fast, @npmcli/fs, unique-filename, @npmcli/promise-spawn, npm-install-checks, npm-package-arg, normalize-package-data, @npmcli/package-json, bin-links, nopt, npmlog, parse-conflict-json, dezalgo, read
- - npm-normalize-package-bin, @npmcli/name-from-folder, json-parse-even-better-errors, semver, @npmcli/move-file, fs-minipass, infer-owner, ssri, unique-slug, hosted-git-info, proc-log, validate-npm-package-name, @npmcli/node-gyp, ignore-walk, minipass-fetch, cmd-shim, read-cmd-shim, write-file-atomic, abbrev, are-we-there-yet, gauge, wrappy, treeverse, @npmcli/eslint-config, @npmcli/template-oss, minify-registry-metadata, @npmcli/disparity-colors, @npmcli/ci-detect, mute-stream, ini, npm-audit-report, npm-user-validate
+ - @npmcli/docs, @npmcli/installed-package-contents, @npmcli/map-workspaces, cacache, npm-pick-manifest, @npmcli/run-script, npm-packlist, read-package-json, @npmcli/query, readdir-scoped-modules, promzard
+ - @npmcli/fs, npm-bundled, read-package-json-fast, unique-filename, @npmcli/promise-spawn, npm-install-checks, npm-package-arg, normalize-package-data, @npmcli/package-json, bin-links, nopt, npmlog, parse-conflict-json, dezalgo, read
+ - semver, ignore-walk, @npmcli/eslint-config, @npmcli/template-oss, npm-normalize-package-bin, @npmcli/name-from-folder, json-parse-even-better-errors, @npmcli/move-file, fs-minipass, infer-owner, ssri, unique-slug, hosted-git-info, proc-log, validate-npm-package-name, @npmcli/node-gyp, minipass-fetch, cmd-shim, read-cmd-shim, write-file-atomic, abbrev, are-we-there-yet, gauge, wrappy, treeverse, minify-registry-metadata, @npmcli/disparity-colors, @npmcli/ci-detect, mute-stream, ini, npm-audit-report, npm-user-validate

docs/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "docs",
+  "name": "@npmcli/docs",
   "description": "The npm cli documentation",
   "version": "1.0.0",
   "private": true,
@@ -36,7 +36,7 @@
   },
   "devDependencies": {
     "@npmcli/eslint-config": "^3.1.0",
-    "@npmcli/template-oss": "4.5.1",
+    "@npmcli/template-oss": "4.7.1",
     "tap": "^16.0.1"
   },
   "author": "GitHub Inc.",

lib/commands/completion.js

@@ -33,9 +33,9 @@ const fs = require('@npmcli/fs')
 const nopt = require('nopt')
 
 const { definitions, shorthands } = require('../utils/config/index.js')
-const { aliases, cmdList, plumbing } = require('../utils/cmd-list.js')
+const { aliases, commands, plumbing } = require('../utils/cmd-list.js')
 const aliasNames = Object.keys(aliases)
-const fullList = cmdList.concat(aliasNames).filter(c => !plumbing.includes(c))
+const fullList = commands.concat(aliasNames).filter(c => !plumbing.includes(c))
 const configNames = Object.keys(definitions)
 const shorthandNames = Object.keys(shorthands)
 const allConfs = configNames.concat(shorthandNames)

lib/commands/publish.js

@@ -16,7 +16,7 @@ const { getContents, logTar } = require('../utils/tar.js')
 // keys that npm supports in .npmrc files and elsewhere.  We *may* want to
 // revisit this at some point, and have a minimal set that's a SemVer-major
 // change that ought to get a RFC written on it.
-const flatten = require('../utils/config/flatten.js')
+const { flatten } = require('../utils/config/index.js')
 
 // this is the only case in the CLI where we want to use the old full slow
 // 'read-package-json' module, because we want to pull in all the defaults and

lib/commands/unpublish.js

@@ -6,7 +6,7 @@ const path = require('path')
 const util = require('util')
 const readJson = util.promisify(require('read-package-json'))
 
-const flatten = require('../utils/config/flatten.js')
+const { flatten } = require('../utils/config/index.js')
 const getIdentity = require('../utils/get-identity.js')
 const log = require('../utils/log-shim')
 const otplease = require('../utils/otplease.js')

lib/utils/cmd-list.js

@@ -1,4 +1,5 @@
 const abbrev = require('abbrev')
+const localeCompare = require('@isaacs/string-locale-compare')('en')
 
 // plumbing should not have any aliases
 const aliases = {
@@ -69,8 +70,7 @@ const aliases = {
 }
 
 // these are filenames in .
-// Keep these sorted so that lib/utils/npm-usage.js outputs in order
-const cmdList = [
+const commands = [
   'access',
   'adduser',
   'audit',
@@ -141,11 +141,13 @@ const cmdList = [
 ]
 
 const plumbing = ['birthday', 'help-search']
-const abbrevs = abbrev(cmdList.concat(Object.keys(aliases)))
+const allCommands = [...commands, ...plumbing].sort(localeCompare)
+const abbrevs = abbrev(commands.concat(Object.keys(aliases)))
 
 module.exports = {
   abbrevs,
   aliases,
-  cmdList,
+  commands,
   plumbing,
+  allCommands,
 }

lib/utils/config/index.js

@@ -1,6 +1,35 @@
-const flatten = require('./flatten.js')
 const definitions = require('./definitions.js')
-const describeAll = require('./describe-all.js')
+
+// use the defined flattening function, and copy over any scoped
+// registries and registry-specific "nerfdart" configs verbatim
+//
+// TODO: make these getters so that we only have to make dirty
+// the thing that changed, and then flatten the fields that
+// could have changed when a config.set is called.
+//
+// TODO: move nerfdart auth stuff into a nested object that
+// is only passed along to paths that end up calling npm-registry-fetch.
+const flatten = (obj, flat = {}) => {
+  for (const [key, val] of Object.entries(obj)) {
+    const def = definitions[key]
+    if (def && def.flatten) {
+      def.flatten(key, obj, flat)
+    } else if (/@.*:registry$/i.test(key) || /^\/\//.test(key)) {
+      flat[key] = val
+    }
+  }
+
+  // XXX make this the bin/npm-cli.js file explicitly instead
+  // otherwise using npm programmatically is a bit of a pain.
+  flat.npmBin = require.main ? require.main.filename
+    : /* istanbul ignore next - not configurable property */ undefined
+  flat.nodeBin = process.env.NODE || process.execPath
+
+  // XXX should this be sha512?  is it even relevant?
+  flat.hashAlgorithm = 'sha1'
+
+  return flat
+}
 
 // aliases where they get expanded into a completely different thing
 // these are NOT supported in the environment or npmrc files, only
@@ -26,30 +55,24 @@ const shorthands = {
   readonly: ['--read-only'],
   reg: ['--registry'],
   iwr: ['--include-workspace-root'],
-}
-
-for (const [key, { short }] of Object.entries(definitions)) {
-  if (!short) {
-    continue
-  }
-  // can be either an array or string
-  for (const s of [].concat(short)) {
-    shorthands[s] = [`--${key}`]
-  }
+  ...Object.entries(definitions).reduce((acc, [key, { short = [] }]) => {
+    // can be either an array or string
+    for (const s of [].concat(short)) {
+      acc[s] = [`--${key}`]
+    }
+    return acc
+  }, {}),
 }
 
 module.exports = {
   get defaults () {
     // NB: 'default' is a reserved word
-    return Object.entries(definitions).map(([key, { default: def }]) => {
-      return [key, def]
-    }).reduce((defaults, [key, def]) => {
-      defaults[key] = def
-      return defaults
+    return Object.entries(definitions).reduce((acc, [key, { default: d }]) => {
+      acc[key] = d
+      return acc
     }, {})
   },
   definitions,
   flatten,
   shorthands,
-  describeAll,
 }

lib/utils/did-you-mean.js

@@ -1,10 +1,10 @@
 const { distance } = require('fastest-levenshtein')
 const readJson = require('read-package-json-fast')
-const { cmdList } = require('./cmd-list.js')
+const { commands } = require('./cmd-list.js')
 
 const didYouMean = async (npm, path, scmd) => {
   // const cmd = await npm.cmd(str)
-  const close = cmdList.filter(cmd => distance(scmd, cmd) < scmd.length * 0.4 && scmd !== cmd)
+  const close = commands.filter(cmd => distance(scmd, cmd) < scmd.length * 0.4 && scmd !== cmd)
   let best = []
   for (const str of close) {
     const cmd = await npm.cmd(str)

lib/utils/npm-usage.js

@@ -1,5 +1,5 @@
 const { dirname } = require('path')
-const { cmdList } = require('./cmd-list')
+const { commands } = require('./cmd-list')
 const localeCompare = require('@isaacs/string-locale-compare')('en')
 
 module.exports = async (npm) => {
@@ -35,7 +35,7 @@ const allCommands = async (npm) => {
   if (npm.config.get('long')) {
     return usages(npm)
   }
-  return ('\n    ' + wrap(cmdList))
+  return ('\n    ' + wrap(commands))
 }
 
 const wrap = (arr) => {
@@ -60,7 +60,7 @@ const usages = async (npm) => {
   // return a string of <command>: <usage>
   let maxLen = 0
   const set = []
-  for (const c of cmdList) {
+  for (const c of commands) {
     const cmd = await npm.cmd(c)
     set.push([c, cmd.usage])
     maxLen = Math.max(maxLen, c.length)