@greenarmor/ges-inference-engine 1.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025–2026 greenarmor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/analyzers/finding-clusterer.d.ts

@@ -0,0 +1,10 @@
+import type { InferenceFinding, ClusteringResult } from "../types.js";
+/**
+ * Cluster findings using cosine similarity on n-gram token vectors.
+ * Two findings are in the same cluster if they share the same ruleId,
+ * or if their text similarity exceeds the threshold.
+ *
+ * Uses a greedy union-join approach: iterate findings, assign to the first
+ * sufficiently similar existing cluster, or create a new one.
+ */
+export declare function clusterFindings(findings: InferenceFinding[]): ClusteringResult;

package/dist/analyzers/finding-clusterer.js

@@ -0,0 +1,165 @@
+const SEVERITY_RANK = {
+    critical: 4,
+    high: 3,
+    medium: 2,
+    low: 1,
+};
+/**
+ * Tokenize a string into normalized n-gram tokens.
+ * Lowercase, strip non-alphanumeric, split on whitespace, then generate 2-grams + 3-grams.
+ */
+function tokenize(text) {
+    const cleaned = text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").trim();
+    if (!cleaned)
+        return [];
+    const words = cleaned.split(/\s+/).filter((w) => w.length > 1);
+    const tokens = [...words];
+    for (let i = 0; i < words.length - 1; i++) {
+        tokens.push(`${words[i]} ${words[i + 1]}`);
+    }
+    for (let i = 0; i < words.length - 2; i++) {
+        tokens.push(`${words[i]} ${words[i + 1]} ${words[i + 2]}`);
+    }
+    return tokens;
+}
+/**
+ * Build a term-frequency map from a set of tokens.
+ */
+function termFrequency(tokens) {
+    const tf = new Map();
+    for (const t of tokens) {
+        tf.set(t, (tf.get(t) ?? 0) + 1);
+    }
+    return tf;
+}
+/**
+ * Compute cosine similarity between two term-frequency vectors.
+ */
+function cosineSimilarity(tfA, tfB) {
+    let dotProduct = 0;
+    let magA = 0;
+    let magB = 0;
+    const keys = new Set([...tfA.keys(), ...tfB.keys()]);
+    for (const key of keys) {
+        const a = tfA.get(key) ?? 0;
+        const b = tfB.get(key) ?? 0;
+        dotProduct += a * b;
+        magA += a * a;
+        magB += b * b;
+    }
+    if (magA === 0 || magB === 0)
+        return 0;
+    return dotProduct / (Math.sqrt(magA) * Math.sqrt(magB));
+}
+const SIMILARITY_THRESHOLD = 0.55;
+/**
+ * Cluster findings using cosine similarity on n-gram token vectors.
+ * Two findings are in the same cluster if they share the same ruleId,
+ * or if their text similarity exceeds the threshold.
+ *
+ * Uses a greedy union-join approach: iterate findings, assign to the first
+ * sufficiently similar existing cluster, or create a new one.
+ */
+export function clusterFindings(findings) {
+    if (findings.length === 0) {
+        return {
+            totalFindings: 0,
+            clusterCount: 0,
+            clusters: [],
+            reductionRatio: 0,
+        };
+    }
+    // Pre-compute term-frequency vectors for each finding
+    const tfVectors = findings.map((f) => {
+        const combinedText = `${f.ruleId} ${f.category} ${f.title} ${f.description} ${f.evidence}`;
+        return termFrequency(tokenize(combinedText));
+    });
+    // Union-Find data structure
+    const parent = findings.map((_, i) => i);
+    function find(x) {
+        while (parent[x] !== x) {
+            parent[x] = parent[parent[x]];
+            x = parent[x];
+        }
+        return x;
+    }
+    function union(x, y) {
+        const px = find(x);
+        const py = find(y);
+        if (px !== py)
+            parent[py] = px;
+    }
+    // Compare all pairs — O(n²) but finding counts in GESF are typically < 500
+    for (let i = 0; i < findings.length; i++) {
+        for (let j = i + 1; j < findings.length; j++) {
+            if (find(i) === find(j))
+                continue;
+            // Same ruleId → always cluster together
+            if (findings[i].ruleId === findings[j].ruleId) {
+                union(i, j);
+                continue;
+            }
+            const similarity = cosineSimilarity(tfVectors[i], tfVectors[j]);
+            if (similarity >= SIMILARITY_THRESHOLD) {
+                union(i, j);
+            }
+        }
+    }
+    // Group findings by cluster root
+    const clusterMap = new Map();
+    for (let i = 0; i < findings.length; i++) {
+        const root = find(i);
+        if (!clusterMap.has(root))
+            clusterMap.set(root, []);
+        clusterMap.get(root).push(i);
+    }
+    // Build cluster objects
+    const clusters = [];
+    let clusterIdx = 0;
+    for (const [root, indices] of clusterMap) {
+        const memberFindings = indices.map((i) => findings[i]);
+        // Pick the highest-severity finding as representative
+        const representativeIdx = indices.reduce((best, current) => {
+            const bestSev = SEVERITY_RANK[findings[best].severity] ?? 0;
+            const curSev = SEVERITY_RANK[findings[current].severity] ?? 0;
+            return curSev > bestSev ? current : best;
+        }, indices[0]);
+        const representative = findings[representativeIdx];
+        // Aggregate unique files
+        const fileSet = new Set(memberFindings.map((f) => f.file));
+        // Determine cluster severity (max of members)
+        const maxSeverity = memberFindings.reduce((max, f) => {
+            return (SEVERITY_RANK[f.severity] ?? 0) > (SEVERITY_RANK[max] ?? 0) ? f.severity : max;
+        }, memberFindings[0].severity);
+        // Generate a pattern description from the most common ruleId
+        const ruleIdCounts = new Map();
+        for (const f of memberFindings) {
+            ruleIdCounts.set(f.ruleId, (ruleIdCounts.get(f.ruleId) ?? 0) + 1);
+        }
+        const dominantRuleId = [...ruleIdCounts.entries()].sort((a, b) => b[1] - a[1])[0][0];
+        clusters.push({
+            clusterId: `CLUSTER-${String(clusterIdx + 1).padStart(3, "0")}`,
+            pattern: dominantRuleId,
+            ruleId: dominantRuleId,
+            category: representative.category,
+            severity: maxSeverity,
+            findingCount: indices.length,
+            files: [...fileSet].sort(),
+            representativeTitle: representative.title,
+            representativeFix: representative.fix,
+            findingIndices: indices,
+        });
+        clusterIdx++;
+    }
+    // Sort clusters by finding count descending
+    clusters.sort((a, b) => b.findingCount - a.findingCount);
+    const reductionRatio = findings.length > 0
+        ? (1 - clusters.length / findings.length) * 100
+        : 0;
+    return {
+        totalFindings: findings.length,
+        clusterCount: clusters.length,
+        clusters,
+        reductionRatio: Math.round(reductionRatio * 10) / 10,
+    };
+}

