refactor: share duplicate script helpers

scripts/lib/bundled-plugin-build-entries-types.d.ts

@@ -0,0 +1,23 @@
+export type BundledPluginBuildEntry = {
+  id: string;
+  hasPackageJson: boolean;
+  packageJson: unknown;
+  sourceEntries: string[];
+};
+
+export type BundledPluginBuildEntryParams = {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+};
+
+export const NON_PACKAGED_BUNDLED_PLUGIN_DIRS: Set<string>;
+export function collectBundledPluginBuildEntries(
+  params?: BundledPluginBuildEntryParams,
+): BundledPluginBuildEntry[];
+export function listBundledPluginBuildEntries(
+  params?: BundledPluginBuildEntryParams,
+): Record<string, string>;
+export function listBundledPluginPackArtifacts(params?: BundledPluginBuildEntryParams): string[];
+export function listBundledPluginRuntimeDependencies(
+  params?: BundledPluginBuildEntryParams,
+): string[];

scripts/lib/bundled-plugin-build-entries.d.mts

@@ -1,23 +1 @@
-export type BundledPluginBuildEntry = {
-  id: string;
-  hasPackageJson: boolean;
-  packageJson: unknown;
-  sourceEntries: string[];
-};
-
-export type BundledPluginBuildEntryParams = {
-  cwd?: string;
-  env?: NodeJS.ProcessEnv;
-};
-
-export const NON_PACKAGED_BUNDLED_PLUGIN_DIRS: Set<string>;
-export function collectBundledPluginBuildEntries(
-  params?: BundledPluginBuildEntryParams,
-): BundledPluginBuildEntry[];
-export function listBundledPluginBuildEntries(
-  params?: BundledPluginBuildEntryParams,
-): Record<string, string>;
-export function listBundledPluginPackArtifacts(params?: BundledPluginBuildEntryParams): string[];
-export function listBundledPluginRuntimeDependencies(
-  params?: BundledPluginBuildEntryParams,
-): string[];
+export * from "./bundled-plugin-build-entries-types.js";

scripts/lib/bundled-plugin-build-entries.d.ts

@@ -1,23 +1 @@
-export type BundledPluginBuildEntry = {
-  id: string;
-  hasPackageJson: boolean;
-  packageJson: unknown;
-  sourceEntries: string[];
-};
-
-export type BundledPluginBuildEntryParams = {
-  cwd?: string;
-  env?: NodeJS.ProcessEnv;
-};
-
-export const NON_PACKAGED_BUNDLED_PLUGIN_DIRS: Set<string>;
-export function collectBundledPluginBuildEntries(
-  params?: BundledPluginBuildEntryParams,
-): BundledPluginBuildEntry[];
-export function listBundledPluginBuildEntries(
-  params?: BundledPluginBuildEntryParams,
-): Record<string, string>;
-export function listBundledPluginPackArtifacts(params?: BundledPluginBuildEntryParams): string[];
-export function listBundledPluginRuntimeDependencies(
-  params?: BundledPluginBuildEntryParams,
-): string[];
+export * from "./bundled-plugin-build-entries-types.js";

scripts/lib/extension-import-boundary-checker.mjs

@@ -0,0 +1,104 @@
+import ts from "typescript";
+import { BUNDLED_PLUGIN_PATH_PREFIX } from "./bundled-plugin-paths.mjs";
+import {
+  collectTypeScriptInventory,
+  createCachedAsync,
+  formatGroupedInventoryHuman,
+  normalizeRepoPath,
+  resolveRepoSpecifier,
+  visitModuleSpecifiers,
+  writeLine,
+} from "./guard-inventory-utils.mjs";
+import {
+  collectTypeScriptFilesFromRoots,
+  resolveRepoRoot,
+  resolveSourceRoots,
+  toLine,
+} from "./ts-guard-utils.mjs";
+
+const repoRoot = resolveRepoRoot(import.meta.url);
+
+function compareEntries(left, right) {
+  return (
+    left.file.localeCompare(right.file) ||
+    left.line - right.line ||
+    left.kind.localeCompare(right.kind) ||
+    left.specifier.localeCompare(right.specifier) ||
+    left.reason.localeCompare(right.reason)
+  );
+}
+
+function classifyResolvedExtensionReason(kind, boundaryLabel) {
+  const verb =
+    kind === "export"
+      ? "re-exports"
+      : kind === "dynamic-import"
+        ? "dynamically imports"
+        : "imports";
+  return `${verb} bundled plugin file from ${boundaryLabel} boundary`;
+}
+
+function scanImportBoundaryViolations(sourceFile, filePath, boundaryLabel) {
+  const entries = [];
+  const relativeFile = normalizeRepoPath(repoRoot, filePath);
+
+  visitModuleSpecifiers(ts, sourceFile, ({ kind, specifier, specifierNode }) => {
+    const resolvedPath = resolveRepoSpecifier(repoRoot, specifier, filePath);
+    if (!resolvedPath?.startsWith(BUNDLED_PLUGIN_PATH_PREFIX)) {
+      return;
+    }
+    entries.push({
+      file: relativeFile,
+      line: toLine(sourceFile, specifierNode),
+      kind,
+      specifier,
+      resolvedPath,
+      reason: classifyResolvedExtensionReason(kind, boundaryLabel),
+    });
+  });
+
+  return entries;
+}
+
+export function createExtensionImportBoundaryChecker(params) {
+  const scanRoots = resolveSourceRoots(repoRoot, params.roots);
+
+  const collectInventory = createCachedAsync(async () => {
+    const files = (await collectTypeScriptFilesFromRoots(scanRoots))
+      .filter((filePath) => !params.shouldSkipFile?.(normalizeRepoPath(repoRoot, filePath)))
+      .toSorted((left, right) =>
+        normalizeRepoPath(repoRoot, left).localeCompare(normalizeRepoPath(repoRoot, right)),
+      );
+    return await collectTypeScriptInventory({
+      ts,
+      files,
+      compareEntries,
+      collectEntries(sourceFile, filePath) {
+        return scanImportBoundaryViolations(sourceFile, filePath, params.boundaryLabel);
+      },
+      shouldParseSource: params.skipSourcesWithoutBundledPluginPrefix
+        ? (source) => source.includes(BUNDLED_PLUGIN_PATH_PREFIX)
+        : undefined,
+    });
+  });
+
+  async function main(argv = process.argv.slice(2), io) {
+    const streams = io ?? { stdout: process.stdout, stderr: process.stderr };
+    const json = argv.includes("--json");
+    const inventory = await collectInventory();
+
+    if (json) {
+      writeLine(streams.stdout, JSON.stringify(inventory, null, 2));
+    } else {
+      writeLine(streams.stdout, formatGroupedInventoryHuman(params, inventory));
+      writeLine(
+        streams.stdout,
+        inventory.length === 0 ? "Boundary is clean." : "Boundary has violations.",
+      );
+    }
+
+    return inventory.length === 0 ? 0 : 1;
+  }
+
+  return { collectInventory, main };
+}

