@rsdk/yarn.constraints 6.0.0-next.4 → 6.0.0-next.41

package/src/lib/package-json.ts

@@ -0,0 +1,46 @@
+/**
+ * Package manifest helpers.
+ *
+ * This module intentionally stays small: it reads `package.json` files and
+ * locates the monorepo root. Higher-level workspace discovery and model
+ * semantics belong to collectors and the engine.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export interface PackageJson {
+  name: string;
+  private?: boolean;
+  role?: 'library' | 'service' | 'cli';
+  workspaces?: string[] | { packages: string[] };
+  main?: string;
+  types?: string;
+  typings?: string;
+  exports?: unknown;
+  bin?: string | Record<string, string>;
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+  devDependencies?: Record<string, string>;
+}
+
+export function readPackageJson(dir: string): PackageJson {
+  return JSON.parse(
+    readFileSync(join(dir, 'package.json'), 'utf8'),
+  ) as PackageJson;
+}
+
+export function findMonorepoRoot(startDir: string): string | null {
+  let dir = startDir;
+
+  while (true) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as PackageJson;
+      if (pkg.workspaces) return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}

package/src/model/config-validation.ts

@@ -0,0 +1,49 @@
+/**
+ * Config validation for rule shapes that the model cannot interpret safely.
+ */
+import type { DependencyModelConfig, DependencyRule } from './types';
+
+function getRuleMatches(rule: DependencyRule): string[] {
+  return Array.isArray(rule.match) ? rule.match : [rule.match];
+}
+
+function getRuleLabel(rule: DependencyRule, index: number): string {
+  return `rules[${index}] (${getRuleMatches(rule).join(', ')})`;
+}
+
+export function validateDependencyRules(rules: DependencyRule[]): string[] {
+  const errors: string[] = [];
+
+  rules.forEach((rule, index) => {
+    const label = getRuleLabel(rule, index);
+    const matches = getRuleMatches(rule);
+
+    if (rule.required === true && matches.some((match) => match.includes('*'))) {
+      errors.push(
+        `${label}: required: true requires concrete match patterns; wildcard matches are ignored by required dependency expansion`,
+      );
+    }
+
+    if (rule.section === 'devDependencies' && rule.rootOnly !== true) {
+      errors.push(
+        `${label}: section: devDependencies is only supported together with rootOnly: true; workspace devDependencies are derived by the model`,
+      );
+    }
+  });
+
+  return errors;
+}
+
+export function assertValidDependencyModelConfig(
+  config: DependencyModelConfig,
+): void {
+  const errors = validateDependencyRules(config.rules ?? []);
+
+  if (errors.length === 0) return;
+
+  throw new Error(
+    ['Invalid dependency constraints config:', ...errors.map((e) => `- ${e}`)].join(
+      '\n',
+    ),
+  );
+}

package/src/model/diagnostics.ts

