@perpscope/percolator-adapter 0.8.0 → 0.9.0

package/README.md

@@ -65,11 +65,17 @@ The full field-level contract is documented in `../../docs/field-compatibility-m
 
 `buildCompatibilityRealityCheck(report, { input })` returns `perpscope.reality-check` with provenance, required/useful mapped counts, unknown fields, and alias counts. Use it when a terminal needs to show whether a capture is synthetic, real-backed candidate, or externally submitted.
 
+`buildCompatibilityDoctor(report, { input })` returns `perpscope.compatibility-doctor` with pass/check status, shape, safety, required/useful mapped fields, unknown fields, alias suggestions, and next actions.
+
+`buildCompatibilityBadge(reportOrDoctor)` returns `perpscope.compatibility-badge` with Markdown and JSON-friendly fields for READMEs, PRs, and capture handoffs.
+
 ## CLI
 
 ```bash
 perpscope compat report capture.json
 perpscope compat diff previous.json current.json
+perpscope compat doctor capture.json
+perpscope compat badge capture.json --json
 ```
 
 Try it locally with:
@@ -80,6 +86,8 @@ perpscope compat diff ../../examples/fixture-pack-minimal-terminal.json ../../ex
 
 For the real-backed candidate path, try `../../examples/fixture-pack-real-sanitized-rpc-shape.json`.
 
+For a copy-paste starter shape, use `../../examples/capture-template.json`.
+
 ## DTO Example
 
 ```js

