From aaef3952e78d53cda6a40d1282ffa44a37230e74 Mon Sep 17 00:00:00 2001 From: CTO Hermes Date: Sun, 31 May 2026 17:50:58 +0700 Subject: [PATCH] =?UTF-8?q?docs:=20fix=20all=20documentation=20issues=20?= =?UTF-8?q?=E2=80=94=20schema,=20flags,=20URLs,=20env=20vars,=20structure?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 54 ++++++++++--- README.md | 208 ++++++++++++++++++++++++++---------------------- 2 files changed, 155 insertions(+), 107 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd6274c..bb7a822 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,7 @@ Be respectful, constructive, and inclusive. We follow the [Rust Code of Conduct] ### Prerequisites -- **Rust** 1.75+ (stable toolchain recommended) +- **Rust 1.85+** (stable toolchain recommended) - **Git** for version control - An **LLM API key** (OpenAI, Anthropic, etc.) for testing review features @@ -47,14 +47,43 @@ cargo clippy -- -D warnings ``` cora-cli/ ├── src/ -│ ├── main.rs # CLI entry point -│ ├── cli.rs # Argument parsing (clap) -│ ├── config.rs # Configuration management -│ ├── scanner.rs # File scanning and diff generation -│ ├── reviewer.rs # LLM integration for code review -│ ├── formatter.rs # Output formatting -│ └── ci.rs # CI/CD integration helpers -├── tests/ # Integration tests +│ ├── main.rs # CLI entry point +│ ├── commands/ # CLI subcommand handlers +│ │ ├── mod.rs +│ │ ├── review.rs # cora review +│ │ ├── scan.rs # cora scan +│ │ ├── upload.rs # cora upload-sarif +│ │ ├── auth.rs # cora auth +│ │ ├── hook_cmd.rs # cora hook +│ │ ├── init.rs # cora init +│ │ ├── completion.rs # cora completion +│ │ └── providers.rs # cora providers +│ ├── config/ # Configuration loading & schema +│ │ ├── mod.rs +│ │ ├── schema.rs # Config struct definitions +│ │ ├── loader.rs # Config file discovery & loading +│ │ └── providers.rs # Provider auto-detection +│ ├── engine/ # Core review/scanning engine +│ │ ├── mod.rs +│ │ ├── llm.rs # LLM API client +│ │ ├── review.rs # Diff review logic +│ │ ├── scanner.rs # Project scanning logic +│ │ └── types.rs # Shared types (Severity, Findings, etc.) +│ ├── formatters/ # Output formatting +│ │ ├── mod.rs +│ │ ├── pretty.rs # Pretty-printed terminal output +│ │ ├── compact.rs # Compact single-line output +│ │ ├── json_fmt.rs # JSON output +│ │ └── sarif.rs # SARIF output +│ ├── git/ # Git operations +│ │ ├── mod.rs +│ │ ├── diff.rs # Diff generation +│ │ └── files.rs # File discovery +│ └── hook/ # Git hook management +│ ├── mod.rs +│ ├── install.rs # Hook install/uninstall +│ └── template.rs # Hook script template +├── tests/ # Integration tests ├── Cargo.toml └── README.md ``` @@ -68,7 +97,7 @@ cora-cli/ ``` 3. **Make your changes** and commit with meaningful messages: ```bash - git commit -s -m "feat: add support for SARIF output format" + git commit -m "feat: add support for SARIF output format" ``` 4. **Push** to your fork and open a **Pull Request** @@ -94,6 +123,7 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/): 4. Ensure `cargo clippy -- -D warnings` is clean 5. Ensure `cargo fmt` has been applied 6. Keep PRs focused — one logical change per PR +7. **CI will automatically run cora on your PR** — all findings must be addressed or the PR will be blocked ## Coding Standards @@ -124,8 +154,8 @@ Please open a [GitHub Issue](https://github.com/ajianaz/cora-cli/issues/new) wit - **Description** — What happened vs. what you expected - **Steps to reproduce** — Minimal reproduction steps -- **Environment** — OS, Rust version, cora-cli version -- **Logs** — Output with `RUST_LOG=debug cora review` +- **Environment** — OS, Rust version, cora-cli version (`cora --version`) +- **Logs** — Output with `cora --verbose review` ## Feature Requests diff --git a/README.md b/README.md index a24ddcf..c5901b7 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ ## ✨ Features - 🔍 **Git-Aware Scanning** — Automatically detects staged, committed, or changed files -- 🤖 **Multi-LLM Support** — Works with OpenAI, Anthropic, Google, and any OpenAI-compatible API +- 🤖 **Multi-LLM Support** — Works with OpenAI, Anthropic, Google, Ollama, and any OpenAI-compatible API - 🎨 **Beautiful Output** — Colorized, structured review output with severity levels - 🏗️ **CI/CD Ready** — Designed for GitHub Actions, GitLab CI, and any pipeline - ⚡ **Fast & Lightweight** — Native Rust binary, no runtime dependencies @@ -35,33 +35,34 @@ cargo install cora-cli ``` -### Homebrew - -```bash -brew tap ajianaz/tap -brew install cora-cli -``` - ### Binary Download Download the latest release from [GitHub Releases](https://github.com/ajianaz/cora-cli/releases): ```bash -# Linux x86_64 -curl -L https://github.com/ajianaz/cora-cli/releases/latest/download/cora-linux-x86_64.tar.gz | tar xz +# Determine your platform tag from the releases page, e.g.: +# cora-aarch64-unknown-linux-gnu-v0.1.2.tar.gz +# cora-x86_64-unknown-linux-gnu-v0.1.2.tar.gz +# cora-aarch64-apple-darwin-v0.1.2.tar.gz +# cora-x86_64-apple-darwin-v0.1.2.tar.gz +# cora-x86_64-pc-windows-msvc-v0.1.2.zip + +# Example: Linux aarch64 +VERSION=$(curl -s https://api.github.com/repos/ajianaz/cora-cli/releases/latest | grep tag_name | cut -d'"' -f4) +curl -L "https://github.com/ajianaz/cora-cli/releases/download/${VERSION}/cora-aarch64-unknown-linux-gnu-${VERSION}.tar.gz" | tar xz +sudo mv cora /usr/local/bin/ +``` -# macOS ARM (Apple Silicon) -curl -L https://github.com/ajianaz/cora-cli/releases/latest/download/cora-macos-aarch64.tar.gz | tar xz +> **Tip:** Visit the [Releases page](https://github.com/ajianaz/cora-cli/releases) to find the correct asset name for your platform. -# macOS x86_64 (Intel) -curl -L https://github.com/ajianaz/cora-cli/releases/latest/download/cora-macos-x86_64.tar.gz | tar xz +### Homebrew -# Windows x86_64 -curl -L https://github.com/ajianaz/cora-cli/releases/latest/download/cora-windows-x86_64.tar.gz | tar xz -``` +> 🚧 Homebrew tap is planned — check back soon! ### Build from Source +Requires **Rust 1.85+**. + ```bash git clone https://github.com/ajianaz/cora-cli.git cd cora-cli @@ -78,16 +79,16 @@ export OPENAI_API_KEY="sk-..." export ANTHROPIC_API_KEY="sk-ant-..." ``` -### 2. Review Staged Changes +### 2. Initialize Config (Optional) ```bash -cora review +cora init ``` -### 3. Review a Specific File +### 3. Review Staged Changes ```bash -cora review src/main.rs +cora review ``` ### 4. Review the Last Commit @@ -99,7 +100,7 @@ cora review --commit HEAD ### 5. Scan the Entire Project ```bash -cora scan . +cora scan ``` ## 📖 Commands @@ -109,29 +110,35 @@ cora scan . Review code changes using an LLM. ```bash -# Review staged files +# Review staged files (default) cora review -# Review specific files -cora review src/main.rs src/lib.rs +# Review unpushed changes +cora review --unpushed # Review a range of commits cora review --commit HEAD~3..HEAD -# Review a pull request diff +# Review changes vs a base branch +cora review --base origin/main + +# Review a pull request diff from a file cora review --diff-file pr.diff # Use a specific model cora review --model gpt-4o -# Output as SARIF (for CI) -cora review --output sarif --output-file results.sarif +# Output as SARIF +cora review --format sarif # Output as JSON -cora review --output json +cora review --format json + +# Upload SARIF to GitHub Code Scanning (implies --format sarif) +cora review --upload # Set severity threshold -cora review --severity warning +cora review --severity major # Quiet mode (machine-readable) cora review --quiet @@ -143,16 +150,19 @@ Scan files for code quality issues without requiring git context. ```bash # Scan current directory -cora scan . +cora scan -# Scan specific files -cora scan src/**/*.rs +# Scan a specific directory +cora scan --path src/ -# Scan with custom rules focus -cora scan . --focus security,performance +# Scan with focus areas +cora scan --focus security,performance # Exclude patterns -cora scan . --exclude "tests/**" --exclude "examples/**" +cora scan --exclude "tests/**" --exclude "examples/**" + +# Only scan changed files (incremental) +cora scan --incremental ``` ### `cora config` @@ -163,12 +173,17 @@ Manage configuration. # Show current configuration cora config show -# Initialize config file -cora config init - # Set a configuration value cora config set model claude-sonnet-4-20250514 -cora config set severity error +cora config set severity major +``` + +### `cora init` + +Create a `.cora.yaml` config file in the current directory. + +```bash +cora init ``` ### `cora completion` @@ -181,47 +196,58 @@ cora completion zsh > ~/.cora-completion.zsh cora completion fish > ~/.cora-completion.fish ``` +### `cora hook` + +Manage pre-commit git hooks. + +```bash +cora hook install +cora hook uninstall +``` + ## ⚙️ Configuration Create a `.cora.yaml` in your project root or `~/.config/cora/config.yaml` globally: ```yaml # .cora.yaml -model: gpt-4o -temperature: 0.1 # Provider configuration provider: - name: openai # openai | anthropic | google | custom - base_url: null # Override API endpoint (for custom/self-hosted) - api_key_env: OPENAI_API_KEY # Environment variable for API key - -# Review settings -review: - severity: warning # error | warning | info | note - focus: # Focus areas (empty = all) - - security - - performance - - maintainability - ignore: - patterns: - - "tests/**" - - "vendor/**" - - "*.generated.*" - rules: - - "line-too-long" - max_tokens: 4096 - language: en # Response language + provider: openai # openai | anthropic | google | ollama | custom + model: gpt-4o-mini + base_url: https://api.openai.com/v1 # Override for custom/self-hosted endpoints + +# Focus areas for review (empty = all) +focus: + - security + - performance + - bugs + - best_practice + +# Custom rules +rules: + - "no unwrap" + +# Ignore configuration +ignore: + files: + - "tests/**" + - "vendor/**" + - "*.generated.*" + rules: + - "skip-rule-1" + +# Hook configuration +hook: + mode: warn # warn | block + min_severity: major # info | minor | major | critical + max_diff_size: 51200 # Max diff size in bytes (50 KB) # Output settings output: - format: colored # colored | plain | json | sarif - file: null # Output to file instead of stdout - -# Git settings -git: - auto_stage: false # Auto-stage files after review - base_branch: main # Base branch for PR reviews + format: pretty # pretty | json | compact | sarif + color: true ``` ### Environment Variables @@ -231,10 +257,13 @@ git: | `OPENAI_API_KEY` | OpenAI API key | — | | `ANTHROPIC_API_KEY` | Anthropic API key | — | | `GOOGLE_API_KEY` | Google AI API key | — | -| `CORa_MODEL` | Override model | — | -| `CORa_PROVIDER` | Override provider | — | -| `CORa_CONFIG` | Path to config file | `.cora.yaml` | -| `CORa_LOG_LEVEL` | Log verbosity | `info` | +| `CORA_API_KEY` | API key (overrides provider-specific keys) | — | +| `CORA_MODEL` | Override model | — | +| `CORA_PROVIDER` | Override provider | — | +| `CORA_BASE_URL` | Override API base URL | — | +| `CORA_CONFIG` | Path to config file | `.cora.yaml` | +| `CORA_FORMAT` | Output format (`pretty`, `json`, `compact`, `sarif`) | `pretty` | +| `CORA_NO_COLOR` | Disable colored output | — | ## 🔗 CI/CD Integration @@ -257,21 +286,16 @@ jobs: fetch-depth: 0 - name: Install cora-cli - run: cargo install cora-cli + run: | + VERSION=$(curl -s https://api.github.com/repos/ajianaz/cora-cli/releases/latest | grep tag_name | cut -d'"' -f4) + curl -L "https://github.com/ajianaz/cora-cli/releases/download/${VERSION}/cora-x86_64-unknown-linux-gnu-${VERSION}.tar.gz" | tar xz + sudo mv cora /usr/local/bin/ - name: Run code review env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} - run: | - cora review --commit origin/main..HEAD \ - --output sarif \ - --output-file results.sarif - - - name: Upload SARIF to GitHub Code Scanning - if: always() - uses: github/codeql-action/upload-sarif@v3 - with: - sarif_file: results.sarif + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: cora review --base origin/main --upload ``` ### GitLab CI @@ -284,7 +308,7 @@ code-review: before_script: - cargo install cora-cli script: - - cora review --commit origin/main..HEAD --severity error + - cora review --base origin/main --severity major variables: OPENAI_API_KEY: $CI_OPENAI_API_KEY rules: @@ -311,7 +335,7 @@ Or add it manually to `.git/hooks/pre-commit`: ```bash #!/bin/sh # cora-cli pre-commit hook -cora review --quiet --severity error +cora review --quiet --severity major if [ $? -ne 0 ]; then echo "❌ Code review found critical issues. Commit blocked." echo " Run 'cora review' to see details, or use 'git commit --no-verify' to skip." @@ -321,15 +345,7 @@ fi ### With [pre-commit](https://pre-commit.com) framework -```yaml -# .pre-commit-config.yaml -repos: - - repo: https://github.com/ajianaz/cora-cli - rev: v0.1.0 - hooks: - - id: cora-review - args: ['--severity', 'warning'] -``` +> 🚧 Planned — the pre-commit hook repo will be available soon. For now, use `cora hook install` directly. ## 🆚 Positioning: How Cora Compares @@ -354,6 +370,8 @@ repos: ## 🛠️ Development +Requires **Rust 1.85+**. + ```bash # Build cargo build