@@ -0,0 +1,358 @@
+/**
+ * Manifest diagnostics.
+ *
+ * The expected graph is compared with actual package manifests here. This
+ * module also owns basic shape checks such as root-only sections, workspace
+ * roles, forbidden service/CLI sections, and library mirror diagnostics.
+ */
+import {
+  getDeclaredRange,
+  getDeclaredSection,
+  getExpectedRange,
+  getExpectedSection,
+} from './expected';
+import { isExternal } from './placement';
+import { getEffectiveRule, isWorkspaceRole } from './rules';
+import type {
+  DependencyRule,
+  DependencyViolation,
+  DependencyWarning,
+  ExpectedWorkspace,
+  WorkspaceFacts,
+} from './types';
+import { SECTIONS } from './types';
+
+function getWorkspaceLabel(workspace: WorkspaceFacts): string {
+  return workspace.isRoot ? '<root>' : workspace.name;
+}
+
+function collectActualDependencyNames(workspace: WorkspaceFacts): Set<string> {
+  return new Set(
+    SECTIONS.flatMap((section) => Object.keys(workspace.pkg[section] ?? {})),
+  );
+}
+
+function hasExternalCollectedUsage(
+  workspace: WorkspaceFacts,
+  workspaceNames: Set<string>,
+): boolean {
+  for (const depIdent of workspace.sourceUsage.keys()) {
+    if (isExternal(depIdent, workspaceNames)) return true;
+  }
+
+  for (const depIdent of workspace.dtsImports) {
+    if (isExternal(depIdent, workspaceNames)) return true;
+  }
+
+  return false;
+}
+
+export function compareManifest(
+  expected: ExpectedWorkspace,
+  violations: DependencyViolation[],
+): void {
+  const workspace = expected.workspace;
+  const actualNames = collectActualDependencyNames(workspace);
+  const expectedNames = new Set<string>();
+
+  for (const section of SECTIONS) {
+    for (const depIdent of expected.sections[section].keys()) {
+      expectedNames.add(depIdent);
+    }
+  }
+
+  for (const depIdent of expectedNames) {
+    const expectedSection = getExpectedSection(expected, depIdent)!;
+    const expectedRange = getExpectedRange(expected, depIdent)!;
+    const actualSection = getDeclaredSection(workspace.pkg, depIdent);
+    const actualRange = getDeclaredRange(workspace.pkg, depIdent);
+
+    if (!actualSection) {
+      violations.push({
+        code: 'missing',
+        workspace: getWorkspaceLabel(workspace),
+        workspaceLocation: workspace.location,
+        dependency: depIdent,
+        expectedSection,
+        expectedRange,
+        message: `${depIdent} is missing from ${expectedSection}`,
+      });
+      continue;
+    }
+
+    if (actualSection !== expectedSection) {
+      violations.push({
+        code: expected.workspace.isRoot ? 'root-section' : 'wrong-section',
+        workspace: getWorkspaceLabel(workspace),
+        workspaceLocation: workspace.location,
+        dependency: depIdent,
+        actualSection,
+        expectedSection,
+        actualRange: actualRange ?? undefined,
+        expectedRange,
+        message: `${depIdent} is in ${actualSection}, expected ${expectedSection}`,
+      });
+      continue;
+    }
+
+    if (actualRange !== expectedRange) {
+      violations.push({
+        code: 'wrong-range',
+        workspace: getWorkspaceLabel(workspace),
+        workspaceLocation: workspace.location,
+        dependency: depIdent,
+        actualSection,
+        expectedSection,
+        actualRange: actualRange ?? undefined,
+        expectedRange,
+        message: `${depIdent} range is ${actualRange}, expected ${expectedRange}`,
+      });
+    }
+  }
+
+  for (const depIdent of actualNames) {
+    if (expectedNames.has(depIdent)) continue;
+    const actualSection = getDeclaredSection(workspace.pkg, depIdent);
+    const actualRange = getDeclaredRange(workspace.pkg, depIdent);
+    const isForbiddenRootSection =
+      workspace.isRoot && actualSection && actualSection !== 'devDependencies';
+
+    violations.push({
+      code: isForbiddenRootSection ? 'root-section' : 'stale',
+      workspace: getWorkspaceLabel(workspace),
+      workspaceLocation: workspace.location,
+      dependency: depIdent,
+      actualSection: actualSection ?? undefined,
+      actualRange: actualRange ?? undefined,
+      message: isForbiddenRootSection
+        ? `${depIdent} is declared in root ${actualSection}; root package.json may contain only devDependencies`
+        : `${depIdent} is declared but not required by the derived model`,
+    });
+  }
+
+  for (const depIdent of Object.keys(
+    workspace.pkg.peerDependenciesMeta ?? {},
+  )) {
+    if (expected.sections.peerDependencies.has(depIdent)) continue;
+
+    violations.push({
+      code: 'stale',
+      workspace: getWorkspaceLabel(workspace),
+      workspaceLocation: workspace.location,
+      dependency: depIdent,
+      message:
+        `${depIdent} has peerDependenciesMeta but is not expected in peerDependencies`,
+    });
+  }
+}
+
+export function validateBasicShape(
+  workspaces: WorkspaceFacts[],
+  expectedByLocation: Map<string, ExpectedWorkspace>,
+  rules: DependencyRule[],
+  violations: DependencyViolation[],
+  warnings: DependencyWarning[],
+  withDts: boolean,
+): void {
+  const workspaceNames = new Set(
+    workspaces.filter((ws) => !ws.isRoot).map((ws) => ws.name),
+  );
+
+  for (const workspace of workspaces) {
+    if (workspace.isRoot) {
+      if (workspace.pkg.private !== true) {
+        violations.push({
+          code: 'root-private',
+          workspace: getWorkspaceLabel(workspace),
+          workspaceLocation: workspace.location,
+          message: 'root package.json must have private: true',
+        });
+      }
+      continue;
+    }
+
+    if (!workspace.pkg.role) {
+      violations.push({
+        code: 'role-missing',
+        workspace: getWorkspaceLabel(workspace),
+        workspaceLocation: workspace.location,
+        message: 'workspace package.json must declare role',
+      });
+    } else if (!isWorkspaceRole(workspace.pkg.role)) {
+      violations.push({
+        code: 'role-invalid',
+        workspace: getWorkspaceLabel(workspace),
+        workspaceLocation: workspace.location,
+        message: `workspace role must be library, service, or cli; got ${workspace.pkg.role}`,
+      });
+    }
+
+    if (workspace.pkg.bin && workspace.role !== 'cli') {
+      warnings.push({
+        code: 'bin-role-mismatch',
+        workspace: getWorkspaceLabel(workspace),
+        workspaceLocation: workspace.location,
+        message: 'workspace declares bin but role is not cli',
+      });
+    }
+
+    if (
+      workspace.role &&
+      workspace.sourceFileCount !== undefined &&
+      workspace.sourceFileCount > 0 &&
+      !hasExternalCollectedUsage(workspace, workspaceNames)
+    ) {
+      warnings.push({
+        code: 'zero-external-dependencies',
+        workspace: getWorkspaceLabel(workspace),
+        workspaceLocation: workspace.location,
+        message:
+          `no external source imports were collected from ${workspace.sourceFileCount} source file(s); check source roots and entrypoints before trusting autofix`,
+      });
+    }
+
+    if (workspace.hasSrc && !workspace.hasDist && withDts) {
+      violations.push({
+        code: 'dist-missing',
+        workspace: getWorkspaceLabel(workspace),
+        workspaceLocation: workspace.location,
+        message: 'dist/ not found; build required before --with-dts check',
+      });
+    }
+
+    if (workspace.role === 'service' || workspace.role === 'cli') {
+      for (const section of ['peerDependencies', 'devDependencies'] as const) {
+        for (const depIdent of Object.keys(workspace.pkg[section] ?? {})) {
+          violations.push({
+            code: 'forbidden-section',
+            workspace: getWorkspaceLabel(workspace),
+            workspaceLocation: workspace.location,
+            dependency: depIdent,
+            actualSection: section,
+            expectedSection:
+              section === 'peerDependencies' ? 'dependencies' : undefined,
+            message: `${section} are forbidden for ${workspace.role} workspaces`,
+          });
+        }
+      }
+    }
+
+    if (workspace.role === 'library') {
+      for (const depIdent of Object.keys(workspace.pkg.dependencies ?? {})) {
+        if (workspace.pkg.peerDependencies?.[depIdent] !== undefined) {
+          violations.push({
+            code: 'forbidden-section',
+            workspace: getWorkspaceLabel(workspace),
+            workspaceLocation: workspace.location,
+            dependency: depIdent,
+            actualSection: 'dependencies',
+            expectedSection: 'peerDependencies',
+            message: `${depIdent} is declared in both dependencies and peerDependencies`,
+          });
+        }
+      }
+
+      const expected = expectedByLocation.get(workspace.location);
+      if (expected) {
+        for (const [depIdent, peerRange] of expected.sections
+          .peerDependencies) {
+          const devRange = workspace.pkg.devDependencies?.[depIdent];
+          if (devRange !== peerRange) {
+            violations.push({
+              code: 'mirror',
+              workspace: getWorkspaceLabel(workspace),
+              workspaceLocation: workspace.location,
+              dependency: depIdent,
+              actualSection: 'devDependencies',
+              expectedSection: 'devDependencies',
+              actualRange: devRange,
+              expectedRange: peerRange,
+              message: `${depIdent} must be mirrored from peerDependencies to devDependencies`,
+            });
+          }
+        }
+      }
+    }
+
+    for (const depIdent of Object.keys(workspace.pkg.devDependencies ?? {})) {
+      if (workspace.pkg.dependencies?.[depIdent] !== undefined) {
+        violations.push({
+          code: 'forbidden-section',
+          workspace: getWorkspaceLabel(workspace),
+          workspaceLocation: workspace.location,
+          dependency: depIdent,
+          actualSection: 'devDependencies',
+          expectedSection: 'dependencies',
+          message: `${depIdent} is declared in both dependencies and devDependencies`,
+        });
+      }
+    }
+
+    for (const section of SECTIONS) {
+      for (const depIdent of Object.keys(workspace.pkg[section] ?? {})) {
+        const rule = getEffectiveRule(
+          rules,
+          depIdent,
+          workspace.name,
+          workspace.location,
+        );
+        const expected = expectedByLocation.get(workspace.location);
+        if (
+          rule.rootOnly &&
+          isExternal(depIdent, workspaceNames) &&
+          !expected?.sections[section].has(depIdent)
+        ) {
+          violations.push({
+            code: 'root-only',
+            workspace: getWorkspaceLabel(workspace),
+            workspaceLocation: workspace.location,
+            dependency: depIdent,
+            actualSection: section,
+            expectedSection: 'devDependencies',
+            message: `${depIdent} is rootOnly and must not be declared in workspace package.json`,
+          });
+        }
+      }
+    }
+
+    const expected = expectedByLocation.get(workspace.location);
+    if (expected) {
+      for (const [depIdent, reasons] of expected.reasons) {
+        if (!isExternal(depIdent, workspaceNames)) continue;
+        if (!reasons.some((reason) => reason.kind === 'root-only')) continue;
+
+        violations.push({
+          code: 'root-only-usage',
+          workspace: getWorkspaceLabel(workspace),
+          workspaceLocation: workspace.location,
+          dependency: depIdent,
+          expectedSection: 'devDependencies',
+          message: `${depIdent} is rootOnly and must not be used by workspace source or peer surface`,
+        });
+      }
+    }
+  }
+}
+
+export function dedupeViolations(
+  violations: DependencyViolation[],
+): DependencyViolation[] {
+  const result: DependencyViolation[] = [];
+  const seen = new Set<string>();
+
+  for (const violation of violations) {
+    const key = [
+      violation.code,
+      violation.workspaceLocation,
+      violation.dependency ?? '',
+      violation.actualSection ?? '',
+      violation.expectedSection ?? '',
+      violation.expectedRange ?? '',
+    ].join('\0');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(violation);
+  }
+
+  return result;
+}

