Skip to content

Commit 952bc37

Browse files
refactor: keep command and daemon-route owner-file claims tooling-only (#1178) (#1192)
* refactor(command-descriptor): keep owner-file claims tooling-only Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * refactor(daemon): keep daemon-route owner-file claims tooling-only Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * test(daemon): guard against re-adding owner-file paths to the production route chain Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * refactor(command-descriptor): derive owner-file projection from colocated RAW_COMMAND_DESCRIPTORS - Keep ownerFiles on each RAW_COMMAND_DESCRIPTORS entry as the source of truth. - Add tooling-only __OWNER_FILES__ build flag so production bundles omit the ownerFiles properties entirely. - Derive COMMAND_OWNER_FILES from RAW_COMMAND_DESCRIPTORS instead of a hand-maintained parallel table. - Guard command-explain tests against leaking ownerFiles into production descriptor objects. - Enable treeshake.propertyReadSideEffects: false in tsdown to help drop the dead ownerFiles branch from production bundles. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * chore: apply oxfmt formatting Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * test(build): guard tooling metadata exclusion Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * refactor(command-descriptor): drop global treeshake option and add bundle guard - Remove treeshake.propertyReadSideEffects from tsdown.config.ts; the __OWNER_FILES__ define + conditional spread already keeps owner files out of the bundle, so the global DCE lever is unnecessary and scope-creeping. - Add a comment on the __OWNER_FILES__ global declaration explaining the deliberate type-versus-runtime mismatch. - Add test/output-economy/owner-files-no-leak.test.ts to build dist and assert that no command or daemon-route owner-file path appears in the emitted JS. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * fix(build): remove owner metadata property reads Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * fix(command-descriptor): enforce owner claim totality Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --------- Co-authored-by: Michał Pierzchała <[email protected]> Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
1 parent 973df8a commit 952bc37

16 files changed

Lines changed: 348 additions & 120 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,7 @@ jobs:
150150
- name: Build and pack CLI
151151
run: |
152152
pnpm build
153+
pnpm check:bundle-owner-files
153154
mkdir -p .tmp/node-compat
154155
npm pack --ignore-scripts --pack-destination .tmp/node-compat
155156

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,11 +121,12 @@
121121
"check:layering:baseline": "node --experimental-strip-types scripts/layering/check.ts --update-baseline",
122122
"check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --baseline fallow-baselines/production-unused-exports.json --fail-on-issues",
123123
"check:production-exports:baseline": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --save-baseline fallow-baselines/production-unused-exports.json --summary",
124+
"check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts",
124125
"check:quick": "pnpm lint && pnpm typecheck",
125126
"sync:mcp-metadata": "node scripts/sync-mcp-metadata.mjs",
126127
"check:mcp-metadata": "node scripts/sync-mcp-metadata.mjs --check",
127128
"version": "node scripts/sync-mcp-metadata.mjs && git add server.json",
128-
"check:tooling": "pnpm lint && pnpm typecheck && pnpm check:layering && pnpm check:production-exports && pnpm check:mcp-metadata && pnpm build",
129+
"check:tooling": "pnpm lint && pnpm typecheck && pnpm check:layering && pnpm check:production-exports && pnpm check:mcp-metadata && pnpm build && pnpm check:bundle-owner-files",
129130
"check:unit": "pnpm test:unit && pnpm test:smoke",
130131
"check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
131132
"prepack": "pnpm check:mcp-metadata && pnpm build:all && pnpm package:apple-runner:npm && pnpm package:android-snapshot-helper:npm && pnpm package:android-multitouch-helper:npm && pnpm package:android-ime-helper:npm",
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
import fs from 'node:fs';
2+
import path from 'node:path';
3+
import { COMMAND_OWNER_FILES } from '../src/core/command-descriptor/owner-files.ts';
4+
import { getDaemonRouteOwnerFiles } from '../src/daemon/route-owner-files.ts';
5+
6+
const repoRoot = path.resolve(import.meta.dirname, '..');
7+
const distRoot = path.join(repoRoot, 'dist', 'src');
8+
const ownerPaths = new Set([
9+
...Object.values(COMMAND_OWNER_FILES).flat(),
10+
...Object.values(getDaemonRouteOwnerFiles()),
11+
]);
12+
const forbiddenMetadata = new Set(['ownerFiles', ...ownerPaths]);
13+
14+
const bundleFiles = walkFiles(distRoot).filter((file) => file.endsWith('.js'));
15+
if (bundleFiles.length === 0) {
16+
throw new Error('No dist/src JavaScript files found. Run `pnpm build` first.');
17+
}
18+
19+
const leaks = bundleFiles.flatMap((file) => {
20+
const content = fs.readFileSync(file, 'utf8');
21+
return [...forbiddenMetadata]
22+
.filter((value) => content.includes(value))
23+
.map((value) => ({ file: path.relative(repoRoot, file), value }));
24+
});
25+
26+
if (leaks.length > 0) {
27+
const details = leaks.map(({ file, value }) => `- ${value} in ${file}`).join('\n');
28+
throw new Error(`Owner-file navigation metadata leaked into production bundles:\n${details}`);
29+
}
30+
31+
process.stdout.write(
32+
`Verified the ownerFiles key and ${ownerPaths.size} owner-file paths are absent from ${bundleFiles.length} production bundles.\n`,
33+
);
34+
35+
function walkFiles(root: string): string[] {
36+
if (!fs.existsSync(root)) return [];
37+
return fs.readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
38+
const entryPath = path.join(root, entry.name);
39+
return entry.isDirectory() ? walkFiles(entryPath) : [entryPath];
40+
});
41+
}

