Repository navigation
Expand file tree
/
Copy pathplatform-package-policy.ts
More file actions
411 lines (388 loc) · 17.5 KB
/
Copy pathplatform-package-policy.ts
File metadata and controls
411 lines (388 loc) · 17.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
// Catches: a platform package's private implementation loaded before the one canonical
// composition root assembles it, or a cross-boundary edge into another platform family's
// private surface — the six platform packages moved behind package facades (#2116-#2125)
// specifically to make eager loading and cross-family reach-ins visible, and only a source
// walk over every package's imports can confirm the boundary actually held.
// Evidence: 838ed223b5 (#2116) moved the six W6 platform families behind package facades;
// ed26b31c94 (#2125) contracted the Apple platform surface to match.
// Cost: 1030 LOC (377 rule + 653 test); shared with platform-composition-policy.ts (103 LOC)
// and platform-package-source-policy.ts (230 LOC), which this module orchestrates.
// Kill criterion: none enforced today; retire only by maintainer decision that platform-family
// isolation (private manifests with exact exports, static imports only from the composition
// root, no sibling-family reach-ins, no top-level loadInventory/loadRuntime) no longer
// matters. Publishing the families separately would not replace it: the A4 spike found an
// undeclared workspace package still resolves through root node_modules and a relative tunnel
// into a sibling's src still compiles; project references are a build cache, not a boundary.
import path from 'node:path';
import { DAEMON_SOURCE_ROOT } from './tracked-sources.ts';
import { PLATFORMS } from '@agent-device/kernel/device';
import { parseImports, type LayeringViolation } from './model.ts';
import { checkPlatformComposition } from './platform-composition-policy.ts';
import { checkPlatformPackageSourcePolicy } from './platform-package-source-policy.ts';
import { retiredPathViolations } from './retired-zone-policy.ts';
export const CANONICAL_PLATFORM_FAMILIES = PLATFORMS;
type PlatformFamily = (typeof CANONICAL_PLATFORM_FAMILIES)[number];
export type PlatformPackageDeclaration = {
dir: string;
family: string;
name: string;
private: boolean;
exportedSubpaths: readonly string[];
};
const COMPOSITION_FILE = 'src/platform-runtime.ts';
const REQUEST_PROVIDER_COMPOSITION_FILE = 'src/platform-runtime/request-providers.ts';
const COMPOSITION_FILES = new Set([COMPOSITION_FILE, REQUEST_PROVIDER_COMPOSITION_FILE]);
const RULE = 'R13 platform-package-substrate';
const RAW_PROCESS_SPECIFIERS = new Set(['child_process', 'node:child_process']);
const PLATFORM_RUNTIME_HOST_FILES = new Set([
'src/platform-runtime-audio-probe-host.ts',
'src/platform-runtime-host-diagnostics.ts',
'src/platform-runtime-managed-web-backend.ts',
'src/platform-runtime-network-web-transport.ts',
'src/platform-runtime-operation-host.ts',
'src/platform-runtime-perf-host.ts',
'src/platform-runtime-resource-cleanup.ts',
'src/platform-runtime-screen-recording-harmony-host.ts',
'src/platform-runtime-screen-recording-web-host.ts',
'src/platform-runtime-toolchain-host.ts',
]);
// #2040: the Apple XCUITest runner client is a platform-owned implementation
// facet colocated in platform-apple as the src/runner/ subtree. Its subpaths
// are the enumerated seam through which daemon/root consumers reach runner
// mechanics directly (the runner-consumer migration behind the composition
// gateway has no owner today; if one retires those direct consumers, the seam
// narrows with it — the facet itself is durable Apple ownership, not a
// temporary exception).
export const APPLE_RUNNER_SUBTREE = 'packages/platform-apple/src/runner/';
export function checkRetiredPlatformsZone(files: readonly string[]): LayeringViolation[] {
return retiredPathViolations(
files,
'src/platforms',
'retired-platforms-zone',
'src/platforms is retired; family code belongs in its platform package, shared mechanics in an owning substrate package, and cross-family tests in their root or package test owner',
);
}
const APPLE_RUNNER_FACADE = '@agent-device/platform-apple/runner';
const APPLE_RUNNER_TEST_HOST = '@agent-device/platform-apple/runner/test-host';
const APPLE_RUNNER_TEST_HOST_INSTALLER = 'scripts/vitest-apple-runner-host-setup.ts';
const ANDROID_MECHANICS_FACADE = '@agent-device/platform-android/mechanics';
const ANDROID_HOST_FACET = '@agent-device/platform-android/adb-host';
const ANDROID_HOST_BINDING = 'src/platform-runtime-android-adb-host.ts';
const ANDROID_DEVICE_BOOT_FACADE = '@agent-device/platform-android/device-boot';
const MECHANICS_FACET_SUBPATHS: Readonly<Partial<Record<PlatformFamily, readonly string[]>>> = {
apple: [
APPLE_RUNNER_FACADE,
APPLE_RUNNER_TEST_HOST,
'@agent-device/platform-apple/app-lifecycle',
'@agent-device/platform-apple/app-resolution',
'@agent-device/platform-apple/debug-symbols',
'@agent-device/platform-apple/doctor',
'@agent-device/platform-apple/install-artifact',
'@agent-device/platform-apple/macos',
'@agent-device/platform-apple/perf',
'@agent-device/platform-apple/physical-device',
'@agent-device/platform-apple/runner-owner',
'@agent-device/platform-apple/runner/operations',
'@agent-device/platform-apple/runner/requests-fixtures',
'@agent-device/platform-apple/session-observation',
'@agent-device/platform-apple/snapshot-source',
'@agent-device/platform-apple/simctl',
'@agent-device/platform-apple/simctl-settings',
'@agent-device/platform-apple/simulator',
'@agent-device/platform-apple/simulator-boot',
'@agent-device/platform-apple/tool-provider',
],
android: [ANDROID_HOST_FACET, ANDROID_MECHANICS_FACADE, ANDROID_DEVICE_BOOT_FACADE],
};
// Test-only entries: the shared Android capture/walk fixtures (#3517). They ride export
// validation with the facets above but not its consumer set: only non-production files
// may import them, so `src/commands/` style production code importing a fixture trips R13.
const ANDROID_TEST_ONLY_SUBPATHS: readonly string[] = [
'@agent-device/platform-android/snapshot-capture-fixtures',
'@agent-device/platform-android/ui-hierarchy-fixtures',
];
function isAndroidFacetSubpathImport(file: string, specifier: string): boolean {
if (specifier === ANDROID_HOST_FACET) return file === ANDROID_HOST_BINDING;
if (ANDROID_TEST_ONLY_SUBPATHS.includes(specifier)) return isNonProductionConsumer(file);
if (!(MECHANICS_FACET_SUBPATHS.android ?? []).includes(specifier)) return false;
// The named facets are the implementation seam for root/core/SDK consumers. Daemon production
// code still reaches platform behavior through the request-bound runtime gateway; tests may
// import a facet to exercise the package-owned mechanics directly.
return !file.startsWith(DAEMON_SOURCE_ROOT) || !isProductionSource(file);
}
function isAppleFacadeSubpathImport(specifier: string): boolean {
return MECHANICS_FACET_SUBPATHS.apple?.includes(specifier) ?? false;
}
function violation(file: string, line: number, message: string): LayeringViolation {
return { rule: RULE, file, line, message };
}
function packageName(family: PlatformFamily): string {
return `@agent-device/platform-${family}`;
}
function packageDir(family: PlatformFamily): string {
return `packages/platform-${family}`;
}
function familyForPackageFile(file: string): string | undefined {
return /^packages\/platform-([^/]+)\//.exec(file)?.[1];
}
function isProductionSource(file: string): boolean {
return !file.endsWith('.test.ts') && !file.includes('/__tests__/');
}
function isNonProductionConsumer(file: string): boolean {
return !isProductionSource(file) || file.startsWith('test/');
}
function concretePlatformFamily(specifier: string): string | undefined {
return /^@agent-device\/platform-([^/]+)(?:\/|$)/.exec(specifier)?.[1];
}
function resolvesOutsidePackage(file: string, specifier: string, family: string): boolean {
if (!specifier.startsWith('.')) return false;
const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(file), specifier));
return !resolved.startsWith(`packages/platform-${family}/`);
}
function resolvesToRequestProviderComposition(file: string, specifier: string): boolean {
if (!specifier.startsWith('.')) return false;
const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(file), specifier));
return resolved === REQUEST_PROVIDER_COMPOSITION_FILE;
}
function isPackageOwnedFacadeTest(file: string, family: string, specifier: string): boolean {
return (
file.startsWith(`packages/platform-${family}/`) &&
(file.endsWith('.test.ts') || file.includes('/__tests__/')) &&
specifier === `@agent-device/platform-${family}`
);
}
function isWebPackageTestSelectorImport(file: string, family: string, specifier: string): boolean {
return (
family === 'web' &&
file.startsWith('packages/platform-web/') &&
(file.endsWith('.test.ts') || file.includes('/__tests__/')) &&
specifier === '@agent-device/selectors'
);
}
function checkDeclarations(packages: readonly PlatformPackageDeclaration[]): LayeringViolation[] {
const violations: LayeringViolation[] = [];
for (const family of CANONICAL_PLATFORM_FAMILIES) {
const expectedDir = packageDir(family);
const matches = packages.filter((pkg) => pkg.dir === expectedDir);
if (matches.length === 0) {
violations.push(
violation(expectedDir, 1, `missing canonical platform package ${expectedDir}`),
);
continue;
}
if (matches.length > 1) {
violations.push(violation(expectedDir, 1, `${expectedDir} is declared more than once`));
continue;
}
const declaration = matches[0]!;
const expectedName = packageName(family);
if (declaration.name !== expectedName) {
violations.push(
violation(
`${expectedDir}/package.json`,
1,
`${expectedDir} must be named '${expectedName}', found '${declaration.name}'`,
),
);
}
if (!declaration.private) {
violations.push(
violation(`${expectedDir}/package.json`, 1, `${expectedDir} must be private`),
);
}
const expectedSubpaths = [
expectedName,
...(MECHANICS_FACET_SUBPATHS[family] ?? []),
...(family === 'android' ? ANDROID_TEST_ONLY_SUBPATHS : []),
];
if (
declaration.exportedSubpaths.length !== expectedSubpaths.length ||
expectedSubpaths.some((subpath) => !declaration.exportedSubpaths.includes(subpath))
) {
violations.push(
violation(
`${expectedDir}/package.json`,
1,
`${expectedDir} must export exactly its root façade '${expectedName}'` +
(expectedSubpaths.length > 1 ? ` plus its enumerated mechanics subpaths` : ''),
),
);
}
}
for (const declaration of packages) {
if (!declaration.dir.startsWith('packages/platform-')) continue;
const family = declaration.dir.slice('packages/platform-'.length);
if (!(CANONICAL_PLATFORM_FAMILIES as readonly string[]).includes(family)) {
violations.push(
violation(declaration.dir, 1, `${declaration.dir} is not a canonical platform family`),
);
}
}
return violations;
}
function checkSource(file: string, source: string): LayeringViolation[] {
const violations: LayeringViolation[] = [];
const ownerFamily = familyForPackageFile(file);
// The runner mechanics facet owns its cache/lease files and usbmux sockets
// (fs/net/os) and reads process identity directly — that ownership is part
// of the facet's definition, so the ambient-host rules do not apply to it.
// Raw process primitives stay banned below and host tooling still enters
// through the AppleRunnerHost port.
if (ownerFamily && isProductionSource(file) && !file.startsWith(APPLE_RUNNER_SUBTREE)) {
violations.push(...checkPlatformPackageSourcePolicy(file, source, ownerFamily));
}
for (const site of parseImports(source)) {
if (resolvesToRequestProviderComposition(file, site.spec) && file !== COMPOSITION_FILE) {
violations.push(
violation(
file,
site.line,
`only ${COMPOSITION_FILE} may import the private request-provider composition submodule`,
),
);
}
const importedFamily = concretePlatformFamily(site.spec);
if (file.startsWith('packages/contracts/') && importedFamily) {
violations.push(
violation(
file,
site.line,
`contracts may never import a concrete platform package ('${site.spec}')`,
),
);
}
if (file.startsWith('packages/provision-kit/') && importedFamily) {
violations.push(
violation(
file,
site.line,
`only ${COMPOSITION_FILE} or its governed request-provider composition submodule may import '${site.spec}' outside its package-owned tests`,
),
);
}
if (site.spec === APPLE_RUNNER_TEST_HOST && file !== APPLE_RUNNER_TEST_HOST_INSTALLER) {
violations.push(
violation(
file,
site.line,
`'${APPLE_RUNNER_TEST_HOST}' installs the runner test host dispatcher — only ${APPLE_RUNNER_TEST_HOST_INSTALLER} may import it`,
),
);
} else if (
importedFamily &&
!COMPOSITION_FILES.has(file) &&
// Named platform facades are the package's consumer seams. R11's
// workspace-dependency declarations bound the importer set to the root
// package.
!isAppleFacadeSubpathImport(site.spec) &&
!isAllowedPlatformRootImport(file, site, importedFamily) &&
!isPackageOwnedFacadeTest(file, importedFamily, site.spec) &&
!isAndroidFacetSubpathImport(file, site.spec)
) {
violations.push(
violation(
file,
site.line,
site.spec === `@agent-device/platform-${importedFamily}`
? `production static imports of '${site.spec}' are limited to ${COMPOSITION_FILE} and src/core/interactors/; other value edges require a deferred import from an approved platform-runtime host file`
: `only ${COMPOSITION_FILE} or its governed request-provider composition submodule may import '${site.spec}' outside its package-owned tests`,
),
);
}
if (!ownerFamily) continue;
if (
site.spec.startsWith('@agent-device/') &&
!site.spec.startsWith('@agent-device/contracts/') &&
site.spec !== '@agent-device/capture-kit' &&
!site.spec.startsWith('@agent-device/capture-kit/') &&
!site.spec.startsWith('@agent-device/host-kit/') &&
!site.spec.startsWith('@agent-device/provision-kit/') &&
!site.spec.startsWith('@agent-device/kernel/') &&
site.spec !== '@agent-device/xml' &&
!isAppleFacadeSubpathImport(site.spec) &&
!isPackageOwnedFacadeTest(file, ownerFamily, site.spec) &&
!isWebPackageTestSelectorImport(file, ownerFamily, site.spec)
) {
violations.push(
violation(
file,
site.line,
`platform-${ownerFamily} may import workspace code only from capture-kit, host-kit, provision-kit, contracts, kernel, or xml; found '${site.spec}'`,
),
);
}
if (importedFamily && importedFamily !== ownerFamily) {
violations.push(
violation(file, site.line, `platform-${ownerFamily} may not import sibling '${site.spec}'`),
);
}
if (
resolvesOutsidePackage(file, site.spec, ownerFamily) ||
/^agent-device(?:\/|$)/.test(site.spec)
) {
violations.push(
violation(file, site.line, `platform-${ownerFamily} may not reach root or daemon code`),
);
}
// Production value-imports only: package tests fake process primitives
// (they intercept, not spawn), and the runner host port names ChildProcess
// as a type. The spawn ban is about mechanics bypassing the host-command
// port at runtime.
if (RAW_PROCESS_SPECIFIERS.has(site.spec) && isProductionSource(file) && !site.typeOnly) {
violations.push(
violation(
file,
site.line,
`platform-${ownerFamily} may not import raw process primitives ('${site.spec}'); use the host-command port`,
),
);
}
if (
file === `packages/platform-${ownerFamily}/src/index.ts` &&
!site.dynamic &&
!site.typeOnly
) {
violations.push(
violation(
file,
site.line,
`platform-${ownerFamily} facade must not eagerly evaluate '${site.spec}'`,
),
);
}
}
return violations;
}
function isAllowedPlatformRootImport(
file: string,
site: { spec: string; dynamic: boolean; typeOnly: boolean },
family: string,
): boolean {
if (site.spec !== `@agent-device/platform-${family}`) return false;
return (
isNonProductionConsumer(file) ||
file.startsWith('src/core/interactors/') ||
(PLATFORM_RUNTIME_HOST_FILES.has(file) && (site.dynamic || site.typeOnly))
);
}
export function checkPlatformPackagePolicy(
sources: ReadonlyMap<string, string>,
packages: readonly PlatformPackageDeclaration[],
options: { untrackedProductionFiles?: readonly string[] } = {},
): LayeringViolation[] {
return [
...(options.untrackedProductionFiles ?? []).map((file) =>
violation(
file,
1,
'untracked production source is not committed-state layering evidence; commit the complete slice before running the gate',
),
),
...checkDeclarations(packages),
...checkPlatformComposition(sources.get(COMPOSITION_FILE)),
...[...sources].flatMap(([file, source]) => checkSource(file, source)),
];
}
export function platformPackagePolicySummary(): string {
return 'R13 holds six private implementation-lazy platform packages above capture-kit behind one canonical composition root and its single private provider-composition submodule, with the apple runner and android mechanics facets behind their enumerated seams; deferred or type-only edges are limited to the approved platform-runtime host watchlist';
}