@openclaw/plugin-inspector 0.0.0 → 0.1.0

package/src/import-loop-profile.js

@@ -0,0 +1,169 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { resolveFromRoot } from "./path-utils.js";
+import { runProfiledProcess } from "./process-profile.js";
+import { assertRunCount, percentile } from "./stats.js";
+
+const defaultCliPath = fileURLToPath(new URL("./cli.js", import.meta.url));
+
+export const defaultImportLoopProfileOptions = {
+  entrypoint: "test/fixtures/lazy-import-plugin.mjs",
+  generatedAt: "deterministic",
+  jsonPath: "reports/plugin-import-loop-profile.json",
+  markdownPath: "reports/plugin-import-loop-profile.md",
+  outputDir: ".plugin-inspector/import-loop",
+  reportTitle: "Plugin Import Loop Profile",
+  runs: 3,
+};
+
+export async function buildImportLoopProfile(options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const runs = options.runs ?? defaultImportLoopProfileOptions.runs;
+  const entrypoint = options.entrypoint ?? defaultImportLoopProfileOptions.entrypoint;
+  assertRunCount(runs, 20);
+
+  const samples = [];
+  for (let index = 0; index < runs; index += 1) {
+    samples.push(await runCaptureSample({ ...options, entrypoint, index, rootDir }));
+  }
+
+  const wallMs = samples.map((sample) => sample.wallMs).sort((left, right) => left - right);
+  return {
+    generatedAt: options.generatedAt ?? defaultImportLoopProfileOptions.generatedAt,
+    mode: options.mode ?? "subprocess-cold-import-loop",
+    entrypoint,
+    summary: {
+      runs,
+      p50WallMs: percentile(wallMs, 0.5),
+      p95WallMs: percentile(wallMs, 0.95),
+      maxPeakRssMb: Math.max(0, ...samples.map((sample) => sample.peakRssMb)),
+      maxCpuMsEstimate: Math.max(0, ...samples.map((sample) => sample.cpuMsEstimate)),
+      capturedCount: samples.reduce((sum, sample) => sum + sample.capturedCount, 0),
+      failCount: samples.filter((sample) => sample.exitCode !== 0 || sample.status !== "captured").length,
+    },
+    samples,
+  };
+}
+
+export function validateImportLoopProfile(report) {
+  const errors = [];
+  if (report.summary.failCount > 0) {
+    errors.push(`import loop has ${report.summary.failCount} failed sample(s)`);
+  }
+  if (report.summary.capturedCount < report.summary.runs) {
+    errors.push("import loop did not capture at least one contract per run");
+  }
+  if (report.summary.p50WallMs <= 0) {
+    errors.push("import loop is missing wall-time samples");
+  }
+  return errors;
+}
+
+export async function writeImportLoopProfile(report, options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const jsonPath = resolveFromRoot(rootDir, options.jsonPath ?? defaultImportLoopProfileOptions.jsonPath);
+  const markdownPath = resolveFromRoot(rootDir, options.markdownPath ?? defaultImportLoopProfileOptions.markdownPath);
+  return writeJsonMarkdownArtifacts({
+    jsonPath,
+    markdownPath,
+    json: report,
+    markdown: renderImportLoopProfileMarkdown(report, options),
+    check: options.check,
+  });
+}
+
+export function renderImportLoopProfileMarkdown(report, options = {}) {
+  const title = options.title ?? options.reportTitle ?? defaultImportLoopProfileOptions.reportTitle;
+  return [
+    `# ${title}`,
+    "",
+    `Generated: ${report.generatedAt}`,
+    `Mode: ${report.mode}`,
+    `Entrypoint: ${report.entrypoint}`,
+    "",
+    "## Summary",
+    "",
+    markdownTable(Object.entries(report.summary).map(([key, value]) => [key, value]), ["Metric", "Value"]),
+    "",
+    "## Samples",
+    "",
+    markdownTable(
+      report.samples.map((sample) => [
+        sample.index,
+        sample.status,
+        sample.capturedCount,
+        `${sample.wallMs} ms`,
+        `${sample.peakRssMb} MB`,
+        `${sample.cpuMsEstimate} ms`,
+        sample.exitCode,
+      ]),
+      ["Run", "Status", "Captured", "Wall", "Peak RSS", "CPU Estimate", "Exit"],
+    ),
+  ].join("\n");
+}
+
+async function runCaptureSample(options) {
+  const outputDir = resolveFromRoot(
+    options.rootDir,
+    options.outputDir ?? defaultImportLoopProfileOptions.outputDir,
+  );
+  const outputPath = path.join(outputDir, `capture-${options.index}.json`);
+  await mkdir(path.dirname(outputPath), { recursive: true });
+
+  const command = buildCaptureCommand({ ...options, outputPath });
+  const profile = await runProfiledProcess({
+    command: command.command,
+    args: command.args,
+    cwd: command.cwd ?? options.rootDir,
+    env: { ...process.env, ...command.env },
+  });
+  const output = profile.exitCode === 0 ? await readCaptureOutput(outputPath) : null;
+
+  return {
+    index: options.index,
+    exitCode: profile.exitCode,
+    status: output?.status ?? "failed",
+    capturedCount: output?.captured?.length ?? 0,
+    wallMs: profile.wallMs,
+    peakRssMb: profile.peakRssMb,
+    peakCpuPercent: profile.peakCpuPercent,
+    cpuMsEstimate: profile.cpuMsEstimate,
+    stderrPreview: profile.stderrPreview,
+  };
+}
+
+function buildCaptureCommand(options) {
+  if (typeof options.captureCommand === "function") {
+    return options.captureCommand({
+      entrypoint: options.entrypoint,
+      index: options.index,
+      outputPath: options.outputPath,
+      rootDir: options.rootDir,
+    });
+  }
+  if (options.captureScript) {
+    return {
+      command: process.execPath,
+      args: [options.captureScript, options.entrypoint, "--output", options.outputPath],
+      cwd: options.rootDir,
+      env: { [options.optInEnv ?? "PLUGIN_INSPECTOR_EXECUTE_ISOLATED"]: "1", ...options.captureEnv },
+    };
+  }
+  return {
+    command: process.execPath,
+    args: [defaultCliPath, "capture", options.entrypoint, "--output", options.outputPath],
+    cwd: options.rootDir,
+    env: { PLUGIN_INSPECTOR_EXECUTE_ISOLATED: "1", ...options.captureEnv },
+  };
+}
+
+async function readCaptureOutput(outputPath) {
+  const { readFile } = await import("node:fs/promises");
+  return JSON.parse(await readFile(outputPath, "utf8"));
+}
+
+function markdownTable(rows, headers) {
+  return renderPaddedMarkdownTable(rows, headers);
+}

