openclaw/scripts/check-plugin-sdk-subpath-exports.mts

#!/usr/bin/env node

// Verifies plugin SDK subpath exports and generated entrypoint metadata.
import { readFileSync } from "node:fs";
import path from "node:path";
import * as ts from "typescript/unstable/ast";
import { normalizeRepoPath } from "./lib/guard-inventory-utils.mjs";
import { createNativeTypeScriptParser } from "./lib/native-typescript.mts";
import { resolveRepoRoot } from "./lib/repo-root.mjs";
import {
  collectTypeScriptFilesFromRoots,
  isTestLikeTypeScriptFile,
  resolveSourceRoots,
  toLine,
  visitModuleSpecifiers,
} from "./lib/ts-guard-utils.mts";
const repoRoot = resolveRepoRoot(import.meta.url);
const scanRoots = resolveSourceRoots(repoRoot, [
  "src",
  "packages",
  "extensions",
  "scripts",
  "test",
]);
const extraTestSuffixes = [".test-support.ts", ".test-loader.ts", ".test-fixtures.ts"];

type PluginSdkViolation = {
  file: string;
  kind: string;
  line: number;
  reason: string;
  specifier: string;
  subpath: string;
};

function readPackageExports(): Set<string> {
  const packageJson = JSON.parse(readFileSync(path.join(repoRoot, "package.json"), "utf8")) as {
    exports?: Record<string, unknown>;
  };
  return new Set(
    Object.keys(packageJson.exports ?? {})
      .filter((key) => key.startsWith("./plugin-sdk/"))
      .map((key) => key.slice("./plugin-sdk/".length)),
  );
}

function readEntrypoints(): Set<string> {
  const entrypoints = JSON.parse(
    readFileSync(path.join(repoRoot, "scripts/lib/plugin-sdk-entrypoints.json"), "utf8"),
  ) as unknown[];
  return new Set(
    entrypoints.filter((entry): entry is string => typeof entry === "string" && entry !== "index"),
  );
}

function readPrivateLocalOnlySubpaths(): Set<string> {
  const subpaths = JSON.parse(
    readFileSync(
      path.join(repoRoot, "scripts/lib/plugin-sdk-private-local-only-subpaths.json"),
      "utf8",
    ),
  ) as unknown[];
  return new Set(
    subpaths.filter((entry): entry is string => typeof entry === "string" && !entry.includes("/")),
  );
}

function parsePluginSdkSubpath(specifier: string): string | null {
  return specifier.match(/^@?openclaw\/plugin-sdk\/(.+)$/u)?.[1] ?? null;
}

function isGeneratedBuildArtifact(filePath: string): boolean {
  return normalizeRepoPath(repoRoot, filePath).split("/").includes("dist");
}

function isRuntimeModuleReference(node: ts.Node): boolean {
  // With verbatimModuleSyntax, inline `type` specifiers emit an empty import/export and still
  // resolve the module. Only declaration-level `import type` and `export type` are erased.
  if (ts.isImportDeclaration(node)) {
    return node.importClause?.phaseModifier !== ts.SyntaxKind.TypeKeyword;
  }
  if (ts.isExportDeclaration(node) || ts.isImportEqualsDeclaration(node)) {
    return !node.isTypeOnly;
  }
  return !ts.isImportTypeNode(node);
}

function compareEntries(left: PluginSdkViolation, right: PluginSdkViolation): number {
  return (
    left.file.localeCompare(right.file) ||
    left.line - right.line ||
    left.kind.localeCompare(right.kind) ||
    left.specifier.localeCompare(right.specifier) ||
    left.subpath.localeCompare(right.subpath)
  );
}

async function collectViolations(): Promise<PluginSdkViolation[]> {
  using parser = createNativeTypeScriptParser({ cwd: repoRoot });
  const entrypoints = readEntrypoints();
  const exports = readPackageExports();
  const privateLocalOnlySubpaths = readPrivateLocalOnlySubpaths();
  const files = (await collectTypeScriptFilesFromRoots(scanRoots, { includeTests: true }))
    .filter((filePath) => !isGeneratedBuildArtifact(filePath))
    .toSorted((left, right) =>
      normalizeRepoPath(repoRoot, left).localeCompare(normalizeRepoPath(repoRoot, right)),
    );
  const violations: PluginSdkViolation[] = [];

  for (const filePath of files) {
    const sourceText = readFileSync(filePath, "utf8");
    // Escaped module names need parsing even when the literal SDK prefix is absent.
    if (!sourceText.includes("plugin-sdk") && !sourceText.includes("\\")) {
      continue;
    }
    const repoPath = normalizeRepoPath(repoRoot, filePath);
    // Workspace packages resolve private facades through TS paths; core runtime stays relative.
    const isCoreRuntimeFile =
      repoPath.startsWith("src/") && !isTestLikeTypeScriptFile(filePath, extraTestSuffixes);
    const sourceFile = parser.parseSourceFile(filePath, sourceText);

    visitModuleSpecifiers(
      sourceFile,
      ({ kind, node, specifier, specifierNode }) => {
        const subpath = parsePluginSdkSubpath(specifier);
        if (!subpath) {
          return;
        }
        if (privateLocalOnlySubpaths.has(subpath)) {
          if (isCoreRuntimeFile && isRuntimeModuleReference(node)) {
            violations.push({
              file: repoPath,
              line: toLine(sourceFile, specifierNode),
              kind,
              specifier,
              subpath,
              reason: "private runtime helper used by core must use a relative import",
            });
          }
          return;
        }

        const missingFrom: string[] = [];
        if (!entrypoints.has(subpath)) {
          missingFrom.push("scripts/lib/plugin-sdk-entrypoints.json");
        }
        if (!exports.has(subpath)) {
          missingFrom.push("package.json exports");
        }
        if (missingFrom.length === 0) {
          return;
        }

        violations.push({
          file: repoPath,
          line: toLine(sourceFile, specifierNode),
          kind,
          specifier,
          subpath,
          reason: `missing from ${missingFrom.join(" and ")}`,
        });
      },
      { includeCommonJs: true, includeImportTypes: true },
    );
  }

  return violations.toSorted(compareEntries);
}

async function main(): Promise<void> {
  const violations = await collectViolations();
  if (violations.length === 0) {
    console.log("OK: all referenced openclaw/plugin-sdk/<subpath> imports are exported.");
    return;
  }

  console.error(
    "Rule: every referenced openclaw/plugin-sdk/<subpath> must be public or use its required private boundary.",
  );
  for (const violation of violations) {
    console.error(
      `- ${violation.file}:${violation.line} [${violation.kind}] ${violation.specifier}: ${violation.reason}`,
    );
  }
  process.exitCode = 1;
}

main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});