From a85cd94ddea65903f6bbfff913d7fb3345b17948 Mon Sep 17 00:00:00 2001 From: Amp Date: Wed, 12 Aug 2026 15:19:42 +0000 Subject: [PATCH] refactor(scripts): share wildcard re-export scanner --- .../check-extension-wildcard-reexports.mts | 101 +++-------------- .../check-plugin-sdk-wildcard-reexports.mts | 96 +++------------- .../extension-wildcard-reexport-scanner.mts | 104 ++++++++++++++++++ 3 files changed, 136 insertions(+), 165 deletions(-) create mode 100644 scripts/lib/extension-wildcard-reexport-scanner.mts diff --git a/scripts/check-extension-wildcard-reexports.mts b/scripts/check-extension-wildcard-reexports.mts index 73335b69103f..3f06948306cd 100644 --- a/scripts/check-extension-wildcard-reexports.mts +++ b/scripts/check-extension-wildcard-reexports.mts @@ -1,99 +1,30 @@ #!/usr/bin/env node // Rejects local wildcard re-exports in guarded extension API barrels. -import fs from "node:fs/promises"; -import path from "node:path"; -import { fileURLToPath } from "node:url"; -import { resolveRepoRoot } from "./lib/repo-root.mjs"; -const repoRoot = resolveRepoRoot(import.meta.url); +import { + createExtensionWildcardReexportScanner, + type ExtensionWildcardReexportPolicy, +} from "./lib/extension-wildcard-reexport-scanner.mts"; const LOCAL_WILDCARD_REEXPORT_PATTERN = /^\s*export\s+(?:type\s+)?\*\s+from\s+["'](?:\.{1,2}\/)/u; - -async function walkFiles(rootDir: string, predicate: (filePath: string) => boolean) { - const files: string[] = []; - async function visit(dir: string) { - const entries = await fs.readdir(dir, { withFileTypes: true }); - for (const entry of entries) { - if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "dist") { - continue; - } - const filePath = path.join(dir, entry.name); - if (entry.isDirectory()) { - await visit(filePath); - continue; - } - if (entry.isFile() && predicate(filePath)) { - files.push(filePath); - } - } - } - await visit(rootDir); - return files.toSorted((left, right) => left.localeCompare(right)); -} - -async function listGuardedFiles(rootDir = repoRoot) { - return walkFiles( - path.join(rootDir, "extensions"), - (filePath) => - filePath.endsWith(`${path.sep}runtime-api.ts`) || filePath.endsWith(`${path.sep}api.ts`), - ); -} +const policy = { + // Local wildcard pinning also protects nested implementation barrels. + fileScope: "all-extension-api-files", + pattern: LOCAL_WILDCARD_REEXPORT_PATTERN, + successMessage: "No guarded extension wildcard re-exports found.", + findingsMessage: "Found guarded extension wildcard re-exports:", + remediationMessage: "Use explicit named exports so runtime and public API barrels stay pinned.", +} satisfies ExtensionWildcardReexportPolicy; +const scanner = createExtensionWildcardReexportScanner(policy); /** * Finds local wildcard re-export lines in a barrel source string. */ -export function findLocalWildcardReexports(source: string) { - return source - .split(/\r?\n/u) - .map((text, index) => ({ line: index + 1, text })) - .filter(({ text }) => LOCAL_WILDCARD_REEXPORT_PATTERN.test(text)); -} - -/** - * Collects guarded extension API/runtime barrels that use wildcard re-exports. - */ -async function collectExtensionWildcardReexports(rootDir = repoRoot) { - const files = await listGuardedFiles(rootDir); - const violations = []; - for (const filePath of files) { - const source = await fs.readFile(filePath, "utf8"); - for (const match of findLocalWildcardReexports(source)) { - violations.push({ - file: path.relative(rootDir, filePath).split(path.sep).join("/"), - line: match.line, - text: match.text.trim(), - }); - } - } - return violations; -} +export const findLocalWildcardReexports = scanner.findLines; /** * Runs the extension wildcard re-export guard. */ -export async function main(argv = process.argv.slice(2), io = process) { - const json = argv.includes("--json"); - const violations = await collectExtensionWildcardReexports(); +export const main = scanner.main; - if (json) { - io.stdout.write(`${JSON.stringify(violations, null, 2)}\n`); - return violations.length === 0 ? 0 : 1; - } - - if (violations.length === 0) { - io.stdout.write("No guarded extension wildcard re-exports found.\n"); - return 0; - } - - io.stderr.write("Found guarded extension wildcard re-exports:\n"); - for (const violation of violations) { - io.stderr.write(`- ${violation.file}:${violation.line} ${violation.text}\n`); - } - io.stderr.write("Use explicit named exports so runtime and public API barrels stay pinned.\n"); - return 1; -} - -if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { - const exitCode = await main(); - process.exit(exitCode); -} +await scanner.exitIfMain(import.meta.url); diff --git a/scripts/check-plugin-sdk-wildcard-reexports.mts b/scripts/check-plugin-sdk-wildcard-reexports.mts index 199c8bd58e7b..7e60ab61abe4 100644 --- a/scripts/check-plugin-sdk-wildcard-reexports.mts +++ b/scripts/check-plugin-sdk-wildcard-reexports.mts @@ -1,95 +1,31 @@ #!/usr/bin/env node // Rejects wildcard plugin SDK re-exports in extension API barrels. -import fs from "node:fs/promises"; -import path from "node:path"; -import { fileURLToPath } from "node:url"; -import { resolveRepoRoot } from "./lib/repo-root.mjs"; -const repoRoot = resolveRepoRoot(import.meta.url); -const extensionsRoot = path.join(repoRoot, "extensions"); +import { + createExtensionWildcardReexportScanner, + type ExtensionWildcardReexportPolicy, +} from "./lib/extension-wildcard-reexport-scanner.mts"; const WILDCARD_PLUGIN_SDK_REEXPORT_PATTERN = /^\s*export\s+(?:type\s+)?\*\s+(?:as\s+[$\w]+\s+)?from\s+["']openclaw\/plugin-sdk\//u; - -async function listExtensionApiFiles(rootDir = extensionsRoot): Promise { - const entries = await fs.readdir(rootDir, { withFileTypes: true }); - const files: string[] = []; - for (const entry of entries) { - if (!entry.isDirectory()) { - continue; - } - for (const fileName of ["api.ts", "runtime-api.ts"]) { - const filePath = path.join(rootDir, entry.name, fileName); - try { - const stat = await fs.stat(filePath); - if (stat.isFile()) { - files.push(filePath); - } - } catch (error) { - if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") { - throw error; - } - } - } - } - return files.toSorted((left, right) => left.localeCompare(right)); -} +const policy = { + // SDK wildcard exposure is only a public extension-root barrel policy. + fileScope: "extension-root-api-files", + pattern: WILDCARD_PLUGIN_SDK_REEXPORT_PATTERN, + successMessage: "No plugin-sdk wildcard re-exports found in extension API barrels.", + findingsMessage: "Found plugin-sdk wildcard re-exports in extension API barrels:", + remediationMessage: "Use explicit named exports from the narrow SDK subpath instead.", +} satisfies ExtensionWildcardReexportPolicy; +const scanner = createExtensionWildcardReexportScanner(policy); /** * Finds wildcard plugin SDK re-export lines in an extension API barrel. */ -export function findPluginSdkWildcardReexports(source: string) { - return source - .split(/\r?\n/u) - .map((text, index) => ({ line: index + 1, text })) - .filter(({ text }) => WILDCARD_PLUGIN_SDK_REEXPORT_PATTERN.test(text)); -} - -/** - * Collects extension API barrels that wildcard re-export plugin SDK subpaths. - */ -async function collectPluginSdkWildcardReexports(rootDir = repoRoot) { - const files = await listExtensionApiFiles(path.join(rootDir, "extensions")); - const violations = []; - for (const filePath of files) { - const source = await fs.readFile(filePath, "utf8"); - for (const match of findPluginSdkWildcardReexports(source)) { - violations.push({ - file: path.relative(rootDir, filePath).split(path.sep).join("/"), - line: match.line, - text: match.text.trim(), - }); - } - } - return violations; -} +export const findPluginSdkWildcardReexports = scanner.findLines; /** * Runs the plugin SDK wildcard re-export guard. */ -export async function main(argv = process.argv.slice(2), io = process) { - const json = argv.includes("--json"); - const violations = await collectPluginSdkWildcardReexports(); +export const main = scanner.main; - if (json) { - io.stdout.write(`${JSON.stringify(violations, null, 2)}\n`); - return violations.length === 0 ? 0 : 1; - } - - if (violations.length === 0) { - io.stdout.write("No plugin-sdk wildcard re-exports found in extension API barrels.\n"); - return 0; - } - - io.stderr.write("Found plugin-sdk wildcard re-exports in extension API barrels:\n"); - for (const violation of violations) { - io.stderr.write(`- ${violation.file}:${violation.line} ${violation.text}\n`); - } - io.stderr.write("Use explicit named exports from the narrow SDK subpath instead.\n"); - return 1; -} - -if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { - const exitCode = await main(); - process.exit(exitCode); -} +await scanner.exitIfMain(import.meta.url); diff --git a/scripts/lib/extension-wildcard-reexport-scanner.mts b/scripts/lib/extension-wildcard-reexport-scanner.mts new file mode 100644 index 000000000000..f02eeb5a8b10 --- /dev/null +++ b/scripts/lib/extension-wildcard-reexport-scanner.mts @@ -0,0 +1,104 @@ +// Shared scanner for the extension wildcard re-export guards. +import fs from "node:fs/promises"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { resolveRepoRoot } from "./repo-root.mjs"; + +const repoRoot = resolveRepoRoot(import.meta.url); +const guardedFileNames = new Set(["api.ts", "runtime-api.ts"]); +const recursivelySkippedDirectories = new Set(["node_modules", ".git", "dist"]); + +type ScriptIo = { + stdout: { write(chunk: string): unknown }; + stderr: { write(chunk: string): unknown }; +}; + +export type ExtensionWildcardReexportPolicy = { + fileScope: "all-extension-api-files" | "extension-root-api-files"; + pattern: RegExp; + successMessage: string; + findingsMessage: string; + remediationMessage: string; +}; + +async function listGuardedFiles(policy: ExtensionWildcardReexportPolicy) { + const files: string[] = []; + const recursive = policy.fileScope === "all-extension-api-files"; + + async function visit(dir: string, depth: number) { + const entries = await fs.readdir(dir, { withFileTypes: true }); + for (const entry of entries) { + const filePath = path.join(dir, entry.name); + if (entry.isDirectory()) { + if ( + (!recursive && depth > 0) || + (recursive && recursivelySkippedDirectories.has(entry.name)) + ) { + continue; + } + await visit(filePath, depth + 1); + continue; + } + if ((recursive || depth === 1) && entry.isFile() && guardedFileNames.has(entry.name)) { + files.push(filePath); + } + } + } + + await visit(path.join(repoRoot, "extensions"), 0); + return files.toSorted((left, right) => left.localeCompare(right)); +} + +function findWildcardReexportLines(source: string, pattern: RegExp) { + return source + .split(/\r?\n/u) + .map((text, index) => ({ line: index + 1, text })) + .filter(({ text }) => pattern.test(text)); +} + +async function collectWildcardReexports(policy: ExtensionWildcardReexportPolicy) { + const findings = []; + for (const filePath of await listGuardedFiles(policy)) { + const source = await fs.readFile(filePath, "utf8"); + for (const match of findWildcardReexportLines(source, policy.pattern)) { + findings.push({ + file: path.relative(repoRoot, filePath).split(path.sep).join("/"), + line: match.line, + text: match.text.trim(), + }); + } + } + return findings.toSorted( + (left, right) => left.file.localeCompare(right.file) || left.line - right.line, + ); +} + +export function createExtensionWildcardReexportScanner(policy: ExtensionWildcardReexportPolicy) { + async function main(argv = process.argv.slice(2), io: ScriptIo = process) { + const findings = await collectWildcardReexports(policy); + if (argv.includes("--json")) { + io.stdout.write(`${JSON.stringify(findings, null, 2)}\n`); + } else if (findings.length === 0) { + io.stdout.write(`${policy.successMessage}\n`); + } else { + io.stderr.write(`${policy.findingsMessage}\n`); + for (const finding of findings) { + io.stderr.write(`- ${finding.file}:${finding.line} ${finding.text}\n`); + } + io.stderr.write(`${policy.remediationMessage}\n`); + } + return findings.length === 0 ? 0 : 1; + } + + async function exitIfMain(importMetaUrl: string) { + if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(importMetaUrl)) { + process.exit(await main()); + } + } + + return { + exitIfMain, + findLines: (source: string) => findWildcardReexportLines(source, policy.pattern), + main, + }; +}