@openclaw/plugin-inspector 0.3.10 → 0.3.12

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## Unreleased
 
+## 0.3.12 - 2026-06-09
+
+### Changed
+
+- Hide maintainer-facing `inspector-gap` findings from author-facing `check`, `ci`, and `batch` output by default, with `--include-inspector-gaps` for internal coverage reports.
+
+## 0.3.11 - 2026-05-26
+
+### Fixed
+
+- Classify the latest generated kitchen-sink registrars for meeting notes, node CLI features, hosted media, model catalogs, embedding providers, and session actions.
+- Stop classifying package source entrypoints as missing when the published package provides built runtime entrypoints, and collapse SDK alias findings into a single compat-gap row.
+- Treat compat-gap issues as reconciled contract coverage for their own compatibility record.
+- Count passed synthetic hook probes as runtime coverage so conversation-access and `before_tool_call` inspector gaps close when probe artifacts prove them.
+- Keep mock-SDK synthetic probes in-process so retained hook and registration handlers remain callable, and harden dynamic root SDK mock exports.
+- Synthesize nested manifest config samples for optional object settings with required inner shape.
+- Populate message and agent lifecycle synthetic hook payloads with the fields telemetry plugins commonly read.
+- Resolve plugin manifests from parent directories when runtime capture starts from built `dist` entrypoints.
+- Capture CLIs no longer treat `--output`, `--plugin-root`, or `--sdk` flag values as the positional entrypoint. Thanks @KrasimirKralev.
+- Mock-SDK TypeScript capture now falls back to Node's strip-only parser on Node 26.
+
 ## 0.3.10 - 2026-05-03
 
 ### Fixed

package/README.md

@@ -170,6 +170,7 @@ Copy-ready examples live in:
 | `plugin-inspector config` | Print resolved plugin-root config as text or JSON. |
 | `plugin-inspector init` | Write starter config, scripts, and optional GitHub Actions workflow. |
 | `plugin-inspector report` | Run a fixture-suite config with many plugins. |
+| `plugin-inspector batch` | Discover plugin roots under a folder and write one aggregate impact report. |
 | `plugin-inspector capture` | Runtime-capture one entrypoint directly. |
 
 Common options:
@@ -186,6 +187,7 @@ Common options:
 | `--mock-sdk` / `--sdk mock` | Use generated SDK and external-package mocks for runtime capture. |
 | `--real-sdk` / `--sdk real` | Use installed real SDK dependencies instead of mocks. |
 | `--allow-execute` | Permit commands that import plugin code. |
+| `--include-inspector-gaps` | Include maintainer-facing scanner coverage gaps in `check`, `ci`, and `batch` output. |
 | `--json` | Print machine-readable JSON to stdout. |
 | `--sarif [path]` | Write SARIF from `check` or `inspect`; `ci` enables this by default. |
 | `--junit [path]` | Write JUnit XML from `check` or `inspect`; `ci` enables this by default. |
@@ -305,8 +307,9 @@ Important report sections:
 | `logs` | Informational inventory and coverage rows. |
 | `decisions` | Maintainer-facing follow-up or compatibility-policy decisions. |
 
-Issue classes currently flow through the reports as live issues, compat gaps,
-deprecation warnings, inspector gaps, upstream metadata, and fixture regressions.
+Author-facing `check`, `ci`, and `batch` output hides inspector gaps by default
+because they are scanner coverage backlog, not plugin-author fixes. Pass
+`--include-inspector-gaps` for Crabpot-style maintainer coverage reports.
 
 ## CI Policy And Shared Reporting Primitives
 
@@ -404,6 +407,7 @@ Stable grouped facades:
 | `reports` | Render/write reports and classify issue findings. |
 | `contracts` | Build, render, validate, and write contract captures and coverage. |
 | `ci` | Build summaries, policy reports, execution results, SARIF, and JUnit outputs. |
+| `batch` | Discover plugin roots and aggregate compatibility findings across a corpus. |
 | `runtime` | Build runtime profiles, profile diffs, ref diffs, and import-loop profiles. |
 | `synthetic` | Build and run synthetic probe plans. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",
