Skip to content

Commit 524c074

Browse files
committed
chore(gates): forbid plugin framework dependencies on provider packages
R85 rejects manifest entries and static, type-only, dynamic and mocked imports from packages/plugins to any packages/provider-* package, and declares the new root policy module's zone.
1 parent 9294c0a commit 524c074

4 files changed

Lines changed: 194 additions & 0 deletions

File tree

‎scripts/layering/check.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,7 @@ import { sourceExecutionCompatibilityViolations } from './source-execution-polic
161161
import { sessionResourceOwnershipViolations } from './session-resource-ownership.ts';
162162
import { applicationLifecycleOwnershipViolations } from './application-lifecycle-policy.ts';
163163
import { iosSnapshotEngineOwnershipViolations } from './ios-snapshot-engine-policy.ts';
164+
import { checkPluginFrameworkIndependence } from './plugin-framework-independence.ts';
164165
import { providerSnapshotPresentationViolations } from './provider-snapshot-presentation-policy.ts';
165166
import { snapshotAssemblyPresentationViolations } from './snapshot-assembly-presentation-policy.ts';
166167
import { RETIRED_PATH_RULES, retiredPathRuleViolations } from './retired-paths-policy.ts';
@@ -539,6 +540,7 @@ export const LAYERING_RULE_IDS = [
539540
'session-authority-overlay',
540541
'daemon-layers',
541542
'package-export-surface',
543+
'plugin-framework-independence',
542544
'test-colocation',
543545
] as const;
544546

