@mnci/cli 1.17.0 → 1.17.1

package/README.md

@@ -78,7 +78,7 @@ ever needed is noise that trains people to ignore the output.
 | Check                                                   | The failure it catches                                                                                                             |
 | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
 | Exactly one root ESLint config, and no per-project ones | The config fragmenting — every `@nx/*` generator writes one, so each project ends up linting against whichever config sits nearest |
-| No stray `.prettierrc`                                  | It outranks `.prettierrc.json`, so the whole formatting opinion is silently discarded while both files look fine                   |
+| No stray `.prettierrc`                                  | It outranks `.prettierrc.mjs`, so the whole formatting opinion is silently discarded while both files look fine                    |
 | `@nx/eslint/plugin` registered in `nx.json`             | Without it `npm run lint` exits 0 while linting nothing                                                                            |
 | The **resolved** `eslint` major                         | A declared range and an installed version are different things — manifests once said `^10` while the pin said 9                    |
 | `.npmrc` matches the recorded registry                  | The two registry kinds get different files; an Azure workspace also needs its scope routed                                         |
@@ -152,9 +152,11 @@ that would just fail felt worse than being upfront that it doesn't exist yet.
    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` (three lines importing `@mnci/eslint-config` —
-   the whole linting opinion, in one root config), `.prettierrc.json` +
-   `.prettierignore`, `.npmrc` (publish auth — see **Publish auth** below),
+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), `.prettierrc.mjs` (which re-exports
+   `@mnci/eslint-config/prettier`, so lint and format ship as one package and
+   upgrade together) + `.prettierignore`, `.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
@@ -177,7 +179,7 @@ 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`, `.prettierrc.json`, `commitlint.config.mjs`,
+`eslint.config.mjs`, `.prettierrc.mjs`, `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
@@ -194,9 +196,10 @@ project's build/qa/start entry on upgrade.
 has always done — one more reason to run `git diff` first, as the command's own
 output tells you to:
 
-- `create-nx-workspace`'s `.prettierrc` and `.vscode/`, both superseded (by
-  `.prettierrc.json`, which Prettier would otherwise never reach, and by the
-  `.code-workspace` file).
+- `create-nx-workspace`'s `.prettierrc` and `.vscode/`, plus mnci's own former
+  `.prettierrc.json`. The two Prettier files are deleted for the same reason:
+  both outrank `.prettierrc.mjs`, which Prettier would otherwise never reach.
+  `.vscode/` is superseded by the `.code-workspace` file.
 - **every per-project `eslint.config.*` under `apps/`, `libs/` and
   `packages/`.** This is the migration path for a workspace generated before
   mnci owned linting: without it an upgrade would install the root config while
@@ -251,11 +254,26 @@ switch linting off workspace-wide.)
 
 ESLint handles code quality only; **Prettier owns all formatting**, configured
 for JavaScript Standard Style (no semicolons, single quotes, 2-space indents, no
-trailing commas). `mnci` runs Prettier itself at the end of `new` and every
+trailing commas). Both opinions come from the same package: `.prettierrc.mjs`
+re-exports `@mnci/eslint-config/prettier`, so a formatting fix arrives through
+`npm update` exactly as a rule fix does, and the two cannot drift into
+contradicting each other. `mnci` runs Prettier itself at the end of `new` and every
 `add`, so a generated workspace passes its own `format:check` immediately — Nx's
 generators emit semicolons and double quotes, and without that pass the first
 commit buries every real change under generator noise.
 
+**Finding and overriding a rule.** One root config importing a package is easy to
+own and hard to read: nothing in three lines says which of ~20 plugins reported
+the thing you disagree with. Every block in `@mnci/eslint-config` therefore
+carries a `name` — `mnci/base`, `mnci/react`, `mnci/type-aware`,
+`mnci/prettier-compat` — and the generated `eslint.config.mjs` ships the full list
+as a comment, next to the recipe for overriding one. `npx eslint --inspect-config`
+lists them as ESLint actually resolves them, `npx eslint --print-config <file>`
+shows the merged result for a single file, and an override is a named block
+appended after the spread, since later blocks win. Don't edit the package inside
+`node_modules`: it is a dependency, and `npm update` will replace it.
+`packages/eslint-config/README.md` has the block-by-block table.
+
 One caveat worth knowing: `space-before-function-paren`, Standard's signature
 rule, is **not** enforced. Prettier rewrites `function f (a)` to `function f(a)`
 on every run and has closed the corresponding option permanently, so enabling it

package/dist/cli.js

@@ -1350,15 +1350,25 @@ var COMMITLINT_CONFIG = `export default { extends: ['@commitlint/config-conventi
 `;
 var COMMIT_MSG_HOOK = `npx --no -- commitlint --edit "$1"
 `;
