@ariestools/toolchain 8.7.4 → 8.7.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/bin/xy.mjs CHANGED
@@ -23097,6 +23097,10 @@ function isTerminalPackage$1(location) {
23097
23097
  }
23098
23098
  //#endregion
23099
23099
  //#region src/actions/deplint/checkPackage/getUnsatisfiedPeerDependencies.ts
23100
+ /** True when the policy (if any) obliges this package to forward `peer`. */
23101
+ function isPeerForwarded(policy, peer) {
23102
+ return policy === void 0 || policy.mode === "always" || policy.importedModules.has(peer);
23103
+ }
23100
23104
  function readDepPackageJson(location, dep) {
23101
23105
  const depPkgPath = findDepPackageJson(location, dep);
23102
23106
  if (depPkgPath == null || depPkgPath.length === 0) return void 0;
@@ -23278,21 +23282,39 @@ function findDeclaredPeerVersionMismatches(name, location, peerDependencies, pee
23278
23282
  }
23279
23283
  return results;
23280
23284
  }
23281
- function classifyPeer(peer, sources, ctx) {
23282
- const { location, depsSet, devDepsSet, peerDepsSet, isTerminal, forceDevs, forcePeerOptional } = ctx;
23283
- if (forceDevs.has(peer)) return void 0;
23285
+ /**
23286
+ * Resolves how the peer's runtime contract binds this package. An explicit
23287
+ * `peerOptional` override vouches for the contract; otherwise
23288
+ * `peerForwarding: 'when-used'` demotes never-imported chain peers to a
23289
+ * local dev need (installers resolve the consumer-side contract).
23290
+ */
23291
+ function resolveRuntimeContract(peer, sources, ctx) {
23292
+ const { location, forcePeerOptional, forwarding } = ctx;
23284
23293
  const isPeerForced = forcePeerOptional?.has(peer) ?? false;
23294
+ const isForwarded = isPeerForced || isPeerForwarded(forwarding, peer);
23285
23295
  const runtimeSources = sources.filter((s) => s.isRuntimeDep);
23286
- const hasRuntimeSource = runtimeSources.length > 0 && (isPeerForced || !isPeerOptionalInAll(location, peer, runtimeSources));
23296
+ const hasRuntimeContract = runtimeSources.length > 0 && (isPeerForced || !isPeerOptionalInAll(location, peer, runtimeSources));
23297
+ const directRuntimeSources = sources.filter((s) => s.isRuntimeDep && !s.chain);
23298
+ const shouldForwardRuntime = directRuntimeSources.length > 0 && isForwarded && (isPeerForced || !isPeerOptionalInAll(location, peer, directRuntimeSources));
23299
+ return {
23300
+ hasRuntimeSource: hasRuntimeContract && isForwarded,
23301
+ isInherited: hasRuntimeContract && !isForwarded,
23302
+ shouldForwardRuntime
23303
+ };
23304
+ }
23305
+ function classifyPeer(peer, sources, ctx) {
23306
+ const { location, depsSet, devDepsSet, peerDepsSet, isTerminal, forceDevs } = ctx;
23307
+ if (forceDevs.has(peer)) return void 0;
23308
+ const { hasRuntimeSource, isInherited, shouldForwardRuntime } = resolveRuntimeContract(peer, sources, ctx);
23287
23309
  if (!depsSet.has(peer) && !devDepsSet.has(peer)) return {
23288
23310
  hasRuntimeSource,
23311
+ ...isInherited && { inherited: true },
23289
23312
  peer,
23290
23313
  reason: "missing",
23291
23314
  sources,
23292
23315
  versionRange: resolveVersionRange(location, sources, peer)
23293
23316
  };
23294
- const directRuntimeSources = sources.filter((s) => s.isRuntimeDep && !s.chain);
23295
- if (directRuntimeSources.length > 0 && (isPeerForced || !isPeerOptionalInAll(location, peer, directRuntimeSources)) && !isTerminal && !depsSet.has(peer) && !peerDepsSet.has(peer)) return {
23317
+ if (shouldForwardRuntime && !isTerminal && !depsSet.has(peer) && !peerDepsSet.has(peer)) return {
23296
23318
  hasRuntimeSource,
23297
23319
  peer,
23298
23320
  reason: "under-exposed",
@@ -23312,13 +23334,14 @@ function classifyPeer(peer, sources, ctx) {
23312
23334
  versionRange
23313
23335
  };
23314
23336
  }
23315
- function findUnsatisfiedPeers({ name, location }, { dependencies, devDependencies, peerDependencies, peerDependencyVersions }, exclude, isTerminal, forcePeerOptional, forceDevs) {
23337
+ function findUnsatisfiedPeers({ name, location }, { dependencies, devDependencies, peerDependencies, peerDependencyVersions }, exclude, isTerminal, forcePeerOptional, forceDevs, forwarding) {
23316
23338
  const peerSources = collectPeerSources(location, dependencies, devDependencies, peerDependencies);
23317
23339
  const ctx = {
23318
23340
  depsSet: new Set(dependencies),
23319
23341
  devDepsSet: new Set(devDependencies),
23320
23342
  forceDevs: forceDevs ?? /* @__PURE__ */ new Set(),
23321
23343
  forcePeerOptional,
23344
+ forwarding,
23322
23345
  isTerminal: isTerminal ?? isTerminalPackage$1(location),
23323
23346
  location,
23324
23347
  peerDepsSet: new Set(peerDependencies)
@@ -23521,12 +23544,24 @@ const AEI_RULES = [
23521
23544
  id: "aei.signal.required-peer",
23522
23545
  kind: "dep-signal"
23523
23546
  },
23547
+ {
23548
+ defaultWeight: 0,
23549
+ description: "Peer contract inherited from a runtime dependency chain for a package never imported here (peerForwarding: when-used) — installers resolve it; no forwarding required",
23550
+ id: "aei.signal.inherited-peer",
23551
+ kind: "dep-signal"
23552
+ },
23524
23553
  {
23525
23554
  defaultWeight: 40,
23526
23555
  description: "Dependency uses a global registry",
23527
23556
  id: "aei.signal.global-registry",
23528
23557
  kind: "dep-signal"
23529
23558
  },
23559
+ {
23560
+ defaultWeight: 40,
23561
+ description: "Dependency creates React contexts at module scope (a duplicate copy forks the context)",
23562
+ id: "aei.signal.creates-context",
23563
+ kind: "dep-signal"
23564
+ },
23530
23565
  {
23531
23566
  defaultWeight: 30,
23532
23567
  description: "Dependency exports mutable objects",
@@ -23675,6 +23710,10 @@ function matchingOverrides(packages, dependency) {
23675
23710
  });
23676
23711
  return exact === void 0 ? globs : [...globs, exact];
23677
23712
  }
23713
+ function resolvePeerForwarding(peerForwarding = "always") {
23714
+ if (peerForwarding !== "always" && peerForwarding !== "when-used") throw new TypeError("commands.apiExposure.peerForwarding must be \"always\" or \"when-used\"");
23715
+ return peerForwarding;
23716
+ }
23678
23717
  function normalizeApiExposureConfig(config) {
23679
23718
  const globalRuleSettings = config?.rules ?? {};
23680
23719
  validateRuleIds("commands.apiExposure.rules", globalRuleSettings);
@@ -23720,6 +23759,7 @@ function normalizeApiExposureConfig(config) {
23720
23759
  };
23721
23760
  return {
23722
23761
  classificationFor,
23762
+ peerForwarding: resolvePeerForwarding(config?.peerForwarding),
23723
23763
  ruleFor,
23724
23764
  rules: globalRules,
23725
23765
  thresholds: resolveThresholds(config?.thresholds),
@@ -24020,6 +24060,98 @@ const FACTORY_NAME_PATTERN = /^(?:create|make|build)[A-Z_]/;
24020
24060
  const REGISTRY_NAME_PATTERN = /registry|container/i;
24021
24061
  /** Cap on how much of a dependency's types entry we parse for signals. */
24022
24062
  const MAX_TYPES_FILE_BYTES = 1e6;
24063
+ const pnpmVirtualStoreCache = /* @__PURE__ */ new Map();
24064
+ /** Walks up from `startDir` looking for a `node_modules/.pnpm` virtual store. */
24065
+ function findPnpmVirtualStoreEntries(startDir) {
24066
+ let current = PATH.resolve(startDir);
24067
+ while (true) {
24068
+ const candidate = PATH.join(current, "node_modules", ".pnpm");
24069
+ if (fs.existsSync(candidate)) {
24070
+ const cached = pnpmVirtualStoreCache.get(candidate);
24071
+ if (cached !== void 0) return cached;
24072
+ try {
24073
+ const entries = fs.readdirSync(candidate);
24074
+ pnpmVirtualStoreCache.set(candidate, entries);
24075
+ return entries;
24076
+ } catch {
24077
+ return;
24078
+ }
24079
+ }
24080
+ const parent = PATH.dirname(current);
24081
+ if (parent === current) return void 0;
24082
+ current = parent;
24083
+ }
24084
+ }
24085
+ /** Walks up from `startDir` looking for a `pnpm-lock.yaml`. */
24086
+ function findPnpmLockfile(startDir) {
24087
+ let current = PATH.resolve(startDir);
24088
+ while (true) {
24089
+ const candidate = PATH.join(current, "pnpm-lock.yaml");
24090
+ if (fs.existsSync(candidate)) return candidate;
24091
+ const parent = PATH.dirname(current);
24092
+ if (parent === current) return void 0;
24093
+ current = parent;
24094
+ }
24095
+ }
24096
+ const lockfileVersionsCache = /* @__PURE__ */ new Map();
24097
+ /**
24098
+ * Package-key lines of the lockfile's `packages:` section, e.g.
24099
+ * ` '@mui/material@9.2.0':` (v9), ` react@19.2.7:` (v9 unquoted) or
24100
+ * ` /@mui/material@9.2.0(react@19.2.7):` (v6).
24101
+ */
24102
+ const LOCKFILE_PACKAGE_KEY = /^ {2}['"]?\/?((?:@[^/'"\s]+\/)?[^@/'"\s]+)@([^('":\s]+)/;
24103
+ /**
24104
+ * Resolved versions per package name from the lockfile's `packages:` section.
24105
+ * The lockfile is authoritative for what an install produces — unlike the
24106
+ * `.pnpm` virtual store directory, which can hold stale entries from prior
24107
+ * installs.
24108
+ */
24109
+ function readLockfileVersions(lockfilePath) {
24110
+ if (lockfileVersionsCache.has(lockfilePath)) return lockfileVersionsCache.get(lockfilePath);
24111
+ let versions;
24112
+ try {
24113
+ const lines = fs.readFileSync(lockfilePath, "utf8").split("\n");
24114
+ versions = /* @__PURE__ */ new Map();
24115
+ let inPackagesSection = false;
24116
+ for (const line of lines) {
24117
+ if (line.length > 0 && line[0] !== " " && line[0] !== "#") {
24118
+ inPackagesSection = line.startsWith("packages:");
24119
+ continue;
24120
+ }
24121
+ if (!inPackagesSection) continue;
24122
+ const match = LOCKFILE_PACKAGE_KEY.exec(line);
24123
+ if (match === null) continue;
24124
+ const [, name, version] = match;
24125
+ const set = versions.get(name) ?? /* @__PURE__ */ new Set();
24126
+ set.add(version);
24127
+ versions.set(name, set);
24128
+ }
24129
+ } catch {
24130
+ versions = void 0;
24131
+ }
24132
+ lockfileVersionsCache.set(lockfilePath, versions);
24133
+ return versions;
24134
+ }
24135
+ /**
24136
+ * True when the install tree holds more than one version of the dependency —
24137
+ * the duplication-risk condition of the tree-shaking modifier
24138
+ * (API-EXPOSURE-INDEX.md section 9). The pnpm lockfile is the authoritative
24139
+ * source; the `.pnpm` virtual store directory is the fallback (it can hold
24140
+ * stale entries from prior installs, so it may over-report). On other
24141
+ * layouts the answer is unknown, so the modifier keeps its historical
24142
+ * behavior and applies.
24143
+ */
24144
+ function hasInstalledVersionMultiplicity(workspaceDir, dependency) {
24145
+ const lockfilePath = findPnpmLockfile(workspaceDir);
24146
+ if (lockfilePath !== void 0) {
24147
+ const lockfileVersions = readLockfileVersions(lockfilePath);
24148
+ if (lockfileVersions !== void 0) return (lockfileVersions.get(dependency)?.size ?? 0) > 1;
24149
+ }
24150
+ const entries = findPnpmVirtualStoreEntries(workspaceDir);
24151
+ if (entries === void 0) return true;
24152
+ const prefix = `${dependency.replace("/", "+")}@`;
24153
+ return new Set(entries.filter((entry) => entry.startsWith(prefix)).map((entry) => entry.slice(prefix.length).split("_", 1)[0])).size > 1;
24154
+ }
24023
24155
  /** Walks up from `startDir` looking for `node_modules/<dependency>/package.json`. */
24024
24156
  function findDependencyDir(startDir, dependency) {
24025
24157
  let current = PATH.resolve(startDir);
@@ -24065,6 +24197,69 @@ function hasEsmSurface(manifest) {
24065
24197
  if (typeof exportsField === "object" && exportsField !== null) return firstStringDeep(exportsField, ["import"]) !== void 0 || JSON.stringify(exportsField).includes("\"import\"");
24066
24198
  return false;
24067
24199
  }
24200
+ const CONTEXT_CREATION_PATTERN = /\bcreateContext\s*\(/;
24201
+ /** Bounds for the shipped-runtime context scan (large deps like MUI). */
24202
+ const MAX_CONTEXT_SCAN_FILES = 400;
24203
+ const MAX_CONTEXT_SCAN_BYTES = 8e6;
24204
+ const RUNTIME_FILE_PATTERN = /\.(?:js|mjs|cjs)$/;
24205
+ const createsContextCache = /* @__PURE__ */ new Map();
24206
+ /** Collects shipped runtime files, capped, skipping nested node_modules. */
24207
+ function collectRuntimeFiles(dir, collected) {
24208
+ if (collected.length >= MAX_CONTEXT_SCAN_FILES * 4) return;
24209
+ let entries;
24210
+ try {
24211
+ entries = fs.readdirSync(dir, { withFileTypes: true });
24212
+ } catch {
24213
+ return;
24214
+ }
24215
+ for (const entry of entries) {
24216
+ if (collected.length >= MAX_CONTEXT_SCAN_FILES * 4) return;
24217
+ const entryPath = PATH.join(dir, entry.name);
24218
+ if (entry.isDirectory()) {
24219
+ if (entry.name !== "node_modules") collectRuntimeFiles(entryPath, collected);
24220
+ } else if (entry.isFile() && RUNTIME_FILE_PATTERN.test(entry.name)) collected.push(entryPath);
24221
+ }
24222
+ }
24223
+ /**
24224
+ * Bounded scan of the dependency's shipped runtime for module-scope context
24225
+ * creation (`createContext(`). Context-named files are scanned first — the
24226
+ * conventional home of the pattern — so large dependencies resolve within
24227
+ * the scan budget.
24228
+ */
24229
+ function createsSharedContext(dependencyDir) {
24230
+ const cached = createsContextCache.get(dependencyDir);
24231
+ if (cached !== void 0) return cached;
24232
+ const files = [];
24233
+ collectRuntimeFiles(dependencyDir, files);
24234
+ const prioritized = files.toSorted((a, b) => Number(/context/i.test(b)) - Number(/context/i.test(a)));
24235
+ let scannedFiles = 0;
24236
+ let scannedBytes = 0;
24237
+ let result = false;
24238
+ for (const file of prioritized) {
24239
+ if (scannedFiles >= MAX_CONTEXT_SCAN_FILES || scannedBytes >= MAX_CONTEXT_SCAN_BYTES) break;
24240
+ try {
24241
+ const content = fs.readFileSync(file, "utf8");
24242
+ scannedFiles += 1;
24243
+ scannedBytes += content.length;
24244
+ if (CONTEXT_CREATION_PATTERN.test(content)) {
24245
+ result = true;
24246
+ break;
24247
+ }
24248
+ } catch {
24249
+ continue;
24250
+ }
24251
+ }
24252
+ createsContextCache.set(dependencyDir, result);
24253
+ return result;
24254
+ }
24255
+ /**
24256
+ * True for packages in the React-singleton class: React itself and libraries
24257
+ * designed to share the host's React copy. Scopes the context scan so
24258
+ * unrelated uses of `createContext` (e.g. `node:vm`) don't fire the signal.
24259
+ */
24260
+ function isReactAdjacent(dependency, manifest) {
24261
+ return dependency === "react" || dependency === "react-dom" || Object.hasOwn(manifest.peerDependencies ?? {}, "react");
24262
+ }
24068
24263
  /** Syntactic scan of the dependency's types entry point. */
24069
24264
  function scanTypesSurface(typesEntry) {
24070
24265
  let sourceCode;
@@ -24118,6 +24313,7 @@ function getDependencySignals(workspaceDir, dependency) {
24118
24313
  if (manifest.peerDependencies !== void 0 && Object.keys(manifest.peerDependencies).length > 0) report("aei.signal.declares-peers", `${dependency} declares peerDependencies of its own`);
24119
24314
  const sideEffectsFree = manifest.sideEffects === false;
24120
24315
  if (sideEffectsFree) report("aei.signal.side-effects-free", `${dependency} declares sideEffects: false`);
24316
+ if (isReactAdjacent(dependency, manifest) && createsSharedContext(dependencyDir)) report("aei.signal.creates-context", `${dependency} creates React contexts at module scope — a duplicate copy forks the context`);
24121
24317
  const typesEntry = resolveTypesEntry(dependencyDir, manifest);
24122
24318
  const surface = typesEntry === void 0 ? void 0 : scanTypesSurface(typesEntry);
24123
24319
  if (surface !== void 0) {
@@ -24441,6 +24637,42 @@ function getExposureFindings({ entryFiles, fileLabel, program }) {
24441
24637
  return findings;
24442
24638
  }
24443
24639
  //#endregion
24640
+ //#region src/actions/api-exposure/analyzer/importedPackages.ts
24641
+ /**
24642
+ * Extracts the external package name from a module specifier, if any.
24643
+ * Relative paths, `#` subpath imports, and `node:` builtins are internal.
24644
+ */
24645
+ function packageNameFromSpecifier(specifier) {
24646
+ if (specifier.startsWith(".") || specifier.startsWith("#") || specifier.startsWith("node:")) return void 0;
24647
+ const parts = specifier.split("/");
24648
+ if (specifier.startsWith("@")) return parts.length > 1 ? `${parts[0]}/${parts[1]}` : void 0;
24649
+ return parts[0] === "" ? void 0 : parts[0];
24650
+ }
24651
+ function collectFileImports(sourceFile, imported) {
24652
+ for (const statement of sourceFile.statements) {
24653
+ const moduleSpecifier = ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement) ? statement.moduleSpecifier : void 0;
24654
+ if (moduleSpecifier === void 0 || !ts.isStringLiteral(moduleSpecifier)) continue;
24655
+ const name = packageNameFromSpecifier(moduleSpecifier.text);
24656
+ if (name !== void 0) imported.add(name);
24657
+ }
24658
+ }
24659
+ /**
24660
+ * Collects the external packages the workspace's own source files import
24661
+ * (static imports and re-exports reachable from the entry points). This is
24662
+ * the "does this package use the dependency itself" signal consumed by the
24663
+ * `peerForwarding: 'when-used'` policy — a peer contract inherited from a
24664
+ * dependency chain only forwards conclusively when the package appears here.
24665
+ */
24666
+ function getImportedPackages(program, workspaceDir) {
24667
+ const imported = /* @__PURE__ */ new Set();
24668
+ for (const sourceFile of program.getSourceFiles()) {
24669
+ const { fileName } = sourceFile;
24670
+ if (!fileName.startsWith(workspaceDir) || fileName.includes("node_modules")) continue;
24671
+ collectFileImports(sourceFile, imported);
24672
+ }
24673
+ return imported;
24674
+ }
24675
+ //#endregion
24444
24676
  //#region src/actions/api-exposure/analyzer/program.ts
24445
24677
  function createSharedProgramCache() {
24446
24678
  return { sourceFiles: /* @__PURE__ */ new Map() };
@@ -24497,6 +24729,7 @@ function readManifestSections(workspaceDir) {
24497
24729
  return {
24498
24730
  dependencies: new Set(Object.keys(pkg.dependencies ?? {})),
24499
24731
  devDependencies: new Set(Object.keys(pkg.devDependencies ?? {})),
24732
+ isPrivate: pkg.private === true,
24500
24733
  peerDependencies: new Set(Object.keys(pkg.peerDependencies ?? {})),
24501
24734
  sideEffectsFree: pkg.sideEffects === false
24502
24735
  };
@@ -24504,6 +24737,7 @@ function readManifestSections(workspaceDir) {
24504
24737
  return {
24505
24738
  dependencies: /* @__PURE__ */ new Set(),
24506
24739
  devDependencies: /* @__PURE__ */ new Set(),
24740
+ isPrivate: false,
24507
24741
  peerDependencies: /* @__PURE__ */ new Set(),
24508
24742
  sideEffectsFree: false
24509
24743
  };
@@ -24524,40 +24758,73 @@ function couplingSourceFiles(workspaceDir, programFiles) {
24524
24758
  return findFilesByGlob(workspaceDir, "./src/**/*.{ts,tsx,mts,cts}", ["**/node_modules/**"]).filter((file) => !file.endsWith(".d.ts"));
24525
24759
  }
24526
24760
  const PROVIDED_CLOSURE_DEPTH = 2;
24527
- const PROVIDED_CANDIDATE_BANDS = /* @__PURE__ */ new Set([
24528
- "review",
24529
- "probably-peer",
24530
- "peer"
24761
+ /**
24762
+ * Exposure of these rules requires the dependency's code at runtime; every
24763
+ * other exposure rule only leaks *types*. Coupling rules are runtime by
24764
+ * definition. Used to decide whether a devDependency (e.g. `@types/express`)
24765
+ * can vouch for an unlisted, provided dependency.
24766
+ */
24767
+ const RUNTIME_EXPOSURE_RULES = /* @__PURE__ */ new Set([
24768
+ "aei.exposure.class-extends",
24769
+ "aei.exposure.exported-constant",
24770
+ "aei.exposure.exported-owned-value",
24771
+ "aei.exposure.named-reexport",
24772
+ "aei.exposure.star-reexport"
24531
24773
  ]);
24774
+ function isTypeOnlyExposure(findings) {
24775
+ return findings.every((finding) => !RUNTIME_EXPOSURE_RULES.has(finding.ruleId) && !finding.ruleId.startsWith("aei.coupling."));
24776
+ }
24777
+ /**
24778
+ * The `@types/*` spelling(s) of a package name. Symbol attribution maps
24779
+ * `@types/foo` declarations back to `foo` (exposureWalk), so the provided
24780
+ * check must also look for the DefinitelyTyped package in provider closures.
24781
+ */
24782
+ function typesAliasesOf(target) {
24783
+ return target.startsWith("@") ? [`@types/${target.slice(1).replace("/", "__")}`] : [`@types/${target}`];
24784
+ }
24532
24785
  /**
24533
- * True when `target` is provided by the dependency closure of one of the
24534
- * package's declared deps (depth-limited, mirroring the peer-chain walk).
24535
- * An exposed-but-unlisted package that arrives this way is version-managed
24536
- * by the declaring intermediary, so the analyzer must not conclude `peer`
24537
- * on its own — the emitted d.ts (deplint's dist type-import rule) is the
24538
- * enforcement point for whether it must also be declared here.
24786
+ * Resolves a provider package's real directory and its declared runtime
24787
+ * dependencies. The realpath matters under pnpm's non-hoisted layout: a
24788
+ * provider's own dependencies are only resolvable from its virtual-store
24789
+ * directory, not from the workspace that (transitively) links it.
24539
24790
  */
24540
- function readDeclaredDependencies(workspaceDir, dep) {
24541
- const manifestPath = findDepPackageJson(workspaceDir, dep);
24542
- if (manifestPath === void 0) return [];
24791
+ function resolveProvider(baseDir, dep) {
24792
+ const manifestPath = findDepPackageJson(baseDir, dep);
24793
+ if (manifestPath === void 0) return void 0;
24543
24794
  try {
24544
24795
  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
24545
- return Object.keys(manifest.dependencies ?? {});
24796
+ let dir = PATH.dirname(manifestPath);
24797
+ try {
24798
+ dir = fs.realpathSync(dir);
24799
+ } catch {}
24800
+ return {
24801
+ dependencies: Object.keys(manifest.dependencies ?? {}),
24802
+ dir
24803
+ };
24546
24804
  } catch {
24547
- return [];
24805
+ return;
24548
24806
  }
24549
24807
  }
24550
- function isProvidedByDeclaredDeps(workspaceDir, declared, target) {
24808
+ function isProvidedByDeclaredDeps(workspaceDir, declared, targets) {
24809
+ const targetSet = new Set(targets);
24551
24810
  const visited = /* @__PURE__ */ new Set();
24552
- let frontier = [...declared];
24811
+ let frontier = [...declared].map((name) => ({
24812
+ baseDir: workspaceDir,
24813
+ name
24814
+ }));
24553
24815
  for (let depth = 0; depth <= PROVIDED_CLOSURE_DEPTH; depth++) {
24554
- const unvisited = frontier.filter((entry) => !visited.has(entry));
24555
24816
  const next = [];
24556
- for (const dep of unvisited) {
24557
- visited.add(dep);
24558
- const dependencies = readDeclaredDependencies(workspaceDir, dep);
24559
- if (dependencies.includes(target)) return true;
24560
- next.push(...dependencies);
24817
+ const unvisited = frontier.filter(({ name }) => !visited.has(name));
24818
+ for (const { baseDir, name } of unvisited) {
24819
+ visited.add(name);
24820
+ const provider = resolveProvider(baseDir, name);
24821
+ if (provider !== void 0) {
24822
+ if (provider.dependencies.some((dependency) => targetSet.has(dependency))) return true;
24823
+ next.push(...provider.dependencies.map((dependency) => ({
24824
+ baseDir: provider.dir,
24825
+ name: dependency
24826
+ })));
24827
+ }
24561
24828
  }
24562
24829
  frontier = next;
24563
24830
  }
@@ -24568,20 +24835,28 @@ function requiredPeerEvidence(sources) {
24568
24835
  const chains = [...new Set(sources.map((source) => source.chain?.join(" > ") ?? source.requiredBy))];
24569
24836
  return `required as a peer by ${chains.slice(0, 3).join(", ")}${chains.length > 3 ? ` (+${chains.length - 3} more)` : ""}`;
24570
24837
  }
24571
- function assessDependency({ config, dependency, isSelfOrInternal, isTerminal, raw, refTypes, requiredPeerSources, sections, workspaceDir }) {
24838
+ function assessDependency({ config, dependency, importedPackages, isSelfOrInternal, isTerminal, raw, refTypes, requiredPeerSources, sections, workspaceDir }) {
24572
24839
  const dependencyRaw = raw.filter((finding) => finding.dependency === dependency);
24573
24840
  const signals = getDependencySignals(workspaceDir, dependency);
24574
24841
  if (signals !== void 0) dependencyRaw.push(...signals.findings);
24575
24842
  const peerSources = requiredPeerSources.get(dependency);
24576
- if (peerSources !== void 0 && !isSelfOrInternal(dependency) && !sections.dependencies.has(dependency)) dependencyRaw.push({
24577
- dependency,
24578
- evidence: requiredPeerEvidence(peerSources),
24579
- file: "(peer-chain)",
24580
- ruleId: "aei.signal.required-peer"
24581
- });
24582
- if (config.treeShaking && sections.sideEffectsFree && signals?.esm === true) dependencyRaw.push({
24843
+ if (peerSources !== void 0 && !isSelfOrInternal(dependency) && !sections.dependencies.has(dependency)) {
24844
+ const isForwarded = config.peerForwarding === "always" || importedPackages === void 0 || importedPackages.has(dependency);
24845
+ dependencyRaw.push(isForwarded ? {
24846
+ dependency,
24847
+ evidence: requiredPeerEvidence(peerSources),
24848
+ file: "(peer-chain)",
24849
+ ruleId: "aei.signal.required-peer"
24850
+ } : {
24851
+ dependency,
24852
+ evidence: `${requiredPeerEvidence(peerSources)} — never imported here; the installer resolves the contract (peerForwarding: when-used)`,
24853
+ file: "(peer-chain)",
24854
+ ruleId: "aei.signal.inherited-peer"
24855
+ });
24856
+ }
24857
+ if (config.treeShaking && sections.sideEffectsFree && signals?.esm === true && hasInstalledVersionMultiplicity(workspaceDir, dependency)) dependencyRaw.push({
24583
24858
  dependency,
24584
- evidence: "sideEffects: false package with ESM dependency — peers improve deduplication",
24859
+ evidence: "sideEffects: false package with ESM dependency installed at multiple versions — peers improve deduplication",
24585
24860
  file: "(package)",
24586
24861
  ruleId: "aei.modifier.tree-shaking"
24587
24862
  });
@@ -24590,6 +24865,7 @@ function assessDependency({ config, dependency, isSelfOrInternal, isTerminal, ra
24590
24865
  const resolved = resolveRecommendation(score.recommendation, findings, {
24591
24866
  config,
24592
24867
  dependency,
24868
+ importedPackages,
24593
24869
  isSelfOrInternal,
24594
24870
  isTerminal,
24595
24871
  raw,
@@ -24614,6 +24890,22 @@ function assessDependency({ config, dependency, isSelfOrInternal, isTerminal, ra
24614
24890
  };
24615
24891
  }
24616
24892
  /**
24893
+ * True when the unlisted dependency's exposure is provided (and
24894
+ * version-managed) by the package's declared sections. Runtime sections can
24895
+ * vouch for anything; devDependencies (e.g. `@types/express`) can only vouch
24896
+ * for purely type-level exposure — and a directly declared `@types/*`
24897
+ * spelling of the dependency itself (e.g. `@types/express-serve-static-core`
24898
+ * for exposure attributed to `express-serve-static-core`) is the most direct
24899
+ * provider of all.
24900
+ */
24901
+ function isProvidedBySections(dependency, findings, sections, workspaceDir) {
24902
+ if (findings.some((finding) => finding.ruleId === "aei.signal.required-peer")) return false;
24903
+ const aliases = typesAliasesOf(dependency);
24904
+ const targets = [dependency, ...aliases];
24905
+ const isTypeOnly = isTypeOnlyExposure(findings);
24906
+ return isTypeOnly && aliases.some((alias) => sections.dependencies.has(alias) || sections.peerDependencies.has(alias) || sections.devDependencies.has(alias)) || isProvidedByDeclaredDeps(workspaceDir, [...sections.dependencies, ...sections.peerDependencies], targets) || isTypeOnly && isProvidedByDeclaredDeps(workspaceDir, [...sections.devDependencies], targets);
24907
+ }
24908
+ /**
24617
24909
  * Applies the override precedence chain from spec section 11 to a scored
24618
24910
  * recommendation. Returns undefined when the assessment should be suppressed
24619
24911
  * entirely (the `aei.exposure.provided-transitive` reporting gate, off by
@@ -24621,11 +24913,14 @@ function assessDependency({ config, dependency, isSelfOrInternal, isTerminal, ra
24621
24913
  */
24622
24914
  function resolveRecommendation(scored, findings, { config, dependency, isSelfOrInternal, isTerminal, refTypes, sections, workspaceDir }) {
24623
24915
  const classification = config.classificationFor(dependency) ?? refTypes?.get(dependency);
24624
- if (classification !== void 0) return [classification === "peer" ? "peer" : "dependency", "override"];
24625
- if (isTerminal === true) return ["dependency", "terminal"];
24916
+ if (classification !== void 0 && !(isTerminal === true && classification === "peer")) return [classification === "peer" ? "peer" : "dependency", "override"];
24917
+ if (isTerminal === true) {
24918
+ if (sections.isPrivate && currentSectionOf(dependency, sections) === "devDependencies") return void 0;
24919
+ return ["dependency", "terminal"];
24920
+ }
24626
24921
  if (isSelfOrInternal(dependency)) return ["dependency", "workspace-internal"];
24627
24922
  if (dependency.startsWith("@types/")) return ["dependency", "types-package"];
24628
- if (PROVIDED_CANDIDATE_BANDS.has(scored) && currentSectionOf(dependency, sections) === "unlisted" && findings.every((finding) => finding.ruleId !== "aei.signal.required-peer") && isProvidedByDeclaredDeps(workspaceDir, [...sections.dependencies, ...sections.peerDependencies], dependency)) return config.ruleFor("aei.exposure.provided-transitive", dependency)?.enabled === true ? ["review", "provided"] : void 0;
24923
+ if (currentSectionOf(dependency, sections) === "unlisted" && isProvidedBySections(dependency, findings, sections, workspaceDir)) return config.ruleFor("aei.exposure.provided-transitive", dependency)?.enabled === true ? ["review", "provided"] : void 0;
24629
24924
  return [scored, "score"];
24630
24925
  }
24631
24926
  /**
@@ -24640,6 +24935,7 @@ function analyzeWorkspaceApiExposure({ cache, config, isTerminal, refTypes, work
24640
24935
  const requiredPeerSources = getRuntimeRootedNonOptionalTransitivePeerSources(workspaceDir, getDependenciesFromPackageJson(PATH.join(workspaceDir, "package.json")), { excludeSatisfiedInChain: true });
24641
24936
  const entryPoints = resolveEntryPoints(workspaceDir);
24642
24937
  const program = createExposureProgram(workspaceDir, entryPoints, cache);
24938
+ const importedPackages = program === void 0 || config.peerForwarding !== "when-used" ? void 0 : getImportedPackages(program, workspaceDir);
24643
24939
  const raw = [];
24644
24940
  if (program !== void 0) raw.push(...getExposureFindings({
24645
24941
  entryFiles: entryPoints,
@@ -24658,6 +24954,7 @@ function analyzeWorkspaceApiExposure({ cache, config, isTerminal, refTypes, work
24658
24954
  ])].filter((dependency) => dependency !== workspace.name).toSorted().map((dependency) => assessDependency({
24659
24955
  config,
24660
24956
  dependency,
24957
+ importedPackages,
24661
24958
  isSelfOrInternal,
24662
24959
  isTerminal,
24663
24960
  raw,
@@ -29139,6 +29436,15 @@ function resolvePeerDeclaredVersion(context, dep) {
29139
29436
  function shouldSkipAeiPeerDemotion(context, dep, version) {
29140
29437
  return context.isTerminalPackage || context.classifierMode !== "aei" || context.forcePeers.has(dep) || dep.startsWith("@types/") || version.startsWith("workspace:");
29141
29438
  }
29439
+ /**
29440
+ * A peer this package never imports is not a placement candidate — demoting
29441
+ * it into `dependencies` would immediately make it an unused dependency. If
29442
+ * it is genuinely unneeded, `dep.peerDependencies.unused` removes it instead.
29443
+ */
29444
+ function isImportedAnywhere(context, dep) {
29445
+ const { externalAllImports, externalDistImports, externalDistTypeImports } = context.sourceParams;
29446
+ return externalAllImports.includes(dep) || externalDistImports.includes(dep) || externalDistTypeImports.includes(dep);
29447
+ }
29142
29448
  function evaluateMisplacedPeer(context, dep, version) {
29143
29449
  if (context.forceDeps.has(dep)) return {
29144
29450
  alreadyInTarget: context.packageParams.dependencies.includes(dep),
@@ -29162,6 +29468,7 @@ function evaluateMisplacedPeer(context, dep, version) {
29162
29468
  version
29163
29469
  };
29164
29470
  if (shouldSkipAeiPeerDemotion(context, dep, version)) return void 0;
29471
+ if (!isImportedAnywhere(context, dep)) return void 0;
29165
29472
  if (context.classifyDependency(dep) !== "dependency") return void 0;
29166
29473
  return {
29167
29474
  alreadyInTarget: context.packageParams.dependencies.includes(dep),
@@ -29631,12 +29938,12 @@ const unsatisfiedPeersRule = {
29631
29938
  severity: "error"
29632
29939
  },
29633
29940
  evaluate(context) {
29634
- const findings = findUnsatisfiedPeers(context.workspace, context.packageParams, context.exclude, context.isTerminalPackage, context.forcePeerOptional, context.forceDevs);
29941
+ const findings = findUnsatisfiedPeers(context.workspace, context.packageParams, context.exclude, context.isTerminalPackage, context.forcePeerOptional, context.forceDevs, context.peerForwarding);
29635
29942
  for (const finding of findings) {
29636
29943
  const requiredBy = finding.sources.map((source) => source.requiredBy).join(", ");
29637
29944
  const chain = finding.sources.find((source) => (source.chain && source.chain.length > 0) ?? false)?.chain?.join(" -> ");
29638
29945
  const evidence = chain != null && chain.length > 0 ? [`via ${chain}`] : void 0;
29639
- const message = finding.reason === "version-mismatch" ? `Peer dependency version mismatch ${finding.peer} — installed ${finding.installedVersion ?? "unknown"} does not satisfy ${finding.versionRange} (required by ${requiredBy})` : finding.reason === "under-exposed" ? `Under-exposed peer dependency ${finding.peer} (required by ${requiredBy}) — in devDependencies only; must also be in dependencies or peerDependencies` : finding.hasRuntimeSource ? `Unsatisfied peer dependency ${finding.peer} (required by ${requiredBy}) — must be in dependencies or peerDependencies` : `Unsatisfied peer dependency ${finding.peer} (required by devDependency ${requiredBy}) — must be in dependencies, devDependencies, or peerDependencies`;
29946
+ const message = finding.reason === "version-mismatch" ? `Peer dependency version mismatch ${finding.peer} — installed ${finding.installedVersion ?? "unknown"} does not satisfy ${finding.versionRange} (required by ${requiredBy})` : finding.reason === "under-exposed" ? `Under-exposed peer dependency ${finding.peer} (required by ${requiredBy}) — in devDependencies only; must also be in dependencies or peerDependencies` : finding.hasRuntimeSource ? `Unsatisfied peer dependency ${finding.peer} (required by ${requiredBy}) — must be in dependencies or peerDependencies` : finding.inherited === true ? `Unsatisfied peer dependency ${finding.peer} (required by ${requiredBy}) — never imported here (peerForwarding: when-used); needed in devDependencies for local resolution` : `Unsatisfied peer dependency ${finding.peer} (required by devDependency ${requiredBy}) — must be in dependencies, devDependencies, or peerDependencies`;
29640
29947
  context.report({
29641
29948
  data: { finding },
29642
29949
  dependency: finding.peer,
@@ -30016,8 +30323,16 @@ function buildWorkspaceContext(workspace, options = {}) {
30016
30323
  const packageMetaStarted = performance.now();
30017
30324
  const packageJsonPath = `${workspace.location}/package.json`;
30018
30325
  const packageParams = getDependenciesFromPackageJson(packageJsonPath);
30326
+ const peerForwarding = options.classifier === "aei" && options.apiExposureConfig?.peerForwarding === "when-used" ? {
30327
+ importedModules: /* @__PURE__ */ new Set([
30328
+ ...sourceParams.externalAllImports,
30329
+ ...sourceParams.externalDistImports,
30330
+ ...sourceParams.externalDistTypeImports
30331
+ ]),
30332
+ mode: "when-used"
30333
+ } : void 0;
30019
30334
  const requiredTransitivePeers = getRequiredNonOptionalTransitivePeers(workspace.location, packageParams);
30020
- const runtimeRootedRequired = getRuntimeRootedNonOptionalTransitivePeers(workspace.location, packageParams);
30335
+ const runtimeRootedRequired = new Set([...getRuntimeRootedNonOptionalTransitivePeers(workspace.location, packageParams)].filter((peer) => isPeerForwarded(peerForwarding, peer)));
30021
30336
  const packageClassification = classifyDeplintPackage(workspace.location, terminalOverride);
30022
30337
  if (phases !== void 0) phases.packageMetaMs = performance.now() - packageMetaStarted;
30023
30338
  return {
@@ -30037,6 +30352,7 @@ function buildWorkspaceContext(workspace, options = {}) {
30037
30352
  packageKind: packageClassification.kind,
30038
30353
  packageJsonPath,
30039
30354
  packageParams,
30355
+ peerForwarding,
30040
30356
  peerRangeBound: options.peerRangeBound,
30041
30357
  peerRangeForm: options.peerRangeForm ?? "shorthand",
30042
30358
  sourceParams,