@@ -620,6 +622,11 @@ export const LAYERING_RULES: Readonly<Record<LayeringRuleId, LayeringRule>> = {
620622
),
621623
...checkTestKitIsolation(readTrackedPackageManifests(repoRoot), context.allTypeScriptSources),
622624
],
625+
'plugin-framework-independence': (context) =>
626+
checkPluginFrameworkIndependence(
627+
readTrackedPackageManifests(repoRoot),
628+
context.allTypeScriptSources,
629+
),
623630
'test-colocation': (context) =>
624631
checkTestColocation(context.ratchets.unmatchedTests, context.reference.unmatchedTests),
625632
};
Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
// R85: the plugin framework imports and declares no concrete provider package.
2+
3+
import assert from 'node:assert/strict';
4+
import fs from 'node:fs';
5+
import path from 'node:path';
6+
import { test } from 'node:test';
7+
import {
8+
checkPluginFrameworkIndependence,
9+
PLUGIN_FRAMEWORK_INDEPENDENCE_RULE,
10+
} from './plugin-framework-independence.ts';
11+
import { readTrackedPackageManifests } from './package-boundaries.ts';
12+
import { listTrackedTypeScriptFiles } from './tracked-sources.ts';
13+
14+
const repoRoot = path.resolve(import.meta.dirname, '../..');
15+
const PROVIDER_ENTRY = "'@agent-device/provider-webdriver/plugin'";
16+
17+
function manifests(plugins: Record<string, unknown> = {}): Map<string, string> {
18+
return new Map([
19+
[
20+
'packages/plugins/package.json',
21+
JSON.stringify({ name: '@agent-device/plugins', ...plugins }),
22+
],
23+
[
24+
'packages/provider-webdriver/package.json',
25+
JSON.stringify({ name: '@agent-device/provider-webdriver' }),
26+
],
27+
['packages/provider-testmu/package.json', JSON.stringify({ name: '@agent-device/testmu' })],
28+
['packages/kernel/package.json', JSON.stringify({ name: '@agent-device/kernel' })],
29+
]);
30+
}
31+
32+
function check(source: string, file = 'packages/plugins/src/load.ts') {
33+
return checkPluginFrameworkIndependence(manifests(), new Map([[file, source]]));
34+
}
35+
36+
test('the real plugin framework declares and imports no provider package', () => {
37+
const sources = new Map(
38+
listTrackedTypeScriptFiles(repoRoot).map((file) => [
39+
file,
40+
fs.readFileSync(path.join(repoRoot, file), 'utf8'),
41+
]),
42+
);
43+
assert.deepEqual(
44+
checkPluginFrameworkIndependence(readTrackedPackageManifests(repoRoot), sources),
45+
[],
46+
);
47+
});
48+
49+
test('R85 rejects a static, type-only, dynamic, re-export, inline-type or mocked provider import', () => {
50+
for (const source of [
51+
`import { createCloudWebDriverRuntime } from ${PROVIDER_ENTRY};`,
52+
`import type { CloudWebDriverProviderOptions } from ${PROVIDER_ENTRY};`,
53+
`const { createCloudWebDriverRuntime } = await import(${PROVIDER_ENTRY});`,
54+
`export { createCloudWebDriverRuntime } from ${PROVIDER_ENTRY};`,
55+
`type Options = import(${PROVIDER_ENTRY}).CloudWebDriverProviderOptions;`,
56+
`vi.mock(${PROVIDER_ENTRY}, () => ({}));`,
57+
`import plugin from '@agent-device/testmu';`,
58+
]) {
59+
const [result, ...rest] = check(source);
60+
assert.equal(rest.length, 0, source);
61+
assert.equal(result?.rule, PLUGIN_FRAMEWORK_INDEPENDENCE_RULE, source);
62+
assert.equal(result?.file, 'packages/plugins/src/load.ts', source);
63+
}
64+
});
65+
66+
test('R85 rejects a provider package listed in any dependency field of the plugins manifest', () => {
67+
for (const field of [
68+
'dependencies',
69+
'devDependencies',
70+
'optionalDependencies',
71+
'peerDependencies',
72+
]) {
73+
const result = checkPluginFrameworkIndependence(
74+
manifests({ [field]: { '@agent-device/provider-webdriver': 'workspace:*' } }),
75+
new Map(),
76+
);
77+
assert.deepEqual(
78+
result.map(({ file }) => file),
79+
['packages/plugins/package.json'],
80+
field,
81+
);
82+
}
83+
});
84+
85+
test('R85 admits the foundations the framework builds on and imports elsewhere in the repo', () => {
86+
assert.deepEqual(check(`import { AppError } from '@agent-device/kernel/errors';`), []);
87+
assert.deepEqual(
88+
checkPluginFrameworkIndependence(
89+
manifests({ dependencies: { '@agent-device/kernel': 'workspace:*' } }),
90+
new Map([
91+
['src/provider-plugin-policy.ts', `import('@agent-device/provider-webdriver/plugin');`],
92+
]),
93+
),
94+
[],
95+
);
96+
});
Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
// Catches: `@agent-device/plugins` — the manifest, store, host and loader every provider plugin
2+
// runs under — acquiring a dependency on a concrete provider package, whether as a manifest entry
3+
// or as a static, type-only, dynamic or `vi.mock` import. Bundled-provider knowledge (which ids
4+
// plugins may not claim, how a `{ webDriver }` factory result becomes a runtime) belongs to the
5+
// composition that selects providers, which hands it to the loader as a policy.
6+
// Evidence: #3712 extracted the loader with `provider-webdriver` still imported by its manifest and
7+
// loader; the provider-independence follow-up moved that knowledge to src/provider-plugin-policy.ts.
8+
// Cost: one pass over the tracked manifests and the plugins package's sources.
9+
// Kill criterion: a maintainer decision that the plugin framework may depend on a concrete
10+
// provider, or that provider-* packages stop being the unit of provider implementation.
11+
//
12+
// The forbidden set is derived from the workspace layout, not from name patterns: every package
13+
// under `packages/provider-*`, whatever name it publishes (e.g. `@agent-device/testmu`).
14+
15+
import type { LayeringViolation } from './model.ts';
16+
import { specifierSites } from './package-boundaries.ts';
17+
18+
export const PLUGIN_FRAMEWORK_INDEPENDENCE_RULE = 'R85 plugin-framework-independence';
19+
20+
const PLUGINS_DIR = 'packages/plugins';
21+
const PROVIDER_MANIFEST = /^packages\/provider-[^/]+\/package\.json$/;
22+
23+
type DependencyManifest = {
24+
name?: string;
25+
dependencies?: Record<string, string>;
26+
devDependencies?: Record<string, string>;
27+
optionalDependencies?: Record<string, string>;
28+
peerDependencies?: Record<string, string>;
29+
};
30+
31+
function declaredNames(manifest: DependencyManifest): string[] {
32+
return [
33+
...Object.keys(manifest.dependencies ?? {}),
34+
...Object.keys(manifest.devDependencies ?? {}),
35+
...Object.keys(manifest.optionalDependencies ?? {}),
36+
...Object.keys(manifest.peerDependencies ?? {}),
37+
];
38+
}
39+
40+
function packageName(specifier: string): string {
41+
const parts = specifier.split('/');
42+
return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0]!;
43+
}
44+
45+
function violation(file: string, line: number, message: string): LayeringViolation {
46+
return { rule: PLUGIN_FRAMEWORK_INDEPENDENCE_RULE, file, line, message };
47+
}
48+
49+
/** The plugin framework package declares and imports no `packages/provider-*` package. */
50+
export function checkPluginFrameworkIndependence(
51+
manifests: ReadonlyMap<string, string>,
52+
sources: ReadonlyMap<string, string>,
53+
): LayeringViolation[] {
54+
const providers = new Set<string>();
55+
for (const [file, text] of manifests) {
56+
const { name } = JSON.parse(text) as DependencyManifest;
57+
if (PROVIDER_MANIFEST.test(file) && name) providers.add(name);
58+
}
59+
60+
const violations: LayeringViolation[] = [];
61+
const pluginsManifest = `${PLUGINS_DIR}/package.json`;
62+
const manifest = manifests.get(pluginsManifest);
63+
for (const name of manifest ? declaredNames(JSON.parse(manifest) as DependencyManifest) : []) {
64+
if (providers.has(name)) {
65+
violations.push(
66+
violation(
67+
pluginsManifest,
68+
1,
69+
`${name} is a provider package; the plugin framework must not declare it. ` +
70+
`Provider knowledge reaches the loader as a policy from the composing root.`,
71+
),
72+
);
73+
}
74+
}
75+
for (const [file, source] of sources) {
76+
if (!file.startsWith(`${PLUGINS_DIR}/`)) continue;
77+
for (const site of specifierSites(file, source)) {
78+
if (!providers.has(packageName(site.specifier))) continue;
79+
violations.push(
80+
violation(
81+
file,
82+
site.line,
83+
`${site.specifier} is a provider package; the plugin framework must not import it ` +
84+
`(static, type-only, dynamic or mocked). Pass provider knowledge in as a policy from the composing root.`,
85+
),
86+
);
87+
}
88+
}
89+
return violations;
90+
}

‎scripts/layering/root-module-zones.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ export const ROOT_MODULE_ZONES: Readonly<Record<string, readonly string[]>> = {
5151
'src/provider-credential-fingerprint.ts',
5252
'src/provider-device-runtimes.ts',
5353
'src/provider-limrun-credentials.ts',
54+
'src/provider-plugin-policy.ts',
5455
'src/provider-webdriver.ts',
5556
],
5657
// The operation host the platform runtime loads through `import()` (`loadHost`) and its facets.

0 commit comments

Comments
 (0)