-var PRETTIER_CONFIG = `{
-  "semi": false,
-  "singleQuote": true,
-  "trailingComma": "none",
-  "arrowParens": "avoid",
-  "printWidth": 100,
-  "tabWidth": 2,
-  "useTabs": false
-}
+var PRETTIER_CONFIG = `// The formatting half of @mnci/eslint-config.
+//
+// Prettier's options live in the same package as the ESLint rules on purpose:
+// linting and formatting are one decision. \`eslint-config-prettier\` is composed
+// last inside that package so every formatting rule defers to these settings, and
+// splitting the two across packages means a version pair that can drift until
+// \`npm run lint\` and \`npm run format:check\` disagree with each other.
+//
+// Consuming it as a shareable config also means a formatting fix reaches this
+// workspace through \`npm update\`, the same way a rule change does, instead of
+// waiting for \`mnci upgrade\` to rewrite a file.
+//
+// TO OVERRIDE an option, spread it rather than re-exporting:
+//
+//   import mnci from '@mnci/eslint-config/prettier'
+//   export default { ...mnci, printWidth: 120 }
+//
+// TO SEE the resolved options for a file:  npx prettier --find-config-path <file>
+export { default } from '@mnci/eslint-config/prettier'
 `;
 var ESLINT_CONFIG_VERSION = "^0.1.0";
 function eslintConfigSpec() {
@@ -1415,8 +1425,61 @@ function eslintToolchainDependencies(nxVersion) {
     "@mnci/eslint-config": eslintConfigSpec()
   };
 }
+var ESLINT_BLOCK_INVENTORY = `// WHAT IS IN HERE. Each line is one config block, by the \`name\` it carries.
+//
+//   mnci/ignores                  paths never linted (dist, coverage, .venv, \u2026)
+//   mnci/base                     JS/TS correctness \u2014 @eslint/js, eslint-plugin-unicorn,
+//                                 -promise, -n, -unused-imports
+//   typescript-eslint/*           typescript-eslint's own recommended blocks
+//   mnci/typescript*              TS rules on top of them, no type information needed
+//   mnci/type-aware*              the rules that DO read types (no-floating-promises and
+//                                 friends), scoped to {apps,libs,packages}/*/src
+//   mnci/import-graph             import cycles \u2014 eslint-plugin-import-x
+//   mnci/react                    JSX/TSX \u2014 @eslint-react/eslint-plugin,
+//                                 eslint-plugin-react-hooks, -react-refresh, -jsx-a11y
+//   mnci/regexp*                  regex correctness \u2014 eslint-plugin-regexp
+//   mnci/json  mnci/jsonc  mnci/json5
+//                                 eslint-plugin-jsonc \u2014 comments are allowed in .jsonc
+//                                 and tsconfig.json, forbidden in plain .json
+//   mnci/yaml*                    eslint-plugin-yml \u2014 your CI pipeline files
+//   mnci/toml/base*               eslint-plugin-toml, PARSER ONLY: a malformed
+//                                 pyproject.toml is a syntax error, nothing is styled
+//   mnci/markdown                 @eslint/markdown
+//   mnci/css                      @eslint/css
+//   mnci/html                     @html-eslint/eslint-plugin
+//   mnci/tests                    *.spec/*.test relaxations \u2014 eslint-plugin-jest
+//                                 (Vitest's globals too; the two stacks share them)
+//   mnci/nx-dependency-checks     @nx/eslint-plugin, on publishable packages' manifests
+//   mnci/prettier-compat          eslint-config-prettier \u2014 switches off every rule
+//                                 Prettier owns. Composed LAST, on purpose.
+//   mnci/stylistic                the 3 Standard rules Prettier does not touch
+//
+// To list them as ESLint actually resolves them:  npx eslint --inspect-config
+`;
 var ESLINT_CONFIG = `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.
+//
+// One override cannot work, and it is the one people reach for first:
+// \`space-before-function-paren\`. Prettier rewrites \`f (a)\` to \`f(a)\` on every
+// run, so switching that rule on makes \`npm run lint\` and \`npm run format:check\`
+// impossible to satisfy at the same time. Formatting lives in .prettierrc.mjs.
 export default mnci({ workspaceRoot: import.meta.dirname })
 `;
 var PRETTIER_IGNORE = `node_modules
@@ -2036,7 +2099,7 @@ updates:
     schedule:
       interval: weekly
 `;
-var NX_SCAFFOLDING_TO_REMOVE = [".prettierrc", ".vscode"];
+var NX_SCAFFOLDING_TO_REMOVE = [".prettierrc", ".prettierrc.json", ".vscode"];
 function removeNxScaffolding(workspaceRoot) {
   for (const entry of NX_SCAFFOLDING_TO_REMOVE) {
     (0, import_node_fs6.rmSync)((0, import_node_path11.join)(workspaceRoot, entry), { recursive: true, force: true });
@@ -2106,7 +2169,7 @@ function applyOverlay(workspaceRoot, options) {
   writeFileEnsured(hookPath, COMMIT_MSG_HOOK);
   markExecutable(hookPath);
   writeFileEnsured((0, import_node_path11.join)(workspaceRoot, "eslint.config.mjs"), ESLINT_CONFIG);
-  writeFileEnsured((0, import_node_path11.join)(workspaceRoot, ".prettierrc.json"), PRETTIER_CONFIG);
+  writeFileEnsured((0, import_node_path11.join)(workspaceRoot, ".prettierrc.mjs"), PRETTIER_CONFIG);
   writeFileEnsured(
     (0, import_node_path11.join)(workspaceRoot, ".devcontainer/devcontainer.json"),
     devcontainerJson(options.workspaceName)