@sentry/warden 0.0.0

package/docs/src/pages/config.astro

@@ -0,0 +1,394 @@
+---
+import Base from '../layouts/Base.astro';
+import Terminal from '../components/Terminal.astro';
+import { Code } from 'astro:components';
+---
+
+<Base title="Config" description="Warden configuration reference">
+  <h1>Config</h1>
+
+  <p>Warden is configured via <code>warden.toml</code> in your repository root.</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`version = 1
+
+[[triggers]]
+name = "Security Review"
+event = "pull_request"
+actions = ["opened", "synchronize"]
+skill = "security-review"`}
+      lang="toml"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h2>Triggers</h2>
+
+  <p>Triggers map GitHub events to skills.</p>
+
+  <dl>
+    <dt>name</dt>
+    <dd>Display name</dd>
+    <dt>event</dt>
+    <dd><code>pull_request</code>, <code>issues</code>, <code>issue_comment</code>, <code>schedule</code></dd>
+    <dt>actions</dt>
+    <dd>Event actions (required except for <code>schedule</code>)</dd>
+    <dt>skill</dt>
+    <dd>Skill name or path to run (see <a href="#skill-references">Skill References</a>)</dd>
+    <dt>remote</dt>
+    <dd>GitHub repository for remote skills: <code>owner/repo</code> or <code>owner/repo@sha</code></dd>
+    <dt>model</dt>
+    <dd>Model override (optional)</dd>
+    <dt>maxTurns</dt>
+    <dd>Max agentic turns per hunk (optional)</dd>
+  </dl>
+
+  <h3>Pull Request Actions</h3>
+
+  <dl>
+    <dt>opened</dt>
+    <dd>PR created</dd>
+    <dt>synchronize</dt>
+    <dd>New commits pushed</dd>
+    <dt>reopened</dt>
+    <dd>PR reopened</dd>
+    <dt>closed</dt>
+    <dd>PR closed or merged</dd>
+  </dl>
+
+  <h2>Filters</h2>
+
+  <p>Control which files are analyzed using glob patterns.</p>
+
+  <dl>
+    <dt>paths</dt>
+    <dd>Files to include</dd>
+    <dt>ignorePaths</dt>
+    <dd>Files to exclude</dd>
+  </dl>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`[[triggers]]
+name = "API Review"
+event = "pull_request"
+actions = ["opened", "synchronize"]
+skill = "api-review"
+
+[triggers.filters]
+paths = ["src/api/**/*.ts"]
+ignorePaths = ["**/*.test.ts"]`}
+      lang="toml"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h2>Output</h2>
+
+  <p>Control how findings are reported.</p>
+
+  <dl>
+    <dt>failOn</dt>
+    <dd>Minimum severity to fail: <code>critical</code>, <code>high</code>, <code>medium</code>, <code>low</code>, <code>info</code>, <code>off</code></dd>
+    <dt>commentOn</dt>
+    <dd>Minimum severity to post as comment</dd>
+    <dt>maxFindings</dt>
+    <dd>Maximum findings to report</dd>
+    <dt>commentOnSuccess</dt>
+    <dd>Post comment when no findings. Default: <code>false</code></dd>
+  </dl>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`[triggers.output]
+failOn = "high"
+commentOn = "medium"
+maxFindings = 20`}
+      lang="toml"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h2>Defaults</h2>
+
+  <p>Default settings inherited by all triggers. Individual triggers can override any setting.</p>
+
+  <dl>
+    <dt>model</dt>
+    <dd>Model for all triggers</dd>
+    <dt>maxTurns</dt>
+    <dd>Max agentic turns per hunk. Default: 50</dd>
+    <dt>defaultBranch</dt>
+    <dd>Repository default branch (auto-detected)</dd>
+    <dt>filters</dt>
+    <dd>Default path filters</dd>
+    <dt>output</dt>
+    <dd>Default output settings</dd>
+    <dt>chunking</dt>
+    <dd>File processing configuration</dd>
+  </dl>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`[defaults]
+model = "claude-sonnet-4-20250514"
+maxTurns = 30
+
+[defaults.filters]
+ignorePaths = ["**/vendor/**", "**/node_modules/**"]
+
+[defaults.output]
+failOn = "high"
+commentOn = "medium"`}
+      lang="toml"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h2>Chunking</h2>
+
+  <p>Control how files are split for analysis. By default, Warden analyzes each hunk separately.</p>
+
+  <h3>File Patterns</h3>
+
+  <dl>
+    <dt>per-hunk</dt>
+    <dd>Analyze each diff hunk separately (default)</dd>
+    <dt>whole-file</dt>
+    <dd>Analyze entire file as one chunk</dd>
+    <dt>skip</dt>
+    <dd>Skip the file entirely</dd>
+  </dl>
+
+  <h3>Coalescing</h3>
+
+  <p>Merge nearby hunks for better context.</p>
+
+  <dl>
+    <dt>enabled</dt>
+    <dd>Enable hunk coalescing. Default: <code>true</code></dd>
+    <dt>maxGapLines</dt>
+    <dd>Max lines between hunks to merge. Default: 30</dd>
+    <dt>maxChunkSize</dt>
+    <dd>Target max chunk size in characters. Default: 8000</dd>
+  </dl>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`[defaults.chunking]
+
+[[defaults.chunking.filePatterns]]
+pattern = "**/pnpm-lock.yaml"
+mode = "skip"
+
+[[defaults.chunking.filePatterns]]
+pattern = "**/migrations/*.sql"
+mode = "whole-file"
+
+[defaults.chunking.coalesce]
+enabled = true
+maxGapLines = 50
+maxChunkSize = 10000`}
+      lang="toml"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h2>Schedule Triggers</h2>
+
+  <p>Run on a cron schedule instead of PR events. Requires <code>filters.paths</code> to specify which files to scan.</p>
+
+  <dl>
+    <dt>issueTitle</dt>
+    <dd>Title for the tracking issue. Default: "Warden: {'{name}'}"</dd>
+    <dt>createFixPR</dt>
+    <dd>Create PR with fixes when available. Default: <code>false</code></dd>
+    <dt>fixBranchPrefix</dt>
+    <dd>Branch prefix for fix PRs. Default: <code>warden-fix</code></dd>
+  </dl>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`[[triggers]]
+name = "Weekly Security Scan"
+event = "schedule"
+skill = "security-review"
+
+[triggers.filters]
+paths = ["src/**/*.ts"]
+
+[triggers.schedule]
+createFixPR = true`}
+      lang="toml"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h2>Environment Variables</h2>
+
+  <dl>
+    <dt>WARDEN_ANTHROPIC_API_KEY</dt>
+    <dd>Anthropic API key (required)</dd>
+    <dt>WARDEN_MODEL</dt>
+    <dd>Model override</dd>
+    <dt>WARDEN_SKILL_CACHE_TTL</dt>
+    <dd>Cache duration for unpinned remote skills. Default: 24h</dd>
+  </dl>
+
+  <h2 id="skill-references">Skill References</h2>
+
+  <p>Skills can be referenced in multiple ways:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`# By name (resolved from .warden/skills/, .agents/skills/, .claude/skills/)
+[[triggers]]
+skill = "security-review"
+
+# By relative path
+[[triggers]]
+skill = "./custom-skills/my-review"
+
+# Remote skill (unpinned - checks for updates every 24h)
+[[triggers]]
+skill = "security-review"
+remote = "getsentry/warden-skills"
+
+# Remote skill (pinned to commit - cached permanently)
+[[triggers]]
+skill = "security-review"
+remote = "getsentry/warden-skills@abc123def"`}
+      lang="toml"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h3>Resolution Order</h3>
+
+  <ol>
+    <li>Remote repository (if <code>remote</code> field is specified)</li>
+    <li>Direct path (if skill contains <code>/</code>, <code>\</code>, or starts with <code>.</code>)</li>
+    <li>Conventional directories (first match wins)</li>
+  </ol>
+
+  <h2>Skills</h2>
+
+  <p>Skills define what Warden analyzes. They follow the <a href="https://agentskills.io">agentskills.io</a> specification.</p>
+
+  <h3>Skill Directories</h3>
+
+  <p>Warden discovers skills from these directories (first match wins):</p>
+
+  <dl>
+    <dt>.warden/skills/</dt>
+    <dd>Warden-specific skills (highest priority)</dd>
+    <dt>.agents/skills/</dt>
+    <dd>Shared agent skills</dd>
+    <dt>.claude/skills/</dt>
+    <dd>Claude Code skills</dd>
+  </dl>
+
+  <h3>SKILL.md Format</h3>
+
+  <p>Create a directory with a <code>SKILL.md</code> file:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`.agents/skills/
+└── security-review/
+    └── SKILL.md`}
+      lang="text"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <p>The <code>SKILL.md</code> file uses YAML frontmatter for metadata and markdown for the prompt:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`---
+name: security-review
+description: Review code for security vulnerabilities
+allowed-tools: Read Grep Glob
+---
+
+Review the code for security issues including:
+- SQL injection
+- XSS vulnerabilities
+- Hardcoded secrets
+- Insecure dependencies`}
+      lang="markdown"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <dl>
+    <dt>name</dt>
+    <dd>Skill name (referenced by triggers)</dd>
+    <dt>description</dt>
+    <dd>Brief description</dd>
+    <dt>allowed-tools</dt>
+    <dd>Space-separated tool names (optional)</dd>
+  </dl>
+
+  <h3>Available Tools</h3>
+
+  <p><code>Read</code>, <code>Grep</code>, <code>Glob</code>, <code>Edit</code>, <code>Write</code>, <code>Bash</code>, <code>WebFetch</code>, <code>WebSearch</code></p>
+
+  <h2 id="workflow">Workflow</h2>
+
+  <p>The workflow generated by <code>warden init</code>. Uncomment the GitHub App section for branded comments.</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`name: Warden
+
+permissions:
+  contents: read
+  pull-requests: write
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+env:
+  WARDEN_ANTHROPIC_API_KEY: \${{ secrets.WARDEN_ANTHROPIC_API_KEY }}
+
+jobs:
+  warden:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Uncomment for GitHub App (branded comments)
+      # - uses: actions/create-github-app-token@v1
+      #   id: app-token
+      #   with:
+      #     app-id: \${{ secrets.WARDEN_APP_ID }}
+      #     private-key: \${{ secrets.WARDEN_PRIVATE_KEY }}
+
+      - uses: getsentry/warden-action@v1
+        with:
+          github-token: \${{ secrets.GITHUB_TOKEN }}
+          # github-token: \${{ steps.app-token.outputs.token }}`}
+      lang="yaml"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h3>Action Inputs</h3>
+
+  <dl>
+    <dt>github-token</dt>
+    <dd>GitHub token for posting comments. Default: <code>GITHUB_TOKEN</code></dd>
+    <dt>anthropic-api-key</dt>
+    <dd>Anthropic API key (falls back to <code>WARDEN_ANTHROPIC_API_KEY</code>)</dd>
+    <dt>config-path</dt>
+    <dd>Path to config file. Default: <code>warden.toml</code></dd>
+    <dt>fail-on</dt>
+    <dd>Minimum severity to fail the check</dd>
+    <dt>comment-on</dt>
+    <dd>Minimum severity to post comments</dd>
+  </dl>
+</Base>