@openclaw/plugin-inspector 0.1.3 → 0.3.0

package/src/ci-outputs.js

@@ -0,0 +1,235 @@
+import path from "node:path";
+import { writeArtifacts } from "./artifacts.js";
+
+export const defaultSarifPath = "plugin-inspector.sarif";
+export const defaultJunitPath = "plugin-inspector.junit.xml";
+
+export async function writeCiOutputArtifacts(report, options = {}) {
+  const outDir = path.resolve(options.cwd ?? process.cwd(), options.outDir ?? "reports");
+  const artifacts = [];
+
+  if (options.sarifPath) {
+    artifacts.push({
+      name: "sarifPath",
+      path: path.resolve(outDir, options.sarifPath),
+      json: buildSarifReport(report),
+    });
+  }
+
+  if (options.junitPath) {
+    artifacts.push({
+      name: "junitPath",
+      path: path.resolve(outDir, options.junitPath),
+      content: renderJunitXml(report),
+    });
+  }
+
+  if (artifacts.length === 0) {
+    return {};
+  }
+
+  return writeArtifacts(artifacts, { check: options.check });
+}
+
+export function buildSarifReport(report) {
+  const findings = reportFindings(report);
+  const rules = [...new Map(findings.map((finding) => [finding.code, sarifRule(finding)])).values()];
+  const fixtureById = new Map((report.fixtures ?? []).map((fixture) => [fixture.id, fixture]));
+
+  return {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "plugin-inspector",
+            informationUri: "https://github.com/openclaw/plugin-inspector",
+            rules,
+          },
+        },
+        results: findings.map((finding) => sarifResult(finding, fixtureById)),
+      },
+    ],
+  };
+}
+
+export function renderJunitXml(report) {
+  const findings = reportFindings(report);
+  const testcases = findings.length > 0 ? findings.map(junitFindingTestcase) : [junitPassingTestcase(report)];
+  const failures = findings.filter(isBlockingFinding).length;
+  const tests = testcases.length;
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<testsuite name="plugin-inspector" tests="${tests}" failures="${failures}" errors="0" skipped="0">`,
+    ...testcases,
+    "</testsuite>",
+    "",
+  ].join("\n");
+}
+
+export function reportFindings(report) {
+  const findings = new Map();
+  for (const finding of [...(report.breakages ?? []), ...(report.warnings ?? []), ...(report.suggestions ?? [])]) {
+    findings.set(findingKey(finding), finding);
+  }
+  for (const issue of report.issues ?? []) {
+    const finding = issueToFinding(issue);
+    findings.set(findingKey(finding), {
+      ...findings.get(findingKey(finding)),
+      ...finding,
+    });
+  }
+  return [...findings.values()];
+}
+
+function issueToFinding(issue) {
+  return {
+    fixture: issue.fixture,
+    code: issue.code,
+    level: issue.status === "blocking" ? "breakage" : "warning",
+    message: issue.title,
+    evidence: issue.evidence ?? [],
+    severity: issue.severity,
+    issueClass: issue.issueClass,
+  };
+}
+
+function findingKey(finding) {
+  return [
+    finding.fixture ?? "",
+    finding.code ?? "",
+    ...normalizeEvidence(finding.evidence),
+  ].join("\n");
+}
+
+function sarifRule(finding) {
+  return {
+    id: finding.code,
+    shortDescription: {
+      text: finding.code,
+    },
+    fullDescription: {
+      text: finding.message ?? finding.code,
+    },
+    defaultConfiguration: {
+      level: sarifLevel(finding),
+    },
+  };
+}
+
+function sarifResult(finding, fixtureById) {
+  return {
+    ruleId: finding.code,
+    level: sarifLevel(finding),
+    message: {
+      text: finding.message ?? finding.code,
+    },
+    locations: [sarifLocation(finding, fixtureById)],
+    properties: {
+      fixture: finding.fixture,
+      severity: finding.severity ?? finding.level,
+      issueClass: finding.issueClass,
+      evidence: normalizeEvidence(finding.evidence),
+    },
+  };
+}
+
+function sarifLocation(finding, fixtureById) {
+  const parsed = parseEvidenceLocation(normalizeEvidence(finding.evidence)[0]);
+  const fixture = fixtureById.get(finding.fixture);
+  const uri = parsed?.uri ?? fixture?.path ?? ".";
+  return {
+    physicalLocation: {
+      artifactLocation: {
+        uri: normalizeUri(uri),
+      },
+      region: {
+        startLine: parsed?.line ?? 1,
+      },
+    },
+  };
+}
+
+function parseEvidenceLocation(evidence) {
+  if (!evidence) {
+    return null;
+  }
+
+  const ref = evidence.includes(" @ ") ? evidence.split(" @ ").pop() : evidence;
+  const match = /^(?<uri>.+?):(?<line>\d+)(?::\d+)?$/.exec(ref);
+  if (!match?.groups?.uri) {
+    return null;
+  }
+  return {
+    uri: match.groups.uri,
+    line: Number(match.groups.line),
+  };
+}
+
+function junitFindingTestcase(finding) {
+  const classname = `plugin-inspector.${xmlName(finding.fixture ?? "unknown")}`;
+  const name = `${finding.level ?? "finding"}:${finding.code}`;
+  const output = normalizeEvidence(finding.evidence).join("\n");
+  if (!isBlockingFinding(finding)) {
+    return [
+      `  <testcase classname="${escapeXml(classname)}" name="${escapeXml(name)}">`,
+      output ? `    <system-out>${escapeXml(output)}</system-out>` : "",
+      "  </testcase>",
+    ]
+      .filter(Boolean)
+      .join("\n");
+  }
+
+  return [
+    `  <testcase classname="${escapeXml(classname)}" name="${escapeXml(name)}">`,
+    `    <failure message="${escapeXml(finding.message ?? finding.code)}">${escapeXml(output || finding.message || finding.code)}</failure>`,
+    "  </testcase>",
+  ].join("\n");
+}
+
+function junitPassingTestcase(report) {
+  return `  <testcase classname="plugin-inspector" name="status:${escapeXml(report.status ?? "pass")}"/>`;
+}
+
+function isBlockingFinding(finding) {
+  return finding.level === "breakage" || finding.status === "blocking" || finding.severity === "P0";
+}
+
+function sarifLevel(finding) {
+  if (isBlockingFinding(finding) || finding.severity === "P1") {
+    return "error";
+  }
+  if (finding.level === "warning" || finding.severity === "P2") {
+    return "warning";
+  }
+  return "note";
+}
+
+function normalizeEvidence(evidence) {
+  if (Array.isArray(evidence)) {
+    return evidence.map(String);
+  }
+  if (evidence == null) {
+    return [];
+  }
+  return [String(evidence)];
+}
+
+function normalizeUri(uri) {
+  return String(uri).replaceAll(path.sep, "/");
+}
+
+function xmlName(value) {
+  return String(value).replace(/[^a-zA-Z0-9_.-]/g, "_");
+}
+
+function escapeXml(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}

package/src/cli.js

@@ -1,15 +1,19 @@
 #!/usr/bin/env node
 import path from "node:path";
 import {
+  loadPluginConfig,
   renderTextSummary,
   runPluginCheck,
 } from "./index.js";
 import {
   buildCiSummary,
   captureEntrypoint,
+  defaultJunitPath,
+  defaultSarifPath,
   inspectCompatibilityFixtureSet,
   inspectFixtureSet,
   loadInspectorConfig,
+  writeCiOutputArtifacts,
   writeCiSummary,
   writeCompatibilityReport,
   writePluginInspectorInit,
@@ -28,8 +32,14 @@ try {
     await runCheck(commandArgs);
   } else if (command === "init") {
     await runInit(commandArgs);
+  } else if (command === "config") {
+    await runConfig(commandArgs);
   } else if (command === "inspect" || command === "report") {
-    await runReport(command, commandArgs);
+    if (command === "inspect" && !commandArgs.includes("--config")) {
+      await runCheck(commandArgs);
+    } else {
+      await runReport(command, commandArgs);
+    }
   } else if (command === "ci") {
     await runCi(commandArgs);
   } else if (command === "capture") {
@@ -42,6 +52,18 @@ try {
   process.exitCode = 1;
 }
 
+async function runConfig(commandArgs) {
+  const configPath = readFlag(commandArgs, "--config");
+  const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
+  const config = await loadPluginConfig({ configPath, pluginRoot });
+
+  if (commandArgs.includes("--json")) {
+    console.log(JSON.stringify(config, null, 2));
+  } else {
+    console.log(renderConfigTextSummary(config));
+  }
+}
+
 async function runCheck(commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
   const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
@@ -50,12 +72,27 @@ async function runCheck(commandArgs) {
   const json = commandArgs.includes("--json");
   const capture = readRuntimeFlag(commandArgs);
   const mockSdk = readMockSdkFlag(commandArgs);
-  const { report } = await runPluginCheck({ configPath, pluginRoot, outDir, openclawPath, capture, mockSdk });
+  const allowExecution = readAllowExecutionFlag(commandArgs);
+  const ciOutputs = readCiOutputFlags(commandArgs);
+  const { report, paths } = await runPluginCheck({
+    allowExecution,
+    capture,
+    configPath,
+    mockSdk,
+    openclawPath,
+    outDir,
+    pluginRoot,
+  });
+  await writeCiOutputArtifacts(report, {
+    ...ciOutputs,
+    cwd: path.dirname(paths.jsonPath),
+    outDir: ".",
+  });
 
   if (json) {
     console.log(JSON.stringify(report, null, 2));
   } else {
-    console.log(renderTextSummary(report));
+    console.log(renderTextSummary(report, { artifacts: paths }));
   }
 
   if (report.status !== "pass") {
@@ -67,19 +104,27 @@ async function runInit(commandArgs) {
   const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
   const configPath = readFlag(commandArgs, "--config") ?? undefined;
   const workflowPath = readFlag(commandArgs, "--workflow") ?? undefined;
-  const packageManager = readFlag(commandArgs, "--package-manager") ?? "npm";
+  const packageManager = readFlag(commandArgs, "--package-manager") ?? undefined;
   const result = await writePluginInspectorInit({
     pluginRoot,
     configPath,
     workflowPath,
     packageManager,
     ci: commandArgs.includes("--ci"),
+    dryRun: commandArgs.includes("--dry-run"),
+    scripts: commandArgs.includes("--scripts"),
     force: commandArgs.includes("--force"),
   });
 
+  if (commandArgs.includes("--json")) {
+    console.log(JSON.stringify(initCommandSummary(result), null, 2));
+    return;
+  }
+
   for (const filePath of result.written) {
-    console.log(`wrote ${filePath}`);
+    console.log(`${result.dryRun ? "would write" : "wrote"} ${path.relative(result.pluginRoot, filePath)}`);
   }
+  console.log(`package manager: ${result.packageManager}`);
 }
 
 async function runReport(command, commandArgs) {
@@ -87,14 +132,20 @@ async function runReport(command, commandArgs) {
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
   const check = commandArgs.includes("--check") || command === "ci";
   const json = commandArgs.includes("--json");
+  const ciOutputs = readCiOutputFlags(commandArgs);
   const config = await loadInspectorConfig(configPath);
   const report = await inspectFixtureSet(config);
-  await writeReport(report, { outDir });
+  const paths = await writeReport(report, { outDir });
+  await writeCiOutputArtifacts(report, {
+    ...ciOutputs,
+    cwd: path.dirname(paths.jsonPath),
+    outDir: ".",
+  });
 
   if (json) {
     console.log(JSON.stringify(report, null, 2));
   } else {
-    console.log(renderTextSummary(report));
+    console.log(renderTextSummary(report, { artifacts: paths }));
   }
 
   if (check && report.status !== "pass") {
@@ -108,8 +159,15 @@ async function runCi(commandArgs) {
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
   const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
   const json = commandArgs.includes("--json");
+  const capture = readRuntimeFlag(commandArgs);
+  const mockSdk = readMockSdkFlag(commandArgs);
+  const allowExecution = readAllowExecutionFlag(commandArgs);
+  const ciOutputs = readCiOutputFlags(commandArgs, { defaultEnabled: true });
   const { report, reportDir } = await runCiCompatibilityReport({
+    allowExecution,
+    capture,
     configPath,
+    mockSdk,
     openclawPath,
     outDir,
     pluginRoot,
@@ -128,6 +186,11 @@ async function runCi(commandArgs) {
     jsonPath: path.join(reportDir, "plugin-inspector-ci-summary.json"),
     markdownPath: path.join(reportDir, "plugin-inspector-ci-summary.md"),
   });
+  await writeCiOutputArtifacts(report, {
+    ...ciOutputs,
+    cwd: reportDir,
+    outDir: ".",
+  });
 
   if (json) {
     console.log(JSON.stringify(summary, null, 2));
@@ -140,7 +203,7 @@ async function runCi(commandArgs) {
   }
 }
 
-async function runCiCompatibilityReport({ configPath, openclawPath, outDir, pluginRoot }) {
+async function runCiCompatibilityReport({ allowExecution, capture, configPath, mockSdk, openclawPath, outDir, pluginRoot }) {
   if (configPath) {
     const config = await loadInspectorConfig(configPath, { cwd: pluginRoot });
     const report = await inspectCompatibilityFixtureSet(config, { openclawPath });
@@ -151,7 +214,7 @@ async function runCiCompatibilityReport({ configPath, openclawPath, outDir, plug
     };
   }
 
-  const { report } = await runPluginCheck({ pluginRoot, outDir, openclawPath });
+  const { report } = await runPluginCheck({ allowExecution, capture, mockSdk, openclawPath, outDir, pluginRoot });
   return {
     report,
     reportDir: path.resolve(pluginRoot ?? process.cwd(), outDir),
@@ -163,11 +226,12 @@ async function runCapture(commandArgs) {
   const outputPath = readFlag(commandArgs, "--output");
   const pluginRoot = readFlag(commandArgs, "--plugin-root");
   const mockSdk = readMockSdkFlag(commandArgs) ?? commandArgs.includes("--mock-sdk");
+  const allowExecution = readAllowExecutionFlag(commandArgs);
   if (!entrypoint) {
     throw new Error("capture requires an entrypoint path");
   }
-  if (process.env.PLUGIN_INSPECTOR_EXECUTE_ISOLATED !== "1") {
-    throw new Error("capture imports plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
+  if (!allowExecution && process.env.PLUGIN_INSPECTOR_EXECUTE_ISOLATED !== "1") {
+    throw new Error("capture imports plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 or --allow-execute in an isolated workspace");
   }
 
   const result = await captureEntrypoint(entrypoint, { mockSdk, pluginRoot });
@@ -187,6 +251,26 @@ function readFlag(commandArgs, name) {
   return commandArgs[index + 1] ?? null;
 }
 
+function readOptionalPathFlag(commandArgs, name, defaultPath) {
+  const index = commandArgs.indexOf(name);
+  if (index === -1) {
+    return null;
+  }
+  const value = commandArgs[index + 1];
+  return value && !value.startsWith("-") ? value : defaultPath;
+}
+
+function readCiOutputFlags(commandArgs, options = {}) {
+  return {
+    sarifPath: commandArgs.includes("--no-sarif")
+      ? null
+      : (readOptionalPathFlag(commandArgs, "--sarif", defaultSarifPath) ?? (options.defaultEnabled ? defaultSarifPath : null)),
+    junitPath: commandArgs.includes("--no-junit")
+      ? null
+      : (readOptionalPathFlag(commandArgs, "--junit", defaultJunitPath) ?? (options.defaultEnabled ? defaultJunitPath : null)),
+  };
+}
+
 function readRuntimeFlag(commandArgs) {
   if (commandArgs.includes("--runtime") || commandArgs.includes("--capture")) {
     return true;
@@ -217,6 +301,10 @@ function readMockSdkFlag(commandArgs) {
   return undefined;
 }
 
+function readAllowExecutionFlag(commandArgs) {
+  return commandArgs.includes("--allow-execute");
+}
+
 function renderCiTextSummary(summary) {
   return [
     `Status: ${summary.status.toUpperCase()}`,
@@ -226,19 +314,43 @@ function renderCiTextSummary(summary) {
   ].join("\n");
 }
 
+function initCommandSummary(result) {
+  return {
+    dryRun: result.dryRun,
+    packageManager: result.packageManager,
+    pluginRoot: result.pluginRoot,
+    files: result.written.map((filePath) => path.relative(result.pluginRoot, filePath)),
+  };
+}
+
+function renderConfigTextSummary(config) {
+  const fixture = config.fixtures[0];
+  return [
+    `Plugin: ${fixture.id}`,
+    `Root: ${config.rootDir}`,
+    `Config: ${config.configPath ?? "auto"}`,
+    `Priority: ${fixture.priority}`,
+    `Seams: ${fixture.seams.join(", ")}`,
+    `Runtime capture: ${config.capture?.runtime === true ? "on" : "off"}`,
+    `Mock SDK: ${config.capture?.mockSdk === false ? "off" : "on"}`,
+  ].join("\n");
+}
+
 function printHelp() {
   console.log(`plugin-inspector
 
 Usage:
   plugin-inspector
-  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--json]
-  plugin-inspector init [--plugin-root <path>] [--config <path>] [--ci] [--package-manager npm|pnpm|yarn|bun] [--force]
+  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--json]
+  plugin-inspector config [--plugin-root <path>] [--config <path>] [--json]
+  plugin-inspector init [--plugin-root <path>] [--config <path>] [--ci] [--scripts] [--package-manager npm|pnpm|yarn|bun] [--dry-run] [--json] [--force]
   plugin-inspector report --config <path> [--out <dir>] [--check] [--json]
