@openclaw/plugin-inspector 0.0.0 → 0.1.1

package/src/compatibility-report.js

@@ -0,0 +1,356 @@
+import { renderPaddedMarkdownTable } from "./artifacts.js";
+
+const defaultSeverityLabels = {
+  P0: "P0",
+  P1: "P1",
+  P2: "P2",
+  P3: "P3",
+};
+
+export function renderCompatibilityMarkdownReport(report, options = {}) {
+  return [
+    `# ${options.title ?? "OpenClaw Plugin Compatibility Report"}`,
+    "",
+    `Generated: ${report.generatedAt}`,
+    `Status: ${report.status.toUpperCase()}`,
+    "",
+    "## Summary",
+    "",
+    markdownTable(
+      [
+        ["Fixtures", report.summary.fixtureCount],
+        ["High-priority fixtures", report.summary.highPriorityFixtures],
+        ["Hard breakages", report.summary.breakageCount],
+        ["Warnings", report.summary.warningCount],
+        ["Compatibility suggestions", report.summary.suggestionCount],
+        ["Issue findings", report.summary.issueCount],
+        ["P0 issues", report.summary.p0IssueCount],
+        ["P1 issues", report.summary.p1IssueCount],
+        ["Live issues", report.summary.liveIssueCount],
+        ["Live P0 issues", report.summary.liveP0IssueCount],
+        ["Compat gaps", report.summary.compatGapCount],
+        ["Deprecation warnings", report.summary.deprecationWarningCount],
+        ["Inspector gaps", report.summary.inspectorGapCount],
+        ["Upstream metadata", report.summary.upstreamIssueCount],
+        ["Contract probes", report.summary.contractProbeCount],
+        ["Decision rows", report.summary.decisionCount],
+      ],
+      ["Metric", "Value"],
+    ),
+    "",
+    "## Triage Overview",
+    "",
+    triageOverview(report),
+    "",
+    "## P0 Live Issues",
+    "",
+    issuesTable(
+      report.issues.filter((issue) => issue.issueClass === "live-issue" && issue.severity === "P0"),
+      options,
+    ),
+    "",
+    "## Live Issues",
+    "",
+    issuesTable(report.issues.filter((issue) => issue.issueClass === "live-issue"), options),
+    "",
+    "## Compat Gaps",
+    "",
+    issuesTable(report.issues.filter((issue) => issue.issueClass === "compat-gap"), options),
+    "",
+    "## Deprecation Warnings",
+    "",
+    issuesTable(report.issues.filter((issue) => issue.issueClass === "deprecation-warning"), options),
+    "",
+    "## Inspector Proof Gaps",
+    "",
+    issuesTable(report.issues.filter((issue) => issue.issueClass === "inspector-gap"), options),
+    "",
+    "## Upstream Metadata Issues",
+    "",
+    issuesTable(report.issues.filter((issue) => issue.issueClass === "upstream-metadata"), options),
+    "",
+    "## Hard Breakages",
+    "",
+    findingsTable(report.breakages),
+    "",
+    "## Target OpenClaw Compat Records",
+    "",
+    targetOpenClawTable(report.targetOpenClaw),
+    "",
+    "## Warnings",
+    "",
+    findingsTable(report.warnings),
+    "",
+    "## Suggestions To OpenClaw Compat Layer",
+    "",
+    findingsTable(report.suggestions),
+    "",
+    "## Issue Findings",
+    "",
+    issuesTable(report.issues, options),
+    "",
+    "## Contract Probe Backlog",
+    "",
+    contractProbesTable(report.contractProbes, options),
+    "",
+    "## Fixture Seam Inventory",
+    "",
+    markdownTable(
+      report.fixtures.map((fixture) => [
+        fixture.id,
+        fixture.priority,
+        fixture.seams.join(", "),
+        fixture.hooks.join(", ") || "-",
+        fixture.registrations.join(", ") || "-",
+        fixture.manifestContracts.join(", ") || "-",
+      ]),
+      ["Fixture", "Priority", "Seams", "Hooks", "Registrations", "Manifest contracts"],
+    ),
+    "",
+    "## Decision Matrix",
+    "",
+    markdownTable(
+      report.decisions.map((decision) => [
+        decision.fixture,
+        decision.decision,
+        decision.seam,
+        decision.action,
+        decision.evidence,
+      ]),
+      ["Fixture", "Decision", "Seam", "Action", "Evidence"],
+    ),
+    "",
+    "## Raw Logs",
+    "",
+    findingsTable(report.logs),
+  ].join("\n");
+}
+
+export function renderCompatibilityIssuesReport(report, options = {}) {
+  return [
+    `# ${options.title ?? "OpenClaw Plugin Issue Findings"}`,
+    "",
+    `Generated: ${report.generatedAt}`,
+    `Status: ${report.status.toUpperCase()}`,
+    "",
+    "## Triage Summary",
+    "",
+    markdownTable(
+      [
+        ["Issue findings", report.summary.issueCount],
+        [severityLabel("P0", options), report.summary.p0IssueCount],
+        [severityLabel("P1", options), report.summary.p1IssueCount],
+        ["Live issues", report.summary.liveIssueCount],
+        ["Live P0 issues", report.summary.liveP0IssueCount],
+        ["Compat gaps", report.summary.compatGapCount],
+        ["Deprecation warnings", report.summary.deprecationWarningCount],
+        ["Inspector gaps", report.summary.inspectorGapCount],
+        ["Upstream metadata", report.summary.upstreamIssueCount],
+        ["Contract probes", report.summary.contractProbeCount],
+      ],
+      ["Metric", "Value"],
+    ),
+    "",
+    "## Triage Overview",
+    "",
+    triageOverview(report),
+    "",
+    "## P0 Live Issues",
+    "",
+    issuesTable(
+      report.issues.filter((issue) => issue.issueClass === "live-issue" && issue.severity === "P0"),
+      options,
+    ),
+    "",
+    "## Live Issues",
+    "",
+    issuesTable(report.issues.filter((issue) => issue.issueClass === "live-issue"), options),
+    "",
+    "## Compat Gaps",
+    "",
+    issuesTable(report.issues.filter((issue) => issue.issueClass === "compat-gap"), options),
+    "",
+    "## Deprecation Warnings",
+    "",
+    issuesTable(report.issues.filter((issue) => issue.issueClass === "deprecation-warning"), options),
+    "",
+    "## Inspector Proof Gaps",
+    "",
+    issuesTable(report.issues.filter((issue) => issue.issueClass === "inspector-gap"), options),
+    "",
+    "## Upstream Metadata Issues",
+    "",
+    issuesTable(report.issues.filter((issue) => issue.issueClass === "upstream-metadata"), options),
+    "",
+    "## Issues",
+    "",
+    issuesTable(report.issues, options),
+    "",
+    "## Contract Probe Backlog",
+    "",
+    contractProbesTable(report.contractProbes, options),
+  ].join("\n");
+}
+
+function findingsTable(findings) {
+  if (findings.length === 0) {
+    return "_none_";
+  }
+
+  return markdownTable(
+    findings.map((finding) => [
+      finding.fixture,
+      finding.code,
+      finding.level,
+      finding.message,
+      (finding.evidence ?? []).join(", ") || "-",
+      finding.compatRecord ?? "-",
+    ]),
+    ["Fixture", "Code", "Level", "Message", "Evidence", "Compat record"],
+  );
+}
+
+function issuesTable(issues, options) {
+  if (issues.length === 0) {
+    return "_none_";
+  }
+
+  return issues.map((issue) => issueBlock(issue, options)).join("\n\n");
+}
+
+function issueBlock(issue, options) {
+  return [
+    `- ${severityLabel(issue.severity, options)} **${issue.fixture}** \`${issue.issueClass}\` \`${issue.decision}\``,
+    `  - **${issue.code}**: ${issue.title}`,
+    `  - state: ${issueState(issue)}`,
+    "  - evidence:",
+    ...evidenceList(issue.evidence, options).map((item) => `    - ${item}`),
+  ].join("\n");
+}
+
+function issueState(issue) {
+  const flags = [
+    issue.status,
+    `compat:${issue.compatStatus ?? "none"}`,
+    issue.live ? "live" : null,
+    issue.deprecated ? "deprecated" : null,
+  ].filter(Boolean);
+  return flags.join(" · ");
+}
+
+function triageOverview(report) {
+  return markdownTable(
+    [
+      [
+        "live-issue",
+        report.summary.liveIssueCount,
+        report.summary.liveP0IssueCount,
+        "Potential runtime breakage in the target OpenClaw/plugin pair. P0 only when it is not a deprecated compat seam.",
+      ],
+      [
+        "compat-gap",
+        report.summary.compatGapCount,
+        "-",
+        "Compatibility behavior is needed but missing from the target OpenClaw compat registry.",
+      ],
+      [
+        "deprecation-warning",
+        report.summary.deprecationWarningCount,
+        "-",
+        "Plugin uses a supported but deprecated compatibility seam; keep it wired while migration exists.",
+      ],
+      [
+        "inspector-gap",
+        report.summary.inspectorGapCount,
+        "-",
+        "Plugin Inspector needs stronger capture/probe evidence before making contract judgments.",
+      ],
+      [
+        "upstream-metadata",
+        report.summary.upstreamIssueCount,
+        "-",
+        "Plugin package or manifest metadata should improve upstream; not a target OpenClaw live break by itself.",
+      ],
+      [
+        "fixture-regression",
+        report.summary.fixtureRegressionCount,
+        "-",
+        "Fixture no longer exposes an expected seam; investigate fixture pin or scanner drift.",
+      ],
+    ],
+    ["Class", "Count", "P0", "Meaning"],
+  );
+}
+
+function contractProbesTable(probes, options) {
+  if (probes.length === 0) {
+    return "_none_";
+  }
+
+  return probes.map((probe) => contractProbeBlock(probe, options)).join("\n\n");
+}
+
+function contractProbeBlock(probe, options) {
+  return [
+    `- ${severityLabel(probe.priority, options)} **${probe.fixture}** \`${probe.target}\``,
+    `  - contract: ${probe.contract}`,
+    `  - id: \`${probe.id}\``,
+    "  - evidence:",
+    ...evidenceList(probe.evidence, options).map((item) => `    - ${item}`),
+  ].join("\n");
+}
+
+function targetOpenClawTable(targetOpenClaw = {}) {
+  const compatRecords = targetOpenClaw.compatRecords ?? [];
+  const recordPreview = compatRecords.length > 0 ? compatRecords.join(", ") : "-";
+  const statusCounts = Object.values(targetOpenClaw.compatRecordStatuses ?? {}).reduce((counts, status) => {
+    counts[status] = (counts[status] ?? 0) + 1;
+    return counts;
+  }, {});
+  return markdownTable(
+    [
+      ["Configured path", targetOpenClaw.configuredPath ?? "-"],
+      ["Status", targetOpenClaw.status],
+      ["Compat registry", targetOpenClaw.compatRegistryPath ?? "-"],
+      ["Compat records", targetOpenClaw.compatRecordCount ?? 0],
+      ["Compat status counts", Object.entries(statusCounts).map(([status, count]) => `${status}:${count}`).join(", ") || "-"],
+      ["Record ids", recordPreview],
+      ["Hook registry", targetOpenClaw.hookTypesPath ?? "-"],
+      ["Hook names", targetOpenClaw.hookNameCount ?? 0],
+      ["API builder", targetOpenClaw.apiBuilderPath ?? "-"],
+      ["API registrars", targetOpenClaw.apiRegistrarCount ?? 0],
+      ["Captured registration", targetOpenClaw.capturedRegistrationPath ?? "-"],
+      ["Captured registrars", targetOpenClaw.capturedRegistrarCount ?? 0],
+      ["Package metadata", targetOpenClaw.packagePath ?? "-"],
+      ["Plugin SDK exports", targetOpenClaw.sdkExportCount ?? 0],
+      ["Manifest types", targetOpenClaw.manifestTypesPath ?? "-"],
+      ["Manifest fields", targetOpenClaw.manifestFieldCount ?? 0],
+      ["Manifest contract fields", targetOpenClaw.manifestContractFieldCount ?? 0],
+    ],
+    ["Metric", "Value"],
+  );
+}
+
+function markdownTable(rows, headers) {
+  return renderPaddedMarkdownTable(
+    rows.map((row) => row.map((cell) => escapeCell(String(cell)))),
+    headers.map((header) => escapeCell(String(header))),
+  );
+}
+
+function escapeCell(value) {
+  return String(value).replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+function severityLabel(severity, options) {
+  return { ...defaultSeverityLabels, ...options.severityLabels }[severity] ?? severity ?? "-";
+}
+
+function evidenceList(evidence, options) {
+  const items = (evidence ?? []).filter(Boolean);
+  if (items.length === 0) {
+    return ["-"];
+  }
+  const formatEvidence = options.formatEvidence ?? ((item) => item);
+  return items.map((item) => formatEvidence(item));
+}

package/src/config.js

@@ -0,0 +1,182 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export const npmPackagePayloadDir = ".crabpot-package";
+export const defaultPluginRootConfigFiles = ["plugin-inspector.config.json", ".plugin-inspector.json"];
+
+export async function loadInspectorConfig(configPath, options = {}) {
+  if (!configPath) {
+    throw new Error("--config is required");
+  }
+  const resolvedPath = path.resolve(options.cwd ?? process.cwd(), configPath);
+  const config = JSON.parse(await readFile(resolvedPath, "utf8"));
+  const rootDir = path.resolve(options.cwd ?? process.cwd(), options.rootDir ?? path.dirname(resolvedPath));
+  const normalizedConfig = await normalizeInspectorConfig(config, { rootDir });
+  validateInspectorConfig(normalizedConfig);
+  return {
+    ...normalizedConfig,
+    rootDir,
+    configPath: resolvedPath,
+  };
+}
+
+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"))) {
+    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 normalizedConfig = await normalizePluginRootConfig(config, { rootDir });
+  validateInspectorConfig(normalizedConfig);
+  return {
+    ...normalizedConfig,
+    rootDir,
+    configPath: resolvedPath,
+  };
+}
+
+export function validateInspectorConfig(config) {
+  const errors = [];
+
+  if (config.version !== 1) {
+    errors.push("config.version must be 1");
+  }
+
+  if (!config.submoduleRoot || typeof config.submoduleRoot !== "string") {
+    errors.push("config.submoduleRoot must be set");
+  }
+
+  if (!Array.isArray(config.fixtures) || config.fixtures.length === 0) {
+    errors.push("config.fixtures must be a non-empty array");
+  }
+
+  const ids = new Set();
+  const paths = new Set();
+  for (const fixture of config.fixtures ?? []) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(fixture.id ?? "")) {
+      errors.push(`invalid fixture id: ${fixture.id}`);
+    }
+    if (ids.has(fixture.id)) {
+      errors.push(`duplicate fixture id: ${fixture.id}`);
+    }
+    ids.add(fixture.id);
+
+    if (typeof fixture.path !== "string" || fixture.path.length === 0) {
+      errors.push(`${fixture.id}: path must be set`);
+    }
+    if (paths.has(fixture.path)) {
+      errors.push(`duplicate fixture path: ${fixture.path}`);
+    }
+    paths.add(fixture.path);
+
+    const hasRepo = typeof fixture.repo === "string";
+    const hasPackage = fixture.package && typeof fixture.package === "object";
+    if (hasRepo === hasPackage) {
+      errors.push(`${fixture.id}: fixture must declare exactly one of repo or package`);
+    }
+    if (!["high", "medium", "low"].includes(fixture.priority)) {
+      errors.push(`${fixture.id}: priority must be high, medium, or low`);
+    }
+    if (!Array.isArray(fixture.seams) || fixture.seams.length === 0) {
+      errors.push(`${fixture.id}: seams must be non-empty`);
+    }
+    for (const key of ["hooks", "registrations", "manifestContracts"]) {
+      const values = fixture.expect?.[key];
+      if (values !== undefined && (!Array.isArray(values) || values.length === 0)) {
+        errors.push(`${fixture.id}: expect.${key} must be a non-empty array when present`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+}
+
+export function fixtureCheckoutPath(config, fixture) {
+  return path.resolve(config.rootDir ?? process.cwd(), fixture.path);
+}
+
+export function fixtureSourceRoot(config, fixture) {
+  const checkoutPath = fixtureCheckoutPath(config, fixture);
+  if (fixture.subdir) {
+    return path.join(checkoutPath, fixture.subdir);
+  }
+  if (fixture.package) {
+    return path.join(checkoutPath, npmPackagePayloadDir);
+  }
+  return checkoutPath;
+}
+
+export async function normalizePluginRootConfig(config, options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const plugin = config.plugin ?? {};
+  const packageJson = await readJsonIfExists(path.join(rootDir, "package.json"));
+  const pluginManifest = await readJsonIfExists(path.join(rootDir, "openclaw.plugin.json"));
+  const sourceRoot = plugin.sourceRoot ?? config.sourceRoot ?? ".";
+  const fixture = {
+    id: plugin.id ?? pluginManifest?.id ?? packageId(packageJson?.name) ?? "plugin",
+    name: plugin.name ?? pluginManifest?.name ?? packageJson?.name ?? "Plugin",
+    path: ".",
+    repo: "local",
+    priority: plugin.priority ?? config.priority ?? "high",
+    seams: plugin.seams ?? config.seams ?? inferPluginSeams(pluginManifest, packageJson),
+    why: plugin.why ?? config.why ?? "local OpenClaw plugin root",
+    expect: plugin.expect ?? config.expect,
+  };
+
+  if (sourceRoot !== ".") {
+    fixture.subdir = sourceRoot;
+  }
+
+  return {
+    version: 1,
+    submoduleRoot: ".",
+    openclaw: config.openclaw,
+    fixtures: [fixture],
+  };
+}
+
+export async function normalizeInspectorConfig(config, options = {}) {
+  if (Array.isArray(config.fixtures)) {
+    return config;
+  }
+  return normalizePluginRootConfig(config, options);
+}
+
+function findPluginRootConfigPath(rootDir) {
+  return defaultPluginRootConfigFiles.map((file) => path.join(rootDir, file)).find(existsSync) ?? null;
+}
+
+async function readJsonIfExists(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  return JSON.parse(await readFile(filePath, "utf8"));
+}
+
+function packageId(packageName) {
+  if (!packageName) {
+    return null;
+  }
+  return packageName
+    .split("/")
+    .pop()
+    .replace(/^openclaw-/, "")
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+function inferPluginSeams(pluginManifest, packageJson) {
+  const contracts = Object.keys(pluginManifest?.contracts ?? {});
+  if (contracts.includes("tools")) {
+    return ["dynamic-tool"];
+  }
+  if (packageJson?.openclaw?.extensions || packageJson?.openclaw?.runtimeExtensions) {
+    return ["plugin-runtime"];
+  }
+  return ["plugin-metadata"];
+}