@solana-epic/github-action 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -0,0 +1,157 @@
+# EPIC
+
+<p align="center">
+  <b>Upgrade Intelligence for Solana Programs</b>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@solana-epic/cli"><img src="https://img.shields.io/npm/v/@solana-epic/cli.svg?style=flat-square&color=blue" alt="npm version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/solana-epic/epic.svg?style=flat-square" alt="license" /></a>
+  <a href="https://github.com/solana-epic/epic/releases"><img src="https://img.shields.io/github/v/release/solana-epic/epic.svg?style=flat-square&color=orange" alt="GitHub release" /></a>
+  <a href="https://github.com/solana-epic/epic/actions"><img src="https://img.shields.io/github/actions/workflow/status/solana-epic/epic/test.yml?branch=main&style=flat-square" alt="GitHub Actions status" /></a>
+</p>
+
+---
+
+EPIC is the deployment readiness and upgrade intelligence infrastructure for Solana programs. Positioned between git push and mainnet, EPIC evaluates state layout evolution, ABI compatibility, and security regressions to answer a simple question before you deploy:
+
+**"Can this upgrade safely reach mainnet?"**
+
+---
+
+## Why EPIC Exists
+
+Standard developer tooling tells you if your code compiles. Security scanners tell you if a codebase has known vulnerabilities. **Neither tells you if the transition between your old deployment and your new code will break state on mainnet.**
+
+Every Solana program upgrade is a high-risk migration. A minor type shift, field reordering, or missing state reload can corrupt deserialization layouts, lock user accounts, or introduce severe security regressions.
+
+EPIC catches these upgrade compatibility issues and regressions in local development and on every pull request.
+
+---
+
+## What EPIC Does
+
+### 1. Upgrade Compatibility (`epic check`)
+Compare two program versions to verify layout compatibility and prevent state corruption.
+```
+$ epic check ./old-program ./new-program
+
+🔍 Comparing Program Layouts...
+[CRITICAL] Layout size decrease detected on struct Position: 56 bytes -> 48 bytes.
+           Account shrinkage can lead to mainnet deserialization failures.
+           Consider using realloc or adding padding fields to preserve layout sizing.
+```
+
+### 2. State Layout Analysis (`epic analyze`)
+Track account layout evolution, serialized sizes, and memory offsets to manage state scaling.
+```
+$ epic analyze .
+
+🔍 Analyzing State Account Layouts...
+STATE ACCOUNTS:
+├── Vault (49 bytes) [program::lib] [Static]
+└── Position (56 bytes) [program::lib] [Static]
+```
+
+### 3. Upgrade Safety Verification (`epic audit`)
+Verify that modifications to instruction state rules and safety invariants do not introduce security regressions.
+```
+$ epic audit .
+
+🔍 Verifying Invariant Safety...
+[CRITICAL] EPIC-SEC-003: Missing Post-CPI Account Reload
+           Affected File: programs/vault/src/lib.rs:42
+           Context: State mutation of Vault account following CPI invocation
+           Recommendation: Reload local state cache (e.g. run vault.reload()?) after CPI.
+```
+
+---
+
+## Installation
+
+Install the CLI wrapper:
+```bash
+npm install -g @solana-epic/cli
+```
+
+Verify your installation:
+```bash
+epic rules
+```
+
+---
+
+## Quick Start
+
+### 1. Check Upgrade Compatibility
+Compare your current working directory against a previous release or program folder:
+```bash
+epic check ./old_release_dir ./new_release_dir
+```
+
+### 2. Run Layout Invariant Verification
+Audit your codebase for security regressions before committing:
+```bash
+epic audit .
+```
+
+### 3. Integrate with CI/CD
+Incorporate upgrade checks directly into your pull requests. EPIC supports standard SARIF outputs for GitHub Actions integration:
+```yaml
+- name: Run EPIC Upgrade Checks
+  run: npx @solana-epic/cli audit . -f sarif
+
+- name: Upload Safety Report
+  uses: github/code-scanning-upload-aurora@v2
+  with:
+    sarif_file: sarif.json
+```
+
+---
+
+## Safety Invariant Rules
+
+EPIC parses Rust source code directly to ensure upgrade changes do not break safety invariants:
+
+| Rule ID | Name | Severity | Description |
+| :--- | :--- | :--- | :--- |
+| **EPIC-SEC-001** | Owner Validation | Critical | Ensures mutable account write paths are guarded by ownership checks (`account.owner == program_id`). |
+| **EPIC-SEC-002** | Signer Validation | Critical | Verifies privileged mutations check signer authority. |
+| **EPIC-SEC-003** | Missing Post-CPI Reload | Critical | Flags reads/writes on stale deserialized state cached before a mutating CPI. |
+| **EPIC-SEC-004** | PDA Seed Collision Risk | High | Identifies adjacent variable-length seeds lacking delimiters that could cause derivation collision. |
+| **EPIC-SEC-005** | Arbitrary CPI Targets | Critical | Flags CPIs targeting dynamic program IDs without validations. |
+
+To inspect a rule's criteria in detail, run:
+```bash
+epic explain EPIC-SEC-001
+```
+
+---
+
+## Architecture Overview
+
+EPIC constructs control-flow representations of program ASTs and diffs state schemas across the following unified pipeline:
+```
+Source Code ➔ Rust AST Parser ➔ Type Registry ➔ CFG Builder ➔ SSA Engine ➔ Dominance Tree ➔ GuardFacts IR ➔ Rules Analyzer
+```
+For a deep dive into the compiler and engine architecture, see [docs/architecture.md](docs/architecture.md).
+
+---
+
+## Roadmap
+
+*   **IDL-based layout drift verification**: Track compatibility profiles directly via published IDLs.
+*   **Editor LSP integration**: Real-time IDE diagnostics for layout drift and offset alignment.
+*   **Migration assistance**: Automatically generate Anchor state migration wrappers.
+
+---
+
+## Contributing
+
+We welcome contributions to EPIC! See [CONTRIBUTING.md](CONTRIBUTING.md) for local development setup, package structure, and submission guidelines.
+
+---
+
+## License
+
+EPIC is open-source developer tooling licensed under the **MIT License**. See [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana-epic/github-action",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "Solana EPIC Upgrade Guard GitHub Action",
   "private": false,
   "publishConfig": {
@@ -16,11 +16,34 @@
   "dependencies": {
     "@actions/core": "^1.10.1",
     "@actions/github": "^6.0.0",
-    "@solana-epic/diff-engine": "^0.1.0-beta.1",
-    "@solana-epic/parser": "^0.1.0-beta.1"
+    "@solana-epic/diff-engine": "^0.1.0-beta.2",
+    "@solana-epic/parser": "^0.1.0-beta.2"
   },
   "devDependencies": {
     "esbuild": "^0.20.1",
     "typescript": "^5.3.3"
-  }
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/solana-epic/epic#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solana-epic/epic.git"
+  },
+  "bugs": {
+    "url": "https://github.com/solana-epic/epic/issues"
+  },
+  "keywords": [
+    "solana",
+    "anchor",
+    "security",
+    "static-analysis",
+    "audit",
+    "upgrade-safety",
+    "rust"
+  ],
+  "author": "Solana EPIC Team",
+  "files": [
+    "dist",
+    "action.yml"
+  ]
 }

