@mnci/cli 1.16.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,8 +179,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`, `.prettierrc.json`, `commitlint.config.mjs`,
-`.husky/commit-msg`, the CI pipeline file(s), the
+`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
 from `mnci add` — is ever touched, and it finishes by running Prettier over the
@@ -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,21 +1350,55 @@ 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() {
   return process.env.MNCI_ESLINT_CONFIG_SPEC ?? ESLINT_CONFIG_VERSION;
 }
 var ESLINT_VERSION = "^10.8.0";
+function devcontainerJson(workspaceName) {
+  return `${toJson({
+    name: workspaceName,
+    image: `mcr.microsoft.com/devcontainers/typescript-node:${NODE_VERSION}-bookworm`,
+    features: {
+      "ghcr.io/devcontainers/features/python:1": { version: "3.12" },
+      "ghcr.io/devcontainers/features/go:1": { version: "latest" }
+    },
+    // `npm ci` first: every guard after it runs through the workspace's own
+    // scripts and Nx, which do not exist until the install completes.
+    postCreateCommand: [
+      "npm ci",
+      "npm run python:install",
+      GOLANGCI_LINT_INSTALL_GUARD,
+      FLUTTER_SDK_INSTALL_GUARD
+    ].join(" && "),
+    // The same recommendations the `.code-workspace` file carries, so opening
+    // the folder in a container suggests the identical toolset.
+    customizations: {
+      vscode: { extensions: [...VSCODE_RECOMMENDED_EXTENSIONS] }
+    }
+  })}
+`;
+}
 var ROOT_LINT_TARGET = {
   executor: "nx:run-commands",
   cache: true,
@@ -1391,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
@@ -1414,6 +1501,12 @@ __pycache__
 .ruff_cache
 .dart_tool
 `;
+var VSCODE_RECOMMENDED_EXTENSIONS = [
+  "dbaeumer.vscode-eslint",
+  "esbenp.prettier-vscode",
+  "nrwl.angular-console",
+  "firsttris.vscode-jest-runner"
+];
 function vscodeWorkspace(workspaceName, existingTasks) {
   return JSON.stringify(
     {
@@ -1444,14 +1537,7 @@ function vscodeWorkspace(workspaceName, existingTasks) {
           "editor.defaultFormatter": "esbenp.prettier-vscode"
         }
       },
-      extensions: {
-        recommendations: [
-          "dbaeumer.vscode-eslint",
-          "esbenp.prettier-vscode",
-          "nrwl.angular-console",
-          "firsttris.vscode-jest-runner"
-        ]
-      },
+      extensions: { recommendations: [...VSCODE_RECOMMENDED_EXTENSIONS] },
       tasks: {
         version: existingTasks?.version ?? "2.0.0",
         tasks: existingTasks?.tasks ?? []
@@ -1531,6 +1617,7 @@ var GO_TOOL_PATH_PRELUDE = `const fs=require('node:fs'),cp=require('node:child_p
 var GO_TOOL_PATH_AZURE = `node -e "${GO_TOOL_PATH_PRELUDE}console.log('##vso[task.prependpath]'+bin)"`;
 var GO_TOOL_PATH_GITHUB = `node -e "${GO_TOOL_PATH_PRELUDE}if(!process.env.GITHUB_PATH){console.log('Not running in GitHub Actions - skipping.');process.exit(0)}fs.appendFileSync(process.env.GITHUB_PATH,bin+${String.raw`'\n'`})"`;
 var FLUTTER_SDK_VERSION = "3.44.8";
+var NODE_VERSION = "24";
 var FLUTTER_SDK_DIRECTORY_EXPRESSION = `require('node:path').join(require('node:os').homedir(),'.mnci-flutter-${FLUTTER_SDK_VERSION}')`;
 var FLUTTER_SDK_INSTALL_GUARD = `node -e "const fs=require('node:fs'),cp=require('node:child_process');if(!fs.existsSync('pubspec.yaml')){console.log('No Flutter projects - skipping.');process.exit(0)}if(cp.spawnSync('flutter',['--version'],{stdio:'ignore',shell:process.platform==='win32'}).status===0){console.log('Flutter SDK already on PATH - skipping.');process.exit(0)}const sdk=${FLUTTER_SDK_DIRECTORY_EXPRESSION};if(fs.existsSync(sdk)){console.log('Flutter SDK already installed at '+sdk+' - skipping.');process.exit(0)}process.exit(cp.spawnSync('git',['clone','--depth','1','--branch','${FLUTTER_SDK_VERSION}','https://github.com/flutter/flutter.git',sdk],{stdio:'inherit'}).status ?? 1)"`;
 var FLUTTER_TOOL_PATH_PRELUDE = `const fs=require('node:fs'),path=require('node:path');if(!fs.existsSync('pubspec.yaml')){console.log('No Flutter projects - skipping.');process.exit(0)}const sdk=${FLUTTER_SDK_DIRECTORY_EXPRESSION};if(!fs.existsSync(sdk)){console.log('Flutter SDK was not installed by mnci (already on PATH) - skipping.');process.exit(0)}const bin=path.join(sdk,'bin');`;
@@ -1828,7 +1915,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 24
+          node-version: ${NODE_VERSION}
           # Caches ~/.npm keyed on package-lock.json, so \`npm ci\` restores from
           # the local cache instead of re-downloading every tarball on every run.
           # Nothing to invalidate by hand: the action keys on the lockfile, so a
@@ -2012,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 });
@@ -2082,7 +2169,11 @@ 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)
+  );
   writeFileEnsured((0, import_node_path11.join)(workspaceRoot, ".prettierignore"), PRETTIER_IGNORE);
   removeNxScaffolding(workspaceRoot);
   const codeWorkspacePath = (0, import_node_path11.join)(workspaceRoot, `${options.workspaceName}.code-workspace`);