scripts/lib/guard-inventory-utils.mjs

@@ -74,6 +74,42 @@ export function writeLine(stream, text) {
   stream.write(`${text}\n`);
 }
 
+export function createCachedAsync(factory) {
+  let cachedPromise = null;
+  return async function getCachedValue() {
+    if (cachedPromise) {
+      return cachedPromise;
+    }
+
+    cachedPromise = factory();
+    try {
+      return await cachedPromise;
+    } catch (error) {
+      cachedPromise = null;
+      throw error;
+    }
+  };
+}
+
+export function formatGroupedInventoryHuman(params, inventory) {
+  if (inventory.length === 0) {
+    return `${params.rule}\n${params.cleanMessage}`;
+  }
+
+  const lines = [params.rule, params.inventoryTitle];
+  let activeFile = "";
+  for (const entry of inventory) {
+    if (entry.file !== activeFile) {
+      activeFile = entry.file;
+      lines.push(activeFile);
+    }
+    lines.push(`  - line ${entry.line} [${entry.kind}] ${entry.reason}`);
+    lines.push(`    specifier: ${entry.specifier}`);
+    lines.push(`    resolved: ${entry.resolvedPath}`);
+  }
+  return lines.join("\n");
+}
+
 export async function collectTypeScriptInventory(params) {
   const inventory = [];
   const scriptKind = params.scriptKind ?? params.ts.ScriptKind.TS;

scripts/lib/optional-bundled-clusters-types.d.ts

@@ -0,0 +1,11 @@
+export const optionalBundledClusters: string[];
+export const optionalBundledClusterSet: Set<string>;
+export const OPTIONAL_BUNDLED_BUILD_ENV: "OPENCLAW_INCLUDE_OPTIONAL_BUNDLED";
+export function isOptionalBundledCluster(cluster: string): boolean;
+export function shouldIncludeOptionalBundledClusters(env?: NodeJS.ProcessEnv): boolean;
+export function hasReleasedBundledInstall(packageJson: unknown): boolean;
+export function shouldBuildBundledCluster(
+  cluster: string,
+  env?: NodeJS.ProcessEnv,
+  options?: { packageJson?: unknown },
+): boolean;

scripts/lib/optional-bundled-clusters.d.mts

@@ -1,11 +1 @@
-export const optionalBundledClusters: string[];
-export const optionalBundledClusterSet: Set<string>;
-export const OPTIONAL_BUNDLED_BUILD_ENV: "OPENCLAW_INCLUDE_OPTIONAL_BUNDLED";
-export function isOptionalBundledCluster(cluster: string): boolean;
-export function shouldIncludeOptionalBundledClusters(env?: NodeJS.ProcessEnv): boolean;
-export function hasReleasedBundledInstall(packageJson: unknown): boolean;
-export function shouldBuildBundledCluster(
-  cluster: string,
-  env?: NodeJS.ProcessEnv,
-  options?: { packageJson?: unknown },
-): boolean;
+export * from "./optional-bundled-clusters-types.js";

scripts/lib/optional-bundled-clusters.d.ts

@@ -1,11 +1 @@
-export const optionalBundledClusters: string[];
-export const optionalBundledClusterSet: Set<string>;
-export const OPTIONAL_BUNDLED_BUILD_ENV: "OPENCLAW_INCLUDE_OPTIONAL_BUNDLED";
-export function isOptionalBundledCluster(cluster: string): boolean;
-export function shouldIncludeOptionalBundledClusters(env?: NodeJS.ProcessEnv): boolean;
-export function hasReleasedBundledInstall(packageJson: unknown): boolean;
-export function shouldBuildBundledCluster(
-  cluster: string,
-  env?: NodeJS.ProcessEnv,
-  options?: { packageJson?: unknown },
-): boolean;
+export * from "./optional-bundled-clusters-types.js";

scripts/lib/package-root-args.mjs

@@ -0,0 +1,23 @@
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const defaultPackageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+export function parsePackageRootArg(argv, envName) {
+  let packageRoot = process.env[envName];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--package-root") {
+      packageRoot = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith("--package-root=")) {
+      packageRoot = arg.slice("--package-root=".length);
+      continue;
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+  return { packageRoot: path.resolve(packageRoot ?? defaultPackageRoot) };
+}