[UPDATE PRIMITIVE] Fix codeql_database_analyze additionalArgs pass-through

[Copilot]

📝 Update Information

Primitive Details

• Type: Tool
• Name: codeql_database_analyze (and all CLI tools with additionalArgs)
• Update Category: Bug Fix

⚠️ CRITICAL: PR SCOPE VALIDATION

• ONLY server implementation files are included
• NO temporary or output files are included
• NO unrelated configuration files are included
• ALL existing tests continue to pass
• NEW functionality is properly tested

---

• Impact Scope: Moderate — affects all CLI tools that declare additionalArgs in their schema

Update Metadata

• Breaking Changes: No
• API Compatibility: Maintained (existing schema unchanged)
• Performance Impact: Neutral

🎯 Changes Description

Current Behavior

additionalArgs: ["--sarif-include-query-help=always", "--no-sarif-minify"] stays in the options object and gets processed by buildCodeQLArgs(), producing invalid CLI arguments:

--additionalArgs=--sarif-include-query-help=always --additionalArgs=--no-sarif-minify

Updated Behavior

additionalArgs is extracted from options before buildCodeQLArgs() runs. The raw strings are appended after positional args, producing correct CLI output:

codeql database analyze --format=sarif-latest /path/to/db query.ql --sarif-include-query-help=always --no-sarif-minify

Additionally, for tools with post-execution processing (codeql_query_run, codeql_test_run, codeql_database_analyze), internally-managed flags (--logdir, --evaluator-log, --output, --verbosity, --tuple-counting) are filtered from additionalArgs with a warning. These flags are set internally and their values are read back by post-processing (e.g., log summary generation, SARIF interpretation). Passing them via additionalArgs would create conflicting duplicates and cause post-processing to use stale values. Users should use the corresponding named parameters instead.

The managed-flag filter handles both inline (--flag=value) and space-separated (--flag value) forms. When a managed flag is supplied in space-separated form (e.g., ['--output', '/override.sarif']), both the flag token and the following value token are removed, preventing stray positional arguments from leaking into the CLI invocation.

Motivation

Any --key=value style argument passed via additionalArgs was mangled, making the feature unusable for its intended purpose. Additionally, unfiltered pass-through of managed flags could silently break post-execution processing.

🔄 Before vs. After Comparison

Functionality Changes

// BEFORE: additionalArgs left in options, processed by buildCodeQLArgs
result = await executeCodeQLCommand(subcommand, options, positionalArgs, cwd);
// options still contains { additionalArgs: ["--sarif-include-query-help=always"] }
// buildCodeQLArgs emits: --additionalArgs=--sarif-include-query-help=always  ← WRONG

// AFTER: additionalArgs extracted, managed flags filtered (both forms), raw args appended
const rawAdditionalArgs = Array.isArray(options.additionalArgs)
  ? options.additionalArgs as string[]
  : [];
delete options.additionalArgs;

// Filter managed flags for tools with post-processing using a for-loop
// that handles both --flag=value and --flag value (space-separated) forms
const userAdditionalArgs = queryLogDir
  ? (() => {
      const filtered: string[] = [];
      for (let i = 0; i < rawAdditionalArgs.length; i += 1) {
        const arg = rawAdditionalArgs[i];
        const m = arg.match(/^--(?:no-)?([^=]+)(?:=.*)?$/);
        if (m && managedFlagNames.has(m[1])) {
          logger.warn(`Ignoring "${arg}" from additionalArgs: use the named parameter instead.`);
          // Skip the following value token for space-separated form
          if (!arg.includes('=') && i + 1 < rawAdditionalArgs.length) i += 1;
          continue;
        }
        filtered.push(arg);
      }
      return filtered;
    })()
  : rawAdditionalArgs;

result = await executeCodeQLCommand(
  subcommand, options, [...positionalArgs, ...userAdditionalArgs], cwd
);
// emits: --sarif-include-query-help=always  ← CORRECT
// managed flags like --logdir, --output are filtered out with warning
// space-separated values like ['--output', 'file.sarif'] are fully removed

API Changes

No schema changes. The existing additionalArgs: z.array(z.string()).optional() now works as documented.

Output Format Changes

No output format changes.

🧪 Testing & Validation

Test Coverage Updates

• Existing Tests: All existing tests continue to pass
• New Test Cases: 5 tests added
• Regression Tests: Test verifies additionalArgs never appears in options passed to CLI
• Edge Case Tests: Missing/undefined additionalArgs handled gracefully; managed flag filtering validated for both --flag=value and --flag value (space-separated) forms

Validation Scenarios

1. Backward Compatibility: Existing codeql_database_analyze test without additionalArgs still passes
2. New Functionality: --sarif-include-query-help=always and --no-sarif-minify passed through correctly
3. Error Handling: Undefined additionalArgs produces empty array (no-op)
4. Managed Flag Filtering (inline): --logdir=/override, --evaluator-log=/override.jsonl, --output=/override.sarif, --no-tuple-counting, --verbosity=errors are filtered from additionalArgs for tools with post-processing; non-managed flags pass through
5. Managed Flag Filtering (space-separated): ['--output', '/override.sarif'], ['--logdir', '/override'], ['--verbosity', 'errors'] are fully removed (both flag and value tokens) without leaving stray positional arguments

