inspequte 0.16.0

Fast, CLI-first static analysis for JVM class and JAR files.
inspequte-0.16.0 is not a library.

inspequte

inspequte logo

CI Crates.io Gradle Plugin Portal Version License: AGPL-3.0 Conventional Commits

[!NOTE] Project Intention

inspequte itself already has enough features and support for production use. This repository remains a PoC for exploring how to work with and empower agents through practical, real-world static analysis development.

The goal is to improve both the tool and the agent-driven development workflow by iterating in the open with reproducible, CI-friendly outputs.

inspequte is a fast, CLI-first static analysis tool for JVM class and JAR files. It focuses on CI/CD speed, deterministic output, and SARIF-only reporting for global standard compatibility.

The name combines "inspect" and "cute". The CLI command is inspequte.

Goals

  • Fast startup and analysis for CI pipelines.
  • No IDE integration required.
  • Deterministic SARIF v2.1.0 output for LLM-friendly automation.

Local rule workflow (Codex skills)

Four local skills are available under .codex/skills/ for sequential rule work:

  • inspequte-rule-plan
  • inspequte-rule-spec
  • inspequte-rule-impl
  • inspequte-rule-verify

Recommended sequence:

  1. Plan: run inspequte-rule-plan with a short rule idea and target rule-id.
  2. Spec: run inspequte-rule-spec to write src/rules/<rule-id>/spec.md.
  3. Implement: run inspequte-rule-impl from spec.md and add tests.
  4. Prepare isolated verify input: 
    scripts/prepare-verify-input.sh <rule-id> [base-ref]
cargo build > verify-input/reports/cargo-build.txt 2>&1
cargo test > verify-input/reports/cargo-test.txt 2>&1
cargo audit --format sarif > verify-input/reports/cargo-audit.sarif
  5. Verify: run inspequte-rule-verify using verify-input/ only (no plan/log context).

You can run the full sequence with one reusable prompt:

  • prompts/authoring-rule.md

Usage:

  1. Open prompts/authoring-rule.md.
  2. Replace placeholders: <RULE_ID>, <RULE_IDEA_SHORT_TEXT>, <BASE_REF_OR_EMPTY>.
  3. Paste the prompt into Codex and execute.

Rule docs generation is deterministic:

scripts/generate-rule-docs.sh

This command regenerates docs/rules/index.md and docs/rules/<rule-id>.md.

Bytecode/JDK compatibility

  • Supports JVM class files up to Java 21 (major version 65).
  • Some advanced bytecode attributes may still be skipped in future releases.
  • Some checks (such as the Prefer EnumSet rule for local variables) rely on the LocalVariableTypeTable attribute, which is only present when classes are compiled with debug symbols (for example, javac -g). Field and method signatures are still analyzed without debug info.

Install

Install with Homebrew tap:

brew install KengoTODA/tap/inspequte

Or install a pre-built binary from GitHub Releases:

  • Linux (x86_64): inspequte-<TAG>-amd64-unknown-linux-gnu.tar.gz
  • Linux (ARM64): inspequte-<TAG>-arm64-unknown-linux-gnu.tar.gz
  • macOS (Apple Silicon): inspequte-<TAG>-arm64-apple-darwin.tar.gz
  • macOS (Intel): inspequte-<TAG>-amd64-apple-darwin.tar.gz
  • Windows (x86_64): inspequte-<TAG>-amd64-pc-windows-msvc.zip (TAG is the GitHub release tag, for example inspequte-v0.15.1.)

Example for Linux/macOS:

TAG="$(gh release list --repo KengoTODA/inspequte --exclude-drafts --exclude-pre-releases --limit 1 --json tagName --jq '.[0].tagName')"
TARGET="arm64-apple-darwin" # use amd64-apple-darwin on macOS Intel, arm64-unknown-linux-gnu on Linux ARM64, amd64-unknown-linux-gnu on Linux x86_64
curl -fL -o inspequte.tar.gz \
  "https://github.com/KengoTODA/inspequte/releases/download/${TAG}/inspequte-${TAG}-${TARGET}.tar.gz"
