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

package/src/lib/imports.ts

@@ -0,0 +1,293 @@
+/**
+ * TypeScript/JavaScript import collectors.
+ *
+ * These helpers parse source and emitted declaration files into package-level
+ * import facts. They do not decide dependency placement; they only normalize
+ * specifiers and classify imports as runtime or type-only.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { builtinModules } from 'node:module';
+import path from 'node:path';
+import ts = require('typescript');
+
+import type { PackageJson } from './package-json';
+
+export interface ImportEntry {
+  packageName: string;
+  isTypeOnly: boolean;
+  file: string;
+}
+
+const BUILTINS = new Set([
+  ...builtinModules,
+  ...builtinModules.map((m) => `node:${m}`),
+]);
+
+const SOURCE_EXTENSIONS = new Set([
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.cts',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.cjs',
+]);
+
+const DTS_RE = /\.d\.(?:c|m)?ts$/;
+
+export function getPackageName(specifier: string): string | null {
+  if (
+    specifier.startsWith('.') ||
+    specifier.startsWith('/') ||
+    specifier.includes('*')
+  )
+    return null;
+  if (BUILTINS.has(specifier) || specifier.startsWith('node:')) return null;
+  if (specifier.startsWith('@')) {
+    const scopeSlash = specifier.indexOf('/', 1);
+    if (scopeSlash === -1) return null;
+    const subpathSlash = specifier.indexOf('/', scopeSlash + 1);
+
+    return subpathSlash === -1 ? specifier : specifier.slice(0, subpathSlash);
+  }
+  const slash = specifier.indexOf('/');
+
+  return slash === -1 ? specifier : specifier.slice(0, slash);
+}
+
+function walkFiles(dir: string, filter: (name: string) => boolean): string[] {
+  const results: string[] = [];
+
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory() && entry.name !== 'node_modules') {
+        results.push(...walkFiles(full, filter));
+      } else if (entry.isFile() && filter(entry.name)) {
+        results.push(full);
+      }
+    }
+  } catch {
+    // dir doesn't exist - return empty
+  }
+  return results;
+}
+
+function isSourceFile(name: string): boolean {
+  return SOURCE_EXTENSIONS.has(path.extname(name)) && !DTS_RE.test(name);
+}
+
+function getScriptKind(file: string): ts.ScriptKind {
+  if (file.endsWith('.tsx')) return ts.ScriptKind.TSX;
+  if (file.endsWith('.jsx')) return ts.ScriptKind.JSX;
+  if (
+    file.endsWith('.js') ||
+    file.endsWith('.mjs') ||
+    file.endsWith('.cjs')
+  )
+    return ts.ScriptKind.JS;
+  return ts.ScriptKind.TS;
+}
+
+function stringLiteralText(node: ts.Node | undefined): string | null {
+  return node && ts.isStringLiteralLike(node) ? node.text : null;
+}
+
+function addImport(
+  results: ImportEntry[],
+  file: string,
+  specifier: string,
+  isTypeOnly: boolean,
+): void {
+  const packageName = getPackageName(specifier);
+  if (!packageName) return;
+  results.push({ packageName, isTypeOnly, file });
+}
+
+function isImportDeclarationTypeOnly(node: ts.ImportDeclaration): boolean {
+  const clause = node.importClause;
+  if (!clause) return false;
+  if (clause.isTypeOnly) return true;
+  if (clause.name) return false;
+  if (!clause.namedBindings) return true;
+  if (ts.isNamespaceImport(clause.namedBindings)) return false;
+
+  return (
+    clause.namedBindings.elements.length > 0 &&
+    clause.namedBindings.elements.every((element) => element.isTypeOnly)
+  );
+}
+
+function isExportDeclarationTypeOnly(node: ts.ExportDeclaration): boolean {
+  if (node.isTypeOnly) return true;
+  const clause = node.exportClause;
+  if (!clause || !ts.isNamedExports(clause)) return false;
+
+  return (
+    clause.elements.length > 0 &&
+    clause.elements.every((element) => element.isTypeOnly)
+  );
+}
+
+function collectExternalModuleReference(
+  node: ts.ExternalModuleReference,
+): string | null {
+  return stringLiteralText(node.expression);
+}
+
+function extractImports(
+  file: string,
+  content: string,
+  options: { includeDtsForms?: boolean } = {},
+): ImportEntry[] {
+  const results: ImportEntry[] = [];
+  const sourceFile = ts.createSourceFile(
+    file,
+    content,
+    ts.ScriptTarget.Latest,
+    true,
+    getScriptKind(file),
+  );
+
+  if (options.includeDtsForms) {
+    for (const reference of sourceFile.typeReferenceDirectives) {
+      addImport(results, file, reference.fileName, true);
+    }
+  }
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isImportDeclaration(node)) {
+      const specifier = stringLiteralText(node.moduleSpecifier);
+      if (specifier) {
+        addImport(results, file, specifier, isImportDeclarationTypeOnly(node));
+      }
+    } else if (ts.isExportDeclaration(node)) {
+      const specifier = stringLiteralText(node.moduleSpecifier);
+      if (specifier) {
+        addImport(results, file, specifier, isExportDeclarationTypeOnly(node));
+      }
+    } else if (ts.isImportEqualsDeclaration(node)) {
+      if (ts.isExternalModuleReference(node.moduleReference)) {
+        const specifier = collectExternalModuleReference(node.moduleReference);
+        if (specifier) addImport(results, file, specifier, node.isTypeOnly);
+      }
+    } else if (ts.isCallExpression(node)) {
+      if (
+        node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+        node.arguments.length === 1
+      ) {
+        const specifier = stringLiteralText(node.arguments[0]);
+        if (specifier) addImport(results, file, specifier, false);
+      } else if (
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === 'require' &&
+        node.arguments.length === 1
+      ) {
+        const specifier = stringLiteralText(node.arguments[0]);
+        if (specifier) addImport(results, file, specifier, false);
+      }
+    } else if (ts.isImportTypeNode(node)) {
+      const argument = node.argument;
+      if (ts.isLiteralTypeNode(argument)) {
+        const specifier = stringLiteralText(argument.literal);
+        if (specifier) addImport(results, file, specifier, true);
+      }
+    } else if (
+      options.includeDtsForms &&
+      ts.isModuleDeclaration(node) &&
+      ts.isStringLiteral(node.name)
+    ) {
+      addImport(results, file, node.name.text, true);
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+  return results;
+}
+
+function collectEntrypointStrings(value: unknown, result: Set<string>): void {
+  if (typeof value === 'string') {
+    result.add(value);
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+  if (Array.isArray(value)) {
+    for (const item of value) collectEntrypointStrings(item, result);
+    return;
+  }
+  for (const item of Object.values(value as Record<string, unknown>)) {
+    collectEntrypointStrings(item, result);
+  }
+}
+
+function getPackageEntrypointFiles(
+  workspaceDir: string,
+  pkg: PackageJson,
+): string[] {
+  const candidates = new Set<string>();
+  if (pkg.main) candidates.add(pkg.main);
+  if (typeof pkg.bin === 'string') {
+    candidates.add(pkg.bin);
+  } else if (pkg.bin) {
+    for (const value of Object.values(pkg.bin)) candidates.add(value);
+  }
+  collectEntrypointStrings(pkg.exports, candidates);
+
+  const result = new Set<string>();
+
+  for (const candidate of candidates) {
+    if (!candidate || candidate.includes('*')) continue;
+    const full = path.resolve(workspaceDir, candidate);
+    const relative = path.relative(workspaceDir, full);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) continue;
+    if (!existsSync(full) || !isSourceFile(full)) continue;
+
+    const normalized = relative.split(path.sep).join('/');
+    const isSrc = normalized.startsWith('src/');
+    const isRoot = !normalized.includes('/');
+    if (isSrc || isRoot) result.add(full);
+  }
+
+  return [...result];
+}
+
+export function collectSourceImports(
+  srcDirOrWorkspaceDir: string,
+  pkg?: PackageJson,
+): ImportEntry[] {
+  const srcDir = pkg
+    ? path.join(srcDirOrWorkspaceDir, 'src')
+    : srcDirOrWorkspaceDir;
+  const files = new Set(
+    walkFiles(srcDir, (name) => isSourceFile(name)),
+  );
+
+  if (pkg) {
+    for (const file of getPackageEntrypointFiles(srcDirOrWorkspaceDir, pkg)) {
+      files.add(file);
+    }
+  }
+
+  return [...files].flatMap((file) =>
+    extractImports(file, readFileSync(file, 'utf8')),
+  );
+}
+
+export function collectDtsImports(distDir: string): Set<string> {
+  const files = walkFiles(distDir, (name) => DTS_RE.test(name));
+  const result = new Set<string>();
+
+  for (const file of files) {
+    for (const { packageName } of extractImports(
+      file,
+      readFileSync(file, 'utf8'),
+      { includeDtsForms: true },
+    )) {
+      result.add(packageName);
+    }
+  }
+  return result;
+}

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/diagnostics.ts

@@ -0,0 +1,328 @@
+/**
+ * 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] ?? {})),
+  );
+}
+
+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.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;
+}