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

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) ??
+    '*'
+  );
+}

package/src/model/peer-propagation.ts

@@ -0,0 +1,199 @@
+/**
+ * Peer propagation across dependency edges.
+ *
+ * This module applies peer requirements from local libraries and external
+ * packages to the current workspace. It consumes already collected peer
+ * metadata and does not inspect `node_modules` itself.
+ */
+import {
+  addExpectedMirrorDependency,
+  addReason,
+  addRuleReason,
+  getExpectedRange,
+  getExpectedSection,
+  setExpectedDependency,
+} from './expected';
+import { getEffectiveRule } from './rules';
+import type {
+  DependencyRule,
+  ExpectedWorkspace,
+  WorkspaceFacts,
+} from './types';
+
+function providePeer(
+  expected: ExpectedWorkspace,
+  rootExpected: ExpectedWorkspace,
+  workspaceNames: Set<string>,
+  rules: DependencyRule[],
+  depIdent: string,
+  range: string,
+  provider: string,
+): boolean {
+  if (workspaceNames.has(depIdent)) return false;
+  if (expected.sections.dependencies.has(depIdent)) return false;
+
+  const beforeSection = getExpectedSection(expected, depIdent);
+  const beforeRange = getExpectedRange(expected, depIdent);
+  const rule = getEffectiveRule(
+    rules,
+    depIdent,
+    expected.workspace.name,
+    expected.workspace.location,
+  );
+  const resolvedRange = rule.version ?? range;
+
+  addRuleReason(expected, depIdent, rule);
+
+  if (rule.rootOnly) {
+    setExpectedDependency(
+      rootExpected,
+      'devDependencies',
+      depIdent,
+      resolvedRange,
+      {
+        kind: 'root-only',
+        detail: `${depIdent} is required by ${provider} but marked rootOnly`,
+      },
+    );
+    addReason(expected, depIdent, {
+      kind: 'root-only',
+      detail: `${depIdent} is required by ${provider} but marked rootOnly`,
+    });
+    return false;
+  }
+
+  if (
+    expected.workspace.role === 'library' &&
+    rule.section !== 'dependencies'
+  ) {
+    setExpectedDependency(
+      expected,
+      'peerDependencies',
+      depIdent,
+      resolvedRange,
+      {
+        kind: 'peer-propagation',
+        detail: `${depIdent} is required peer of ${provider}`,
+      },
+    );
+    addExpectedMirrorDependency(expected, depIdent, resolvedRange, {
+      kind: 'mirror',
+      detail: `${depIdent} mirrors propagated peer`,
+    });
+  } else {
+    setExpectedDependency(expected, 'dependencies', depIdent, resolvedRange, {
+      kind: 'peer-propagation',
+      detail: `${depIdent} is required peer of ${provider}`,
+    });
+  }
+
+  return (
+    beforeSection !== getExpectedSection(expected, depIdent) ||
+    beforeRange !== getExpectedRange(expected, depIdent)
+  );
+}
+
+export function propagatePeers(
+  expectedByLocation: Map<string, ExpectedWorkspace>,
+  workspacesByName: Map<string, WorkspaceFacts>,
+  workspaceNames: Set<string>,
+  externalPeerMetadata: Map<string, Map<string, string> | null>,
+  rules: DependencyRule[],
+): void {
+  const rootExpected = expectedByLocation.get('.')!;
+  let changed = true;
+  let passes = 0;
+
+  while (changed && passes < 10) {
+    changed = false;
+    passes++;
+
+    for (const expected of expectedByLocation.values()) {
+      const workspace = expected.workspace;
+      const providerDeps = new Map<string, string>();
+
+      for (const [depIdent, range] of expected.sections.dependencies) {
+        providerDeps.set(depIdent, range);
+      }
+      for (const [depIdent, range] of expected.sections.peerDependencies) {
+        providerDeps.set(depIdent, range);
+      }
+      if (workspace.isRoot) {
+        for (const [depIdent, range] of expected.sections.devDependencies) {
+          providerDeps.set(depIdent, range);
+        }
+      }
+
+      for (const [providerIdent] of providerDeps) {
+        if (workspaceNames.has(providerIdent)) {
+          const provider = workspacesByName.get(providerIdent);
+          if (!provider || provider.role !== 'library') continue;
+          const providerExpected = expectedByLocation.get(provider.location);
+          if (!providerExpected) continue;
+
+          for (const [peerIdent, peerRange] of providerExpected.sections
+            .peerDependencies) {
+            if (provider.pkg.peerDependenciesMeta?.[peerIdent]?.optional) {
+              continue;
+            }
+            if (workspaceNames.has(peerIdent)) continue;
+            if (workspace.isRoot) {
+              setExpectedDependency(
+                rootExpected,
+                'devDependencies',
+                peerIdent,
+                peerRange,
+                {
+                  kind: 'peer-propagation',
+                  detail: `${peerIdent} is required by ${providerIdent}`,
+                },
+              );
+            } else {
+              changed =
+                providePeer(
+                  expected,
+                  rootExpected,
+                  workspaceNames,
+                  rules,
+                  peerIdent,
+                  peerRange,
+                  providerIdent,
+                ) || changed;
+            }
+          }
+          continue;
+        }
+
+        const externalPeers = externalPeerMetadata.get(providerIdent) ?? null;
+        if (!externalPeers) continue;
+
+        for (const [peerIdent, peerRange] of externalPeers) {
+          if (workspaceNames.has(peerIdent)) continue;
+          if (workspace.isRoot) {
+            setExpectedDependency(
+              rootExpected,
+              'devDependencies',
+              peerIdent,
+              peerRange,
+              {
+                kind: 'peer-propagation',
+                detail: `${peerIdent} is required by ${providerIdent}`,
+              },
+            );
+          } else {
+            changed =
+              providePeer(
+                expected,
+                rootExpected,
+                workspaceNames,
+                rules,
+                peerIdent,
+                peerRange,
+                providerIdent,
+              ) || changed;
+          }
+        }
+      }
+    }
+  }
+}