-  plugin-inspector inspect --config <path> [--out <dir>] [--check] [--json]
-  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--json]
-  PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector capture <entrypoint> [--mock-sdk|--real-sdk] [--plugin-root <path>] [--output <path>]
+  plugin-inspector inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--check] [--json] [--sarif [path]] [--junit [path]] [--allow-execute]
+  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--json] [--no-sarif] [--no-junit]
+  plugin-inspector capture <entrypoint> [--mock-sdk|--real-sdk] [--allow-execute] [--plugin-root <path>] [--output <path>]
 
 Default check runs from the current plugin root and writes reports/ unless --out is set.
-Runtime capture is opt-in because it imports plugin code; use --runtime with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1.
+CI writes SARIF and JUnit artifacts by default; check/inspect can write them with --sarif and --junit.
+Runtime capture is opt-in because it imports plugin code; use --runtime with --allow-execute or PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1.
 `);
 }

package/src/config.js

@@ -4,6 +4,7 @@ import path from "node:path";
 
 export const npmPackagePayloadDir = ".crabpot-package";
 export const defaultPluginRootConfigFiles = ["plugin-inspector.config.json", ".plugin-inspector.json"];
+export const packageJsonConfigKeys = ["pluginInspector", "plugin-inspector"];
 
 export async function loadInspectorConfig(configPath, options = {}) {
   if (!configPath) {
@@ -24,16 +25,23 @@ export async function loadInspectorConfig(configPath, options = {}) {
 export async function loadPluginRootConfig(configPath = null, options = {}) {
   const rootDir = path.resolve(options.cwd ?? process.cwd());
   const resolvedPath = configPath ? path.resolve(rootDir, configPath) : findPluginRootConfigPath(rootDir);
-  if (!resolvedPath && !existsSync(path.join(rootDir, "package.json")) && !existsSync(path.join(rootDir, "openclaw.plugin.json"))) {
+  const packageJsonPath = path.join(rootDir, "package.json");
+  const packageJson = await readJsonIfExists(packageJsonPath);
+  const packageConfig = packageJsonConfig(packageJson);
+
+  if (!resolvedPath && !packageJson && !existsSync(path.join(rootDir, "openclaw.plugin.json"))) {
     throw new Error("run from a plugin root with package.json/openclaw.plugin.json, or pass --config");
   }
-  const config = resolvedPath ? JSON.parse(await readFile(resolvedPath, "utf8")) : { version: 1 };
+
+  const config = resolvedPath
+    ? JSON.parse(await readFile(resolvedPath, "utf8"))
+    : (packageConfig.config ?? { version: 1 });
   const normalizedConfig = await normalizePluginRootConfig(config, { rootDir });
   validateInspectorConfig(normalizedConfig);
   return {
     ...normalizedConfig,
     rootDir,
-    configPath: resolvedPath,
+    configPath: resolvedPath ?? packageConfig.configPath,
   };
 }
 
@@ -164,6 +172,25 @@ function findPluginRootConfigPath(rootDir) {
   return defaultPluginRootConfigFiles.map((file) => path.join(rootDir, file)).find(existsSync) ?? null;
 }
 
+function packageJsonConfig(packageJson) {
+  if (!packageJson) {
+    return { config: null, configPath: null };
+  }
+  for (const key of packageJsonConfigKeys) {
+    if (packageJson[key] === undefined) {
+      continue;
+    }
+    if (!packageJson[key] || typeof packageJson[key] !== "object" || Array.isArray(packageJson[key])) {
+      throw new Error(`package.json ${key} must be an object`);
+    }
+    return {
+      config: packageJson[key],
+      configPath: `package.json#${key}`,
+    };
+  }
+  return { config: null, configPath: null };
+}
+
 async function readJsonIfExists(filePath) {
   if (!existsSync(filePath)) {
     return null;

package/src/index.js

@@ -1,11 +1,17 @@
 export {
   capturePluginEntrypoint,
   createCaptureApi,
+  inspectCompatibilityFixtureSetConfig,
   inspectFixtureSetConfig,
   inspectPluginRoot,
   loadPluginConfig,
+  renderFixtureSetIssuesReport,
+  renderFixtureSetMarkdownReport,
   renderTextSummary,
+  runFixtureSetReport,
   runPluginCheck,
   setupPluginInspector,
+  writeCiOutputArtifacts,
+  writeFixtureSetReports,
   writePluginReports,
 } from "./api.js";