@openclaw/plugin-inspector 0.0.0 → 0.1.1

package/src/capture-api.js

@@ -0,0 +1,115 @@
+export function createCaptureApi(options = {}) {
+  const captured = [];
+  const retained = [];
+  const knownRegistrars = new Set(options.knownRegistrars ?? []);
+  const retainHandlers = options.retainHandlers === true;
+
+  const api = new Proxy(
+    {
+      config: options.config ?? {},
+      logger: options.logger ?? console,
+      pluginConfig: options.pluginConfig ?? {},
+      runtime: options.runtime ?? {},
+      on(name, handler) {
+        const captureIndex =
+          captured.push({
+            kind: "hook",
+            name,
+            handlerType: typeof handler,
+            arguments: summarizeArguments([name, handler]),
+          }) - 1;
+        if (retainHandlers) {
+          retained.push({
+            kind: "hook",
+            name,
+            handler,
+            captureIndex,
+          });
+        }
+        return api;
+      },
+    },
+    {
+      get(target, property) {
+        if (property === "getCapturedContracts") {
+          return () => captured.map((entry) => ({ ...entry }));
+        }
+        if (property === "getRetainedContracts") {
+          return () => retained.map((entry) => ({ ...entry }));
+        }
+        if (property in target) {
+          return target[property];
+        }
+        if (typeof property === "string" && isRegistrarProperty(property)) {
+          return (...args) => {
+            const captureIndex =
+              captured.push({
+                kind: "registration",
+                name: property,
+                known: knownRegistrars.size === 0 ? null : knownRegistrars.has(property),
+                arguments: summarizeArguments(args),
+              }) - 1;
+            if (retainHandlers) {
+              retained.push({
+                kind: "registration",
+                name: property,
+                arguments: args,
+                captureIndex,
+              });
+            }
+            return registrationReturnValue(property, args);
+          };
+        }
+        return undefined;
+      },
+    },
+  );
+
+  return api;
+}
+
+function isRegistrarProperty(property) {
+  return property.startsWith("register") || property.startsWith("define");
+}
+
+function registrationReturnValue(name, args) {
+  if (name === "registerService") {
+    return {
+      name: objectName(args[0]),
+      start: async () => undefined,
+      stop: async () => undefined,
+    };
+  }
+  return objectName(args[0]) ?? undefined;
+}
+
+function summarizeArguments(args) {
+  return args.map((arg) => summarizeValue(arg));
+}
+
+function summarizeValue(value) {
+  if (typeof value === "function") {
+    return { type: "function" };
+  }
+  if (Array.isArray(value)) {
+    return { type: "array", length: value.length };
+  }
+  if (value && typeof value === "object") {
+    return {
+      type: "object",
+      keys: Object.keys(value).sort(),
+      name: objectName(value),
+    };
+  }
+  return { type: typeof value, value };
+}
+
+function objectName(value) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  if (typeof value.name === "string") {
+    return value.name;
+  }
+  return typeof value.id === "string" ? value.id : null;
+}

package/src/ci-policy.js

