devskill 2.0.6 → 2.0.8

package/skills/codeql/references/troubleshooting.md

@@ -0,0 +1,259 @@
+# CodeQL Troubleshooting Reference
+
+Comprehensive guide for diagnosing and resolving CodeQL analysis errors, SARIF upload issues, and common configuration problems.
+
+## Build and Analysis Errors
+
+### "No source code was seen during the build"
+
+**Cause:** CodeQL extractor did not find any source files during database creation.
+
+**Solutions:**
+- Verify the `--source-root` points to the correct directory
+- For compiled languages, ensure the build command actually compiles source files
+- Check that `autobuild` is detecting the correct build system
+- Switch from `autobuild` to `manual` build mode with explicit build commands
+- Verify the language specified matches the actual source code language
+
+### Automatic Build Failed
+
+**Cause:** `autobuild` could not detect or run the project's build system.
+
+**Solutions:**
+- Switch to `build-mode: manual` and provide explicit build commands
+- Ensure all build dependencies are installed on the runner
+- For C/C++: verify `gcc`, `make`, `cmake`, or `msbuild` are available
+- For C#: verify `.NET SDK` or `MSBuild` is installed
+- For Java: verify `gradle` or `maven` is installed
+- Check the autobuild logs for the specific detection step that failed
+
+### C# Compiler Unexpectedly Failing
+
+**Cause:** The CodeQL tracer injects compiler flags that may conflict with project configuration.
+
+**Details:** CodeQL injects `/p:EmitCompilerGeneratedFiles=true` which can cause issues with:
+- Legacy .NET Framework projects
+- Projects using `.sqlproj` files
+
+**Solutions:**
+- Add `<EmitCompilerGeneratedFiles>false</EmitCompilerGeneratedFiles>` to problematic project files
+- Use `build-mode: none` for C# if build accuracy is acceptable
+- Exclude problematic projects from the CodeQL analysis
+
+### Analysis Takes Too Long
+
+**Cause:** Large codebase, complex queries, or insufficient resources.
+
+**Solutions:**
+- Use `build-mode: none` where accuracy is acceptable (significantly faster)
+- Enable dependency caching: `dependency-caching: true`
+- Set `timeout-minutes` on the job to prevent hung workflows
+- Use `--threads=0` (CLI) to use all available CPU cores
+- Reduce query scope: use `default` suite instead of `security-and-quality`
+- For self-hosted runners, ensure hardware meets recommendations:
+  - Small (<100K LOC): 8 GB RAM, 2 cores
+  - Medium (100K–1M LOC): 16 GB RAM, 4–8 cores
+  - Large (>1M LOC): 64 GB RAM, 8 cores
+- Configure larger GitHub-hosted runners if available
+- Use `paths` in config file to limit analyzed directories
+
+### CodeQL Scanned Fewer Lines Than Expected
+
+**Cause:** Build command didn't compile all source files, or `build-mode: none` missed generated code.
+
+**Solutions:**
+- Switch from `none` to `autobuild` or `manual` build mode
+- Ensure the build command compiles the full codebase (not just a subset)
+- Check the code scanning logs for extraction metrics:
+  - Lines of code in codebase (baseline)
+  - Lines of code extracted
+  - Lines excluding auto-generated files
+- Verify language detection includes all expected languages
+
+### Kotlin Detected in No-Build Mode
+
+**Cause:** Repository uses `build-mode: none` (Java only) but also contains Kotlin code.
+
+**Solutions:**
+- Disable default setup and re-enable it (switches to `autobuild`)
+- Or switch to advanced setup with `build-mode: autobuild` for `java-kotlin`
+- Kotlin requires a build to be analyzed; `none` mode only works for Java
+
+## Permission and Access Errors
+
+### Error: 403 "Resource not accessible by integration"
+
+**Cause:** `GITHUB_TOKEN` lacks required permissions.
+
+**Solutions:**
+- Add explicit permissions to the workflow:
+  ```yaml
+  permissions:
+    security-events: write
+    contents: read
+    actions: read
+  ```
+- For Dependabot PRs, use `pull_request_target` instead of `pull_request`
+- Verify the repository has GitHub Code Security enabled (for private repos)
+
+### Cannot Enable CodeQL in a Private Repository
+
+**Cause:** GitHub Code Security is not enabled.
+
+**Solution:** Enable GitHub Code Security in repository Settings → Advanced Security.
+
+### Error: "GitHub Code Security or Advanced Security must be enabled"
+
+**Cause:** Attempting to use code scanning on a private repo without the required license.
+
+**Solutions:**
+- Enable GitHub Code Security for the repository
+- Contact organization admin to enable Advanced Security
+
+## Configuration Errors
+
+### Two CodeQL Workflows Running
+
+**Cause:** Both default setup and a pre-existing `codeql.yml` workflow are active.
+
+**Solutions:**
+- Disable default setup if using advanced setup, or
+- Delete the old workflow file if using default setup
+- Check repository Settings → Advanced Security for active configurations
+
+### Some Languages Not Analyzed
+
+**Cause:** Matrix configuration doesn't include all languages.
+
+**Solutions:**
+- Add missing languages to the `matrix.include` array
+- Verify language identifiers are correct (e.g., `javascript-typescript` not just `javascript`)
+- Check that each language has an appropriate `build-mode`
+
+### Unclear What Triggered a Workflow Run
+
+**Solutions:**
+- Check the tool status page in repository Settings → Advanced Security
+- Review workflow run logs for trigger event details
+- Look at the `on:` triggers in the workflow file
+
+### Error: "is not a .ql file, .qls file, a directory, or a query pack specification"
+
+**Cause:** Invalid query or pack reference in the workflow.
+
+**Solutions:**
+- Verify query pack names and versions exist
+- Use correct format: `owner/pack-name@version` or `owner/pack-name:path/to/query.ql`
+- Run `codeql resolve packs` to verify available packs
+
+## Resource Errors
+
+### "Out of disk" or "Out of memory"
+
+**Cause:** Runner lacks sufficient resources for the analysis.
+
+**Solutions:**
+- Use larger GitHub-hosted runners (if available)
+- For self-hosted runners, increase RAM and disk (SSD with ≥14 GB)
+- Reduce analysis scope with `paths` configuration
+- Analyze fewer languages per job
+- Use `build-mode: none` to reduce resource usage
+
+### Extraction Errors in Database
+
+**Cause:** Some source files couldn't be processed by the CodeQL extractor.
+
+**Solutions:**
+- Check extraction metrics in workflow logs for error counts
+- Enable debug logging for detailed extraction diagnostics
+- Verify source files are syntactically valid
+- Ensure all build dependencies are available
+
+## Logging and Debugging
+
+### Enable Debug Logging
+
+To get more detailed diagnostic information:
+
+**GitHub Actions:**
+1. Re-run the workflow with debug logging enabled
+2. In the workflow run, click "Re-run jobs" → "Enable debug logging"
+
+**CodeQL CLI:**
+```bash
+codeql database create my-db \
+  --language=javascript-typescript \
+  --verbosity=progress++ \
+  --logdir=codeql-logs
+```
+
+**Verbosity levels:** `errors`, `warnings`, `progress`, `progress+`, `progress++`, `progress+++`
+
+### Code Scanning Log Metrics
+
+Workflow logs include summary metrics:
+- **Lines of code in codebase** — baseline before extraction
+- **Lines of code in CodeQL database** — extracted including external libraries
+- **Lines excluding auto-generated files** — net analyzed code
+- **Extraction success/error/warning counts** — per-file extraction results
+
+### Private Registry Diagnostics
+
+For `build-mode: none` with private package registries:
+- Check the "Setup proxy for registries" step in workflow logs
+- Look for `Credentials loaded for the following registries:` message
+- Verify organization-level private registry configuration
+- Ensure internet access is available for dependency resolution
+
+## SARIF Upload Errors
+
+### SARIF File Too Large
+
+**Limit:** 10 MB maximum (gzip-compressed).
+
+**Solutions:**
+- Focus on the most important query suites (use `default` instead of `security-and-quality`)
+- Reduce the number of queries via configuration
+- Split analysis into multiple jobs with separate SARIF uploads
+- Remove `--sarif-add-file-contents` flag
+
+### SARIF Results Exceed Limits
+
+GitHub enforces limits on SARIF data objects:
+
+| Object | Maximum |
+|---|---|
+| Runs per file | 20 |
+| Results per run | 25,000 |
+| Rules per run | 25,000 |
+| Tool extensions per run | 100 |
+| Thread flow locations per result | 10,000 |
+| Location per result | 1,000 |
+| Tags per rule | 20 |
+
+**Solutions:**
+- Reduce query scope to focus on high-impact rules
+- Split analysis across multiple SARIF uploads with different `--sarif-category`
+- Disable noisy queries that produce many results
+
+### SARIF File Invalid
+
+**Solutions:**
+- Validate against the [Microsoft SARIF validator](https://sarifweb.azurewebsites.net/)
+- Ensure `version` is `"2.1.0"` and `$schema` points to the correct schema
+- Verify required properties (`runs`, `tool.driver`, `results`) are present
+
+### Upload Rejected: Default Setup Enabled
+
+**Cause:** Cannot upload CodeQL-generated SARIF when default setup is active.
+
+**Solutions:**
+- Disable default setup before uploading via CLI/API
+- Or switch to using default setup exclusively (no manual uploads)
+
+### Missing Authentication Token
+
+**Solutions:**
+- Set `GITHUB_TOKEN` environment variable with `security-events: write` scope
+- Or use `--github-auth-stdin` to pipe the token
+- For GitHub Actions: the token is automatically available via `${{ secrets.GITHUB_TOKEN }}`

package/skills/codeql/references/workflow-configuration.md

@@ -0,0 +1,398 @@
+# CodeQL Workflow Configuration Reference
+
+Detailed reference for configuring CodeQL analysis via GitHub Actions workflows. This supplements the procedural guidance in SKILL.md.
+
+## Trigger Configuration
+
+### Push Trigger
+
+Scan on every push to specified branches:
+
+```yaml
+on:
+  push:
+    branches: [main, protected]
+```
+
+- Code scanning is triggered on every push to the listed branches
+- The workflow must exist on the target branch for scanning to activate
+- Results appear in the repository Security tab
+- When push results map to an open PR, alerts also appear as PR annotations
+
+### Pull Request Trigger
+
+Scan merge commits of pull requests:
+
+```yaml
+on:
+  pull_request:
+    branches: [main]
+```
+
+- Scans the PR's merge commit (not the head commit) for more accurate results
+- For private fork PRs, enable "Run workflows from fork pull requests" in repository settings
+- Results appear as PR check annotations
+
+### Schedule Trigger
+
+Periodic scans on the default branch:
+
+```yaml
+on:
+  schedule:
+    - cron: '20 14 * * 1'  # Monday 14:20 UTC
+```
+
+- Only triggers if the workflow file exists on the default branch
+- Catches newly discovered vulnerabilities even without active development
+
+### Merge Group Trigger
+
+Required when using merge queues:
+
+```yaml
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  merge_group:
+```
+
+### Path Filtering
+
+Control when the workflow runs based on changed files:
+
+```yaml
+on:
+  pull_request:
+    paths-ignore:
+      - '**/*.md'
+      - '**/*.txt'
+      - 'docs/**'
+```
+
+Or use `paths` to only trigger on specific directories:
+
+```yaml
+on:
+  pull_request:
+    paths:
+      - 'src/**'
+      - 'apps/**'
+```
+
+> **Important:** `paths-ignore` and `paths` control whether the workflow runs. When the workflow does run, it analyzes ALL changed files in the PR (including those matched by `paths-ignore`), unless files are excluded via the CodeQL configuration file's `paths-ignore`.
+
+### Workflow Dispatch (Manual Trigger)
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      language:
+        description: 'Language to analyze'
+        required: true
+        default: 'javascript-typescript'
+```
+
+## Runner and OS Configuration
+
+### GitHub-Hosted Runners
+
+```yaml
+jobs:
+  analyze:
+    runs-on: ubuntu-latest    # Also: windows-latest, macos-latest
+```
+
+- `ubuntu-latest` — most common, recommended for most languages
+- `macos-latest` — required for Swift analysis
+- `windows-latest` — required for some C/C++ and C# projects using MSBuild
+
+### Self-Hosted Runners
+
+```yaml
+jobs:
+  analyze:
+    runs-on: [self-hosted, ubuntu-latest]
+```
+
+Requirements for self-hosted runners:
+- Git must be in the PATH
+- SSD with ≥14 GB disk space recommended
+- See hardware requirements table in SKILL.md
+
+### Timeout Configuration
+
+Prevent hung workflows:
+
+```yaml
+jobs:
+  analyze:
+    timeout-minutes: 120
+```
+
+## Language and Build Mode Matrix
+
+### Standard Matrix Pattern
+
+```yaml
+strategy:
+  fail-fast: false
+  matrix:
+    include:
+      - language: javascript-typescript
+        build-mode: none
+      - language: python
+        build-mode: none
+      - language: java-kotlin
+        build-mode: none
+      - language: c-cpp
+        build-mode: autobuild
+```
+
+### Multi-Language Repository with Mixed Build Modes
+
+```yaml
+strategy:
+  fail-fast: false
+  matrix:
+    include:
+      - language: c-cpp
+        build-mode: manual
+      - language: csharp
+        build-mode: autobuild
+      - language: java-kotlin
+        build-mode: none
+```
+
+### Build Mode Summary
+
+| Language | `none` | `autobuild` | `manual` | Default Setup Mode |
+|---|:---:|:---:|:---:|---|
+| C/C++ | ✅ | ✅ | ✅ | `none` |
+| C# | ✅ | ✅ | ✅ | `none` |
+| Go | ❌ | ✅ | ✅ | `autobuild` |
+| Java | ✅ | ✅ | ✅ | `none` |
+| Kotlin | ❌ | ✅ | ✅ | `autobuild` |
+| Python | ✅ | ❌ | ❌ | `none` |
+| Ruby | ✅ | ❌ | ❌ | `none` |
+| Rust | ✅ | ✅ | ✅ | `none` |
+| Swift | ❌ | ✅ | ✅ | `autobuild` |
+| JavaScript/TypeScript | ✅ | ❌ | ❌ | `none` |
+| GitHub Actions | ✅ | ❌ | ❌ | `none` |
+
+## CodeQL Database Location
+
+Override the default database location:
+
+```yaml
+- uses: github/codeql-action/init@v4
+  with:
+    db-location: '${{ github.runner_temp }}/my_location'
+```
+
+- Default: `${{ github.runner_temp }}/codeql_databases`
+- Path must be writable and either not exist or be an empty directory
+- On self-hosted runners, ensure cleanup between runs
+
+## Query Suites and Packs
+
+### Built-In Query Suites
+
+```yaml
+- uses: github/codeql-action/init@v4
+  with:
+    queries: security-extended
+```
+
+Options:
+- (default) — standard security queries
+- `security-extended` — additional security queries with slightly higher false-positive rate
+- `security-and-quality` — security plus code quality queries
+
+### Custom Query Packs
+
+```yaml
+- uses: github/codeql-action/init@v4
+  with:
+    packs: |
+      codeql/javascript-queries:AlertSuppression.ql
+      codeql/javascript-queries:~1.0.0
+      my-org/my-custom-pack@1.2.3
+```
+
+### Model Packs
+
+Extend CodeQL coverage for custom libraries/frameworks:
+
+```yaml
+- uses: github/codeql-action/init@v4
+  with:
+    packs: my-org/my-model-pack
+```
+
+## Analysis Category
+
+Distinguish between multiple analyses for the same commit:
+
+```yaml
+- uses: github/codeql-action/analyze@v4
+  with:
+    category: "/language:${{ matrix.language }}"
+```
+
+### Monorepo Category Patterns
+
+```yaml
+# Per language (default auto-generated pattern)
+category: "/language:${{ matrix.language }}"
+
+# Per component
+category: "/language:${{ matrix.language }}/component:frontend"
+
+# Per app in monorepo
+category: "/language:javascript-typescript/app:blog"
+```
+
+The `category` value appears as `<run>.automationDetails.id` in the SARIF output.
+
+## CodeQL Configuration File
+
+Create `.github/codeql/codeql-config.yml` for advanced path and query configuration:
+
+```yaml
+name: "CodeQL Configuration"
+
+# Directories to scan
+paths:
+  - apps/
+  - services/
+  - packages/
+
+# Directories to exclude
+paths-ignore:
+  - node_modules/
+  - '**/test/**'
+  - '**/fixtures/**'
+  - '**/*.test.ts'
+
+# Additional queries
+queries:
+  - uses: security-extended
+  - uses: security-and-quality
+
+# Custom query packs
+packs:
+  javascript-typescript:
+    - codeql/javascript-queries
+  python:
+    - codeql/python-queries
+```
+
+Reference in the workflow:
+
+```yaml
+- uses: github/codeql-action/init@v4
+  with:
+    config-file: .github/codeql/codeql-config.yml
+```
+
+## Dependency Caching
+
+Enable caching to speed up dependency resolution:
+
+```yaml
+- uses: github/codeql-action/init@v4
+  with:
+    dependency-caching: true
+```
+
+Values:
+- `false` / `none` / `off` — disabled (default for advanced setup)
+- `restore` — only restore existing caches
+- `store` — only store new caches
+- `true` / `full` / `on` — restore and store caches
+
+> Default setup on GitHub-hosted runners has caching enabled automatically.
+
+## Alert Severity and Merge Protection
+
+Use repository rulesets to block PRs based on code scanning alerts:
+
+- A required tool finds an alert matching the defined severity threshold
+- A required tool's analysis is still in progress
+- A required tool is not configured for the repository
+
+Configure via repository Settings → Rules → Rulesets → Code scanning.
+
+## Concurrency Control
+
+Prevent duplicate workflow runs:
+
+```yaml
+concurrency:
+  group: codeql-${{ github.ref }}
+  cancel-in-progress: true
+```
+
+## Complete Workflow Example
+
+```yaml
+name: "CodeQL Analysis"
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '30 6 * * 1'
+
+permissions:
+  security-events: write
+  contents: read
+  actions: read
+
+concurrency:
+  group: codeql-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ${{ matrix.language == 'swift' && 'macos-latest' || 'ubuntu-latest' }}
+    timeout-minutes: 120
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: javascript-typescript
+            build-mode: none
+          - language: python
+            build-mode: none
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          queries: security-extended
+          dependency-caching: true
+
+      - if: matrix.build-mode == 'manual'
+        name: Manual Build
+        run: |
+          echo 'Replace with actual build commands'
+          exit 1
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"
+```

package/skills/comment-code-generate-a-tutorial/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright GitHub, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/comment-code-generate-a-tutorial/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: comment-code-generate-a-tutorial
+description: 'Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial.'
+---
+
+Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial.
+
+1. **Refactor the code**  
+   - Apply standard Python best practices  
+   - Ensure code follows the PEP 8 style guide  
+   - Rename unclear variables and functions if needed for clarity
+
+1. **Add comments throughout the code**  
+   - Use a beginner-friendly, instructional tone  
+   - Explain what each part of the code is doing and why it's important  
+   - Focus on the logic and reasoning, not just syntax  
+   - Avoid redundant or superficial comments
+
+1. **Generate a tutorial as a `README.md` file**  
+   Include the following sections:
+   - **Project Overview:** What the script does and why it's useful  
+   - **Setup Instructions:** Prerequisites, dependencies, and how to run the script  
+   - **How It Works:** A breakdown of the code logic based on the comments  
+   - **Example Usage:** A code snippet showing how to use it  
+   - **Sample Output:** (Optional) Include if the script returns visible results  
+   - Use clear, readable Markdown formatting

package/skills/comment-code-generate-a-tutorial/SYNC.md

@@ -0,0 +1,5 @@
+# Sync Info
+
+- **Source:** `vendor/awesome-copilot/skills/comment-code-generate-a-tutorial`
+- **Git SHA:** `23fb7006c132a0bba75b0e5af7a35cab11272812`
+- **Synced:** 2026-03-24