@@ -56,7 +56,13 @@
     "release:readiness": "npm run release:local && npm run release:crabpot",
     "release:local": "npm run check",
     "release:notes": "node scripts/release-notes.mjs --unreleased",
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "check:changed": "npm run check",
+    "test:changed": "npm test",
+    "crabbox:hydrate": "crabbox actions hydrate",
+    "crabbox:run": "crabbox run",
+    "crabbox:stop": "crabbox stop",
+    "crabbox:warmup": "crabbox warmup"
   },
   "keywords": [
     "openclaw",

package/src/advanced.js

@@ -194,6 +194,7 @@ export {
   writeRuntimeCaptureReport,
 } from "./runtime-capture-report.js";
 export { createMockSdkPackage } from "./sdk-mock.js";
+export { runEntrypointSyntheticProbes } from "./synthetic-entrypoint.js";
 export {
   buildSyntheticProbePlan,
   defaultSyntheticHookContexts,

package/src/api.js

@@ -44,6 +44,7 @@ export async function inspectPluginRoot(options = {}) {
   const config = await loadPluginConfig(options);
   return inspectCompatibilityFixtureSet(config, {
     generatedAt: options.generatedAt,
+    includeInspectorGaps: options.includeInspectorGaps,
     openclawPath: options.openclawPath,
     executionResults: options.executionResults,
     targetOpenClaw: options.targetOpenClaw,
@@ -59,6 +60,7 @@ export async function inspectCompatibilityFixtureSetConfig(options = {}) {
   const config = await loadFixtureSetConfig(options);
   return inspectCompatibilityFixtureSet(config, {
     generatedAt: options.generatedAt,
+    includeInspectorGaps: options.includeInspectorGaps,
     openclawPath: options.openclawPath,
     executionResults: options.executionResults,
     targetOpenClaw: options.targetOpenClaw,
@@ -113,6 +115,7 @@ export async function buildFixtureSetColdImportReadiness(options = {}) {
     options.report ??
     (await inspectCompatibilityFixtureSet(config, {
       generatedAt: options.generatedAt,
+      includeInspectorGaps: options.includeInspectorGaps,
       openclawPath: options.openclawPath,
       executionResults: options.executionResults,
       targetOpenClaw: options.targetOpenClaw,
@@ -145,6 +148,7 @@ export async function buildFixtureSetWorkspacePlan(options = {}) {
     options.report ??
     (await inspectCompatibilityFixtureSet(config, {
       generatedAt: options.generatedAt,
+      includeInspectorGaps: options.includeInspectorGaps,
       openclawPath: options.openclawPath,
       executionResults: options.executionResults,
       targetOpenClaw: options.targetOpenClaw,

package/src/batch.js

@@ -0,0 +1,297 @@
+import { existsSync } from "node:fs";
+import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { renderMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { runPluginCheck } from "./api.js";
+
+const ignoredDirs = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  "node_modules",
+  "reports",
+  "dist",
+  "build",
+  ".plugin-inspector",
+]);
+
+export async function runBatchAnalysis(options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? options.inputDir ?? process.cwd());
+  const outDir = options.outDir ?? "reports";
+  const outRoot = path.resolve(rootDir, outDir);
+  const concurrency = Math.max(1, Math.min(Math.round(options.concurrency ?? 4), 32));
+  const keepPluginReports = options.keepPluginReports === true;
+  const pluginRoots = await discoverPluginRoots(rootDir);
+  const tempRoot = keepPluginReports ? null : await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-batch-"));
+  const entries = [];
+
+  try {
+    await runWithConcurrency(pluginRoots, concurrency, async (pluginRoot) => {
+      const reportsRoot = keepPluginReports
+        ? path.join(outRoot, "plugins", slugForPath(path.relative(rootDir, pluginRoot)))
+        : path.join(tempRoot, slugForPath(path.relative(rootDir, pluginRoot)));
+      entries.push(
+        await inspectBatchPlugin(pluginRoot, {
+          ...options,
+          rootDir,
+          outDir: reportsRoot,
+          openclawPath: options.openclawPath,
+        }),
+      );
+    });
+  } finally {
+    if (tempRoot) await rm(tempRoot, { recursive: true, force: true });
+  }
+
+  entries.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  const report = buildBatchReport({
+    rootDir,
+    entries,
+    generatedAt: options.generatedAt ?? new Date().toISOString(),
+  });
+  const paths = await writeBatchReport(report, { outDir: outRoot, check: options.checkArtifacts });
+  return { report, paths };
+}
+
+export async function discoverPluginRoots(rootDir) {
+  const roots = [];
+  await walk(path.resolve(rootDir));
+  roots.sort();
+  return roots;
+
+  async function walk(dir) {
+    if (await isPluginRoot(dir)) {
+      roots.push(dir);
+      return;
+    }
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || ignoredDirs.has(entry.name)) continue;
+      await walk(path.join(dir, entry.name));
+    }
+  }
+}
+
+export async function writeBatchReport(report, options = {}) {
+  return writeJsonMarkdownArtifacts({
+    jsonPath: path.join(options.outDir ?? "reports", "plugin-inspector-batch-report.json"),
+    markdownPath: path.join(options.outDir ?? "reports", "plugin-inspector-batch-report.md"),
+    json: report,
+    markdown: renderBatchMarkdown(report),
+    check: options.check,
+  });
+}
+
+function buildBatchReport({ rootDir, entries, generatedAt }) {
+  const findingFrequency = findingFrequencyRows(entries);
+  const summary = {
+    pluginCount: entries.length,
+    passed: entries.filter((entry) => entry.status === "pass").length,
+    failed: entries.filter((entry) => entry.status !== "pass").length,
+    pluginsWithErrors: entries.filter((entry) => entry.errorCount > 0).length,
+    pluginsWithWarnings: entries.filter((entry) => entry.warningCount > 0).length,
+    errorCount: entries.reduce((sum, entry) => sum + entry.errorCount, 0),
+    warningCount: entries.reduce((sum, entry) => sum + entry.warningCount, 0),
+    findingCodeCount: findingFrequency.length,
+  };
+  return {
+    generatedAt,
+    rootDir,
+    summary,
+    findingFrequency,
+    plugins: entries,
+  };
+}
+
+async function inspectBatchPlugin(pluginRoot, options) {
+  try {
+    const { report } = await runPluginCheck({
+      allowExecution: options.allowExecution,
+      capture: options.capture,
+      configPath: options.configPath,
+      includeInspectorGaps: options.includeInspectorGaps,
+      mockSdk: options.mockSdk,
+      openclawPath: options.openclawPath,
+      outDir: options.outDir,
+      pluginRoot,
+    });
+    const findings = normalizeReportFindings(report);
+    return {
+      pluginRoot,
+      relativePath: path.relative(options.rootDir ?? process.cwd(), pluginRoot) || ".",
+      status: report.status,
+      packageName: packageNameFromReport(report),
+      targetOpenClaw: report.targetOpenClaw,
+      errorCount: findings.filter((finding) => finding.kind === "error").length,
+      warningCount: findings.filter((finding) => finding.kind === "warning").length,
+      findings,
+    };
+  } catch (error) {
+    return {
+      pluginRoot,
+      relativePath: path.relative(options.rootDir ?? process.cwd(), pluginRoot) || ".",
+      status: "error",
+      packageName: path.basename(pluginRoot),
+      targetOpenClaw: null,
+      errorCount: 1,
+      warningCount: 0,
+      findings: [
+        {
+          kind: "error",
+          code: "plugin-inspector-batch-failure",
+          message: error instanceof Error ? error.message : String(error),
+        },
+      ],
+    };
+  }
+}
+
+function normalizeReportFindings(report) {
+  return [
+    ...(report.breakages ?? []).map((finding) => normalizeFinding(finding, "error")),
+    ...(report.issues ?? []).map((finding) =>
+      normalizeFinding(
+        finding,
+        finding.status === "blocking" || finding.severity === "P0" ? "error" : "warning",
+      ),
+    ),
+    ...(report.warnings ?? []).map((finding) => normalizeFinding(finding, "warning")),
+    ...(report.suggestions ?? []).map((finding) => normalizeFinding(finding, "warning")),
+  ];
+}
+
+function normalizeFinding(finding, kind) {
+  return {
+    kind,
+    code: finding.code ?? "plugin-inspector-finding",
+    severity: finding.severity,
+    issueClass: finding.issueClass,
+    message: finding.message ?? finding.title ?? "See plugin report.",
+    evidence: finding.evidence,
+  };
+}
+
+function findingFrequencyRows(entries) {
+  const byCode = new Map();
+  for (const entry of entries) {
+    const seenForPlugin = new Set();
+    for (const finding of entry.findings) {
+      const current = byCode.get(finding.code) ?? {
+        code: finding.code,
+        count: 0,
+        plugins: 0,
+        errors: 0,
+        warnings: 0,
+      };
+      current.count += 1;
+      if (!seenForPlugin.has(finding.code)) {
+        current.plugins += 1;
+        seenForPlugin.add(finding.code);
+      }
+      if (finding.kind === "error") current.errors += 1;
+      else current.warnings += 1;
+      byCode.set(finding.code, current);
+    }
+  }
+  return [...byCode.values()].sort((a, b) => b.plugins - a.plugins || b.count - a.count);
+}
+
+function renderBatchMarkdown(report) {
+  return [
+    "# Plugin Inspector Batch Report",
+    "",
+    `Generated: ${report.generatedAt}`,
+    `Root: ${report.rootDir}`,
+    "",
+    "## Summary",
+    "",
+    renderMarkdownTable(
+      [
+        ["Plugins", report.summary.pluginCount],
+        ["Passed", report.summary.passed],
+        ["Failed", report.summary.failed],
+        ["Plugins with errors", report.summary.pluginsWithErrors],
+        ["Plugins with warnings", report.summary.pluginsWithWarnings],
+        ["Errors", report.summary.errorCount],
+        ["Warnings", report.summary.warningCount],
+      ],
+      ["Metric", "Value"],
+    ),
+    "",
+    "## Finding Frequency",
+    "",
+    report.findingFrequency.length
+      ? renderMarkdownTable(
+          report.findingFrequency.map((row) => [
+            row.code,
+            row.plugins,
+            row.count,
+            row.errors,
+            row.warnings,
+          ]),
+          ["Code", "Plugins", "Findings", "Errors", "Warnings"],
+        )
+      : "_No findings._",
+    "",
+    "## Plugins",
+    "",
+    report.plugins.length
+      ? renderMarkdownTable(
+          report.plugins.map((plugin) => [
+            plugin.packageName,
+            plugin.relativePath,
+            plugin.status,
+            plugin.errorCount,
+            plugin.warningCount,
+          ]),
+          ["Package", "Path", "Status", "Errors", "Warnings"],
+        )
+      : "_No plugin roots discovered._",
+  ].join("\n");
+}
+
+async function runWithConcurrency(items, concurrency, worker) {
+  let index = 0;
+  const runners = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (index < items.length) {
+      const item = items[index];
+      index += 1;
+      await worker(item);
+    }
+  });
+  await Promise.all(runners);
+}
+
+async function isPluginRoot(dir) {
+  if (existsSync(path.join(dir, "plugin-inspector.config.json"))) return true;
+  if (existsSync(path.join(dir, ".plugin-inspector.json"))) return true;
+  if (existsSync(path.join(dir, "openclaw.plugin.json"))) return true;
+  const packageJsonPath = path.join(dir, "package.json");
+  if (!existsSync(packageJsonPath)) return false;
+  try {
+    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    return Boolean(packageJson.openclaw || packageJson.pluginInspector || packageJson["plugin-inspector"]);
+  } catch {
+    return false;
+  }
+}
+
+function packageNameFromReport(report) {
+  return (
+    report.fixtures?.[0]?.package?.packageJson?.name ??
+    report.fixtures?.[0]?.package?.name ??
+    report.fixtures?.[0]?.name ??
+    report.fixtures?.[0]?.id ??
+    "plugin"
+  );
+}
+
+function slugForPath(value) {
+  return (
+    String(value)
+      .replaceAll(path.sep, "-")
+      .replace(/[^a-zA-Z0-9._-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "plugin"
+  );
+}

package/src/capture-cli.js

@@ -11,7 +11,7 @@ try {
 }
 
 async function run(commandArgs) {
-  const entrypoint = commandArgs.find((arg) => !arg.startsWith("-"));
+  const entrypoint = findEntrypoint(commandArgs);
   const outputPath = readFlag(commandArgs, "--output");
   const pluginRoot = readFlag(commandArgs, "--plugin-root");
   const mockSdk = readMockSdkFlag(commandArgs) ?? true;
@@ -40,6 +40,17 @@ function readFlag(commandArgs, name) {
   return commandArgs[index + 1] ?? null;
 }
 
+function findEntrypoint(commandArgs) {
+  const flagsWithValues = new Set(["--output", "--plugin-root", "--sdk"]);
+  const consumedIndexes = new Set();
+  for (const [index, arg] of commandArgs.entries()) {
+    if (flagsWithValues.has(arg)) {
+      consumedIndexes.add(index + 1);
+    }
+  }
+  return commandArgs.find((arg, index) => !arg.startsWith("-") && !consumedIndexes.has(index)) ?? null;
+}
+
 function readMockSdkFlag(commandArgs) {
   const sdk = readFlag(commandArgs, "--sdk");
   if (sdk === "mock") {

package/src/capture-config.js

@@ -17,7 +17,10 @@ export async function captureApiOptionsForPlugin(apiOptions = {}, options = {})
 }
 
 async function readSamplePluginConfig(pluginRoot) {
-  const manifestPath = path.join(pluginRoot, "openclaw.plugin.json");
+  const manifestPath = await findNearestManifestPath(pluginRoot);
+  if (!manifestPath) {
+    return undefined;
+  }
   let manifest;
   try {
     manifest = JSON.parse(await readFile(manifestPath, "utf8"));
@@ -29,6 +32,23 @@ async function readSamplePluginConfig(pluginRoot) {
   return isPlainObject(sample) && Object.keys(sample).length > 0 ? sample : undefined;
 }
 
+async function findNearestManifestPath(pluginRoot) {
+  let current = path.resolve(pluginRoot);
+  while (true) {
+    const manifestPath = path.join(current, "openclaw.plugin.json");
+    try {
+      await readFile(manifestPath, "utf8");
+      return manifestPath;
+    } catch {}
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
 function sampleJsonSchema(schema, context = {}) {
   if (!isPlainObject(schema)) {
     return undefined;
@@ -83,6 +103,16 @@ function sampleObjectSchema(schema) {
     }
   }
 
+  if (!hasNonBooleanSample(output, properties)) {
+    const key = preferredNestedConfigKey(properties);
+    if (key) {
+      const value = sampleJsonSchema(properties[key], { key });
+      if (value !== undefined) {
+        output[key] = value;
+      }
+    }
+  }
+
   if (Object.keys(output).length === 0 && Number(schema.minProperties ?? 0) > 0) {
     const key = preferredSamplePropertyKey(properties);
     if (key) {
@@ -96,6 +126,24 @@ function sampleObjectSchema(schema) {
   return output;
 }
 
+function hasNonBooleanSample(output, properties) {
+  return Object.keys(output).some((key) => properties[key]?.type !== "boolean");
+}
+
+function preferredNestedConfigKey(properties) {
+  for (const key of ["embedding", "credentials", "auth", "provider", ...Object.keys(properties)]) {
+    const schema = properties[key];
+    if (!isPlainObject(schema)) {
+      continue;
+    }
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    if ((schema.type === "object" || schema.properties) && (Number(schema.minProperties ?? 0) > 0 || required.length > 0)) {
+      return key;
+    }
+  }
+  return null;
+}
+
 function preferredSamplePropertyKey(properties) {
   for (const key of ["provider", "model", "apiKey", "id", "name", ...Object.keys(properties)]) {
     if (Object.prototype.hasOwnProperty.call(properties, key)) {