@rsdk/depdoc.cli 6.0.0-next.42 → 6.0.0-next.44

package/DEPDOC_MODEL.md

@@ -19,6 +19,7 @@ autofixable.
 | 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`. |
+| Ignored import | A module specifier that appears in source but is provided virtually or resolved as an internal alias, so it is not a package dependency. |
 
 ## Invariants
 
@@ -86,6 +87,7 @@ autofixable.
 | 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 declarations and source usage are forbidden unless a more specific override exists. `required` + `rootOnly` means required for the selected workspace but physically owned by root `devDependencies`. |
+| V6 | Concrete dependency rules must describe packages that exist in the repo model. | Wildcard policy rules are allowed, but concrete stale `depdoc.yml` entries are reported. |
 
 ## Placement Formula
 
@@ -114,8 +116,9 @@ guess something that an earlier phase can derive.
 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.
+4. Read ignored import patterns and 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
@@ -136,16 +139,21 @@ guess something that an earlier phase can derive.
 1. Scan source imports for every workspace from `src/`, `test/`, `tests/`,
    `__tests__/`, concrete package entry-points, and relative imports reachable
    from those entry-points.
-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
+2. Ignore module specifiers from `ignoredImports` and every `compilerOptions.paths`
+   alias collected from root-level `tsconfig*.json` files in the workspace.
+   For example, `@docusaurus/router` can be ignored as a virtual Docusaurus
+   runtime module, and `~app/*` / `~shared/*` are ignored when declared as
+   TypeScript path aliases.
+3. Classify each import as local or external.
+4. Classify each import as runtime, type-only, test-only, or tooling-only.
+5. Scan emitted `dist/**/*.d.ts` imports when `dist/` exists.
+6. 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. Skip generated entry-point roots such as `dist/`, `build/`, `coverage/`, and
+7. Mark all dependencies found in emitted `.d.ts` as public type surface.
+8. Skip generated entry-point roots such as `dist/`, `build/`, `coverage/`, and
    `node_modules/`.
-8. Warn when a workspace has scanned source files and declared dependencies,
+9. Warn when a workspace has scanned source files and declared dependencies,
    but zero collected source or `.d.ts` package usage.
 
 ### Phase 4. Derive Required Public/Runtime Deps
@@ -214,8 +222,11 @@ For each manifest:
 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.
+6. Report stale concrete dependency rules from `depdoc.yml` when no matching
+   source usage, `.d.ts` usage, manifest declaration, or expected dependency
+   exists in the matching workspace scope.
+7. Report missing or incorrect library peer/dev mirrors.
+8. Report root-only violations.
 
 ### Phase 9. Autofix
 

package/__tests__/compatibility.test.ts

@@ -4,8 +4,8 @@ import { tmpdir } from 'node:os';
 import { resolve } from 'node:path';
 
 // Paths relative to this test file:
-//   __tests__/ -> depdoc/ -> packages/ -> monorepo root
-const MONOREPO_ROOT = resolve(__dirname, '../../..');
+//   __tests__/ -> depdoc/ -> dx/ -> packages/ -> monorepo root
+const MONOREPO_ROOT = resolve(__dirname, '../../../..');
 const YARN_BIN = resolve(MONOREPO_ROOT, '.yarn/releases/yarn-4.5.3.cjs');
 const YARN_CACHE = resolve(MONOREPO_ROOT, '.yarn/cache');
 // Reuse the main project's tsc instead of installing typescript in each temp monorepo.
@@ -136,13 +136,20 @@ describe('compatibility: yarn-install-clean', () => {
     const { dir, cleanup: c } = createMonorepo(
       { private: true, name: '@compat/root' },
       [
+        {
+          location: 'packages/lodash',
+          manifest: {
+            name: 'lodash',
+            version: '4.17.21',
+          },
+        },
         {
           location: 'packages/lib',
           manifest: {
             name: '@compat/lib',
             version: '1.0.0',
-            peerDependencies: { lodash: '^4.17.21' },
-            devDependencies: { lodash: '^4.17.21' },
+            peerDependencies: { lodash: '*' },
+            devDependencies: { lodash: '*' },
           },
         },
         {
@@ -152,7 +159,7 @@ describe('compatibility: yarn-install-clean', () => {
             version: '1.0.0',
             dependencies: {
               '@compat/lib': 'workspace:*',
-              lodash: '^4.17.21',
+              lodash: '*',
             },
           },
         },
@@ -175,7 +182,7 @@ describe('compatibility: yarn-install-clean', () => {
 });
 
 // ---------------------------------------------------------------------------
-// yarn-peer-requirements-clean: required external peers propagated to service
+// yarn-peer-requirements-clean: required peers propagated to service
 // ---------------------------------------------------------------------------
 
 describe('compatibility: yarn-peer-requirements-clean', () => {
@@ -184,20 +191,45 @@ describe('compatibility: yarn-peer-requirements-clean', () => {
   let cleanup: () => void;
 
   beforeAll(() => {
-    // @nestjs/common requires rxjs (required) and reflect-metadata (required).
-    // The model propagates both into service dependencies (invariant P2 + S1).
+    // @compat/framework requires rxjs and reflect-metadata. The model should
+    // propagate both into service dependencies (invariant P2 + S1).
     const { dir, cleanup: c } = createMonorepo(
       { private: true, name: '@compat/root' },
       [
+        {
+          location: 'packages/framework',
+          manifest: {
+            name: '@compat/framework',
+            version: '1.0.0',
+            peerDependencies: {
+              rxjs: '*',
+              'reflect-metadata': '*',
+            },
+          },
+        },
+        {
+          location: 'packages/rxjs',
+          manifest: {
+            name: 'rxjs',
+            version: '7.8.2',
+          },
+        },
+        {
+          location: 'packages/reflect-metadata',
+          manifest: {
+            name: 'reflect-metadata',
+            version: '0.2.2',
+          },
+        },
         {
           location: 'packages/svc',
           manifest: {
             name: '@compat/svc',
             version: '1.0.0',
             dependencies: {
-              '@nestjs/common': '10.4.8',
-              rxjs: '^7.8.1',
-              'reflect-metadata': '^0.1.12 || ^0.2.0',
+              '@compat/framework': 'workspace:*',
+              rxjs: '*',
+              'reflect-metadata': '*',
             },
           },
         },
@@ -233,12 +265,23 @@ describe('compatibility: missing-peer-detected (negative)', () => {
     const { dir, cleanup: c } = createMonorepo(
       { private: true, name: '@compat/root' },
       [
+        {
+          location: 'packages/framework',
+          manifest: {
+            name: '@compat/framework',
+            version: '1.0.0',
+            peerDependencies: {
+              rxjs: '*',
+              'reflect-metadata': '*',
+            },
+          },
+        },
         {
           location: 'packages/svc',
           manifest: {
             name: '@compat/svc',
             version: '1.0.0',
-            dependencies: { '@nestjs/common': '10.4.8' },
+            dependencies: { '@compat/framework': 'workspace:*' },
           },
         },
       ],
@@ -268,19 +311,35 @@ describe('compatibility: tsc-library-build', () => {
   let cleanup: () => void;
 
   beforeAll(() => {
-    // Library imports rxjs (which ships with bundled types). After install the
+    // Library imports rxjs (provided by a local workspace with types). After install the
     // dev mirror (devDependencies = peerDependencies) makes rxjs available for
     // tsc without any additional @types packages.
     const { dir, cleanup: c } = createMonorepo(
       { private: true, name: '@compat/root' },
       [
+        {
+          location: 'packages/rxjs',
+          manifest: {
+            name: 'rxjs',
+            version: '7.8.2',
+            types: 'index.d.ts',
+          },
+          files: {
+            'index.d.ts': [
+              'export declare class Observable<T> {',
+              '  readonly value?: T;',
+              '}',
+              '',
+            ].join('\n'),
+          },
+        },
         {
           location: 'packages/lib',
           manifest: {
             name: '@compat/lib',
             version: '1.0.0',
-            peerDependencies: { rxjs: '^7.8.1' },
-            devDependencies: { rxjs: '^7.8.1' },
+            peerDependencies: { rxjs: '*' },
+            devDependencies: { rxjs: '*' },
           },
           files: {
             'src/index.ts': [

package/__tests__/config-validation.test.ts

@@ -1,4 +1,8 @@
-import { validateDependencyRules } from '../src/model/config-validation';
+import {
+  validateDependencyRules,
+  validateIgnoredImports,
+  validateToolingFiles,
+} from '../src/model/config-validation';
 
 describe('validateDependencyRules', () => {
   it('rejects required wildcard rules because they cannot expand to concrete deps', () => {
@@ -40,3 +44,44 @@ describe('validateDependencyRules', () => {
     ]);
   });
 });
+
+describe('validateIgnoredImports', () => {
+  it('allows string module specifier patterns', () => {
+    expect(validateIgnoredImports(['@docusaurus/router'])).toEqual([]);
+  });
+
+  it('rejects non-string items', () => {
+    expect(validateIgnoredImports([42])).toEqual([
+      expect.stringContaining('ignoredImports[0] must be a string'),
+    ]);
+  });
+});
+
+describe('validateToolingFiles', () => {
+  it('allows a global rule with no workspace scoping', () => {
+    expect(validateToolingFiles([{ match: 'sidebars.ts' }])).toEqual([]);
+  });
+
+  it('allows a workspace-scoped rule with an array of matches', () => {
+    expect(
+      validateToolingFiles([
+        {
+          match: ['sidebars.ts', 'sidebars.js'],
+          workspace: 'niisokb.artifactory.docusaurus',
+        },
+      ]),
+    ).toEqual([]);
+  });
+
+  it('rejects entries missing match', () => {
+    expect(validateToolingFiles([{ workspace: 'foo' }])).toEqual([
+      expect.stringContaining('toolingFiles[0].match must be a string'),
+    ]);
+  });
+
+  it('rejects a non-array value', () => {
+    expect(validateToolingFiles('sidebars.ts')).toEqual([
+      expect.stringContaining('toolingFiles must be an array'),
+    ]);
+  });
+});