package/src/index.js

@@ -0,0 +1,186 @@
+export {
+  escapeMarkdownTableCell,
+  renderArtifactContent,
+  renderMarkdownTable,
+  renderPaddedMarkdownTable,
+  writeArtifacts,
+  writeJsonMarkdownArtifacts,
+} from "./artifacts.js";
+export {
+  normalizeRepoPath,
+  posixJoin,
+  resolveFromRoot,
+  resolveRequiredFromRoot,
+  slugForArtifact,
+  toRepoPath,
+} from "./path-utils.js";
+export { readJsonFile, readOptionalJsonFile } from "./json-file.js";
+export { assertRunCount, percentile } from "./stats.js";
+export { createCaptureApi } from "./capture-api.js";
+export {
+  buildCiPolicyReport,
+  defaultCiPolicyReportOptions,
+  renderCiPolicyMarkdown,
+  validateCiPolicy,
+  validateCiPolicyReport,
+  writeCiPolicyReport,
+} from "./ci-policy.js";
+export {
+  buildCiSummary,
+  defaultCiReportPaths,
+  deriveCiStatus,
+  readCiReports,
+  renderCiSummaryMarkdown,
+  writeCiSummary,
+} from "./ci-summary.js";
+export {
+  buildContractProbes,
+  contractProbeRules,
+  probePriority,
+} from "./contract-probes.js";
+export {
+  buildContractCapture,
+  defaultHookAssertions,
+  defaultHookContexts,
+  defaultHookEvents,
+  defaultRegistrationArguments,
+  defaultRegistrationAssertions,
+  renderContractCaptureMarkdown,
+  validateContractCapture,
+  writeContractCapture,
+} from "./contract-capture.js";
+export {
+  renderCompatibilityIssuesReport,
+  renderCompatibilityMarkdownReport,
+} from "./compatibility-report.js";
+export {
+  knownIssueClasses,
+  validateContractCoverage,
+} from "./contract-coverage.js";
+export {
+  buildColdImportReadiness,
+  renderColdImportReadinessMarkdown,
+  validateColdImportReadiness,
+  writeColdImportReadiness,
+} from "./cold-import-readiness.js";
+export {
+  buildIssues,
+  classifyIssueFinding,
+  deprecatedCompatRecords,
+  issueId,
+  issueMetadata,
+  issueMetadataByCode,
+  knownIssueCodes,
+  summarizeIssueClasses,
+} from "./issues.js";
+export {
+  buildExecutionResultsReport,
+  defaultExecutionResultsOptions,
+  renderExecutionResultsMarkdown,
+  writeExecutionResultsReport,
+} from "./execution-results.js";
+export {
+  buildCompatibilityFixtureReport,
+  classifyCompatibilityFixture,
+  classifyPackageContracts,
+  classifyTargetOpenClawCoverage,
+  readPackageSummaries,
+  readPluginManifests,
+  summarizePackage,
+} from "./fixture-summary.js";
+export {
+  buildImportLoopProfile,
+  defaultImportLoopProfileOptions,
+  renderImportLoopProfileMarkdown,
+  validateImportLoopProfile,
+  writeImportLoopProfile,
+} from "./import-loop-profile.js";
+export {
+  defaultOpenClawCheckoutPaths,
+  openClawTargetPathCandidates,
+  parseCompatRecordEntries,
+  parseExportedStringArray,
+  parsePluginSdkExports,
+  parseTypeFields,
+  readOpenClawTargetSurface,
+} from "./openclaw-target.js";
+export {
+  captureEntrypoint,
+  captureEntrypointWithMockSdk,
+  inspectCompatibilityFixtureSet,
+  inspectFixtureSet,
+  inspectPlugin,
+  inspectSourceText,
+} from "./inspector.js";
+export {
+  defaultPluginRootConfigFiles,
+  fixtureCheckoutPath,
+  fixtureSourceRoot,
+  loadInspectorConfig,
+  loadPluginRootConfig,
+  normalizeInspectorConfig,
+  normalizePluginRootConfig,
+  validateInspectorConfig,
+} from "./config.js";
+export {
+  buildPlatformProbes,
+  defaultPlatformTargets,
+  renderPlatformProbesMarkdown,
+  validatePlatformProbes,
+  writePlatformProbes,
+} from "./platform-probes.js";
+export {
+  buildProfileDiff,
+  defaultProfileDiffOptions,
+  renderProfileDiffMarkdown,
+  validateProfileDiff,
+  writeProfileDiff,
+} from "./profile-diff.js";
+export {
+  buildRefDiff,
+  defaultRefDiffDimensions,
+  defaultRefDiffOptions,
+  renderRefDiffMarkdown,
+  validateRefDiff,
+  writeRefDiff,
+} from "./ref-diff.js";
+export {
+  buildCompatibilityReport,
+  classifyCompatRecordCoverage,
+  renderMarkdownReport,
+  renderTextSummary,
+  writeCompatibilityReport,
+  writeReport,
+} from "./report.js";
+export {
+  buildRuntimeProfile,
+  defaultRuntimeProfileCommands,
+  defaultRuntimeProfileOptions,
+  renderRuntimeProfileMarkdown,
+  validateRuntimeProfile,
+  writeRuntimeProfile,
+} from "./runtime-profile.js";
+export {
+  buildRuntimeCaptureReport,
+  renderRuntimeCaptureMarkdown,
+  writeRuntimeCaptureReport,
+} from "./runtime-capture-report.js";
+export { createMockSdkPackage } from "./sdk-mock.js";
+export {
+  buildSyntheticProbePlan,
+  defaultSyntheticHookContexts,
+  defaultSyntheticHookEvents,
+  defaultSyntheticRegistrationArguments,
+  renderSyntheticProbeMarkdown,
+  runCapturedSyntheticProbes,
+  syntheticRegistrationExecutionProfiles,
+  validateSyntheticProbePlan,
+  writeSyntheticProbePlan,
+} from "./synthetic-probes.js";
+export {
+  buildWorkspacePlan,
+  defaultWorkspacePlanOptions,
+  renderWorkspacePlanMarkdown,
+  validateWorkspacePlan,
+  writeWorkspacePlan,
+} from "./workspace-plan.js";