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

package/src/model/types.ts

@@ -0,0 +1,165 @@
+/**
+ * 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' | 'zero-external-dependencies';
+  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;
+  sourceFileCount?: number;
+}
+
+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,114 @@
+/**
+ * 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, hasWorkspaceVersionRule } 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(', ');
+      const occurrencesList = [...byOccurrence].sort().join(', ');
+      const workspaceRuleHint = hasWorkspaceVersionRule(rules, depIdent)
+        ? '; workspace-scoped version rules do not satisfy V1'
+        : '';
+
+      return {
+        code: 'unconstrained-version' as const,
+        workspace: '<root>',
+        workspaceLocation: '.',
+        dependency: depIdent,
+        message:
+          `${depIdent} appears ${byOccurrence.size} times without a global version rule (${rangeList}); occurrences: ${occurrencesList}${workspaceRuleHint}`,
+      };
+    });
+}

package/src/reporting.ts

@@ -0,0 +1,117 @@
+/**
+ * CLI-oriented dependency model reporting.
+ *
+ * The engine returns structured diagnostics and reason trails. This module
+ * turns them into stable human-readable text for `check`, `fix`, and `explain`.
+ */
+import {
+  getDeclaredRange,
+  getDeclaredSection,
+  getExpectedRange,
+  getExpectedSection,
+} from './model/expected';
+import type { DependencyModelResult } from './model/types';
+import { ansi } from './ansi';
+
+export function formatDependencyModelResult(
+  result: DependencyModelResult,
+): string {
+  const lines: string[] = [];
+
+  for (const violation of result.violations) {
+    const dep = violation.dependency ? ` ${violation.dependency}` : '';
+    const location =
+      violation.workspaceLocation === '.'
+        ? ''
+        : ` (${violation.workspaceLocation})`;
+
+    lines.push(
+      `${ansi.red('✖')} ${ansi.bold(violation.workspace)}${ansi.dim(location)}${ansi.red(dep)}: ${violation.message}`,
+    );
+  }
+
+  for (const warning of result.warnings) {
+    const workspace = warning.workspace ? `${warning.workspace}: ` : '';
+
+    lines.push(`${ansi.yellow('⚠')} ${ansi.bold(workspace)}${warning.message}`);
+  }
+
+  if (result.violations.length === 0) {
+    lines.push(`${ansi.green('✓')} ${ansi.bold('dependency model is consistent')}`);
+  } else {
+    lines.push(
+      `${ansi.red('✖')} ${ansi.bold(`${result.violations.length} dependency model violation(s)`)}`,
+    );
+  }
+
+  if (result.warnings.length > 0) {
+    lines.push(
+      `${ansi.yellow('⚠')} ${ansi.bold(`${result.warnings.length} warning(s)`)}`,
+    );
+  }
+
+  return lines.join('\n');
+}
+
+export function explainDependency(
+  result: DependencyModelResult,
+  workspaceSelector: string,
+  depIdent: string,
+): string {
+  const workspace = result.contexts.find(
+    (ctx) =>
+      ctx.name === workspaceSelector ||
+      ctx.location === workspaceSelector ||
+      (workspaceSelector === '<root>' && ctx.isRoot),
+  );
+
+  if (!workspace) {
+    return `Workspace not found: ${workspaceSelector}`;
+  }
+
+  const expected = result.expected.get(workspace.location);
+  if (!expected) {
+    return `No dependency model data for workspace: ${workspaceSelector}`;
+  }
+
+  const actualSection = getDeclaredSection(workspace.pkg, depIdent);
+  const actualRange = getDeclaredRange(workspace.pkg, depIdent);
+  const expectedSection = getExpectedSection(expected, depIdent);
+  const expectedRange = getExpectedRange(expected, depIdent);
+  const reasons = expected.reasons.get(depIdent) ?? [];
+  const lines = [
+    `${ansi.bold(workspace.name)} ${ansi.dim(`(${workspace.location})`)}`,
+    ansi.cyan(depIdent),
+    `${ansi.bold('actual:')} ${actualSection ? `${ansi.yellow(actualSection)}@${actualRange}` : ansi.dim('not declared')}`,
+    `${ansi.bold('expected:')} ${expectedSection ? `${ansi.green(expectedSection)}@${expectedRange}` : ansi.dim('not required')}`,
+  ];
+
+  if (actualSection && !expectedSection) {
+    lines.push(
+      `${ansi.bold('status:')} ${ansi.yellow('actual dependency is stale in the derived model')}`,
+    );
+  }
+
+  if (reasons.length > 0) {
+    lines.push(ansi.bold('reasons:'));
+    for (const reason of reasons) {
+      lines.push(`  - ${ansi.magenta(reason.kind)}: ${reason.detail}`);
+    }
+  }
+
+  const usage = workspace.sourceUsage.get(depIdent);
+  if (usage) {
+    lines.push(ansi.bold('source imports:'));
+    for (const file of [...usage.files].sort()) {
+      lines.push(`  - ${ansi.dim(file)}`);
+    }
+  }
+
+  if (workspace.dtsImports.has(depIdent)) {
+    lines.push(
+      `${ansi.bold('public type surface:')} ${ansi.green('appears in dist/**/*.d.ts')}`,
+    );
+  }
+
+  return lines.join('\n');
+}

