@godzillaba/mutest 1.0.0

package/.devcontainer/Dockerfile

@@ -0,0 +1,117 @@
+FROM node:20
+
+ARG TZ
+ENV TZ="$TZ"
+
+ARG CLAUDE_CODE_VERSION=latest
+
+# Install basic development tools and iptables/ipset
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  less \
+  git \
+  procps \
+  sudo \
+  fzf \
+  zsh \
+  man-db \
+  unzip \
+  gnupg2 \
+  gh \
+  iptables \
+  ipset \
+  iproute2 \
+  dnsutils \
+  aggregate \
+  jq \
+  nano \
+  vim \
+  && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Install Go
+ARG GO_VERSION=1.23.6
+RUN ARCH=$(dpkg --print-architecture) && \
+  wget -q "https://go.dev/dl/go${GO_VERSION}.linux-${ARCH}.tar.gz" && \
+  tar -C /usr/local -xzf "go${GO_VERSION}.linux-${ARCH}.tar.gz" && \
+  rm "go${GO_VERSION}.linux-${ARCH}.tar.gz"
+ENV PATH=$PATH:/usr/local/go/bin
+ENV GOPATH=/home/node/go
+ENV PATH=$PATH:/home/node/go/bin
+
+# Ensure default node user has access to /usr/local/share
+RUN mkdir -p /usr/local/share/npm-global && \
+  chown -R node:node /usr/local/share
+
+ARG USERNAME=node
+
+# Persist bash history.
+RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  && mkdir /commandhistory \
+  && touch /commandhistory/.bash_history \
+  && chown -R $USERNAME /commandhistory
+
+# Set `DEVCONTAINER` environment variable to help with orientation
+ENV DEVCONTAINER=true
+
+# Create workspace and config directories and set permissions
+RUN mkdir -p /workspace /home/node/.claude && \
+  chown -R node:node /workspace /home/node/.claude
+
+WORKDIR /workspace
+
+ARG GIT_DELTA_VERSION=0.18.2
+RUN ARCH=$(dpkg --print-architecture) && \
+  wget "https://github.com/dandavison/delta/releases/download/${GIT_DELTA_VERSION}/git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+  sudo dpkg -i "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+  rm "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb"
+
+# Set up non-root user
+USER node
+
+# Install global packages
+ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global
+ENV PATH=$PATH:/usr/local/share/npm-global/bin
+
+# Set the default shell to zsh rather than sh
+ENV SHELL=/bin/zsh
+
+# Set the default editor and visual
+ENV EDITOR=nano
+ENV VISUAL=nano
+
+# Default powerline10k theme
+ARG ZSH_IN_DOCKER_VERSION=1.2.0
+RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/v${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh)" -- \
+  -p git \
+  -p fzf \
+  -a "source /usr/share/doc/fzf/examples/key-bindings.zsh" \
+  -a "source /usr/share/doc/fzf/examples/completion.zsh" \
+  -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  -x
+
+# Install Gambit (Solidity mutation testing)
+ARG GAMBIT_VERSION=v1.0.6
+USER root
+RUN wget -q "https://github.com/Certora/gambit/releases/download/${GAMBIT_VERSION}/gambit-linux-${GAMBIT_VERSION}" -O /usr/local/bin/gambit && \
+  chmod +x /usr/local/bin/gambit
+USER node
+
+# Install Foundry (forge, cast, anvil, chisel)
+ENV PATH=$PATH:/home/node/.foundry/bin
+RUN curl -L https://foundry.paradigm.xyz | bash && foundryup
+
+# Symlink solc
+USER root
+RUN ln -s /home/node/.svm/0.8.33/solc-0.8.33 /usr/local/bin/solc
+USER node
+
+# Install Claude
+RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}
+
+
+# Copy and set up firewall script
+COPY init-firewall.sh /usr/local/bin/
+USER root
+RUN chmod +x /usr/local/bin/init-firewall.sh && \
+  echo "node ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/node-firewall && \
+  chmod 0440 /etc/sudoers.d/node-firewall
+USER node

