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

package/src/model/placement.ts

@@ -0,0 +1,372 @@
+/**
+ * Dependency placement rules.
+ *
+ * This module converts source and `.d.ts` usage facts into expected manifest
+ * sections. It is pure: it receives workspace facts, rules, type metadata, and
+ * local workspace names, then mutates only the in-memory expected graph.
+ */
+import {
+  addExpectedMirrorDependency,
+  addReason,
+  addRuleReason,
+  getDeclaredRange,
+  getRangeSource,
+  setExpectedDependency,
+} from './expected';
+import { getEffectiveRule } from './rules';
+import type {
+  DependencyRule,
+  ExpectedWorkspace,
+  Reason,
+  WorkspaceFacts,
+} from './types';
+
+function isTestFile(file: string): boolean {
+  return /(^|[/.])(__test__|__tests__|test|tests|spec|e2e)([/.]|$)|\.(spec|test|e2e)\.[cm]?[tj]sx?$/.test(
+    file,
+  );
+}
+
+export function isExternal(
+  depIdent: string,
+  workspaceNames: Set<string>,
+): boolean {
+  return !workspaceNames.has(depIdent);
+}
+
+function getDefinitelyTypedProvider(depIdent: string): string | null {
+  if (depIdent.startsWith('@types/')) return null;
+  if (depIdent.startsWith('@')) {
+    const [scope, name] = depIdent.slice(1).split('/');
+    if (!scope || !name) return null;
+    return `@types/${scope}__${name}`;
+  }
+
+  return `@types/${depIdent}`;
+}
+
+function shouldAddDefinitelyTypedProvider(
+  depIdent: string,
+  externalTypeMetadata: Map<string, { hasBundledTypes: boolean }>,
+  typeProviderPackages: Set<string>,
+): string | null {
+  const provider = getDefinitelyTypedProvider(depIdent);
+  if (!provider || !typeProviderPackages.has(provider)) return null;
+  if (externalTypeMetadata.get(depIdent)?.hasBundledTypes) return null;
+
+  return provider;
+}
+
+function getConcreteRuleMatches(rule: DependencyRule): string[] {
+  const matches = Array.isArray(rule.match) ? rule.match : [rule.match];
+
+  return matches.filter((match) => !match.includes('*'));
+}
+
+function addPublicDependency(
+  expected: ExpectedWorkspace,
+  rootExpected: ExpectedWorkspace,
+  root: WorkspaceFacts,
+  workspaceNames: Set<string>,
+  rules: DependencyRule[],
+  depIdent: string,
+  reason: Reason,
+  options: { allowRootOnly?: boolean } = {},
+): void {
+  const workspace = expected.workspace;
+  const rule = getEffectiveRule(
+    rules,
+    depIdent,
+    workspace.name,
+    workspace.location,
+  );
+  const isLocal = workspaceNames.has(depIdent);
+  const range = isLocal
+    ? 'workspace:*'
+    : getRangeSource(root, workspace, depIdent, rules);
+
+  addRuleReason(expected, depIdent, rule);
+
+  if (rule.rootOnly && !isLocal && !options.allowRootOnly) {
+    setExpectedDependency(rootExpected, 'devDependencies', depIdent, range, {
+      kind: 'root-only',
+      detail: `${depIdent} is marked rootOnly`,
+    });
+    addReason(expected, depIdent, reason);
+    addReason(expected, depIdent, {
+      kind: 'root-only',
+      detail: `${depIdent} is marked rootOnly and cannot be used by ${workspace.name}`,
+    });
+    return;
+  }
+
+  if (isLocal) {
+    setExpectedDependency(expected, 'dependencies', depIdent, 'workspace:*', {
+      kind: reason.kind,
+      detail: `${reason.detail}; local workspace edge`,
+    });
+    return;
+  }
+
+  if (
+    workspace.role === 'library' &&
+    rule.section !== 'dependencies' &&
+    rule.section !== 'devDependencies'
+  ) {
+    setExpectedDependency(
+      expected,
+      'peerDependencies',
+      depIdent,
+      range,
+      reason,
+    );
+    addExpectedMirrorDependency(expected, depIdent, range, {
+      kind: 'mirror',
+      detail: `${depIdent} mirrors peerDependencies in devDependencies`,
+    });
+    return;
+  }
+
+  setExpectedDependency(expected, 'dependencies', depIdent, range, reason);
+}
+
+function addPrivateDependency(
+  rootExpected: ExpectedWorkspace,
+  root: WorkspaceFacts,
+  requester: ExpectedWorkspace,
+  workspaceNames: Set<string>,
+  rules: DependencyRule[],
+  depIdent: string,
+  reason: Reason,
+): void {
+  const workspace = requester.workspace;
+  if (workspaceNames.has(depIdent)) return;
+  const rule = getEffectiveRule(
+    rules,
+    depIdent,
+    workspace.name,
+    workspace.location,
+  );
+  const range = getRangeSource(root, workspace, depIdent, rules);
+
+  addRuleReason(rootExpected, depIdent, rule);
+  addRuleReason(requester, depIdent, rule);
+
+  if (rule.rootOnly) {
+    addReason(requester, depIdent, {
+      kind: 'root-only',
+      detail: `${depIdent} is marked rootOnly and cannot be used by ${workspace.name}`,
+    });
+  }
+
+  setExpectedDependency(
+    rootExpected,
+    'devDependencies',
+    depIdent,
+    range,
+    reason,
+  );
+}
+
+export function seedRootDevDependencies(
+  expectedByLocation: Map<string, ExpectedWorkspace>,
+  workspaceNames: Set<string>,
+  rules: DependencyRule[],
+): void {
+  const rootExpected = expectedByLocation.get('.')!;
+
+  for (const [depIdent, declaredRange] of Object.entries(
+    rootExpected.workspace.pkg.devDependencies ?? {},
+  )) {
+    const rule = getEffectiveRule(
+      rules,
+      depIdent,
+      rootExpected.workspace.name,
+      rootExpected.workspace.location,
+    );
+    const range = workspaceNames.has(depIdent)
+      ? 'workspace:*'
+      : (rule.version ?? declaredRange);
+
+    setExpectedDependency(rootExpected, 'devDependencies', depIdent, range, {
+      kind: 'declared',
+      detail: `${depIdent} is declared in root devDependencies baseline`,
+    });
+    addRuleReason(rootExpected, depIdent, rule);
+  }
+}
+
+export function addUsageDependencies(
+  expectedByLocation: Map<string, ExpectedWorkspace>,
+  root: WorkspaceFacts,
+  workspaceNames: Set<string>,
+  rules: DependencyRule[],
+  externalTypeMetadata: Map<string, { hasBundledTypes: boolean }>,
+  typeProviderPackages: Set<string>,
+): void {
+  const rootExpected = expectedByLocation.get('.')!;
+
+  for (const expected of expectedByLocation.values()) {
+    const workspace = expected.workspace;
+    if (workspace.isRoot) continue;
+
+    for (const [depIdent, usage] of workspace.sourceUsage) {
+      const publicType = workspace.dtsImports.has(depIdent);
+      const runtime = [...usage.runtimeFiles].some((file) => !isTestFile(file));
+      const allTestOnly = [...usage.files].every(isTestFile);
+
+      if (runtime || publicType) {
+        addPublicDependency(
+          expected,
+          rootExpected,
+          root,
+          workspaceNames,
+          rules,
+          depIdent,
+          {
+            kind: publicType ? 'source-public-type' : 'source-runtime',
+            detail: publicType
+              ? `${depIdent} appears in emitted .d.ts`
+              : `${depIdent} is imported at runtime`,
+          },
+        );
+      } else {
+        addPrivateDependency(
+          rootExpected,
+          root,
+          expected,
+          workspaceNames,
+          rules,
+          depIdent,
+          {
+            kind: 'source-private-dev',
+            detail: allTestOnly
+              ? `${depIdent} is only used by test files in ${workspace.name}`
+              : `${depIdent} is only used as private type/tooling dependency in ${workspace.name}`,
+          },
+        );
+      }
+    }
+
+    for (const depIdent of workspace.dtsImports) {
+      addPublicDependency(
+        expected,
+        rootExpected,
+        root,
+        workspaceNames,
+        rules,
+        depIdent,
+        {
+          kind: 'source-public-type',
+          detail: `${depIdent} appears in emitted .d.ts`,
+        },
+      );
+
+      const typeProvider = shouldAddDefinitelyTypedProvider(
+        depIdent,
+        externalTypeMetadata,
+        typeProviderPackages,
+      );
+      if (!typeProvider) continue;
+
+      addPublicDependency(
+        expected,
+        rootExpected,
+        root,
+        workspaceNames,
+        rules,
+        typeProvider,
+        {
+          kind: 'dts-provider',
+          detail: `${typeProvider} provides public types for ${depIdent}`,
+        },
+        { allowRootOnly: true },
+      );
+    }
+  }
+}
+
+export function addRequiredRuleDependencies(
+  expectedByLocation: Map<string, ExpectedWorkspace>,
+  root: WorkspaceFacts,
+  workspaceNames: Set<string>,
+  rules: DependencyRule[],
+): void {
+  const rootExpected = expectedByLocation.get('.')!;
+  const candidates = new Set<string>();
+
+  for (const rule of rules) {
+    if (rule.required === undefined) continue;
+    for (const depIdent of getConcreteRuleMatches(rule)) {
+      candidates.add(depIdent);
+    }
+  }
+
+  for (const expected of expectedByLocation.values()) {
+    const workspace = expected.workspace;
+    if (workspace.isRoot) continue;
+
+    for (const depIdent of candidates) {
+      const rule = getEffectiveRule(
+        rules,
+        depIdent,
+        workspace.name,
+        workspace.location,
+      );
+      if (!rule.required) continue;
+
+      addPublicDependency(
+        expected,
+        rootExpected,
+        root,
+        workspaceNames,
+        rules,
+        depIdent,
+        {
+          kind: 'required-rule',
+          detail: `${depIdent} is marked required by dependency rule`,
+        },
+      );
+    }
+  }
+}
+
+export function rebuildLibraryMirrors(
+  expectedByLocation: Map<string, ExpectedWorkspace>,
+): void {
+  for (const expected of expectedByLocation.values()) {
+    if (expected.workspace.role !== 'library') continue;
+    expected.sections.devDependencies = new Map(
+      expected.sections.peerDependencies,
+    );
+    for (const [depIdent] of expected.sections.devDependencies) {
+      addReason(expected, depIdent, {
+        kind: 'mirror',
+        detail: `${depIdent} mirrors peerDependencies in devDependencies`,
+      });
+    }
+  }
+}
+
+export function resolveExpectedRangeAfterRulePass(
+  root: WorkspaceFacts,
+  expected: ExpectedWorkspace,
+  workspaceNames: Set<string>,
+  rules: DependencyRule[],
+  depIdent: string,
+  currentRange: string,
+): string {
+  const rule = getEffectiveRule(
+    rules,
+    depIdent,
+    expected.workspace.name,
+    expected.workspace.location,
+  );
+
+  return workspaceNames.has(depIdent)
+    ? 'workspace:*'
+    : (rule.version ??
+      getDeclaredRange(expected.workspace.pkg, depIdent) ??
+      getDeclaredRange(root.pkg, depIdent) ??
+      currentRange);
+}

