@vigolium/piolium 0.0.1

package/skills/codeql/references/language-details.md

@@ -0,0 +1,207 @@
+# Language-Specific Guidance
+
+## No Build Required
+
+### Python
+
+```bash
+codeql database create codeql.db --language=python --source-root=.
+```
+
+**Framework Support:**
+- Django, Flask, FastAPI: Built-in models
+- Tornado, Pyramid: Partial support
+- Custom frameworks: May need data extensions
+
+**Common Issues:**
+| Issue | Fix |
+|-------|-----|
+| Missing Django models | Ensure `settings.py` is at expected location |
+| Virtual env included | Use `paths-ignore` in config |
+| Type stubs missing | Install `types-*` packages before extraction |
+
+### JavaScript/TypeScript
+
+```bash
+codeql database create codeql.db --language=javascript --source-root=.
+```
+
+**Framework Support:**
+- React, Vue, Angular: Built-in models
+- Express, Koa, Fastify: HTTP source/sink models
+- Next.js, Nuxt: Partial SSR support
+
+**Common Issues:**
+| Issue | Fix |
+|-------|-----|
+| node_modules bloat | Already excluded by default |
+| TypeScript not parsed | Ensure `tsconfig.json` is valid |
+| Monorepo issues | Use `--source-root` for specific package |
+
+### Go
+
+```bash
+codeql database create codeql.db --language=go --source-root=.
+```
+
+**Framework Support:**
+- net/http, Gin, Echo, Chi: Built-in models
+- gRPC: Partial support
+- Custom routers: May need data extensions
+
+**Common Issues:**
+| Issue | Fix |
+|-------|-----|
+| Missing dependencies | Run `go mod download` first |
+| Vendor directory | CodeQL handles automatically |
+| CGO code | Requires `--command='go build'` with CGO enabled |
+
+### Ruby
+
+```bash
+codeql database create codeql.db --language=ruby --source-root=.
+```
+
+**Framework Support:**
+- Rails: Full support (controllers, models, views)
+- Sinatra: Built-in support
+- Hanami: Partial support
+
+**Common Issues:**
+| Issue | Fix |
+|-------|-----|
+| Bundler issues | Run `bundle install` first |
+| Rails engines | May need multiple database passes |
+
+## Build Required
+
+### C/C++
+
+```bash
+# Make
+codeql database create codeql.db --language=cpp --command='make -j8'
+
+# CMake
+codeql database create codeql.db --language=cpp \
+  --source-root=/path/to/src \
+  --command='cmake --build build'
+
+# Ninja
+codeql database create codeql.db --language=cpp \
+  --command='ninja -C build'
+```
+
+**Build System Tips:**
+| Build System | Command |
+|--------------|---------|
+| Make | `make clean && make -j$(nproc)` |
+| CMake | `cmake -B build && cmake --build build` |
+| Meson | `meson setup build && ninja -C build` |
+| Bazel | `bazel build //...` |
+
+**Common Issues:**
+| Issue | Fix |
+|-------|-----|
+| Partial extraction | Ensure `make clean` before CodeQL build |
+| Header-only libraries | Use `--extractor-option cpp_trap_headers=true` |
+| Cross-compilation | Set `CODEQL_EXTRACTOR_CPP_TARGET_ARCH` |
+
+### Java/Kotlin
+
+```bash
+# Gradle
+codeql database create codeql.db --language=java --command='./gradlew build -x test'
+
+# Maven
+codeql database create codeql.db --language=java --command='mvn compile -DskipTests'
+```
+
+**Framework Support:**
+- Spring Boot: Full support
+- Jakarta EE: Built-in models
+- Android: Requires Android SDK
+
+**Common Issues:**
+| Issue | Fix |
+|-------|-----|
+| Missing dependencies | Run `./gradlew dependencies` first |
+| Kotlin mixed projects | Use `--language=java` (covers both) |
+| Annotation processors | Ensure they run during CodeQL build |
+
+### Rust
+
+```bash
+codeql database create codeql.db --language=rust --command='cargo build'
+```
+
+**Common Issues:**
+| Issue | Fix |
+|-------|-----|
+| Proc macros | May require special handling |
+| Workspace projects | Use `--source-root` for specific crate |
+| Build script failures | Ensure native dependencies are available |
+
+### C#
+
+```bash
+# .NET Core
+codeql database create codeql.db --language=csharp --command='dotnet build'
+
+# MSBuild
+codeql database create codeql.db --language=csharp --command='msbuild /t:rebuild'
+```
+
+**Framework Support:**
+- ASP.NET Core: Full support
+- Entity Framework: Database query models
+- Blazor: Partial support
+
+**Common Issues:**
+| Issue | Fix |
+|-------|-----|
+| NuGet restore | Run `dotnet restore` first |
+| Multiple solutions | Specify solution file in command |
+
+### Swift
+
+```bash
+# Xcode project
+codeql database create codeql.db --language=swift \
+  --command='xcodebuild -project MyApp.xcodeproj -scheme MyApp build'
+
+# Swift Package Manager
+codeql database create codeql.db --language=swift --command='swift build'
+```
+
+**Requirements:**
+- macOS only
+- Xcode Command Line Tools
+
+**Common Issues:**
+| Issue | Fix |
+|-------|-----|
+| Code signing | Add `CODE_SIGN_IDENTITY=- CODE_SIGNING_REQUIRED=NO` |
+| Simulator target | Add `-sdk iphonesimulator` |
+
+## Extractor Options
+
+Set via environment variables: `CODEQL_EXTRACTOR_<LANG>_OPTION_<NAME>=<VALUE>`
+
+### C/C++ Options
+
+| Option | Description |
+|--------|-------------|
+| `trap_headers=true` | Include header file analysis |
+| `target_arch=x86_64` | Target architecture |
+
+### Java Options
+
+| Option | Description |
+|--------|-------------|
+| `jdk_version=17` | JDK version for analysis |
+
+### Python Options
+
+| Option | Description |
+|--------|-------------|
+| `python_executable=/path/to/python` | Specific Python interpreter |

