@openclaw/plugin-inspector 0.3.19 → 0.3.21

package/src/index.js

@@ -8,7 +8,8 @@ import * as executionResultsApi from "./execution-results.js";
 import * as importLoopProfileApi from "./import-loop-profile.js";
 import * as inspectorApi from "./inspector.js";
 import * as issuesApi from "./issues.js";
-import * as openClawTargetApi from "./openclaw-target.js";
+import * as openClawTargetApi from "./openclaw-version.js";
+import * as openClawTargetSurfaceApi from "./openclaw-target.js";
 import * as profileDiffApi from "./profile-diff.js";
 import * as refDiffApi from "./ref-diff.js";
 import * as reportApi from "./report.js";
@@ -67,8 +68,16 @@ export const reports = Object.freeze({
   issueId: issuesApi.issueId,
   classifyIssueFinding: issuesApi.classifyIssueFinding,
   knownIssueCodes: issuesApi.knownIssueCodes,
-  openClawTargetPathCandidates: openClawTargetApi.openClawTargetPathCandidates,
-  readOpenClawTargetSurface: openClawTargetApi.readOpenClawTargetSurface,
+  openClawTargetPathCandidates: openClawTargetSurfaceApi.openClawTargetPathCandidates,
+  readOpenClawTargetSurface: openClawTargetSurfaceApi.readOpenClawTargetSurface,
+});
+
+export const openClawTargets = Object.freeze({
+  resolveVersion: openClawTargetApi.resolveOpenClawTargetVersion,
+  prepare: openClawTargetApi.prepareOpenClawTarget,
+  eligibilityVersion: openClawTargetApi.openClawEligibilityVersion,
+  satisfiesCompatibilityRange: openClawTargetApi.satisfiesOpenClawCompatibilityRange,
+  satisfiesRange: openClawTargetApi.satisfiesOpenClawVersionRange,
 });
 
 export const contracts = Object.freeze({

package/src/inspector.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { execFile } from "node:child_process";
 import { readdir, readFile } from "node:fs/promises";
+import * as nodeModule from "node:module";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { promisify } from "node:util";
@@ -9,6 +10,7 @@ import { captureApiOptionsForPlugin } from "./capture-config.js";
 import { fixtureCheckoutPath, fixtureSourceRoot } from "./config.js";
 import { buildCompatibilityFixtureReport } from "./fixture-summary.js";
 import { readOpenClawTargetSurface } from "./openclaw-target.js";
+import { prepareOpenClawTarget, resolveOpenClawTargetVersion } from "./openclaw-version.js";
 import { buildCompatibilityReport, buildReport } from "./report.js";
 import { inspectSdkDeprecations } from "./sdk-deprecation-rules.js";
 
@@ -26,11 +28,13 @@ export async function inspectCompatibilityFixtureSet(config, options = {}) {
   const { inspections, failures } = await inspectConfiguredFixtures(config, options);
   const targetOpenClaw =
     options.targetOpenClaw ??
-    (await readOpenClawTargetSurface({
-      configuredPath: options.openclawPath,
-      manifest: config,
-      rootDir: config.rootDir,
-    }));
+    (options.openclawVersion
+      ? await prepareOpenClawTarget(await resolveOpenClawTargetVersion(options.openclawVersion, options), options)
+      : await readOpenClawTargetSurface({
+          configuredPath: options.openclawPath,
+          manifest: config,
+          rootDir: config.rootDir,
+        }));
 
   return buildCompatibilityReport({
     config,
@@ -165,12 +169,7 @@ export function inspectSourceText(text, filePath = "source.js") {
     ...collectDetailedMatches(searchableText, /\b(createChatChannelPlugin)\s*\(/g, filePath, "name"),
     ...collectDetailedMatches(searchableText, /\b(definePluginEntry)\s*\(/g, filePath, "name"),
   ];
-  const sdkImports = collectDetailedMatches(
-    searchableText,
-    /(?:from\s*["'`]|import\(\s*["'`])([^"'`]*openclaw\/plugin-sdk[^"'`]*)/g,
-    filePath,
-    "specifier",
-  );
+  const sdkImports = collectSdkImports(searchableText, filePath);
   const sdkDeprecations = inspectSdkDeprecations(searchableText, filePath);
 
   return {
@@ -385,6 +384,165 @@ function collectDetailedMatches(text, regex, filePath, key) {
   return details;
 }
 
+function collectSdkImports(text, filePath) {
+  const details = [];
+  for (const candidate of text.matchAll(/(?:^|;)[\t ]*(import|export)\b/gm)) {
+    const keyword = candidate[1];
+    const keywordIndex = (candidate.index ?? 0) + candidate[0].lastIndexOf(keyword);
+    const declaration = parseStaticModuleDeclaration(text, keywordIndex, keyword);
+    if (!declaration?.specifier.includes("openclaw/plugin-sdk")) continue;
+    if (isTypeOnlyStaticImportClause(declaration.clause)) continue;
+    const line = lineForOffset(text, keywordIndex);
+    details.push({
+      specifier: declaration.specifier,
+      file: filePath,
+      line,
+      ref: `${filePath}:${line}`,
+    });
+  }
+
+  const dynamicMatches = [...text.matchAll(/\bimport\(\s*["'`]([^"'`]*openclaw\/plugin-sdk[^"'`]*)/g)];
+  const runtimeDynamicImports = runtimeDynamicImportIndexes(text, dynamicMatches);
+  for (const [index, match] of dynamicMatches.entries()) {
+    if (!runtimeDynamicImports.has(index)) continue;
+    const line = lineForOffset(text, match.index ?? 0);
+    details.push({
+      specifier: match[1],
+      file: filePath,
+      line,
+      ref: `${filePath}:${line}`,
+    });
+  }
+  return details.sort((left, right) => left.line - right.line || left.specifier.localeCompare(right.specifier));
+}
+
+function parseStaticModuleDeclaration(text, keywordIndex, keyword) {
+  const clauseStart = keywordIndex + keyword.length;
+  let cursor = skipWhitespace(text, clauseStart);
+  if (text[cursor] === "(") return null;
+  if (keyword === "export" && text[cursor] !== "{" && text[cursor] !== "*" && !hasWordAt(text, cursor, "type")) {
+    return null;
+  }
+
+  let braceDepth = 0;
+  while (cursor < text.length) {
+    const char = text[cursor];
+    if (char === '"' || char === "'" || char === "`") {
+      cursor = skipQuotedText(text, cursor, char);
+      continue;
+    }
+    if (char === "{") braceDepth += 1;
+    if (char === "}") braceDepth = Math.max(0, braceDepth - 1);
+    if (char === ";" && braceDepth === 0) return null;
+    if (braceDepth === 0 && hasWordAt(text, cursor, "from")) {
+      const clause = text.slice(clauseStart, cursor).trim();
+      cursor = skipWhitespace(text, cursor + "from".length);
+      const quote = text[cursor];
+      if (quote !== '"' && quote !== "'" && quote !== "`") return null;
+      const specifierStart = cursor + 1;
+      const specifierEnd = skipQuotedText(text, cursor, quote) - 1;
+      return { clause, specifier: text.slice(specifierStart, specifierEnd) };
+    }
+    cursor += 1;
+  }
+  return null;
+}
+
+function skipWhitespace(text, index) {
+  while (index < text.length && /\s/.test(text[index])) index += 1;
+  return index;
+}
+
+function hasWordAt(text, index, word) {
+  return (
+    text.startsWith(word, index) &&
+    !/[A-Za-z0-9_$]/.test(text[index - 1] ?? "") &&
+    !/[A-Za-z0-9_$]/.test(text[index + word.length] ?? "")
+  );
+}
+
+function skipQuotedText(text, quoteIndex, quote) {
+  let cursor = quoteIndex + 1;
+  while (cursor < text.length) {
+    if (text[cursor] === "\\") {
+      cursor += 2;
+      continue;
+    }
+    cursor += 1;
+    if (text[cursor - 1] === quote) break;
+  }
+  return cursor;
+}
+
+function runtimeDynamicImportIndexes(text, matches) {
+  if (matches.length === 0) return new Set();
+  const markedImports = matches.map((match, index) => {
+    const specifier = match[1];
+    const specifierStart = (match.index ?? 0) + match[0].indexOf(specifier);
+    return {
+      index,
+      specifierStart,
+      specifierEnd: specifierStart + specifier.length,
+      marker: `${specifier}/__plugin_inspector_runtime_import_${index}__`,
+    };
+  });
+  let markedText = text;
+  for (const markedImport of markedImports.toReversed()) {
+    markedText =
+      markedText.slice(0, markedImport.specifierStart) +
+      markedImport.marker +
+      markedText.slice(markedImport.specifierEnd);
+  }
+
+  try {
+    const runtimeText = eraseTypeScript(markedText);
+    if (runtimeText === null) {
+      return new Set(markedImports.map((markedImport) => markedImport.index));
+    }
+    return new Set(
+      markedImports.filter((markedImport) => runtimeText.includes(markedImport.marker)).map((markedImport) => markedImport.index),
+    );
+  } catch {
+    return new Set(markedImports.map((markedImport) => markedImport.index));
+  }
+}
+
+function eraseTypeScript(text) {
+  if (typeof nodeModule.stripTypeScriptTypes === "function") {
+    return nodeModule.stripTypeScriptTypes(text, { mode: "transform" });
+  }
+  if (typeof globalThis.Bun?.Transpiler === "function") {
+    const transpiler = new globalThis.Bun.Transpiler({ loader: "ts", target: "bun" });
+    return transpiler.transformSync(text);
+  }
+  return null;
+}
+
+function isTypeOnlyStaticImportClause(clause) {
+  clause = clause.trim();
+  if (/^type\b/.test(clause)) {
+    const typeOnlyClause = clause.slice("type".length).trimStart();
+    return typeOnlyClause.length > 0 && !typeOnlyClause.startsWith(",");
+  }
+  if (!clause.startsWith("{") || !clause.endsWith("}")) {
+    return false;
+  }
+
+  const namedImports = clause
+    .slice(1, -1)
+    .split(",")
+    .map((specifier) => specifier.trim())
+    .filter(Boolean);
+  return namedImports.length > 0 && namedImports.every(isTypeOnlyNamedImport);
+}
+
+function isTypeOnlyNamedImport(specifier) {
+  const typeModifier = /^type\b/.exec(specifier);
+  if (!typeModifier) return false;
+  const importedName = specifier.slice(typeModifier[0].length).trimStart();
+  return importedName.length > 0 && !/^as\b/.test(importedName);
+}
+
 async function readManifestContracts(config, checkoutPath, sourceRoot) {
   const manifests = new Set(
     [path.join(sourceRoot, "openclaw.plugin.json"), path.join(checkoutPath, "openclaw.plugin.json")].filter(
@@ -436,6 +594,7 @@ async function readPackageMetadata(config, checkoutPath, sourceRoot) {
       collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.openclaw?.entry);
       collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.openclaw?.entrypoint);
       collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.openclaw?.setupEntry);
+      collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.openclaw?.runtimeSetupEntry);
       collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.exports?.["."]?.import);
       collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.exports?.["."]?.default);
       collectEntrypoints(entrypoints, entrypointFiles, packageDir, packageJson.openclaw?.extensions);

package/src/issues.js

@@ -518,7 +518,10 @@ export function buildIssues({ breakages = [], warnings = [], suggestions = [], t
       runtimeCoverage: finding.runtimeCoverage ?? null,
       ...(finding.authorRemediation
         ? {
-            authorRemediation: withAuthorRemediationDocs(finding.code, finding.authorRemediation),
+            authorRemediation:
+              finding.authorRemediationDocs === false
+                ? finding.authorRemediation
+                : withAuthorRemediationDocs(finding.code, finding.authorRemediation),
           }
         : {}),
     }));

package/src/openclaw-target.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 
 export const defaultOpenClawCheckoutPaths = ["./openclaw", "../openclaw"];
@@ -26,6 +26,10 @@ export async function readOpenClawTargetSurface(options = {}) {
     });
   }
 
+  if (match.kind === "package") {
+    return readPackedOpenClawTargetSurface({ rootDir, requestedPaths, ...match });
+  }
+
   const { requestedPath, resolvedPath, registryPath } = match;
   const hookTypesPath = path.join(resolvedPath, "src/plugins/hook-types.ts");
   const apiBuilderPath = path.join(resolvedPath, "src/plugins/api-builder.ts");
@@ -251,12 +255,191 @@ function findTargetCheckout(rootDir, requestedPaths) {
     const resolvedPath = path.resolve(rootDir, requestedPath);
     const registryPath = path.join(resolvedPath, "src/plugins/compat/registry.ts");
     if (existsSync(registryPath)) {
-      return { requestedPath, resolvedPath, registryPath };
+      return { kind: "checkout", requestedPath, resolvedPath, registryPath };
+    }
+    if (existsSync(path.join(resolvedPath, "package.json")) && existsSync(path.join(resolvedPath, "dist"))) {
+      return { kind: "package", requestedPath, resolvedPath };
+    }
+  }
+  return null;
+}
+
+async function readPackedOpenClawTargetSurface({ rootDir, requestedPaths, requestedPath, resolvedPath }) {
+  const packagePath = path.join(resolvedPath, "package.json");
+  const packageJson = JSON.parse(await readFile(packagePath, "utf8"));
+  if (packageJson.name !== "openclaw") {
+    return emptyTargetSurface({ configuredPath: requestedPath, searchedPaths: requestedPaths, status: "missing" });
+  }
+
+  const distPath = path.join(resolvedPath, "dist");
+  const declarationFiles = await listDeclarationFiles(distPath);
+  const declarations = [];
+  for (const filePath of declarationFiles) {
+    declarations.push({ filePath, source: await readFile(filePath, "utf8") });
+  }
+  const apiDeclaration = declarations
+    .map((declaration) => ({
+      ...declaration,
+      values: parseObjectTypeFields(declaration.source, "OpenClawPluginApi", (value) => value.startsWith("register")),
+    }))
+    .sort((left, right) => right.values.length - left.values.length)[0];
+  const hookDeclaration = declarations.find((declaration) => declaration.source.includes("type PluginHookName ="));
+  const manifestDeclaration = declarations.find((declaration) => declaration.source.includes("type PluginManifest ="));
+  const manifestContractDeclaration = declarations.find((declaration) => declaration.source.includes("type PluginManifestContracts ="));
+  const apiRegistrars = apiDeclaration?.values ?? [];
+  const hookNames = hookDeclaration ? parseStringUnion(hookDeclaration.source, "PluginHookName") : [];
+  const manifestFields = manifestDeclaration
+    ? parseObjectTypeFields(manifestDeclaration.source, "PluginManifest")
+    : [];
+  const manifestContractFields = manifestContractDeclaration
+    ? parseObjectTypeFields(manifestContractDeclaration.source, "PluginManifestContracts")
+    : [];
+  const sdkExports = parsePluginSdkExports(packageJson);
+
+  return {
+    configuredPath: requestedPath,
+    searchedPaths: requestedPaths,
+    status: "ok",
+    version: packageJson.version ?? null,
+    compatRegistryPath: null,
+    compatRecordCount: 0,
+    compatRecords: [],
+    compatRecordStatuses: {},
+    hookTypesPath: hookDeclaration ? relativePath(rootDir, hookDeclaration.filePath) : null,
+    hookNameCount: hookNames.length,
+    hookNames,
+    apiBuilderPath: apiDeclaration ? relativePath(rootDir, apiDeclaration.filePath) : null,
+    apiRegistrarCount: apiRegistrars.length,
+    apiRegistrars,
+    capturedRegistrationPath: apiDeclaration ? relativePath(rootDir, apiDeclaration.filePath) : null,
+    capturedRegistrarCount: apiRegistrars.length,
+    capturedRegistrars: apiRegistrars,
+    packagePath: relativePath(rootDir, packagePath),
+    sdkExportCount: sdkExports.length,
+    sdkExports,
+    pluginSdkEntrypointsPath: null,
+    reservedSdkExportCount: 0,
+    reservedSdkExports: [],
+    supportedFacadeSdkExports: [],
+    publicPluginOwnedSdkExports: [],
+    manifestTypesPath: manifestDeclaration ? relativePath(rootDir, manifestDeclaration.filePath) : null,
+    manifestFieldCount: manifestFields.length,
+    manifestFields,
+    manifestContractFieldCount: manifestContractFields.length,
+    manifestContractFields,
+  };
+}
+
+async function listDeclarationFiles(rootDir) {
+  const files = [];
+  const entries = await readdir(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listDeclarationFiles(entryPath)));
+    } else if (entry.isFile() && entry.name.endsWith(".d.ts")) {
+      files.push(entryPath);
     }
   }
+  return files.sort();
+}
+
+function parseObjectTypeFields(source, typeName, filter = () => true) {
+  const body = readObjectTypeBody(source, typeName);
+  if (!body) return [];
+  return unique(parseTopLevelTypeProperties(body).filter(filter)).sort();
+}
+
+function parseTopLevelTypeProperties(body) {
+  const properties = [];
+  let braceDepth = 0;
+  let bracketDepth = 0;
+  let parenDepth = 0;
+  let propertyStart = true;
+
+  for (let index = 0; index < body.length; index += 1) {
+    const char = body[index];
+    const next = body[index + 1];
+    if (char === "/" && next === "*") {
+      index = body.indexOf("*/", index + 2);
+      if (index === -1) break;
+      index += 1;
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      const newline = body.indexOf("\n", index + 2);
+      if (newline === -1) break;
+      index = newline;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      index = skipQuotedTypeText(body, index);
+      continue;
+    }
+    if (char === "{") braceDepth += 1;
+    else if (char === "}") braceDepth -= 1;
+    else if (char === "[") bracketDepth += 1;
+    else if (char === "]") bracketDepth -= 1;
+    else if (char === "(") parenDepth += 1;
+    else if (char === ")") parenDepth -= 1;
+
+    if (braceDepth !== 0 || bracketDepth !== 0 || parenDepth !== 0) continue;
+    if (char === ";" || char === ",") {
+      propertyStart = true;
+      continue;
+    }
+    if (/\s/.test(char)) continue;
+    if (!propertyStart || !/[A-Za-z_$]/.test(char)) {
+      propertyStart = false;
+      continue;
+    }
+
+    const match = body.slice(index).match(/^([A-Za-z_$][A-Za-z0-9_$]*)/);
+    if (!match) {
+      propertyStart = false;
+      continue;
+    }
+    const name = match[1];
+    index += name.length - 1;
+    if (name === "readonly") continue;
+    let cursor = index + 1;
+    while (/\s/.test(body[cursor] ?? "")) cursor += 1;
+    if (body[cursor] === "?") cursor += 1;
+    while (/\s/.test(body[cursor] ?? "")) cursor += 1;
+    if (body[cursor] === ":") properties.push(name);
+    propertyStart = false;
+  }
+  return properties;
+}
+
+function skipQuotedTypeText(source, quoteIndex) {
+  const quote = source[quoteIndex];
+  for (let index = quoteIndex + 1; index < source.length; index += 1) {
+    if (source[index] === "\\") index += 1;
+    else if (source[index] === quote) return index;
+  }
+  return source.length - 1;
+}
+
+function readObjectTypeBody(source, typeName) {
+  const marker = new RegExp(`(?:export\\s+)?type\\s+${typeName}(?:\\$\\d+)?\\s*=\\s*\\{`, "g");
+  const match = marker.exec(source);
+  if (!match) return null;
+  const start = match.index + match[0].length;
+  let depth = 1;
+  for (let index = start; index < source.length; index += 1) {
+    if (source[index] === "{") depth += 1;
+    if (source[index] === "}") depth -= 1;
+    if (depth === 0) return source.slice(start, index);
+  }
   return null;
 }
 
+function parseStringUnion(source, typeName) {
+  const match = source.match(new RegExp(`type\\s+${typeName}\\s*=\\s*([^;]+);`));
+  return match ? unique([...match[1].matchAll(/["']([^"']+)["']/g)].map((item) => item[1])).sort() : [];
+}
+
 function emptyTargetSurface({ configuredPath, searchedPaths = undefined, status }) {
   return {
     configuredPath,