package/src/model/engine.ts

@@ -0,0 +1,120 @@
+/**
+ * Pure dependency model engine.
+ *
+ * The engine receives complete facts and derives expected manifests plus
+ * diagnostics. It must not read files, execute Yarn, or inspect `node_modules`;
+ * those concerns belong to collectors and the runner.
+ */
+import { compareManifest, dedupeViolations, validateBasicShape } from './diagnostics';
+import { emptySections } from './expected';
+import { propagatePeers } from './peer-propagation';
+import {
+  addRequiredRuleDependencies,
+  addUsageDependencies,
+  rebuildLibraryMirrors,
+  seedRootDevDependencies,
+} from './placement';
+import type {
+  DependencyModelFacts,
+  DependencyModelOutput,
+  DependencyRule,
+  ExpectedWorkspace,
+  WorkspaceFacts,
+} from './types';
+import {
+  applyVersionRules,
+  collectUnconstrainedVersionViolations,
+} from './versions';
+
+export function buildExpected(
+  workspaces: WorkspaceFacts[],
+  rules: DependencyRule[],
+  externalPeerMetadata: Map<string, Map<string, string> | null>,
+  externalTypeMetadata: Map<string, { hasBundledTypes: boolean }>,
+  typeProviderPackages: Set<string>,
+): Map<string, ExpectedWorkspace> {
+  const expectedByLocation = new Map<string, ExpectedWorkspace>();
+  const root = workspaces[0]!;
+  const workspaceNames = new Set(
+    workspaces.filter((ws) => !ws.isRoot).map((ws) => ws.name),
+  );
+  const workspacesByName = new Map(
+    workspaces.filter((ws) => !ws.isRoot).map((ws) => [ws.name, ws]),
+  );
+
+  for (const workspace of workspaces) {
+    expectedByLocation.set(workspace.location, {
+      workspace,
+      sections: emptySections(),
+      reasons: new Map(),
+    });
+  }
+
+  seedRootDevDependencies(expectedByLocation, workspaceNames, rules);
+  addUsageDependencies(
+    expectedByLocation,
+    root,
+    workspaceNames,
+    rules,
+    externalTypeMetadata,
+    typeProviderPackages,
+  );
+  addRequiredRuleDependencies(
+    expectedByLocation,
+    root,
+    workspaceNames,
+    rules,
+  );
+  propagatePeers(
+    expectedByLocation,
+    workspacesByName,
+    workspaceNames,
+    externalPeerMetadata,
+    rules,
+  );
+  applyVersionRules(expectedByLocation, root, workspaceNames, rules);
+  rebuildLibraryMirrors(expectedByLocation);
+
+  return expectedByLocation;
+}
+
+export function deriveDependencyModel(
+  facts: DependencyModelFacts,
+): DependencyModelOutput {
+  const {
+    workspaces,
+    externalPeerMetadata,
+    externalTypeMetadata = new Map(),
+    typeProviderPackages = new Set(),
+    rules,
+    withDts = false,
+  } = facts;
+  const expected = buildExpected(
+    workspaces,
+    rules,
+    externalPeerMetadata,
+    externalTypeMetadata,
+    typeProviderPackages,
+  );
+  const violations: DependencyModelOutput['violations'] = [];
+  const warnings: DependencyModelOutput['warnings'] = [];
+
+  validateBasicShape(
+    workspaces,
+    expected,
+    rules,
+    violations,
+    warnings,
+    withDts,
+  );
+  for (const item of expected.values()) compareManifest(item, violations);
+  violations.push(
+    ...collectUnconstrainedVersionViolations(workspaces, expected, rules),
+  );
+
+  return {
+    violations: dedupeViolations(violations),
+    warnings,
+    expected,
+  };
+}