Test Results

• Unit Tests: All pass
• Integration Tests: 67/68 pass (1 pre-existing codeql_pack_install network failure)

📋 Implementation Details

Files Modified

• Supporting Libraries: server/src/lib/cli-tool-registry.ts — extract additionalArgs before CLI arg building; filter managed flags for tools with post-processing (handles both inline and space-separated forms)
• Tests: server/test/src/lib/cli-tool-registry.test.ts — 5 new test cases
• Bundle: server/dist/ — rebuilt

Code Changes Summary

• Bug Fix: additionalArgs no longer mangled by buildCodeQLArgs
• Error Handling: Managed flags filtered from additionalArgs with warning for tools with post-execution processing, covering both --flag=value and --flag value forms

Dependencies

• No New Dependencies

🔍 Quality Improvements

Bug Fixes

• Issue: additionalArgs values transformed into --additionalArgs=<value> instead of raw pass-through
• Root Cause: additionalArgs was not extracted from options before buildCodeQLArgs(), which treats all array entries as --key=value pairs
• Solution: Extract and delete additionalArgs from options, append as raw args. Filter managed flags (--logdir, --evaluator-log, --output, --verbosity, --tuple-counting) for tools with post-processing to prevent conflicting duplicates and stale post-processing state. The filter uses a for loop over the argv list to handle both --flag=value (inline) and --flag value (space-separated) forms, skipping the following value token in the space-separated case to prevent stray positional arguments.
• Prevention: Unit tests assert additionalArgs never appears in the options object passed to the CLI executor; managed flag filtering tests validate both inline and space-separated forms, and both filtered and pass-through args

🔗 References

External References

• codeql database analyze -h -vv documents --sarif-include-query-help and --no-sarif-minify flags

🚀 Compatibility & Migration

Backward Compatibility

• Fully Compatible: No breaking changes. Tools without additionalArgs are unaffected; undefined additionalArgs produces an empty array. Managed flags in additionalArgs are filtered with a warning (not an error), directing users to use the corresponding named parameter.

API Evolution

• Maintained Contracts: Core API contracts preserved

👥 Review Guidelines

For Reviewers

• ⚠️ SCOPE COMPLIANCE: PR contains only server implementation files
• ⚠️ NO UNRELATED FILES: No temporary, output, or unrelated files
• ⚠️ BACKWARD COMPATIBILITY: Existing functionality preserved

Testing Instructions

npm run build-and-test
# or targeted:
cd server && npx vitest run --reporter=verbose 2>&1 | grep -i "additional\|managed\|space-separated"

📊 Impact Assessment

Server Impact

• Startup Time: No impact
• Runtime Stability: No impact
• Resource Usage: No impact
• Concurrent Usage: Safe

AI Assistant Impact

• Enhanced Accuracy: LLMs can now pass arbitrary codeql database analyze flags via additionalArgs
• Improved Reliability: Arguments like --sarif-include-query-help=always no longer silently fail; managed flags are filtered with a clear warning instead of causing conflicting CLI behavior; space-separated managed flags no longer leave stray values

🔄 Deployment Strategy

Rollout Considerations

• Safe Deployment: Pure bug fix, no new APIs
• Rollback Plan: Revert single commit

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.

[github-actions]

Dependency Review

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

Snapshot Warnings

⚠️: No snapshots were found for the head SHA 218f339.

Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

Scanned Files

• package-lock.json

[Copilot]

Pull request overview

Fixes how additionalArgs are passed to CLI tool executions so user-supplied flags are forwarded as raw arguments (instead of being transformed into --additionalArgs=<value>), improving correctness for codeql_database_analyze and any other tools that expose additionalArgs.

Changes:

• Extract additionalArgs from the options object before building CodeQL/QLT args, and append them as raw CLI args.
• Add unit tests validating additionalArgs pass-through for codeql_database_analyze, missing additionalArgs, and a generic CodeQL tool case.
• Rebuild the bundled server/dist output.

Reviewed changes

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

File	Description
server/src/lib/cli-tool-registry.ts	Extracts additionalArgs from options and appends them to the executor arg list as raw CLI flags.
server/test/src/lib/cli-tool-registry.test.ts	Adds regression tests for additionalArgs pass-through behavior (currently only for CodeQL path).
server/dist/codeql-development-mcp-server.js	Updates bundled output to reflect the new argument-handling logic.

[Copilot]

Pull request overview

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

[data-douser]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

Applied in ab9c9e5. The managed-flag filter now uses a for loop instead of .filter() to handle space-separated forms (e.g. ['--output', '/override.sarif']) — both the flag and its following value token are skipped. Added a new test case that verifies space-separated --output, --logdir, and --verbosity forms are fully removed (flag + value) while non-managed flags pass through.