package/.devcontainer/devcontainer.json

@@ -0,0 +1,62 @@
+{
+  "name": "Claude Code Sandbox",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      "TZ": "${localEnv:TZ:America/Los_Angeles}",
+      "CLAUDE_CODE_VERSION": "latest",
+      "GIT_DELTA_VERSION": "0.18.2",
+      "ZSH_IN_DOCKER_VERSION": "1.2.0"
+    }
+  },
+  "runArgs": [
+    "--cap-add=NET_ADMIN",
+    "--cap-add=NET_RAW"
+  ],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "anthropic.claude-code",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "eamodio.gitlens",
+        "golang.go"
+      ],
+      "settings": {
+        "go.useLanguageServer": true,
+        "[go]": {
+          "editor.formatOnSave": true,
+          "editor.defaultFormatter": "golang.go",
+          "editor.codeActionsOnSave": {
+            "source.organizeImports": "explicit"
+          }
+        },
+        "terminal.integrated.defaultProfile.linux": "zsh",
+        "terminal.integrated.profiles.linux": {
+          "bash": {
+            "path": "bash",
+            "icon": "terminal-bash"
+          },
+          "zsh": {
+            "path": "zsh"
+          }
+        }
+      }
+    }
+  },
+  "remoteUser": "node",
+  "mounts": [
+    "source=claude-code-bashhistory-${devcontainerId},target=/commandhistory,type=volume",
+    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
+  ],
+  "containerEnv": {
+    "NODE_OPTIONS": "--max-old-space-size=4096",
+    "CLAUDE_CONFIG_DIR": "/home/node/.claude",
+    "GOPATH": "/home/node/go",
+    "POWERLEVEL9K_DISABLE_GITSTATUS": "true"
+  },
+  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated",
+  "workspaceFolder": "/workspace",
+  "postStartCommand": "sudo /usr/local/bin/init-firewall.sh",
+  "waitFor": "postStartCommand"
+}