package/src/model/expected.ts

@@ -0,0 +1,141 @@
+/**
+ * Helpers for expected dependency sections and their explanations.
+ *
+ * The model derives a fresh expected manifest for each workspace. This module
+ * owns the small mutation primitives for those expected sections and keeps the
+ * reason trail used by `depdoc explain`.
+ */
+import type { PackageJson } from '../lib/package-json';
+
+import { getEffectiveRule } from './rules';
+import {
+  type DependencyRule,
+  type ExpectedWorkspace,
+  type Reason,
+  SECTIONS,
+  type SectionType,
+  type WorkspaceFacts,
+} from './types';
+
+export function emptySections(): Record<SectionType, Map<string, string>> {
+  return {
+    dependencies: new Map(),
+    peerDependencies: new Map(),
+    devDependencies: new Map(),
+  };
+}
+
+export function getDeclaredSection(
+  pkg: PackageJson,
+  depIdent: string,
+): SectionType | null {
+  for (const section of SECTIONS) {
+    if (pkg[section]?.[depIdent] !== undefined) return section;
+  }
+
+  return null;
+}
+
+export function getDeclaredRange(
+  pkg: PackageJson,
+  depIdent: string,
+): string | null {
+  const section = getDeclaredSection(pkg, depIdent);
+
+  return section ? (pkg[section]?.[depIdent] ?? null) : null;
+}
+
+export function addReason(
+  expected: ExpectedWorkspace,
+  depIdent: string,
+  reason: Reason,
+): void {
+  if (!expected.reasons.has(depIdent)) expected.reasons.set(depIdent, []);
+  const list = expected.reasons.get(depIdent)!;
+  if (!list.some((r) => r.kind === reason.kind && r.detail === reason.detail)) {
+    list.push(reason);
+  }
+}
+
+export function addRuleReason(
+  expected: ExpectedWorkspace,
+  depIdent: string,
+  rule: ReturnType<typeof getEffectiveRule>,
+): void {
+  const details: string[] = [];
+  if (rule.section) details.push(`section: ${rule.section}`);
+  if (rule.version !== undefined) details.push(`version: ${rule.version}`);
+  if (rule.rootOnly) details.push('rootOnly: true');
+  if (rule.required) details.push('required: true');
+  if (details.length === 0) return;
+
+  addReason(expected, depIdent, {
+    kind: 'rule',
+    detail: `${depIdent} matched rule (${details.join(', ')})`,
+  });
+}
+
+export function setExpectedDependency(
+  expected: ExpectedWorkspace,
+  section: SectionType,
+  depIdent: string,
+  range: string,
+  reason: Reason,
+): void {
+  for (const other of SECTIONS) {
+    if (other !== section) expected.sections[other].delete(depIdent);
+  }
+  expected.sections[section].set(depIdent, range);
+  addReason(expected, depIdent, reason);
+}
+
+export function addExpectedMirrorDependency(
+  expected: ExpectedWorkspace,
+  depIdent: string,
+  range: string,
+  reason: Reason,
+): void {
+  expected.sections.devDependencies.set(depIdent, range);
+  addReason(expected, depIdent, reason);
+}
+
+export function getExpectedSection(
+  expected: ExpectedWorkspace,
+  depIdent: string,
+): SectionType | null {
+  for (const section of SECTIONS) {
+    if (expected.sections[section].has(depIdent)) return section;
+  }
+
+  return null;
+}
+
+export function getExpectedRange(
+  expected: ExpectedWorkspace,
+  depIdent: string,
+): string | null {
+  const section = getExpectedSection(expected, depIdent);
+
+  return section ? (expected.sections[section].get(depIdent) ?? null) : null;
+}
+
+export function getRangeSource(
+  root: WorkspaceFacts,
+  workspace: WorkspaceFacts,
+  depIdent: string,
+  rules: DependencyRule[],
+): string {
+  const rule = getEffectiveRule(
+    rules,
+    depIdent,
+    workspace.name,
+    workspace.location,
+  );
+  if (rule.version !== undefined) return rule.version;
+
+  return (
+    getDeclaredRange(workspace.pkg, depIdent) ??
+    getDeclaredRange(root.pkg, depIdent) ??
+    '*'
+  );
+}