Implement duplicated code detection prompts, supported by tools.

[MichaelRFairhurst]

Adds tools to find symbols in a file to help detect duplicated code.

Fixes ql libraries resolve.

Adds ql pack resolve which works without a ql file to base on.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

Adds new workflow prompts and supporting tooling to help detect duplicated CodeQL definitions and discover overlapping queries/libraries, along with improvements to CodeQL pack/library resolution.

Changes:

• Added two new workflow prompts: check_for_duplicated_code and find_overlapping_queries, including new prompt templates and prompt-loader registrations.
• Introduced a new LSP tool codeql_lsp_document_symbols (plus language-server support) to enumerate file symbols for duplication/overlap analysis.
• Added codeql resolve packs CLI tool wrapper and fixed resolve library-path argument handling to use --query.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
server/test/src/prompts/workflow-prompts.test.ts	Updates prompt registry tests for the two new workflow prompts/schemas.
server/src/tools/lsp/lsp-tools.ts	Registers new codeql_lsp_document_symbols MCP tool.
server/src/tools/lsp/lsp-handlers.ts	Adds handler for document symbols + helper to extract names.
server/src/lib/language-server.ts	Adds SymbolKind/DocumentSymbol/SymbolInformation types and a getDocumentSymbols LSP request wrapper.
server/src/prompts/workflow-prompts.ts	Adds schemas + prompt registrations for duplicated-code and overlapping-queries workflows.
server/src/prompts/prompt-loader.ts	Statically imports and registers the two new prompt templates.
server/src/prompts/check-for-duplicated-code.prompt.md	New prompt content for auditing a file for duplicated definitions.
server/src/prompts/find-overlapping-queries.prompt.md	New prompt content for discovering reusable/overlapping queries and libraries.
server/src/tools/codeql/resolve-packs.ts	Adds a codeql_resolve_packs CLI tool definition.
server/src/tools/codeql/resolve-library-path.ts	Updates resolve library-path tool to require query (matches CLI usage).
server/src/lib/cli-tool-registry.ts	Restores --query as a named flag for codeql_resolve_library-path.
server/src/tools/codeql/index.ts	Exports the new codeqlResolvePacksTool.
server/src/tools/codeql-tools.ts	Registers the new codeqlResolvePacksTool.

Comments suppressed due to low confidence (8)

server/src/tools/lsp/lsp-tools.ts:210