package/skills/codeql/references/macos-arm64e-workaround.md

@@ -0,0 +1,179 @@
+# macOS arm64e Workaround
+
+Methods for building CodeQL databases on macOS Apple Silicon when the `arm64e`/`arm64` architecture mismatch causes SIGKILL (exit code 137) during build tracing.
+
+**Use when `IS_MACOS_ARM64E=true`** (detected in build-database workflow Step 2a). These replace Methods 1 and 2 on affected systems.
+
+The strategy is to use Homebrew-installed tools (plain `arm64`, not `arm64e`) so `libtrace.dylib` can be injected successfully. Try sub-methods in order:
+
+## Sub-method 2m-a: Homebrew clang/gcc with multi-step tracing
+
+Trace only the compiler invocations individually, avoiding system tools (`/usr/bin/ar`, `/bin/mkdir`) that would be killed. This requires a multi-step build: init → trace each compiler call → finalize.
+
+```bash
+log_step "METHOD 2m-a: macOS arm64 — Homebrew compiler with multi-step tracing"
+
+# 1. Find Homebrew C/C++ compiler (arm64, not arm64e)
+BREW_CC=""
+# Prefer Homebrew clang
+if [ -x "/opt/homebrew/opt/llvm/bin/clang" ]; then
+  BREW_CC="/opt/homebrew/opt/llvm/bin/clang"
+# Try Homebrew GCC (e.g. gcc-14, gcc-13)
+elif command -v gcc-14 >/dev/null 2>&1; then
+  BREW_CC="$(command -v gcc-14)"
+elif command -v gcc-13 >/dev/null 2>&1; then
+  BREW_CC="$(command -v gcc-13)"
+fi
+
+if [ -z "$BREW_CC" ]; then
+  log_result "No Homebrew C/C++ compiler found — skipping 2m-a"
+  # Fall through to 2m-b
+else
+  # Verify it's arm64 (not arm64e)
+  BREW_CC_ARCH=$(lipo -archs "$BREW_CC" 2>/dev/null)
+  if [[ "$BREW_CC_ARCH" == *"arm64e"* ]]; then
+    log_result "Homebrew compiler is arm64e — skipping 2m-a"
+  else
+    log_step "Using Homebrew compiler: $BREW_CC (arch: $BREW_CC_ARCH)"
+
+    # 2. Run the build normally (without tracing) to create build dirs and artifacts
+    #    Use Homebrew make (gmake) if available, otherwise system make outside tracer
+    if command -v gmake >/dev/null 2>&1; then
+      MAKE_CMD="gmake"
+    else
+      MAKE_CMD="make"
+    fi
+    $MAKE_CMD clean 2>/dev/null || true
+    $MAKE_CMD CC="$BREW_CC" 2>&1 | tee -a "$LOG_FILE"
+
+    # 3. Extract compiler commands from the Makefile / build system
+    #    Use make's dry-run mode to get the exact compiler invocations
+    $MAKE_CMD clean 2>/dev/null || true
+    COMPILE_CMDS=$($MAKE_CMD CC="$BREW_CC" --dry-run 2>/dev/null \
+      | grep -E "^\s*$BREW_CC\b.*\s-c\s" \
+      | sed 's/^[[:space:]]*//')
+
+    if [ -z "$COMPILE_CMDS" ]; then
+      log_result "Could not extract compile commands from dry-run — skipping 2m-a"
+    else
+      # 4. Init database
+      codeql database init $DB_NAME --language=cpp --source-root=. --overwrite 2>&1 \
+        | tee -a "$LOG_FILE"
+
+      # 5. Ensure build directories exist (outside tracer — avoids arm64e mkdir)
+      $MAKE_CMD clean 2>/dev/null || true
+      #    Parse -o flags to find output dirs, or just create common dirs
+      echo "$COMPILE_CMDS" | sed -n 's/.*-o[[:space:]]\{1,\}\([^[:space:]]\{1,\}\).*/\1/p' | xargs -I{} dirname {} \
+        | sort -u | xargs mkdir -p 2>/dev/null || true
+
+      # 6. Trace each compiler invocation individually
+      TRACE_OK=true
+      while IFS= read -r cmd; do
+        [ -z "$cmd" ] && continue
+        log_cmd "codeql database trace-command $DB_NAME -- $cmd"
+        if ! codeql database trace-command $DB_NAME -- $cmd 2>&1 | tee -a "$LOG_FILE"; then
+          log_result "FAILED on: $cmd"
+          TRACE_OK=false
+          break
+        fi
+      done <<< "$COMPILE_CMDS"
+
+      if $TRACE_OK; then
+        # 7. Finalize
+        codeql database finalize $DB_NAME 2>&1 | tee -a "$LOG_FILE"
+        if codeql resolve database -- "$DB_NAME" >/dev/null 2>&1; then
+          log_result "SUCCESS (macOS arm64 multi-step)"
+          # Done — skip to Step 4
+        else
+          log_result "FAILED (finalize failed)"
+        fi
+      fi
+    fi
+  fi
+fi
+```
+
+## Sub-method 2m-b: Rosetta x86_64 emulation
+
+Force the entire CodeQL pipeline to run under Rosetta, which uses the `x86_64` slice of both `libtrace.dylib` and system tools — no `arm64e` mismatch.
+
+```bash
+log_step "METHOD 2m-b: macOS arm64 — Rosetta x86_64 emulation"
+
+# Check if Rosetta is available
+if ! arch -x86_64 /usr/bin/true 2>/dev/null; then
+  log_result "Rosetta not available — skipping 2m-b"
+else
+  BUILD_CMD="<BUILD_CMD>"  # e.g. "make clean && make -j4"
+  CMD="arch -x86_64 codeql database create $DB_NAME --language=$CODEQL_LANG --source-root=. --command='$BUILD_CMD' --overwrite"
+  log_cmd "$CMD"
+
+  arch -x86_64 codeql database create $DB_NAME --language=$CODEQL_LANG --source-root=. \
+    --command="$BUILD_CMD" --overwrite 2>&1 | tee -a "$LOG_FILE"
+
+  if codeql resolve database -- "$DB_NAME" >/dev/null 2>&1; then
+    log_result "SUCCESS (Rosetta x86_64)"
+  else
+    log_result "FAILED (Rosetta)"
+  fi
+fi
+```
+
+## Sub-method 2m-c: System compiler (direct attempt)
+
+As a verification step, try the standard autobuild with the system compiler. This will likely fail with exit code 137 on affected systems, but confirms the arm64e issue is the cause.
+
+> **This sub-method is optional.** Skip it if arm64e incompatibility was already confirmed in Step 2a.
+
+```bash
+log_step "METHOD 2m-c: System compiler (expected to fail on arm64e)"
+CMD="codeql database create $DB_NAME --language=$CODEQL_LANG --source-root=. --overwrite"
+log_cmd "$CMD"
+
+$CMD 2>&1 | tee -a "$LOG_FILE"
+
+EXIT_CODE=$?
+if [ $EXIT_CODE -eq 137 ] || [ $EXIT_CODE -eq 134 ]; then
+  log_result "FAILED: exit code $EXIT_CODE confirms arm64e/libtrace incompatibility"
+elif codeql resolve database -- "$DB_NAME" >/dev/null 2>&1; then
+  log_result "SUCCESS (unexpected — system compiler worked)"
+else
+  log_result "FAILED (exit code: $EXIT_CODE)"
+fi
+```
+
+## Sub-method 2m-d: Ask user
+
+If all macOS workarounds fail, present options:
+
+```
+AskUserQuestion:
+  header: "macOS Build"
+  question: "Build tracing failed due to macOS arm64e incompatibility. How to proceed?"
+  multiSelect: false
+  options:
+    - label: "Use build-mode=none (Recommended)"
+      description: "Source-level analysis only. Misses some interprocedural data flow but catches most C/C++ vulnerabilities (format strings, buffer overflows, unsafe functions)."
+    - label: "Install arm64 tools and retry"
+      description: "Run: brew install llvm make — then retry with Homebrew toolchain"
+    - label: "Install Rosetta and retry"
+      description: "Run: softwareupdate --install-rosetta — then retry under x86_64 emulation"
+    - label: "Abort"
+      description: "Stop database creation"
+```
+
+**If "Use build-mode=none":** Proceed to Method 4.
+
+**If "Install arm64 tools and retry":**
+```bash
+log_step "Installing Homebrew arm64 toolchain"
+brew install llvm make 2>&1 | tee -a "$LOG_FILE"
+# Retry Sub-method 2m-a
+```
+
+**If "Install Rosetta and retry":**
+```bash
+log_step "Installing Rosetta"
+softwareupdate --install-rosetta --agree-to-license 2>&1 | tee -a "$LOG_FILE"
+# Retry Sub-method 2m-b
+```