package/dist/analyzers/root-cause.d.ts

@@ -0,0 +1,13 @@
+import type { InferenceFinding, RootCauseResult } from "../types.js";
+/**
+ * Root Cause Analysis via bipartite graph (findings ↔ files ↔ controls).
+ *
+ * Builds a bipartite graph: findings connect to files, findings connect to controls.
+ * Computes each file/control node's:
+ *   - severityScore: weighted sum of connected finding severities
+ *   - betweenness: fraction of all findings this node is connected to (simplified)
+ *   - connectedFindings: which findings touch this node
+ *
+ * The "root cause" is the file or control with the highest severityScore × betweenness.
+ */
+export declare function analyzeRootCause(findings: InferenceFinding[]): RootCauseResult;

package/dist/analyzers/root-cause.js

@@ -0,0 +1,131 @@
+const SEVERITY_WEIGHT = {
+    critical: 40,
+    high: 20,
+    medium: 8,
+    low: 2,
+};
+/**
+ * Root Cause Analysis via bipartite graph (findings ↔ files ↔ controls).
+ *
+ * Builds a bipartite graph: findings connect to files, findings connect to controls.
+ * Computes each file/control node's:
+ *   - severityScore: weighted sum of connected finding severities
+ *   - betweenness: fraction of all findings this node is connected to (simplified)
+ *   - connectedFindings: which findings touch this node
+ *
+ * The "root cause" is the file or control with the highest severityScore × betweenness.
+ */
+export function analyzeRootCause(findings) {
+    if (findings.length === 0) {
+        return {
+            nodes: [],
+            topCause: null,
+            summary: "No findings to analyze.",
+            totalFindingsTraced: 0,
+            maxSeverityScore: 0,
+        };
+    }
+    // Build adjacency: file → finding indices, control → finding indices
+    const fileToFindings = new Map();
+    const controlToFindings = new Map();
+    for (let i = 0; i < findings.length; i++) {
+        const f = findings[i];
+        // File mapping
+        if (!fileToFindings.has(f.file))
+            fileToFindings.set(f.file, []);
+        fileToFindings.get(f.file).push(i);
+        // Control mapping
+        for (const cid of f.controlIds) {
+            if (!controlToFindings.has(cid))
+                controlToFindings.set(cid, []);
+            controlToFindings.get(cid).push(i);
+        }
+    }
+    // Collect unique frameworks
+    const frameworkSet = new Set();
+    // Build nodes for files
+    const fileNodes = [];
+    for (const [file, findIndices] of fileToFindings) {
+        const severityScore = findIndices.reduce((sum, idx) => {
+            return sum + (SEVERITY_WEIGHT[findings[idx].severity] ?? 1);
+        }, 0);
+        const frameworks = new Set();
+        for (const idx of findIndices) {
+            for (const cid of findings[idx].controlIds) {
+                const prefix = cid.split("-")[0];
+                if (prefix)
+                    frameworks.add(prefix);
+            }
+        }
+        const node = {
+            type: "file",
+            identifier: file,
+            connectedFindings: findIndices,
+            severityScore,
+            betweenness: findIndices.length / findings.length,
+            frameworks: [...frameworks].sort(),
+        };
+        fileNodes.push(node);
+        for (const fw of frameworks)
+            frameworkSet.add(fw);
+    }
+    // Build framework name mapping from known prefixes
+    const prefixMap = {
+        GDPR: "GDPR",
+        OWASP: "OWASP",
+        CIS: "CIS",
+        NIST: "NIST",
+        GOVP: "GDPR",
+        AI: "GDPR",
+        GOV: "GDPR",
+        SOC2: "SOC2",
+        HIPAA: "HIPAA",
+        PCI: "PCI-DSS",
+        ISO: "ISO27001",
+    };
+    // Build nodes for controls
+    const controlNodes = [];
+    for (const [control, findIndices] of controlToFindings) {
+        const severityScore = findIndices.reduce((sum, idx) => {
+            return sum + (SEVERITY_WEIGHT[findings[idx].severity] ?? 1);
+        }, 0);
+        const prefix = control.split("-")[0];
+        const framework = prefixMap[prefix] ?? prefix;
+        const node = {
+            type: "control",
+            identifier: control,
+            connectedFindings: findIndices,
+            severityScore,
+            betweenness: findIndices.length / findings.length,
+            frameworks: [framework],
+        };
+        controlNodes.push(node);
+        frameworkSet.add(framework);
+    }
+    // Combine and sort by severityScore × betweenness (composite impact)
+    const allNodes = [...fileNodes, ...controlNodes].sort((a, b) => {
+        const scoreA = a.severityScore * a.betweenness;
+        const scoreB = b.severityScore * b.betweenness;
+        return scoreB - scoreA;
+    });
+    const topCause = allNodes.length > 0 ? allNodes[0] : null;
+    const maxSeverityScore = allNodes.length > 0
+        ? Math.max(...allNodes.map((n) => n.severityScore))
+        : 0;
+    let summary;
+    if (topCause) {
+        const pct = Math.round(topCause.betweenness * 100);
+        const nodeLabel = topCause.type === "file" ? "file" : "control";
+        summary = `${topCause.identifier} is the primary root cause, connected to ${topCause.connectedFindings.length} of ${findings.length} findings (${pct}%).`;
+    }
+    else {
+        summary = "No root cause identified.";
+    }
+    return {
+        nodes: allNodes,
+        topCause,
+        summary,
+        totalFindingsTraced: findings.length,
+        maxSeverityScore,
+    };
+}