package/.devcontainer/init-firewall.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+set -euo pipefail  # Exit on error, undefined vars, and pipeline failures
+IFS=$'\n\t'       # Stricter word splitting
+
+# 1. Extract Docker DNS info BEFORE any flushing
+DOCKER_DNS_RULES=$(iptables-save -t nat | grep "127\.0\.0\.11" || true)
+
+# Flush existing rules and delete existing ipsets
+iptables -F
+iptables -X
+iptables -t nat -F
+iptables -t nat -X
+iptables -t mangle -F
+iptables -t mangle -X
+ipset destroy allowed-domains 2>/dev/null || true
+
+# 2. Selectively restore ONLY internal Docker DNS resolution
+if [ -n "$DOCKER_DNS_RULES" ]; then
+    echo "Restoring Docker DNS rules..."
+    iptables -t nat -N DOCKER_OUTPUT 2>/dev/null || true
+    iptables -t nat -N DOCKER_POSTROUTING 2>/dev/null || true
+    echo "$DOCKER_DNS_RULES" | xargs -L 1 iptables -t nat
+else
+    echo "No Docker DNS rules to restore"
+fi
+
+# First allow DNS and localhost before any restrictions
+# Allow outbound DNS
+iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
+# Allow inbound DNS responses
+iptables -A INPUT -p udp --sport 53 -j ACCEPT
+# Allow outbound SSH
+iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT
+# Allow inbound SSH responses
+iptables -A INPUT -p tcp --sport 22 -m state --state ESTABLISHED -j ACCEPT
+# Allow localhost
+iptables -A INPUT -i lo -j ACCEPT
+iptables -A OUTPUT -o lo -j ACCEPT
+
+# Create ipset with CIDR support
+ipset create allowed-domains hash:net
+
+# Resolve and add other allowed domains
+for domain in \
+    "registry.npmjs.org" \
+    "api.anthropic.com" \
+    "sentry.io" \
+    "statsig.anthropic.com" \
+    "statsig.com" \
+    "marketplace.visualstudio.com" \
+    "vscode.blob.core.windows.net" \
+    "update.code.visualstudio.com" \
+    "proxy.golang.org" \
+    "sum.golang.org" \
+    "storage.googleapis.com" \
+    "binaries.soliditylang.org"; do
+    echo "Resolving $domain..."
+    ips=$(dig +noall +answer A "$domain" | awk '$4 == "A" {print $5}')
+    if [ -z "$ips" ]; then
+        echo "ERROR: Failed to resolve $domain"
+        exit 1
+    fi
+    
+    while read -r ip; do
+        if [[ ! "$ip" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
+            echo "ERROR: Invalid IP from DNS for $domain: $ip"
+            exit 1
+        fi
+        echo "Adding $ip for $domain"
+        ipset add allowed-domains "$ip" -exist
+    done < <(echo "$ips")
+done
+
+# Get host IP from default route
+HOST_IP=$(ip route | grep default | cut -d" " -f3)
+if [ -z "$HOST_IP" ]; then
+    echo "ERROR: Failed to detect host IP"
+    exit 1
+fi
+
+HOST_NETWORK=$(echo "$HOST_IP" | sed "s/\.[0-9]*$/.0\/24/")
+echo "Host network detected as: $HOST_NETWORK"
+
+# Set up remaining iptables rules
+iptables -A INPUT -s "$HOST_NETWORK" -j ACCEPT
+iptables -A OUTPUT -d "$HOST_NETWORK" -j ACCEPT
+
+# Set default policies to DROP first
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+iptables -P OUTPUT DROP
+
+# First allow established connections for already approved traffic
+iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+# Then allow only specific outbound traffic to allowed domains
+iptables -A OUTPUT -m set --match-set allowed-domains dst -j ACCEPT
+
+# Explicitly REJECT all other outbound traffic for immediate feedback
+iptables -A OUTPUT -j REJECT --reject-with icmp-admin-prohibited
+
+echo "Firewall configuration complete"
+echo "Verifying firewall rules..."
+if curl --connect-timeout 5 https://example.com >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - was able to reach https://example.com"
+    exit 1
+else
+    echo "Firewall verification passed - unable to reach https://example.com as expected"
+fi
+
+# Verify GitHub API access
+if curl --connect-timeout 5 https://api.github.com/zen >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - was able to reach https://api.github.com"
+    exit 1
+else
+    echo "Firewall verification passed - unable to reach https://api.github.com as expected"
+fi

package/.github/workflows/test.yml

@@ -0,0 +1,38 @@
+name: CI
+
+permissions: {}
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+env:
+  FOUNDRY_PROFILE: ci
+
+jobs:
+  check:
+    name: Foundry project
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Show Forge version
+        run: forge --version
+
+      - name: Run Forge fmt
+        run: forge fmt --check
+
+      - name: Run Forge build
+        run: forge build --sizes
+
+      - name: Run Forge tests
+        run: forge test -vvv

package/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "lib/forge-std"]
+	path = lib/forge-std
+	url = https://github.com/foundry-rs/forge-std

package/CLAUDE.md

@@ -0,0 +1,39 @@
+# CLAUDE.md
+
+## Git
+
+Always commit with `--no-gpg-sign` — GPG signing is not configured in this container.
+
+## Solidity Toolchain
+
+`solc` is symlinked into PATH via the Dockerfile. If `solc` is not found (e.g. after a container rebuild), run `forge clean && forge build` — Foundry will re-install solc via svm automatically.
+
+## Development Environment
+
+This project runs inside a devcontainer (`.devcontainer/`). The container is locked down with an iptables firewall that only allows traffic to a small allowlist of domains.
+
+- **To install system packages or tools** — edit `.devcontainer/Dockerfile` and rebuild the container.
+- **To allow network access to a new domain** — add it to the domain list in `.devcontainer/init-firewall.sh`.
+
+## Tooling Philosophy
+
+Always use the right tool for the job — install real libraries instead of reimplementing things with stdlib. If a dependency is missing and can't be installed due to the container/firewall setup, ask the user to help unblock it (e.g. add a domain to the firewall, add a package to the Dockerfile, rebuild the container). Don't silently work around missing tools with inferior hand-rolled alternatives.
+
+## Documentation
+
+When adding or modifying a feature, always update the relevant documentation if it exists. Keep docs in sync with code.
+
+## Code Style
+
+Inspired by NASA/JPL's "Power of 10" — code must be quickly and easily reviewable by a human.
+
+- Write minimal, concise code. No unnecessary abstractions or indirection.
+- Functions should be short enough to fit on a screen (~60 lines max). If longer, split by responsibility.
+- Simple control flow. Minimal nesting, early returns over deep if/else chains.
+- Smallest possible scope for all variables and data.
+- No comments unless the logic is genuinely non-obvious. Never restate what the code already says.
+- No JSDoc unless it's a public API. Skip @param/@returns that just repeat type signatures.
+- Don't add error handling, validation, or fallbacks for cases that can't realistically happen.
+- Prefer fewer lines. Three similar lines are better than a helper function used once.
+- Don't refactor, rename, or "improve" code you weren't asked to change.
+- No clever tricks. Code should be obvious, not impressive.

package/README.md

@@ -0,0 +1,33 @@
+# mutest
+
+Mutation testing for Solidity. Uses [Gambit](https://github.com/Certora/gambit) to generate mutants and [Foundry](https://github.com/foundry-rs/foundry) to test them.
+
+## Usage
+
+```sh
+npx . src/Counter.sol
+```
+
+Pass one or more Solidity files. Mutest will:
+
+1. Create 10 parallel copies of your project
+2. Generate mutants with Gambit (e.g. `++` -> `--`, assignments replaced)
+3. Run `forge test` against each mutant across the worker copies
+4. Report which mutants were killed (tests caught them) or survived (coverage gap)
+
+Example output:
+
+```
+[KILLED]   #1 DeleteExpressionMutation src/Counter.sol
+[KILLED]   #2 AssignmentMutation src/Counter.sol
+[SURVIVED] #3 AssignmentMutation src/Counter.sol
+
+3 mutants tested: 2 killed, 1 survived
+```
+
+## Requirements
+
+- [Foundry](https://getfoundry.sh/) (`forge`)
+- [Gambit](https://github.com/Certora/gambit) (`gambit`)
+- `solc` in PATH
+- Node.js >= 18

package/foundry.lock

@@ -0,0 +1,8 @@
+{
+  "lib/forge-std": {
+    "tag": {
+      "name": "v1.15.0",
+      "rev": "0844d7e1fc5e60d77b68e469bff60265f236c398"
+    }
+  }
+}

package/foundry.toml

@@ -0,0 +1,6 @@
+[profile.default]
+src = "src"
+out = "out"
+libs = ["lib"]
+
+# See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options

package/index.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env -S npx tsx
+import { execFile as execFileCb } from "child_process";
+import { readFile, cp, rm } from "fs/promises";
+import { promisify } from "util";
+
+const execFile = promisify(execFileCb);
+
+interface Mutant {
+  id: string;
+  description: string;
+  name: string;
+  original: string;
+}
+
+async function setupWorkers(workerCount: number): Promise<string> {
+  const { stdout: tempDir } = await execFile("mktemp", ["-d"]);
+  const root = tempDir.trim();
+
+  const workers = Array.from({ length: workerCount }, (_, i) => {
+    const dir = `${root}/worker-${i}`;
+    return execFile("bash", [
+      "-c",
+      `mkdir -p "${dir}" && git ls-files -z | tar -c --null -T - | tar -x -C "${dir}"`,
+    ]);
+  });
+  await Promise.all(workers);
+  return root;
+}
+
+async function runGambit(solFiles: string[]): Promise<Mutant[]> {
+  await rm("gambit_out", { recursive: true, force: true });
+  for (const file of solFiles) {
+    await execFile("gambit", ["mutate", "--filename", file]);
+  }
+  const raw = await readFile("gambit_out/gambit_results.json", "utf-8");
+  return JSON.parse(raw);
+}
+
+async function processMutants(
+  tempDir: string,
+  mutants: Mutant[],
+  workerCount: number,
+) {
+  const queues: Mutant[][] = Array.from({ length: workerCount }, () => []);
+  for (let i = 0; i < mutants.length; i++)
+    queues[i % workerCount].push(mutants[i]);
+
+  let killed = 0;
+  let survived = 0;
+
+  const workers = queues.map(async (queue, workerIdx) => {
+    const workerDir = `${tempDir}/worker-${workerIdx}`;
+    for (const mutant of queue) {
+      await cp(`gambit_out/${mutant.name}`, `${workerDir}/${mutant.original}`);
+      try {
+        await execFile("forge", ["test", "--root", workerDir]);
+        survived++;
+        console.log(
+          `[SURVIVED] #${mutant.id} ${mutant.description} ${mutant.original}`,
+        );
+      } catch {
+        killed++;
+        console.log(
+          `[KILLED]   #${mutant.id} ${mutant.description} ${mutant.original}`,
+        );
+      }
+    }
+  });
+
+  await Promise.all(workers);
+  console.log(
+    `\n${killed + survived} mutants tested: ${killed} killed, ${survived} survived`,
+  );
+}
+
+async function main() {
+  const solFiles = process.argv.slice(2);
+  if (solFiles.length === 0) {
+    console.error("Usage: mutest <sol-file> [sol-file ...]");
+    process.exit(1);
+  }
+
+  const workerCount = 10;
+  console.log(`Setting up ${workerCount} workers...`);
+  const tempDir = await setupWorkers(workerCount);
+
+  try {
+    console.log(`Running gambit on ${solFiles.join(", ")}...`);
+    const mutants = await runGambit(solFiles);
+    console.log(`Generated ${mutants.length} mutants, running tests...\n`);
+    await processMutants(tempDir, mutants, workerCount);
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+main();

package/lib/forge-std/.gitattributes

@@ -0,0 +1 @@
+src/Vm.sol linguist-generated

package/lib/forge-std/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @danipopes @klkvr @mattsse @grandizzy @yash-atreya @zerosnacks @onbjerg @0xrusowsky

package/lib/forge-std/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

package/lib/forge-std/.github/workflows/ci.yml

@@ -0,0 +1,125 @@
+name: CI
+
+permissions: {}
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    name: build +${{ matrix.toolchain }} ${{ matrix.flags }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        toolchain: [stable, nightly]
+        flags:
+          - ""
+          - --via-ir
+          - --use solc:0.8.33 --via-ir
+          - --use solc:0.8.33
+          - --use solc:0.8.13 --via-ir
+          - --use solc:0.8.13
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: ${{ matrix.toolchain }}
+      - run: forge --version
+      - run: forge build -vvvvv --skip test --deny warnings ${{ matrix.flags }} --contracts 'test/compilation/*'
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        toolchain: [stable, nightly]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: ${{ matrix.toolchain }}
+      - run: forge --version
+      - run: forge test -vvv
+
+  fmt:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: foundry-rs/foundry-toolchain@v1
+      - run: forge --version
+      - run: forge fmt --check
+
+  typos:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: crate-ci/typos@78bc6fb2c0d734235d57a2d6b9de923cc325ebdd # v1
+
+  codeql:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      actions: read
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: actions
+            build-mode: none
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{matrix.language}}"
+
+  ci-success:
+    runs-on: ubuntu-latest
+    if: always()
+    needs:
+      - build
+      - test
+      - fmt
+      - typos
+      - codeql
+    timeout-minutes: 10
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}