@ariestools/toolchain 8.7.3 → 8.7.5

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)
@@ -23472,6 +23495,12 @@ const AEI_RULES = [
23472
23495
  id: "aei.exposure.generic-parameter",
23473
23496
  kind: "exposure"
23474
23497
  },
23498
+ {
23499
+ defaultWeight: 0,
23500
+ description: "Producer-owned function return represented by a structurally compatible interface or type alias",
23501
+ id: "aei.exposure.structural-return",
23502
+ kind: "exposure"
23503
+ },
23475
23504
  {
23476
23505
  defaultEnabled: false,
23477
23506
  defaultWeight: 0,
@@ -23515,6 +23544,12 @@ const AEI_RULES = [
23515
23544
  id: "aei.signal.required-peer",
23516
23545
  kind: "dep-signal"
23517
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
+ },
23518
23553
  {
23519
23554
  defaultWeight: 40,
23520
23555
  description: "Dependency uses a global registry",
@@ -23669,6 +23704,10 @@ function matchingOverrides(packages, dependency) {
23669
23704
  });
23670
23705
  return exact === void 0 ? globs : [...globs, exact];
23671
23706
  }
23707
+ function resolvePeerForwarding(peerForwarding = "always") {
23708
+ if (peerForwarding !== "always" && peerForwarding !== "when-used") throw new TypeError("commands.apiExposure.peerForwarding must be \"always\" or \"when-used\"");
23709
+ return peerForwarding;
23710
+ }
23672
23711
  function normalizeApiExposureConfig(config) {
23673
23712
  const globalRuleSettings = config?.rules ?? {};
23674
23713
  validateRuleIds("commands.apiExposure.rules", globalRuleSettings);
@@ -23714,6 +23753,7 @@ function normalizeApiExposureConfig(config) {
23714
23753
  };
23715
23754
  return {
23716
23755
  classificationFor,
23756
+ peerForwarding: resolvePeerForwarding(config?.peerForwarding),
23717
23757
  ruleFor,
23718
23758
  rules: globalRules,
23719
23759
  thresholds: resolveThresholds(config?.thresholds),
@@ -24014,6 +24054,41 @@ const FACTORY_NAME_PATTERN = /^(?:create|make|build)[A-Z_]/;
24014
24054
  const REGISTRY_NAME_PATTERN = /registry|container/i;
24015
24055
  /** Cap on how much of a dependency's types entry we parse for signals. */
24016
24056
  const MAX_TYPES_FILE_BYTES = 1e6;
24057
+ const pnpmVirtualStoreCache = /* @__PURE__ */ new Map();
24058
+ /** Walks up from `startDir` looking for a `node_modules/.pnpm` virtual store. */
24059
+ function findPnpmVirtualStoreEntries(startDir) {
24060
+ let current = PATH.resolve(startDir);
24061
+ while (true) {
24062
+ const candidate = PATH.join(current, "node_modules", ".pnpm");
24063
+ if (fs.existsSync(candidate)) {
24064
+ const cached = pnpmVirtualStoreCache.get(candidate);
24065
+ if (cached !== void 0) return cached;
24066
+ try {
24067
+ const entries = fs.readdirSync(candidate);
24068
+ pnpmVirtualStoreCache.set(candidate, entries);
24069
+ return entries;
24070
+ } catch {
24071
+ return;
24072
+ }
24073
+ }
24074
+ const parent = PATH.dirname(current);
24075
+ if (parent === current) return void 0;
24076
+ current = parent;
24077
+ }
24078
+ }
24079
+ /**
24080
+ * True when the install tree holds more than one version of the dependency —
24081
+ * the duplication-risk condition of the tree-shaking modifier
24082
+ * (API-EXPOSURE-INDEX.md section 9). Only the pnpm virtual store can be read
24083
+ * cheaply; on other layouts the answer is unknown, so the modifier keeps its
24084
+ * historical behavior and applies.
24085
+ */
24086
+ function hasInstalledVersionMultiplicity(workspaceDir, dependency) {
24087
+ const entries = findPnpmVirtualStoreEntries(workspaceDir);
24088
+ if (entries === void 0) return true;
24089
+ const prefix = `${dependency.replace("/", "+")}@`;
24090
+ return new Set(entries.filter((entry) => entry.startsWith(prefix)).map((entry) => entry.slice(prefix.length).split("_", 1)[0])).size > 1;
24091
+ }
24017
24092
  /** Walks up from `startDir` looking for `node_modules/<dependency>/package.json`. */
24018
24093
  function findDependencyDir(startDir, dependency) {
24019
24094
  let current = PATH.resolve(startDir);
@@ -24215,6 +24290,32 @@ function resolveEntryPoints(workspaceDir) {
24215
24290
  return [...entryPoints];
24216
24291
  }
24217
24292
  //#endregion
24293
+ //#region src/actions/api-exposure/analyzer/structuralType.ts
24294
+ const NOMINAL_SYMBOL_FLAGS = ts.SymbolFlags.Class | ts.SymbolFlags.Enum | ts.SymbolFlags.EnumMember;
24295
+ function hasNominalSymbol(type) {
24296
+ return [type.aliasSymbol, type.getSymbol()].some((symbol) => symbol !== void 0 && (symbol.flags & NOMINAL_SYMBOL_FLAGS) !== 0);
24297
+ }
24298
+ /**
24299
+ * True when a public type is represented by TypeScript's structural type
24300
+ * system rather than a class, enum, constructor, or unique-symbol identity.
24301
+ * Type arguments and interface base types must also be structural so wrappers
24302
+ * such as `Promise<ExternalClass>` do not hide nominal exposure.
24303
+ */
24304
+ function isStructuralPublicType(type, checker, seen = /* @__PURE__ */ new Set()) {
24305
+ if (seen.has(type)) return true;
24306
+ seen.add(type);
24307
+ if ((type.flags & (ts.TypeFlags.UniqueESSymbol | ts.TypeFlags.EnumLike)) !== 0 || hasNominalSymbol(type)) return false;
24308
+ if (type.isUnionOrIntersection()) return type.types.every((member) => isStructuralPublicType(member, checker, seen));
24309
+ if (((type.objectFlags ?? 0) & ts.ObjectFlags.Class) !== 0 || type.getConstructSignatures().length > 0) return false;
24310
+ const reference = type;
24311
+ if (reference.target !== void 0 && reference.target !== type && !isStructuralPublicType(reference.target, checker, seen)) return false;
24312
+ if ((reference.typeArguments ?? type.aliasTypeArguments ?? []).some((argument) => !isStructuralPublicType(argument, checker, seen))) return false;
24313
+ if (type.isClassOrInterface()) {
24314
+ if (checker.getBaseTypes(type).some((baseType) => !isStructuralPublicType(baseType, checker, seen))) return false;
24315
+ }
24316
+ return true;
24317
+ }
24318
+ //#endregion
24218
24319
  //#region src/actions/api-exposure/analyzer/exposureWalk.ts
24219
24320
  /** How deep the type walker follows type arguments and object members. */
24220
24321
  const MAX_TYPE_DEPTH = 4;
@@ -24241,29 +24342,33 @@ function symbolDependencies(symbol) {
24241
24342
  }
24242
24343
  return dependencies;
24243
24344
  }
24244
- function recordUsage(context, dependency, usage) {
24245
- if (context.usage.get(dependency) !== "direct") context.usage.set(dependency, usage);
24345
+ function recordUsage(context, dependency, kind, structural) {
24346
+ const existing = context.usage.get(dependency);
24347
+ context.usage.set(dependency, {
24348
+ kind: existing?.kind === "direct" ? "direct" : kind,
24349
+ structural: (existing?.structural ?? true) && structural
24350
+ });
24246
24351
  }
24247
24352
  function resolveAlias(checker, symbol) {
24248
24353
  if (symbol === void 0) return void 0;
24249
24354
  return (symbol.flags & ts.SymbolFlags.Alias) === 0 ? symbol : checker.getAliasedSymbol(symbol);
24250
24355
  }
24251
24356
  /** Walks members and signatures of anonymous object types. */
24252
- function collectAnonymousMemberDependencies(type, usage, depth, context) {
24357
+ function collectAnonymousMemberDependencies(type, kind, depth, context) {
24253
24358
  const symbolType = (property) => {
24254
24359
  const declaration = property.valueDeclaration ?? property.declarations?.[0];
24255
24360
  return declaration === void 0 ? void 0 : context.checker.getTypeOfSymbolAtLocation(property, declaration);
24256
24361
  };
24257
24362
  for (const property of type.getProperties()) {
24258
24363
  const propertyType = symbolType(property);
24259
- if (propertyType !== void 0) collectTypeDependencies(propertyType, usage, depth + 1, context);
24364
+ if (propertyType !== void 0) collectTypeDependencies(propertyType, kind, depth + 1, context);
24260
24365
  }
24261
24366
  for (const signature of [...type.getCallSignatures(), ...type.getConstructSignatures()]) {
24262
24367
  for (const parameter of signature.getParameters()) {
24263
24368
  const parameterType = symbolType(parameter);
24264
- if (parameterType !== void 0) collectTypeDependencies(parameterType, usage, depth + 1, context);
24369
+ if (parameterType !== void 0) collectTypeDependencies(parameterType, kind, depth + 1, context);
24265
24370
  }
24266
- collectTypeDependencies(signature.getReturnType(), usage, depth + 1, context);
24371
+ collectTypeDependencies(signature.getReturnType(), kind, depth + 1, context);
24267
24372
  }
24268
24373
  }
24269
24374
  /**
@@ -24271,17 +24376,18 @@ function collectAnonymousMemberDependencies(type, usage, depth, context) {
24271
24376
  * declared in. Type arguments are recorded as `generic` usage; unions,
24272
24377
  * intersections, and anonymous object members keep their parent's usage.
24273
24378
  */
24274
- function collectTypeDependencies(type, usage, depth, context) {
24379
+ function collectTypeDependencies(type, kind, depth, context) {
24275
24380
  if (depth > MAX_TYPE_DEPTH || context.visited.has(type)) return;
24276
24381
  context.visited.add(type);
24277
- for (const symbol of [type.aliasSymbol, type.getSymbol()]) for (const dependency of symbolDependencies(symbol)) recordUsage(context, dependency, usage);
24382
+ const structural = isStructuralPublicType(type, context.checker);
24383
+ for (const symbol of [type.aliasSymbol, type.getSymbol()]) for (const dependency of symbolDependencies(symbol)) recordUsage(context, dependency, kind, structural);
24278
24384
  if (type.isUnionOrIntersection()) {
24279
- for (const constituent of type.types) collectTypeDependencies(constituent, usage, depth + 1, context);
24385
+ for (const constituent of type.types) collectTypeDependencies(constituent, kind, depth + 1, context);
24280
24386
  return;
24281
24387
  }
24282
24388
  const typeArguments = type.typeArguments ?? type.aliasTypeArguments ?? [];
24283
24389
  for (const argument of typeArguments) collectTypeDependencies(argument, "generic", depth + 1, context);
24284
- if (((type.objectFlags ?? 0) & ts.ObjectFlags.Anonymous) !== 0 && symbolDependencies(type.getSymbol()).size === 0) collectAnonymousMemberDependencies(type, usage, depth, context);
24390
+ if (((type.objectFlags ?? 0) & ts.ObjectFlags.Anonymous) !== 0 && symbolDependencies(type.getSymbol()).size === 0) collectAnonymousMemberDependencies(type, kind, depth, context);
24285
24391
  }
24286
24392
  function typeDependencies(type, checker) {
24287
24393
  const context = {
@@ -24319,8 +24425,9 @@ function getExposureFindings({ entryFiles, fileLabel, program }) {
24319
24425
  ruleId
24320
24426
  });
24321
24427
  }
24322
- function reportUsage(usage, directRuleId, node, directEvidence, genericEvidence) {
24323
- for (const [dependency, kind] of usage) if (kind === "direct") report(directRuleId, dependency, node, directEvidence(dependency));
24428
+ function reportUsage(usage, directRuleId, node, directEvidence, genericEvidence, structuralRuleId) {
24429
+ for (const [dependency, typeUsage] of usage) if (typeUsage.structural && structuralRuleId !== void 0) report(structuralRuleId, dependency, node, `exported API returns a structural type from ${dependency}`);
24430
+ else if (typeUsage.kind === "direct") report(directRuleId, dependency, node, directEvidence(dependency));
24324
24431
  else report("aei.exposure.generic-parameter", dependency, node, genericEvidence(dependency));
24325
24432
  }
24326
24433
  function visitFunctionExport(name, symbol, declaration) {
@@ -24330,7 +24437,7 @@ function getExposureFindings({ entryFiles, fileLabel, program }) {
24330
24437
  const parameterDeclaration = parameter.valueDeclaration ?? parameter.declarations?.[0] ?? declaration;
24331
24438
  reportUsage(typeDependencies(checker.getTypeOfSymbolAtLocation(parameter, parameterDeclaration), checker), "aei.exposure.function-parameter", parameterDeclaration, (dep) => `exported function \`${name}\` parameter \`${parameter.name}\` is typed by ${dep}`, (dep) => `exported function \`${name}\` parameter \`${parameter.name}\` uses ${dep} as a generic argument`);
24332
24439
  }
24333
- reportUsage(typeDependencies(signature.getReturnType(), checker), "aei.exposure.function-return", declaration, (dep) => `exported function \`${name}\` return type originates in ${dep}`, (dep) => `exported function \`${name}\` return type uses ${dep} as a generic argument`);
24440
+ reportUsage(typeDependencies(signature.getReturnType(), checker), "aei.exposure.function-return", declaration, (dep) => `exported function \`${name}\` return type originates in ${dep}`, (dep) => `exported function \`${name}\` return type uses ${dep} as a generic argument`, "aei.exposure.structural-return");
24334
24441
  const typeParameters = signature.typeParameters ?? [];
24335
24442
  for (const typeParameter of typeParameters) {
24336
24443
  const constraint = typeParameter.getConstraint();
@@ -24368,9 +24475,9 @@ function getExposureFindings({ entryFiles, fileLabel, program }) {
24368
24475
  for (const dependency of symbolDependencies(resolved)) report("aei.exposure.exported-owned-value", dependency, declaration, `exported value \`${name}\` is owned by ${dependency}`);
24369
24476
  }
24370
24477
  const usage = typeDependencies(checker.getTypeOfSymbolAtLocation(symbol, declaration), checker);
24371
- const directDependencies = [...usage].filter(([, kind]) => kind === "direct").map(([dependency]) => dependency);
24478
+ const directDependencies = [...usage].filter(([, typeUsage]) => typeUsage.kind === "direct").map(([dependency]) => dependency);
24372
24479
  for (const dependency of directDependencies) report("aei.exposure.exported-value", dependency, declaration, `exported runtime value \`${name}\` has a type originating in ${dependency}`);
24373
- for (const [dependency, kind] of usage) if (kind === "generic") report("aei.exposure.generic-parameter", dependency, declaration, `exported value \`${name}\` uses ${dependency} as a generic argument`);
24480
+ for (const [dependency, typeUsage] of usage) if (typeUsage.kind === "generic") report("aei.exposure.generic-parameter", dependency, declaration, `exported value \`${name}\` uses ${dependency} as a generic argument`);
24374
24481
  if (directDependencies.length === 0 && initializer !== void 0 && ts.isCallExpression(initializer)) {
24375
24482
  const resolved = resolveAlias(checker, checker.getSymbolAtLocation(initializer.expression));
24376
24483
  for (const dependency of symbolDependencies(resolved)) report("aei.exposure.exported-constant", dependency, declaration, `exported constant \`${name}\` is produced by a ${dependency} factory`);
@@ -24403,6 +24510,42 @@ function getExposureFindings({ entryFiles, fileLabel, program }) {
24403
24510
  return findings;
24404
24511
  }
24405
24512
  //#endregion
24513
+ //#region src/actions/api-exposure/analyzer/importedPackages.ts
24514
+ /**
24515
+ * Extracts the external package name from a module specifier, if any.
24516
+ * Relative paths, `#` subpath imports, and `node:` builtins are internal.
24517
+ */
24518
+ function packageNameFromSpecifier(specifier) {
24519
+ if (specifier.startsWith(".") || specifier.startsWith("#") || specifier.startsWith("node:")) return void 0;
24520
+ const parts = specifier.split("/");
24521
+ if (specifier.startsWith("@")) return parts.length > 1 ? `${parts[0]}/${parts[1]}` : void 0;
24522
+ return parts[0] === "" ? void 0 : parts[0];
24523
+ }
24524
+ function collectFileImports(sourceFile, imported) {
24525
+ for (const statement of sourceFile.statements) {
24526
+ const moduleSpecifier = ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement) ? statement.moduleSpecifier : void 0;
24527
+ if (moduleSpecifier === void 0 || !ts.isStringLiteral(moduleSpecifier)) continue;
24528
+ const name = packageNameFromSpecifier(moduleSpecifier.text);
24529
+ if (name !== void 0) imported.add(name);
24530
+ }
24531
+ }
24532
+ /**
24533
+ * Collects the external packages the workspace's own source files import
24534
+ * (static imports and re-exports reachable from the entry points). This is
24535
+ * the "does this package use the dependency itself" signal consumed by the
24536
+ * `peerForwarding: 'when-used'` policy — a peer contract inherited from a
24537
+ * dependency chain only forwards conclusively when the package appears here.
24538
+ */
24539
+ function getImportedPackages(program, workspaceDir) {
24540
+ const imported = /* @__PURE__ */ new Set();
24541
+ for (const sourceFile of program.getSourceFiles()) {
24542
+ const { fileName } = sourceFile;
24543
+ if (!fileName.startsWith(workspaceDir) || fileName.includes("node_modules")) continue;
24544
+ collectFileImports(sourceFile, imported);
24545
+ }
24546
+ return imported;
24547
+ }
24548
+ //#endregion
24406
24549
  //#region src/actions/api-exposure/analyzer/program.ts
24407
24550
  function createSharedProgramCache() {
24408
24551
  return { sourceFiles: /* @__PURE__ */ new Map() };
@@ -24459,6 +24602,7 @@ function readManifestSections(workspaceDir) {
24459
24602
  return {
24460
24603
  dependencies: new Set(Object.keys(pkg.dependencies ?? {})),
24461
24604
  devDependencies: new Set(Object.keys(pkg.devDependencies ?? {})),
24605
+ isPrivate: pkg.private === true,
24462
24606
  peerDependencies: new Set(Object.keys(pkg.peerDependencies ?? {})),
24463
24607
  sideEffectsFree: pkg.sideEffects === false
24464
24608
  };
@@ -24466,6 +24610,7 @@ function readManifestSections(workspaceDir) {
24466
24610
  return {
24467
24611
  dependencies: /* @__PURE__ */ new Set(),
24468
24612
  devDependencies: /* @__PURE__ */ new Set(),
24613
+ isPrivate: false,
24469
24614
  peerDependencies: /* @__PURE__ */ new Set(),
24470
24615
  sideEffectsFree: false
24471
24616
  };
@@ -24486,11 +24631,30 @@ function couplingSourceFiles(workspaceDir, programFiles) {
24486
24631
  return findFilesByGlob(workspaceDir, "./src/**/*.{ts,tsx,mts,cts}", ["**/node_modules/**"]).filter((file) => !file.endsWith(".d.ts"));
24487
24632
  }
24488
24633
  const PROVIDED_CLOSURE_DEPTH = 2;
24489
- const PROVIDED_CANDIDATE_BANDS = /* @__PURE__ */ new Set([
24490
- "review",
24491
- "probably-peer",
24492
- "peer"
24634
+ /**
24635
+ * Exposure of these rules requires the dependency's code at runtime; every
24636
+ * other exposure rule only leaks *types*. Coupling rules are runtime by
24637
+ * definition. Used to decide whether a devDependency (e.g. `@types/express`)
24638
+ * can vouch for an unlisted, provided dependency.
24639
+ */
24640
+ const RUNTIME_EXPOSURE_RULES = /* @__PURE__ */ new Set([
24641
+ "aei.exposure.class-extends",
24642
+ "aei.exposure.exported-constant",
24643
+ "aei.exposure.exported-owned-value",
24644
+ "aei.exposure.named-reexport",
24645
+ "aei.exposure.star-reexport"
24493
24646
  ]);
24647
+ function isTypeOnlyExposure(findings) {
24648
+ return findings.every((finding) => !RUNTIME_EXPOSURE_RULES.has(finding.ruleId) && !finding.ruleId.startsWith("aei.coupling."));
24649
+ }
24650
+ /**
24651
+ * The `@types/*` spelling(s) of a package name. Symbol attribution maps
24652
+ * `@types/foo` declarations back to `foo` (exposureWalk), so the provided
24653
+ * check must also look for the DefinitelyTyped package in provider closures.
24654
+ */
24655
+ function typesAliasesOf(target) {
24656
+ return target.startsWith("@") ? [`@types/${target.slice(1).replace("/", "__")}`] : [`@types/${target}`];
24657
+ }
24494
24658
  /**
24495
24659
  * True when `target` is provided by the dependency closure of one of the
24496
24660
  * package's declared deps (depth-limited, mirroring the peer-chain walk).
@@ -24509,7 +24673,8 @@ function readDeclaredDependencies(workspaceDir, dep) {
24509
24673
  return [];
24510
24674
  }
24511
24675
  }
24512
- function isProvidedByDeclaredDeps(workspaceDir, declared, target) {
24676
+ function isProvidedByDeclaredDeps(workspaceDir, declared, targets) {
24677
+ const targetSet = new Set(targets);
24513
24678
  const visited = /* @__PURE__ */ new Set();
24514
24679
  let frontier = [...declared];
24515
24680
  for (let depth = 0; depth <= PROVIDED_CLOSURE_DEPTH; depth++) {
@@ -24518,7 +24683,7 @@ function isProvidedByDeclaredDeps(workspaceDir, declared, target) {
24518
24683
  for (const dep of unvisited) {
24519
24684
  visited.add(dep);
24520
24685
  const dependencies = readDeclaredDependencies(workspaceDir, dep);
24521
- if (dependencies.includes(target)) return true;
24686
+ if (dependencies.some((dependency) => targetSet.has(dependency))) return true;
24522
24687
  next.push(...dependencies);
24523
24688
  }
24524
24689
  frontier = next;
@@ -24530,20 +24695,28 @@ function requiredPeerEvidence(sources) {
24530
24695
  const chains = [...new Set(sources.map((source) => source.chain?.join(" > ") ?? source.requiredBy))];
24531
24696
  return `required as a peer by ${chains.slice(0, 3).join(", ")}${chains.length > 3 ? ` (+${chains.length - 3} more)` : ""}`;
24532
24697
  }
24533
- function assessDependency({ config, dependency, isSelfOrInternal, isTerminal, raw, refTypes, requiredPeerSources, sections, workspaceDir }) {
24698
+ function assessDependency({ config, dependency, importedPackages, isSelfOrInternal, isTerminal, raw, refTypes, requiredPeerSources, sections, workspaceDir }) {
24534
24699
  const dependencyRaw = raw.filter((finding) => finding.dependency === dependency);
24535
24700
  const signals = getDependencySignals(workspaceDir, dependency);
24536
24701
  if (signals !== void 0) dependencyRaw.push(...signals.findings);
24537
24702
  const peerSources = requiredPeerSources.get(dependency);
24538
- if (peerSources !== void 0 && !isSelfOrInternal(dependency) && !sections.dependencies.has(dependency)) dependencyRaw.push({
24539
- dependency,
24540
- evidence: requiredPeerEvidence(peerSources),
24541
- file: "(peer-chain)",
24542
- ruleId: "aei.signal.required-peer"
24543
- });
24544
- if (config.treeShaking && sections.sideEffectsFree && signals?.esm === true) dependencyRaw.push({
24703
+ if (peerSources !== void 0 && !isSelfOrInternal(dependency) && !sections.dependencies.has(dependency)) {
24704
+ const isForwarded = config.peerForwarding === "always" || importedPackages === void 0 || importedPackages.has(dependency);
24705
+ dependencyRaw.push(isForwarded ? {
24706
+ dependency,
24707
+ evidence: requiredPeerEvidence(peerSources),
24708
+ file: "(peer-chain)",
24709
+ ruleId: "aei.signal.required-peer"
24710
+ } : {
24711
+ dependency,
24712
+ evidence: `${requiredPeerEvidence(peerSources)} — never imported here; the installer resolves the contract (peerForwarding: when-used)`,
24713
+ file: "(peer-chain)",
24714
+ ruleId: "aei.signal.inherited-peer"
24715
+ });
24716
+ }
24717
+ if (config.treeShaking && sections.sideEffectsFree && signals?.esm === true && hasInstalledVersionMultiplicity(workspaceDir, dependency)) dependencyRaw.push({
24545
24718
  dependency,
24546
- evidence: "sideEffects: false package with ESM dependency — peers improve deduplication",
24719
+ evidence: "sideEffects: false package with ESM dependency installed at multiple versions — peers improve deduplication",
24547
24720
  file: "(package)",
24548
24721
  ruleId: "aei.modifier.tree-shaking"
24549
24722
  });
@@ -24552,6 +24725,7 @@ function assessDependency({ config, dependency, isSelfOrInternal, isTerminal, ra
24552
24725
  const resolved = resolveRecommendation(score.recommendation, findings, {
24553
24726
  config,
24554
24727
  dependency,
24728
+ importedPackages,
24555
24729
  isSelfOrInternal,
24556
24730
  isTerminal,
24557
24731
  raw,
@@ -24576,6 +24750,22 @@ function assessDependency({ config, dependency, isSelfOrInternal, isTerminal, ra
24576
24750
  };
24577
24751
  }
24578
24752
  /**
24753
+ * True when the unlisted dependency's exposure is provided (and
24754
+ * version-managed) by the package's declared sections. Runtime sections can
24755
+ * vouch for anything; devDependencies (e.g. `@types/express`) can only vouch
24756
+ * for purely type-level exposure — and a directly declared `@types/*`
24757
+ * spelling of the dependency itself (e.g. `@types/express-serve-static-core`
24758
+ * for exposure attributed to `express-serve-static-core`) is the most direct
24759
+ * provider of all.
24760
+ */
24761
+ function isProvidedBySections(dependency, findings, sections, workspaceDir) {
24762
+ if (findings.some((finding) => finding.ruleId === "aei.signal.required-peer")) return false;
24763
+ const aliases = typesAliasesOf(dependency);
24764
+ const targets = [dependency, ...aliases];
24765
+ const isTypeOnly = isTypeOnlyExposure(findings);
24766
+ 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);
24767
+ }
24768
+ /**
24579
24769
  * Applies the override precedence chain from spec section 11 to a scored
24580
24770
  * recommendation. Returns undefined when the assessment should be suppressed
24581
24771
  * entirely (the `aei.exposure.provided-transitive` reporting gate, off by
@@ -24584,10 +24774,13 @@ function assessDependency({ config, dependency, isSelfOrInternal, isTerminal, ra
24584
24774
  function resolveRecommendation(scored, findings, { config, dependency, isSelfOrInternal, isTerminal, refTypes, sections, workspaceDir }) {
24585
24775
  const classification = config.classificationFor(dependency) ?? refTypes?.get(dependency);
24586
24776
  if (classification !== void 0) return [classification === "peer" ? "peer" : "dependency", "override"];
24587
- if (isTerminal === true) return ["dependency", "terminal"];
24777
+ if (isTerminal === true) {
24778
+ if (sections.isPrivate && currentSectionOf(dependency, sections) === "devDependencies") return void 0;
24779
+ return ["dependency", "terminal"];
24780
+ }
24588
24781
  if (isSelfOrInternal(dependency)) return ["dependency", "workspace-internal"];
24589
24782
  if (dependency.startsWith("@types/")) return ["dependency", "types-package"];
24590
- 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;
24783
+ if (currentSectionOf(dependency, sections) === "unlisted" && isProvidedBySections(dependency, findings, sections, workspaceDir)) return config.ruleFor("aei.exposure.provided-transitive", dependency)?.enabled === true ? ["review", "provided"] : void 0;
24591
24784
  return [scored, "score"];
24592
24785
  }
24593
24786
  /**
@@ -24602,6 +24795,7 @@ function analyzeWorkspaceApiExposure({ cache, config, isTerminal, refTypes, work
24602
24795
  const requiredPeerSources = getRuntimeRootedNonOptionalTransitivePeerSources(workspaceDir, getDependenciesFromPackageJson(PATH.join(workspaceDir, "package.json")), { excludeSatisfiedInChain: true });
24603
24796
  const entryPoints = resolveEntryPoints(workspaceDir);
24604
24797
  const program = createExposureProgram(workspaceDir, entryPoints, cache);
24798
+ const importedPackages = program === void 0 || config.peerForwarding !== "when-used" ? void 0 : getImportedPackages(program, workspaceDir);
24605
24799
  const raw = [];
24606
24800
  if (program !== void 0) raw.push(...getExposureFindings({
24607
24801
  entryFiles: entryPoints,
@@ -24620,6 +24814,7 @@ function analyzeWorkspaceApiExposure({ cache, config, isTerminal, refTypes, work
24620
24814
  ])].filter((dependency) => dependency !== workspace.name).toSorted().map((dependency) => assessDependency({
24621
24815
  config,
24622
24816
  dependency,
24817
+ importedPackages,
24623
24818
  isSelfOrInternal,
24624
24819
  isTerminal,
24625
24820
  raw,
@@ -29101,6 +29296,15 @@ function resolvePeerDeclaredVersion(context, dep) {
29101
29296
  function shouldSkipAeiPeerDemotion(context, dep, version) {
29102
29297
  return context.isTerminalPackage || context.classifierMode !== "aei" || context.forcePeers.has(dep) || dep.startsWith("@types/") || version.startsWith("workspace:");
29103
29298
  }
29299
+ /**
29300
+ * A peer this package never imports is not a placement candidate — demoting
29301
+ * it into `dependencies` would immediately make it an unused dependency. If
29302
+ * it is genuinely unneeded, `dep.peerDependencies.unused` removes it instead.
29303
+ */
29304
+ function isImportedAnywhere(context, dep) {
29305
+ const { externalAllImports, externalDistImports, externalDistTypeImports } = context.sourceParams;
29306
+ return externalAllImports.includes(dep) || externalDistImports.includes(dep) || externalDistTypeImports.includes(dep);
29307
+ }
29104
29308
  function evaluateMisplacedPeer(context, dep, version) {
29105
29309
  if (context.forceDeps.has(dep)) return {
29106
29310
  alreadyInTarget: context.packageParams.dependencies.includes(dep),
@@ -29124,6 +29328,7 @@ function evaluateMisplacedPeer(context, dep, version) {
29124
29328
  version
29125
29329
  };
29126
29330
  if (shouldSkipAeiPeerDemotion(context, dep, version)) return void 0;
29331
+ if (!isImportedAnywhere(context, dep)) return void 0;
29127
29332
  if (context.classifyDependency(dep) !== "dependency") return void 0;
29128
29333
  return {
29129
29334
  alreadyInTarget: context.packageParams.dependencies.includes(dep),
@@ -29593,12 +29798,12 @@ const unsatisfiedPeersRule = {
29593
29798
  severity: "error"
29594
29799
  },
29595
29800
  evaluate(context) {
29596
- const findings = findUnsatisfiedPeers(context.workspace, context.packageParams, context.exclude, context.isTerminalPackage, context.forcePeerOptional, context.forceDevs);
29801
+ const findings = findUnsatisfiedPeers(context.workspace, context.packageParams, context.exclude, context.isTerminalPackage, context.forcePeerOptional, context.forceDevs, context.peerForwarding);
29597
29802
  for (const finding of findings) {
29598
29803
  const requiredBy = finding.sources.map((source) => source.requiredBy).join(", ");
29599
29804
  const chain = finding.sources.find((source) => (source.chain && source.chain.length > 0) ?? false)?.chain?.join(" -> ");
29600
29805
  const evidence = chain != null && chain.length > 0 ? [`via ${chain}`] : void 0;
29601
- 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`;
29806
+ 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`;
29602
29807
  context.report({
29603
29808
  data: { finding },
29604
29809
  dependency: finding.peer,
@@ -29978,8 +30183,16 @@ function buildWorkspaceContext(workspace, options = {}) {
29978
30183
  const packageMetaStarted = performance.now();
29979
30184
  const packageJsonPath = `${workspace.location}/package.json`;
29980
30185
  const packageParams = getDependenciesFromPackageJson(packageJsonPath);
30186
+ const peerForwarding = options.classifier === "aei" && options.apiExposureConfig?.peerForwarding === "when-used" ? {
30187
+ importedModules: /* @__PURE__ */ new Set([
30188
+ ...sourceParams.externalAllImports,
30189
+ ...sourceParams.externalDistImports,
30190
+ ...sourceParams.externalDistTypeImports
30191
+ ]),
30192
+ mode: "when-used"
30193
+ } : void 0;
29981
30194
  const requiredTransitivePeers = getRequiredNonOptionalTransitivePeers(workspace.location, packageParams);
29982
- const runtimeRootedRequired = getRuntimeRootedNonOptionalTransitivePeers(workspace.location, packageParams);
30195
+ const runtimeRootedRequired = new Set([...getRuntimeRootedNonOptionalTransitivePeers(workspace.location, packageParams)].filter((peer) => isPeerForwarded(peerForwarding, peer)));
29983
30196
  const packageClassification = classifyDeplintPackage(workspace.location, terminalOverride);
29984
30197
  if (phases !== void 0) phases.packageMetaMs = performance.now() - packageMetaStarted;
29985
30198
  return {
@@ -29999,6 +30212,7 @@ function buildWorkspaceContext(workspace, options = {}) {
29999
30212
  packageKind: packageClassification.kind,
30000
30213
  packageJsonPath,
30001
30214
  packageParams,
30215
+ peerForwarding,
30002
30216
  peerRangeBound: options.peerRangeBound,
30003
30217
  peerRangeForm: options.peerRangeForm ?? "shorthand",
30004
30218
  sourceParams,