ci-triage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 clankamode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# ci-triage
+
+Open-source CI failure triage for humans and agents. Parses CI logs, classifies failures, detects flaky tests, and outputs structured JSON — with an MCP server for coding agents.
+
+## Why
+
+When CI fails, everyone does the same dance: open the run, scroll logs, squint at errors. Coding agents have it worse — they can't scroll. **ci-triage** gives both humans and agents structured, queryable failure data.
+
+## Features
+
+- 🔍 **Smart log parsing** — extracts errors, file:line references, stack traces from GitHub Actions logs
+- 🏷️ **Failure classification** — 16 categories with severity levels and confidence scores
+- 🧪 **Flake detection** — compares against run history to distinguish flaky from real failures
+- 📋 **JUnit XML support** — parses standard test result files
+- 📊 **Structured JSON output** — agent-consumable schema with full failure context
+- 🤖 **MCP server** — coding agents (Codex, Claude Code) can query failures programmatically
+- 🔧 **GitHub Action** — drop into any workflow with PR comments and artifacts
+
+## Quick Start
+
+### CLI
+```bash
+# Install
+npm install -g ci-triage
+
+# Triage the most recent failed run
+ci-triage owner/repo
+
+# JSON output (for agents)
+ci-triage owner/repo --json
+
+# Triage a specific run
+ci-triage owner/repo --run 12345
+
+# Save markdown report
+ci-triage owner/repo --md triage.md
+```
+
+### GitHub Action
+```yaml
+- uses: clankamode/ci-triage@v1
+  with:
+    token: ${{ secrets.GITHUB_TOKEN }}
+    flake-detect: true
+    comment: true
+    json-artifact: true
+```
+
+### MCP Server (for coding agents)
+
+**Codex CLI** (`~/.codex/config.toml`):
+```toml
+[mcp-servers.ci-triage]
+command = "npx"
+args = ["-y", "ci-triage", "--mcp"]
+```
+
+**Claude Code**:
+```bash
+claude mcp add ci-triage npx -y ci-triage --mcp
+```
+
+**Tools exposed:**
+| Tool | Description |
+|------|-------------|
+| `triage_run` | Full triage report for a CI run |
+| `list_failures` | Recent failed runs summary |
+| `is_flaky` | Flake history for a specific test |
+| `suggest_fix` | Fix suggestions for failures |
+
+## Output Schema
+
+```json
+{
+  "version": "1.0",
+  "repo": "owner/repo",
+  "run_id": 12345,
+  "run_url": "https://github.com/...",
+  "commit": "abc1234",
+  "branch": "feat/something",
+  "status": "failed",
+  "jobs": [{
+    "name": "test",
+    "status": "failed",
+    "steps": [{
+      "name": "Run tests",
+      "failures": [{
+        "category": "assertion_error",
+        "severity": "medium",
+        "error": "Expected 42 but received undefined",
+        "file": "src/foo.test.ts",
+        "line": 42,
+        "flaky": { "is_flaky": true, "confidence": 0.92 },
+        "suggested_fix": "Check null handling in Foo.validate()"
+      }]
+    }]
+  }],
+  "summary": {
+    "total_failures": 1,
+    "flaky_count": 1,
+    "real_count": 0,
+    "root_cause": "Flaky assertion in Foo.validate"
+  }
+}
+```
+
+## Failure Categories
+
+| Category | Severity | Description |
+|----------|----------|-------------|
+| `oom` | critical | Out of memory / heap exhaustion |
+| `port_conflict` | high | Address already in use |
+| `permission_error` | high | EACCES / permission denied |
+| `module_not_found` | high | Missing dependency or import |
+| `assertion_error` | medium | Test failure / assertion mismatch |
+| `docker_error` | high | Container / image failure |
+| `network_error` | medium | Connection refused / timeout |
+| `missing_env` | high | Missing environment variable |
+| `missing_file` | medium | File or artifact not found |
+| `rate_limited` | medium | HTTP 429 / rate limiting |
+| `missing_lockfile` | high | Lockfile not committed |
+| `dependency_security` | high | Vulnerable dependency |
+| `timeout` | medium | Step or job timeout |
+| `lint_error` | low | Linter / formatter failure |
+| `type_error` | high | TypeScript / compilation error |
+| `unknown` | low | Unrecognized (manual triage) |
+
+## Development
+
+```bash
+git clone https://github.com/clankamode/ci-triage
+cd ci-triage
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT
+
+## Credits
+
+Built by [Clanka](https://clankamode.github.io) ⚡ — an autonomous engineer.

package/action.yml

@@ -0,0 +1,67 @@
+name: "CI Triage"
+description: "Automated CI failure triage with flake detection"
+inputs:
+  token:
+    description: "GitHub token for API access"
+    required: true
+  flake-detect:
+    description: "Enable flake detection"
+    required: false
+    default: "true"
+  comment:
+    description: "Post or update a PR comment"
+    required: false
+    default: "true"
+  json-artifact:
+    description: "Upload JSON report as artifact"
+    required: false
+    default: "true"
+  history-depth:
+    description: "Number of historical runs to inspect"
+    required: false
+    default: "20"
+outputs:
+  report-json:
+    description: "Raw triage report JSON string"
+    value: ${{ steps.triage.outputs.report-json }}
+  status:
+    description: "Triage status (pass/fail/flaky)"
+    value: ${{ steps.triage.outputs.status }}
+  failure-count:
+    description: "Total number of failures"
+    value: ${{ steps.triage.outputs.failure-count }}
+runs:
+  using: "composite"
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: "20"
+
+    - name: Install dependencies
+      shell: bash
+      run: npm ci
+
+    - name: Build
+      shell: bash
+      run: npm run build
+
+    - name: Run triage
+      id: triage
+      shell: bash
+      env:
+        INPUT_TOKEN: ${{ inputs.token }}
+        GH_TOKEN: ${{ inputs.token }}
+        GITHUB_TOKEN: ${{ inputs.token }}
+        CI_TRIAGE_FLAKE_DETECT: ${{ inputs.flake-detect }}
+        CI_TRIAGE_COMMENT: ${{ inputs.comment }}
+        CI_TRIAGE_JSON_ARTIFACT: ${{ inputs.json-artifact }}
+        CI_TRIAGE_HISTORY_DEPTH: ${{ inputs.history-depth }}
+      run: node dist/action.js
+
+    - name: Upload triage JSON artifact
+      if: ${{ inputs.json-artifact == 'true' && steps.triage.outputs.artifact-path != '' }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: ci-triage-report
+        path: ${{ steps.triage.outputs.artifact-path }}

package/dist/action.js

@@ -0,0 +1,104 @@
+import { execFileSync } from 'node:child_process';
+import { appendFileSync } from 'node:fs';
+import { formatComment } from './comment.js';
+import { getPRForRun, postOrUpdateComment, uploadArtifact } from './github.js';
+function parseBool(value, defaultValue) {
+    if (!value)
+        return defaultValue;
+    return value.toLowerCase() === 'true';
+}
+function flattenFailures(job) {
+    if (job.failures)
+        return job.failures;
+    const out = [];
+    for (const step of job.steps ?? []) {
+        for (const failure of step.failures ?? []) {
+            out.push(failure);
+        }
+    }
+    return out;
+}
+function asReport(raw, repo, runId) {
+    if (raw && typeof raw === 'object' && 'summary' in raw && 'jobs' in raw && 'status' in raw) {
+        return raw;
+    }
+    const rows = Array.isArray(raw) ? raw : [];
+    const jobs = rows.map((row, idx) => ({
+        name: row.workflowName ?? `failed-job-${idx + 1}`,
+        status: 'failed',
+        failures: [
+            {
+                test_name: row.displayTitle ?? 'Unknown failure',
+                error: row.cause ?? 'Unknown cause',
+                suggested_fix: row.fix,
+            },
+        ],
+    }));
+    const total = jobs.reduce((acc, job) => acc + flattenFailures(job).length, 0);
+    return {
+        version: '1.0',
+        repo,
+        run_id: runId,
+        timestamp: new Date().toISOString(),
+        status: total > 0 ? 'fail' : 'pass',
+        jobs,
+        summary: {
+            total_failures: total,
+            flaky_count: 0,
+            real_count: total,
+            categories: {},
+            root_cause: total > 0 ? 'See failed job sections for causes.' : 'No failures detected.',
+            action: total > 0 ? 'fix' : 'none',
+        },
+    };
+}
+function main() {
+    const token = process.env.INPUT_TOKEN;
+    const repo = process.env.GITHUB_REPOSITORY;
+    const runIdRaw = process.env.GITHUB_RUN_ID;
+    const outputPath = process.env.GITHUB_OUTPUT;
+    if (!token)
+        throw new Error('Missing required input: token');
+    if (!repo)
+        throw new Error('Missing GITHUB_REPOSITORY');
+    if (!outputPath)
+        throw new Error('Missing GITHUB_OUTPUT');
+    const flakeDetect = parseBool(process.env.CI_TRIAGE_FLAKE_DETECT, true);
+    const shouldComment = parseBool(process.env.CI_TRIAGE_COMMENT, true);
+    const shouldUploadArtifact = parseBool(process.env.CI_TRIAGE_JSON_ARTIFACT, true);
+    const historyDepth = Number(process.env.CI_TRIAGE_HISTORY_DEPTH ?? '20');
+    const runId = runIdRaw ? Number(runIdRaw) : undefined;
+    const triageArgs = ['dist/index.js', repo, '--json'];
+    if (flakeDetect) {
+        triageArgs.push('--flake-detect', '--history', String(historyDepth));
+    }
+    const rawJson = execFileSync('node', triageArgs, {
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            GH_TOKEN: token,
+            GITHUB_TOKEN: token,
+        },
+    }).trim();
+    const rawReport = rawJson ? JSON.parse(rawJson) : [];
+    const report = asReport(rawReport, repo, runId);
+    const reportJson = JSON.stringify(report);
+    const failureCount = String(report.summary.total_failures);
+    const status = report.status === 'failed' ? 'fail' : report.status;
+    let artifactPath = '';
+    if (shouldUploadArtifact) {
+        artifactPath = uploadArtifact('ci-triage-report', JSON.stringify(report, null, 2));
+    }
+    if (shouldComment && runId !== undefined) {
+        const prNumber = getPRForRun(repo, runId, token);
+        if (prNumber !== null) {
+            const body = formatComment(report);
+            postOrUpdateComment(repo, prNumber, body, token);
+        }
+    }
+    appendFileSync(outputPath, `report-json<<__CI_TRIAGE__\n${reportJson}\n__CI_TRIAGE__\n`);
+    appendFileSync(outputPath, `status=${status}\n`);
+    appendFileSync(outputPath, `failure-count=${failureCount}\n`);
+    appendFileSync(outputPath, `artifact-path=${artifactPath}\n`);
+}
+main();

package/dist/classifier.js

@@ -0,0 +1,157 @@
+const RULES = [
+    {
+        category: 'oom',
+        severity: 'critical',
+        type: 'infra_resource',
+        cause: 'Out of memory (OOM/heap)',
+        suggestedFix: 'Increase runner memory, reduce parallelism, or tune heap settings.',
+        patterns: [/\b(?:heap out of memory|out of memory|oom\b|killed process \d+)\b/i],
+    },
+    {
+        category: 'port_conflict',
+        severity: 'high',
+        type: 'runtime_error',
+        cause: 'Port already in use',
+        suggestedFix: 'Use dynamic ports and ensure tests/services close listeners during teardown.',
+        patterns: [/\b(?:eaddrinuse|address already in use|port \d+.*in use)\b/i],
+    },
+    {
+        category: 'permission_error',
+        severity: 'high',
+        type: 'permission_error',
+        cause: 'Permission denied (EACCES)',
+        suggestedFix: 'Fix file permissions/ownership and confirm required executable bits are set.',
+        patterns: [/\b(?:eacces|permission denied|operation not permitted)\b/i],
+    },
+    {
+        category: 'module_not_found',
+        severity: 'high',
+        type: 'build_error',
+        cause: 'Module not found',
+        suggestedFix: 'Install missing dependency and verify import paths/casing and lockfile sync.',
+        patterns: [/\b(?:cannot find module|module not found|err_module_not_found)\b/i],
+    },
+    {
+        category: 'assertion_error',
+        severity: 'medium',
+        type: 'test_assertion',
+        cause: 'Test failure/assertion error',
+        suggestedFix: 'Inspect failing expectations and fix logic or stabilize flaky assertions.',
+        patterns: [/\b(?:assertionerror|assertion failed|expected .* but received|\bFAIL\b.*\.(?:test|spec)\.)\b/i],
+    },
+    {
+        category: 'docker_error',
+        severity: 'high',
+        type: 'infra_container',
+        cause: 'Docker/container failure',
+        suggestedFix: 'Check image pull/startup logs and container service health in CI.',
+        patterns: [/\b(?:docker|containerd|failed to start container|no such image)\b/i],
+    },
+    {
+        category: 'network_error',
+        severity: 'medium',
+        type: 'network_error',
+        cause: 'Network/connectivity error',
+        suggestedFix: 'Retry transient calls, validate endpoints, and tune network timeouts.',
+        patterns: [/\b(?:econnrefused|etimedout|network error|connection refused|getaddrinfo enotfound)\b/i],
+    },
+    {
+        category: 'missing_env',
+        severity: 'high',
+        type: 'configuration_error',
+        cause: 'Missing environment variable',
+        suggestedFix: 'Set required CI secrets/variables and validate configuration at startup.',
+        patterns: [/\b(?:missing env(?:ironment)? variable|undefined env|environment variable .* not set)\b/i],
+    },
+    {
+        category: 'missing_file',
+        severity: 'medium',
+        type: 'build_error',
+        cause: 'Missing file/build artifact',
+        suggestedFix: 'Verify artifact generation and ensure inter-job paths are correct.',
+        patterns: [/\b(?:no such file or directory|file not found|artifact not found|enoent)\b/i],
+    },
+    {
+        category: 'rate_limited',
+        severity: 'medium',
+        type: 'external_service',
+        cause: 'Rate limited (429)',
+        suggestedFix: 'Add backoff/retries and reduce burst traffic to external APIs.',
+        patterns: [/\b(?:rate limit(?:ed)?|http\s*429|too many requests)\b/i],
+    },
+    {
+        category: 'missing_lockfile',
+        severity: 'high',
+        type: 'build_error',
+        cause: 'Missing dependency lockfile',
+        suggestedFix: 'Commit lockfile and rerun CI.',
+        patterns: [/\b(?:lock file is not found|package-lock\.json.*not found|yarn\.lock.*not found|pnpm-lock\.yaml.*not found)\b/i],
+    },
+    {
+        category: 'dependency_security',
+        severity: 'high',
+        type: 'security_gate',
+        cause: 'Dependency security gate failure',
+        suggestedFix: 'Upgrade vulnerable dependencies or adjust policy gates where appropriate.',
+        patterns: [/\b(?:npm audit|found [1-9]\d* vulnerabilit(?:y|ies)|dependency check failed|security audit failed)\b/i],
+    },
+    {
+        category: 'timeout',
+        severity: 'medium',
+        type: 'timeout_error',
+        cause: 'Timeout/flaky infrastructure',
+        suggestedFix: 'Increase timeout, split long-running steps, or add targeted retries.',
+        patterns: [/\b(?:timed out|timeout exceeded|operation timed out|deadline exceeded)\b/i],
+    },
+    {
+        category: 'lint_error',
+        severity: 'low',
+        type: 'quality_gate',
+        cause: 'Lint/format failure',
+        suggestedFix: 'Run local linter/formatter and apply fixes.',
+        patterns: [/\b(?:eslint|prettier|lint(?:ing)? failed|style check failed)\b/i],
+    },
+    {
+        category: 'type_error',
+        severity: 'high',
+        type: 'compile_error',
+        cause: 'TypeScript/build break',
+        suggestedFix: 'Run build locally and fix type or module resolution issues.',
+        patterns: [/\b(?:ts\d{4}:|error\s+ts\d{4}|type error|tsc\b.*error|compilation failed)\b/i],
+    },
+];
+function confidenceFromMatch(failure, patternHits) {
+    let score = 0.45;
+    score += Math.min(0.35, patternHits * 0.2);
+    if (failure.location) {
+        score += 0.1;
+    }
+    if (failure.stack.length > 0) {
+        score += 0.1;
+    }
+    return Number(Math.min(0.99, score).toFixed(2));
+}
+export function classify(failure) {
+    const haystack = [failure.error, ...failure.stack, ...failure.rawLines].join('\n');
+    for (const rule of RULES) {
+        const hits = rule.patterns.filter((pattern) => pattern.test(haystack)).length;
+        if (hits > 0) {
+            return {
+                category: rule.category,
+                severity: rule.severity,
+                confidence: confidenceFromMatch(failure, hits),
+                cause: rule.cause,
+                suggestedFix: rule.suggestedFix,
+                type: rule.type,
+            };
+        }
+    }
+    return {
+        category: 'unknown',
+        severity: 'low',
+        confidence: 0.35,
+        cause: 'Unknown (manual triage needed)',
+        suggestedFix: 'Open failed logs and inspect the first failing step in detail.',
+        type: 'unknown_failure',
+    };
+}

package/dist/comment.js

@@ -0,0 +1,81 @@
+export const CI_TRIAGE_MARKER = '<!-- ci-triage-comment -->';
+function statusEmoji(status) {
+    if (status === 'pass')
+        return '✅';
+    if (status === 'flaky')
+        return '⚠️';
+    return '❌';
+}
+function normalizeStatus(status) {
+    if (status === 'pass')
+        return 'pass';
+    if (status === 'flaky')
+        return 'flaky';
+    return 'fail';
+}
+function flattenFailures(job) {
+    if (job.failures && job.failures.length > 0) {
+        return job.failures;
+    }
+    const out = [];
+    for (const step of job.steps ?? []) {
+        for (const failure of step.failures ?? []) {
+            out.push(failure);
+        }
+    }
+    return out;
+}
+function formatFileLink(report, failure) {
+    if (!failure.file)
+        return '_unknown location_';
+    const line = failure.line ?? 1;
+    if (report.commit) {
+        const url = `https://github.com/${report.repo}/blob/${report.commit}/${failure.file}#L${line}`;
+        return `[${failure.file}:${line}](${url})`;
+    }
+    return `\`${failure.file}:${line}\``;
+}
+function formatFailure(report, failure) {
+    const testName = failure.test_name ?? '_unnamed test_';
+    const error = failure.error ?? '_no error message_';
+    const location = formatFileLink(report, failure);
+    const flakyBadge = failure.flaky?.is_flaky ? ' `flaky`' : '';
+    const fix = failure.suggested_fix ? `\n- Fix: ${failure.suggested_fix}` : '';
+    return `- **${testName}**${flakyBadge}\n- Error: ${error}\n- Location: ${location}${fix}`;
+}
+export function formatComment(report) {
+    const status = normalizeStatus(report.status);
+    const emoji = statusEmoji(status);
+    const total = report.summary.total_failures;
+    const flaky = report.summary.flaky_count;
+    const real = report.summary.real_count;
+    const lines = [];
+    lines.push(CI_TRIAGE_MARKER);
+    lines.push(`${emoji} **CI Triage: ${status.toUpperCase()}**`);
+    lines.push('');
+    lines.push(`Failures: **${total}** | Flaky: **${flaky}** | Real: **${real}**`);
+    if (status === 'pass') {
+        lines.push('');
+        lines.push('No failing jobs were detected in this run.');
+    }
+    for (const job of report.jobs.filter((j) => j.status === 'failed' || j.status === 'fail')) {
+        const failures = flattenFailures(job);
+        lines.push('');
+        lines.push(`<details>`);
+        lines.push(`<summary><strong>${job.name}</strong> (${failures.length} failures)</summary>`);
+        lines.push('');
+        if (failures.length === 0) {
+            lines.push('- No parsed failure details were found for this job.');
+        }
+        else {
+            for (const failure of failures) {
+                lines.push(formatFailure(report, failure));
+                lines.push('');
+            }
+        }
+        lines.push(`</details>`);
+    }
+    lines.push('');
+    lines.push('[Generated by ci-triage](https://github.com/clankamode/ci-triage)');
+    return lines.join('\n').trim();
+}