@@ -0,0 +1,259 @@
+import path from "node:path";
+import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { resolveFromRoot } from "./path-utils.js";
+
+export const defaultCiPolicyReportOptions = {
+  generatedAt: "deterministic",
+  jsonPath: "reports/plugin-inspector-ci-policy.json",
+  markdownPath: "reports/plugin-inspector-ci-policy.md",
+  reportTitle: "Plugin Inspector CI Policy",
+};
+
+export function buildCiPolicyReport(options = {}) {
+  const policy = options.policy;
+  validateCiPolicy(policy);
+
+  const checks = [
+    ...compatibilityChecks(options.compatibilityReport, { strict: options.strict }),
+    ...refDiffChecks(options.refDiff, { strict: options.strict }),
+    ...executionChecks(options.executionResults, policy, { strict: options.strict }),
+  ].sort((left, right) => actionRank(left.action) - actionRank(right.action) || left.id.localeCompare(right.id));
+
+  return {
+    generatedAt: options.generatedAt ?? defaultCiPolicyReportOptions.generatedAt,
+    status: checks.some((check) => check.action === "fail") ? "fail" : "pass",
+    strict: Boolean(options.strict),
+    policy: {
+      allowedBlocked: policy.allowedBlocked.length,
+      expectedWarnings: policy.expectedWarnings.length,
+      fixtureSets: Object.keys(policy.fixtureSets).sort(),
+      thresholds: policy.thresholds,
+    },
+    summary: {
+      checkCount: checks.length,
+      failCount: checks.filter((check) => check.action === "fail").length,
+      warnCount: checks.filter((check) => check.action === "warn").length,
+      passCount: checks.filter((check) => check.action === "pass").length,
+    },
+    checks,
+  };
+}
+
+export function validateCiPolicy(policy) {
+  const errors = [];
+  if (policy?.version !== 1) {
+    errors.push("ci policy version must be 1");
+  }
+  for (const key of ["allowedBlocked", "expectedWarnings"]) {
+    if (!Array.isArray(policy?.[key])) {
+      errors.push(`ci policy ${key} must be an array`);
+    }
+  }
+  if (!policy?.thresholds || typeof policy.thresholds !== "object") {
+    errors.push("ci policy thresholds are required");
+  }
+  if (!policy?.fixtureSets || typeof policy.fixtureSets !== "object") {
+    errors.push("ci policy fixtureSets are required");
+  }
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+}
+
+export function validateCiPolicyReport(report) {
+  return report.checks
+    .filter((check) => check.action === "fail")
+    .map((check) => `${check.id}: ${check.message}: ${check.evidence.join(", ")}`);
+}
+
+export async function writeCiPolicyReport(report, options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const jsonPath = resolveFromRoot(rootDir, options.jsonPath ?? defaultCiPolicyReportOptions.jsonPath);
+  const markdownPath = resolveFromRoot(rootDir, options.markdownPath ?? defaultCiPolicyReportOptions.markdownPath);
+  return writeJsonMarkdownArtifacts({
+    jsonPath,
+    markdownPath,
+    json: report,
+    markdown: renderCiPolicyMarkdown(report, options),
+    check: options.check,
+  });
+}
+
+export function renderCiPolicyMarkdown(report, options = {}) {
+  const title = options.title ?? options.reportTitle ?? defaultCiPolicyReportOptions.reportTitle;
+  return [
+    `# ${title}`,
+    "",
+    `Generated: ${report.generatedAt}`,
+    `Status: ${report.status.toUpperCase()}`,
+    `Strict: ${report.strict}`,
+    "",
+    "## Summary",
+    "",
+    markdownTable(
+      [
+        ["Checks", report.summary.checkCount],
+        ["Fail", report.summary.failCount],
+        ["Warn", report.summary.warnCount],
+        ["Pass", report.summary.passCount],
+        ["Allowed blocked rules", report.policy.allowedBlocked],
+        ["Expected warning rules", report.policy.expectedWarnings],
+        ["Fixture sets", report.policy.fixtureSets.join(", ")],
+      ],
+      ["Metric", "Value"],
+    ),
+    "",
+    "## Checks",
+    "",
+    markdownTable(
+      report.checks.map((check) => [
+        check.action,
+        check.id,
+        check.message,
+        check.evidence.join(", ") || "-",
+      ]),
+      ["Action", "ID", "Message", "Evidence"],
+    ),
+  ].join("\n");
+}
+
+function compatibilityChecks(report, options) {
+  const checks = [];
+  if (!report) {
+    checks.push({
+      id: "compatibility-report.missing",
+      action: "fail",
+      message: "compatibility report is missing",
+      evidence: [],
+    });
+    return checks;
+  }
+  checks.push({
+    id: "compatibility-report.breakages",
+    action: report.summary.breakageCount > 0 ? "fail" : "pass",
+    message: `${report.summary.breakageCount} hard breakages`,
+    evidence: (report.breakages ?? []).map((finding) => `${finding.fixture}:${finding.code}`),
+  });
+  checks.push({
+    id: "compatibility-report.p1-issues",
+    action: "pass",
+    message: `${report.summary.p1IssueCount} P1 issues tracked`,
+    evidence: (report.issues ?? [])
+      .filter((issue) => issue.severity === "P1")
+      .map((issue) => `${issue.fixture}:${issue.code}`),
+  });
+  const issues = report.issues ?? [];
+  const liveP0Issues = issues.filter((issue) => issue.issueClass === "live-issue" && issue.severity === "P0");
+  const deprecationWarnings = issues.filter((issue) => issue.issueClass === "deprecation-warning");
+  const inspectorGaps = issues.filter((issue) => issue.issueClass === "inspector-gap");
+  checks.push({
+    id: "compatibility-report.live-p0-issues",
+    action: liveP0Issues.length > 0 ? (options.strict ? "fail" : "warn") : "pass",
+    message: `${liveP0Issues.length} live P0 issues tracked`,
+    evidence: liveP0Issues.map((issue) => `${issue.fixture}:${issue.code}:${issue.compatStatus ?? "none"}`),
+  });
+  checks.push({
+    id: "compatibility-report.deprecation-warnings",
+    action: "pass",
+    message: `${deprecationWarnings.length} deprecated compat seams tracked`,
+    evidence: deprecationWarnings.map((issue) => `${issue.fixture}:${issue.code}`),
+  });
+  checks.push({
+    id: "compatibility-report.inspector-gaps",
+    action: "pass",
+    message: `${inspectorGaps.length} inspector proof gaps tracked`,
+    evidence: inspectorGaps.map((issue) => `${issue.fixture}:${issue.code}`),
+  });
+  return checks;
+}
+
+function refDiffChecks(refDiff, options) {
+  if (!refDiff) {
+    return [
+      {
+        id: "ref-diff.not-run",
+        action: "pass",
+        message: "ref diff artifact was not present for this CI mode",
+        evidence: [],
+      },
+    ];
+  }
+
+  return (refDiff.regressions ?? []).map((regression) => ({
+    id: `ref-diff.${regression.code}`,
+    action: regression.action === "fail" || (options.strict && regression.action === "warn") ? "fail" : "warn",
+    message: regression.message,
+    evidence: regression.evidence ?? [],
+  }));
+}
+
+function executionChecks(executionResults, policy, options) {
+  if (!executionResults) {
+    return [
+      {
+        id: "execution-results.not-run",
+        action: "pass",
+        message: "isolated execution artifact was not present for this CI mode",
+        evidence: [],
+      },
+    ];
+  }
+
+  const checks = [
+    {
+      id: "execution-results.failures",
+      action: executionResults.summary.failCount > 0 ? "fail" : "pass",
+      message: `${executionResults.summary.failCount} failed synthetic probes`,
+      evidence: failedExecutionEvidence(executionResults),
+    },
+    {
+      id: "execution-results.audit-findings",
+      action: executionResults.summary.auditFindingCount > 0 ? "warn" : "pass",
+      message: `${executionResults.summary.auditFindingCount ?? 0} package audit findings`,
+      evidence: executionResults.artifacts
+        .filter((artifact) => artifact.kind === "audit" && artifact.findingCount > 0)
+        .map((artifact) => `${artifact.fixture}:${artifact.findingCount}`),
+    },
+  ];
+
+  const blocked = executionResults.artifacts.flatMap((artifact) =>
+    (artifact.blocked ?? []).map((item) => ({ artifact, item })),
+  );
+  for (const blockedItem of blocked) {
+    const expectedWarning = findPolicyMatch(policy.expectedWarnings, blockedItem.item);
+    const allowedBlocked = findPolicyMatch(policy.allowedBlocked, blockedItem.item);
+    const match = expectedWarning ?? allowedBlocked;
+    checks.push({
+      id: `execution-results.blocked.${blockedItem.artifact.fixture}.${blockedItem.item.seam}.${blockedItem.item.captureIndex}`,
+      action: match ? (options.strict ? "fail" : "warn") : "fail",
+      message: match
+        ? `${match.decision}: ${blockedItem.item.reason}`
+        : `unknown blocked synthetic probe: ${blockedItem.item.reason}`,
+      evidence: [
+        blockedItem.artifact.artifactPath,
+        blockedItem.item.seam,
+        blockedItem.item.reason,
+        match?.id ?? "unclassified",
+      ],
+    });
+  }
+  return checks;
+}
+
+function findPolicyMatch(rules, item) {
+  return rules.find((rule) => item.seam === rule.seam && item.reason?.includes(rule.reasonIncludes));
+}
+
+function failedExecutionEvidence(executionResults) {
+  return executionResults.artifacts.flatMap((artifact) =>
+    (artifact.failures ?? []).map((failure) => `${artifact.fixture}:${failure.seam}:${failure.error}`),
+  );
+}
+
+function actionRank(value) {
+  return { fail: 0, warn: 1, pass: 2 }[value] ?? 3;
+}
+
+function markdownTable(rows, headers) {
+  return renderPaddedMarkdownTable(rows, headers);
+}

