@rsdk/yarn.constraints 6.0.0-next.39 → 6.0.0-next.40

package/DEPENDENCY_MODEL.md

@@ -0,0 +1,452 @@
+# Dependency Model
+
+Status: draft.
+
+This document defines the dependency ownership model for the monorepo. The goal
+is to make dependency placement deterministic, checkable, and mostly
+autofixable.
+
+## Terms
+
+| Term | Meaning |
+|---|---|
+| Root | The monorepo root workspace. It is an orchestrator, not a product package. |
+| Workspace | Any non-root workspace package. |
+| Role | Explicit package role: `library`, `service`, or `cli`. |
+| Local dependency | A package that is also present as a workspace in this monorepo. |
+| External dependency | Any dependency that is not a local workspace package. |
+| Runtime surface | Imports required by emitted JavaScript / production execution. |
+| Public type surface | Imports that appear in emitted `dist/**/*.d.ts`. |
+| Private dev surface | Test, build, lint, type-only, and tooling usage that does not reach runtime or public `.d.ts`. |
+| Mirror | A `library` package has the same dependency name and range in both `peerDependencies` and `devDependencies`. |
+
+## Invariants
+
+### Root
+
+| ID | Invariant | Check |
+|---|---|---|
+| R1 | Root is not a product package. | Root `package.json` has `private: true`. |
+| R2 | Root may contain only `devDependencies`. | Root `dependencies` and `peerDependencies` are forbidden. |
+| R3 | Root `devDependencies` define the shared dev/type/build environment. | Tooling, `@types/*`, test infra, build infra, release infra, and constraints infra live here. |
+| R4 | Root dependencies do not declare dependencies for workspaces. | A workspace runtime/public dependency must be declared in that workspace manifest. |
+
+### Workspace Roles
+
+| ID | Invariant | Check |
+|---|---|---|
+| W1 | Every workspace has an explicit role. | `role` is one of `library`, `service`, `cli`. |
+| W2 | Local workspace dependencies are runtime graph edges. | Local deps are in `dependencies` with `workspace:*`. |
+| W3 | Dependency ownership belongs to the importing workspace. | Runtime/public imports must be represented in that workspace manifest. |
+
+### Libraries
+
+| ID | Invariant | Check |
+|---|---|---|
+| L1 | External deps required by runtime or public type surface default to `peerDependencies`. | Unless an explicit override says otherwise. |
+| L2 | `devDependencies` exactly mirror `peerDependencies`. | Same names and same ranges. |
+| L3 | Extra `devDependencies` are forbidden. | `devDependencies - peerDependencies = empty`. |
+| L4 | A dependency cannot be both `dependencies` and `peerDependencies`. | A package has one runtime/public ownership mode. |
+| L5 | External implementation deps are explicit exceptions. | They require a `section: dependencies` override. |
+| L6 | Private dev/type/test/build-only deps are not declared in the library package. | They belong to root `devDependencies`. |
+
+### Services and CLI Packages
+
+| ID | Invariant | Check |
+|---|---|---|
+| S1 | Runtime/prod deps are declared in `dependencies`. | Includes local and external runtime deps. |
+| S2 | `peerDependencies` are forbidden. | Services and CLIs do not push a peer contract to consumers. |
+| S3 | `devDependencies` are forbidden. | Dev/type/test/build deps live in root. |
+| S4 | CLI runtime deps cannot be peers. | Global install / `dlx` flows do not reliably install peer dependencies. |
+
+### Types
+
+| ID | Invariant | Check |
+|---|---|---|
+| T1 | Type-only deps that do not appear in `dist/**/*.d.ts` are private dev deps. | They belong to root `devDependencies`. |
+| T2 | Type deps that appear in `dist/**/*.d.ts` are public contract deps. | `library`: peer + dev mirror. `service`/`cli`: dependency. |
+| T3 | `@types/*` default to root `devDependencies`. | Until they appear in public `.d.ts`. |
+| T4 | If public `.d.ts` requires a DefinitelyTyped provider, that provider is public contract. | The corresponding `@types/*` is promoted according to T2. |
+
+### Peer Propagation
+
+| ID | Invariant | Check |
+|---|---|---|
+| P1 | A workspace depending on a local library must provide that library's peers. | `library` consumer: peer + dev mirror. `service`/`cli`: dependencies. |
+| P2 | Required peers of external npm deps must be provided by the current workspace. | Optional peers are not forced. |
+| P3 | Incorrect third-party peer metadata is fixed through package manager metadata overrides. | Use `packageExtensions`, not random workspace deps. |
+| P4 | Local workspace packages are not propagated as peer targets. | Local packages stay `dependencies: workspace:*`. |
+
+### Versions and Overrides
+
+| ID | Invariant | Check |
+|---|---|---|
+| V1 | Any external dependency that appears more than once must have a version rule. | Count root and all workspaces, all dependency sections. |
+| V2 | Wildcard rules count as version rules. | For example `@nestjs/*`. |
+| V3 | The constraints config does not describe the whole model. | It contains versions, overrides, root-only rules, manual required dependencies, and workspace-specific exceptions. |
+| V4 | The last matching rule wins. | Enables broad rules plus specific overrides. |
+| V5 | `rootOnly` means the dependency belongs only to the root dev environment. | Workspace usage is forbidden unless a more specific override exists. |
+
+## Placement Formula
+
+```text
+root:
+  only devDependencies
+
+library:
+  dependencies     = local workspace deps + explicit implementation overrides
+  peerDependencies = external runtime/public deps by default
+  devDependencies  = exact mirror of peerDependencies
+
+service/cli:
+  dependencies     = runtime/prod deps
+  peerDependencies = forbidden
+  devDependencies  = forbidden
+```
+
+## Check Algorithm
+
+The checks should run from facts to derived manifests. A later phase should not
+guess something that an earlier phase can derive.
+
+### Phase 1. Load Facts
+
+1. Read root `package.json`.
+2. Read every workspace `package.json`.
+3. Build the set of local workspace package names.
+4. Read dependency rules: version rules, section overrides, `rootOnly` rules,
+   manual `required` dependencies, and workspace-specific exceptions.
+5. Read package manager metadata overrides, such as `packageExtensions`.
+
+### Phase 2. Validate Basic Shape
+
+1. Root has `private: true`.
+2. Root has no `dependencies`.
+3. Root has no `peerDependencies`.
+4. Every non-root workspace has a valid `role`.
+5. `service` and `cli` workspaces have no `peerDependencies`.
+6. `service` and `cli` workspaces have no `devDependencies`.
+7. `library` workspaces have no dependency listed in both `dependencies` and
+   `peerDependencies`.
+8. No workspace has the same dependency in both `dependencies` and
+   `devDependencies`.
+
+### Phase 3. Collect Usage
+
+1. Scan source imports for every workspace.
+2. Classify each import as local or external.
+3. Classify each import as runtime, type-only, test-only, or tooling-only.
+4. Scan emitted `dist/**/*.d.ts` imports when `dist/` exists.
+5. In `--with-dts` mode, require `dist/` for workspaces with `src/`; without
+   `--with-dts`, missing `dist/` is allowed so local source-only checks remain
+   usable before build.
+6. Mark all dependencies found in emitted `.d.ts` as public type surface.
+7. Collect `bin`, `exports`, `main`, and package entry metadata to identify
+   runtime/public entrypoints where needed.
+
+### Phase 4. Derive Required Public/Runtime Deps
+
+For each workspace:
+
+1. Local runtime/public deps become `dependencies: workspace:*`.
+2. For `library`, external runtime/public deps become `peerDependencies` by
+   default.
+3. For `library`, external deps with `section: dependencies` override become
+   `dependencies`.
+4. For `service` and `cli`, external runtime deps become `dependencies`.
+5. Type-only deps that appear in `dist/**/*.d.ts` are treated as public deps.
+6. Type-only/test/tooling deps that do not appear in `dist/**/*.d.ts` are moved
+   to root `devDependencies`.
+7. Dependencies matched by a concrete `required: true` rule are treated as
+   required public/runtime dependencies even when source scanning cannot see a
+   direct import.
+
+### Phase 5. Propagate Peers
+
+For each workspace dependency edge:
+
+1. If a workspace depends on a local library, read that library's
+   `peerDependencies`.
+2. If a workspace depends on an external npm package, read that package's
+   required `peerDependencies`.
+3. Ignore optional peers.
+4. Ignore local workspace packages as peer targets.
+5. For a `library` consumer, required external peers become `peerDependencies`.
+6. For a `service` or `cli` consumer, required external peers become
+   `dependencies`.
+7. Third-party metadata mistakes are handled by metadata overrides before this
+   phase, so this phase sees corrected peer metadata.
+
+### Phase 6. Derive Mirrors
+
+For each `library`:
+
+1. `devDependencies` must be exactly equal to `peerDependencies`.
+2. Every peer range is copied exactly into the dev mirror.
+3. Any extra dev dependency is removed or moved to root dev dependencies,
+   depending on whether it is still needed by private dev usage.
+
+### Phase 7. Resolve Versions
+
+1. Count every external dependency occurrence across root and all workspaces,
+   all sections.
+2. If an external dependency appears more than once, require a matching version
+   rule.
+3. A wildcard rule is valid if it provides a version.
+4. Apply the last matching rule.
+5. Mirror ranges must stay identical.
+6. Local workspace deps use `workspace:*`.
+
+### Phase 8. Compare Expected vs Actual Manifests
+
+For each manifest:
+
+1. Report missing dependencies.
+2. Report dependencies in the wrong section.
+3. Report dependencies with the wrong version range.
+4. Report forbidden dependencies.
+5. Report stale dependencies that are not required by the derived graph.
+6. Report missing or incorrect library peer/dev mirrors.
+7. Report root-only violations.
+
+### Phase 9. Autofix
+
+Autofix should write manifests from the derived expected graph:
+
+1. Remove forbidden root `dependencies` and `peerDependencies`.
+2. Add/move local workspace deps to `dependencies: workspace:*`.
+3. Add/move library external public/runtime deps to `peerDependencies`.
+4. Rebuild library `devDependencies` from `peerDependencies`.
+5. Add/move service and CLI runtime deps to `dependencies`.
+6. Move private dev/type/test/tooling deps to root `devDependencies`.
+7. Apply version rules.
+8. Sort dependency sections consistently.
+
+### Phase 10. Verification Order
+
+1. Run the manifest model checker with autofix.
+2. Run package install.
+3. Build packages to generate `dist/**/*.d.ts`.
+4. Run the type-surface check.
+5. Run the manifest model checker again, because `.d.ts` leaks can change the
+   expected graph.
+6. Run package install again if manifests changed.
+7. Assert that package manager peer requirements have no failures.
+8. Run the full dependency check task.
+
+## Target Tooling Shape
+
+The implementation should have one CLI backed by one dependency model engine.
+Separate scripts must not own separate placement logic.
+
+```text
+depdoc check
+depdoc fix
+depdoc explain <workspace> <dependency>
+depdoc doctor
+```
+
+The CLI commands share the same pipeline:
+
+```text
+collect facts
+  -> derive expected dependency graph
+  -> compare actual manifests with expected manifests
+  -> print diagnostics or write fixes
+```
+
+`check` and `fix` differ only in the final step. `check` reports diagnostics.
+`fix` writes the expected manifests. Both commands include `.d.ts` facts when
+`dist/` already exists, so a normal `fix` must not delete public type-surface
+dependencies from a built checkout. The `--with-dts` flag only changes
+strictness around missing build artifacts: it requires `dist/` for packages with
+`src/`.
+
+`explain` explains why a dependency belongs to a specific section, which rule
+matched it, which import or peer edge required it, and whether the dependency is
+part of runtime surface, public type surface, or private dev surface.
+
+`doctor` runs the full compatibility pipeline:
+
+```text
+depdoc fix
+yarn install
+build packages
+depdoc check --with-dts
+yarn install
+yarn explain peer-requirements
+lint
+typecheck
+```
+
+The exact build/lint/typecheck commands are repository-specific, but the order
+is part of the model: `.d.ts` facts are available when `dist/` exists, and
+`--with-dts` makes missing `.d.ts` artifacts a hard failure after build.
+
+## Implementation Layers
+
+### Engine
+
+The engine should be pure and deterministic.
+
+```ts
+deriveDependencyModel({
+  rootPackage,
+  workspaces,
+  sourceImports,
+  dtsImports,
+  externalPeerMetadata,
+  rules,
+});
+```
+
+The engine returns:
+
+```ts
+{
+  expectedManifests,
+  diagnostics,
+  fixes
+}
+```
+
+The engine must not run Yarn, read the filesystem, or execute TypeScript. It
+only consumes facts and derives the expected dependency graph.
+
+### Collectors
+
+Collectors gather facts for the engine:
+
+| Collector | Responsibility |
+|---|---|
+| Package JSON collector | Reads root and workspace manifests. |
+| Workspace collector | Reads workspace names and locations. |
+| Source import collector | Reads source imports and classifies runtime/type/test/tooling usage. |
+| DTS import collector | Reads emitted `dist/**/*.d.ts` imports. |
+| External peer metadata collector | Reads required/optional peers from installed packages and metadata overrides. |
+| Rules collector | Reads version rules, section overrides, root-only rules, and workspace exceptions. |
+
+Collectors may be integration-tested separately. The core placement model should
+remain testable without filesystem or Yarn.
+
+### Manifest Writer
+
+The writer applies engine fixes:
+
+1. Preserve unrelated manifest fields.
+2. Rewrite dependency sections from the expected graph.
+3. Keep peer/dev mirrors exact for libraries.
+4. Apply normalized sorting.
+5. Avoid touching files when generated content is identical.
+
+## Test Strategy
+
+Testing must prove two different things:
+
+1. The dependency model is internally consistent.
+2. Real tools accept manifests produced by the model.
+
+### Test Layers
+
+| Layer | Goal | Uses Yarn/build |
+|---|---|---|
+| Model unit tests | Test individual invariants and section decisions. | No |
+| Model fixture tests | Test complete expected manifests from package/import facts. | No |
+| Collector tests | Test import parsing, workspace discovery, package metadata parsing. | Minimal |
+| Type-surface tests | Test behavior when `dist/**/*.d.ts` contains public type imports. | No build required if `.d.ts` fixtures are provided |
+| Tool compatibility tests | Test generated manifests against real Yarn, TypeScript, and ESLint. | Yes |
+| Repo smoke tests | Test the model on the current monorepo. | Yes |
+
+### Model Fixture Format
+
+Each fixture should provide package manifests, model facts, rules, and expected
+output.
+
+```text
+fixtures/library-external-default-peer/
+  input/
+    package.json
+    packages/foo/package.json
+  facts.json
+  rules.yml
+  expected/
+    package.json
+    packages/foo/package.json
+    diagnostics.json
+```
+
+Example `facts.json`:
+
+```json
+{
+  "sourceImports": {
+    "packages/foo": [
+      {
+        "packageName": "lodash",
+        "kind": "runtime",
+        "file": "src/index.ts"
+      }
+    ]
+  },
+  "dtsImports": {
+    "packages/foo": []
+  },
+  "externalPeerMetadata": {}
+}
+```
+
+### Required Model Fixtures
+
+| Fixture | Proves |
+|---|---|
+| `root-only-devdeps` | Root rejects `dependencies` and `peerDependencies`. |
+| `library-external-default-peer` | External runtime dep in a library becomes peer + dev mirror. |
+| `library-implementation-override` | `section: dependencies` keeps an external library dep in `dependencies`. |
+| `library-dev-mirror-exact` | Library `devDependencies` exactly mirror `peerDependencies`. |
+| `library-private-type-root-dev` | Private type-only usage belongs to root `devDependencies`. |
+| `library-dts-type-leak` | A dependency imported by public `.d.ts` becomes public contract. |
+| `service-runtime-deps` | Service external runtime deps become `dependencies`; peers/dev are forbidden. |
+| `cli-runtime-deps` | CLI runtime deps become `dependencies`; peers are forbidden. |
+| `local-workspace-deps` | Local workspace deps are `dependencies: workspace:*`. |
+| `peer-propagation-local-library` | A consumer provides peers required by a local library. |
+| `peer-propagation-external-package` | A consumer provides required peers of an external npm dependency. |
+| `optional-peers-ignored` | Optional peers are not added. |
+| `repeated-dep-needs-version-rule` | External deps used more than once require a version rule. |
+| `rule-precedence-last-wins` | The last matching rule wins. |
+| `rootonly-violation` | `rootOnly` deps are rejected in workspaces. |
+
+### Compatibility Tests
+
+Compatibility tests run on small temporary monorepos. They should be few and
+focused, because they invoke real tools.
+
+| Test | Proves |
+|---|---|
+| `yarn-install-clean` | After autofix, `yarn install` has no dependency placement warnings. |
+| `yarn-peer-requirements-clean` | `yarn explain peer-requirements` has no failed peer requirements. |
+| `tsc-library-build` | A library with peer + dev mirror compiles. |
+| `tsc-dts-leak` | A public `.d.ts` leak is detected when `dist/` exists and changes expected manifests. |
+| `eslint-extraneous-compatible` | ESLint import/dependency rules do not contradict the model. |
+| `production-focus` | Production install/focus uses only production graph and does not require root dev deps or package dev mirrors. |
+| `cli-install-shape` | CLI runtime deps are in `dependencies`, so install/dlx-style usage has the required deps. |
+| `service-prod-shape` | Service production graph is complete from `dependencies`. |
+
+The production test may use `yarn workspaces focus --production` if that is the
+chosen production mechanism. Otherwise it should assert the same invariant
+directly: production runtime must not depend on root `devDependencies` or
+workspace `devDependencies`.
+
+### Repo Smoke Tests
+
+Repo smoke tests verify that the model works on the real repository:
+
+1. Run `depdoc fix`.
+2. Run `yarn install`.
+3. Build packages.
+4. Run `depdoc check --with-dts`.
+5. Run `yarn install` again if manifests changed.
+6. Assert no failed peer requirements.
+7. Run repo lint/typecheck/dependency task.
+
+This is the final confidence layer. Most edge cases should still be covered by
+fast model fixtures, not by expanding the smoke suite.

package/README.MD

@@ -12,6 +12,30 @@ some-package: 1.0.0
 
 ## Usage
 
+Dependency model CLI:
+
+```sh
+depdoc check
+depdoc fix
+depdoc explain <workspace> <dependency>
+depdoc doctor
+```
+
+`depdoc` is the unified dependency-model entrypoint. It derives the
+expected manifests from workspace roles, dependency rules, source imports,
+emitted `.d.ts` imports, peer propagation, and library peer/dev mirrors.
+
+Dependency rules can mark indirect runtime requirements explicitly:
+
+```yaml
+rules:
+  - match: '@fastify/static'
+    workspace: '@rsdk/http.server.fastify'
+    section: dependencies
+    version: '^6.12.0'
+    required: true
+```
+
 Default
 
 ```js