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

package/src/bin/depdoc.ts

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * `depdoc` command-line entrypoint.
+ *
+ * The CLI only parses commands and orchestrates high-level steps. Dependency
+ * placement decisions live in the model engine, while filesystem collection and
+ * manifest writes go through the runner.
+ */
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { ansi } from '../ansi';
+import {
+  explainDependency,
+  formatDependencyModelResult,
+  runDependencyModel,
+} from '../dependency-model';
+
+function printUsage(): void {
+  console.error(`${ansi.bold('Usage:')}
+  ${ansi.cyan('depdoc')} check [--with-dts]
+  ${ansi.cyan('depdoc')} fix [--with-dts]
+  ${ansi.cyan('depdoc')} explain <workspace> <dependency>
+  ${ansi.cyan('depdoc')} doctor`);
+}
+
+function spawnStep(label: string, cmd: string, cwd: string): void {
+  console.error(`\n${ansi.cyan('──')} ${ansi.bold(label)}`);
+  console.error(`${ansi.dim('$')} ${ansi.cyan(cmd)}`);
+  execSync(cmd, { cwd, stdio: 'inherit' });
+}
+
+function checkPeerRequirements(cwd: string): boolean {
+  const cmd = 'yarn explain peer-requirements';
+
+  console.error(`\n${ansi.cyan('──')} ${ansi.bold('yarn peer requirements')}`);
+  console.error(`${ansi.dim('$')} ${ansi.cyan(cmd)}`);
+
+  let output: string;
+
+  try {
+    output = execSync(cmd, {
+      cwd,
+      encoding: 'utf8',
+      maxBuffer: 32 * 1024 * 1024,
+    });
+  } catch (error) {
+    const childError = error as { stdout?: string; stderr?: string };
+    if (childError.stdout) process.stderr.write(childError.stdout);
+    if (childError.stderr) process.stderr.write(childError.stderr);
+    return false;
+  }
+
+  const failedRequirements = output
+    .split(/\r?\n/)
+    .filter((line) => line.includes('✘'));
+
+  if (failedRequirements.length === 0) {
+    console.error(ansi.green('✓ peer requirements are satisfied'));
+    return true;
+  }
+
+  console.error(failedRequirements.join('\n'));
+  console.error(
+    ansi.red(`${failedRequirements.length} peer requirement(s) failed`),
+  );
+  console.error(
+    ansi.dim('Run `yarn explain peer-requirements <hash>` for details.'),
+  );
+  return false;
+}
+
+function snapshotPackageJsons(
+  result: ReturnType<typeof runDependencyModel>,
+): string {
+  return [...result.expected.keys()]
+    .sort()
+    .map((location) =>
+      readFileSync(path.join(result.rootDir, location, 'package.json'), 'utf8'),
+    )
+    .join('\0');
+}
+
+function main(): void {
+  const rawArgs = process.argv.slice(2);
+  if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
+    printUsage();
+    process.exit(0);
+  }
+
+  const positional = rawArgs.filter((a) => !a.startsWith('--'));
+  const [command, firstArg, secondArg] = positional;
+  const withDts = rawArgs.includes('--with-dts');
+
+  if (!command) {
+    printUsage();
+    process.exit(1);
+  }
+
+  if (command === 'check') {
+    const result = runDependencyModel({ withDts });
+
+    console.error(formatDependencyModelResult(result));
+    process.exit(result.violations.length === 0 ? 0 : 1);
+  }
+
+  if (command === 'fix') {
+    const before = runDependencyModel({ fix: true, withDts });
+    const after = runDependencyModel({ withDts });
+    const fixed = Math.max(
+      0,
+      before.violations.length - after.violations.length,
+    );
+
+    console.error(formatDependencyModelResult(after));
+    if (fixed > 0) {
+      console.error(
+        ansi.green(`fixed ${fixed} dependency model violation(s)`),
+      );
+    }
+    process.exit(after.violations.length === 0 ? 0 : 1);
+  }
+
+  if (command === 'explain') {
+    if (!firstArg || !secondArg) {
+      printUsage();
+      process.exit(1);
+    }
+    const result = runDependencyModel();
+
+    console.log(explainDependency(result, firstArg, secondArg));
+    process.exit(0);
+  }
+
+  if (command === 'doctor') {
+    runDoctor();
+    return;
+  }
+
+  printUsage();
+  process.exit(1);
+}
+
+function runDoctor(): void {
+  console.error(`\n${ansi.cyan('──')} ${ansi.bold('depdoc fix')}`);
+  const fixResult = runDependencyModel({ fix: true });
+  const afterFix = runDependencyModel();
+  const fixed = Math.max(
+    0,
+    fixResult.violations.length - afterFix.violations.length,
+  );
+
+  console.error(formatDependencyModelResult(afterFix));
+  if (fixed > 0) console.error(ansi.green(`fixed ${fixed} violation(s)`));
+
+  const { rootDir, config } = afterFix;
+
+  spawnStep('yarn install', 'yarn install', rootDir);
+
+  if (config.doctor?.buildCmd) {
+    spawnStep('build', config.doctor.buildCmd, rootDir);
+  } else {
+    console.error(
+      `\n${ansi.cyan('──')} ${ansi.yellow('build skipped')} ${ansi.dim('(doctor.buildCmd not configured in .constraints.yml)')}`,
+    );
+  }
+
+  const beforeDtsFixSnapshot = snapshotPackageJsons(afterFix);
+
+  console.error(`\n${ansi.cyan('──')} ${ansi.bold('depdoc fix --with-dts')}`);
+  const dtsFix = runDependencyModel({ fix: true, withDts: true });
+  const afterDtsFix = runDependencyModel({ withDts: true });
+  const afterDtsFixSnapshot = snapshotPackageJsons(afterDtsFix);
+  const dtsFixed = Math.max(
+    0,
+    dtsFix.violations.length - afterDtsFix.violations.length,
+  );
+
+  console.error(formatDependencyModelResult(afterDtsFix));
+  if (dtsFixed > 0) {
+    console.error(
+      ansi.green(
+        `fixed ${dtsFixed} additional violation(s) from .d.ts surface`,
+      ),
+    );
+  }
+
+  if (beforeDtsFixSnapshot !== afterDtsFixSnapshot) {
+    spawnStep('yarn install (post-dts-fix)', 'yarn install', rootDir);
+  }
+
+  if (!checkPeerRequirements(rootDir)) process.exit(1);
+
+  if (config.doctor?.lintCmd) {
+    spawnStep('lint', config.doctor.lintCmd, rootDir);
+  }
+
+  if (config.doctor?.typecheckCmd) {
+    spawnStep('typecheck', config.doctor.typecheckCmd, rootDir);
+  }
+
+  const finalViolations = afterDtsFix.violations.length;
+
+  console.error(
+    finalViolations === 0
+      ? `\n${ansi.green('✓')} ${ansi.bold('doctor: all checks passed')}`
+      : `\n${ansi.red('✖')} ${ansi.bold(`doctor: ${finalViolations} violation(s) remain`)}`,
+  );
+  process.exit(finalViolations === 0 ? 0 : 1);
+}
+
+main();