package/src/ci-summary.js

@@ -0,0 +1,223 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { readOptionalJsonFile } from "./json-file.js";
+
+export const defaultCiReportPaths = {
+  compatibility: "reports/plugin-inspector-report.json",
+  capture: "reports/plugin-inspector-capture.json",
+  synthetic: "reports/plugin-inspector-synthetic-probes.json",
+  coldImport: "reports/plugin-inspector-cold-import.json",
+  workspace: "reports/plugin-inspector-workspace-plan.json",
+  platform: "reports/plugin-inspector-platform-probes.json",
+  importLoop: "reports/plugin-inspector-import-loop-profile.json",
+  execution: "reports/plugin-inspector-execution-results.json",
+  runtimeProfile: "reports/plugin-inspector-runtime-profile.json",
+  refDiff: "reports/plugin-inspector-ref-diff.json",
+  profileDiff: "reports/plugin-inspector-profile-diff.json",
+  ciPolicy: "reports/plugin-inspector-ci-policy.json",
+};
+
+export async function buildCiSummary(options = {}) {
+  const reportPaths = options.reportPaths ?? defaultCiReportPaths;
+  const reports = options.reports ?? (await readCiReports(options.reportsDir ?? "reports", reportPaths));
+  const artifactBaseDir = options.artifactBaseDir ?? process.cwd();
+
+  return {
+    generatedAt: options.generatedAt ?? "deterministic",
+    title: options.title ?? "Plugin Inspector CI Summary",
+    mode: options.mode ?? "local",
+    openclawLabel: options.openclawLabel ?? "",
+    status: deriveCiStatus(reports),
+    summary: {
+      breakages: reports.compatibility?.summary?.breakageCount ?? 0,
+      warnings: reports.compatibility?.summary?.warningCount ?? 0,
+      suggestions: reports.compatibility?.summary?.suggestionCount ?? 0,
+      issues: reports.compatibility?.summary?.issueCount ?? 0,
+      p0Issues: reports.compatibility?.summary?.p0IssueCount ?? 0,
+      p1Issues: reports.compatibility?.summary?.p1IssueCount ?? 0,
+      liveIssues: reports.compatibility?.summary?.liveIssueCount ?? 0,
+      liveP0Issues: reports.compatibility?.summary?.liveP0IssueCount ?? 0,
+      compatGaps: reports.compatibility?.summary?.compatGapCount ?? 0,
+      deprecationWarnings: reports.compatibility?.summary?.deprecationWarningCount ?? 0,
+      inspectorGaps: reports.compatibility?.summary?.inspectorGapCount ?? 0,
+      upstreamIssues: reports.compatibility?.summary?.upstreamIssueCount ?? 0,
+      refDiffFailures: reports.refDiff?.summary?.hardRegressionCount ?? 0,
+      refDiffWarnings: reports.refDiff?.summary?.warningRegressionCount ?? 0,
+      policyFailures: reports.ciPolicy?.summary?.failCount ?? 0,
+      policyWarnings: reports.ciPolicy?.summary?.warnCount ?? 0,
+      profileFailures: reports.profileDiff?.summary?.failCount ?? 0,
+      profileWarnings: reports.profileDiff?.summary?.warnCount ?? 0,
+      executionPass: reports.execution?.summary?.passCount ?? 0,
+      executionFail: reports.execution?.summary?.failCount ?? 0,
+      executionBlocked: reports.execution?.summary?.blockedCount ?? 0,
+      platformWindowsRisks: reports.platform?.summary?.windowsRiskStepCount ?? 0,
+      platformContainerRisks: reports.platform?.summary?.containerRiskStepCount ?? 0,
+      loaderJitiCandidates: reports.platform?.summary?.jitiAlternativeCount ?? 0,
+      importLoopP50Ms: reports.importLoop?.summary?.p50WallMs ?? 0,
+      importLoopP95Ms: reports.importLoop?.summary?.p95WallMs ?? 0,
+      importLoopMaxRssMb: reports.importLoop?.summary?.maxPeakRssMb ?? 0,
+      importLoopMaxCpuMs: reports.importLoop?.summary?.maxCpuMsEstimate ?? 0,
+    },
+    topIssues: topIssues(reports.compatibility),
+    refRegressions: (reports.refDiff?.regressions ?? []).slice(0, 20),
+    policyFindings: (reports.ciPolicy?.checks ?? []).filter((check) => check.action !== "pass").slice(0, 20),
+    profileFindings: (reports.profileDiff?.checks ?? []).filter((check) => check.action !== "pass").slice(0, 20),
+    artifacts: Object.fromEntries(
+      Object.entries(reportPaths).map(([key, value]) => [key, existsSync(path.join(artifactBaseDir, value)) ? value : null]),
+    ),
+  };
+}
+
+export async function readCiReports(reportsDir, reportPaths = defaultCiReportPaths) {
+  const reports = {};
+  for (const [key, defaultPath] of Object.entries(reportPaths)) {
+    const reportPath = path.join(reportsDir, path.basename(defaultPath));
+    reports[key] = await readOptionalJsonFile(reportPath);
+  }
+  return reports;
+}
+
+export function deriveCiStatus(reports) {
+  if ((reports.compatibility?.summary?.breakageCount ?? 0) > 0) {
+    return "fail";
+  }
+  if ((reports.refDiff?.summary?.hardRegressionCount ?? 0) > 0) {
+    return "fail";
+  }
+  if ((reports.ciPolicy?.summary?.failCount ?? 0) > 0) {
+    return "fail";
+  }
+  if ((reports.profileDiff?.summary?.failCount ?? 0) > 0) {
+    return "fail";
+  }
+  if ((reports.execution?.summary?.failCount ?? 0) > 0) {
+    return "fail";
+  }
+  return "pass";
+}
+
+export async function writeCiSummary(summary, options = {}) {
+  const jsonPath = options.jsonPath ?? path.join(process.cwd(), "reports/plugin-inspector-ci-summary.json");
+  const markdownPath = options.markdownPath ?? path.join(process.cwd(), "reports/plugin-inspector-ci-summary.md");
+  return writeJsonMarkdownArtifacts({
+    jsonPath,
+    markdownPath,
+    json: summary,
+    markdown: renderCiSummaryMarkdown(summary),
+    check: options.check,
+  });
+}
+
+export function renderCiSummaryMarkdown(summary) {
+  return [
+    `# ${summary.title ?? "Plugin Inspector CI Summary"}`,
+    "",
+    `Generated: ${summary.generatedAt}`,
+    `Mode: ${summary.mode}`,
+    `OpenClaw: ${summary.openclawLabel || "-"}`,
+    `Status: ${summary.status.toUpperCase()}`,
+    "",
+    "## Counts",
+    "",
+    markdownTable(
+      [
+        ["Breakages", summary.summary.breakages],
+        ["Warnings", summary.summary.warnings],
+        ["Suggestions", summary.summary.suggestions],
+        ["Issues", summary.summary.issues],
+        ["P0 issues", summary.summary.p0Issues],
+        ["P1 issues", summary.summary.p1Issues],
+        ["Live issues", summary.summary.liveIssues],
+        ["Live P0 issues", summary.summary.liveP0Issues],
+        ["Compat gaps", summary.summary.compatGaps],
+        ["Deprecation warnings", summary.summary.deprecationWarnings],
+        ["Inspector gaps", summary.summary.inspectorGaps],
+        ["Upstream metadata", summary.summary.upstreamIssues],
+        ["Ref diff failures", summary.summary.refDiffFailures],
+        ["Ref diff warnings", summary.summary.refDiffWarnings],
+        ["Policy failures", summary.summary.policyFailures],
+        ["Policy warnings", summary.summary.policyWarnings],
+        ["Profile failures", summary.summary.profileFailures],
+        ["Profile warnings", summary.summary.profileWarnings],
+        ["Execution pass", summary.summary.executionPass],
+        ["Execution fail", summary.summary.executionFail],
+        ["Execution blocked", summary.summary.executionBlocked],
+        ["Windows portability risks", summary.summary.platformWindowsRisks],
+        ["Container portability risks", summary.summary.platformContainerRisks],
+        ["Jiti loader candidates", summary.summary.loaderJitiCandidates],
+        [
+          "Import loop",
+          `p50 ${summary.summary.importLoopP50Ms} ms / p95 ${summary.summary.importLoopP95Ms} ms / max RSS ${summary.summary.importLoopMaxRssMb} MB / CPU ${summary.summary.importLoopMaxCpuMs} ms`,
+        ],
+      ],
+      ["Metric", "Value"],
+    ),
+    "",
+    "## Top Issues",
+    "",
+    markdownTable(
+      summary.topIssues.map((issue) => [issue.severity, issue.issueClass ?? "-", issue.fixture, issue.code, issue.decision, issue.title]),
+      ["Severity", "Class", "Fixture", "Code", "Decision", "Title"],
+    ),
+    "",
+    "## Ref Regressions",
+    "",
+    markdownTable(
+      summary.refRegressions.map((regression) => [
+        regression.action,
+        regression.severity,
+        regression.dimension,
+        regression.code,
+        regression.message,
+      ]),
+      ["Action", "Severity", "Surface", "Code", "Message"],
+    ),
+    "",
+    "## Policy Findings",
+    "",
+    markdownTable(
+      summary.policyFindings.map((finding) => [finding.action, finding.id, finding.message, finding.evidence.join(", ")]),
+      ["Action", "ID", "Message", "Evidence"],
+    ),
+    "",
+    "## Profile Findings",
+    "",
+    markdownTable(
+      summary.profileFindings.map((finding) => [
+        finding.action,
+        finding.id,
+        finding.metric,
+        finding.baseline ?? "-",
+        finding.current ?? "-",
+        finding.message,
+      ]),
+      ["Action", "ID", "Metric", "Baseline", "Current", "Message"],
+    ),
+    "",
+    "## Artifacts",
+    "",
+    markdownTable(
+      Object.entries(summary.artifacts).map(([key, value]) => [key, value ?? "-"]),
+      ["Artifact", "Path"],
+    ),
+  ].join("\n");
+}
+
+function topIssues(report) {
+  return (report?.issues ?? [])
+    .filter((issue) => ["P0", "P1"].includes(issue.severity))
+    .slice(0, 20)
+    .map((issue) => ({
+      severity: issue.severity,
+      issueClass: issue.issueClass,
+      fixture: issue.fixture,
+      code: issue.code,
+      title: issue.title,
+      decision: issue.decision,
+    }));
+}
+
+function markdownTable(rows, headers) {
+  return renderPaddedMarkdownTable(rows, headers, { nullValue: "-" });
+}