@openclaw/plugin-inspector 0.0.0 → 0.1.0

package/src/cold-import-readiness.js

@@ -0,0 +1,271 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { slugForArtifact } from "./path-utils.js";
+
+export function buildColdImportReadiness(options = {}) {
+  const report = options.report;
+  if (!report) {
+    throw new TypeError("buildColdImportReadiness requires a compatibility report");
+  }
+
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const sdkExports = new Set(report.targetOpenClaw.sdkExports ?? []);
+  const fixtures = [];
+
+  for (const fixture of report.fixtures) {
+    const sdkBlockers = (fixture.sdkImportDetails ?? [])
+      .filter((sdkImport) => !sdkExports.has(sdkImport.specifier))
+      .map((sdkImport) => `${sdkImport.specifier} @ ${sdkImport.ref}`);
+    const entrypoints = (fixture.packages ?? []).flatMap((packageSummary) =>
+      (packageSummary.openclaw?.entrypoints ?? []).map((entrypoint) =>
+        classifyEntrypointReadiness({
+          fixture,
+          packageSummary,
+          entrypoint,
+          rootDir,
+          sdkBlockers,
+        }),
+      ),
+    );
+
+    fixtures.push({
+      id: fixture.id,
+      priority: fixture.priority,
+      entrypoints,
+    });
+  }
+
+  const allEntrypoints = fixtures.flatMap((fixture) => fixture.entrypoints);
+  return {
+    generatedAt: report.generatedAt,
+    targetOpenClaw: {
+      status: report.targetOpenClaw.status,
+      configuredPath: report.targetOpenClaw.configuredPath,
+      sdkExportCount: report.targetOpenClaw.sdkExportCount ?? 0,
+    },
+    summary: {
+      fixtureCount: fixtures.length,
+      entrypointCount: allEntrypoints.length,
+      readyCount: allEntrypoints.filter((entrypoint) => entrypoint.status === "ready").length,
+      blockedCount: allEntrypoints.filter((entrypoint) => entrypoint.status !== "ready").length,
+      tsLoaderRequiredCount: allEntrypoints.filter((entrypoint) => entrypoint.status === "ts-loader-required").length,
+      buildRequiredCount: allEntrypoints.filter((entrypoint) => entrypoint.status === "build-required").length,
+      dependencyInstallRequiredCount: allEntrypoints.filter((entrypoint) =>
+        entrypoint.blockers.some((blocker) => blocker.code === "dependency-install-required"),
+      ).length,
+      sdkAliasRequiredCount: allEntrypoints.filter((entrypoint) =>
+        entrypoint.blockers.some((blocker) => blocker.code === "sdk-alias-required"),
+      ).length,
+    },
+    fixtures,
+  };
+}
+
+export function validateColdImportReadiness(readiness) {
+  const errors = [];
+
+  for (const fixture of readiness.fixtures) {
+    for (const entrypoint of fixture.entrypoints) {
+      if (!entrypoint.id || !entrypoint.path) {
+        errors.push(`${fixture.id}: entrypoint is missing id or path`);
+      }
+      if (!entrypoint.status) {
+        errors.push(`${entrypoint.id}: missing readiness status`);
+      }
+      if (!Array.isArray(entrypoint.assertions) || entrypoint.assertions.length === 0) {
+        errors.push(`${entrypoint.id}: missing cold-import assertions`);
+      }
+      if (entrypoint.status !== "ready" && entrypoint.blockers.length === 0) {
+        errors.push(`${entrypoint.id}: blocked entrypoint has no blockers`);
+      }
+      for (const blocker of entrypoint.blockers) {
+        if (!blocker.code || !blocker.evidence) {
+          errors.push(`${entrypoint.id}: blocker is missing code or evidence`);
+        }
+      }
+    }
+  }
+
+  return errors;
+}
+
+export async function writeColdImportReadiness(readiness, options = {}) {
+  return writeJsonMarkdownArtifacts({
+    jsonPath: options.jsonPath,
+    markdownPath: options.markdownPath,
+    json: readiness,
+    markdown: renderColdImportReadinessMarkdown(readiness, options),
+    check: options.check,
+  });
+}
+
+export function renderColdImportReadinessMarkdown(readiness, options = {}) {
+  return [
+    `# ${options.title ?? "Plugin Inspector Cold Import Readiness"}`,
+    "",
+    `Generated: ${readiness.generatedAt}`,
+    "",
+    "## Summary",
+    "",
+    markdownTable(
+      [
+        ["Fixtures", readiness.summary.fixtureCount],
+        ["Entrypoints", readiness.summary.entrypointCount],
+        ["Ready", readiness.summary.readyCount],
+        ["Blocked", readiness.summary.blockedCount],
+        ["TypeScript loader required", readiness.summary.tsLoaderRequiredCount],
+        ["Build required", readiness.summary.buildRequiredCount],
+        ["Dependency install required", readiness.summary.dependencyInstallRequiredCount],
+        ["SDK alias required", readiness.summary.sdkAliasRequiredCount],
+      ],
+      ["Metric", "Value"],
+    ),
+    "",
+    "## Entrypoints",
+    "",
+    markdownTable(
+      readiness.fixtures.flatMap((fixture) =>
+        fixture.entrypoints.map((entrypoint) => [
+          fixture.id,
+          entrypoint.kind,
+          entrypoint.status,
+          entrypoint.path,
+          entrypoint.blockers.map((blocker) => blocker.code).join(", ") || "-",
+          entrypoint.assertions.join("; "),
+        ]),
+      ),
+      ["Fixture", "Kind", "Status", "Path", "Blockers", "Assertions"],
+    ),
+  ].join("\n");
+}
+
+function classifyEntrypointReadiness({ fixture, packageSummary, entrypoint, rootDir, sdkBlockers }) {
+  const blockers = [];
+  const resolvedPath = path.resolve(rootDir, entrypoint.relativePath);
+  const extension = path.extname(entrypoint.relativePath);
+
+  if (!entrypoint.exists) {
+    blockers.push({
+      code: entrypoint.requiresBuild ? "build-required" : "missing-entrypoint",
+      message: entrypoint.requiresBuild
+        ? "entrypoint points at build output that is absent in the fixture checkout"
+        : "entrypoint path is missing in the fixture checkout",
+      evidence: entrypoint.relativePath,
+    });
+  } else if (extension === ".ts" || extension === ".tsx") {
+    blockers.push({
+      code: "ts-loader-required",
+      message: "entrypoint is TypeScript source and needs a loader or build step before Node cold import",
+      evidence: entrypoint.relativePath,
+    });
+  } else if (![".js", ".mjs", ".cjs"].includes(extension)) {
+    blockers.push({
+      code: "unknown-entrypoint-extension",
+      message: "entrypoint extension is not directly importable by the default Node runner",
+      evidence: entrypoint.relativePath,
+    });
+  }
+
+  if (entrypoint.exists && existsSync(resolvedPath)) {
+    const source = readSourcePreviewSync(resolvedPath);
+    if (source && /\b(process\.env|spawn\(|execFile\(|exec\(|fetch\(|WebSocket\b)/.test(source)) {
+      blockers.push({
+        code: "top-level-side-effect-review",
+        message: "entrypoint source contains side-effect-prone tokens that cold import must sandbox or review",
+        evidence: entrypoint.relativePath,
+      });
+    }
+  }
+
+  const runtimeDependencies = unique([
+    ...(packageSummary.dependencies ?? []),
+    ...(packageSummary.peerDependencies ?? []),
+    ...(packageSummary.optionalDependencies ?? []),
+  ]);
+  if (entrypoint.exists && runtimeDependencies.length > 0) {
+    blockers.push({
+      code: "dependency-install-required",
+      message: "package declares runtime dependencies that must be installed before cold import",
+      evidence: runtimeDependencies.join(", "),
+    });
+  }
+
+  for (const sdkBlocker of sdkBlockers) {
+    blockers.push({
+      code: "sdk-alias-required",
+      message: "fixture imports an SDK alias missing from target OpenClaw package exports",
+      evidence: sdkBlocker,
+    });
+  }
+
+  return {
+    id: `cold-import.${entrypoint.kind}:${fixture.id}:${slugForArtifact(entrypoint.relativePath)}`,
+    fixture: fixture.id,
+    packagePath: packageSummary.path,
+    kind: entrypoint.kind,
+    specifier: entrypoint.specifier,
+    path: entrypoint.relativePath,
+    status: readinessStatus(blockers),
+    blockers,
+    assertions: coldImportAssertions(blockers),
+  };
+}
+
+function readSourcePreviewSync(filePath) {
+  try {
+    return existsSync(filePath) ? readFileSync(filePath, "utf8").slice(0, 20000) : "";
+  } catch {
+    return "";
+  }
+}
+
+function readinessStatus(blockers) {
+  if (blockers.length === 0) {
+    return "ready";
+  }
+  if (blockers.some((blocker) => blocker.code === "sdk-alias-required")) {
+    return "sdk-alias-required";
+  }
+  if (blockers.some((blocker) => blocker.code === "build-required")) {
+    return "build-required";
+  }
+  if (blockers.some((blocker) => blocker.code === "missing-entrypoint")) {
+    return "missing";
+  }
+  if (blockers.some((blocker) => blocker.code === "ts-loader-required")) {
+    return "ts-loader-required";
+  }
+  if (blockers.some((blocker) => blocker.code === "dependency-install-required")) {
+    return "dependency-install-required";
+  }
+  return "review-required";
+}
+
+function coldImportAssertions(blockers) {
+  if (blockers.length === 0) {
+    return ["entrypoint can be imported by Node without fixture credentials", "registration capture shim receives plugin registrations"];
+  }
+  return blockers.map((blocker) => assertionForBlocker(blocker.code));
+}
+
+function assertionForBlocker(code) {
+  const assertions = {
+    "build-required": "plugin build or source alias resolution runs before cold import",
+    "dependency-install-required": "fixture dependencies are installed in an isolated workspace before cold import",
+    "missing-entrypoint": "plugin package metadata points at an existing OpenClaw entrypoint",
+    "sdk-alias-required": "target OpenClaw exports the imported SDK alias or provides a migration shim",
+    "top-level-side-effect-review": "cold import sandbox blocks network/process side effects before register capture",
+    "ts-loader-required": "TypeScript source entrypoint is compiled or loaded before cold import",
+    "unknown-entrypoint-extension": "entrypoint extension has an explicit loader",
+  };
+  return assertions[code] ?? "cold import blocker has a documented mitigation";
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+function markdownTable(rows, headers) {
+  return renderPaddedMarkdownTable(rows, headers);
+}

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));
+}