From 7ac7f8ae20c59a21a2ec8f74b095630e9e9f7b61 Mon Sep 17 00:00:00 2001 From: 4gray Date: Sun, 2 Aug 2026 10:51:39 +0200 Subject: [PATCH] docs(nx): document coordinated dependency updates --- AGENTS.md | 6 +++++ CLAUDE.md | 6 +++++ docs/architecture/nx-workspace-boundaries.md | 23 ++++++++++++++++++++ 3 files changed, 35 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 0829e2403..32f1cb395 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,6 +16,12 @@ This file provides guidance to coding agents working in this repository. - Use scoped path aliases from `tsconfig.base.json` such as `@iptvnator/services`, `@iptvnator/shared/interfaces`, and `@iptvnator/ui/components`. Do not add new imports from legacy bare aliases such as `services`, `shared-interfaces`, `components`, `m3u-state`, or `database`. - Every Nx project should keep `scope:*`, `domain:*`, and `type:*` tags in `project.json` so `@nx/enforce-module-boundaries` remains useful for humans and agents. - See `docs/architecture/nx-workspace-boundaries.md` for the current Nx tag and alias policy. +- Keep `nx` and every official `@nx/*` package on the same exact version; run + `pnpm run deps:nx:validate` after dependency updates. +- Update Nx with `pnpm nx migrate nx@ --skipInstall`, regenerate the + lockfile, run generated migrations when present, and validate before opening + a PR. Major updates are always manual. Replace incomplete Dependabot security + PRs with a coordinated update instead of editing the bot branch. - ESLint enforces `max-lines` on TypeScript files: production code targets under 300 with a hard maximum of 400, while tests (`**/*.spec.ts`, `**/*.e2e.ts`, `apps/*-e2e/**`) are held to 1200 — a long spec signals coverage, not the design debt the production limit catches. Blank lines and comments are not counted, so a docblock never forces a split. Limits live in `tools/eslint/max-lines-config.mjs`, imported by both `eslint.config.mjs` and the generator so the rule and the baseline cannot drift. Files that predate the rule are baselined in `tools/eslint/max-lines-baseline.mjs`; after splitting a file, regenerate it with `node tools/eslint/generate-max-lines-baseline.mjs` (it runs ESLint's own rule rather than counting lines itself). Never add new files to the baseline — the list must only shrink. A new file that genuinely cannot be split (for example a function serialized into another process) instead carries its own file-wide `/* eslint-disable max-lines -- */`; the generator skips those files, so a justified exemption never lands in the baseline. Remove such a directive once ESLint reports it as unused. - Project `lint` targets that shell out to eslint must quote the glob, e.g. `eslint "apps//**/*.ts"`. An unquoted `**` is expanded by the POSIX shell on Linux and macOS (which has no `globstar`, so it matches only a shallow subset of files) while Windows passes the literal pattern to ESLint, which expands it recursively — the two hosts then lint different file sets. The target still reports success either way, so a broken glob hides missing coverage instead of failing. After changing such a target, compare the linted file count against `find -name '*.ts' | wc -l`. - Repository-specific skills live under `.codex/skills/`. diff --git a/CLAUDE.md b/CLAUDE.md index 32868bb61..e43683a47 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -74,6 +74,12 @@ pnpm nx show projects - Do not add new imports from legacy bare aliases such as `services`, `shared-interfaces`, `components`, `m3u-state`, or `database`. - Every Nx project should keep `scope:*`, `domain:*`, and `type:*` tags in `project.json`. - See `docs/architecture/nx-workspace-boundaries.md` for the current Nx tag and alias policy. +- Keep `nx` and every official `@nx/*` package on the same exact version; run + `pnpm run deps:nx:validate` after dependency updates. +- Update Nx with `pnpm nx migrate nx@ --skipInstall`, regenerate the + lockfile, run generated migrations when present, and validate before opening + a PR. Major updates are always manual. Replace incomplete Dependabot security + PRs with a coordinated update instead of editing the bot branch. - Repository-specific skills live under `.codex/skills/`. - Frontmatter descriptions are trigger-only and begin with `Use when`; keep each skill at or below 500 words. diff --git a/docs/architecture/nx-workspace-boundaries.md b/docs/architecture/nx-workspace-boundaries.md index e73a47b54..202ab7cee 100644 --- a/docs/architecture/nx-workspace-boundaries.md +++ b/docs/architecture/nx-workspace-boundaries.md @@ -27,6 +27,29 @@ Do not invent a `test`, `build`, or `e2e` target because a similarly named project has one. Run affected lint/test/build targets that exist and the closest available E2E target for the changed behavior. +## Nx Dependency Updates + +Keep `nx` and every official `@nx/*` package on the same exact version. Run +`pnpm run deps:nx:validate` after any manifest or lockfile update; CI runs the +same policy check and rejects both direct specifier drift and multiple resolved +Nx versions. + +Dependabot groups routine minor and patch Nx updates when possible. A security +update may still contain only the vulnerable package, so replace an incomplete +Dependabot PR with a coordinated maintainer update instead of editing the bot +branch: + +```bash +pnpm nx migrate nx@ --skipInstall +pnpm install --no-frozen-lockfile +pnpm nx migrate --run-migrations +pnpm run deps:nx:validate +``` + +Omit `pnpm nx migrate --run-migrations` when the first command reports that no +migrations exist. Major Nx updates always use this manual workflow and the +resulting PR runs the full CI pipeline. + ## Placement Decision - `apps/` owns runtime applications, development servers, E2E applications,