chromium-helper
Version:
CLI tool for searching and exploring Chromium source code via Google's official APIs
645 lines (553 loc) • 23.8 kB
JavaScript
export function getAIUsageGuide() {
return `# Chromium Helper CLI - AI Usage Guide
A comprehensive CLI tool for searching and exploring the Chromium source code. All commands support --debug flag for detailed logging and --format for output control.
## Global Options
--format <type> Output format: json, table, plain (default: plain)
--debug Enable debug logging
--no-color Disable colored output
--ai Show this AI usage guide
## Commands Overview
### 1. search - Search Chromium source code
Usage: ch search <query> [options]
Aliases: s
Options:
-c, --case-sensitive Case sensitive search
-l, --language <lang> Filter by language (cpp, javascript, python, etc.)
-p, --file-pattern <pattern> File pattern (*.cc, *.h, chrome/browser/*, etc.)
-t, --type <type> Search type: content|function|class|symbol|comment
--exclude-comments Exclude comments from results
--limit <number> Max results (default: 20)
Examples:
ch search "LOG(INFO)" --format json --limit 5
ch search "WebContents" --type class --file-pattern "*.h"
ch search "memory leak" --language cpp --exclude-comments
Advanced Search Syntax:
The tool uses Google Code Search syntax. You can use filters directly in your query:
Supported Filters:
case:yes - Case sensitive search (case:yes Hello World)
class:ClassName - Search for class definitions (class:Browser)
function:name - Search for function definitions (function:CreateWindow)
symbol:name - Search for symbol definitions (symbol:WebContents)
comment:text - Search in comments only (comment:TODO)
content:text - Search file contents only (content:hello)
file:pattern - Filter by filename/path (file:*.cc or file:chrome/browser/*)
lang:language - Filter by language (lang:cpp test)
usage:term - Search excluding comments/strings (usage:malloc)
pcre:yes pattern - Use Perl regex for advanced patterns
Language Values (for lang: filter):
cpp, cc, cxx - C++ files
c - C files
java - Java files
python, py - Python files
javascript, js - JavaScript files
go, golang - Go files
rust, rs - Rust files
And many more...
Operators:
AND - Logical AND (Browser AND Create)
OR - Logical OR (malloc OR free)
-term - Exclude term (-test removes matches with "test")
"exact phrase" - Literal search for exact phrase
(group) - Group terms together
\ - Escape special characters
Examples with Advanced Syntax:
ch search "class:Browser file:*.h"
ch search "function:Create lang:cpp"
ch search "case:yes WebContents"
ch search "usage:malloc -test"
ch search "(Browser OR Tab) AND Create"
JSON Output Format:
[
{
"file": "path/to/file.cc",
"line": 123,
"content": "matched code context",
"url": "https://source.chromium.org/chromium/chromium/src/+/main:path/to/file.cc;l=123"
}
]
### 2. symbol - Find symbol definitions and usage
Usage: ch symbol <symbol> [options]
Aliases: sym
Options:
-f, --file <path> File context for symbol resolution
Examples:
ch symbol "Browser" --format json
ch symbol "CreateWindow" --file "chrome/browser/ui/browser.cc"
JSON Output Format:
{
"symbol": "Browser",
"symbolResults": [SearchResult[]],
"classResults": [SearchResult[]],
"functionResults": [SearchResult[]],
"usageResults": [SearchResult[]],
"estimatedUsageCount": 1250
}
### 3. file - Get file content from Chromium source
Usage: ch file <path> [options]
Aliases: f
Options:
-s, --start <line> Starting line number
-e, --end <line> Ending line number
Examples:
ch file "base/logging.h" --format json
ch file "chrome/browser/ui/browser.h" --start 100 --end 200
JSON Output Format:
{
"filePath": "base/logging.h",
"content": "1 // Copyright text\\n2 #ifndef BASE_LOGGING_H_\\n...",
"totalLines": 456,
"displayedLines": 356,
"lineStart": 100,
"lineEnd": 200,
"browserUrl": "https://source.chromium.org/chromium/chromium/src/+/main:base/logging.h;l=100-200"
}
### 4. auth - Authentication management for Gerrit
Usage: ch auth <command>
No aliases
Subcommands:
manual Interactive cookie setup (recommended)
login Browser-based authentication (may be blocked by Google)
status Check authentication status
logout Clear saved authentication
help Show detailed cookie extraction help
Examples:
ch auth manual # Interactive setup - enter __Secure-1PSID or __Secure-3PSID
ch auth login # Opens browser for automatic login
ch auth status # Check if authenticated
ch auth logout # Clear saved cookies
ch auth help # Show detailed instructions
Authentication Notes:
- Only ONE cookie is required: either __Secure-1PSID OR __Secure-3PSID
- Cookies are saved to ~/.gerrit-cookie with secure permissions
- Once authenticated, gerrit list and pdfium list work without --auth-cookie
- Manual method is recommended as browser login may be blocked by Google security
### 5. list-folder - List files and folders in a Chromium source directory
Usage: ch list-folder <path>
Aliases: ls
Examples:
ch list-folder "third_party/blink/renderer/core/style" --format json
ch list-folder "base" --format json
ch list-folder "chrome/browser/ui" --format table
ch list-folder "v8/test/benchmarks" --format json # Uses GitHub API for V8 submodule
ch list-folder "third_party/webrtc" --format json # Uses WebRTC Gitiles for submodule
Special Support for Git Submodules:
- V8 paths (e.g., v8/test): Automatically fetches from GitHub (https://github.com/v8/v8)
- WebRTC paths (e.g., third_party/webrtc): Automatically fetches from WebRTC Gitiles
- Other submodules: Returns helpful error with browse URL
JSON Output Format:
{
"path": "third_party/blink/renderer/core/style",
"browserUrl": "https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/style/",
"totalItems": 164,
"folders": 0,
"files": 164,
"items": [
{
"name": "anchor_specifier_value.cc",
"type": "file"
},
{
"name": "anchor_specifier_value.h",
"type": "file"
},
{
"name": "sub_folder",
"type": "folder"
}
],
"source": "GitHub (V8 submodule)", // Only present for submodules
"githubUrl": "https://github.com/v8/v8/tree/main/test/benchmarks" // For V8
}
### 6. owners - Find OWNERS files for a file path
Usage: ch owners <path>
Aliases: own
Examples:
ch owners "chrome/browser/ui/browser.cc" --format json
JSON Output Format:
{
"filePath": "chrome/browser/ui/browser.cc",
"ownerFiles": [
{
"path": "chrome/browser/ui/OWNERS",
"content": "# OWNERS file content\\nuser@chromium.org\\n...",
"browserUrl": "https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/ui/OWNERS"
}
]
}
### 7. commits - Search commit history
Usage: ch commits <query> [options]
Aliases: cm
Options:
-a, --author <author> Filter by author
--since <date> Commits after date (YYYY-MM-DD)
--until <date> Commits before date (YYYY-MM-DD)
--limit <number> Max results (default: 20)
Examples:
ch commits "password manager" --format json --limit 10
ch commits "security fix" --author "chrome-security"
ch commits "memory leak" --since "2023-01-01" --until "2023-12-31"
JSON Output Format:
{
"log": [
{
"commit": "abc123def456...",
"author": {
"name": "Developer Name",
"email": "dev@chromium.org",
"time": 1703980800
},
"message": "Fix memory leak in browser startup\\n\\nDetailed description..."
}
]
}
### 8. gerrit - Gerrit code review operations
Usage: ch gerrit <command> [options]
Aliases: gr
Subcommands:
status <cl> Get CL status and test results
comments <cl> [options] Get CL review comments (with threaded display)
diff <cl> [options] Get CL diff/changes
file <cl> <path> [options] Get file content from CL patchset
bots <cl> [options] Get try-bot status for CL
bot-errors <cl> [options] Get detailed error messages with stack traces from failed try-bots
list [options] List Gerrit CLs (requires authentication)
suggest-reviewers <cl> [options] Find optimal reviewers based on OWNERS and activity (alias: sr)
Options for comments:
-p, --patchset <number> Specific patchset number
--no-resolved Exclude resolved comments
Comment Display Features:
- Threaded conversation view: Comments are organized into discussion threads
- Visual hierarchy: Replies are indented with ↳ markers to show reply relationships
- Thread status: Each thread shows 🔔 Active Discussion (unresolved) or ✓ Resolved
- Reply counts: Number of replies displayed for each thread
- Chronological ordering: Replies sorted by timestamp within each thread
- Summary statistics: Total and unresolved comment counts at the end
Options for diff:
-p, --patchset <number> Specific patchset number
-f, --file <path> Specific file path to get diff for
Options for bots:
-p, --patchset <number> Specific patchset number
--failed-only Show only failed bots
Options for bot-errors:
-p, --patchset <number> Specific patchset number
-b, --bot <name> Filter by bot name (supports partial matching, e.g., "linux" or "linux-rel")
--all-bots Include all bots (not just failed ones)
Options for list:
-q, --query <query> Gerrit search query (default: status:open owner:self)
-a, --auth-cookie <cookie> Authentication cookie from browser (required)
-l, --limit <number> Maximum number of CLs to return (default: 25)
Options for suggest-reviewers:
-p, --patchset <number> Specific patchset number
-l, --limit <number> Max reviewers to suggest (default: 5)
-m, --months <number> Activity lookback period in months (default: 6)
--fast Skip activity analysis for faster results (OWNERS-only)
--show-all Show all candidates, not just optimal set
--exclude <emails...> Exclude specific reviewer emails
Examples:
ch gerrit status 6624568 --format json
ch gerrit comments 6624568 --format json
ch gerrit diff 6624568 --file "base/logging.cc"
ch gerrit file 6624568 "base/logging.cc" --patchset 3
ch gerrit bots 6624568 --format json
ch gerrit bots 5515135 --failed-only --format json
ch gerrit bot-errors 5515135 --format json # Get detailed errors from all failed bots
ch gerrit bot-errors 5515135 --bot linux --format json # Filter to linux bots only
ch gerrit bot-errors 5515135 --bot linux-rel --format json # Specific bot
ch gerrit list --auth-cookie "__Secure-1PSID=..." --format json
ch gerrit list --auth-cookie "__Secure-3PSID=..." --query "status:open owner:me" --limit 10
ch gerrit suggest-reviewers 7186763 --format json # Find optimal reviewers for CL
ch gerrit sr 7186763 --fast # Quick OWNERS-only analysis
ch gerrit sr 7186763 --limit 3 --months 3 # Limit to 3 reviewers, 3 months activity
JSON Output Format for bots:
{
"clId": "6624568",
"patchset": 2,
"runId": "8873420370854-1-4e0066468e986b0a",
"luciUrl": "https://luci-change-verifier.appspot.com/ui/run/chromium/8873420370854-1-4e0066468e986b0a",
"totalBots": 12,
"failedBots": 0,
"passedBots": 12,
"runningBots": 0,
"canceledBots": 0,
"bots": [
{
"name": "linux-chromeos-compile-chrome",
"status": "PASSED",
"luciUrl": "https://luci-change-verifier.appspot.com/ui/run/chromium/8873420370854-1-4e0066468e986b0a",
"runId": "8873420370854-1-4e0066468e986b0a",
"summary": "passed"
}
],
"timestamp": "2024-06-30T10:30:00.000Z"
}
JSON Output Format for bot-errors:
{
"clId": "5515135",
"patchset": 2,
"message": "Found 2 bots with errors",
"bots": [
{
"name": "linux-rel",
"buildUrl": "https://ci.chromium.org/ui/p/chromium/builders/try/linux-rel/b1234567890",
"failedTests": [
{
"testName": "BrowserTest.SomeTest",
"status": "FAILED",
"duration": "5.2s",
"snippet": "Full error output with stack trace...",
"errorMessages": [
"Expected: true",
"Actual: false",
"Stack trace line 1",
"Stack trace line 2"
]
}
],
"totalFailedTests": 1
}
]
}
JSON Output Format for list:
[
{
"_number": 6624568,
"subject": "Fix memory leak in browser",
"owner": {
"name": "Developer Name",
"email": "dev@chromium.org"
},
"status": "NEW",
"created": "2024-01-15T10:00:00.000Z",
"updated": "2024-01-15T14:30:00.000Z",
"current_revision_number": 3,
"insertions": 45,
"deletions": 12,
"total_comment_count": 5,
"unresolved_comment_count": 2,
"labels": {
"Code-Review": {
"all": [{"value": 2}]
},
"Commit-Queue": {
"all": [{"value": 1}]
}
}
}
]
JSON Output Format for suggest-reviewers:
{
"clNumber": "7186763",
"subject": "Fix crash when profile-dependent flags can't load profile",
"changedFiles": ["chrome/browser/ui/startup/startup_browser_creator.cc", "..."],
"suggestedReviewers": [
{
"email": "reviewer@chromium.org",
"coverageScore": 1.0,
"activityScore": 0.8,
"combinedScore": 0.92,
"canReviewFiles": ["file1.cc", "file2.cc"],
"recentCommits": 12,
"lastCommitDate": "2024-01-10T10:00:00.000Z"
}
],
"optimalSet": [
{
"email": "optimal-reviewer@chromium.org",
"coverageScore": 1.0,
"activityScore": 0.8,
"combinedScore": 0.92,
"canReviewFiles": ["file1.cc", "file2.cc"],
"recentCommits": 12
}
],
"uncoveredFiles": [],
"analysisDetails": {
"filesAnalyzed": 2,
"ownersFilesFetched": 8,
"commitHistoryFetched": 1,
"activityMonths": 6
}
}
### 9. pdfium - PDFium Gerrit operations
Usage: ch pdfium <command> [options]
Aliases: pdf
Subcommands:
status <cl> Get PDFium CL status and test results
comments <cl> [options] Get PDFium CL review comments (with threaded display)
diff <cl> [options] Get PDFium CL diff/changes
file <cl> <path> [options] Get file content from PDFium CL patchset
bots <cl> [options] Get try-bot status for PDFium CL
list [options] List PDFium Gerrit CLs (requires authentication)
Options for comments:
-p, --patchset <number> Specific patchset number
--no-resolved Exclude resolved comments
Comment Display Features:
- Threaded conversation view: Comments are organized into discussion threads
- Visual hierarchy: Replies are indented with ↳ markers to show reply relationships
- Thread status: Each thread shows 🔔 Active Discussion (unresolved) or ✓ Resolved
- Reply counts: Number of replies displayed for each thread
- Chronological ordering: Replies sorted by timestamp within each thread
- Summary statistics: Total and unresolved comment counts at the end
Options for diff:
-p, --patchset <number> Specific patchset number
-f, --file <path> Specific file path to get diff for
Options for bots:
-p, --patchset <number> Specific patchset number
--failed-only Show only failed bots
Options for list:
-q, --query <query> PDFium Gerrit search query (default: status:open owner:self)
-a, --auth-cookie <cookie> Authentication cookie from browser (required)
-l, --limit <number> Maximum number of CLs to return (default: 25)
Examples:
ch pdfium status 130850
ch pdfium comments 130850 --format json
ch pdfium diff 130850 --file "fpdfsdk/fpdf_view.cpp"
ch pdfium file 130850 "fpdfsdk/fpdf_view.cpp" --patchset 9
ch pdfium bots 130850 --format json
ch pdfium bots 130850 --failed-only --format json
ch pdfium list --auth-cookie "__Secure-1PSID=..." --format json
ch pdfium list --auth-cookie "__Secure-3PSID=..." --query "status:open owner:me" --limit 10
### 11. issues - Chromium issue operations
Usage: ch issues <command> [options]
Aliases: bugs
Subcommands:
get <id> Get specific issue details
search <query> [options] Search for issues
Options for search:
--limit <number> Max results (default: 50)
--start <number> Starting index for pagination (default: 0)
Examples:
ch issues get 422768753 --format json
ch issues search "memory leak" --format json --limit 10
ch issues search "webrtc" --start 50 --limit 25
JSON Output Format for get:
{
"issueId": "422768753",
"browserUrl": "https://issues.chromium.org/issues/422768753",
"title": "FakeDesktopMediaPickerFactory footgun",
"status": "ASSIGNED",
"priority": "P4",
"type": "Bug",
"severity": "S3",
"reporter": "reporter@chromium.org",
"assignee": "assignee@chromium.org",
"created": "2023-12-30T10:00:00.000Z",
"modified": "2024-01-15T14:30:00.000Z",
"description": "Issue description text...",
"comments": [
{
"author": "commenter@chromium.org",
"timestamp": "2023-12-30T11:00:00.000Z",
"content": "Comment text here..."
}
],
"relatedCLs": ["6624568", "6678901"],
"extractionMethod": "direct-api"
}
JSON Output Format for search:
{
"query": "memory leak",
"total": 15,
"issues": [
{
"issueId": "422768753",
"title": "Memory leak in WebRTC",
"status": "ASSIGNED",
"priority": "P2",
"reporter": "reporter@chromium.org",
"assignee": "assignee@chromium.org",
"created": "2023-12-30T10:00:00.000Z",
"modified": "2024-01-15T14:30:00.000Z",
"browserUrl": "https://issues.chromium.org/issues/422768753"
}
],
"searchUrl": "https://issues.chromium.org/issues?q=memory%20leak"
}
### 11. issue - Get Chromium issue details (Legacy)
Usage: ch issue <id>
Aliases: bug
Note: This is a legacy command. Use 'ch issues get <id>' instead.
## AI Usage Patterns
### Code Analysis Workflow
1. Search for relevant code: \`ch search "feature name" --format json\`
2. Examine specific files: \`ch file "path/to/file.cc" --format json\`
3. Find symbol definitions: \`ch symbol "ClassName" --format json\`
4. Check ownership: \`ch owners "path/to/file.cc" --format json\`
### Bug Investigation Workflow
1. Search for related issues: \`ch issues search "memory leak" --format json\`
2. Get specific issue details: \`ch issues get 12345 --format json\`
3. Review related CLs: \`ch gerrit status 6624568 --format json\`
4. Check CL try-bot status: \`ch gerrit bots 6624568 --format json\`
5. Search for similar code patterns: \`ch search "error message" --format json\`
6. Check commit history: \`ch commits "bug keyword" --format json\`
### CL Review Workflow
1. Get CL status: \`ch gerrit status 6624568 --format json\`
2. Check try-bot results: \`ch gerrit bots 6624568 --format json\`
3. Focus on failures: \`ch gerrit bots 6624568 --failed-only --format json\`
4. Get detailed error messages: \`ch gerrit bot-errors 6624568 --format json\`
5. Filter to specific bots: \`ch gerrit bot-errors 6624568 --bot linux --format json\`
6. Review code changes: \`ch gerrit diff 6624568 --format json\`
7. Check review comments (threaded): \`ch gerrit comments 6624568 --format json\`
8. View only unresolved discussions: \`ch gerrit comments 6624568 --no-resolved\`
### Finding Reviewers Workflow
1. Get optimal reviewers: \`ch gerrit suggest-reviewers 7186763 --format json\`
2. Quick OWNERS-only check: \`ch gerrit sr 7186763 --fast\`
3. Show all candidates: \`ch gerrit sr 7186763 --show-all --format json\`
4. Exclude specific people: \`ch gerrit sr 7186763 --exclude "email@chromium.org"\`
The suggest-reviewers command analyzes:
- OWNERS files in the directory hierarchy for each changed file
- Per-file rules (e.g., per-file *.mojom=user@chromium.org)
- Recent commit activity (last 6 months by default) to rank active contributors
- Uses a greedy set-cover algorithm to find the minimal set of reviewers
Note: Comments are displayed as threaded conversations with visual hierarchy. Replies are
indented with ↳ markers, making it easy to follow discussion flow and understand context.
### Shell Integration Examples
\`\`\`bash
# Find all TODOs in browser code
ch search "TODO" --type comment --file-pattern "chrome/browser/*" --format json | jq '.[] | .file'
# Get security-related symbols
ch search "crypto" --language cpp --format json | jq '.[] | select(.file | contains("security"))'
# Find all Browser class usage
ch symbol "Browser" --format json | jq '.usageResults[].url'
# Search for high priority memory issues
ch issues search "memory" --format json | jq '.issues[] | select(.priority == "P1" or .priority == "P2")'
# Get all issue URLs for a specific search
ch issues search "webrtc" --format json | jq '.issues[].browserUrl'
# Get only failed bot names from a CL
ch gerrit bots 5515135 --failed-only --format json | jq '.bots[].name'
# Count bots by status for a CL
ch gerrit bots 6624568 --format json | jq '{passed: .passedBots, failed: .failedBots, running: .runningBots}'
# Check if all bots passed for a CL
ch gerrit bots 6624568 --format json | jq '.failedBots == 0 and .runningBots == 0'
# Get detailed error messages from failed bots
ch gerrit bot-errors 5515135 --format json | jq '.bots[].failedTests[].testName'
# Count failed tests by bot
ch gerrit bot-errors 5515135 --format json | jq '.bots[] | {name: .name, failedTests: .totalFailedTests}'
# Extract all error messages from failed tests
ch gerrit bot-errors 5515135 --format json | jq '.bots[].failedTests[].errorMessages[]'
# Filter errors for specific bot
ch gerrit bot-errors 5515135 --bot linux-rel --format json | jq '.bots[0].failedTests'
# List all .cc files in a folder
ch list-folder "base" --format json | jq '.items[] | select(.type == "file" and (.name | endswith(".cc"))) | .name'
# Count files by extension in a folder
ch list-folder "chrome/browser/ui" --format json | jq '.items[] | select(.type == "file") | .name | split(".") | .[-1]' | sort | uniq -c
# List V8 test subdirectories
ch list-folder "v8/test" --format json | jq '.items[] | select(.type == "folder") | .name'
# Check if a WebRTC folder exists
ch list-folder "third_party/webrtc/api" --format json | jq '.totalItems > 0'
\`\`\`
### Error Handling
All commands return non-zero exit codes on failure. JSON output always includes error information when available.
### Performance Notes
- Use --limit to control result count for faster responses
- File pattern filters improve search performance
- JSON format is fastest for programmatic processing
- Debug mode (--debug) provides detailed API timing information
### Output Formats
- **json**: Structured data, best for AI/programmatic use
- **table**: Tabular format, good for comparison
- **plain**: Human-readable with colors, best for terminal use
All JSON outputs are valid, parseable JSON. Empty results return empty arrays [] or objects {}.
`;
}
//# sourceMappingURL=ai-guide.js.map