progmune-runtime 2.1.6 → 3.2.0

package/dist/resource-abstraction.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * Resource Abstraction Layer — from words to semantics.
+ *
+ * The detector used to work like this:
+ *   createPost → Post Asset → Protocol
+ *
+ * Now it works like this:
+ *   create<X> → X is a MutableResource → needs Ownership + Validation + Authorization
+ *
+ * This is the generalization breakthrough:
+ *   Post, Issue, Ticket, Task, Order, Artifact → ALL automatically recognized
+ *
+ * Three components:
+ *   1. Resource Classifier — identifies what kind of resource an entity is
+ *   2. Protocol Deriver — derives required protocols from resource type
+ *   3. Lexical Generalization — maps unknown entity names to known categories
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseResourceName = parseResourceName;
+exports.classifyResource = classifyResource;
+exports.abstractResource = abstractResource;
+exports.isMutatingOperation = isMutatingOperation;
+exports.isReadOperation = isReadOperation;
+exports.getRequiredProtocols = getRequiredProtocols;
+exports.testLexicalGeneralization = testLexicalGeneralization;
+// ═══════════════════════════════════════════════════════════════
+// Verb → Resource Kind mapping
+// ═══════════════════════════════════════════════════════════════
+const MUTABLE_VERBS = new Set([
+    "create", "add", "insert", "new", "make", "build",
+    "update", "edit", "modify", "change", "set", "put",
+    "delete", "remove", "destroy", "drop", "clear", "erase",
+]);
+const READ_VERBS = new Set([
+    "get", "fetch", "find", "query", "read", "load", "list", "search", "lookup",
+]);
+const AUTH_VERBS = new Set([
+    "login", "logout", "register", "signup", "signin", "authenticate", "authorize",
+    "verify", "validate", "check",
+]);
+// ═══════════════════════════════════════════════════════════════
+// Entity → Resource Kind heuristics
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Known entity suffixes that indicate resource kinds.
+ * These are generalizable — they work for ANY entity name.
+ */
+const RESOURCE_SUFFIX_PATTERNS = [
+    {
+        // Mutable resources: Post, Issue, Ticket, Task, Order, Product, Project, etc.
+        // These need: Ownership + Validation + Authorization + DataIntegrity
+        pattern: /^(Post|Issue|Ticket|Task|Order|Product|Project|Item|Entry|Record|Document|Article|Page|Thread|Topic|Subject|Object|Entity|Artifact|Asset|Resource|Job|Workflow|Pipeline|Deployment|Release)$/i,
+        kind: "mutable_resource",
+        protocols: ["ownership_check", "input_validation", "authorization", "data_integrity"],
+    },
+    {
+        // Comments/Replies: always reference a parent resource
+        pattern: /^(Comment|Reply|Response|Note|Annotation|Feedback|Review|Remark)$/i,
+        kind: "mutable_resource",
+        protocols: ["ownership_check", "input_validation", "data_integrity", "authorization"],
+    },
+    {
+        // Credential material
+        pattern: /^(Password|Token|Key|Secret|Credential|ApiKey|AccessKey|Certificate)$/i,
+        kind: "credential",
+        protocols: ["password_hashing", "token_security", "secure_storage"],
+    },
+    {
+        // File assets
+        pattern: /^(File|Attachment|Image|Photo|Video|Audio|Document|Media|Asset|Binary|Blob|Upload|Download)$/i,
+        kind: "file_asset",
+        protocols: ["file_validation", "ownership_check", "authorization"],
+    },
+    {
+        // Reference data
+        pattern: /^(Category|Tag|Label|Status|Type|State|Priority|Severity|Role|Permission|Group|Team|Organization)$/i,
+        kind: "reference_data",
+        protocols: ["authorization"],
+    },
+    {
+        // Session/connection
+        pattern: /^(Session|Connection|Stream|Channel|Socket|WebSocket|SSE)$/i,
+        kind: "session",
+        protocols: ["tls_enforcement", "token_verification"],
+    },
+];
+// ═══════════════════════════════════════════════════════════════
+// Core Engine
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Parse a function name into verb + entity.
+ *
+ * Examples:
+ *   createPost       → { verb: "create", entity: "Post" }
+ *   deleteUser       → { verb: "delete", entity: "User" }
+ *   addProductItem   → { verb: "add", entity: "ProductItem" }
+ *   getNotifications → { verb: "get", entity: "Notifications" }
+ */
+function parseResourceName(functionName) {
+    // Common verb prefixes
+    const verbPatterns = [
+        "create", "delete", "update", "remove", "destroy",
+        "add", "insert", "new", "make", "build",
+        "get", "fetch", "find", "query", "read", "load", "list",
+        "edit", "modify", "change", "set", "put",
+        "login", "logout", "register", "signup", "signin",
+        "verify", "validate", "check", "authorize", "authenticate",
+        "upload", "download", "send", "receive",
+        "toggle", "lock", "unlock", "enable", "disable",
+        "follow", "unfollow", "like", "unlike",
+        "hash", "generate", "sign", "encrypt", "decrypt",
+    ];
+    for (const verb of verbPatterns) {
+        if (functionName.toLowerCase().startsWith(verb.toLowerCase())) {
+            const entity = functionName.slice(verb.length);
+            if (entity.length >= 2) {
+                return { verb: verb.toLowerCase(), entity };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Classify a resource by its entity name.
+ * Uses suffix patterns for known categories, heuristics for unknown ones.
+ */
+function classifyResource(entity) {
+    // Normalize: handle plurals, camelCase suffixes
+    const normalized = entity.replace(/s$/, ""); // Remove trailing 's' for plurals
+    // Check known patterns
+    for (const { pattern, kind, protocols } of RESOURCE_SUFFIX_PATTERNS) {
+        if (pattern.test(entity) || pattern.test(normalized)) {
+            return { kind, protocols, confidence: 0.9 };
+        }
+    }
+    // Heuristic: if the entity starts with an uppercase letter (camelCase), it's likely a resource
+    // Unknown entities default to mutable_resource with full protocol requirements
+    if (/^[A-Z]/.test(entity)) {
+        return {
+            kind: "mutable_resource",
+            protocols: ["ownership_check", "input_validation", "authorization", "data_integrity"],
+            confidence: 0.5, // Lower confidence for unknown entities
+        };
+    }
+    return { kind: "unknown", protocols: [], confidence: 0.1 };
+}
+/**
+ * Full resource abstraction pipeline:
+ *   functionName → verb + entity → resource kind → required protocols
+ */
+function abstractResource(functionName) {
+    const parsed = parseResourceName(functionName);
+    if (!parsed)
+        return null;
+    const { kind, protocols, confidence } = classifyResource(parsed.entity);
+    // Read operations on mutable resources: classify as reference_data
+    // (accessing a resource doesn't mutate it; the entity type reflects the access mode)
+    const adjustedKind = READ_VERBS.has(parsed.verb) && kind === "mutable_resource"
+        ? "reference_data"
+        : kind;
+    return {
+        original: functionName,
+        verb: parsed.verb,
+        entity: parsed.entity,
+        kind: adjustedKind,
+        requiredProtocols: protocols,
+        confidence,
+    };
+}
+/**
+ * Check if a given function name is a mutating operation on a resource.
+ * Mutations require: Ownership + Authorization + (optionally) Validation
+ */
+function isMutatingOperation(functionName) {
+    const parsed = parseResourceName(functionName);
+    if (!parsed)
+        return false;
+    return MUTABLE_VERBS.has(parsed.verb);
+}
+/**
+ * Check if a given function name is a read operation.
+ */
+function isReadOperation(functionName) {
+    const parsed = parseResourceName(functionName);
+    if (!parsed)
+        return false;
+    return READ_VERBS.has(parsed.verb);
+}
+/**
+ * Get the protocols required for a given function.
+ * Combines verb semantics with resource classification.
+ */
+function getRequiredProtocols(functionName) {
+    const abs = abstractResource(functionName);
+    if (!abs)
+        return [];
+    const protocols = [...abs.requiredProtocols];
+    // Mutating operations ALWAYS need authorization
+    if (MUTABLE_VERBS.has(abs.verb) && !protocols.includes("authorization")) {
+        protocols.push("authorization");
+    }
+    // Mutating operations on mutable resources need ownership checks
+    if (MUTABLE_VERBS.has(abs.verb) && abs.kind === "mutable_resource" && !protocols.includes("ownership_check")) {
+        protocols.push("ownership_check");
+    }
+    return protocols;
+}
+// ═══════════════════════════════════════════════════════════════
+// Lexical Generalization Test
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Test whether the resource abstraction correctly identifies
+ * that DIFFERENT entity names with the SAME semantics require
+ * the SAME protocols.
+ *
+ * Known entities: Post, Comment, Task, Order, Product → should all require ownership_check
+ * Unknown entities: Ticket, Issue, Artifact, Foo → should ALSO require ownership_check
+ */
+function testLexicalGeneralization() {
+    const knownEntities = ["Post", "Comment", "Task", "Order", "Product", "Project", "Item"];
+    const unknownEntities = ["Ticket", "Issue", "Artifact", "Document", "Foo", "Widget", "Thing"];
+    const expectedProtocol = "ownership_check";
+    let knownCorrect = 0;
+    for (const entity of knownEntities) {
+        const { protocols } = classifyResource(entity);
+        if (protocols.includes(expectedProtocol))
+            knownCorrect++;
+    }
+    let unknownCorrect = 0;
+    for (const entity of unknownEntities) {
+        const { protocols } = classifyResource(entity);
+        if (protocols.includes(expectedProtocol))
+            unknownCorrect++;
+    }
+    return {
+        knownEntities,
+        unknownEntities,
+        knownRecall: knownCorrect / knownEntities.length,
+        unknownRecall: unknownCorrect / unknownEntities.length,
+    };
+}

package/dist/resource-detector.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Resource Lifecycle Detector
+ *
+ * Focused detection of resource acquire/release violations.
+ * Replaces noisy auto-discovered call-ordering rules with
+ * explicit acquire→release pair analysis.
+ *
+ * Strategy:
+ *   1. Identify resource-acquiring calls (malloc, open, connect, SSL_new, ...)
+ *   2. Identify resource-releasing calls (free, close, disconnect, SSL_free, ...)
+ *   3. Flag violations: acquire without corresponding release in same scope
+ *   4. Exclude "allocation-return" pattern (function allocates for caller)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectResourceViolations = detectResourceViolations;
+exports.validateResourceLifecycle = validateResourceLifecycle;
+// ── Known resource pairs ──
+const RESOURCE_PAIRS = [
+    // Memory
+    { acquire: /\b(malloc|calloc|realloc|curlx_malloc|curlx_calloc|curlx_realloc|zmalloc|zcalloc|zrealloc|ngx_alloc|ngx_calloc|ngx_palloc)\b/i, release: /\b(free|curlx_free|zfree|ngx_free|ngx_pfree)\b/i, category: "memory" },
+    // File descriptors (accept removed — listening sockets stay open)
+    { acquire: /\b(open|fopen|socket|curlx_open)\b/i, release: /\b(close|fclose|closesocket|curlx_close|shutdown)\b/i, category: "file" },
+    // SSL/TLS (expanded with CTX and bio patterns)
+    { acquire: /\b(SSL_new|TLS_new|wolfSSL_new|gtls_new|BIO_new|ossl_new|nghttp2_session_new|SSL_CTX_new|BIO_new_mem_buf|BIO_s_file|BIO_read_filename)\b/i, release: /\b(SSL_free|TLS_free|wolfSSL_free|gtls_free|BIO_free|ossl_free|nghttp2_session_del|SSL_CTX_free|BIO_free_all)\b/i, category: "ssl" },
+    // Connections (accept removed — server socket, not per-connection resource)
+    { acquire: /\b(connect|Curl_connect|ngx_connect|redisConnect)\b/i, release: /\b(disconnect|Curl_disconnect|ngx_disconnect|redisFree)\b/i, category: "connection" },
+    // General lifecycle — only for double-release / UAF checks, not missing-release
+    { acquire: /\b(_init|_create|_setup|_start|_begin|_open|_alloc|_connect|init|create|setup|start|open|alloc)\b/i, release: /\b(_free|_destroy|_cleanup|_close|_stop|_end|_release|_unlock|_done|_finish|_remove|_delete|cleanup|destroy|close|free)\b/i, category: "lifecycle" },
+    // C error-handling: goto cleanup/fail pattern (synthetic calls from sequence-extractor)
+    { acquire: /\b(goto_cleanup|goto_fail|goto_err|goto_error|goto_out)\b/i, release: /\b(_free|_destroy|_cleanup|_close|_release|free|destroy|cleanup|close)\b/i, category: "lifecycle" },
+    // Python resource pairs
+    { acquire: /\b(sqlite3\.connect|psycopg2\.connect|create_engine|pymongo\.MongoClient|redis\.Redis|redis\.StrictRedis)\b/i, release: /\b(close|disconnect)\b/i, category: "connection" },
+    { acquire: /\b(socket\.socket|socket\.create_connection|socket\.socketpair)\b/i, release: /\b(close)\b/i, category: "file" },
+    { acquire: /\b(asyncio\.(Lock|Semaphore|Event|Condition)|threading\.(Lock|RLock|Semaphore|Condition))\b/i, release: /\b(release)\b/i, category: "lock" },
+    { acquire: /\b(tempfile\.(TemporaryFile|NamedTemporaryFile|mkstemp|mkdtemp|SpooledTemporaryFile))\b/i, release: /\b(close|cleanup)\b/i, category: "file" },
+];
+// ── Allocation-return patterns (functions that allocate and return to caller) ──
+const ALLOCATOR_PATTERNS = [
+    /\b(create|alloc|new|init|open|dup|clone|copy|build|make|setup|construct)\w*\b/i,
+];
+// ── Cleanup/destructor functions (expected to call release without acquire) ──
+const CLEANUP_PATTERNS = [
+    /\b(remove|cleanup|destroy|free|close|delete|detach|release|shutdown|teardown|done|finish)\w*\b/i,
+    // Curl-specific cleanup functions (cross-function alloc/free patterns)
+    /\b(Curl_close|curl_multi_cleanup|Curl_detach_connection|curl_easy_cleanup|Curl_expire_clear|Curl_resolv_destroy_all|Curl_conncache_remove|Curl_ssl_close_all|Curl_req_free)\b/i,
+];
+function isAllocatorFunction(funcName) {
+    return ALLOCATOR_PATTERNS.some(p => p.test(funcName));
+}
+function isCleanupFunction(funcName) {
+    return CLEANUP_PATTERNS.some(p => p.test(funcName));
+}
+function detectResourceViolations(calls, enclosingFuncName) {
+    const violations = [];
+    const funcName = enclosingFuncName || "";
+    for (const pair of RESOURCE_PAIRS) {
+        const acquires = [];
+        const releases = [];
+        for (let i = 0; i < calls.length; i++) {
+            const c = calls[i];
+            if (pair.acquire.test(c) && !isAllocatorFunction(c))
+                acquires.push(i);
+            if (pair.release.test(c))
+                releases.push(i);
+        }
+        // Rule 1: more acquires than releases → potential leak
+        // Exception: allocator functions (return resource to caller)
+        // Exception: cleanup functions (release resources allocated elsewhere)
+        // Exception: lifecycle category (too broad for missing-release check)
+        if (acquires.length > releases.length && acquires.length > 0 && pair.category !== "lifecycle") {
+            if (!isAllocatorFunction(funcName) && !isCleanupFunction(funcName)) {
+                for (let i = releases.length; i < acquires.length; i++) {
+                    violations.push({
+                        type: "missing_release",
+                        category: pair.category,
+                        acquireCall: calls[acquires[i]],
+                        detail: `${calls[acquires[i]]} acquired without matching ${pair.release.source} — possible resource leak`,
+                    });
+                }
+            }
+        }
+        // Rule 2: release without acquire → only flag if 2+ releases (true double-free)
+        // Single release without acquire = cross-function cleanup (normal in C code)
+        // Exception: cleanup/destructor functions always exempt
+        if (releases.length >= 2 && acquires.length === 0) {
+            if (!isCleanupFunction(funcName)) {
+                violations.push({
+                    type: "double_free",
+                    category: pair.category,
+                    releaseCall: calls[releases[0]],
+                    detail: `${calls[releases[0]]} → ${calls[releases[releases.length - 1]]}: multiple releases without any acquire — possible double-free`,
+                });
+            }
+        }
+        // Rule 3: release before corresponding acquire (interleaved)
+        if (acquires.length > 0 && releases.length > 0) {
+            for (const ri of releases) {
+                // A release at position ri must have at least one acquire before it
+                const hasPriorAcquire = acquires.some(ai => ai < ri);
+                if (!hasPriorAcquire) {
+                    violations.push({
+                        type: "use_after_release",
+                        category: pair.category,
+                        releaseCall: calls[ri],
+                        detail: `${calls[ri]} called before any ${pair.acquire.source} — possible double-free`,
+                    });
+                }
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Validate a call sequence using resource lifecycle analysis.
+ * Returns valid=true if no resource violations found.
+ */
+function validateResourceLifecycle(calls, enclosingFuncName) {
+    const violations = detectResourceViolations(calls, enclosingFuncName);
+    const missingCount = violations.filter(v => v.type === "missing_release").length;
+    const otherCount = violations.length - missingCount;
+    let detail = "";
+    if (violations.length === 0) {
+        detail = "Resource lifecycle clean";
+    }
+    else {
+        const parts = [];
+        if (missingCount > 0)
+            parts.push(`${missingCount} potential resource leak(s)`);
+        if (otherCount > 0)
+            parts.push(`${otherCount} ordering violation(s)`);
+        detail = parts.join(", ");
+    }
+    return {
+        valid: violations.length === 0,
+        violations,
+        detail,
+    };
+}
+// ═══════════════════════════════════════════════════════════════
+// CLI — Precision Report
+// ═══════════════════════════════════════════════════════════════
+if (require.main === module) {
+    const fs = require("fs");
+    const path = require("path");
+    const args = process.argv.slice(2);
+    const repoPath = path.resolve(args.find(a => !a.startsWith("--")) || ".");
+    const baseDir = path.dirname(repoPath);
+    const repoName = path.basename(repoPath);
+    const seqFile = path.join(baseDir, `${repoName}-sequences.json`);
+    const labelFile = path.join(baseDir, `${repoName}-labels.json`);
+    if (!fs.existsSync(seqFile) || !fs.existsSync(labelFile)) {
+        console.error(`❌ Files not found: ${seqFile}, ${labelFile}`);
+        process.exit(1);
+    }
+    const seqData = JSON.parse(fs.readFileSync(seqFile, "utf-8"));
+    const labelData = JSON.parse(fs.readFileSync(labelFile, "utf-8"));
+    const sequences = seqData.sequences || seqData;
+    const labels = labelData.labels || labelData;
+    let tp = 0, fp = 0, tn = 0, fn = 0;
+    const mismatches = [];
+    for (const seq of sequences) {
+        const idx = sequences.indexOf(seq);
+        const expected = labels[idx];
+        if (!expected || expected === "s" || expected === "skip")
+            continue;
+        const result = validateResourceLifecycle(seq.calls || [], seq.function);
+        const detected = result.valid ? "clean" : "violation";
+        if (expected === "clean" && detected === "clean")
+            tn++;
+        else if (expected === "violation" && detected === "violation")
+            tp++;
+        else if (expected === "clean" && detected === "violation")
+            fp++;
+        else if (expected === "violation" && detected === "clean")
+            fn++;
+        if (expected !== detected || result.violations.length > 0) {
+            mismatches.push({ idx, fn: seq.function, expected, detected, calls: (seq.calls || []).slice(0, 5), vios: result.violations.map(v => v.detail) });
+        }
+    }
+    const total = tp + fp + tn + fn;
+    const precision = tp + fp > 0 ? tp / (tp + fp) : 0;
+    const recall = tp + fn > 0 ? tp / (tp + fn) : 0;
+    const f1 = precision + recall > 0 ? 2 * precision * recall / (precision + recall) : 0;
+    const pct = (v) => `${(v * 100).toFixed(0)}%`;
+    const C = { reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m", green: "\x1b[32m", red: "\x1b[31m", yellow: "\x1b[33m", cyan: "\x1b[36m" };
+    const color = (v) => v >= 0.7 ? C.green : v >= 0.5 ? C.yellow : C.red;
+    console.log(`\n${C.bold}${C.cyan}╔══════════════════════════════════════════════╗${C.reset}`);
+    console.log(`${C.bold}${C.cyan}║${C.reset}  ${C.bold}Resource Lifecycle Precision — ${repoName}${C.reset}${" ".repeat(Math.max(0, 19 - repoName.length))}${C.bold}${C.cyan}║${C.reset}`);
+    console.log(`${C.bold}${C.cyan}╚══════════════════════════════════════════════╝${C.reset}`);
+    console.log("");
+    console.log(`  Samples:    ${total}`);
+    console.log(`  TP: ${C.green}${tp}${C.reset}  FP: ${C.red}${fp}${C.reset}  TN: ${C.green}${tn}${C.reset}  FN: ${C.red}${fn}${C.reset}`);
+    console.log("");
+    console.log(`  Precision:  ${color(precision)}${pct(precision)}${C.reset}`);
+    console.log(`  Recall:     ${color(recall)}${pct(recall)}${C.reset}`);
+    console.log(`  F1:         ${color(f1)}${pct(f1)}${C.reset}`);
+    console.log("");
+    if (mismatches.length > 0) {
+        console.log(`  ${C.yellow}Details:${C.reset}`);
+        for (const m of mismatches.slice(0, 12)) {
+            const icon = m.expected === "violation" ? `${C.red}FN${C.reset}` : `${C.yellow}FP${C.reset}`;
+            console.log(`    ${icon} [${m.idx}] ${m.expected}→${m.detected}  ${(m.calls || []).join(" → ")}`);
+            if (m.vios.length)
+                console.log(`       ${C.dim}${m.vios[0]}${C.reset}`);
+        }
+    }
+    console.log("");
+    const rating = f1 >= 0.7 ? `${C.green}GOOD${C.reset}` : f1 >= 0.5 ? `${C.yellow}FAIR${C.reset}` : `${C.red}NEEDS IMPROVEMENT${C.reset}`;
+    console.log(`  Rating: ${rating}\n`);
+}

package/dist/result.test.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Unit tests for the Result<T,E> type and factory functions.
+ */
+const vitest_1 = require("vitest");
+const runtime_types_1 = require("./runtime-types");
+(0, vitest_1.describe)("Result type", () => {
+    (0, vitest_1.it)("ok() returns { ok: true, value }", () => {
+        const r = (0, runtime_types_1.ok)(42);
+        (0, vitest_1.expect)(r.ok).toBe(true);
+        if (r.ok)
+            (0, vitest_1.expect)(r.value).toBe(42);
+    });
+    (0, vitest_1.it)("err() returns { ok: false, error }", () => {
+        const r = (0, runtime_types_1.err)("something broke");
+        (0, vitest_1.expect)(r.ok).toBe(false);
+        if (!r.ok)
+            (0, vitest_1.expect)(r.error).toBe("something broke");
+    });
+    (0, vitest_1.it)("supports discriminated union narrowing", () => {
+        function divide(a, b) {
+            if (b === 0)
+                return (0, runtime_types_1.err)("division by zero");
+            return (0, runtime_types_1.ok)(a / b);
+        }
+        const good = divide(10, 2);
+        if (good.ok)
+            (0, vitest_1.expect)(good.value).toBe(5);
+        const bad = divide(1, 0);
+        if (!bad.ok)
+            (0, vitest_1.expect)(bad.error).toBe("division by zero");
+    });
+    (0, vitest_1.it)("supports typed ValidationError", () => {
+        const e = { message: "type mismatch", code: "SVL-2", index: 3 };
+        const r = (0, runtime_types_1.err)([e]);
+        (0, vitest_1.expect)(r.ok).toBe(false);
+        if (!r.ok) {
+            (0, vitest_1.expect)(r.error[0].code).toBe("SVL-2");
+            (0, vitest_1.expect)(r.error[0].index).toBe(3);
+        }
+    });
+});