package/dist/analyzers/score-anomaly.d.ts

@@ -0,0 +1,11 @@
+import type { ScoreDataPoint, ScoreAnomalyResult, ActivityEntry } from "../types.js";
+/**
+ * Score anomaly detection using z-score analysis on score deltas.
+ *
+ * Takes a history of score data points and detects which frameworks
+ * experienced statistically significant score changes (|z-score| > 1.5).
+ *
+ * Also correlates anomalies with recent activity log entries to identify
+ * triggering events (e.g., policy install, audit, fix).
+ */
+export declare function detectScoreAnomalies(scoreHistory: ScoreDataPoint[], activityLog: ActivityEntry[]): ScoreAnomalyResult;

package/dist/analyzers/score-anomaly.js

@@ -0,0 +1,136 @@
+/**
+ * Score anomaly detection using z-score analysis on score deltas.
+ *
+ * Takes a history of score data points and detects which frameworks
+ * experienced statistically significant score changes (|z-score| > 1.5).
+ *
+ * Also correlates anomalies with recent activity log entries to identify
+ * triggering events (e.g., policy install, audit, fix).
+ */
+export function detectScoreAnomalies(scoreHistory, activityLog) {
+    if (scoreHistory.length < 2) {
+        return {
+            anomalies: [],
+            hasAnomalies: false,
+            averageScore: scoreHistory.length > 0 ? scoreHistory[0].overall : 0,
+            standardDeviation: 0,
+            dataPointCount: scoreHistory.length,
+        };
+    }
+    // Collect all framework keys across all data points
+    const frameworkKeys = new Set();
+    for (const dp of scoreHistory) {
+        for (const fw of Object.keys(dp.frameworks)) {
+            frameworkKeys.add(fw);
+        }
+    }
+    // For each framework, compute deltas and z-scores
+    const anomalies = [];
+    const allDeltas = [];
+    for (const fw of frameworkKeys) {
+        const fwScores = scoreHistory
+            .map((dp) => dp.frameworks[fw])
+            .filter((s) => s !== undefined)
+            .map((s) => s.score);
+        if (fwScores.length < 2)
+            continue;
+        // Compute deltas between consecutive data points
+        const deltas = [];
+        for (let i = 1; i < fwScores.length; i++) {
+            deltas.push(fwScores[i] - fwScores[i - 1]);
+        }
+        if (deltas.length === 0)
+            continue;
+        // Mean and standard deviation of deltas
+        const mean = deltas.reduce((sum, d) => sum + d, 0) / deltas.length;
+        const variance = deltas.reduce((sum, d) => sum + (d - mean) ** 2, 0) / deltas.length;
+        const stdDev = Math.sqrt(variance);
+        for (const d of deltas) {
+            allDeltas.push(d);
+        }
+        // Check the most recent delta for anomaly
+        const latestDelta = deltas[deltas.length - 1];
+        const prevScore = fwScores[fwScores.length - 2];
+        const currScore = fwScores[fwScores.length - 1];
+        // z-score: avoid division by zero; with only 1 delta (2 data points), flag by magnitude alone
+        const zScore = stdDev > 0 ? Math.abs(latestDelta - mean) / stdDev : (Math.abs(latestDelta) > 10 ? 3 : 0);
+        const isAnomalous = zScore > 1.5 && Math.abs(latestDelta) > 5; // z > 1.5 AND meaningful change > 5%
+        // Try to find a triggering event near the time of the latest score point
+        const latestTimestamp = scoreHistory[scoreHistory.length - 1].evaluatedAt;
+        const triggeringEvent = findTriggeringEvent(activityLog, latestTimestamp, fw);
+        let description;
+        if (isAnomalous) {
+            const direction = latestDelta < 0 ? "dropped" : "increased";
+            const magnitude = Math.abs(latestDelta).toFixed(1);
+            description = `${fw} score ${direction} by ${magnitude}% (from ${prevScore.toFixed(0)}% to ${currScore.toFixed(0)}%), z-score: ${zScore.toFixed(2)}.`;
+            if (triggeringEvent) {
+                description += ` Triggered by: ${triggeringEvent}.`;
+            }
+        }
+        else {
+            description = `${fw} score change of ${latestDelta.toFixed(1)}% is within normal range (z-score: ${zScore.toFixed(2)}).`;
+        }
+        anomalies.push({
+            framework: fw,
+            delta: Math.round(latestDelta * 10) / 10,
+            previousScore: prevScore,
+            currentScore: currScore,
+            zScore: Math.round(zScore * 100) / 100,
+            isAnomalous,
+            evaluatedAt: latestTimestamp,
+            triggeringEvent,
+            description,
+        });
+    }
+    // Compute overall statistics
+    const overallMean = allDeltas.length > 0
+        ? allDeltas.reduce((sum, d) => sum + d, 0) / allDeltas.length
+        : 0;
+    const overallVar = allDeltas.length > 0
+        ? allDeltas.reduce((sum, d) => sum + (d - overallMean) ** 2, 0) / allDeltas.length
+        : 0;
+    const overallStdDev = Math.sqrt(overallVar);
+    return {
+        anomalies: anomalies.sort((a, b) => b.zScore - a.zScore),
+        hasAnomalies: anomalies.some((a) => a.isAnomalous),
+        averageScore: Math.round(overallMean * 10) / 10,
+        standardDeviation: Math.round(overallStdDev * 10) / 10,
+        dataPointCount: scoreHistory.length,
+    };
+}
+/**
+ * Find a triggering activity log entry near the given timestamp.
+ */
+function findTriggeringEvent(activityLog, targetTimestamp, framework) {
+    const target = new Date(targetTimestamp).getTime();
+    // Look for activity entries within 12 hours before the score drop
+    const window = 12 * 60 * 60 * 1000; // 12 hours
+    const candidates = activityLog
+        .filter((entry) => {
+        const entryTime = new Date(entry.timestamp).getTime();
+        return entryTime >= target - window && entryTime <= target;
+    })
+        .sort((a, b) => {
+        return new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime();
+    });
+    for (const entry of candidates) {
+        const actionMap = {
+            audit: "Audit completed",
+            fix: "Auto-fix applied",
+            policy_install: "Policy pack installed",
+            policy_remove: "Policy pack removed",
+            control_override: "Control override applied",
+            score: "Score evaluation",
+        };
+        const label = actionMap[entry.action] ?? entry.action;
+        if (entry.action === "audit" || entry.action === "score") {
+            return `${label}: ${entry.title}`;
+        }
+        // For policy installs, check if it affects this framework
+        const fwAdded = entry.details?.frameworks_added;
+        if (fwAdded?.some((fw) => fw.toUpperCase() === framework.toUpperCase())) {
+            return `${label}: ${entry.title}`;
+        }
+    }
+    return null;
+}

