@mnci/cli 4.5.0 → 4.6.1

package/README.md

@@ -429,15 +429,20 @@ that would just fail felt worse than being upfront that it doesn't exist yet.
    `{projectName}@{version}` tags, **tag-only git** (`commit: false`) — nothing
    is ever pushed to `main`; future runs resolve versions from tag names. Also
    fills in `namedInputs.sharedGlobals` with the root config files
-   (`eslint.config.mjs`, `tsconfig.base.json`, `package.json`), without which
+   (`eslint.config.mjs`, `eslint.config.mnci.mjs`, `tsconfig.base.json`,
+   `package.json`), without which
    `nx affected` on a pull request is blind to them: they live in no project, so
    changing one marked only the root pseudo-project — which has no
    lint/typecheck/test/build target — and the affected-scoped verify step ran
    nothing at all while reporting green.
-3. Writes `eslint.config.mjs` (one import from `@mnci/eslint-config` — the whole
-   linting opinion, in one root config — plus a commented inventory naming every
-   config block and how to override it — there is no formatter config, because
-   ESLint is the formatter), `.npmrc` (publish auth — see **Publish auth** below),
+3. Writes **two** ESLint files, and only one of them is mnci's:
+   `eslint.config.mnci.mjs` holds the whole linting opinion (one import from
+   `@mnci/eslint-config`, plus a commented inventory naming every config block)
+   and is rewritten on every upgrade; `eslint.config.mjs` is the file ESLint
+   actually loads, imports that one, holds **your** blocks, and is written once
+   and then never touched again. See **Your half of the ESLint config** below.
+   There is no formatter config, because ESLint is the formatter. Also writes
+   `.npmrc` (publish auth — see **Publish auth** below),
    `commitlint.config.mjs`, a husky `commit-msg` hook, the chosen CI provider's
    pipeline file(s)
    (`azure-pipelines.yml` and/or `.github/workflows/ci.yml`, `--ci`, default
@@ -460,7 +465,8 @@ same options `new` would have and calls the exact same `applyOverlay` `new`
 itself calls — the one function that does every bit of `mnci`-owned file
 writing (`nx.json`'s `release`/`sync`/`generators`/`namedInputs.sharedGlobals`/
 `mnci` blocks, `.npmrc`,
-`eslint.config.mjs`, `commitlint.config.mjs`,
+`eslint.config.mnci.mjs` (**not** `eslint.config.mjs` — see below),
+`commitlint.config.mjs`,
 `.husky/commit-msg`, the CI pipeline file(s), `.devcontainer/devcontainer.json`, the
 `<workspace-name>.code-workspace` file, and the curated root `package.json`
 scripts). Nothing else in the workspace — app/lib source, `project.json` targets
@@ -532,8 +538,52 @@ stack:
 | --------------- | ------------------ | ------- | ---------------------------------------------------------------------------------------- |
 | `--test-runner` | `jest` \| `vitest` | `jest`  | `nx.json` generator `unitTestRunner` default; the hand-built function app follows it too |
 
+### Your half of the ESLint config
+
+There are two root ESLint files, and the split exists because the old
+single-file layout lost work. `eslint.config.mjs` used to be mnci-owned and
+rewritten wholesale on every `mnci upgrade` — so a block appended to it, in the
+way a comment mnci itself wrote three lines above described, was deleted
+without a word. Worse, `upgrade` then tells you to run `npm run format`, so the
+first thing that happens after your overrides vanish is every file in the
+repository being rewritten against the rules you thought you had changed.
+
+So:
+
+| File | Owner | On `mnci upgrade` |
+| --- | --- | --- |
+| `eslint.config.mnci.mjs` | mnci | rewritten every time |
+| `eslint.config.mjs` | you | written once, then never touched |
+
+`eslint.config.mjs` is what ESLint loads, because `eslint.config.mjs` is
+ESLint's own default filename — the file the tool looks for has to be the one
+you own, or the tool's default is the one mnci overwrites.
+
+```js
+import mnci from './eslint.config.mnci.mjs'
+
+export default [
+  ...mnci(),
+  { name: 'local/legacy-app-allows-any', files: ['apps/legacy/**/*.ts'], rules: { … } },
+]
+```
+
+The owned file exports a **function**, not a resolved array, so options still
+reach `@mnci/eslint-config` from the file you own:
+`...mnci({ verticalSlices: ['packages/*/src/**/*.ts'] })`. An array would have
+had nowhere to receive them — mnci's own repository passes `verticalSlices`,
+which is how that was caught.
+
+**Upgrading an existing workspace.** If your `eslint.config.mjs` is still the
+old single-file one and you never edited it, `mnci upgrade` moves it onto the
+split for you: it replaces the file only when it provably holds nothing but
+mnci's own output. If you did edit it, it is left exactly as it is and
+`mnci doctor` reports that it no longer imports the rules, with the line to
+add. mnci does not rewrite that file any more — which is the point, and also
+why it cannot do this part for you.
+
 **Linting and formatting are unified across the workspace, from exactly one
-config file each.** The root `eslint.config.mjs` is three lines importing
+pair of config files.** The rules are three lines importing
 [`@mnci/eslint-config`](../eslint-config/README.md); every `@nx/*` generator
 drops a config into the project it creates, and `mnci add` deletes it. Projects
 still get their `lint` target: `@nx/eslint/plugin` infers it by mapping config

package/dist/cli.js

@@ -313,8 +313,24 @@ function npmrcContent(registry, scope) {
   if (registry.kind === "npm") {
     return `; Publish authentication for the public npm registry.
 ;
-; NODE_AUTH_TOKEN is exported by the generated CI's release step; an unset value
-; is harmless locally, so no token is needed for day-to-day work.
+; NODE_AUTH_TOKEN is exported by the generated CI's release step. Nothing needs
+; it for day-to-day work here - installing, building and testing never
+; authenticate.
+;
+; It is NOT harmless the moment you DO want to authenticate from this directory,
+; which an earlier version of this comment claimed. A project .npmrc wins over
+; your user one, so with NODE_AUTH_TOKEN unset this line hands npm an empty
+; token and overrides 'npm login': inside this repo 'npm whoami' fails with a
+; 401 and any write is refused. The refusal is easy to misread, because for a
+; scoped package the registry answers a write you are not allowed to make with
+;
+;   npm error 404 Not Found - PUT https://registry.npmjs.org/@scope%2fthing
+;
+; and everything above it is npm listing what it intended to send, so a long
+; healthy-looking run still changes nothing.
+;
+; To publish or deprecate by hand, run it from outside this directory, or export
+; a real token first.
 //registry.npmjs.org/:_authToken=\${NODE_AUTH_TOKEN}
 
 ; There is deliberately NO '${scope}:registry' line here. npmjs.org is already
@@ -403,6 +419,7 @@ function withEslintPlugin(nxJson) {
 }
 var SHARED_GLOBAL_INPUTS = [
   "{workspaceRoot}/eslint.config.mjs",
+  "{workspaceRoot}/eslint.config.mnci.mjs",
   "{workspaceRoot}/tsconfig.base.json",
   "{workspaceRoot}/package.json"
 ];
@@ -583,26 +600,15 @@ var ESLINT_BLOCK_INVENTORY = `// WHAT IS IN HERE. Each line is one config block,
 //
 // To list them as ESLint actually resolves them:  npx eslint --inspect-config
 `;
-var ESLINT_CONFIG = `import mnci from '@mnci/eslint-config'
+var ESLINT_MNCI_FILENAME = "eslint.config.mnci.mjs";
+var ESLINT_USER_FILENAME = "eslint.config.mjs";
+var ESLINT_MNCI_CONFIG = `// GENERATED BY mnci. Every \`mnci upgrade\` overwrites this file.
+//
+// Do not edit it: put your own blocks in eslint.config.mjs next to it, which
+// imports this one and which mnci never touches once it exists.
+import mnci from '@mnci/eslint-config'
 
 ${ESLINT_BLOCK_INVENTORY}//
-// TO OVERRIDE a rule, append a block AFTER the spread \u2014 later blocks win, so one
-// of your own beats anything above it. Give it a name, so the inspector shows
-// where the change came from:
-//
-//   export default [
-//     ...mnci({ workspaceRoot: import.meta.dirname }),
-//     {
-//       name: 'local/legacy-app-allows-any',
-//       files: ['apps/legacy/**/*.ts'],
-//       rules: { '@typescript-eslint/no-explicit-any': 'off' }
-//     }
-//   ]
-//
-// Do NOT edit @mnci/eslint-config inside node_modules, and do not fork it: it is
-// a dependency, so \`npm update\` brings rule fixes in the way it brings any
-// other. An override here survives that; an edit to the package does not.
-//
 // FORMATTING IS LINTING HERE. There is no Prettier, no oxfmt and no
 // \`format:check\` \u2014 \`npm run lint\` reports indentation, quotes and spacing as
 // ordinary errors, and \`npm run format\` is \`eslint . --fix\`. So do not add a
@@ -614,8 +620,64 @@ ${ESLINT_BLOCK_INVENTORY}//
 // enough on its own \u2014 neither needs a config file, and with none present they
 // format against their own defaults (semicolons, double quotes), which is the
 // inverse of Standard.
-export default mnci({ workspaceRoot: import.meta.dirname })
+//
+// Exported as a FUNCTION, not as the resolved array. @mnci/eslint-config takes
+// options \u2014 \`verticalSlices\` is the one a workspace is most likely to want \u2014
+// and an already-resolved array has nowhere to receive them. Calling it from
+// eslint.config.mjs is what keeps every option reachable from the file you own.
+//
+// \`workspaceRoot\` is resolved HERE because both files sit at the root, and it
+// is what enables the @nx/dependency-checks block.
+//
+// A named function declaration, exported inline. Both shapes matter and both
+// are enforced by this very config: \`unicorn/no-anonymous-default-export\`
+// rejects an anonymous arrow, and \`unicorn/default-export-style\` rejects
+// declaring one above the export and referring to it. Either mistake fails a
+// generated workspace's own lint on its first run.
+export default function mnciConfig (options = {}) {
+  return mnci({ workspaceRoot: import.meta.dirname, ...options })
+}
 `;
+var ESLINT_USER_CONFIG = `// This file is YOURS. mnci writes it once and never touches it again, so
+// anything you add here survives \`mnci upgrade\`.
+//
+// The rules live in ./eslint.config.mnci.mjs, which mnci DOES rewrite on every
+// upgrade \u2014 so put your changes here, not there.
+import mnci from './${ESLINT_MNCI_FILENAME}'
+
+// TO CONFIGURE the shared rules, pass options to mnci() below \u2014 e.g.
+// \`...mnci({ verticalSlices: ['packages/*/src/**/*.ts'] })\`.
+//
+// TO OVERRIDE a rule, append a block AFTER the spread \u2014 later blocks win, so
+// one of your own beats anything above it. Give it a name, so
+// \`npx eslint --inspect-config\` shows where the change came from:
+//
+//   {
+//     name: 'local/legacy-app-allows-any',
+//     files: ['apps/legacy/**/*.ts'],
+//     rules: { '@typescript-eslint/no-explicit-any': 'off' }
+//   }
+//
+// Do NOT edit @mnci/eslint-config inside node_modules, and do not fork it: it
+// is a dependency, so \`npm update\` brings rule fixes in the way it brings any
+// other. An override here survives that; an edit to the package does not.
+export default [
+  ...mnci(),
+]
+`;
+function isUnmodifiedMnciEslintConfig(content) {
+  const code = content.split("\n").map((line) => line.trim()).filter((line) => line !== "" && !line.startsWith("//"));
+  return code.length === 2 && code[0] === "import mnci from '@mnci/eslint-config'" && code[1] === "export default mnci({ workspaceRoot: import.meta.dirname })";
+}
+function writeEslintEntryPoint(workspaceRoot, onProgress) {
+  const path = (0, import_node_path2.join)(workspaceRoot, ESLINT_USER_FILENAME);
+  if ((0, import_node_fs2.existsSync)(path) && !isUnmodifiedMnciEslintConfig((0, import_node_fs2.readFileSync)(path, "utf8"))) {
+    onProgress(`${ESLINT_USER_FILENAME} \u2014 kept as it is, it is yours`);
+    return;
+  }
+  onProgress(`${ESLINT_USER_FILENAME} \u2014 the entry point, yours to edit from now on`);
+  writeFileEnsured(path, ESLINT_USER_CONFIG);
+}
 var VSCODE_RECOMMENDED_EXTENSIONS = [
   "dbaeumer.vscode-eslint",
   "nrwl.angular-console",
@@ -873,6 +935,10 @@ var NPM_AUDIT_STEP = `node -e "const cp=require('node:child_process');const r=cp
 var VERIFY_TARGETS = "lint,typecheck,test,build";
 var AFFECTED_OR_ALL_GUARD = `node -e "const cp=require('node:child_process');const T='${VERIFY_TARGETS}';const all=()=>process.exit(cp.spawnSync('npx nx run-many -t '+T,{stdio:'inherit',shell:true}).status ?? 1);const ref=process.env.GITHUB_BASE_REF||process.env.SYSTEM_PULLREQUEST_TARGETBRANCH||'';if(!ref){console.log('Not a pull request - verifying EVERY project.');all()}const target=ref.replace('refs/heads/','');const mergeBase=r=>{const o=cp.spawnSync('git',['merge-base',r,'HEAD'],{encoding:'utf8'});return o.status===0?o.stdout.trim():''};let base=mergeBase('origin/'+target);if(!base){console.log('No origin/'+target+' ref - fetching it to resolve a merge-base.');cp.spawnSync('git',['fetch','--no-tags','origin',target],{stdio:'inherit'});base=mergeBase('FETCH_HEAD')}if(!base){console.log('Could not resolve a merge-base with '+target+' - verifying EVERY project.');all()}console.log('Pull request against '+target+' - verifying projects affected since '+base);process.exit(cp.spawnSync('npx nx affected -t '+T+' --base='+base,{stdio:'inherit',shell:true}).status ?? 1)"`;
 var PACK_APPS_GUARD = `node -e "const fs=require('node:fs');fs.mkdirSync('dist/drop',{recursive:true});const hasProjectJson=fs.globSync('apps/*/project.json').length>0;const hasInlineNx=fs.globSync('apps/*/package.json').some((f)=>{try{return Boolean(JSON.parse(fs.readFileSync(f,'utf8')).nx)}catch{return false}});const hasCsproj=fs.globSync('apps/*/*.csproj').length>0;if(!hasProjectJson&&!hasInlineNx&&!hasCsproj){console.log('No apps to pack - skipping.');process.exit(0)}process.exit(require('node:child_process').spawnSync('npx nx run-many -t package',{stdio:'inherit',shell:true}).status ?? 1)"`;
+var NPM_AUTH_PREFLIGHT = `node -e "const fs=require('node:fs'),cp=require('node:child_process');if(fs.globSync('packages/*/package.json').length===0){console.log('No npm packages to release - skipping.');process.exit(0)}if(!process.env.NODE_AUTH_TOKEN){console.error('NPM_TOKEN is empty or unset, so the publish would fail AFTER nx release has already tagged. Add it as a repository secret named exactly NPM_TOKEN - under Actions, not the Dependabot or Codespaces tab, and not an Environment secret. Use an npm Automation token - a Publish token is refused by 2FA in CI.');process.exit(1)}const r=cp.spawnSync('npm',['whoami','--registry=https://registry.npmjs.org/'],{encoding:'utf8',shell:process.platform==='win32'});if(r.status!==0){console.error('NPM_TOKEN is set but the registry rejected it - '+((r.stderr||'')+(r.stdout||'')).trim()+'. Check that it has not expired and that it grants publish rights on this scope.');process.exit(1)}console.log('npm auth OK as '+r.stdout.trim())"`;
+function npmAuthPreflight(registryKind) {
+  return registryKind === "npm" ? NPM_AUTH_PREFLIGHT : "";
+}
 var SHALLOW_CLONE_GUARD = `node -e "const r=require('node:child_process').spawnSync('git',['rev-parse','--is-shallow-repository'],{encoding:'utf8'});if(r.status!==0){console.error('Could not determine whether this checkout has full history (git rev-parse --is-shallow-repository failed) - refusing to release. '+(r.stderr||'').trim());process.exit(1)}if(r.stdout.trim()==='true'){console.error('This checkout is a shallow clone. nx release resolves the current version of each package from its git tag, and silently falls back to the permanently-stale on-disk version when a tag cannot be found - which can propose, and publish, a version DOWNGRADE. Fetch full history before releasing - set fetchDepth (Azure) or fetch-depth (GitHub) to 0.');process.exit(1)}"`;
 function releaseGuard(pythonPublishEnv, nugetPublishEnv) {
   return String.raw`node -e "const fs=require('node:fs'),cp=require('node:child_process');const npmCount=fs.globSync('packages/*/package.json').length;const csharpCount=fs.globSync('packages/*/*.csproj').length;const pythonCount=fs.globSync('python-packages/*/pyproject.toml').length;const dartCount=fs.globSync('packages/*/pubspec.yaml').length;const hasNpm=npmCount>0;const hasPython=pythonCount>0;const hasCsharp=csharpCount>0;const hasDart=dartCount>0;if(!hasNpm&&!hasPython&&!hasCsharp&&!hasDart){console.log('Nothing to release - skipping.');process.exit(0)}const specifier=process.env.RELEASE_SPECIFIER||'';let releaseCmd='npx nx release --yes';if(specifier){if(!/^(major|minor|patch|\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?)$/.test(specifier)){console.error('RELEASE_SPECIFIER value \''+specifier+'\' is invalid - use major, minor, patch, or an exact version like 1.2.3.');process.exit(1)}const releaseProjectCount=npmCount+csharpCount+pythonCount+dartCount;if(/^(major|minor|patch)$/.test(specifier)&&releaseProjectCount>1){console.error('RELEASE_SPECIFIER is a keyword (\''+specifier+'\') but this workspace has '+releaseProjectCount+' releasable packages - a keyword under-bumps interdependent packages, because nx computes the dependency-bump pass from a stale cached version. Set RELEASE_SPECIFIER to an exact version instead, or clear it.');process.exit(1)}releaseCmd='npx nx release '+specifier+' --yes'}const env={...process.env};${pythonPublishEnv}${nugetPublishEnv}process.exit(cp.spawnSync(releaseCmd,{stdio:'inherit',shell:true,env}).status ?? 1)"`;
@@ -1148,7 +1214,17 @@ steps:
   - script: ${SHALLOW_CLONE_GUARD}
     displayName: Verify this is a full checkout (nx release needs the real tag history)
     condition: ${onMain}
-
+${npmAuthPreflight(registryKind) ? `
+  # Prove npm will accept us BEFORE anything irreversible happens. nx release
+  # tags first and publishes last, so a rejected token leaves a version tagged
+  # with nothing on the registry - and that number is then skipped forever,
+  # because the next run resolves the current version from the newest tag.
+  - script: ${npmAuthPreflight(registryKind)}
+    displayName: Preflight \u2014 npm must accept the token before anything is tagged
+    condition: ${onMain}
+    env:
+      NODE_AUTH_TOKEN: $(NPM_TOKEN)
+` : ""}
   # Version + tag + publish, in one release, for npm (packages/*), Python
   # (python-packages/*) AND C# (packages/*/*.csproj) \u2014 conventional commits,
   # tag-only push. Portable guard: nx release errors on an empty scope, so
@@ -1374,7 +1450,18 @@ jobs:
       - run: ${SHALLOW_CLONE_GUARD}
         name: Verify this is a full checkout (nx release needs the real tag history)
         if: \${{ ${onMain} }}
-
+${npmAuthPreflight(registryKind) ? `
+      # Prove npm will accept us BEFORE anything irreversible happens. nx
+      # release tags first and publishes last, so a rejected token leaves a
+      # version tagged with nothing on the registry - and that number is then
+      # skipped forever, because the next run resolves the current version
+      # from the newest tag.
+      - run: ${npmAuthPreflight(registryKind)}
+        name: Preflight \u2014 npm must accept the token before anything is tagged
+        if: \${{ ${onMain} }}
+        env:
+          NODE_AUTH_TOKEN: \${{ secrets.NPM_TOKEN }}
+` : ""}
       # Version + tag + publish, in one release, for npm (packages/*), Python
       # (python-packages/*) AND C# (packages/*/*.csproj) \u2014 conventional
       # commits, tag-only push. Portable guard: nx release errors on an empty
@@ -1579,8 +1666,9 @@ function applyOverlay(workspaceRoot, options, onProgress = () => {
   const hookPath = (0, import_node_path2.join)(workspaceRoot, ".husky/commit-msg");
   writeFileEnsured(hookPath, COMMIT_MSG_HOOK);
   markExecutable(hookPath);
-  onProgress("eslint.config.mjs \u2014 the shared lint AND formatting opinion");
-  writeFileEnsured((0, import_node_path2.join)(workspaceRoot, "eslint.config.mjs"), ESLINT_CONFIG);
+  onProgress(`${ESLINT_MNCI_FILENAME} \u2014 the shared lint AND formatting opinion`);
+  writeFileEnsured((0, import_node_path2.join)(workspaceRoot, ESLINT_MNCI_FILENAME), ESLINT_MNCI_CONFIG);
+  writeEslintEntryPoint(workspaceRoot, onProgress);
   ensureEslintCacheIgnored(workspaceRoot);
   for (const retired of RETIRED_FORMATTER_FILES) {
     removeIfPresent((0, import_node_path2.join)(workspaceRoot, retired));
@@ -4444,6 +4532,21 @@ function checkEslintConfigs(workspaceRoot) {
       ok: projectConfigs.length === 0,
       detail: `found ${projectConfigs.length}: ${projectConfigs.join(", ")}`,
       remedy: "run `mnci upgrade`, which sweeps {apps,libs,packages}/*/eslint.config.*"
+    },
+    ...checkEslintEntryPointReachesTheRules(workspaceRoot)
+  ];
+}
+function checkEslintEntryPointReachesTheRules(workspaceRoot) {
+  const rules = (0, import_node_path19.join)(workspaceRoot, ESLINT_MNCI_FILENAME);
+  if (!(0, import_node_fs12.existsSync)(rules)) return [];
+  const entryPoint = (0, import_node_path19.join)(workspaceRoot, ESLINT_USER_FILENAME);
+  const source = (0, import_node_fs12.existsSync)(entryPoint) ? (0, import_node_fs12.readFileSync)(entryPoint, "utf8") : "";
+  return [
+    {
+      check: `${ESLINT_USER_FILENAME} imports the mnci rules`,
+      ok: source.includes(ESLINT_MNCI_FILENAME),
+      detail: source === "" ? `${ESLINT_USER_FILENAME} is missing, so nothing loads the rules` : `${ESLINT_USER_FILENAME} never mentions ${ESLINT_MNCI_FILENAME}`,
+      remedy: `make its first import \`import mnci from './${ESLINT_MNCI_FILENAME}'\` and spread \`...mnci\` into the exported array, keeping your own blocks after it \u2014 mnci does not rewrite this file, so it cannot do this for you`
     }
   ];
 }