package/dist/fetcher.js

@@ -0,0 +1,62 @@
+import { execFileSync } from 'node:child_process';
+function runJson(args) {
+    const out = execFileSync('gh', args, { encoding: 'utf8' });
+    return JSON.parse(out);
+}
+export function fetchRuns(repo, limit) {
+    return runJson([
+        'run',
+        'list',
+        '--repo',
+        repo,
+        '--limit',
+        String(limit),
+        '--json',
+        'databaseId,displayTitle,workflowName,conclusion,url',
+    ]);
+}
+export function fetchRunById(repo, runId) {
+    const runs = runJson([
+        'run',
+        'list',
+        '--repo',
+        repo,
+        '--limit',
+        '100',
+        '--json',
+        'databaseId,displayTitle,workflowName,conclusion,url',
+    ]);
+    const run = runs.find((r) => r.databaseId === runId);
+    if (!run) {
+        throw new Error(`Run ${runId} not found in recent runs.`);
+    }
+    return run;
+}
+export function fetchRunMetadata(repo, runId) {
+    try {
+        const result = runJson([
+            'run',
+            'view',
+            String(runId),
+            '--repo',
+            repo,
+            '--json',
+            'headSha,headBranch,event',
+        ]);
+        return result;
+    }
+    catch {
+        return { headSha: '', headBranch: '', event: '' };
+    }
+}
+export function fetchFailedLog(repo, runId) {
+    try {
+        return execFileSync('gh', ['run', 'view', String(runId), '--repo', repo, '--log-failed'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch {
+        return '';
+    }
+}