Address latest PR review comments

Author: data-douser

.github/instructions/server_src_resources_md.instructions.md

@@ -0,0 +1,55 @@
+---
+applyTo: 'server/src/resources/**/*.md'
+description: 'Instructions for MCP server resource markdown files served to LLMs.'
+---
+
+# Copilot Instructions for `server/src/resources/**/*.md` resource files
+
+## PURPOSE
+
+This file contains instructions for working with markdown resource files in the `server/src/resources/` directory. These files are imported at build time (via esbuild's `.md: 'text'` loader) and served to LLMs through MCP resource endpoints (e.g., `codeql://server/overview`, `codeql://languages/go/ast`). Because LLMs consume these files as authoritative reference material, correctness and consistency are critical.
+
+## REQUIREMENTS
+
+- ALWAYS name resource files to match their MCP endpoint path. For example, a resource served at `codeql://server/overview` must be named `server-overview.md`, and a resource at `codeql://languages/go/ast` must be `languages/go_ast.md`.
+- ALWAYS start each resource file with a `#`-level (H1) heading that identifies the resource topic and scope.
+- ALWAYS use the v2 module-based DataFlow/TaintTracking API (`module MyConfig implements DataFlow::ConfigSig` with `TaintTracking::Global<MyConfig>`) in all CodeQL code examples. NEVER use the deprecated v1 class-based API (`class MyConfig extends TaintTracking::Configuration` with `override predicate`).
+- ALWAYS use `codeql-pack.yml` (not `qlpack.yml`) as the pack configuration filename in all code examples and references.
+- ALWAYS ensure any new resource file has a corresponding import and registration in `server/src/types/language-types.ts` (for language-specific resources) or `server/src/lib/resources.ts` (for general resources), and that the test expectations in `server/test/src/resources/` are updated accordingly.
+- ALWAYS verify ASCII art diagrams have consistent box corners and formatting.
+- ALWAYS ensure code examples are syntactically correct — class names, constructor names, and predicate names must all match (e.g., a class named `FooAsSink` must have a constructor named `FooAsSink()`).
+- **ALWAYS run `npm run build-and-test` from the repo root directory and ensure it passes completely before committing any changes.**
+
+## PREFERENCES
+
+- PREFER actionable, tool-oriented content that tells an LLM exactly which MCP tools and prompts to invoke and in what order, over abstract descriptions.
+- PREFER concrete code examples over prose explanations for CodeQL patterns and idioms.
+- PREFER a single authoritative location for each piece of documentation — if content exists in a resource file, repo-level docs should reference it rather than restate it.
+
+## DOCUMENTATION RELATIONSHIP: `server/src/resources/` ↔ `docs/ql-mcp/`
+
+The `server/src/resources/server-*.md` files are the **authoritative source** for MCP server tools, prompts, and queries documentation. The `docs/ql-mcp/*.md` files are **thin wrappers** that link to these authoritative sources.
+
+### When to update which file
+
+| Change type                                  | Update `server/src/resources/server-*.md` | Update `docs/ql-mcp/*.md`              |
+| -------------------------------------------- | ----------------------------------------- | -------------------------------------- |
+| Add, remove, or modify an MCP tool           | YES — `server-tools.md`                   | Only if monitoring tools table changes |
+| Add, remove, or modify an MCP prompt         | YES — `server-prompts.md`                 | NO — wrapper links to resource file    |
+| Add or remove a language resource            | YES — registration in source code         | YES — update language table            |
+| Add or remove a static resource              | YES — resource file + registration        | YES — update static resources table    |
+| Change a resource URI or endpoint path       | YES — rename file to match new path       | YES — update URI references            |
+| Fix a typo or improve wording in tool/prompt | YES — resource file only                  | NO — wrapper inherits the fix          |
+
+### Rules
+
+- ALWAYS update the authoritative `server/src/resources/server-*.md` file first, then verify the `docs/ql-mcp/*.md` wrapper still links correctly.
+- ALWAYS keep `docs/ql-mcp/*.md` as thin wrappers — they should contain only a brief overview, a link to the authoritative resource file, and any content that is NOT served via MCP (e.g., the optional monitoring tools table in `docs/ql-mcp/tools.md`).
+- NEVER duplicate detailed tool, prompt, or resource descriptions in both `server/src/resources/` and `docs/ql-mcp/`. The `docs/ql-mcp/` file must defer to the resource file for all MCP-served content.
+
+## CONSTRAINTS
+
+- NEVER leave any trailing whitespace on any line.
+- NEVER include placeholder or TODO content in resource files — if a resource is not ready, exclude it from registration until the content is complete.
+- NEVER reference deprecated or removed MCP tools in resource files. When a tool is deprecated, remove all mentions from resource files.
+- NEVER mix deprecated and current API patterns in code examples within the same file or across files in this directory.

docs/ql-mcp/resources.md

@@ -32,7 +32,6 @@ Each supported language can expose one or more of the following resource types u
 | java       |       ✓       |                   |                                           |
 | javascript |       ✓       |         ✓         |                                           |
 | python     |       ✓       |         ✓         |                                           |
-| ql         |       ✓       |                   |                                           |
 | ruby       |       ✓       |                   |                                           |
 
 ### Resource Types

server/dist/codeql-development-mcp-server.js

@@ -1,3 +1,5 @@
+# CodeQL AST nodes for `actions` language
+
 ## CodeQL's core AST classes for `actions` language
 
 Based on analysis of CodeQL's Actions AST test results from local test files, here are the core AST classes for GitHub Actions analysis:

server/dist/codeql-development-mcp-server.js.map

@@ -205,22 +205,20 @@ class EncodingMethod extends MethodCall {
 
 ```ql
 // Configuration for inappropriate encoding detection
-private class InappropriateEncodingConfiguration extends TaintTracking::Configuration {
-  InappropriateEncodingConfiguration() { this = "InappropriateEncodingConfiguration" }
-
-  override predicate isSource(DataFlow::Node source) {
+module InappropriateEncodingConfig implements DataFlow::ConfigSig {
+  predicate isSource(DataFlow::Node source) {
     // Encoded values that might be inappropriate for their context
     source.asExpr() instanceof EncodingMethod
   }
 
-  override predicate isSink(DataFlow::Node sink) {
+  predicate isSink(DataFlow::Node sink) {
     // Sinks that require specific encoding types
     sink instanceof SqlCommandSink or
     sink instanceof HtmlOutputSink or
     sink instanceof UrlRedirectSink
   }
 
-  override predicate isAdditionalTaintStep(DataFlow::Node node1, DataFlow::Node node2) {
+  predicate isAdditionalFlowStep(DataFlow::Node node1, DataFlow::Node node2) {
     // String concatenation and formatting preserve taint
     exists(AddExpr add |
       add.getAnOperand() = node1.asExpr() and
@@ -235,6 +233,8 @@ private class InappropriateEncodingConfiguration extends TaintTracking::Configur
     )
   }
 }
+
+module InappropriateEncodingFlow = TaintTracking::Global<InappropriateEncodingConfig>;
 ```
 
 ## Security Query Implementation Guide

server/src/resources/languages/actions_ast.md

@@ -379,7 +379,7 @@ extensions:
 Create a CodeQL model pack to group and distribute YAML files:
 
 ```yaml
-# qlpack.yml
+# codeql-pack.yml
 name: my-org/go-security-models
 version: 1.0.0
 dependencies:
@@ -391,7 +391,7 @@ dataExtensions: '*.yml'
 
 ```
 my-go-models/
-├── qlpack.yml
+├── codeql-pack.yml
 ├── http-frameworks.yml
 ├── database-orms.yml
 └── json-libraries.yml
@@ -406,7 +406,7 @@ codeql pack publish
 ### Consuming Model Packs
 
 ```yaml
-# In consumer's qlpack.yml
+# In consumer's codeql-pack.yml
 dependencies:
   my-org/go-security-models: '^1.0.0'
 ```

server/src/resources/languages/csharp_security_query_guide.md

@@ -179,8 +179,8 @@ module VulnerabilityName {
   private class RemoteFlowSourceAsSource extends Source instanceof RemoteFlowSource { }
 
   // Define specific sinks based on vulnerability type
-  private class SpecificSinkAssink extends Sink {
-    SpecificSinkAsink() {
+  private class SpecificSinkAsSink extends Sink {
+    SpecificSinkAsSink() {
       // Define sink patterns here
     }
   }
@@ -267,14 +267,12 @@ select sink.getNode(), source, sink, "[Alert message with $@ placeholder]",
 **SSRF Detection Pattern:**
 
 ```ql
-private class RequestForgeryConfiguration extends TaintTracking::Configuration {
-  RequestForgeryConfiguration() { this = "RequestForgeryConfiguration" }
-
-  override predicate isSource(DataFlow::Node source) {
+module RequestForgeryConfig implements DataFlow::ConfigSig {
+  predicate isSource(DataFlow::Node source) {
     source instanceof RemoteFlowSource
   }
 
-  override predicate isSink(DataFlow::Node sink) {
+  predicate isSink(DataFlow::Node sink) {
     // HTTP client requests where URL is controllable
     exists(DataFlow::CallNode call |
       call = DataFlow::moduleImport("axios").getAMemberCall(["get", "post", "put", "delete"]) and
@@ -290,19 +288,19 @@ private class RequestForgeryConfiguration extends TaintTracking::Configuration {
     )
   }
 }
+
+module RequestForgeryFlow = TaintTracking::Global<RequestForgeryConfig>;
 ```
 
 **XSS Detection Pattern:**
 
 ```ql
-private class ReflectedXssConfiguration extends TaintTracking::Configuration {
-  ReflectedXssConfiguration() { this = "ReflectedXssConfiguration" }
-
-  override predicate isSource(DataFlow::Node source) {
+module ReflectedXssConfig implements DataFlow::ConfigSig {
+  predicate isSource(DataFlow::Node source) {
     source instanceof RemoteFlowSource
   }
 
-  override predicate isSink(DataFlow::Node sink) {
+  predicate isSink(DataFlow::Node sink) {
     // DOM manipulation sinks
     exists(DataFlow::PropWrite pw |
       pw.getPropertyName() in ["innerHTML", "outerHTML"] and
@@ -315,6 +313,8 @@ private class ReflectedXssConfiguration extends TaintTracking::Configuration {
     )
   }
 }
+
+module ReflectedXssFlow = TaintTracking::Global<ReflectedXssConfig>;
 ```
 
 ## Testing Patterns

server/src/resources/languages/go_library_modeling.md

@@ -14,8 +14,6 @@ The `profile_codeql_query_from_logs` tool is the primary means of evaluating the
 4. **Identify bottlenecks**: Review the profile output for predicates with high evaluation times or unexpectedly large result sets.
 5. **Refine**: Modify the query to address identified bottlenecks, then re-run and re-profile to verify improvements.
 
-Alternatively, use `profile_codeql_query` to profile a query by running it against a specific database and analyzing the resulting evaluator log in a single step.
-
 ### What the Profile Shows
 
 - **Predicate evaluation times** — which predicates are the most expensive
@@ -83,14 +81,13 @@ For monorepos with multiple independent applications separated by process/networ
 
 ## Related Tools and Prompts
 
-| Tool / Prompt                                    | Purpose                                                              |
-| ------------------------------------------------ | -------------------------------------------------------------------- |
-| `profile_codeql_query`                           | Profile a query run against a database (runs the query and profiles) |
-| `profile_codeql_query_from_logs`                 | Profile from existing evaluator logs (no re-run needed)              |
-| `codeql_generate_log-summary`                    | Generate a human-readable evaluator log summary                      |
-| `codeql_query_run`                               | Execute a query (set `evaluationOutput` to capture logs)             |
-| `explain_codeql_query` prompt                    | Understand query evaluation flow with Mermaid diagrams               |
-| `run_query_and_summarize_false_positives` prompt | Assess result quality (precision)                                    |
+| Tool / Prompt                                    | Purpose                                                  |
+| ------------------------------------------------ | -------------------------------------------------------- |
+| `profile_codeql_query_from_logs`                 | Profile from existing evaluator logs (no re-run needed)  |
+| `codeql_generate_log-summary`                    | Generate a human-readable evaluator log summary          |
+| `codeql_query_run`                               | Execute a query (set `evaluationOutput` to capture logs) |
+| `explain_codeql_query` prompt                    | Understand query evaluation flow with Mermaid diagrams   |
+| `run_query_and_summarize_false_positives` prompt | Assess result quality (precision)                        |
 
 ## Related Resources