diff --git a/README.md b/README.md index f7f9fcac..0172d174 100644 --- a/README.md +++ b/README.md @@ -138,7 +138,10 @@ npm install && npm run build - [Public Installation Guide](docs/public.md) - Install and run without cloning the repository - [Getting Started Guide](docs/getting-started.md) - Detailed installation and setup instructions -- [Tools Reference](docs/tools-reference.md) - Complete list of available MCP tools and usage examples +- [Tools Reference](docs/ql-mcp/tools.md) - Complete list of available MCP tools +- [Prompts Reference](docs/ql-mcp/prompts.md) - MCP prompts for CodeQL development workflows +- [Resources Reference](docs/ql-mcp/resources.md) - MCP resources for CodeQL learning and reference +- [Testing Strategy](docs/testing.md) - Multi-layer testing approach ## License diff --git a/docs/getting-started.md b/docs/getting-started.md index 5d874d4e..bffd9b79 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -104,4 +104,6 @@ Add to your `mcp.json` file: ## Next Steps -- [Tools Reference](./tools-reference.md) - Available MCP tools and usage +- [Tools Reference](./ql-mcp/tools.md) - Available MCP tools +- [Prompts Reference](./ql-mcp/prompts.md) - MCP prompts for CodeQL workflows +- [Resources Reference](./ql-mcp/resources.md) - MCP resources for CodeQL learning diff --git a/docs/public.md b/docs/public.md index 731a94a8..4bdb9fc9 100644 --- a/docs/public.md +++ b/docs/public.md @@ -255,8 +255,11 @@ dependencies: ## Further Reading -- [Tools Reference](./tools-reference.md) — Complete list of MCP tools and usage examples - [Getting Started (developer)](./getting-started.md) — Building from source and advanced configuration +- [Testing Reference](./testing.md) — Overview of this repo's release testing strategy +- [MCP Tools Reference](./ql-mcp/tools.md) — Complete list of MCP tools +- [MCP Prompts Reference](./ql-mcp/prompts.md) — MCP prompts for CodeQL development workflows +- [MCP Resources Reference](./ql-mcp/resources.md) — MCP resources for CodeQL learning and reference - [VS Code MCP Server Documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) — Configuring MCP servers in VS Code - [Publishing and Using CodeQL Packs](https://docs.github.com/en/code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs) — Managing CodeQL packs with the CodeQL CLI - [Model Context Protocol](https://modelcontextprotocol.io/) — The MCP specification diff --git a/docs/ql-mcp/prompts.md b/docs/ql-mcp/prompts.md new file mode 100644 index 00000000..06fb1e6c --- /dev/null +++ b/docs/ql-mcp/prompts.md @@ -0,0 +1,48 @@ +# Prompts + +> MCP prompts provided by the CodeQL Development MCP Server. + +## Overview + +The server provides **10 prompts** that guide AI assistants through common CodeQL development workflows. Each prompt is backed by a `*.prompt.md` file containing structured instructions. + +## Prompt Reference + +| Prompt | Description | +| ------------------------------ | -------------------------------------------------------------------------------------------------------------------- | +| `document_codeql_query` | Create or update documentation for a CodeQL query | +| `explain_codeql_query` | Generate a detailed explanation of a CodeQL query for workshop learning content | +| `ql_lsp_iterative_development` | Iterative CodeQL query development using LSP tools for completion, navigation, and validation | +| `ql_tdd_advanced` | Advanced test-driven CodeQL development with AST visualization, control flow, and call graph analysis | +| `ql_tdd_basic` | Test-driven CodeQL query development checklist — write tests first, implement query, iterate until tests pass | +| `sarif_rank_false_positives` | Analyze SARIF results to identify likely false positives in CodeQL query results | +| `sarif_rank_true_positives` | Analyze SARIF results to identify likely true positives in CodeQL query results | +| `test_driven_development` | Test-driven development workflow for CodeQL queries using MCP tools | +| `tools_query_workflow` | Guide for using built-in tools queries (PrintAST, PrintCFG, CallGraphFrom, CallGraphTo) to understand code structure | +| `workshop_creation_workflow` | Guide for creating CodeQL query development workshops from production-grade queries | + +## Prompt Categories + +### Test-Driven Development + +- **`ql_tdd_basic`** — Covers the core TDD loop: write test cases, implement the query, run tests, iterate. +- **`ql_tdd_advanced`** — Extends basic TDD with AST visualization, control flow graph analysis, and call graph exploration. +- **`test_driven_development`** — End-to-end TDD workflow using MCP tools for each step. + +### Code Understanding + +- **`tools_query_workflow`** — Uses PrintAST, PrintCFG, CallGraphFrom, and CallGraphTo tool queries to explore how source code is represented in a CodeQL database. +- **`explain_codeql_query`** — Produces verbal explanations and Mermaid evaluation diagrams for a given query. + +### Iterative Development + +- **`ql_lsp_iterative_development`** — Combines LSP completions, go-to-definition, and diagnostics for an interactive development loop. + +### Documentation and Quality + +- **`document_codeql_query`** — Generates standardized markdown documentation as a sibling file to a query. +- **`sarif_rank_false_positives`** / **`sarif_rank_true_positives`** — Help assess query precision by ranking SARIF results. + +### Workshop Creation + +- **`workshop_creation_workflow`** — Guides the creation of multi-exercise workshops that teach CodeQL query development. diff --git a/docs/ql-mcp/resources.md b/docs/ql-mcp/resources.md new file mode 100644 index 00000000..e892f82f --- /dev/null +++ b/docs/ql-mcp/resources.md @@ -0,0 +1,40 @@ +# Resources + +> MCP resources provided by the CodeQL Development MCP Server. + +## Overview + +The server exposes **4 static learning resources** and a set of **dynamic per-language resources** that supply AI assistants with CodeQL reference material. Resources are read-only and backed by `*.prompt.md` files bundled with the server. + +## Static Resources + +| Resource | URI | Description | +| --------------------------- | ----------------------------------- | --------------------------------------------------- | +| CodeQL Getting Started | `codeql://learning/getting-started` | Comprehensive introduction to CodeQL for beginners | +| CodeQL Query Basics | `codeql://learning/query-basics` | Learn the fundamentals of writing CodeQL queries | +| CodeQL Security Templates | `codeql://templates/security` | Ready-to-use security query templates | +| CodeQL Performance Patterns | `codeql://patterns/performance` | Best practices for writing efficient CodeQL queries | + +## Language-Specific Resources + +Each supported language can expose one or more of the following resource types under the URI pattern `codeql://languages/{language}/{type}`: + +| Language | AST Reference | Security Patterns | Additional | +| ---------- | :-----------: | :---------------: | ----------------------------------------- | +| actions | ✓ | | | +| cpp | ✓ | ✓ | | +| csharp | ✓ | ✓ | | +| go | ✓ | ✓ | dataflow, library-modeling, basic-queries | +| java | ✓ | | | +| javascript | ✓ | ✓ | | +| python | ✓ | ✓ | | +| ql | ✓ | | | +| ruby | ✓ | | | + +### Resource Types + +- **AST Reference** (`codeql://languages/{language}/ast`) — CodeQL AST class reference for the language, describing how source constructs map to QL classes. +- **Security Patterns** (`codeql://languages/{language}/security`) — Security query patterns and framework modeling guidance. +- **Dataflow** (`codeql://languages/go/dataflow`) — Guide to using the CodeQL dataflow library. +- **Library Modeling** (`codeql://languages/go/library-modeling`) — Guide to modeling third-party libraries for CodeQL analysis. +- **Basic Queries** (`codeql://languages/go/basic-queries`) — Introductory query examples for the language. diff --git a/docs/ql-mcp/tools.md b/docs/ql-mcp/tools.md new file mode 100644 index 00000000..f2501c8c --- /dev/null +++ b/docs/ql-mcp/tools.md @@ -0,0 +1,88 @@ +# Tools + +> Complete reference of MCP tools provided by the CodeQL Development MCP Server. + +## Overview + +The server exposes **34 always-on tools** and **11 optional monitoring tools**. Always-on tools are available in every session; monitoring tools require explicit opt-in (see [Monitoring and Reporting](../mcp-server-monitoring-and-reporting.md)). + +## Always-On Tools + +### CodeQL CLI Tools + +| Tool | Description | +| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `codeql_bqrs_decode` | Decode BQRS result files to human-readable formats | +| `codeql_bqrs_info` | Get metadata and information about BQRS result files | +| `codeql_bqrs_interpret` | Interpret BQRS result files according to query metadata and generate output in specified formats (CSV, SARIF, graph formats) | +| `codeql_database_analyze` | Run queries or query suites against CodeQL databases | +| `codeql_database_create` | Create a CodeQL database from source code | +| `codeql_generate_log-summary` | Create a summary of a structured JSON evaluator event log file | +| `codeql_generate_query-help` | Generate query help documentation from QLDoc comments | +| `codeql_pack_install` | Install CodeQL pack dependencies | +| `codeql_pack_ls` | List CodeQL packs under some local directory path | +| `codeql_query_compile` | Compile and validate CodeQL queries | +| `codeql_query_format` | Automatically format CodeQL source code files | +| `codeql_query_run` | Execute a CodeQL query against a database | +| `codeql_resolve_database` | Resolve database path and validate database structure | +| `codeql_resolve_languages` | List installed CodeQL extractor packs | +| `codeql_resolve_library-path` | Resolve library path for CodeQL queries and libraries | +| `codeql_resolve_metadata` | Resolve and return the key-value metadata pairs from a CodeQL query source file | +| `codeql_resolve_qlref` | Resolve qlref files to their corresponding query files | +| `codeql_resolve_queries` | List available CodeQL queries found on the local filesystem | +| `codeql_resolve_tests` | Resolve the local filesystem paths of unit tests and/or queries under some base directory | +| `codeql_test_accept` | Accept new test results as the expected baseline | +| `codeql_test_extract` | Extract test databases for CodeQL query tests | +| `codeql_test_run` | Run CodeQL query tests | + +### Language Server Protocol (LSP) Tools + +| Tool | Description | +| ------------------------ | ----------------------------------------------------------------------------------------------- | +| `codeql_lsp_completion` | Get code completions at a cursor position in a CodeQL file | +| `codeql_lsp_definition` | Go to the definition of a CodeQL symbol at a given position | +| `codeql_lsp_diagnostics` | Authoritative syntax and semantic validation of CodeQL (QL) code via the CodeQL Language Server | +| `codeql_lsp_references` | Find all references to a CodeQL symbol at a given position | + +### Query Development Tools + +| Tool | Description | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| `create_codeql_query` | Create directory structure and files for a new CodeQL query with tests | +| `find_class_position` | Find the start/end line and column of a class for quick evaluation | +| `find_codeql_query_files` | Find and track all files and directories related to a CodeQL query, including resolved metadata | +| `find_predicate_position` | Find the start/end line and column of a predicate for quick evaluation | +| `profile_codeql_query` | Profile the performance of a CodeQL query run against a specific database by analyzing the evaluator log JSON file | +| `quick_evaluate` | Quick evaluate either a class or a predicate in a CodeQL query for debugging | +| `register_database` | Register a CodeQL database given a local path to the database directory | +| `validate_codeql_query` | Quick heuristic validation for CodeQL query structure (does not compile the query) | + +## Optional Monitoring Tools + +These tools are disabled by default and require opt-in. See [Monitoring and Reporting](../mcp-server-monitoring-and-reporting.md) for details. + +### Session Management + +| Tool | Description | +| ---------------------- | ------------------------------------------------------------ | +| `session_end` | End a query development session with final status | +| `session_get` | Get complete details of a specific query development session | +| `session_list` | List query development sessions with optional filtering | +| `session_update_state` | Update the current state of a query development session | + +### Session Analytics + +| Tool | Description | +| --------------------------------- | ---------------------------------------------------------------- | +| `session_calculate_current_score` | Calculate current quality score for a session based on its state | +| `session_get_call_history` | Get MCP call history for a specific session | +| `session_get_score_history` | Get quality score history for a specific session | +| `session_get_test_history` | Get test execution history for a specific session | + +### Batch Operations + +| Tool | Description | +| -------------------- | ----------------------------------------------------------------------- | +| `sessions_aggregate` | Generate aggregate insights from multiple sessions based on filters | +| `sessions_compare` | Compare multiple query development sessions across specified dimensions | +| `sessions_export` | Export session data in specified format for external analysis | diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 00000000..d6ab9545 --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,62 @@ +# Testing Strategy + +> Multi-layer testing approach for the CodeQL Development MCP Server. + +## Overview + +Every release of the CodeQL Development MCP Server is validated through three progressively broader layers of testing. Each layer builds on the previous one, moving from fast unit checks to real-world agentic validation. + +| Layer | Scope | Framework | Location | +| ---------------------- | ----------------------------------------------- | ------------------------------ | ----------------------------- | +| 1 — Unit tests | TypeScript source code | Vitest | `server/test/**/*.test.ts` | +| 2 — Integration tests | Individual MCP tools against a running server | Custom MCP client | `client/integration-tests/**` | +| 3 — Agentic validation | End-to-end CodeQL workflows driven by AI agents | GitHub Copilot agents + skills | `.github/{agents,skills}/**` | + +## Layer 1 — Unit Tests + +Unit tests verify the TypeScript implementation of the MCP server. + +- **Framework**: [Vitest](https://vitest.dev/) with code coverage via `@vitest/coverage-v8`. +- **Location**: `server/test/**/*.test.ts`, mirroring `server/src/**/*.ts`. +- **Run command**: `npm run test -w server` (or `npm run test:server` from the repo root). +- **Conventions**: Tests follow the Arrange-Act-Assert (AAA) pattern, use descriptive names, and mock external dependencies where necessary. + +## Layer 2 — Integration Tests + +Integration tests exercise individual MCP tools against a live server instance using the custom MCP client. + +- **Client**: `client/src/ql-mcp-client.js` — starts the MCP server, invokes tools, and validates results. +- **Test data**: `client/integration-tests/primitives/tools/` — each test has `before/` and `after/` directories that define the initial fixture state and, for file-based tests, the expected final state. +- **Run command**: `npm run test:integration:default -w client` (or `npm run test:client` from the repo root). +- **Key properties**: + - Tests are deterministic and repeatable. + - No mocks — tests use real CodeQL databases and queries bundled under `server/ql/`. + - The `before/monitoring-state.json` file supplies tool arguments. For file-based tests, the integration-test runner diffs filesystem state from `before/` to `after/`; for monitoring-based tests, `after/` artifacts are generally not diffed and are only interpreted for specific validations (for example, `codeql_query_run` interpreted output). + +## Layer 3 — Agentic Validation + +Agentic validation uses GitHub Copilot agents and skills to solve CodeQL query development challenges, exercising MCP tools in realistic end-to-end scenarios. + +- **Agents** (`.github/agents/`): Define specialized AI agent personas (e.g., `ql-mcp-tool-tester`, `mcp-enabled-ql-query-developer`) that interact with the MCP server exclusively through its tools, prompts, and resources. +- **Skills** (`.github/skills/`): Provide step-by-step workflows such as `create-codeql-query-tdd-generic`, `create-codeql-query-development-workshop`, and language-specific unit test creation skills. +- **Workshop exercises**: Pre-built CodeQL development workshops serve as challenge problems. Agents solve each exercise using only MCP primitives, validating that tools produce correct results in complex, multi-step scenarios. +- **Key properties**: + - Agents never call the `codeql` CLI directly — all operations go through MCP tools. + - Exercises cover query compilation, test execution, AST/CFG exploration, and iterative query refinement. + +## Running All Tests + +From the repository root: + +```bash +# Build everything and run all layers (unit + integration) +npm run build-and-test + +# Run only unit tests +npm run test:server + +# Run only integration tests +npm run test:client +``` + +> **Note**: Layer 3 (agentic validation) runs as part of the CI/CD pipeline via GitHub Actions workflows and is not included in the local `build-and-test` command. diff --git a/docs/tools-reference.md b/docs/tools-reference.md deleted file mode 100644 index 1a4aa75b..00000000 --- a/docs/tools-reference.md +++ /dev/null @@ -1,608 +0,0 @@ -# Tools Reference - -This document provides a comprehensive reference for all tools available in the CodeQL Development MCP Server. - -## Overview - -The MCP server provides tools that wrap CodeQL CLI commands and helper utilities for CodeQL development workflows. Tools are organized into the following categories: - -- **Query Development** - Create, compile, and format queries -- **Query Execution** - Run queries and process results -- **Validation & LSP** - Validate QL code and navigate symbols via LSP -- **Testing** - Run and manage CodeQL tests -- **Database Operations** - Create and analyze databases -- **Resolution** - Resolve paths, dependencies, and metadata -- **BQRS Processing** - Work with query result files -- **Utility** - Helper tools for common workflows - -## Query Development Tools - -### codeql_query_compile - -Compile CodeQL queries to check for errors. - -**Parameters:** - -| Parameter | Type | Required | Description | -| ---------- | ------ | -------- | ------------------------------------- | -| `query` | string | Yes | Path to the query file to compile | -| `database` | string | No | Database to compile against | -| `library` | string | No | Additional search paths for libraries | - -**Example:** - -```text -Compile a query: -- query: /path/to/MyQuery.ql -- database: /path/to/database -``` - -### codeql_query_format - -Format CodeQL queries according to standard conventions. - -**Parameters:** - -| Parameter | Type | Required | Description | -| ---------- | -------- | -------- | ------------------------------------------ | -| `files` | string[] | Yes | Paths to the query files to format | -| `in-place` | boolean | No | Whether to modify the query files in place | - -**Example:** - -```text -Format queries in place: -- files: - - /path/to/MyQuery.ql -- in-place: true -``` - -### create_codeql_query - -Create a new CodeQL query with proper directory structure and test scaffolding. - -**Parameters:** - -| Parameter | Type | Required | Description | -| ------------- | ------ | -------- | ---------------------------------------------- | -| `queryName` | string | Yes | Name of the query to create | -| `language` | string | Yes | Target language (e.g., `python`, `javascript`) | -| `basePath` | string | Yes | Base path for the query | -| `description` | string | No | Query description | - -**Example:** - -```text -Create a new query: -- queryName: SqlInjection -- language: python -- basePath: /path/to/queries -``` - -## Query Execution Tools - -### codeql_query_run - -Execute a CodeQL query against a database. - -**Parameters:** - -| Parameter | Type | Required | Description | -| ---------- | ------ | -------- | ---------------------------- | -| `query` | string | Yes | Path to the query file | -| `database` | string | Yes | Path to the CodeQL database | -| `output` | string | No | Output file path for results | -| `timeout` | number | No | Execution timeout in seconds | - -**Example:** - -```text -Run a query: -- query: /path/to/MyQuery.ql -- database: /path/to/database -- output: /path/to/results.bqrs -``` - -### codeql_execute_query_server2 - -Execute queries using the CodeQL query server for improved performance. - -**Parameters:** - -| Parameter | Type | Required | Description | -| ---------- | ------ | -------- | --------------------------- | -| `query` | string | Yes | Path to the query file | -| `database` | string | Yes | Path to the CodeQL database | - -**Example:** - -```text -Execute with query server: -- query: /path/to/MyQuery.ql -- database: /path/to/database -``` - -### codeql_database_analyze - -Run analysis queries against a CodeQL database. - -**Parameters:** - -| Parameter | Type | Required | Description | -| ---------- | ------ | -------- | -------------------------------- | -| `database` | string | Yes | Path to the CodeQL database | -| `queries` | string | No | Query suite or pack to run | -| `format` | string | No | Output format (sarif, csv, etc.) | -| `output` | string | No | Output file path | - -**Example:** - -```text -Analyze a database: -- database: /path/to/database -- queries: codeql/python-queries -- format: sarif -- output: /path/to/results.sarif -``` - -## Validation & LSP Tools - -### validate_codeql_query - -Quick heuristic validation for CodeQL query structure. Checks for common patterns like `from`/`where`/`select` clauses and metadata presence. Does **not** compile the query. - -**Parameters:** - -| Parameter | Type | Required | Description | -| ---------- | ------ | -------- | --------------------------------- | -| `query` | string | Yes | The CodeQL query text to validate | -| `language` | string | No | Target programming language | - -### codeql_lsp_diagnostics - -Authoritative syntax and semantic validation of CodeQL (QL) code via the CodeQL Language Server. Compiles the query and provides real-time diagnostics with precise error locations. - -> **Note**: Inline `ql_code` is evaluated as a virtual document and cannot resolve pack imports (e.g., `import javascript`). For validating queries with imports, use `codeql_query_compile` on the actual file instead. This tool is best for syntax validation and checking QL code fragments that don't depend on external libraries. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------------- | ------ | -------- | ---------------------------------------------------- | -| `ql_code` | string | Yes | The CodeQL code to evaluate | -| `workspace_uri` | string | No | Workspace URI for context (defaults to `./ql`) | -| `search_path` | string | No | Search path for CodeQL libraries | -| `log_level` | string | No | Log level: OFF, ERROR, WARN, INFO, DEBUG, TRACE, ALL | - -### codeql_lsp_completion - -Get code completions at a cursor position in a CodeQL file. - -> **Important**: Set `workspace_uri` to the pack or workspace root directory (as a `file://` URI) for dependency resolution. Without it, completions for imported library types will be empty. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------------- | ------ | -------- | ------------------------------------------------------------------------------ | -| `file_path` | string | Yes | Path to the `.ql`/`.qll` file (relative paths resolved against user workspace) | -| `line` | number | Yes | 0-based line number | -| `character` | number | Yes | 0-based character offset | -| `file_content` | string | No | File content override (reads disk if omitted) | -| `search_path` | string | No | Search path for CodeQL libraries | -| `workspace_uri` | string | No | Workspace URI for context | - -### codeql_lsp_definition - -Go to the definition of a CodeQL symbol at a given position. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------------- | ------ | -------- | ------------------------------------------------------------------------------ | -| `file_path` | string | Yes | Path to the `.ql`/`.qll` file (relative paths resolved against user workspace) | -| `line` | number | Yes | 0-based line number | -| `character` | number | Yes | 0-based character offset | -| `file_content` | string | No | File content override (reads disk if omitted) | -| `search_path` | string | No | Search path for CodeQL libraries | -| `workspace_uri` | string | No | Workspace URI for context | - -### codeql_lsp_references - -Find all references to a CodeQL symbol at a given position. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------------- | ------ | -------- | ------------------------------------------------------------------------------ | -| `file_path` | string | Yes | Path to the `.ql`/`.qll` file (relative paths resolved against user workspace) | -| `line` | number | Yes | 0-based line number | -| `character` | number | Yes | 0-based character offset | -| `file_content` | string | No | File content override (reads disk if omitted) | -| `search_path` | string | No | Search path for CodeQL libraries | -| `workspace_uri` | string | No | Workspace URI for context | - -## Testing Tools - -### codeql_test_run - -Run CodeQL unit tests. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ----------------------------------- | -| `path` | string | Yes | Path to test directory or test file | -| `threads` | number | No | Number of threads to use | - -**Example:** - -```text -Run tests: -- path: /path/to/tests -- threads: 4 -``` - -### codeql_test_accept - -Accept test results as expected output. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ---------------------- | -| `path` | string | Yes | Path to test directory | - -**Example:** - -```text -Accept test results: -- path: /path/to/test -``` - -### codeql_test_extract - -Extract test databases from test source files. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ---------------------- | -| `path` | string | Yes | Path to test directory | - -**Example:** - -```text -Extract test database: -- path: /path/to/test -``` - -## Database Operations - -### codeql_database_create - -Create a CodeQL database from source code. - -**Parameters:** - -| Parameter | Type | Required | Description | -| ---------- | ------ | -------- | --------------------------- | -| `source` | string | Yes | Path to source code | -| `language` | string | Yes | Programming language | -| `database` | string | Yes | Output database path | -| `command` | string | No | Build command (if required) | - -**Example:** - -```text -Create a database: -- source: /path/to/source -- language: python -- database: /path/to/database -``` - -## Resolution Tools - -### codeql_resolve_database - -Get information about a CodeQL database. - -**Parameters:** - -| Parameter | Type | Required | Description | -| ---------- | ------ | -------- | -------------------- | -| `database` | string | Yes | Path to the database | - -**Example:** - -```text -Resolve database info: -- database: /path/to/database -``` - -### codeql_resolve_languages - -List available CodeQL languages. - -**Parameters:** None - -**Example:** - -```text -List supported languages -``` - -### codeql_resolve_library_path - -Resolve library search paths for a query. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ---------------------- | -| `query` | string | Yes | Path to the query file | - -**Example:** - -```text -Resolve library paths: -- query: /path/to/MyQuery.ql -``` - -### codeql_resolve_metadata - -Get metadata for a query. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ---------------------- | -| `query` | string | Yes | Path to the query file | - -**Example:** - -```text -Get query metadata: -- query: /path/to/MyQuery.ql -``` - -### codeql_resolve_qlref - -Resolve a `.qlref` file to its target query. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ------------------------- | -| `qlref` | string | Yes | Path to the `.qlref` file | - -**Example:** - -```text -Resolve qlref: -- qlref: /path/to/test/MyQuery.qlref -``` - -### codeql_resolve_queries - -Resolve a query suite to individual queries. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ------------------------- | -| `suite` | string | Yes | Query suite specification | - -**Example:** - -```text -Resolve query suite: -- suite: codeql/python-queries -``` - -### codeql_resolve_tests - -Find all tests in a directory. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ------------------------ | -| `path` | string | Yes | Path to search for tests | - -**Example:** - -```text -Find tests: -- path: /path/to/tests -``` - -## BQRS Processing Tools - -### codeql_bqrs_decode - -Decode a BQRS (Binary Query Result Set) file. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ------------------------------- | -| `bqrs` | string | Yes | Path to the BQRS file | -| `format` | string | No | Output format (json, csv, etc.) | -| `output` | string | No | Output file path | - -**Example:** - -```text -Decode BQRS file: -- bqrs: /path/to/results.bqrs -- format: json -``` - -### codeql_bqrs_info - -Get information about a BQRS file. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | --------------------- | -| `bqrs` | string | Yes | Path to the BQRS file | - -**Example:** - -```text -Get BQRS info: -- bqrs: /path/to/results.bqrs -``` - -### codeql_bqrs_interpret - -Interpret BQRS results as SARIF or other formats. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | --------------------- | -| `bqrs` | string | Yes | Path to the BQRS file | -| `format` | string | No | Output format | -| `output` | string | No | Output file path | - -**Example:** - -```text -Interpret as SARIF: -- bqrs: /path/to/results.bqrs -- format: sarif -- output: /path/to/results.sarif -``` - -## Utility Tools - -### find_codeql_query_files - -Find all files related to a CodeQL query. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ---------------------- | -| `query` | string | Yes | Path to the query file | - -**Example:** - -```text -Find related files: -- query: /path/to/MyQuery.ql -``` - -### codeql_pack_install - -Install CodeQL pack dependencies. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ---------------------- | -| `path` | string | Yes | Path to pack directory | - -**Example:** - -```text -Install dependencies: -- path: /path/to/pack -``` - -### codeql_pack_ls - -List contents of a CodeQL pack. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ---------------------- | -| `path` | string | Yes | Path to pack directory | - -**Example:** - -```text -List pack contents: -- path: /path/to/pack -``` - -### codeql_generate_log_summary - -Generate a summary of CodeQL evaluator logs. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | -------------------------- | -| `log` | string | Yes | Path to evaluator log file | - -**Example:** - -```text -Summarize log: -- log: /path/to/evaluator-log.json -``` - -### codeql_generate_query_help - -Generate documentation for a query. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ---------------------- | -| `query` | string | Yes | Path to the query file | -| `output` | string | No | Output file path | - -**Example:** - -```text -Generate help: -- query: /path/to/MyQuery.ql -- output: /path/to/MyQuery.md -``` - -### rank_sarif_results - -Rank SARIF results to identify likely true positives and false positives. - -**Parameters:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | ------------------ | -| `sarif` | string | Yes | Path to SARIF file | - -**Example:** - -```text -Rank results: -- sarif: /path/to/results.sarif -``` - -## Common Workflows - -### Creating and Testing a New Query - -1. Use `create_codeql_query` to scaffold the query structure -2. Edit the generated query file -3. Use `codeql_query_compile` to check for errors -4. Use `codeql_test_run` to run tests -5. Use `codeql_test_accept` to accept correct results - -### Running Analysis on a Codebase - -1. Use `codeql_database_create` to build a database -2. Use `codeql_query_run` or `codeql_database_analyze` to run queries -3. Use `codeql_bqrs_decode` or `codeql_bqrs_interpret` to process results - -### Debugging Query Issues - -1. Use `codeql_resolve_library_path` to check library resolution -2. Use `codeql_resolve_metadata` to verify query metadata -3. Use `codeql_generate_log_summary` to analyze performance - -## Related Documentation - -- [Getting Started Guide](./getting-started.md)