package/src/collectors/config.ts

@@ -0,0 +1,26 @@
+/**
+ * Constraints configuration collector.
+ *
+ * This module is the only place that resolves and parses `.constraints.yml`.
+ * It returns raw model configuration; rule semantics are handled later by the
+ * pure model layer.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import yaml from 'yaml';
+
+import type { DependencyModelConfig } from '../model/types';
+
+export function loadConfig(
+  rootDir: string,
+  constraintsPath?: string,
+): DependencyModelConfig {
+  const filepath =
+    constraintsPath ??
+    process.env.RSDK_YARN_CONSTRAINTS_CFG ??
+    path.join(rootDir, '.rsdk/.constraints.yml');
+
+  if (!existsSync(filepath)) return { rules: [] };
+
+  return yaml.parse(readFileSync(filepath, 'utf8')) as DependencyModelConfig;
+}

package/src/collectors/external-metadata.ts

@@ -0,0 +1,148 @@
+/**
+ * Installed external package metadata collector.
+ *
+ * Peer and bundled-type metadata are read from installed packages and Yarn
+ * packageExtensions. The engine consumes the resulting maps as facts, keeping
+ * node_modules access outside the pure model.
+ */
+import path from 'node:path';
+
+import { readPackageJson } from '../lib/package-json';
+import type {
+  ExpectedWorkspace,
+  PackageExtension,
+  WorkspaceContext,
+} from '../model/types';
+import { SECTIONS } from '../model/types';
+
+import { getMatchingPackageExtensions } from './package-extensions';
+
+const externalPeersCache = new Map<string, Map<string, string> | null>();
+
+function getExternalRequiredPeers(
+  rootDir: string,
+  packageExtensions: Map<string, PackageExtension>,
+  extIdent: string,
+): Map<string, string> | null {
+  const cacheKey = `${rootDir}:${extIdent}`;
+  if (externalPeersCache.has(cacheKey))
+    return externalPeersCache.get(cacheKey)!;
+
+  let peers: Record<string, string>;
+  let meta: Record<string, { optional?: boolean }>;
+
+  try {
+    const pkg = readPackageJson(path.join(rootDir, 'node_modules', extIdent));
+
+    peers = { ...pkg.peerDependencies };
+    meta = { ...pkg.peerDependenciesMeta };
+  } catch {
+    peers = {};
+    meta = {};
+  }
+
+  for (const extension of getMatchingPackageExtensions(
+    extIdent,
+    packageExtensions,
+  )) {
+    peers = { ...peers, ...extension.peerDependencies };
+    meta = { ...meta, ...extension.peerDependenciesMeta };
+  }
+
+  const required = new Map(
+    Object.entries(peers).filter(([ident]) => !meta[ident]?.optional),
+  );
+  const value = required.size > 0 ? required : null;
+
+  externalPeersCache.set(cacheKey, value);
+
+  return value;
+}
+
+function exportsDeclareTypes(value: unknown): boolean {
+  if (!value || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return value.some(exportsDeclareTypes);
+
+  for (const [key, nested] of Object.entries(
+    value as Record<string, unknown>,
+  )) {
+    if ((key === 'types' || key === 'typings') && typeof nested === 'string') {
+      return true;
+    }
+    if (exportsDeclareTypes(nested)) return true;
+  }
+
+  return false;
+}
+
+function getExternalTypeMetadata(
+  rootDir: string,
+  extIdent: string,
+): { hasBundledTypes: boolean } {
+  try {
+    const pkg = readPackageJson(path.join(rootDir, 'node_modules', extIdent));
+
+    return {
+      hasBundledTypes:
+        typeof pkg.types === 'string' ||
+        typeof pkg.typings === 'string' ||
+        exportsDeclareTypes(pkg.exports),
+    };
+  } catch {
+    return { hasBundledTypes: false };
+  }
+}
+
+export function collectExternalProviderIdents(
+  contexts: WorkspaceContext[],
+  workspaceNames: Set<string>,
+  expectedByLocation?: Map<string, ExpectedWorkspace>,
+): Set<string> {
+  const result = new Set<string>();
+  const add = (depIdent: string, range?: string): void => {
+    if (workspaceNames.has(depIdent) || range?.startsWith('workspace:')) return;
+    result.add(depIdent);
+  };
+
+  for (const ctx of contexts) {
+    for (const section of SECTIONS) {
+      for (const [depIdent, range] of Object.entries(ctx.pkg[section] ?? {})) {
+        add(depIdent, range);
+      }
+    }
+    for (const depIdent of ctx.sourceUsage.keys()) add(depIdent);
+    for (const depIdent of ctx.dtsImports) add(depIdent);
+  }
+
+  if (expectedByLocation) {
+    for (const expected of expectedByLocation.values()) {
+      for (const section of SECTIONS) {
+        for (const [depIdent, range] of expected.sections[section]) {
+          add(depIdent, range);
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+export function collectExternalMetadata(
+  rootDir: string,
+  packageExtensions: Map<string, PackageExtension>,
+  idents: Set<string>,
+  externalPeerMetadata: Map<string, Map<string, string> | null>,
+  externalTypeMetadata: Map<string, { hasBundledTypes: boolean }>,
+): void {
+  for (const ident of idents) {
+    if (!externalPeerMetadata.has(ident)) {
+      externalPeerMetadata.set(
+        ident,
+        getExternalRequiredPeers(rootDir, packageExtensions, ident),
+      );
+    }
+    if (!externalTypeMetadata.has(ident)) {
+      externalTypeMetadata.set(ident, getExternalTypeMetadata(rootDir, ident));
+    }
+  }
+}

package/src/collectors/package-extensions.ts

@@ -0,0 +1,52 @@
+/**
+ * Yarn packageExtensions collector.
+ *
+ * Third-party peer metadata corrections are read from `.yarnrc.yml` here. The
+ * model receives these corrections as facts and does not parse Yarn config
+ * directly.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import yaml from 'yaml';
+
+import type { PackageExtension } from '../model/types';
+
+export function loadPackageExtensions(
+  rootDir: string,
+): Map<string, PackageExtension> {
+  const filepath = path.join(rootDir, '.yarnrc.yml');
+  if (!existsSync(filepath)) return new Map();
+
+  const parsed = yaml.parse(readFileSync(filepath, 'utf8')) as {
+    packageExtensions?: Record<string, PackageExtension>;
+  };
+  const result = new Map<string, PackageExtension>();
+
+  for (const [selector, extension] of Object.entries(
+    parsed.packageExtensions ?? {},
+  )) {
+    result.set(selector, extension);
+  }
+
+  return result;
+}
+
+function extensionSelectorIdent(selector: string): string {
+  const atIndex = selector.lastIndexOf('@');
+  if (atIndex <= 0) return selector;
+
+  return selector.slice(0, atIndex);
+}
+
+export function getMatchingPackageExtensions(
+  depIdent: string,
+  packageExtensions: Map<string, PackageExtension>,
+): PackageExtension[] {
+  const result: PackageExtension[] = [];
+
+  for (const [selector, extension] of packageExtensions) {
+    if (extensionSelectorIdent(selector) === depIdent) result.push(extension);
+  }
+
+  return result;
+}

package/src/collectors/type-providers.ts

@@ -0,0 +1,51 @@
+/**
+ * DefinitelyTyped provider collector.
+ *
+ * The engine needs to know which `@types/*` packages are available for public
+ * `.d.ts` promotion. This module gathers that set from installed packages, root
+ * devDependencies, and explicit non-wildcard rules.
+ */
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+
+import type { PackageJson } from '../lib/package-json';
+import type { DependencyRule } from '../model/types';
+
+function collectInstalledTypeProviders(rootDir: string): Set<string> {
+  const result = new Set<string>();
+  const typesDir = path.join(rootDir, 'node_modules', '@types');
+
+  try {
+    for (const entry of readdirSync(typesDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) result.add(`@types/${entry.name}`);
+    }
+  } catch {
+    // node_modules may not exist yet; root devDeps and rules still contribute.
+  }
+
+  return result;
+}
+
+export function collectTypeProviderPackages(
+  rootDir: string,
+  rootPkg: PackageJson,
+  rules: DependencyRule[],
+): Set<string> {
+  const result = collectInstalledTypeProviders(rootDir);
+
+  for (const depIdent of Object.keys(rootPkg.devDependencies ?? {})) {
+    if (depIdent.startsWith('@types/')) result.add(depIdent);
+  }
+
+  for (const rule of rules) {
+    const patterns = Array.isArray(rule.match) ? rule.match : [rule.match];
+
+    for (const pattern of patterns) {
+      if (pattern.startsWith('@types/') && !pattern.includes('*')) {
+        result.add(pattern);
+      }
+    }
+  }
+
+  return result;
+}

package/src/collectors/workspaces.ts

@@ -0,0 +1,99 @@
+/**
+ * Workspace and usage collector.
+ *
+ * This module discovers Yarn workspaces, reads their manifests, and attaches
+ * source/`.d.ts` import usage facts. It is deliberately outside the engine
+ * because it executes Yarn and reads the filesystem.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+import { collectDtsImports, collectSourceImports } from '../lib/imports';
+import { readPackageJson } from '../lib/package-json';
+import { isWorkspaceRole } from '../model/rules';
+import type { WorkspaceContext } from '../model/types';
+
+interface YarnWorkspaceInfo {
+  location: string;
+  name: string | null;
+}
+
+function collectUsage(workspace: WorkspaceContext, withDts: boolean): void {
+  for (const entry of collectSourceImports(workspace.dir, workspace.pkg)) {
+    if (!workspace.sourceUsage.has(entry.packageName)) {
+      workspace.sourceUsage.set(entry.packageName, {
+        files: new Set(),
+        runtimeFiles: new Set(),
+        typeOnlyFiles: new Set(),
+      });
+    }
+    const usage = workspace.sourceUsage.get(entry.packageName)!;
+
+    usage.files.add(entry.file);
+    if (entry.isTypeOnly) {
+      usage.typeOnlyFiles.add(entry.file);
+    } else {
+      usage.runtimeFiles.add(entry.file);
+    }
+  }
+
+  const distDir = path.join(workspace.dir, 'dist');
+  if (withDts || existsSync(distDir)) {
+    workspace.dtsImports = collectDtsImports(distDir);
+  }
+}
+
+export function loadWorkspaces(
+  rootDir: string,
+  withDts: boolean,
+): WorkspaceContext[] {
+  const rootPkg = readPackageJson(rootDir);
+  const raw = execSync('yarn workspaces list --json', {
+    cwd: rootDir,
+  }).toString();
+  const listed = raw
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line) as YarnWorkspaceInfo)
+    .filter((ws) => ws.location !== '.');
+
+  const root: WorkspaceContext = {
+    name: rootPkg.name,
+    location: '.',
+    dir: rootDir,
+    pkg: rootPkg,
+    role: undefined,
+    isRoot: true,
+    sourceUsage: new Map(),
+    dtsImports: new Set(),
+    hasSrc: false,
+    hasDist: false,
+  };
+
+  const workspaces: WorkspaceContext[] = [root];
+
+  for (const ws of listed) {
+    const dir = path.join(rootDir, ws.location);
+    const pkg = readPackageJson(dir);
+    const role = isWorkspaceRole(pkg.role) ? pkg.role : undefined;
+    const ctx: WorkspaceContext = {
+      name: ws.name ?? pkg.name,
+      location: ws.location,
+      dir,
+      pkg,
+      role,
+      isRoot: false,
+      sourceUsage: new Map(),
+      dtsImports: new Set(),
+      hasSrc: existsSync(path.join(dir, 'src')),
+      hasDist: existsSync(path.join(dir, 'dist')),
+    };
+
+    collectUsage(ctx, withDts);
+    workspaces.push(ctx);
+  }
+
+  return workspaces;
+}

package/src/dependency-model.ts

@@ -0,0 +1,26 @@
+/**
+ * Public dependency-model facade.
+ *
+ * Historically this file contained the whole implementation. It now keeps the
+ * public import path stable while delegating to focused modules: the pure model
+ * engine, the filesystem/Yarn runner, and CLI reporting helpers.
+ */
+export { deriveDependencyModel } from './model/engine';
+export { runDependencyModel } from './runner';
+export { explainDependency, formatDependencyModelResult } from './reporting';
+
+export type {
+  DependencyModelConfig,
+  DependencyModelFacts,
+  DependencyModelOptions,
+  DependencyModelOutput,
+  DependencyModelResult,
+  DependencyRule,
+  DependencyViolation,
+  DependencyWarning,
+  ExpectedWorkspace,
+  SectionType,
+  UsageSummary,
+  WorkspaceFacts,
+  WorkspaceRole,
+} from './model/types';

package/src/index.ts

@@ -1,46 +1,29 @@
-import { Value } from '@sinclair/typebox/value';
-import type { Yarn } from '@yarnpkg/types';
-import type { Constraints } from '@yarnpkg/types/lib/yarn';
-import { access, constants, readFile } from 'node:fs/promises';
-import yaml from 'yaml';
+/**
+ * Package public API.
+ *
+ * Consumers should import from this barrel instead of reaching into the model,
+ * runner, or collector internals. The split modules remain implementation
+ * details unless explicitly exported here.
+ */
+export {
+  deriveDependencyModel,
+  runDependencyModel,
+  formatDependencyModelResult,
+  explainDependency,
+} from './dependency-model';
 
-import { ConstraintSchema } from './constraint-schema';
-import { DependencyChecker } from './dependency-checker';
-
-const constraintsManifestPath =
-  process.env.RSDK_YARN_CONSTRAINTS_CFG ?? './.rsdk/.constraints.yml';
-
-export const createConstraints =
-  (overrideConfig?: Yarn.Config) =>
-  async (ctx: Constraints.Context): Promise<void> => {
-    const { Yarn } = ctx;
-
-    await access(constraintsManifestPath, constants.R_OK);
-    const constraints = yaml.parse(
-      await readFile(constraintsManifestPath, 'utf8'),
-    );
-    const isValid = Value.Check(ConstraintSchema, constraints);
-    if (!isValid) {
-      const cause = [...Value.Errors(ConstraintSchema, constraints)];
-
-      throw new Error(
-        'Invalid constraints.yml\n' + JSON.stringify(cause, null, 2),
-        {
-          cause: cause,
-        },
-      );
-    }
-    new DependencyChecker(Yarn).enforceConsistentDependenciesAcrossTheProject(
-      constraints,
-    );
-    overrideConfig?.constraints?.(ctx);
-  };
-
-export const config: Yarn.Config = {
-  constraints: createConstraints(),
-};
-
-export const override = (config: Yarn.Config): Yarn.Config => ({
-  ...config,
-  constraints: createConstraints(config),
-});
+export type {
+  DependencyRule,
+  DependencyModelConfig,
+  DependencyModelOptions,
+  DependencyModelFacts,
+  DependencyModelOutput,
+  DependencyModelResult,
+  DependencyViolation,
+  DependencyWarning,
+  WorkspaceFacts,
+  WorkspaceRole,
+  SectionType,
+  UsageSummary,
+  ExpectedWorkspace,
+} from './dependency-model';