@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/actions/api-exposure/analyzer/analyzePackage.d.ts.map +1 -1
- package/dist/actions/api-exposure/analyzer/depSignals.d.ts +8 -0
- package/dist/actions/api-exposure/analyzer/depSignals.d.ts.map +1 -1
- package/dist/actions/api-exposure/analyzer/exposureWalk.d.ts.map +1 -1
- package/dist/actions/api-exposure/analyzer/importedPackages.d.ts +15 -0
- package/dist/actions/api-exposure/analyzer/importedPackages.d.ts.map +1 -0
- package/dist/actions/api-exposure/analyzer/structuralType.d.ts +9 -0
- package/dist/actions/api-exposure/analyzer/structuralType.d.ts.map +1 -0
- package/dist/actions/api-exposure/config.d.ts +3 -1
- package/dist/actions/api-exposure/config.d.ts.map +1 -1
- package/dist/actions/api-exposure/rules.d.ts.map +1 -1
- package/dist/actions/deplint/checkPackage/getUnsatisfiedPeerDependencies.d.ts +18 -1
- package/dist/actions/deplint/checkPackage/getUnsatisfiedPeerDependencies.d.ts.map +1 -1
- package/dist/actions/deplint/rules.d.ts.map +1 -1
- package/dist/actions/deplint/rulesMisplaced.d.ts.map +1 -1
- package/dist/actions/deplint/snapshot.d.ts.map +1 -1
- package/dist/actions/deplint/types.d.ts +7 -1
- package/dist/actions/deplint/types.d.ts.map +1 -1
- package/dist/actions/package/compile/ApiExposureConfig.d.ts +16 -0
- package/dist/actions/package/compile/ApiExposureConfig.d.ts.map +1 -1
- package/dist/bin/skills.mjs +2073 -1205
- package/dist/bin/skills.mjs.map +1 -1
- package/dist/bin/xy.mjs +256 -42
- package/dist/bin/xy.mjs.map +1 -1
- package/package.json +6 -6
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
|
-
|
|
23282
|
-
|
|
23283
|
-
|
|
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
|
|
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
|
-
|
|
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,
|
|
24245
|
-
|
|
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,
|
|
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,
|
|
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,
|
|
24369
|
+
if (parameterType !== void 0) collectTypeDependencies(parameterType, kind, depth + 1, context);
|
|
24265
24370
|
}
|
|
24266
|
-
collectTypeDependencies(signature.getReturnType(),
|
|
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,
|
|
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
|
-
|
|
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,
|
|
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,
|
|
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,
|
|
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(([,
|
|
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,
|
|
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
|
-
|
|
24490
|
-
|
|
24491
|
-
|
|
24492
|
-
|
|
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,
|
|
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.
|
|
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))
|
|
24539
|
-
dependency
|
|
24540
|
-
|
|
24541
|
-
|
|
24542
|
-
|
|
24543
|
-
|
|
24544
|
-
|
|
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)
|
|
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 (
|
|
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,
|