package/skills/codeql/references/performance-tuning.md

@@ -0,0 +1,111 @@
+# Performance Tuning
+
+## Memory Configuration
+
+### CODEQL_RAM Environment Variable
+
+Control maximum heap memory (in MB):
+
+```bash
+# 48GB for large codebases
+CODEQL_RAM=48000 codeql database analyze codeql.db ...
+
+# 16GB for medium codebases
+CODEQL_RAM=16000 codeql database analyze codeql.db ...
+```
+
+**Guidelines:**
+| Codebase Size | Recommended RAM |
+|---------------|-----------------|
+| Small (<100K LOC) | 4-8 GB |
+| Medium (100K-1M LOC) | 8-16 GB |
+| Large (1M+ LOC) | 32-64 GB |
+
+## Thread Configuration
+
+### Analysis Threads
+
+```bash
+# Use all available cores
+codeql database analyze codeql.db --threads=0 ...
+
+# Use specific number
+codeql database analyze codeql.db --threads=8 ...
+```
+
+**Note:** `--threads=0` uses all available cores. For shared machines, use explicit count.
+
+## Query-Level Timeouts
+
+Prevent individual queries from running indefinitely:
+
+```bash
+# Set per-query timeout (in milliseconds)
+codeql database analyze codeql.db --timeout=600000 ...
+```
+
+A 10-minute timeout (`600000`) catches runaway queries without killing legitimate complex analysis. Taint-tracking queries on large codebases may need longer.
+
+## Evaluator Diagnostics
+
+When analysis is slow, use `--evaluator-log` to identify which queries consume the most time:
+
+```bash
+codeql database analyze codeql.db \
+  --evaluator-log=evaluator.log \
+  --format=sarif-latest \
+  --output=results.sarif \
+  -- codeql/python-queries:codeql-suites/python-security-extended.qls
+
+# Summarize the log
+codeql generate log-summary evaluator.log --format=text
+```
+
+The summary shows per-query timing and tuple counts. Queries producing millions of tuples are likely the bottleneck.
+
+## Disk Space
+
+| Phase | Typical Size | Notes |
+|-------|-------------|-------|
+| Database creation | 2-10x source size | Compiled languages are larger due to build tracing |
+| Analysis cache | 1-5 GB | Stored in database directory |
+| SARIF output | 1-50 MB | Depends on finding count |
+
+Check available space before starting:
+
+```bash
+df -h .
+du -sh codeql_*.db 2>/dev/null
+```
+
+## Caching Behavior
+
+CodeQL caches query evaluation results inside the database directory. Subsequent runs of the same queries skip re-evaluation.
+
+| Scenario | Cache Effect |
+|----------|-------------|
+| Re-run same packs | Fast — uses cached results |
+| Add new query pack | Only new queries evaluate |
+| `codeql database cleanup` | Clears cache — forces full re-evaluation |
+| `--rerun` flag | Ignores cache for this run |
+
+**When to clear cache:**
+- After deploying new data extensions (cache may hold stale results)
+- When investigating unexpected zero-finding results
+- Before benchmark comparisons (ensures consistent timing)
+
+```bash
+# Clear evaluation cache
+codeql database cleanup codeql_1.db
+```
+
+## Troubleshooting Performance
+
+| Symptom | Likely Cause | Solution |
+|---------|--------------|----------|
+| OOM during analysis | Not enough RAM | Increase `CODEQL_RAM` |
+| Slow database creation | Complex build | Use `--threads`, simplify build |
+| Slow query execution | Large codebase | Reduce query scope, add RAM |
+| Database too large | Too many files | Use exclusion config (`codeql-config.yml` with `paths-ignore`) |
+| Single query hangs | Runaway evaluation | Use `--timeout` and check `--evaluator-log` |
+| Repeated runs still slow | Cache not used | Check you're using same database path |

