@wowok/agent-mcp 2.3.16 → 2.4.1

package/dist/knowledge/guard-lint.js

@@ -0,0 +1,590 @@
+import { validateGuardData, MAX_DESCRIPTION_LENGTH, MAX_TABLE_SIZE, } from "@wowok/wowok";
+import { assessGuardRisks } from "./guard-risk.js";
+import { findScene, inferSceneFromAction } from "./guard-ledger.js";
+import { suggestTemplateForScene } from "./guard-templates.js";
+function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+function rootToString(root) {
+    return JSON.stringify(root);
+}
+function hasSignerContext(root) {
+    const str = rootToString(root);
+    return str.includes('"Signer"') || str.includes('"context":"Signer"') || str.includes('"context": "Signer"');
+}
+function getSubmissionEntries(table) {
+    return table.filter((e) => e.b_submission === true);
+}
+function inferValueType(value) {
+    if (typeof value === "string") {
+        if (value.startsWith("0x") && value.length >= 3)
+            return "Address";
+        return "String";
+    }
+    if (typeof value === "number") {
+        if (Number.isInteger(value)) {
+            if (value >= 0 && value <= 255)
+                return "U8";
+            if (value >= 0 && value <= 65535)
+                return "U16";
+            return "U64";
+        }
+        return "U256";
+    }
+    if (typeof value === "boolean")
+        return "Bool";
+    if (Array.isArray(value)) {
+        if (value.length > 0) {
+            const elemType = inferValueType(value[0]);
+            if (elemType === "Address")
+                return "Vec<Address>";
+            if (elemType === "String")
+                return "Vec<String>";
+            if (elemType === "Bool")
+                return "Vec<Bool>";
+        }
+        return "Vec<Address>";
+    }
+    return undefined;
+}
+function sdkIssueToDiagnostic(issue) {
+    return {
+        code: issue.code,
+        message: issue.message,
+        severity: issue.severity,
+        source: "sdk",
+        location: {
+            path: issue.path,
+        },
+        fix: {
+            description: `SDK validation failed (${issue.sdk_error ?? "InvalidParam"}); manual fix required`,
+            auto_fixable: false,
+        },
+    };
+}
+async function checkSdkSyntax(json) {
+    const tableForSdk = json.table.map((e) => ({
+        identifier: e.identifier,
+        b_submission: e.b_submission ?? false,
+        value_type: (e.value_type ?? "Address"),
+        value: e.value,
+        name: e.name ?? "",
+    }));
+    const issues = await validateGuardData({
+        description: json.description,
+        table: tableForSdk,
+        root: json.root,
+        rely: json.rely,
+    });
+    return issues.map(sdkIssueToDiagnostic);
+}
+function checkSemanticErrors(json) {
+    const diagnostics = [];
+    const { table, root, binding_hint } = json;
+    const submissionEntries = getSubmissionEntries(table);
+    if (submissionEntries.length > 0 && root && !hasSignerContext(root)) {
+        const hasAddressSubmission = submissionEntries.some((e) => e.value_type === "Address");
+        if (hasAddressSubmission) {
+            const indices = submissionEntries
+                .filter((e) => e.value_type === "Address")
+                .map((e) => table.indexOf(e));
+            diagnostics.push({
+                code: "LE-04",
+                message: "Submitted data has no Signer binding (submission forgery risk)",
+                severity: "error",
+                source: "lint",
+                location: { path: indices.map((i) => `/table/${i}`).join(" → ") },
+                fix: {
+                    description: "Add logic_equal(context(Signer), identifier[N]) in root to bind the submitter identity",
+                    auto_fixable: false,
+                },
+            });
+        }
+    }
+    const scene = binding_hint ? findScene(binding_hint.host_object ?? "", binding_hint.binding_field ?? "") : undefined;
+    if (scene?.id === "arbitration_voting_guard") {
+        const hasWeightSubmission = submissionEntries.some((e) => ["U8", "U16", "U32", "U64", "U128", "U256"].includes(e.value_type ?? ""));
+        if (hasWeightSubmission) {
+            const indices = submissionEntries
+                .filter((e) => ["U8", "U16", "U32", "U64", "U128", "U256"].includes(e.value_type ?? ""))
+                .map((e) => table.indexOf(e));
+            diagnostics.push({
+                code: "LE-05",
+                message: "voting_guard voting weight comes from submitted data (weight forgery risk)",
+                severity: "error",
+                source: "lint",
+                location: { path: indices.map((i) => `/table/${i}`).join(" → ") },
+                fix: {
+                    description: "Derive arbitrator weights from the Arb object via witness (e.g. 105 TypeArbArbitration) rather than submitting them directly",
+                    auto_fixable: false,
+                },
+            });
+        }
+    }
+    if (scene?.id === "gen_passport_guard" || binding_hint?.action === "gen_passport") {
+        const rootStr = rootToString(root);
+        if (rootStr.includes("1167") || rootStr.includes("repository.data")) {
+            const hasQuoteGuard = rootStr.includes("quote_guard");
+            if (hasQuoteGuard) {
+                diagnostics.push({
+                    code: "LE-06",
+                    message: "gen_passport scene uses quote_guard (will always fail)",
+                    severity: "error",
+                    source: "lint",
+                    location: { path: "/root" },
+                    fix: {
+                        description: "Remove quote_guard authentication, or switch to a query method that does not depend on impack_list",
+                        auto_fixable: false,
+                    },
+                });
+            }
+        }
+    }
+    if (binding_hint?.host_object && scene) {
+        const hostType = binding_hint.host_object;
+        const circularEntries = table.filter((e) => !e.b_submission && e.value_type === "Address" &&
+            typeof e.value === "string" && e.value.startsWith("0x") &&
+            e.object_type === hostType);
+        if (circularEntries.length > 0) {
+            const indices = circularEntries.map((e) => table.indexOf(e));
+            diagnostics.push({
+                code: "LE-07",
+                message: `Circular reference uses an address rather than a name (Host Object may not be published yet when the Guard is created)`,
+                severity: "error",
+                source: "lint",
+                location: { path: indices.map((i) => `/table/${i}/value`).join(" → ") },
+                fix: {
+                    description: `Change value from an address to an object name (e.g. "service1"); the SDK will resolve it to an address after the Host Object is published`,
+                    auto_fixable: false,
+                },
+            });
+        }
+    }
+    return diagnostics;
+}
+function checkSyntaxHints(json) {
+    const diagnostics = [];
+    const { table } = json;
+    if (!json.description || json.description.trim() === "") {
+        diagnostics.push({
+            code: "SH-01",
+            message: "description is missing or empty",
+            severity: "info",
+            source: "lint",
+            location: { path: "/description" },
+            fix: {
+                description: "Add a description, e.g. 'Service buy_guard: whitelist validation'",
+                auto_fixable: true,
+            },
+        });
+    }
+    for (let i = 0; i < table.length; i++) {
+        const entry = table[i];
+        if (!entry.name || entry.name.trim() === "") {
+            diagnostics.push({
+                code: "SH-03",
+                message: `table[${i}] is missing name`,
+                severity: "warning",
+                source: "lint",
+                location: { path: `/table/${i}/name` },
+                fix: {
+                    description: `Add a name, e.g. "data entry ${entry.identifier}"`,
+                    auto_fixable: true,
+                },
+            });
+        }
+    }
+    for (let i = 0; i < table.length; i++) {
+        const entry = table[i];
+        if (!entry.value_type) {
+            diagnostics.push({
+                code: "SH-05",
+                message: `table[${i}] is missing value_type`,
+                severity: "warning",
+                source: "lint",
+                location: { path: `/table/${i}/value_type` },
+                fix: {
+                    description: "Infer value_type from value (e.g. Address/String/U64, etc.)",
+                    auto_fixable: true,
+                },
+            });
+        }
+    }
+    if (table.length > MAX_TABLE_SIZE) {
+        diagnostics.push({
+            code: "SH-07",
+            message: `table entry count ${table.length} exceeds the maximum limit ${MAX_TABLE_SIZE}`,
+            severity: "error",
+            source: "lint",
+            location: { path: "/table" },
+            fix: {
+                description: "Slim down the table by merging similar entries, or split into multiple Guards + rely",
+                auto_fixable: false,
+            },
+        });
+    }
+    for (let i = 0; i < table.length; i++) {
+        if (table[i].b_submission === undefined) {
+            diagnostics.push({
+                code: "SH-10",
+                message: `table[${i}] b_submission is missing`,
+                severity: "info",
+                source: "lint",
+                location: { path: `/table/${i}/b_submission` },
+                fix: {
+                    description: "Set to false (constant) or true (submitted data)",
+                    auto_fixable: true,
+                },
+            });
+        }
+    }
+    return diagnostics;
+}
+function checkSuggestions(json) {
+    const diagnostics = [];
+    const { root, binding_hint, table } = json;
+    if (root) {
+        const rootStr = rootToString(root);
+        if (rootStr.includes("vec_contains_address") && rootStr.includes("Signer")) {
+            diagnostics.push({
+                code: "SG-01",
+                message: "Matches Pattern P04 (whitelist validation)",
+                severity: "hint",
+                source: "lint",
+                location: { path: "/root" },
+                fix: { description: "Refer to the P04 Pattern to ensure best practices", auto_fixable: false },
+            });
+        }
+        else if (rootStr.includes("logic_equal") && rootStr.includes("Signer")) {
+            const hasAddressConst = table.some((e) => !e.b_submission && e.value_type === "Address" && typeof e.value === "string" && e.value.length > 0);
+            if (hasAddressConst) {
+                diagnostics.push({
+                    code: "SG-01",
+                    message: "Matches Pattern P04 (whitelist validation — single-address variant)",
+                    severity: "hint",
+                    source: "lint",
+                    location: { path: "/root" },
+                    fix: { description: "P04 single-address form; for multi-address scenarios, consider vec_contains_address", auto_fixable: false },
+                });
+            }
+        }
+        if (rootStr.includes("logic_as_u256_greater") ||
+            rootStr.includes("logic_as_u256_lesser")) {
+            diagnostics.push({
+                code: "SG-01",
+                message: "Matches Pattern P02 (numeric threshold validation)",
+                severity: "hint",
+                source: "lint",
+                location: { path: "/root" },
+                fix: { description: "Suitable for amount/quantity threshold validation scenarios", auto_fixable: false },
+            });
+        }
+        if (rootStr.includes("convert_witness")) {
+            diagnostics.push({
+                code: "SG-01",
+                message: "Matches Pattern P09 (witness-derived validation)",
+                severity: "hint",
+                source: "lint",
+                location: { path: "/root" },
+                fix: { description: "Suitable for cross-object relationship validation (e.g. Order→Progress)", auto_fixable: false },
+            });
+        }
+    }
+    if (binding_hint?.action) {
+        const validActions = ["buy", "forward", "allocate", "claim_reward", "vote", "dispute", "write_repository", "submit_progress", "gen_passport"];
+        if (validActions.includes(binding_hint.action)) {
+            const scene = inferSceneFromAction(binding_hint.action);
+            if (scene) {
+                const template = suggestTemplateForScene(scene.id);
+                if (template) {
+                    diagnostics.push({
+                        code: "SG-02",
+                        message: `Recommended scene template: ${template.name}`,
+                        severity: "hint",
+                        source: "lint",
+                        location: { path: "/" },
+                        fix: { description: `Refer to template ${template.id} (${template.example_use_case})`, auto_fixable: false },
+                    });
+                }
+            }
+        }
+    }
+    const submissionEntries = getSubmissionEntries(table);
+    for (const entry of submissionEntries) {
+        const name = entry.name ?? "";
+        if (name.length < 10 || /^[a-z_]+$/i.test(name)) {
+            const idx = table.indexOf(entry);
+            diagnostics.push({
+                code: "SG-03",
+                message: `table[${idx}] submitted data has a vague name description`,
+                severity: "info",
+                source: "lint",
+                location: { path: `/table/${idx}/name` },
+                fix: { description: "Use a full natural-language description (≥10 characters), e.g. 'user-submitted operation type (return/damage)'", auto_fixable: false },
+            });
+        }
+    }
+    return diagnostics;
+}
+export function autoFixGuard(json) {
+    const fixed = deepClone(json);
+    const actions = [];
+    if (!fixed.description || fixed.description.trim() === "") {
+        fixed.description = `Guard (table: ${fixed.table.length} items, root: ${fixed.root?.type ?? "unknown"})`;
+        actions.push({
+            diagnostic_code: "SH-01",
+            description: "Fill in default description",
+            after: fixed.description,
+            path: "/description",
+        });
+    }
+    if (fixed.description && fixed.description.length > MAX_DESCRIPTION_LENGTH) {
+        const before = fixed.description;
+        fixed.description = fixed.description.substring(0, MAX_DESCRIPTION_LENGTH);
+        actions.push({
+            diagnostic_code: "G-001",
+            description: `Truncate description to ${MAX_DESCRIPTION_LENGTH} characters`,
+            before: `${before.length} characters`,
+            after: `${fixed.description.length} characters`,
+            path: "/description",
+        });
+    }
+    for (let i = 0; i < fixed.table.length; i++) {
+        const entry = fixed.table[i];
+        if (!entry.name || entry.name.trim() === "") {
+            entry.name = `data entry ${entry.identifier}`;
+            actions.push({
+                diagnostic_code: "SH-03",
+                description: `table[${i}] fill in name`,
+                after: entry.name,
+                path: `/table/${i}/name`,
+            });
+        }
+    }
+    for (let i = 0; i < fixed.table.length; i++) {
+        const entry = fixed.table[i];
+        if (!entry.value_type && entry.value !== undefined && entry.value !== null) {
+            const inferred = inferValueType(entry.value);
+            if (inferred) {
+                entry.value_type = inferred;
+                actions.push({
+                    diagnostic_code: "SH-05",
+                    description: `table[${i}] infer value_type`,
+                    after: inferred,
+                    path: `/table/${i}/value_type`,
+                });
+            }
+        }
+    }
+    const idMap = new Map();
+    let nextId = 0;
+    for (let i = 0; i < fixed.table.length; i++) {
+        const entry = fixed.table[i];
+        if (!idMap.has(entry.identifier)) {
+            idMap.set(entry.identifier, nextId);
+            if (entry.identifier !== nextId) {
+                actions.push({
+                    diagnostic_code: "G-007",
+                    description: `table[${i}] identifier ${entry.identifier} → ${nextId}`,
+                    before: String(entry.identifier),
+                    after: String(nextId),
+                    path: `/table/${i}/identifier`,
+                });
+            }
+            entry.identifier = nextId;
+            nextId++;
+        }
+        else {
+            const oldId = entry.identifier;
+            entry.identifier = nextId;
+            idMap.set(oldId, nextId);
+            actions.push({
+                diagnostic_code: "G-007",
+                description: `table[${i}] identifier ${oldId} duplicate → reallocated to ${nextId}`,
+                before: String(oldId),
+                after: String(nextId),
+                path: `/table/${i}/identifier`,
+            });
+            nextId++;
+        }
+    }
+    for (let i = 0; i < fixed.table.length; i++) {
+        const entry = fixed.table[i];
+        if (entry.b_submission === undefined) {
+            entry.b_submission = false;
+            actions.push({
+                diagnostic_code: "SH-10",
+                description: `table[${i}] b_submission default set to false`,
+                after: "false",
+                path: `/table/${i}/b_submission`,
+            });
+        }
+    }
+    if (fixed.rely?.guards && fixed.rely.guards.length > 0) {
+        const unique = [...new Set(fixed.rely.guards)];
+        if (unique.length !== fixed.rely.guards.length) {
+            actions.push({
+                diagnostic_code: "G-009",
+                description: `rely deduplicate: ${fixed.rely.guards.length} → ${unique.length}`,
+                before: JSON.stringify(fixed.rely.guards),
+                after: JSON.stringify(unique),
+                path: "/rely/guards",
+            });
+            fixed.rely.guards = unique;
+        }
+    }
+    return { fixed, actions };
+}
+export async function lintGuard(json, options) {
+    const doAutoFix = options?.auto_fix ?? true;
+    const { table, root, rely, binding_hint } = json;
+    const diagnostics = [];
+    let risk_assessment;
+    const sdkDiagnostics = await checkSdkSyntax(json);
+    diagnostics.push(...sdkDiagnostics);
+    const semanticDiagnostics = checkSemanticErrors(json);
+    diagnostics.push(...semanticDiagnostics);
+    const hintDiagnostics = checkSyntaxHints(json);
+    diagnostics.push(...hintDiagnostics);
+    let fixed_json;
+    let fix_actions = [];
+    if (doAutoFix) {
+        const { fixed, actions } = autoFixGuard(json);
+        if (actions.length > 0) {
+            fixed_json = fixed;
+            fix_actions = actions;
+        }
+    }
+    if (table.length > 0 && root) {
+        const scene = binding_hint
+            ? findScene(binding_hint.host_object ?? "", binding_hint.binding_field ?? "")
+            : undefined;
+        const mappedTable = table.map((e) => ({
+            identifier: e.identifier,
+            b_submission: e.b_submission ?? false,
+            value_type: e.value_type ?? "Address",
+            value: e.value,
+            name: e.name,
+            object_type: e.object_type,
+        }));
+        risk_assessment = assessGuardRisks({ table: mappedTable, root, rely, scene });
+        for (const r of risk_assessment.risks) {
+            const severity = r.level === "critical" || r.level === "high" ? "error" :
+                r.level === "medium" ? "warning" :
+                    r.level === "low" ? "info" : "hint";
+            const rawEvidence = r.evidence ?? "";
+            const path = rawEvidence.startsWith("/") ? rawEvidence : "/";
+            diagnostics.push({
+                code: r.id,
+                message: `[${r.level}] ${r.title}`,
+                severity,
+                source: "risk",
+                location: { path },
+                fix: {
+                    description: r.mitigation,
+                    auto_fixable: false,
+                },
+            });
+        }
+    }
+    const suggestionDiagnostics = checkSuggestions(json);
+    diagnostics.push(...suggestionDiagnostics);
+    const errors = diagnostics.filter((d) => d.severity === "error").length;
+    const warnings = diagnostics.filter((d) => d.severity === "warning").length;
+    const infos = diagnostics.filter((d) => d.severity === "info" || d.severity === "hint").length;
+    const ready = errors === 0;
+    let next_step;
+    if (errors > 0) {
+        next_step = `Fix ${errors} error(s) and re-run lint`;
+    }
+    else if (warnings > 0) {
+        next_step = `Consider addressing ${warnings} warning(s), then submit to SDK newGuard() for final syntax validation`;
+    }
+    else {
+        next_step = "lint passed (no errors); submit to SDK newGuard() for final syntax validation before going on-chain";
+    }
+    return {
+        json_summary: {
+            table_count: table.length,
+            root_type: root?.type ?? "unknown",
+            has_rely: !!rely?.guards?.length,
+            rely_count: rely?.guards?.length ?? 0,
+            has_description: !!json.description,
+        },
+        diagnostics,
+        fixed_json,
+        fix_actions,
+        risk_assessment,
+        summary: {
+            errors,
+            warnings,
+            infos,
+            auto_fixes_applied: fix_actions.length,
+            ready,
+            next_step,
+        },
+    };
+}
+export async function isGuardReady(json) {
+    const result = await lintGuard(json, { auto_fix: false });
+    return result.summary.ready;
+}
+export async function getGuardErrors(json) {
+    const result = await lintGuard(json, { auto_fix: false });
+    return result.diagnostics.filter((d) => d.severity === "error");
+}
+export function formatLintResult(result) {
+    const lines = [];
+    lines.push("=== Guard JSON Lint Report ===");
+    lines.push("");
+    lines.push("Summary:");
+    lines.push(`  Errors:     ${result.summary.errors}`);
+    lines.push(`  Warnings:   ${result.summary.warnings}`);
+    lines.push(`  Infos:      ${result.summary.infos}`);
+    lines.push(`  Auto-fixes: ${result.summary.auto_fixes_applied}`);
+    lines.push(`  Ready:      ${result.summary.ready ? "YES" : "NO"}`);
+    lines.push(`  Next step:  ${result.summary.next_step}`);
+    lines.push("");
+    if (result.fix_actions.length > 0) {
+        lines.push("--- Auto-fix Actions ---");
+        for (const action of result.fix_actions) {
+            lines.push(`  [${action.diagnostic_code}] ${action.description}`);
+            lines.push(`    Path: ${action.path}`);
+            if (action.before && action.after) {
+                lines.push(`    ${action.before} -> ${action.after}`);
+            }
+        }
+        lines.push("");
+    }
+    const errors = result.diagnostics.filter((d) => d.severity === "error");
+    const warnings = result.diagnostics.filter((d) => d.severity === "warning");
+    const infos = result.diagnostics.filter((d) => d.severity === "info" || d.severity === "hint");
+    if (errors.length > 0) {
+        lines.push("--- Errors (must fix) ---");
+        for (const d of errors) {
+            lines.push(`  [${d.code}] (${d.source}) ${d.message}`);
+            lines.push(`    Path: ${d.location.path}`);
+            if (d.fix)
+                lines.push(`    Fix:  ${d.fix.description}`);
+        }
+        lines.push("");
+    }
+    if (warnings.length > 0) {
+        lines.push("--- Warnings (consider fixing) ---");
+        for (const d of warnings) {
+            lines.push(`  [${d.code}] (${d.source}) ${d.message}`);
+            lines.push(`    Path: ${d.location.path}`);
+            if (d.fix)
+                lines.push(`    Fix:  ${d.fix.description}`);
+        }
+        lines.push("");
+    }
+    if (infos.length > 0) {
+        lines.push("--- Info & Hints ---");
+        for (const d of infos) {
+            lines.push(`  [${d.code}] (${d.source}) ${d.message}`);
+            lines.push(`    Path: ${d.location.path}`);
+        }
+    }
+    return lines.join("\n");
+}