@amityco/social-plus-vise 0.8.1 → 0.12.2

package/dist/tools/debug.js

@@ -0,0 +1,267 @@
+import { objectInput, optionalBooleanField, stringField, textResult } from "../types.js";
+import { checkCompliance, rulesById } from "./compliance.js";
+import { inspectProject } from "./project.js";
+function sanitizeError(errorMessage) {
+    // Strip out local absolute file paths (e.g., /Users/admin/..., /home/user/...)
+    let sanitized = errorMessage.replace(/(?:\/(?:users|home)\/[^\s:]+)/gi, "[LOCAL_PATH]");
+    // Strip out thread IDs / Hex memory addresses
+    sanitized = sanitized.replace(/0x[0-9a-fA-F]+/g, "[HEX_ADDR]");
+    return sanitized;
+}
+function extractExceptionClass(errorMessage) {
+    // Try to find a Java/Kotlin exception (e.g. java.lang.NullPointerException or com.amity.AmityException)
+    const javaMatch = errorMessage.match(/([a-zA-Z0-9_.]+[A-Z][a-zA-Z0-9_]*Exception)/);
+    if (javaMatch)
+        return javaMatch[1];
+    // Try to find a JS Error (e.g. TypeError, Error)
+    const jsMatch = errorMessage.match(/([A-Z][a-zA-Z0-9]*Error):/);
+    if (jsMatch)
+        return jsMatch[1];
+    return null;
+}
+export async function debugIssue(repoPath, errorMessage, options = {}) {
+    const sanitizedError = sanitizeError(errorMessage);
+    const exceptionClass = extractExceptionClass(errorMessage);
+    // 1. Inspect Context
+    const inspection = await inspectProject(repoPath);
+    // 2. Version-mismatch heuristic (NOT used as benchmark evidence).
+    // This is a keyword-only heuristic, not real dependency inspection.
+    // Version-mismatch scenarios are excluded from the TypeScript pilot
+    // (see DEBUGGING_BENCHMARK_PLAN.md Section 5 "Explicitly excluded from the pilot").
+    // Do not use this branch as measured benchmark evidence.
+    let likelyCause = "";
+    if (errorMessage.includes("method not found") || errorMessage.includes("Unresolved reference")) {
+        likelyCause = "Potential Version Mismatch: The codebase is using a newer API pattern against an older SDK version installed in the project.";
+    }
+    // 3. Compliance History Correlation
+    const correlatedRules = [];
+    let checkResult = null;
+    try {
+        checkResult = await checkCompliance(repoPath);
+        const rulesMap = await rulesById();
+        for (const rule of checkResult.rules) {
+            if (rule.status === "deterministic-fail" || rule.status === "attestation-needed") {
+                // It failed. Check if symptoms match.
+                const ruleDef = rulesMap.get(rule.ruleId);
+                const symptoms = ruleDef?.symptoms || [];
+                if (symptoms.some(s => errorMessage.includes(s))) {
+                    correlatedRules.push({
+                        ruleId: rule.ruleId,
+                        status: "failed",
+                        impact: `This rule is currently failing and its known symptoms match the crash log.`,
+                    });
+                }
+            }
+            else if (rule.status === "attested") {
+                // Check for false-positive attestations
+                const ruleDef = rulesMap.get(rule.ruleId);
+                const symptoms = ruleDef?.symptoms || [];
+                if (symptoms.some(s => errorMessage.includes(s))) {
+                    correlatedRules.push({
+                        ruleId: rule.ruleId,
+                        status: "attested",
+                        attestation: rule.attestation,
+                        impact: `Warning: This rule was attested as passing, but a matching runtime exception was detected. The custom implementation may be flawed.`,
+                    });
+                }
+            }
+        }
+    }
+    catch (err) {
+        // Ignore error if compliance sidecar doesn't exist yet
+    }
+    if (!likelyCause && correlatedRules.length > 0) {
+        likelyCause = `The crash is likely caused by the non-compliant implementation of ${correlatedRules.map(r => r.ruleId).join(", ")}.`;
+    }
+    else if (!likelyCause) {
+        likelyCause = `An unknown ${exceptionClass || "runtime"} error occurred.`;
+    }
+    // Build rule-specific remediation guidance from rule definitions and validator findings.
+    const suggestedRemediation = buildRemediation(correlatedRules, checkResult);
+    const repairBrief = buildRepairBrief(correlatedRules, checkResult, inspection.platforms, likelyCause);
+    const payload = {
+        correlatedRules,
+        likelyCause,
+        sanitizedErrorSignature: sanitizedError,
+        extractedException: exceptionClass,
+        suggestedRemediation,
+        repairBrief,
+        relevantDocs: [
+            {
+                title: "Troubleshooting",
+                url: "https://learn.social.plus/troubleshooting"
+            }
+        ]
+    };
+    if (options.brief) {
+        return {
+            likelyCause: payload.likelyCause,
+            correlatedRules: payload.correlatedRules,
+            repairBrief: payload.repairBrief,
+            relevantDocs: payload.relevantDocs,
+        };
+    }
+    return payload;
+}
+function buildRemediation(correlatedRules, checkResult) {
+    if (correlatedRules.length === 0) {
+        return { action: "Review the correlated rules and ensure SDK integration matches the required patterns." };
+    }
+    const rules = correlatedRules.map(cr => {
+        const ruleResult = checkResult?.rules.find(r => r.ruleId === cr.ruleId);
+        // Prefer the validator's per-finding recommendation; fall back to a generic note.
+        const guidance = ruleResult?.recommendation
+            ?? "Review the rule implementation and ensure the SDK integration matches the required pattern.";
+        return {
+            ruleId: cr.ruleId,
+            title: ruleResult?.title ?? cr.ruleId,
+            guidance,
+            file: ruleResult?.finding?.file,
+            docRef: `vise explain ${cr.ruleId}`,
+        };
+    });
+    return {
+        action: "Repair the compliance failure(s) identified above.",
+        rules,
+    };
+}
+function buildRepairBrief(correlatedRules, checkResult, platforms, likelyCause) {
+    const primaryRuleId = pickPrimaryRuleId(correlatedRules);
+    const verify = verificationCommands(platforms);
+    if (!primaryRuleId) {
+        return {
+            primaryRuleId: null,
+            why: likelyCause,
+            candidateFiles: [],
+            minimumPatchShape: [
+                "Inspect the SDK integration path mentioned in the symptom.",
+                "Repair only the smallest social.plus code path that explains the runtime failure.",
+            ],
+            preserve: [
+                "Do not widen the patch beyond the failing social.plus integration path.",
+                "Preserve any existing compliant setup, auth, and pagination wiring unless the customer explicitly changes behavior.",
+            ],
+            verify,
+        };
+    }
+    const ruleResult = checkResult?.rules.find((rule) => rule.ruleId === primaryRuleId);
+    const template = repairTemplateForRule(primaryRuleId);
+    return {
+        primaryRuleId,
+        why: template.why ?? likelyCause,
+        candidateFiles: candidateFilesForRule(primaryRuleId, checkResult),
+        minimumPatchShape: template.minimumPatchShape,
+        preserve: template.preserve,
+        verify,
+    };
+}
+function pickPrimaryRuleId(correlatedRules) {
+    const failed = correlatedRules.find((rule) => rule.status === "failed");
+    return failed?.ruleId ?? correlatedRules[0]?.ruleId ?? null;
+}
+function candidateFilesForRule(ruleId, checkResult) {
+    if (!checkResult) {
+        return [];
+    }
+    const matches = checkResult.rules
+        .filter((rule) => rule.ruleId === ruleId)
+        .flatMap((rule) => {
+        const file = rule.finding?.file;
+        return typeof file === "string" && file.length > 0 ? [file] : [];
+    });
+    return Array.from(new Set(matches));
+}
+function verificationCommands(platforms) {
+    const commands = [];
+    if (platforms.includes("typescript") || platforms.includes("react-native")) {
+        commands.push("npm run typecheck");
+    }
+    commands.push("vise check . --ci");
+    commands.push("vise run-sensors .");
+    return commands;
+}
+function repairTemplateForRule(ruleId) {
+    const templates = {
+        "typescript.client.region": {
+            why: "The SDK client is initialized without an explicit region or endpoint, so runtime setup does not match the customer's social.plus project.",
+            minimumPatchShape: [
+                "Edit the existing client setup module or initialization function.",
+                "Pass apiRegion or apiEndpoint into the existing client initialization call, such as Client.create() or Client.createClient().",
+                "Prefer the app's existing config or environment source if one already exists.",
+            ],
+            preserve: [
+                "Preserve the app's existing config or environment source of truth for region or endpoint.",
+                "Do not hardcode a guessed default region if the customer already has a region owner elsewhere in the app.",
+            ],
+        },
+        "typescript.session.renewal": {
+            why: "The login path is missing a renewal handler, so the SDK cannot refresh expiring access tokens.",
+            minimumPatchShape: [
+                "Edit the existing Client.login call in the current login path.",
+                "Add sessionHandler.sessionWillRenewAccessToken(renewal).",
+                "Call renewal.renew() from that callback.",
+            ],
+            preserve: [
+                "Preserve the existing session owner and login flow shape.",
+                "Retain the session handler for the full session lifetime instead of creating a short-lived local object.",
+            ],
+        },
+        "typescript.live-collection.api-mismatch": {
+            why: "The feed is using a one-shot list query instead of a reactive LiveCollection, so new posts do not flow into the UI.",
+            minimumPatchShape: [
+                "Edit the existing feed query function instead of replacing the feed surface.",
+                "Convert the one-shot query into a reactive collection with onData.",
+                "Return cleanup that unsubscribes the collection.",
+            ],
+            preserve: [
+                "Preserve existing pagination and query wiring such as pageToken, hasMore/loadMore, or infinite-query state.",
+                "Do not widen the patch into unrelated rendering or moderation logic while restoring live updates.",
+            ],
+        },
+        "typescript.auth.logout-on-user-switch": {
+            why: "The app switches user identity by logging in directly without clearing the previous SDK session.",
+            minimumPatchShape: [
+                "Edit the existing user-switch flow.",
+                "Await Client.logout() before the next Client.login().",
+                "Keep the login call's existing renewal handler behavior intact.",
+            ],
+            preserve: [
+                "Preserve the current sessionHandler and renewal path while inserting logout-before-login.",
+                "Do not widen the patch into unrelated auth or navigation state.",
+            ],
+        },
+    };
+    return (templates[ruleId] ?? {
+        why: "A compliance rule correlated strongly with the reported social.plus failure.",
+        minimumPatchShape: [
+            "Edit the smallest code path associated with the correlated rule.",
+            "Bring the implementation back into compliance with the rule requirement.",
+        ],
+        preserve: [
+            "Preserve adjacent compliant wiring while repairing the failing rule.",
+        ],
+    });
+}
+export const debugIssueTool = {
+    name: "debug_issue",
+    description: "Debug a runtime crash, build failure, or logic issue against the social.plus SDK's specific context.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            errorMessage: { type: "string" },
+            brief: { type: "boolean" },
+        },
+        required: ["repoPath", "errorMessage"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const errorMessage = stringField(args, "errorMessage");
+        const result = await debugIssue(repoPath, errorMessage, {
+            brief: optionalBooleanField(args, "brief"),
+        });
+        return textResult(result);
+    },
+};