package/src/runner.ts

@@ -0,0 +1,102 @@
+/**
+ * Dependency model runner.
+ *
+ * The runner coordinates impure work: locating the repo root, collecting facts,
+ * iterating external metadata discovery, invoking the pure engine, and applying
+ * manifest fixes when requested.
+ */
+import { loadConfig } from './collectors/config';
+import {
+  collectExternalMetadata,
+  collectExternalProviderIdents,
+} from './collectors/external-metadata';
+import { loadPackageExtensions } from './collectors/package-extensions';
+import { collectTypeProviderPackages } from './collectors/type-providers';
+import { loadWorkspaces } from './collectors/workspaces';
+import { findMonorepoRoot } from './lib/package-json';
+import { deriveDependencyModel } from './model/engine';
+import type {
+  DependencyModelOptions,
+  DependencyModelOutput,
+  DependencyModelResult,
+} from './model/types';
+import { writeFixes } from './writer/manifest-writer';
+
+export function runDependencyModel(
+  options: DependencyModelOptions = {},
+): DependencyModelResult {
+  const rootDir = options.rootDir ?? findMonorepoRoot(process.cwd());
+  if (!rootDir) {
+    throw new Error('Unable to find monorepo root');
+  }
+
+  const config = loadConfig(rootDir, options.constraintsPath);
+  const rules = config.rules ?? [];
+  const withDts = options.withDts === true;
+  const contexts = loadWorkspaces(rootDir, withDts);
+  const packageExtensions = loadPackageExtensions(rootDir);
+  const workspaceNames = new Set(
+    contexts.filter((ws) => !ws.isRoot).map((ws) => ws.name),
+  );
+  const typeProviderPackages = collectTypeProviderPackages(
+    rootDir,
+    contexts[0]!.pkg,
+    rules,
+  );
+  const externalPeerMetadata = new Map<string, Map<string, string> | null>();
+  const externalTypeMetadata = new Map<string, { hasBundledTypes: boolean }>();
+  const providerIdents = collectExternalProviderIdents(
+    contexts,
+    workspaceNames,
+  );
+  let output: DependencyModelOutput | null = null;
+
+  for (let pass = 0; pass < 10; pass++) {
+    collectExternalMetadata(
+      rootDir,
+      packageExtensions,
+      providerIdents,
+      externalPeerMetadata,
+      externalTypeMetadata,
+    );
+
+    output = deriveDependencyModel({
+      workspaces: contexts,
+      externalPeerMetadata,
+      externalTypeMetadata,
+      typeProviderPackages,
+      rules,
+      ...(withDts ? { withDts: true } : {}),
+    });
+
+    let changed = false;
+
+    for (const ident of collectExternalProviderIdents(
+      contexts,
+      workspaceNames,
+      output.expected,
+    )) {
+      if (providerIdents.has(ident)) continue;
+      providerIdents.add(ident);
+      changed = true;
+    }
+    if (!changed) break;
+  }
+
+  if (!output) {
+    throw new Error('Unable to derive dependency model');
+  }
+
+  if (options.fix && output.violations.length > 0) {
+    writeFixes(rootDir, output.expected);
+  }
+
+  return {
+    rootDir,
+    violations: output.violations,
+    warnings: output.warnings,
+    contexts,
+    expected: output.expected,
+    config,
+  };
+}

package/src/writer/manifest-writer.ts

