@mnci/cli 4.6.0 → 4.6.2

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

@@ -419,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"
 ];
@@ -599,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
@@ -630,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",
@@ -1620,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));
@@ -4485,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`
     }
   ];
 }