package/src/github.ts

@@ -1,81 +0,0 @@
-import * as github from "@actions/github";
-import * as core from "@actions/core";
-
-export async function upsertPRComment(token: string, reportMarkdown: string): Promise<void> {
-  const context = github.context;
-  
-  if (!context.payload.pull_request) {
-    core.info("Not a pull request event. Skipping comment posting.");
-    return;
-  }
-
-  const prNumber = context.payload.pull_request.number;
-  const owner = context.repo.owner;
-  const repo = context.repo.repo;
-
-  const octokit = github.getOctokit(token);
-
-  const commentHeader = "<!-- epic-upgrade-guard-comment -->";
-  const bodyWithHeader = `${commentHeader}\n${reportMarkdown}`;
-
-  core.info(`Searching for existing EPIC comments on PR #${prNumber}...`);
-
-  const { data: comments } = await octokit.rest.issues.listComments({
-    owner,
-    repo,
-    issue_number: prNumber,
-    per_page: 100
-  });
-
-  const existingComment = comments.find((comment) => comment.body?.includes(commentHeader));
-
-  if (existingComment) {
-    core.info(`Found existing comment (ID: ${existingComment.id}). Updating it to avoid comment spam...`);
-    await octokit.rest.issues.updateComment({
-      owner,
-      repo,
-      comment_id: existingComment.id,
-      body: bodyWithHeader
-    });
-  } else {
-    core.info(`No existing comment found. Creating a new one...`);
-    await octokit.rest.issues.createComment({
-      owner,
-      repo,
-      issue_number: prNumber,
-      body: bodyWithHeader
-    });
-  }
-}
-
-export async function checkIfConfigChanged(token: string): Promise<boolean> {
-  const context = github.context;
-  
-  if (!context.payload.pull_request) {
-    core.info("Not a pull request context. Skipping config change audit.");
-    return false;
-  }
-
-  const prNumber = context.payload.pull_request.number;
-  const owner = context.repo.owner;
-  const repo = context.repo.repo;
-  const octokit = github.getOctokit(token);
-
-  try {
-    core.info(`Auditing PR #${prNumber} files for modifications to epic.toml...`);
-    const { data: files } = await octokit.rest.pulls.listFiles({
-      owner,
-      repo,
-      pull_number: prNumber,
-      per_page: 100
-    });
-
-    const isModified = files.some(file => file.filename.endsWith("epic.toml"));
-    core.info(`Config modification audit: ${isModified ? "MODIFIED" : "UNMODIFIED"}`);
-    return isModified;
-  } catch (error) {
-    core.warning(`Failed to list pull request files from GitHub API: ${error}`);
-    return false;
-  }
-}
-