@@ -0,0 +1,111 @@
+/**
+ * Manifest writer.
+ *
+ * The writer is the only module that mutates package.json files. It preserves
+ * unrelated fields, rewrites dependency sections from the expected graph, and
+ * skips writes when the normalized section content is unchanged.
+ */
+import { writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import type { PackageJson } from '../lib/package-json';
+import type { ExpectedWorkspace } from '../model/types';
+import { SECTIONS } from '../model/types';
+
+function sortedRecord(map: Map<string, string>): Record<string, string> {
+  return Object.fromEntries(
+    [...map.entries()].sort(([a], [b]) => a.localeCompare(b)),
+  );
+}
+
+function recordsEqual(
+  actual: Record<string, string> | undefined,
+  expected: Map<string, string>,
+): boolean {
+  const actualEntries = Object.entries(actual ?? {}).sort(([a], [b]) =>
+    a.localeCompare(b),
+  );
+  const expectedEntries = [...expected.entries()].sort(([a], [b]) =>
+    a.localeCompare(b),
+  );
+
+  return JSON.stringify(actualEntries) === JSON.stringify(expectedEntries);
+}
+
+function peerDependenciesMetaEqual(
+  actual: PackageJson['peerDependenciesMeta'] | undefined,
+  expected: PackageJson['peerDependenciesMeta'],
+): boolean {
+  const actualEntries = Object.entries(actual ?? {}).sort(([a], [b]) =>
+    a.localeCompare(b),
+  );
+  const expectedEntries = Object.entries(expected ?? {}).sort(([a], [b]) =>
+    a.localeCompare(b),
+  );
+
+  return JSON.stringify(actualEntries) === JSON.stringify(expectedEntries);
+}
+
+function prunePeerDependenciesMeta(
+  pkg: PackageJson,
+  expectedPeerDependencies: Map<string, string>,
+): boolean {
+  if (pkg.peerDependenciesMeta === undefined) return false;
+
+  const nextMeta = Object.fromEntries(
+    Object.entries(pkg.peerDependenciesMeta)
+      .filter(([depIdent]) => expectedPeerDependencies.has(depIdent))
+      .sort(([a], [b]) => a.localeCompare(b)),
+  );
+
+  if (Object.keys(nextMeta).length === 0) {
+    delete pkg.peerDependenciesMeta;
+    return true;
+  }
+
+  if (peerDependenciesMetaEqual(pkg.peerDependenciesMeta, nextMeta)) {
+    return false;
+  }
+
+  pkg.peerDependenciesMeta = nextMeta;
+  return true;
+}
+
+export function writeFixes(
+  rootDir: string,
+  expectedByLocation: Map<string, ExpectedWorkspace>,
+): void {
+  for (const expected of expectedByLocation.values()) {
+    const pkg = expected.workspace.pkg;
+    let changed = false;
+
+    for (const section of SECTIONS) {
+      if (expected.sections[section].size === 0) {
+        if (pkg[section] !== undefined) {
+          delete pkg[section];
+          changed = true;
+        }
+        continue;
+      }
+
+      if (!recordsEqual(pkg[section], expected.sections[section])) {
+        pkg[section] = sortedRecord(expected.sections[section]);
+        changed = true;
+      }
+    }
+
+    changed =
+      prunePeerDependenciesMeta(pkg, expected.sections.peerDependencies) ||
+      changed;
+
+    if (changed) {
+      const pkgPath = path.join(
+        rootDir,
+        expected.workspace.location,
+        'package.json',
+      );
+
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    }
+  }
+}

package/tsconfig.build.json

@@ -4,6 +4,7 @@
     "node_modules",
     "dist",
     "test",
+    "__tests__",
     "**/*.spec.ts",
     "**/*.test.ts",
     "**/*.test.e2e.ts",

package/tsconfig.json

@@ -3,5 +3,10 @@
   "compilerOptions": {
     "declaration": true,
     "outDir": "dist"
-  }
+  },
+  "exclude": [
+    "node_modules",
+    "dist",
+    "__tests__/fixtures"
+  ]
 }

package/dist/constraint-schema.d.ts

@@ -1 +0,0 @@
-export declare const ConstraintSchema: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>, import("@sinclair/typebox").TString]>>;

package/dist/constraint-schema.js

@@ -1,17 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConstraintSchema = void 0;
-const typebox_1 = require("@sinclair/typebox");
-exports.ConstraintSchema = typebox_1.Type.Record(typebox_1.Type.String({
-    description: 'scope or package name',
-}), typebox_1.Type.Union([
-    typebox_1.Type.Record(typebox_1.Type.String({
-        description: 'scope package name',
-    }), typebox_1.Type.String({
-        description: 'scope package version',
-    })),
-    typebox_1.Type.String({
-        description: 'package version',
-    }),
-]));
-//# sourceMappingURL=constraint-schema.js.map

package/dist/constraint-schema.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"constraint-schema.js","sourceRoot":"","sources":["../src/constraint-schema.ts"],"names":[],"mappings":";;;AAAA,+CAAyC;AAE5B,QAAA,gBAAgB,GAAG,cAAI,CAAC,MAAM,CACzC,cAAI,CAAC,MAAM,CAAC;IACV,WAAW,EAAE,uBAAuB;CACrC,CAAC,EACF,cAAI,CAAC,KAAK,CAAC;IACT,cAAI,CAAC,MAAM,CACT,cAAI,CAAC,MAAM,CAAC;QACV,WAAW,EAAE,oBAAoB;KAClC,CAAC,EACF,cAAI,CAAC,MAAM,CAAC;QACV,WAAW,EAAE,uBAAuB;KACrC,CAAC,CACH;IACD,cAAI,CAAC,MAAM,CAAC;QACV,WAAW,EAAE,iBAAiB;KAC/B,CAAC;CACH,CAAC,CACH,CAAC"}

package/dist/dependency-checker.d.ts

@@ -1,8 +0,0 @@
-import type { Static } from '@sinclair/typebox';
-import type { Constraints } from '@yarnpkg/types/lib/yarn';
-import type { ConstraintSchema } from './constraint-schema';
-export declare class DependencyChecker {
-    private readonly yarn;
-    constructor(yarn: Constraints.Yarn);
-    enforceConsistentDependenciesAcrossTheProject(constraints: Static<typeof ConstraintSchema>, part?: string): void;
-}