package/skills/codeql/references/quality-assessment.md

@@ -0,0 +1,172 @@
+# Quality Assessment
+
+How to assess and improve CodeQL database quality after a successful build.
+
+## Collect Metrics
+
+```bash
+log_step "Assessing database quality"
+
+# 1. Baseline lines of code and file list (most reliable metric)
+codeql database print-baseline -- "$DB_NAME"
+BASELINE_LOC=$(python3 -c "
+import json
+with open('$DB_NAME/baseline-info.json') as f:
+    d = json.load(f)
+for lang, info in d['languages'].items():
+    print(f'{lang}: {info[\"linesOfCode\"]} LoC, {len(info[\"files\"])} files')
+")
+echo "$BASELINE_LOC"
+log_result "Baseline: $BASELINE_LOC"
+
+# 2. Source archive file count
+SRC_FILE_COUNT=$(unzip -Z1 "$DB_NAME/src.zip" 2>/dev/null | wc -l)
+echo "Files in source archive: $SRC_FILE_COUNT"
+
+# 3. Extraction errors from extractor diagnostics
+EXTRACTOR_ERRORS=$(find "$DB_NAME/diagnostic/extractors" -name '*.jsonl' \
+  -exec cat {} + 2>/dev/null | grep -c '^{' 2>/dev/null || true)
+EXTRACTOR_ERRORS=${EXTRACTOR_ERRORS:-0}
+echo "Extractor errors: $EXTRACTOR_ERRORS"
+
+# 4. Export diagnostics summary (experimental but useful)
+DIAG_TEXT=$(codeql database export-diagnostics --format=text -- "$DB_NAME" 2>/dev/null || true)
+if [ -n "$DIAG_TEXT" ]; then
+  echo "Diagnostics: $DIAG_TEXT"
+fi
+
+# 5. Check database is finalized
+FINALIZED=$(grep '^finalised:' "$DB_NAME/codeql-database.yml" 2>/dev/null \
+  | awk '{print $2}')
+echo "Finalized: $FINALIZED"
+```
+
+## Compare Against Expected Source
+
+Estimate the expected source file count from the working directory and compare.
+
+> **Compiled languages (C/C++, Java, C#):** The source archive (`src.zip`) includes system headers and SDK files alongside project source files. For C/C++, this can inflate the archive count 10-20x (e.g., 111 archive files for 5 project source files). Compare against **project-relative files only** by filtering the archive listing.
+
+```bash
+# Count source files in the project (adjust extensions per language)
+EXPECTED=$(fd -t f -e c -e cpp -e h -e hpp -e java -e kt -e py -e js -e ts \
+  --exclude 'codeql_*.db' --exclude node_modules --exclude vendor --exclude .git . \
+  2>/dev/null | wc -l)
+echo "Expected source files: $EXPECTED"
+
+# Count PROJECT files in source archive (exclude system/SDK paths)
+PROJECT_SRC_COUNT=$(unzip -Z1 "$DB_NAME/src.zip" 2>/dev/null \
+  | grep -v -E '^(Library/|usr/|System/|opt/|Applications/)' | wc -l)
+echo "Project files in source archive: $PROJECT_SRC_COUNT"
+echo "Total files in source archive: $SRC_FILE_COUNT (includes system headers for compiled langs)"
+
+# Baseline LOC from database metadata (most reliable single metric)
+DB_LOC=$(grep '^baselineLinesOfCode:' "$DB_NAME/codeql-database.yml" \
+  | awk '{print $2}')
+echo "Baseline LoC: $DB_LOC"
+
+# Error ratio — use project file count for compiled langs, total for interpreted
+if [ "$PROJECT_SRC_COUNT" -gt 0 ]; then
+  ERROR_RATIO=$(python3 -c "print(f'{$EXTRACTOR_ERRORS/$PROJECT_SRC_COUNT*100:.1f}%')")
+else
+  ERROR_RATIO="N/A (no files)"
+fi
+echo "Error ratio: $ERROR_RATIO ($EXTRACTOR_ERRORS errors / $PROJECT_SRC_COUNT project files)"
+```
+
+## Log Assessment
+
+```bash
+log_step "Quality assessment results"
+log_result "Baseline LoC: $DB_LOC"
+log_result "Project source files: $PROJECT_SRC_COUNT (expected: ~$EXPECTED)"
+log_result "Total archive files: $SRC_FILE_COUNT (includes system headers for compiled langs)"
+log_result "Extractor errors: $EXTRACTOR_ERRORS (ratio: $ERROR_RATIO)"
+log_result "Finalized: $FINALIZED"
+
+# Sample extracted project files (exclude system paths)
+unzip -Z1 "$DB_NAME/src.zip" 2>/dev/null \
+  | grep -v -E '^(Library/|usr/|System/|opt/|Applications/)' \
+  | head -20 >> "$LOG_FILE"
+```
+
+## Quality Criteria
+
+| Metric | Source | Good | Poor |
+|--------|--------|------|------|
+| Baseline LoC | `print-baseline` / `baseline-info.json` | > 0, proportional to project size | 0 or far below expected |
+| Project source files | `src.zip` (filtered) | Close to expected source file count | 0 or < 50% of expected |
+| Extractor errors | `diagnostic/extractors/*.jsonl` | 0 or < 5% of project files | > 5% of project files |
+| Finalized | `codeql-database.yml` | `true` | `false` (incomplete build) |
+| Key directories | `src.zip` listing | Application code directories present | Missing `src/main`, `lib/`, `app/` etc. |
+| "No source code seen" | build log | Absent | Present (cached build — compiled languages) |
+
+**Interpreting archive file counts for compiled languages:** C/C++ databases include system headers (e.g., `<stdio.h>`, SDK headers) in `src.zip`. A project with 5 source files may have 100+ files in the archive. Always filter to project-relative paths when comparing against expected counts. Use `baselineLinesOfCode` as the primary quality indicator.
+
+**Interpreting baseline LoC:** A small number of extractor errors is normal and does not significantly impact analysis. However, if `baselineLinesOfCode` is 0 or the source archive contains no files, the database is empty — likely a cached build (compiled languages) or wrong `--source-root`.
+
+---
+
+## Improve Quality (if poor)
+
+Try these improvements, re-assess after each. **Log all improvements:**
+
+### 1. Adjust source root
+
+```bash
+log_step "Quality improvement: adjust source root"
+NEW_ROOT="./src"  # or detected subdirectory
+# For interpreted: add --codescanning-config=codeql-config.yml
+# For compiled: omit config flag
+log_cmd "codeql database create $DB_NAME --language=$CODEQL_LANG --source-root=$NEW_ROOT --overwrite"
+codeql database create $DB_NAME --language=$CODEQL_LANG --source-root=$NEW_ROOT --overwrite
+log_result "Changed source-root to: $NEW_ROOT"
+```
+
+### 2. Fix "no source code seen" (cached build - compiled languages only)
+
+```bash
+log_step "Quality improvement: force rebuild (cached build detected)"
+log_cmd "make clean && rebuild"
+make clean && codeql database create $DB_NAME --language=$CODEQL_LANG --overwrite
+log_result "Forced clean rebuild"
+```
+
+### 3. Install type stubs / dependencies
+
+> **Note:** These install into the *target project's* environment to improve CodeQL extraction quality.
+
+```bash
+log_step "Quality improvement: install type stubs/additional deps"
+
+# Python type stubs — install into target project's environment
+STUBS_INSTALLED=""
+for stub in types-requests types-PyYAML types-redis; do
+  if pip install "$stub" 2>/dev/null; then
+    STUBS_INSTALLED="$STUBS_INSTALLED $stub"
+  fi
+done
+log_result "Installed type stubs:$STUBS_INSTALLED"
+
+# Additional project dependencies
+log_cmd "pip install -e ."
+pip install -e . 2>&1 | tee -a "$LOG_FILE"
+```
+
+### 4. Adjust extractor options
+
+```bash
+log_step "Quality improvement: adjust extractor options"
+
+# C/C++: Include headers
+export CODEQL_EXTRACTOR_CPP_OPTION_TRAP_HEADERS=true
+log_result "Set CODEQL_EXTRACTOR_CPP_OPTION_TRAP_HEADERS=true"
+
+# Java: Specific JDK version
+export CODEQL_EXTRACTOR_JAVA_OPTION_JDK_VERSION=17
+log_result "Set CODEQL_EXTRACTOR_JAVA_OPTION_JDK_VERSION=17"
+
+# Then rebuild with current method
+```
+
+**After each improvement:** Re-assess quality. If no improvement possible, move to next build method.