tar -xzf inspequte.tar.gz
chmod +x inspequte
sudo mv inspequte /usr/local/bin/inspequte

Example for Windows (PowerShell):

$Tag = gh release list --repo KengoTODA/inspequte --exclude-drafts --exclude-pre-releases --limit 1 --json tagName --jq '.[0].tagName'
$Asset = "inspequte-$Tag-amd64-pc-windows-msvc.zip"
Invoke-WebRequest -Uri "https://github.com/KengoTODA/inspequte/releases/download/$Tag/$Asset" -OutFile "inspequte.zip"
Expand-Archive -Path "inspequte.zip" -DestinationPath "."
# Move to a directory included in PATH
Move-Item ".\\inspequte.exe" "$HOME\\bin\\inspequte.exe" -Force

macOS note for manual binary downloads (Gatekeeper)

macOS can block directly executing binaries downloaded from the internet (Gatekeeper/quarantine behavior). Follow Apple's official guidance to allow the executable:

For terminal tools, after confirming the binary source from the official release, you can remove the quarantine attribute:

xattr -d com.apple.quarantine /usr/local/bin/inspequte

CLI usage

inspequte --input app.jar --classpath lib/ --output results.sarif

Create a baseline of current findings to suppress them in future runs:

inspequte baseline --input app.jar --classpath lib/ --output inspequte.baseline.json

Run with a baseline to emit only new issues:

inspequte --input app.jar --classpath lib/ --output results.sarif --baseline inspequte.baseline.json

If you omit --baseline output/input paths, .inspequte/baseline.json is used by default; missing files are ignored.

You can read input or classpath lists from a file by prefixing the path with @. The file format is one path per line; empty lines and lines starting with # are ignored.

inspequte --input @inputs.txt --classpath @classpath.txt --output results.sarif

Gradle usage

Use the Gradle plugin:

plugins {
    id("java")
    id("io.github.kengotoda.inspequte") version "<VERSION>"
}

inspequte {
    // Optional: forward OTLP collector URL to inspequte via --otel
    otel.set("http://localhost:4318/v1/traces")
}

// Registered automatically:
// - writeInspequteInputs / writeInspequteInputsTest
// - inspequte / inspequteTest
// Each inspequte task emits:
// build/inspequte/<sourceSet>/report.sarif

The plugin hooks all generated inspequte* tasks into check. The inspequte command must be available in PATH. You can also pass the collector URL from CLI for a task run: ./gradlew inspequte --inspequte-otel http://localhost:8080

SARIF output (example)

{
  "version": "2.1.0",
  "$schema": "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0.json",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "inspequte",
          "informationUri": "https://github.com/KengoTODA/inspequte"
        }
      },
      "results": []
    }
  ]
}

CI integration (GitHub Actions)

Use the Gradle plugin in CI and install the CLI from GitHub Releases:

- name: Install inspequte
  uses: KengoTODA/setup-inspequte@8d212fa51a56245829f88e60f081c6549e312c57
- name: Setup Java
  uses: actions/setup-java@v5
  with:
    distribution: temurin
    java-version: "21"
- name: Setup Gradle
  uses: gradle/actions/setup-gradle@v4
- name: Run inspequte tasks
  run: ./gradlew check --no-daemon
- name: Upload SARIF to GitHub Code Scanning (optional)
  uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: results.sarif

Codex integration

Use Codex to run inspequte, inspect generated SARIF, and propose fixes.

See:

  • docs/codex.md for Codex prompt examples to run inspequte.
  • docs/github-actions.md for GitHub Actions automation examples.

Example prompt for Codex:

Run:
inspequte --input app.jar --classpath lib/ --output results.sarif

Then:
1) Summarize findings by rule ID.
2) Prioritize high-impact issues.
3) Propose patch-ready fixes with file paths.

License

AGPL-3.0. See LICENSE.