‎scripts/explain-command.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import fs from 'node:fs';
22
import path from 'node:path';
33
import { explainCommand, formatCommandExplanation } from '../src/commands/command-explain.ts';
4-
import { getDaemonRouteOwnerFiles } from '../src/daemon/request-handler-chain.ts';
4+
import { getDaemonRouteOwnerFiles } from '../src/daemon/route-owner-files.ts';
55

66
const repoRoot = path.resolve(import.meta.dirname, '..');
77
const args = process.argv.slice(2);

‎src/commands/__tests__/command-explain.test.ts‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@ import fs from 'node:fs';
33
import path from 'node:path';
44
import { describe, expect, test } from 'vitest';
55
import { commandDescriptors } from '../../core/command-descriptor/registry.ts';
6-
import { getDaemonRouteOwnerFiles } from '../../daemon/request-handler-chain.ts';
6+
import { ownerFilesForCommand } from '../../core/command-descriptor/owner-files.ts';
7+
import { getDaemonRouteOwnerFiles } from '../../daemon/route-owner-files.ts';
78
import {
89
explainCommand as explainCommandFromMetadata,
910
formatCommandExplanation,
@@ -165,7 +166,7 @@ describe('explainCommand table-driven coverage', () => {
165166
const result = explainCommand(descriptor.name, { fileExists });
166167
expect(result.found).toBe(true);
167168
if (!result.found) continue;
168-
for (const ownerFile of descriptor.ownerFiles) {
169+
for (const ownerFile of ownerFilesForCommand(descriptor.name)) {
169170
expect(result.explanation.files).toContain(ownerFile);
170171
}
171172
for (const file of result.explanation.files) {
@@ -174,6 +175,15 @@ describe('explainCommand table-driven coverage', () => {
174175
}
175176
});
176177

178+
test('owner-file claims stay tooling-only: production descriptors do not carry them', () => {
179+
for (const descriptor of commandDescriptors) {
180+
expect(
181+
Object.hasOwn(descriptor, 'ownerFiles'),
182+
`${descriptor.name} still exposes ownerFiles on the runtime descriptor`,
183+
).toBe(false);
184+
}
185+
});
186+
177187
test('every daemon explanation uses its production handler module owner', () => {
178188
for (const descriptor of commandDescriptors) {
179189
if (!('daemon' in descriptor) || !descriptor.daemon) continue;

‎src/commands/command-explain.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { cliAliasesForCommand, normalizeCliCommandAlias } from '../cli-command-a
33
import { buildCommandUsage } from '../utils/cli-usage.ts';
44
import type { DaemonCommandRoute } from '../daemon/daemon-command-registry.ts';
55
import { commandDescriptors, type Command } from '../core/command-descriptor/registry.ts';
6+
import { ownerFilesForCommand } from '../core/command-descriptor/owner-files.ts';
67
import type { CommandCapability } from '../core/capabilities.ts';
78
import type { CommandTimeoutPolicy } from '../core/command-descriptor/types.ts';
89
import {
@@ -121,7 +122,7 @@ function buildCommandExplanation(
121122
...(cliSchema ? { cli: describeCliSurface(descriptor.name, cliSchema) } : {}),
122123
files: commandFiles(
123124
descriptor.name,
124-
descriptor.ownerFiles,
125+
ownerFilesForCommand(descriptor.name),
125126
family?.name,
126127
'daemon' in descriptor ? descriptor.daemon?.route : undefined,
127128
Boolean('capability' in descriptor && descriptor.capability),
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
import { describe, expect, test } from 'vitest';
2+
import { commandDescriptors } from '../registry.ts';
3+
import { COMMAND_OWNER_FILES, ownerFilesForCommand } from '../owner-files.ts';
4+
5+
describe('command owner-file projection', () => {
6+
test('covers exactly the registered commands (completeness, no extras)', () => {
7+
const declared = Object.keys(COMMAND_OWNER_FILES).sort();
8+
const registered = commandDescriptors.map((descriptor) => descriptor.name).sort();
9+
expect(declared).toEqual(registered);
10+
});
11+
12+
test('every command maps to a non-empty owner-file list', () => {
13+
for (const descriptor of commandDescriptors) {
14+
expect(ownerFilesForCommand(descriptor.name).length).toBeGreaterThan(0);
15+
}
16+
});
17+
18+
test('the projection is not reachable from the runtime descriptor objects', () => {
19+
for (const descriptor of commandDescriptors) {
20+
expect(Object.hasOwn(descriptor, 'ownerFiles')).toBe(false);
21+
}
22+
});
23+
});
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
import { RAW_COMMAND_DESCRIPTORS, type Command } from './registry.ts';
2+
3+
/**
4+
* Development-only owner-file navigation claims for every command (ADR 0008
5+
* follow-up, https://github.com/callstack/agent-device/issues/1178).
6+
*
7+
* These paths point a reader at the module that owns each command's surface so
8+
* `explain:command` can render "where does this live". They are pure tooling
9+
* metadata: nothing in the daemon/CLI runtime reads them, so they were removed
10+
* from the production {@link CommandDescriptor} objects (and therefore from the
11+
* emitted bundles) and kept as a derived view on the source-of-truth registry.
12+
*
13+
* The key space is the descriptor-derived {@link Command} union, so deriving the
14+
* projection from {@link RAW_COMMAND_DESCRIPTORS} makes a missing or misspelled
15+
* command a type error and forbids owner claims for commands that do not exist.
16+
* Only `command-explain.ts` and its tests import this module; the production
17+
* import graph never reaches it, so the bundler drops it entirely.
18+
*/
19+
type OwnerFilesFromDescriptors<
20+
T extends readonly {
21+
readonly name: string;
22+
readonly ownerFiles?: readonly [string, ...string[]];
23+
}[],
24+
> = {
25+
[K in keyof T & number as T[K]['name']]: NonNullable<T[K]['ownerFiles']>;
26+
};
27+
28+
const buildOwnerFiles = <
29+
const T extends readonly {
30+
readonly name: string;
31+
readonly ownerFiles?: readonly [string, ...string[]];
32+
}[],
33+
>(
34+
entries: T,
35+
): OwnerFilesFromDescriptors<T> =>
36+
Object.fromEntries(
37+
entries.map((entry) => [entry.name, entry.ownerFiles]),
38+
) as OwnerFilesFromDescriptors<T>;
39+
40+
export const COMMAND_OWNER_FILES = buildOwnerFiles(RAW_COMMAND_DESCRIPTORS) satisfies Record<
41+
Command,
42+
readonly [string, ...string[]]
43+
>;
44+
45+
/** The owner-file claims for one command (development-only navigation metadata). */
46+
export function ownerFilesForCommand(command: Command): readonly [string, ...string[]] {
47+
return COMMAND_OWNER_FILES[command];
48+
}

0 commit comments

Comments
 (0)