Skill: claytantor/pylinter-assist (version 0.6.3)

# pylinter-assist — OpenClaw Skill name: pylinter-assist version: 0.6.3 ## Prerequisites Before installing this skill, ensure you have the following installed: ### Python (via pyenv or system package manager) This project uses standard **pyenv + pip + venv** — no remote install scripts required. **Install pyenv (no `curl | sh`):** ```bash # macOS brew install pyenv # Linux — auditable git clone (can be pinned to a specific commit) git clone https://github.com/pyenv/pyenv.git ~/.pyenv # Then follow https://github.com/pyenv/pyenv#set-up-your-shell-environment ``` **Install Python 3.11 and activate:** ```bash pyenv install 3.11 # reads .python-version automatically if present pyenv local 3.11 # creates .python-version in the project root ``` Alternatively, use any system Python 3.11+ (`python3 --version`) — pyenv is optional if you already have a suitable Python. ### npm (Node.js package manager, for ClawHub CLI) ```bash # macOS/Linux brew install node # or your preferred package manager # Or download from https://nodejs.org/ ``` ### clawhub CLI (OpenClaw skill installer) ```bash npm i -g clawhub ``` ## Description Context-aware Python linting with smart pattern heuristics for PR review. Automatically integrates into GitHub workflows to lint pull requests and provide feedback. ## Features - Combines Pylint with custom pattern checks (hardcoded secrets, missing docstrings, etc.) - Auto-lints PRs when integrated via GitHub Actions - Supports multiple output formats (markdown, text, json) - Configurable rules via `.linting-rules.yml` ## Installation via ClawHub Install the skill using the ClawHub CLI: ```bash clawhub install pylinter-assist ``` The skill will be installed to `~/.openclaw/workspace/skills/pylinter-assist`. ## Integration Steps ### Step 0: Post-Installation Setup After the skill is installed as a snapshot, create a venv and install the CLI: ```bash cd ~/.openclaw/workspace/skills/pylinter-assist python -m venv .venv source .venv/bin/activate pip install -e . ``` This registers the `lint-pr` command for the duration of your shell session. Deactivate when done: `deactivate` ### Step 1: Use the CLI ```bash # Create and activate the virtual environment python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # Install the package and its dependencies pip install -e . # Run the linter lint-pr pr 42 --post-comment ``` Or run the wrapper script directly (no venv activation needed if dependencies are installed): ```bash python scripts/lint_pr.py pr 42 --post-comment ``` ### Step 2: Add GitHub Actions Workflow > **Security warning:** GitHub Actions workflows run with your repository's permissions > and can read secrets. Only commit a workflow file whose full contents you have read > and understood. Never copy a file from a URL without inspecting it first. **Recommended — copy from a local clone** (you can `git log` and `git show` the file before copying; no network fetch at commit time): ```bash git clone https://github.com/claytantor/pylinter-assist.git /tmp/pylinter-assist # Review the workflow source before copying cat /tmp/pylinter-assist/.github/workflows/lint-pr.yml mkdir -p .github/workflows cp /tmp/pylinter-assist/.github/workflows/lint-pr.yml .github/workflows/ ``` **Last resort — direct download.** Pin to a specific commit SHA, not `main`, so the file cannot change under you. Replace `<COMMIT_SHA>` with the exact commit you reviewed on GitHub: ```bash # Find the commit SHA: https://github.com/claytantor/pylinter-assist/commits/main COMMIT_SHA=<COMMIT_SHA> mkdir -p .github/workflows curl -o .github/workflows/lint-pr.yml \ "https://raw.githubusercontent.com/claytantor/pylinter-assist/${COMMIT_SHA}/.github/workflows/lint-pr.yml" # Verify the download — compare against what you saw on GitHub cat .github/workflows/lint-pr.yml sha256sum .github/workflows/lint-pr.yml # record this for future reference ``` ### Step 3: Add Configuration (Optional) Copy and customize the rules file: ```bash cp /path/to/pylinter-assist/.linting-rules.yml .linting-rules.yml ``` ### Step 4: Set Repository Permissions Ensure your repository has these permissions enabled: ```yaml permissions: contents: read pull-requests: write issues: write ``` ### Step 5: Commit and Push The workflow will automatically trigger on new PRs. ## Enabling a New Project for Support > **Security warning:** The workflow file you are about to commit runs with your > repository's permissions and can access secrets. Read every line of the file before > committing. Do not use `curl … | sh` or copy files from a branch tip (`main`) without > pinning to a reviewed commit. **Recommended approach — clone, review, then copy:** ```bash # 1. Clone the skill repo to a temporary location git clone https://github.com/claytantor/pylinter-assist.git /tmp/pylinter-assist # 2. Review the files you are about to add to your repo cat /tmp/pylinter-assist/.github/workflows/lint-pr.yml cat /tmp/pylinter-assist/.linting-rules.yml # 3. Switch to your project and copy the reviewed files cd <your-project-root> git checkout dev git pull origin dev mkdir -p .github/workflows cp /tmp/pylinter-assist/.github/workflows/lint-pr.yml .github/workflows/ cp /tmp/pylinter-assist/.linting-rules.yml .linting-rules.yml # 4. Commit only after you are satisfied with the contents git add .github/workflows/lint-pr.yml .linting-rules.yml git commit -m "ci: add pylinter-assist workflow for PRs targeting dev" git push origin dev ``` The workflow requires these permissions in your repository settings: ```yaml permissions: contents: read pull-requests: write issues: write ``` ## Usage ```bash # Activate venv first source .venv/bin/activate lint-pr [TARGET] [OPTIONS] ``` ### Targets | Target | Description | |--------|-------------| | `pr <number>` | Lint all files changed in a GitHub PR | | `staged` | Lint git-staged files | | `diff <file>` | Lint files from a unified diff file | | `files <path>...` | Lint explicit files or directories | ### Examples ```bash # Activate venv source .venv/bin/activate # Lint PR #42 and post comment lint-pr pr 42 --post-comment # Lint staged changes lint-pr staged # Lint a diff file lint-pr diff /tmp/changes.diff # Lint specific files lint-pr files src/ tests/ ``` ### Options | Flag | Description | |------|-------------| | `--format text\|json\|markdown` | Output format (default: markdown) | | `--config <path>` | Custom `.linting-rules.yml` path | | `--post-comment` / `--no-post-comment` | Post result as GitHub PR comment | | `--fail-on-warning` | Also fail on warnings (default: errors only) | ## Checks Performed | Check | Code | Severity | Catches | |-------|------|----------|---------| | Pylint | C/W/R/E/F | varies | Standard Python quality issues | | Hardcoded password/secret | HCS001 | ERROR | `[REDACTED_SECRET]"` | | Credentials in URL | HCS002 | ERROR | `[REDACTED_SECRET]` | | Hardcoded IP address | HCS003 | ERROR | `HOST = "10.0.0.5"` | | Hardcoded localhost URL | HCS004 | ERROR | `"http://localhost:8000"` | | AWS/GCP access key | HCS005 | ERROR | `[REDACTED_SECRET]` | | FastAPI missing docstring | FAD001 | WARNING | `@router.get("/")` without docstring | | useEffect missing deps | RUE001 | WARNING | React useEffect with no deps array | | useEffect suspicious deps | RUE002 | INFO | useEffect referencing outer vars | ## Configuration Copy `.linting-rules.yml` to your project root and customize: ```yaml pylint: enabled: true disable: [C0114, C0115] # suppress module/class docstring warnings hardcoded_secrets: enabled: true skip_ip_check: false fastapi_docstring: severity: warning react_useeffect_deps: severity: warning github: post_comment: true fail_on_error: true fail_on_warning: false ``` ## Workflow Triggers - **pull_request**: Auto-lints all files changed in a PR - **workflow_dispatch**: Manual trigger via GitHub UI or API ## Manual Trigger Examples **GitHub CLI (preferred — token is handled by `gh auth`, not exposed in shell):** ```bash gh workflow run lint-pr.yml -f pr_number=42 -f format=markdown -f post_comment=true ``` **REST API:** > **Security note:** The token passed via `-H "Authorization: token $GITHUB_TOKEN"` must > be a Personal Access Token or a fine-grained token scoped to `actions:write`. Never > hard-code the token value in scripts; always expand it from an environment variable. ```bash curl -X POST \ -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/OWNER/REPO/actions/workflows/lint-pr.yml/dispatches \ -d '{"ref":"main","inputs":{"pr_number":"42","format":"markdown","post_comment":"true"}}' ``` ## Output - Markdown reports posted as PR comments (when enabled) - JSON artifacts uploaded for 14 days retention - Exit code 1 if errors found (when `fail_on_error: true`) ## Troubleshooting ### `command not found: lint-pr` after installation The `lint-pr` CLI is installed inside the virtual environment. Either activate it or call it directly: ```bash # Activate the venv source .venv/bin/activate # Or call it directly without activation ./.venv/bin/lint-pr pr 42 ``` ### `python3: command not found` or wrong Python version Ensure Python 3.11+ is installed and on your PATH: ```bash python3 --version # If using pyenv, install the required version pyenv install # reads .python-version automatically pyenv versions # list installed versions ``` ### `pip install -e .` fails Ensure the venv is activated before installing: ```bash python -m venv .venv source .venv/bin/activate pip install -e . ``` ## GitHub Actions Monitoring The skill can automatically monitor GitHub Actions workflow runs and notify you when lint results are ready. ### Monitor a Repository Use the `monitor` command to watch for completed workflow runs: ```bash # Basic monitoring - download report only lint-pr monitor owner/repo --token $GITHUB_TOKEN # Monitor with timeout and custom polling interval lint-pr monitor owner/repo --token $GITHUB_TOKEN --timeout 3600 --poll-interval 60 ``` > **Security note:** Avoid passing secrets (bot tokens, webhook URLs) directly as > `--callback` command-line arguments — they are visible in process listings (`ps aux`). > Prefer setting notification credentials in `.linting-rules.yml` with values read from > environment variables, or ensure your shell history is protected before using the > `--callback` flag. ```bash # Monitor with Telegram notification (tokens visible in process list — use with caution) lint-pr monitor owner/repo --token $GITHUB_TOKEN \ --callback telegram:$TELEGRAM_BOT_TOKEN:$TELEGRAM_CHAT_ID # Monitor with Discord notification lint-pr monitor owner/repo --token $GITHUB_TOKEN \ --callback discord:$DISCORD_WEBHOOK_URL # Monitor with multiple channels lint-pr monitor owner/repo --token $GITHUB_TOKEN \ --callback telegram:$TELEGRAM_BOT_TOKEN:$TELEGRAM_CHAT_ID \ --callback discord:$DISCORD_WEBHOOK_URL ``` ### Configuration Enable notifications in `.linting-rules.yml`: ```yaml notifications: enabled: true channels: - type: telegram bot_token: $TELEGRAM_BOT_TOKEN chat_id: 123456789 - type: discord webhook_url: https://discord.com/api/webhooks/... username: "Lint Bot" - type: slack webhook_url: https://hooks.slack.com/services/... ``` ### Monitoring Configuration ```yaml github_actions: polling_interval: 30 # Seconds between status checks max_timeout: 1800 # Max seconds to wait (30 minutes) retry_attempts: 3 # Retry failed API calls ``` ### Supported Notification Channels | Channel | Setup | |---------|-------| | Telegram | Create bot via @BotFather, get chat_id from bot | | Discord | Create webhook in channel settings | | Slack | Create incoming webhook in apps | | Email | Configure SMTP server credentials | ### Error Handling The monitoring system handles: - **API rate limiting** (429): Exponential backoff with `Retry-After` header - **Missing artifacts**: Retry 3x with 10s delay, then fail gracefully - **Network timeouts**: Retry up to 3 attempts with increasing timeout - **Invalid tokens**: Clear error message with validation hint ### Workflow Integration When enabled in a repository, the workflow automatically: 1. Runs lint on PRs or manual trigger 2. Uploads `lint-report.json` as artifact 3. Can be monitored externally via the `monitor` command 4. Sends notifications when results are ready See [Enabling a New Project for Support](#enabling-a-new-project-for-support) to set up monitoring in your repository. ```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: stale | SkillSpector: clean (LOW)