package/bin/perpscope.mjs

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
 import {
+  buildCompatibilityBadge,
+  buildCompatibilityDoctor,
+  buildReadOnlyRpcSnapshot,
   buildPercolatorCompatibilityReport,
   compareCompatibilityReports,
+  detectPercolatorInputShape,
   exportCompatibilityReport,
   normalizePercolatorSnapshot,
   parsePercolatorJson
@@ -15,6 +19,8 @@ function usage() {
     "Usage:",
     "  perpscope compat report <capture.json>",
     "  perpscope compat diff <previous.json> <current.json>",
+    "  perpscope compat doctor <capture.json>",
+    "  perpscope compat badge <capture.json> [--json|--markdown]",
     "",
     "Read-only only: the adapter rejects wallet, signer, transaction, instruction, order, private key, seed, mnemonic, and API key fields."
   ].join("\n");
@@ -26,10 +32,30 @@ function readCapture(path) {
 }
 
 function buildReport(input) {
-  const snapshot = normalizePercolatorSnapshot(input);
+  const snapshot = detectPercolatorInputShape(input) === "read-only-rpc-fetch"
+    ? buildReadOnlyRpcSnapshot(input)
+    : normalizePercolatorSnapshot(input);
   return buildPercolatorCompatibilityReport(input, snapshot);
 }
 
+function formatDoctor(doctor) {
+  const lines = [
+    `PerpScope compat doctor: ${doctor.pass ? "PASS" : "CHECK"}`,
+    `shape: ${doctor.shape}`,
+    `status: ${doctor.status} (${doctor.score}/100)`,
+    `safety: ${doctor.safety}`,
+    `required: ${doctor.required.label}`,
+    `useful: ${doctor.useful.label}`,
+    `unknown fields: ${doctor.unknownFields.length}`,
+    `alias suggestions: ${doctor.aliasSuggestions.length}`
+  ];
+  if (doctor.nextActions.length) {
+    lines.push("next actions:");
+    for (const action of doctor.nextActions) lines.push(`- ${action}`);
+  }
+  return lines.join("\n");
+}
+
 function main() {
   const [scope, command, ...rest] = args;
   if (!scope || scope === "--help" || scope === "-h") {
@@ -48,6 +74,17 @@ function main() {
     console.log(JSON.stringify(compareCompatibilityReports(previous, current), null, 2));
     return;
   }
+  if (command === "doctor") {
+    const input = readCapture(rest[0]);
+    console.log(formatDoctor(buildCompatibilityDoctor(buildReport(input), { input })));
+    return;
+  }
+  if (command === "badge") {
+    const input = readCapture(rest[0]);
+    const badge = buildCompatibilityBadge(buildReport(input), { input });
+    console.log(rest.includes("--json") ? JSON.stringify(badge, null, 2) : badge.markdown);
+    return;
+  }
   throw new Error(`Unknown compat command: ${command || ""}`.trim());
 }
 

package/index.js

@@ -1,5 +1,7 @@
 export {
   assertReadOnlySnapshot,
+  buildCompatibilityBadge,
+  buildCompatibilityDoctor,
   buildCompatibilityRealityCheck,
   buildPercolatorCompatibilityReport,
   compareCompatibilityReports,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perpscope/percolator-adapter",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Read-only Percolator adapter helpers for Solana perps terminals.",
   "main": "./index.js",

package/src/lib/percolator-adapter.js

@@ -1,6 +1,6 @@
 import { normalizeFundingSkewHistory } from "./funding-history.js";
 
-export const PERPSCOPE_ADAPTER_VERSION = "0.8.0";
+export const PERPSCOPE_ADAPTER_VERSION = "0.9.0";
 
 const KEYPAIR_FIELD_PATTERN = /(^|_)(secret|private|keypair|mnemonic|seed|walletPath|wallet)(_|$)/i;
 const HISTORY_COMMAND_KEYS = new Set([
@@ -285,6 +285,75 @@ export function buildCompatibilityRealityCheck(inputOrReport, options = {}) {
   };
 }
 
+export function buildCompatibilityDoctor(inputOrReport, options = {}) {
+  const hasReportShape = inputOrReport && typeof inputOrReport === "object" && Array.isArray(inputOrReport.recognizedSections);
+  const report = hasReportShape ? normalizeCompatibilityReport(inputOrReport) : buildPercolatorCompatibilityReport(inputOrReport);
+  const reality = buildCompatibilityRealityCheck(report, {
+    input: hasReportShape ? options.input : inputOrReport,
+    generatedAt: options.generatedAt,
+    packageVersion: options.packageVersion
+  });
+  const requiredLane = reality.lanes.find((lane) => lane.label === "required") || {};
+  const usefulLane = reality.lanes.find((lane) => lane.label === "useful") || {};
+  const pass = report.status === "compatible" || (reality.gaps.dangerMissing === 0 && report.status === "partial");
+  const safety = report.status === "rejected" ? "rejected" : "read-only";
+
+  return {
+    schema: "perpscope.compatibility-doctor",
+    version: 1,
+    package: {
+      name: "@perpscope/percolator-adapter",
+      version: options.packageVersion || PERPSCOPE_ADAPTER_VERSION
+    },
+    generatedAt: options.generatedAt || new Date().toISOString(),
+    pass,
+    tone: report.status === "rejected" || reality.gaps.dangerMissing ? "danger" : report.summary.ignoredCount || report.summary.suggestionCount ? "warning" : "good",
+    status: report.status,
+    shape: report.shape,
+    score: report.score,
+    safety,
+    source: report.source,
+    required: {
+      mapped: reality.mapped.requiredCount,
+      total: reality.mapped.requiredTotal,
+      label: requiredLane.value || `${reality.mapped.requiredCount}/${reality.mapped.requiredTotal}`
+    },
+    useful: {
+      mapped: reality.mapped.optionalCount,
+      total: reality.mapped.optionalTotal,
+      label: usefulLane.value || `${reality.mapped.optionalCount}/${reality.mapped.optionalTotal}`
+    },
+    unknownFields: report.ignoredFields || [],
+    aliasSuggestions: report.aliasSuggestions || [],
+    missingFields: report.missingFields || [],
+    nextActions: compatibilityDoctorActions(report, reality)
+  };
+}
+
+export function buildCompatibilityBadge(inputOrReport, options = {}) {
+  const doctor = inputOrReport?.schema === "perpscope.compatibility-doctor"
+    ? inputOrReport
+    : buildCompatibilityDoctor(inputOrReport, options);
+  const label = options.label || "PerpScope compatible";
+  const summary = `${doctor.status}, ${doctor.score}/100, ${doctor.aliasSuggestions.length} alias suggestions`;
+  return {
+    schema: "perpscope.compatibility-badge",
+    version: 1,
+    package: doctor.package,
+    generatedAt: options.generatedAt || doctor.generatedAt || new Date().toISOString(),
+    label,
+    status: doctor.status,
+    score: doctor.score,
+    tone: doctor.tone,
+    aliasSuggestionCount: doctor.aliasSuggestions.length,
+    unknownFieldCount: doctor.unknownFields.length,
+    required: doctor.required,
+    useful: doctor.useful,
+    markdown: `**${label}:** ${summary}`,
+    text: `${label}: ${summary}`
+  };
+}
+
 const COMPATIBILITY_SECTION_SPECS = [
   {
     id: "safety",
@@ -737,6 +806,32 @@ function realityProvenance(input, report) {
   };
 }
 
+function compatibilityDoctorActions(report, reality) {
+  const actions = [];
+  if (report.status === "rejected") {
+    actions.push("Remove wallet, signer, transaction, instruction, order, secret, private key, seed, mnemonic, or API key fields.");
+    return actions;
+  }
+  const dangerMissing = (report.missingFields || []).filter((field) => field.severity === "danger");
+  if (dangerMissing.length) {
+    actions.push(`Map required fields: ${dangerMissing.map((field) => field.field).join(", ")}.`);
+  }
+  const warningMissing = (report.missingFields || []).filter((field) => field.severity !== "danger").slice(0, 3);
+  if (warningMissing.length) {
+    actions.push(`Add useful trader fields: ${warningMissing.map((field) => field.field).join(", ")}.`);
+  }
+  if ((report.aliasSuggestions || []).length) {
+    actions.push(`Apply alias suggestions: ${(report.aliasSuggestions || []).slice(0, 3).map((suggestion) => `${suggestion.candidatePath || suggestion.action} -> ${suggestion.field}`).join(", ")}.`);
+  }
+  if ((report.ignoredFields || []).length) {
+    actions.push(`${report.ignoredFields.length} unknown field${report.ignoredFields.length === 1 ? "" : "s"} can be mapped or intentionally ignored.`);
+  }
+  if (!actions.length && reality.gaps.dangerMissing === 0) {
+    actions.push("Ready for read-only terminal display.");
+  }
+  return actions;
+}
+
 function differenceByField(left = [], right = []) {
   const rightFields = new Set((right || []).map((entry) => entry.field));
   return (left || []).filter((entry) => !rightFields.has(entry.field));