• A new tool (codeql_lsp_document_symbols) is registered here, but the existing LSP registration unit test (server/test/src/tools/lsp/lsp-tools.test.ts) still asserts only 3 direct tool registrations and mocks only completion/definition/references. Please update/add tests to cover the new tool registration and handler behavior (including the names_only path) so CI doesn’t break and the new feature is exercised.

  // --- codeql_lsp_document_symbols ---
  server.tool(
    'codeql_lsp_document_symbols',
    'List all top-level definitions (classes, predicates, modules) in a CodeQL file. Response contains location and type information unless names_only is set to true.',
    {
      names_only: z.boolean().optional().describe('If true, returns only symbol names as a compact string array instead of full symbol objects. Use this when you only need to know what names a file defines.'),
      ...lspFileParamsSchema,
    },
    async (input) => {
      try {
        const symbols = await lspDocumentSymbols({
          fileContent: input.file_content,
          filePath: input.file_path,
          searchPath: input.search_path,
          workspaceUri: input.workspace_uri,
        });
        let result;
        if (input.names_only) {
          result = extractNamesFromDocumentSymbols(symbols);
        } else {
          result = symbols;
        }
        return {
          content: [{
            text: JSON.stringify({ symbolCount: result.length, symbols: result }, null, 2),
            type: 'text' as const,
          }],
        };
      } catch (error) {
        logger.error('codeql_lsp_document_symbols error:', error);
        return {
          content: [{ text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`, type: 'text' as const }],
          isError: true,
        };
      }
    },
  );

server/src/tools/codeql-tools.ts:157

• Registering codeqlResolvePacksTool increases the number of CodeQL tools registered. The unit test server/test/src/tools/codeql-tools.test.ts currently asserts an exact call count (35) and will fail unless updated. Please adjust the test expectations and consider adding an assertion that codeql_resolve_packs is present in the registered tool names.

  registerCLITool(server, codeqlResolveDatabaseTool);
  registerCLITool(server, codeqlResolveLanguagesTool);
  registerCLITool(server, codeqlResolveLibraryPathTool);
  registerCLITool(server, codeqlResolveMetadataTool);
  registerCLITool(server, codeqlResolvePacksTool);
  registerCLITool(server, codeqlResolveQlrefTool);

server/src/lib/cli-tool-registry.ts:346

• This new special-casing for codeql_resolve_library-path argument handling should be covered by a focused unit test in server/test/src/lib/cli-tool-registry.test.ts to ensure --query is emitted as a named flag (and not as a positional arg) going forward. Without a test, regressions here are likely and would break prompt workflows relying on library-path resolution.

          case 'codeql_resolve_library-path':
            // --query is a named flag for resolve library-path, not positional.
            // It was extracted from options so we need to restore it.
            if (query) {
              options.query = query;
            }
            break;

server/src/prompts/check-for-duplicated-code.prompt.md:33

• The example QL snippet has a syntax error (... and followed by and exists(...)). Since this is intended as guidance, please fix the duplicated and so users don’t copy/paste invalid QL.

This issue also appears on line 40 of the same file.

// Duplicated: class should extend `Operator`, not `Function`
class ThrowingOperator extends Function {
  ThrowingOperator() {
    // Duplicated: this check is implied by using base class `Operator`
    this.getName().matches("%operator%") and
    and exists(ThrowExpr te |
      // Duplicated: this is equivalent to `te.getEnclosingFunction() = this`
      te.getParent*() = this.getAChild()
    )

server/src/prompts/check-for-duplicated-code.prompt.md:55

• Minor wording issue: “Existing definitions map wrap complex ideas…” reads like a typo. Consider changing it to “wrap complex ideas…” or “map and wrap complex ideas…” for clarity.

- **Readability**: Existing definitions map wrap complex ideas into readable names
- **Consistency**: A single source of truth makes for a more consistent user experience across queries
- **Completeness/Correctness**: Recreating an already-existing definition can miss edge cases, resulting in false positives or false negatives

server/src/prompts/find-overlapping-queries.prompt.md:140

• This note says “All line/character positions returned by LSP tools are 0-based”, but at least codeql_lsp_definition/codeql_lsp_references currently format startLine/endLine as 1-based in their JSON output. Please clarify this to avoid off-by-one mistakes (e.g., specify that LSP tool inputs are 0-based, and call out which tool outputs are 0-based vs 1-based).

Note: `workspace_uri` must be a **plain directory path**, not a `file://` URI. All
line/character positions returned by LSP tools are **0-based**.

server/src/tools/codeql/resolve-packs.ts:18

• The format parameter description appears copy/pasted from resolve qlref (it says “qlref resolution”). Please update it to describe the output format for codeql resolve packs results to avoid confusing users.

  inputSchema: {
    'search-path': z.string().describe('The project root, to search packs available in the project. Typically the ".", or the current working directory.'),
    format: z.enum(['text', 'json', 'betterjson']).optional()
      .describe('Output format for qlref resolution'),
    verbose: createCodeQLSchemas.verbose(),
    additionalArgs: createCodeQLSchemas.additionalArgs()

server/src/prompts/check-for-duplicated-code.prompt.md:43

• In the example getASuccessor(Stmt a, Stmt b), the exists(Block b, ...) reuses the name b, shadowing the parameter and making the snippet misleading/incorrect. Rename one of them in the example to avoid confusion.

// Duplicated: `ControlFlowNode.getASuccessor()` already exists in `cpp` and is superior
predicate getASuccessor(Stmt a, Stmt b) {
  exists(Block b, int i | a = b.getChild(i) and b = b.getChild(i + 1))
}

[Copilot]

extractNamesFromDocumentSymbols doesn’t type-check: collectSymbolNames expects an array of the union type, but you call it with symbols: DocumentSymbol[] | SymbolInformation[] (union of arrays), which is not assignable and will fail TypeScript compilation. Consider changing collectSymbolNames to accept the same union type (and normalize to (DocumentSymbol | SymbolInformation)[] internally), or cast after converting to an array-of-union. Also add the missing semicolon on the final return to satisfy repo linting.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (6)

server/src/prompts/check-for-duplicated-code.prompt.md:31

• The QL example contains a syntax error (and appears twice in a row), which makes the “duplicated code” illustration harder to follow and potentially confusing to users.

    // Duplicated: this check is implied by using base class `Operator`
    this.getName().matches("%operator%") and
    and exists(ThrowExpr te |
      // Duplicated: this is equivalent to `te.getEnclosingFunction() = this`

server/src/prompts/check-for-duplicated-code.prompt.md:55

• Grammar typo in the readability bullet: “Existing definitions map wrap …” reads incorrectly and should be corrected so the guidance is clear.

- **Simplicity**: Relying on existing definitions reduces the amount of code to read and understand
- **Readability**: Existing definitions map wrap complex ideas into readable names
- **Consistency**: A single source of truth makes for a more consistent user experience across queries
- **Completeness/Correctness**: Recreating an already-existing definition can miss edge cases, resulting in false positives or false negatives

server/src/prompts/check-for-duplicated-code.prompt.md:183

• The “Report Findings” table includes the same myHelper row twice, which looks accidental and makes the expected output format ambiguous.

| Local name          | Local file    | import path                      | Notes      |
| ------------------- | ------------- | -------------------------------- | ---------- |
| `StandardNamespace` | `query.ql:42` | already imported in `import cpp` | Identical  |
| `myHelper`          | `query.ql:80` | `import myproject.Helpers`       | Equivalent |
| `myHelper`          | `query.ql:80` | `import myproject.Helpers`       | Equivalent |

server/src/tools/lsp/lsp-tools.ts:181

• registerLSPTools now registers an additional tool (codeql_lsp_document_symbols), but the existing unit test server/test/src/tools/lsp/lsp-tools.test.ts mocks only lspCompletion/lspDefinition/lspReferences and asserts only 3 direct server.tool registrations. The test will fail unless it’s updated to mock lspDocumentSymbols/extractNamesFromDocumentSymbols, assert 4 registrations, and add expectations for the new tool’s schema/handler output.

  // --- codeql_lsp_document_symbols ---
  server.tool(
    'codeql_lsp_document_symbols',
    'List all top-level definitions (classes, predicates, modules) in a CodeQL file. Response contains location and type information unless names_only is set to true.',
    {
      names_only: z.boolean().optional().describe('If true, returns only symbol names as a compact string array instead of full symbol objects. Use this when you only need to know what names a file defines.'),
      ...lspFileParamsSchema,
    },

server/src/tools/codeql-tools.ts:158

• Adding codeqlResolvePacksTool changes the total number of tools registered by registerCodeQLTools. The unit test server/test/src/tools/codeql-tools.test.ts currently asserts toHaveBeenCalledTimes(35) and does not include codeql_resolve_packs in its expected tool set; it needs updating so the test suite remains consistent with the registration list.

  registerCLITool(server, codeqlResolveLibraryPathTool);
  registerCLITool(server, codeqlResolveMetadataTool);
  registerCLITool(server, codeqlResolvePacksTool);
  registerCLITool(server, codeqlResolveQlrefTool);
  registerCLITool(server, codeqlResolveQueriesTool);

server/src/tools/codeql/resolve-packs.ts:18

• The format field description appears to be copy/pasted from the qlref tool (it says “Output format for qlref resolution”), but this tool is codeql resolve packs. Updating the description will avoid misleading users of the generated MCP tool schema.

    'search-path': z.string().describe('The project root, to search packs available in the project. Typically the ".", or the current working directory.'),
    format: z.enum(['text', 'json', 'betterjson']).optional()
      .describe('Output format for qlref resolution'),
    verbose: createCodeQLSchemas.verbose(),
    additionalArgs: createCodeQLSchemas.additionalArgs()

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (9)

server/src/tools/lsp/lsp-tools.ts:180

• codeql_lsp_document_symbols is described as listing top-level definitions, but when names_only is true the implementation calls extractNamesFromDocumentSymbols, which recursively collects names from children too (class/module members). Either limit names_only to root symbols for consistency, or update the tool description/parameter name to reflect that nested symbols are included.

This issue also appears on line 60 of the same file.

  server.tool(
    'codeql_lsp_document_symbols',
    'List all top-level definitions (classes, predicates, modules) in a CodeQL file. Response contains location and type information unless names_only is set to true.',
    {
      names_only: z.boolean().optional().describe('If true, returns only symbol names as a compact string array instead of full symbol objects. Use this when you only need to know what names a file defines.'),
      ...lspFileParamsSchema,

server/src/tools/lsp/lsp-handlers.ts:212

• Missing semicolon on return symbolNames will fail lint/formatting in this TypeScript file. Add the semicolon (and ensure the function returns the array).

This issue also appears on line 198 of the same file.

  collectSymbolNames(symbols);

  return symbolNames
}

server/src/prompts/check-for-duplicated-code.prompt.md:33

• The example QL snippet contains a syntax error (...matches(...) and followed by and exists(...)), which may confuse users copying it. Adjust the example so it’s valid QL (single and, or restructure the condition).

  ThrowingOperator() {
    // Duplicated: this check is implied by using base class `Operator`
    this.getName().matches("%operator%") and
    and exists(ThrowExpr te |
      // Duplicated: this is equivalent to `te.getEnclosingFunction() = this`
      te.getParent*() = this.getAChild()
    )

server/src/prompts/check-for-duplicated-code.prompt.md:72

• This repository standardizes on codeql-pack.yml (see repo codeql-workspace.yml), but this prompt references qlpack.yml. Please update references to the pack file name to match the repo convention.

1. The file path of the `.ql` or `.qll` file to audit for code duplication
2. Understand which packs are imported by `qlpack.yml`
3. Understand where the relevant language library packs are located (e.g. `~/.codeql`)
4. Understand where project-specific library packs are located (e.g. `$LANGUAGE/lib` or `$LANGUAGE/common`)
5. Understand where pack-specific shared `.qll` files are located (e.g. `$PACKROOT/common/*.qll`)

server/src/prompts/find-overlapping-queries.prompt.md:186

• This prompt mentions qlpack.yml as the source of query metadata, but this repository standardizes on codeql-pack.yml for pack configuration. Update this reference to avoid sending users to the wrong file name.

- It lives in a subdirectory whose name suggests domain overlap, or
- Its containing rule directory (e.g. `RULE-X-Y-Z/`) has a description that overlaps
  with the new query's domain (check `qlpack.yml` query metadata or directory names
  if available)

server/src/prompts/check-for-duplicated-code.prompt.md:54

• Typo/grammar: "map wrap" should be "may wrap" (or similar) in this bullet point.

- **Simplicity**: Relying on existing definitions reduces the amount of code to read and understand
- **Readability**: Existing definitions map wrap complex ideas into readable names
- **Consistency**: A single source of truth makes for a more consistent user experience across queries

server/src/tools/lsp/lsp-handlers.ts:205

• extractNamesFromDocumentSymbols currently won’t compile: sym is typed as { name?: string }, so sym.children is a TypeScript error, and the in check doesn’t narrow this type. Consider narrowing on the original s value (e.g. treat it as DocumentSymbol when it has children) before recursing, rather than casting to a type that omits children.

  function collectSymbolNames(symbols: (DocumentSymbol | SymbolInformation)[]): void {
    symbols.forEach((s) => {
      const sym = s as { name?: string };
      symbolNames.push(sym.name ?? '(unknown)');
      // Only recurse into children if this is a DocumentSymbol (not SymbolInformation)
      if ('children' in sym && Array.isArray(sym.children)) {
        collectSymbolNames(sym.children);
      }

server/src/tools/lsp/lsp-tools.ts:65

• workspace_uri is described as "defaults to ./ql directory", but getInitializedLanguageServer actually defaults to the server’s bundled ql directory under the package root (converted to a file:// URI). Updating the parameter description here (and in other LSP tool schemas) to reflect the real default would prevent confusion for callers trying to set a pack root for dependency resolution.

const lspFileParamsSchema = {
  file_content: z.string().optional().describe('Optional file content override (reads from disk if omitted)'),
  file_path: z.string().describe('Path to the CodeQL (.ql/.qll) file. Relative paths are resolved against the user workspace directory (see CODEQL_MCP_WORKSPACE).'),
  search_path: z.string().optional().describe('Optional search path for CodeQL libraries'),
  workspace_uri: z.string().optional().describe('Optional workspace URI for context (defaults to ./ql directory)'),
};

server/src/tools/codeql/resolve-packs.ts:17

• The format parameter description appears copy/pasted ("Output format for qlref resolution") but this tool resolves packs. Update the description to reflect pack resolution output to avoid misleading users.

    'search-path': z.string().describe('The project root, to search packs available in the project. Typically the ".", or the current working directory.'),
    format: z.enum(['text', 'json', 'betterjson']).optional()
      .describe('Output format for qlref resolution'),
    verbose: createCodeQLSchemas.verbose(),

[data-douser]

@copilot open a new pull request (PR) to apply changes based on the comments in this thread. In the same PR, be sure to rebase to the latest changes from main branch and resolve any conflicts with server/dist/** by simply rebuilding via npm run tidy && npm run build.

[Copilot]

@data-douser I've opened a new pull request, #122, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 15 changed files in this pull request and generated 7 comments.

[Copilot]

codeql_lsp_document_symbols adds a new tool registration, but there are existing unit tests that assert registerLSPTools registers exactly 3 file-based tools and only mock lspCompletion/lspDefinition/lspReferences. Those tests will now fail and the new tool lacks coverage. Update the LSP tool registration tests/mocks to include codeql_lsp_document_symbols (and its handler output shape, including names_only).

[Copilot]

Registering codeqlResolvePacksTool changes the set/number of CLI tools registered by registerCodeQLTools. There are existing unit tests that assert an exact registration count; those will now be out of date and should be updated to include codeql_resolve_packs (and any new expected tool total).

[Copilot]

The QL example in this prompt contains invalid syntax and confusing shadowing (e.g. ...matches(...) and followed immediately by and exists(...), and predicate getASuccessor(Stmt a, Stmt b) then exists(Block b, ...) reuses b). Since these are teaching examples, they should be syntactically correct and avoid name shadowing to prevent users copying broken code.

[Copilot]

This section documents the codeql_lsp_document_symbols response as if each symbols entry contains fields like kind, range, selectionRange, and children, but the example call sets names_only: true (which the tool implementation returns as a string[] of names). Either set names_only: false for this explanation, or update the description to match the names_only output shape.

[Copilot]

This prompt refers to qlpack.yml, but this repository standardizes on codeql-pack.yml for pack configuration. Please update the prompt text to match the repo’s pack file naming so users look in the right place.

Suggested change

	2. Understand which packs are imported by `qlpack.yml`
	2. Understand which packs are imported by `codeql-pack.yml`

[Copilot]

The example “Report Findings” table has a duplicated myHelper row, which makes the guidance look accidental/noisy. Remove the duplicate row or replace it with a different example entry.

Suggested change

	| Local name | Local file | import path | Notes |
	| ------------------- | ------------- | -------------------------------- | ---------- |
	| `StandardNamespace` | `query.ql:42` | already imported in `import cpp` | Identical |
	| `myHelper` | `query.ql:80` | `import myproject.Helpers` | Equivalent |
	| `myHelper` | `query.ql:80` | `import myproject.Helpers` | Equivalent |
	| Local name | Local file | import path | Notes |
	| ------------------- | ------------- | -------------------------------- | ------------------- |
	| `StandardNamespace` | `query.ql:42` | already imported in `import cpp` | Identical |
	| `myHelper` | `query.ql:80` | `import myproject.Helpers` | Equivalent |
	| `myWrapper` | `query.ql:95` | `import myproject.Helpers` | Thin wrapper only |

[Copilot]

This prompt suggests checking qlpack.yml query metadata, but this repository uses codeql-pack.yml. Update the reference so users follow the correct pack file naming convention.

Suggested change

	with the new query's domain (check `qlpack.yml` query metadata or directory names
	with the new query's domain (check `codeql-pack.yml` query metadata or directory names