package/src/model/rules.ts

@@ -0,0 +1,73 @@
+/**
+ * Rule matching and precedence.
+ *
+ * Dependency rules are the explicit override surface for the model: versions,
+ * section overrides, root-only constraints, and workspace-specific exceptions.
+ * The helpers here are pure and apply the documented "last matching rule wins"
+ * semantics.
+ */
+import type { DependencyRule, EffectiveRule, WorkspaceRole } from './types';
+
+export function matchesGlob(value: string, pattern: string): boolean {
+  if (!pattern.includes('*')) return value === pattern;
+  const escaped = pattern.replaceAll(
+    /[-[\]{}()+?.,\\^$|#\s]/g,
+    String.raw`\$&`,
+  );
+
+  return new RegExp(
+    '^' + escaped.replaceAll('**', '.*').replaceAll('*', '[^/]*') + '$',
+  ).test(value);
+}
+
+export function matchesPatterns(
+  value: string,
+  pattern: string | string[],
+): boolean {
+  const patterns = Array.isArray(pattern) ? pattern : [pattern];
+
+  return patterns.some((p) => matchesGlob(value, p));
+}
+
+export function getEffectiveRule(
+  rules: DependencyRule[],
+  depIdent: string,
+  wsIdent: string,
+  wsCwd: string,
+): EffectiveRule {
+  const effective: EffectiveRule = { rootOnly: false };
+
+  for (const rule of rules) {
+    if (!matchesPatterns(depIdent, rule.match)) continue;
+    if (
+      rule.workspace &&
+      !matchesPatterns(wsIdent, rule.workspace) &&
+      !matchesPatterns(wsCwd, rule.workspace)
+    )
+      continue;
+    if (rule.section) effective.section = rule.section;
+    if (rule.version !== undefined) effective.version = rule.version;
+    if (rule.rootOnly !== undefined) effective.rootOnly = rule.rootOnly;
+    if (rule.required !== undefined) effective.required = rule.required;
+  }
+
+  return effective;
+}
+
+export function hasGlobalVersionRule(
+  rules: DependencyRule[],
+  depIdent: string,
+): boolean {
+  return rules.some(
+    (rule) =>
+      !rule.workspace &&
+      rule.version !== undefined &&
+      matchesPatterns(depIdent, rule.match),
+  );
+}
+
+export function isWorkspaceRole(
+  value: string | undefined,
+): value is WorkspaceRole {
+  return value === 'library' || value === 'service' || value === 'cli';
+}

package/src/model/types.ts

@@ -0,0 +1,164 @@
+/**
+ * Shared dependency-model contracts.
+ *
+ * This module defines the data exchanged between collectors, the pure model
+ * engine, the manifest writer, and CLI reporting. It intentionally contains no
+ * filesystem or Yarn logic; callers should pass already collected facts.
+ */
+import type { PackageJson } from '../lib/package-json';
+
+export type SectionType =
+  | 'dependencies'
+  | 'peerDependencies'
+  | 'devDependencies';
+
+export type WorkspaceRole = 'library' | 'service' | 'cli';
+
+export interface DependencyRule {
+  match: string | string[];
+  workspace?: string | string[];
+  section?: SectionType;
+  version?: string;
+  rootOnly?: boolean;
+  required?: boolean;
+}
+
+export interface DependencyModelConfig {
+  version?: number;
+  rules?: DependencyRule[];
+  doctor?: DoctorConfig;
+}
+
+export interface DoctorConfig {
+  buildCmd?: string;
+  lintCmd?: string;
+  typecheckCmd?: string;
+}
+
+export interface DependencyModelOptions {
+  rootDir?: string;
+  constraintsPath?: string;
+  fix?: boolean;
+  withDts?: boolean;
+}
+
+export interface DependencyViolation {
+  code:
+    | 'root-private'
+    | 'root-section'
+    | 'role-missing'
+    | 'role-invalid'
+    | 'forbidden-section'
+    | 'missing'
+    | 'wrong-section'
+    | 'wrong-range'
+    | 'root-only'
+    | 'root-only-usage'
+    | 'unconstrained-version'
+    | 'mirror'
+    | 'stale'
+    | 'dist-missing';
+  workspace: string;
+  workspaceLocation: string;
+  dependency?: string | undefined;
+  actualSection?: SectionType | undefined;
+  expectedSection?: SectionType | undefined;
+  actualRange?: string | undefined;
+  expectedRange?: string | undefined;
+  message: string;
+}
+
+export interface DependencyWarning {
+  code: 'bin-role-mismatch';
+  workspace?: string | undefined;
+  workspaceLocation?: string | undefined;
+  dependency?: string | undefined;
+  message: string;
+}
+
+export interface UsageSummary {
+  files: Set<string>;
+  runtimeFiles: Set<string>;
+  typeOnlyFiles: Set<string>;
+}
+
+export interface WorkspaceFacts {
+  name: string;
+  location: string;
+  pkg: PackageJson;
+  role: WorkspaceRole | undefined;
+  isRoot: boolean;
+  sourceUsage: Map<string, UsageSummary>;
+  dtsImports: Set<string>;
+  hasSrc: boolean;
+  hasDist: boolean;
+}
+
+export interface WorkspaceContext extends WorkspaceFacts {
+  dir: string;
+}
+
+export interface DependencyModelFacts {
+  workspaces: WorkspaceFacts[];
+  externalPeerMetadata: Map<string, Map<string, string> | null>;
+  externalTypeMetadata?: Map<string, { hasBundledTypes: boolean }>;
+  typeProviderPackages?: Set<string>;
+  rules: DependencyRule[];
+  withDts?: boolean;
+}
+
+export interface DependencyModelOutput {
+  violations: DependencyViolation[];
+  warnings: DependencyWarning[];
+  expected: Map<string, ExpectedWorkspace>;
+}
+
+export interface DependencyModelResult {
+  rootDir: string;
+  violations: DependencyViolation[];
+  warnings: DependencyWarning[];
+  contexts: WorkspaceContext[];
+  expected: Map<string, ExpectedWorkspace>;
+  config: DependencyModelConfig;
+}
+
+export interface Reason {
+  kind:
+    | 'declared'
+    | 'source-runtime'
+    | 'source-public-type'
+    | 'source-private-dev'
+    | 'rule'
+    | 'root-only'
+    | 'dts-provider'
+    | 'peer-propagation'
+    | 'mirror'
+    | 'version'
+    | 'required-rule';
+  detail: string;
+}
+
+export interface ExpectedWorkspace {
+  workspace: WorkspaceFacts;
+  sections: Record<SectionType, Map<string, string>>;
+  reasons: Map<string, Reason[]>;
+}
+
+export interface EffectiveRule {
+  section?: SectionType;
+  version?: string;
+  rootOnly: boolean;
+  required?: boolean;
+}
+
+export interface PackageExtension {
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+}
+
+export const SECTIONS: SectionType[] = [
+  'dependencies',
+  'peerDependencies',
+  'devDependencies',
+];

package/src/model/versions.ts

@@ -0,0 +1,109 @@
+/**
+ * Version normalization and version-rule diagnostics.
+ *
+ * The placement engine decides where dependencies belong. This module applies
+ * version rules after placement and checks the invariant that repeated external
+ * dependencies have a global version rule.
+ */
+import { addReason } from './expected';
+import { isExternal, resolveExpectedRangeAfterRulePass } from './placement';
+import { hasGlobalVersionRule } from './rules';
+import type {
+  DependencyRule,
+  DependencyViolation,
+  ExpectedWorkspace,
+  SectionType,
+  WorkspaceFacts,
+} from './types';
+import { SECTIONS } from './types';
+
+export function applyVersionRules(
+  expectedByLocation: Map<string, ExpectedWorkspace>,
+  root: WorkspaceFacts,
+  workspaceNames: Set<string>,
+  rules: DependencyRule[],
+): void {
+  for (const expected of expectedByLocation.values()) {
+    for (const section of SECTIONS) {
+      for (const [depIdent, range] of expected.sections[section]) {
+        const nextRange = resolveExpectedRangeAfterRulePass(
+          root,
+          expected,
+          workspaceNames,
+          rules,
+          depIdent,
+          range,
+        );
+
+        if (nextRange !== range) {
+          expected.sections[section].set(depIdent, nextRange);
+          addReason(expected, depIdent, {
+            kind: 'version',
+            detail: `${depIdent} range resolved to ${nextRange}`,
+          });
+        }
+      }
+    }
+  }
+}
+
+export function collectUnconstrainedVersionViolations(
+  workspaces: WorkspaceFacts[],
+  expectedByLocation: Map<string, ExpectedWorkspace>,
+  rules: DependencyRule[],
+): DependencyViolation[] {
+  const workspaceNames = new Set(
+    workspaces.filter((ws) => !ws.isRoot).map((ws) => ws.name),
+  );
+  const occurrences = new Map<string, Set<string>>();
+  const ranges = new Map<string, Set<string>>();
+
+  const addOccurrence = (
+    workspace: WorkspaceFacts,
+    section: SectionType,
+    depIdent: string,
+    range: string,
+  ): void => {
+    if (!isExternal(depIdent, workspaceNames) || range.startsWith('workspace:'))
+      return;
+    if (!occurrences.has(depIdent)) occurrences.set(depIdent, new Set());
+    if (!ranges.has(depIdent)) ranges.set(depIdent, new Set());
+    occurrences.get(depIdent)!.add(`${workspace.location}:${section}`);
+    ranges.get(depIdent)!.add(range);
+  };
+
+  for (const workspace of workspaces) {
+    for (const section of SECTIONS) {
+      for (const [depIdent, range] of Object.entries(
+        workspace.pkg[section] ?? {},
+      )) {
+        addOccurrence(workspace, section, depIdent, range);
+      }
+    }
+  }
+
+  for (const expected of expectedByLocation.values()) {
+    for (const section of SECTIONS) {
+      for (const [depIdent, range] of expected.sections[section]) {
+        addOccurrence(expected.workspace, section, depIdent, range);
+      }
+    }
+  }
+
+  return [...occurrences.entries()]
+    .filter(
+      ([depIdent, byOccurrence]) =>
+        byOccurrence.size > 1 && !hasGlobalVersionRule(rules, depIdent),
+    )
+    .map(([depIdent, byOccurrence]) => {
+      const rangeList = [...(ranges.get(depIdent) ?? [])].join(', ');
+
+      return {
+        code: 'unconstrained-version' as const,
+        workspace: '<root>',
+        workspaceLocation: '.',
+        dependency: depIdent,
+        message: `${depIdent} appears ${byOccurrence.size} times without a global version rule (${rangeList})`,
+      };
+    });
+}