package/dist/analyzers/trend-predictor.d.ts

@@ -0,0 +1,12 @@
+import type { ScoreDataPoint, TrendPredictionResult } from "../types.js";
+/**
+ * Trend prediction via simple linear regression on score-over-time.
+ *
+ * For each framework (and overall), computes:
+ *   - slope: rate of score change per data point
+ *   - rSquared: fit quality
+ *   - projected score: current + slope (one step ahead)
+ *   - cyclesToThreshold: how many data points until crossing the 80% threshold
+ *   - trendDirection: improving, declining, or stable
+ */
+export declare function predictTrends(scoreHistory: ScoreDataPoint[]): TrendPredictionResult;

package/dist/analyzers/trend-predictor.js

@@ -0,0 +1,134 @@
+const DEFAULT_THRESHOLD = 80;
+/**
+ * Trend prediction via simple linear regression on score-over-time.
+ *
+ * For each framework (and overall), computes:
+ *   - slope: rate of score change per data point
+ *   - rSquared: fit quality
+ *   - projected score: current + slope (one step ahead)
+ *   - cyclesToThreshold: how many data points until crossing the 80% threshold
+ *   - trendDirection: improving, declining, or stable
+ */
+export function predictTrends(scoreHistory) {
+    if (scoreHistory.length < 2) {
+        return {
+            predictions: [],
+            overall: null,
+            dataPointCount: scoreHistory.length,
+        };
+    }
+    // Extract overall score series
+    const overallScores = scoreHistory.map((dp) => dp.overall);
+    const overallPrediction = computePrediction("overall", overallScores);
+    // Collect all framework keys
+    const frameworkKeys = new Set();
+    for (const dp of scoreHistory) {
+        for (const fw of Object.keys(dp.frameworks)) {
+            frameworkKeys.add(fw);
+        }
+    }
+    // Compute predictions per framework
+    const predictions = [];
+    for (const fw of frameworkKeys) {
+        const fwScores = scoreHistory
+            .map((dp) => dp.frameworks[fw])
+            .filter((s) => s !== undefined)
+            .map((s) => s.score);
+        if (fwScores.length < 2)
+            continue;
+        const prediction = computePrediction(fw, fwScores);
+        predictions.push(prediction);
+    }
+    return {
+        predictions: predictions.sort((a, b) => b.rSquared - a.rSquared),
+        overall: overallPrediction,
+        dataPointCount: scoreHistory.length,
+    };
+}
+function computePrediction(name, scores) {
+    const n = scores.length;
+    // Linear regression: y = slope * x + intercept
+    const xValues = scores.map((_, i) => i); // 0, 1, 2, ... (time steps)
+    const yValues = scores;
+    let sumX = 0, sumY = 0, sumXY = 0, sumX2 = 0, sumY2 = 0;
+    for (let i = 0; i < n; i++) {
+        sumX += xValues[i];
+        sumY += yValues[i];
+        sumXY += xValues[i] * yValues[i];
+        sumX2 += xValues[i] * xValues[i];
+        sumY2 += yValues[i] * yValues[i];
+    }
+    const denominator = n * sumX2 - sumX * sumX;
+    let slope;
+    let intercept;
+    if (denominator === 0) {
+        // All x values are the same (shouldn't happen with 0,1,2...)
+        slope = 0;
+        intercept = sumY / n;
+    }
+    else {
+        slope = (n * sumXY - sumX * sumY) / denominator;
+        intercept = (sumY * sumX2 - sumX * sumXY) / denominator;
+    }
+    // R-squared
+    const meanY = sumY / n;
+    let ssTot = 0, ssRes = 0;
+    for (let i = 0; i < n; i++) {
+        const predicted = slope * xValues[i] + intercept;
+        ssTot += (yValues[i] - meanY) ** 2;
+        ssRes += (yValues[i] - predicted) ** 2;
+    }
+    const rSquared = ssTot > 0 ? 1 - ssRes / ssTot : 0;
+    // Projected score (one step ahead)
+    const currentScore = yValues[n - 1];
+    const projectedScore = slope * n + intercept;
+    // Cycles to threshold
+    let cyclesToThreshold = null;
+    if (slope !== 0) {
+        // Solve: slope * t + intercept = threshold
+        const stepsToCross = (DEFAULT_THRESHOLD - intercept) / slope;
+        // t is relative to x=0, current position is at x=n-1
+        const stepsRemaining = stepsToCross - (n - 1);
+        if (stepsRemaining > 0 && stepsRemaining < 1000) {
+            cyclesToThreshold = Math.round(stepsRemaining);
+        }
+    }
+    else if (currentScore < DEFAULT_THRESHOLD) {
+        // flat below threshold — already there
+        cyclesToThreshold = 0;
+    }
+    // Trend direction
+    let trendDirection;
+    if (Math.abs(slope) < 1) {
+        trendDirection = "stable";
+    }
+    else if (slope > 0) {
+        trendDirection = "improving";
+    }
+    else {
+        trendDirection = "declining";
+    }
+    // Description
+    let description;
+    const directionWord = slope > 0 ? "improving" : slope < 0 ? "declining" : "holding steady";
+    const absRate = Math.abs(slope).toFixed(1);
+    const quality = rSquared > 0.7 ? "strong" : rSquared > 0.4 ? "moderate" : "weak";
+    if (name === "overall") {
+        description = `Overall score is ${directionWord} at ${absRate}% per audit cycle (${quality} fit, R²=${rSquared.toFixed(2)}).`;
+    }
+    else {
+        description = `${name} is ${directionWord} at ${absRate}% per audit cycle (${quality} fit, R²=${rSquared.toFixed(2)}).`;
+    }
+    return {
+        framework: name,
+        slope: Math.round(slope * 100) / 100,
+        intercept: Math.round(intercept * 100) / 100,
+        rSquared: Math.round(rSquared * 1000) / 1000,
+        currentScore: Math.round(currentScore * 10) / 10,
+        projectedScore: Math.round(projectedScore * 10) / 10,
+        cyclesToThreshold,
+        threshold: DEFAULT_THRESHOLD,
+        trendDirection,
+        description,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { InferenceInput, InferenceReport, InferenceSummary, ScoreDataPoint, ActivityEntry, InferenceFinding } from "./types.js";
+export type { InferenceInput, InferenceReport, InferenceSummary, ScoreDataPoint, ActivityEntry, InferenceFinding };
+export type { FindingCluster, ClusteringResult, RootCauseNode, RootCauseResult, ScoreAnomaly, ScoreAnomalyResult, TrendPrediction, TrendPredictionResult } from "./types.js";
+/**
+ * Load all inference input data from a project's .ges/ directory.
+ */
+export declare function loadInferenceInput(projectPath: string): InferenceInput;
+/**
+ * Run the full inference pipeline on a project.
+ */
+export declare function runInference(projectPath: string): InferenceReport;
+/**
+ * Run inference from pre-loaded input data (useful for testing).
+ */
+export declare function runInferenceFromInput(input: InferenceInput): InferenceReport;

package/dist/index.js

@@ -0,0 +1,140 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { clusterFindings } from "./analyzers/finding-clusterer.js";
+import { analyzeRootCause } from "./analyzers/root-cause.js";
+import { detectScoreAnomalies } from "./analyzers/score-anomaly.js";
+import { predictTrends } from "./analyzers/trend-predictor.js";
+/**
+ * Load all inference input data from a project's .ges/ directory.
+ */
+export function loadInferenceInput(projectPath) {
+    const gesDir = path.join(projectPath, ".ges");
+    const findings = loadFindings(gesDir);
+    const scoreHistory = loadScoreHistory(gesDir);
+    const activityLog = loadActivity(gesDir);
+    return { findings, scoreHistory, activityLog };
+}
+/**
+ * Run the full inference pipeline on a project.
+ */
+export function runInference(projectPath) {
+    const input = loadInferenceInput(projectPath);
+    return runInferenceFromInput(input);
+}
+/**
+ * Run inference from pre-loaded input data (useful for testing).
+ */
+export function runInferenceFromInput(input) {
+    const clustering = input.findings.length > 0
+        ? clusterFindings(input.findings)
+        : null;
+    const rootCause = input.findings.length > 0
+        ? analyzeRootCause(input.findings)
+        : null;
+    const scoreAnomalies = input.scoreHistory.length >= 2
+        ? detectScoreAnomalies(input.scoreHistory, input.activityLog)
+        : null;
+    const trends = input.scoreHistory.length >= 2
+        ? predictTrends(input.scoreHistory)
+        : null;
+    const summary = buildSummary(input, clustering, rootCause, scoreAnomalies, trends);
+    return {
+        generatedAt: new Date().toISOString(),
+        clustering,
+        rootCause,
+        scoreAnomalies,
+        trends,
+        summary,
+    };
+}
+// ============================================================
+// Data loaders
+// ============================================================
+function loadFindings(gesDir) {
+    const findingsPath = path.join(gesDir, "last-audit.json");
+    try {
+        const raw = fs.readFileSync(findingsPath, "utf-8");
+        const data = JSON.parse(raw);
+        const findings = Array.isArray(data.findings) ? data.findings : [];
+        // Filter out invalid entries
+        return findings.filter((f) => f !== null &&
+            typeof f === "object" &&
+            typeof f.ruleId === "string");
+    }
+    catch {
+        return [];
+    }
+}
+function loadScoreHistory(gesDir) {
+    const historyPath = path.join(gesDir, "score.json");
+    try {
+        const raw = fs.readFileSync(historyPath, "utf-8");
+        const data = JSON.parse(raw);
+        // score.json is a single ScoreFile. Build a single-element history.
+        if (data && typeof data.overall === "number") {
+            const point = {
+                overall: data.overall,
+                evaluatedAt: data.evaluated_at ?? new Date().toISOString(),
+                frameworks: {},
+            };
+            if (data.frameworks && typeof data.frameworks === "object") {
+                for (const [key, val] of Object.entries(data.frameworks)) {
+                    if (val !== null && typeof val === "object" && typeof val.score === "number") {
+                        point.frameworks[key] = { score: val.score };
+                    }
+                }
+            }
+            return [point];
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+function loadActivity(gesDir) {
+    const activityPath = path.join(gesDir, "activity-log.json");
+    try {
+        const raw = fs.readFileSync(activityPath, "utf-8");
+        const data = JSON.parse(raw);
+        const entries = Array.isArray(data) ? data : [];
+        return entries.filter((e) => e !== null &&
+            typeof e === "object" &&
+            typeof e.timestamp === "string");
+    }
+    catch {
+        return [];
+    }
+}
+// ============================================================
+// Summary builder
+// ============================================================
+function buildSummary(input, clustering, rootCause, scoreAnomalies, trends) {
+    let insightCount = 0;
+    // Count insights from each analyzer
+    if (clustering && clustering.clusterCount > 0 && clustering.reductionRatio > 20)
+        insightCount++;
+    if (rootCause?.topCause)
+        insightCount++;
+    if (scoreAnomalies?.hasAnomalies) {
+        insightCount += scoreAnomalies.anomalies.filter((a) => a.isAnomalous).length;
+    }
+    if (trends?.overall && trends.overall.trendDirection === "declining")
+        insightCount++;
+    for (const pred of trends?.predictions ?? []) {
+        if (pred.trendDirection === "declining" && pred.cyclesToThreshold !== null)
+            insightCount++;
+    }
+    return {
+        totalFindings: input.findings.length,
+        distinctPatterns: clustering?.clusterCount ?? 0,
+        reductionRatio: clustering?.reductionRatio ?? 0,
+        topRootCause: rootCause?.topCause?.identifier ?? null,
+        topRootCauseImpact: rootCause?.topCause
+            ? `${rootCause.topCause.connectedFindings.length} of ${rootCause.totalFindingsTraced} findings (${Math.round(rootCause.topCause.betweenness * 100)}%)`
+            : null,
+        hasScoreAnomalies: scoreAnomalies?.hasAnomalies ?? false,
+        overallTrend: trends?.overall?.trendDirection ?? "unknown",
+        insightCount,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,123 @@
+import type { SeverityLevel } from "@greenarmor/ges-core";
+export interface InferenceFinding {
+    ruleId: string;
+    severity: SeverityLevel;
+    category: string;
+    title: string;
+    description: string;
+    file: string;
+    line?: number;
+    evidence: string;
+    controlIds: string[];
+    fix: string;
+}
+export interface ScoreDataPoint {
+    overall: number;
+    evaluatedAt: string;
+    frameworks: Record<string, {
+        score: number;
+    }>;
+}
+export interface ActivityEntry {
+    timestamp: string;
+    action: string;
+    title: string;
+    description: string;
+    status: string;
+    details: {
+        score?: number;
+        findings_count?: number;
+        [key: string]: unknown;
+    };
+}
+export interface FindingCluster {
+    clusterId: string;
+    pattern: string;
+    ruleId: string;
+    category: string;
+    severity: SeverityLevel;
+    findingCount: number;
+    files: string[];
+    representativeTitle: string;
+    representativeFix: string;
+    findingIndices: number[];
+}
+export interface ClusteringResult {
+    totalFindings: number;
+    clusterCount: number;
+    clusters: FindingCluster[];
+    reductionRatio: number;
+}
+export interface RootCauseNode {
+    type: "file" | "control";
+    identifier: string;
+    connectedFindings: number[];
+    severityScore: number;
+    betweenness: number;
+    frameworks: string[];
+}
+export interface RootCauseResult {
+    nodes: RootCauseNode[];
+    topCause: RootCauseNode | null;
+    summary: string;
+    totalFindingsTraced: number;
+    maxSeverityScore: number;
+}
+export interface ScoreAnomaly {
+    framework: string;
+    delta: number;
+    previousScore: number;
+    currentScore: number;
+    zScore: number;
+    isAnomalous: boolean;
+    evaluatedAt: string;
+    triggeringEvent: string | null;
+    description: string;
+}
+export interface ScoreAnomalyResult {
+    anomalies: ScoreAnomaly[];
+    hasAnomalies: boolean;
+    averageScore: number;
+    standardDeviation: number;
+    dataPointCount: number;
+}
+export interface TrendPrediction {
+    framework: string;
+    slope: number;
+    intercept: number;
+    rSquared: number;
+    currentScore: number;
+    projectedScore: number;
+    cyclesToThreshold: number | null;
+    threshold: number;
+    trendDirection: "improving" | "declining" | "stable";
+    description: string;
+}
+export interface TrendPredictionResult {
+    predictions: TrendPrediction[];
+    overall: TrendPrediction | null;
+    dataPointCount: number;
+}
+export interface InferenceReport {
+    generatedAt: string;
+    clustering: ClusteringResult | null;
+    rootCause: RootCauseResult | null;
+    scoreAnomalies: ScoreAnomalyResult | null;
+    trends: TrendPredictionResult | null;
+    summary: InferenceSummary;
+}
+export interface InferenceSummary {
+    totalFindings: number;
+    distinctPatterns: number;
+    reductionRatio: number;
+    topRootCause: string | null;
+    topRootCauseImpact: string | null;
+    hasScoreAnomalies: boolean;
+    overallTrend: "improving" | "declining" | "stable" | "unknown";
+    insightCount: number;
+}
+export interface InferenceInput {
+    findings: InferenceFinding[];
+    scoreHistory: ScoreDataPoint[];
+    activityLog: ActivityEntry[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "dependencies": {
+    "@greenarmor/ges-core": "1.6.0"
+  },
+  "description": "GESF Inference Engine - AI-powered analysis of compliance data (clustering, RCA, anomaly detection, trend prediction)",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.8"
+  },
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "name": "@greenarmor/ges-inference-engine",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/greenarmor/gesf.git"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "version": "1.6.0",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "test": "vitest run"
+  }
+}