|
| 1 | +# Check 1 — Package boundaries |
| 2 | + |
| 3 | +Question: are packages split along real seams, and is each package's public API respected? |
| 4 | +Inputs: `workspace.json`, `scan.json`. Output: `findings/boundaries.json`. |
| 5 | + |
| 6 | +## Rules |
| 7 | + |
| 8 | +| id | severity | detect | evidence | |
| 9 | +| ---------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | |
| 10 | +| `boundaries/oversized-package` | low | `scan.packages[p].sourceFiles > 500` or `loc > 50000` | counts | |
| 11 | +| `boundaries/deep-import` | medium | each `scan.imports` entry with `deep && (declared \|\| fromSource === "project.json")` (undeclared package.json importers are reported by ci-coverage instead) | file:line + import specifier + target's `exports` keys | |
| 12 | +| `boundaries/unlisted-dependency` | medium | knip `unlisted` entries | knip output line | |
| 13 | +| `boundaries/unused-dependency` | low | knip `dependencies` / `devDependencies` entries | knip output line | |
| 14 | +| `boundaries/nx-missing-module-boundaries-rule` | medium | Nx detected and no ESLint config in the root mentions `@nx/enforce-module-boundaries` | list of ESLint config files checked | |
| 15 | +| `boundaries/nx-permissive-module-boundaries` | low | the rule exists but `depConstraints` contains `{ sourceTag: '*', onlyDependOnLibsWithTags: ['*'] }` | the config snippet | |
| 16 | +| `boundaries/nx-untagged-project` | low | Nx detected, rule absent or permissive, and a project has empty `tags` | project.json path | |
| 17 | +| `boundaries/turbo-boundaries-violation` | medium | each violation printed by `turbo boundaries` | output line | |
| 18 | + |
| 19 | +Group `deep-import` findings: one finding per (from, target) pair, listing up to 5 locations in `evidence`; `location` is the first occurrence. |
| 20 | + |
| 21 | +## Steps |
| 22 | + |
| 23 | +1. Load `workspace.json` and `scan.json`. Apply the size and deep-import rules directly. |
| 24 | +2. **knip** — only if `hasNodeModules`: |
| 25 | + ```bash |
| 26 | + W="$(node -p 'require("os").tmpdir()')/monorepo-doctor" |
| 27 | + npx --yes [email protected] --reporter json --include dependencies,unlisted --no-progress --no-exit-code |
| 28 | + ``` |
| 29 | + Parse stdout as JSON. Its shape varies by version; look for per-file `dependencies`, `devDependencies` and `unlisted` arrays of `{ name }`. Map the file to its package via `workspace.json`. If knip fails or the output can't be parsed, mark the check `partial` with reason `knip unavailable: <first line of error>`. Do **not** report `unused-dependency` for `@types/*` packages or for tools only referenced in scripts. |
| 30 | +3. **Nx** — only if Nx is an orchestrator: read ESLint configs in the root (`eslint.config.{js,mjs,cjs,ts}`, `.eslintrc{,.json,.js,.cjs}`) and every package dir. Apply the three `nx-*` rules. A config that contains `@nx/enforce-module-boundaries` or legacy `@nrwl/nx/enforce-module-boundaries` anywhere counts as present. Group `nx-untagged-project` consistently as one finding per untagged project found from the root and package-dir project configs. |
| 31 | +4. **Turborepo** — only if turbo is an orchestrator **and installed**: |
| 32 | + ```bash |
| 33 | + W="$(node -p 'require("os").tmpdir()')/monorepo-doctor" |
| 34 | + TURBO_TELEMETRY_DISABLED=1 npx turbo boundaries |
| 35 | + ``` |
| 36 | + One finding per reported violation. If the command errors with an unknown-command message (turbo < 2.4), skip this sub-step and note it in `reason`. |
| 37 | +5. Write `findings/boundaries.json`. |
| 38 | + |
| 39 | +## Fix guidance |
| 40 | + |
| 41 | +- deep-import: add the subpath to the target's `exports`, or re-export from its entry point, then import from the package root. |
| 42 | +- oversized-package: identify clusters by directory and by which consumers import which files (`scan.imports` subpaths); propose 2–3 candidate splits. |
| 43 | +- nx-missing-module-boundaries-rule: add `@nx/enforce-module-boundaries` with `depConstraints` based on `scope:*`/`type:*` tags. |
0 commit comments