package/src/index.ts

@@ -1,66 +0,0 @@
-import * as core from "@actions/core";
-import { compareAnchorPrograms } from "@solana-epic/diff-engine";
-import { config } from "@solana-epic/parser";
-import { upsertPRComment, checkIfConfigChanged } from "./github.js";
-import { generateCompactMarkdownReport } from "./report.js";
-
-async function run(): Promise<void> {
-  try {
-    const githubToken = core.getInput("github_token", { required: true });
-    const oldPath = core.getInput("old_path", { required: true });
-    const newPath = core.getInput("new_path", { required: true });
-    const configPath = core.getInput("config_path") || undefined;
-
-    core.info(`Running EPIC Upgrade Guard compare:`);
-    core.info(`Old path: ${oldPath}`);
-    core.info(`New path: ${newPath}`);
-    if (configPath) {
-      core.info(`Custom config path: ${configPath}`);
-    }
-
-    // Load epic.toml configuration
-    let epicConfig: config.ResolvedEpicConfig;
-    try {
-      epicConfig = config.loadEpicConfig(configPath);
-      core.info(`Loaded epic.toml settings. Fail severity threshold: ${epicConfig.failOnSeverity}`);
-    } catch (err: any) {
-      core.setFailed(`Failed to validate epic.toml configuration: ${err.message}`);
-      return;
-    }
-
-    // Check if configuration changed in the pull request
-    const configChanged = await checkIfConfigChanged(githubToken);
-
-    // Run layout verification comparison
-    const report = await compareAnchorPrograms(oldPath, newPath, epicConfig);
-
-    const findingsCount = report.findings.length;
-    core.setOutput("severity", report.severity);
-    core.setOutput("findings_count", findingsCount.toString());
-
-    core.info(`Diff completed. Severity: ${report.severity}, Findings: ${findingsCount}`);
-
-    // Generate compact markdown report
-    const markdownReport = generateCompactMarkdownReport(report, epicConfig, configChanged);
-
-    // Upsert the comment on GitHub Pull Request
-    await upsertPRComment(githubToken, markdownReport);
-
-    // Gate verification
-    const severityLevels = ["SAFE", "MINOR", "MAJOR", "CRITICAL"];
-    const thresholdIndex = severityLevels.indexOf(epicConfig.failOnSeverity);
-    const reportSeverityIndex = severityLevels.indexOf(report.severity);
-
-    if (thresholdIndex !== -1 && reportSeverityIndex !== -1 && reportSeverityIndex >= thresholdIndex) {
-      core.setFailed(`EPIC Guard Blocked: Upgrade severity is ${report.severity} (threshold: ${epicConfig.failOnSeverity}).`);
-    } else {
-      core.info("EPIC Guard approved upgrade.");
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    core.setFailed(`EPIC Upgrade Guard failed: ${message}`);
-  }
-}
-
-run();
-

package/src/report.ts

@@ -1,143 +0,0 @@
-import type { DiffReport } from "@solana-epic/diff-engine";
-import type { config } from "@solana-epic/parser";
-import { createUpgradeIntelligenceItem } from "@solana-epic/diff-engine";
-
-export function generateCompactMarkdownReport(
-  report: DiffReport,
-  cfg: config.ResolvedEpicConfig,
-  configChanged: boolean
-): string {
-  const lines: string[] = [];
-
-  // Determine Overall Status
-  const failSeverity = cfg.failOnSeverity;
-  const severityOrder = ["SAFE", "MINOR", "MAJOR", "CRITICAL"];
-  const thresholdIndex = severityOrder.indexOf(failSeverity);
-  const reportSeverityIndex = severityOrder.indexOf(report.severity);
-  const blocked = thresholdIndex !== -1 && reportSeverityIndex !== -1 && reportSeverityIndex >= thresholdIndex;
-
-  const hasOverrides = report.findings.some(f => {
-    const original = f.kind === "FIELD_ADDED" ? "MAJOR" : "CRITICAL";
-    return f.severity !== original;
-  });
-
-  // 1. Status Banner
-  if (blocked) {
-    lines.push("## 🔴 EPIC Guard: UPGRADE BLOCKED");
-    lines.push("");
-    lines.push(`Upgrade checks failed because layout changes exceed the **${failSeverity}** threshold.`);
-  } else if (hasOverrides) {
-    lines.push("## 🟡 EPIC Guard: APPROVED WITH OVERRIDES");
-    lines.push("");
-    lines.push("Upgrade checks passed with muted warnings. Custom overrides are active in `epic.toml`.");
-  } else {
-    lines.push("## 🟢 EPIC Guard: APPROVED");
-    lines.push("");
-    lines.push("Upgrade checks approved. No layout compatibility risks detected.");
-  }
-  lines.push("");
-
-  // 2. Config Change Warning
-  if (configChanged) {
-    lines.push("> [!WARNING]");
-    lines.push("> **UPGRADE CONFIGURATION GATE MODIFIED**");
-    lines.push("> This Pull Request contains changes to `epic.toml` configuration rules.");
-    lines.push("> Signers must audit the modifications below to ensure safety limits are not bypassed.");
-    lines.push("");
-  }
-
-  // 3. Summary Table
-  lines.push("### 📊 Upgrade Summary");
-  lines.push("");
-  lines.push("| Program | Account | Finding | Final Severity | Overridden? |");
-  lines.push("| :--- | :--- | :--- | :--- | :--- |");
-  
-  if (report.findings.length === 0) {
-    lines.push("| *N/A* | *All Accounts* | *No structural changes* | `SAFE` | No |");
-  } else {
-    for (const f of report.findings) {
-      const original = f.kind === "FIELD_ADDED" ? "MAJOR" : "CRITICAL";
-      const isOverridden = f.severity !== original;
-      lines.push(`| \`marginfi\` | \`${f.account}\` | \`${f.kind}\` | \`${f.severity}\` | ${isOverridden ? "✅ Yes" : "No"} |`);
-    }
-  }
-  lines.push("");
-
-  // 4. Detailed Findings
-  if (report.findings.length > 0) {
-    lines.push("### 🔍 Layout Findings");
-    lines.push("");
-    for (const f of report.findings) {
-      const intel = createUpgradeIntelligenceItem(f);
-      lines.push(`#### Struct \`${f.account}\` — **${f.kind}**`);
-      lines.push("");
-      lines.push(`*   **Finding Type**: ${f.kind}`);
-      if (f.field) {
-        lines.push(`*   **Field**: \`${f.field.name}\` (${f.field.oldType || "new"} ──► ${f.field.newType || "removed"})`);
-      }
-      lines.push(`*   **Size Impact**: \`${f.oldSize}B\` ──► \`${f.newSize}B\` (${f.newSize - f.oldSize >= 0 ? "+" : ""}${f.newSize - f.oldSize} bytes)`);
-      lines.push(`*   **Risk Class**: ${intel.riskCategory}`);
-      lines.push(`*   **Severity**: \`${f.severity}\``);
-      lines.push("");
-    }
-  }
-
-  // 5. Applied Overrides Section
-  const appliedOverrides: Array<{ account: string; finding: string; field?: string; shift: string; note: string }> = [];
-  for (const f of report.findings) {
-    const original = f.kind === "FIELD_ADDED" ? "MAJOR" : "CRITICAL";
-    if (f.severity !== original) {
-      // Find override note
-      let note = "No note provided.";
-      for (const [name, program] of cfg.programs.entries()) {
-        const match = program.overrides.find(o => {
-          const accountMatch = o.account.toLowerCase() === f.account.toLowerCase();
-          const findingMatch = o.finding.toUpperCase() === f.kind.toUpperCase();
-          const fieldMatch = f.field && o.field && o.field.toLowerCase() === f.field.name.toLowerCase();
-          return accountMatch && findingMatch && (fieldMatch || !o.field);
-        });
-        if (match) {
-          note = match.note;
-          break;
-        }
-      }
-      appliedOverrides.push({
-        account: f.account,
-        finding: f.kind,
-        field: f.field?.name,
-        shift: `\`${original}\` ──► \`${f.severity}\``,
-        note
-      });
-    }
-  }
-
-  if (appliedOverrides.length > 0) {
-    lines.push("### 🔑 Applied Layout Overrides");
-    lines.push("");
-    lines.push("| Struct | Finding | Field | Severity Shift | Note / Safety Justification |");
-    lines.push("| :--- | :--- | :--- | :--- | :--- |");
-    for (const o of appliedOverrides) {
-      lines.push(`| \`${o.account}\` | \`${o.finding}\` | \`${o.field || "global"}\` | ${o.shift} | ${o.note} |`);
-    }
-    lines.push("");
-  }
-
-  // 6. Recommended Actions
-  lines.push("### 💡 Recommended Actions");
-  lines.push("");
-  if (report.findings.length === 0) {
-    lines.push("*   No action required. Layout upgrades are safe to proceed.");
-  } else {
-    const uniqueRecommendations = new Set<string>();
-    for (const f of report.findings) {
-      const intel = createUpgradeIntelligenceItem(f);
-      uniqueRecommendations.add(intel.recommendation);
-    }
-    for (const rec of uniqueRecommendations) {
-      lines.push(`*   ${rec}`);
-    }
-  }
-  lines.push("");
-
-  return lines.join("\n");
-}

package/test/report.test.mjs

@@ -1,107 +0,0 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-import { generateCompactMarkdownReport } from "../dist/report.js";
-
-// Helper to construct a mock config
-const createMockConfig = (failOnSeverity = "MAJOR") => ({
-  compareMode: "ast",
-  failOnSeverity,
-  excludePaths: [],
-  enforcePadding: false,
-  programs: new Map([
-    ["marginfi", {
-      name: "marginfi",
-      absolutePath: "/workspace/programs/marginfi",
-      programId: "MFv2...",
-      overrides: [
-        {
-          account: "Bank",
-          finding: "PADDING_REPURPOSE",
-          field: "reserved",
-          action: "allow",
-          note: "Replaced padding safely.",
-          used: true
-        }
-      ]
-    }]
-  ])
-});
-
-test("report: generates approved status banner when clean", () => {
-  const report = {
-    oldProgramPath: "/old",
-    newProgramPath: "/new",
-    severity: "SAFE",
-    findings: []
-  };
-  const config = createMockConfig();
-
-  const md = generateCompactMarkdownReport(report, config, false);
-  assert.match(md, /🟢 EPIC Guard: APPROVED/);
-  assert.match(md, /Upgrade checks approved/);
-  assert.match(md, /No structural changes/);
-  assert.match(md, /No action required/);
-});
-
-test("report: generates overrides active banner when warnings are muted", () => {
-  const report = {
-    oldProgramPath: "/old",
-    newProgramPath: "/new",
-    severity: "SAFE",
-    findings: [
-      {
-        severity: "SAFE", // Overridden from CRITICAL
-        account: "Bank",
-        kind: "PADDING_REPURPOSE",
-        field: { name: "reserved" },
-        oldSize: 100,
-        newSize: 100
-      }
-    ]
-  };
-  const config = createMockConfig();
-
-  const md = generateCompactMarkdownReport(report, config, false);
-  assert.match(md, /🟡 EPIC Guard: APPROVED WITH OVERRIDES/);
-  assert.match(md, /Applied Layout Overrides/);
-  assert.match(md, /Replaced padding safely/);
-  assert.match(md, /`CRITICAL` ──► `SAFE`/);
-});
-
-test("report: generates blocked status banner when threshold is exceeded", () => {
-  const report = {
-    oldProgramPath: "/old",
-    newProgramPath: "/new",
-    severity: "MAJOR",
-    findings: [
-      {
-        severity: "MAJOR", // Not overridden
-        account: "Bank",
-        kind: "FIELD_ADDED",
-        field: { name: "maker_rebate" },
-        oldSize: 100,
-        newSize: 108
-      }
-    ]
-  };
-  const config = createMockConfig("MAJOR"); // Will block since report severity is MAJOR
-
-  const md = generateCompactMarkdownReport(report, config, false);
-  assert.match(md, /🔴 EPIC Guard: UPGRADE BLOCKED/);
-  assert.match(md, /Upgrade checks failed because layout changes exceed/);
-});
-
-test("report: injects warning banner when epic.toml changed", () => {
-  const report = {
-    oldProgramPath: "/old",
-    newProgramPath: "/new",
-    severity: "SAFE",
-    findings: []
-  };
-  const config = createMockConfig();
-
-  const md = generateCompactMarkdownReport(report, config, true); // configChanged = true
-  assert.match(md, /🟢 EPIC Guard: APPROVED/);
-  assert.match(md, /UPGRADE CONFIGURATION GATE MODIFIED/);
-  assert.match(md, /This Pull Request contains changes to `epic.toml`/);
-});