diff --git a/.github/instructions/csharp.instructions.md b/.github/instructions/csharp.instructions.md new file mode 100644 index 0000000..e91e420 --- /dev/null +++ b/.github/instructions/csharp.instructions.md @@ -0,0 +1,45 @@ +--- +applyTo: "src/**/*.cs" +description: "C# coding patterns, architecture conventions, and project-specific guidance for CodeQL Development Toolkit" +--- +# C# Code Instructions for CodeQL Development Toolkit + +## Code Style and Conventions + +- Use nullable reference types consistently. Declare properties as nullable (`string?`) when they can be null, or ensure non-nullable properties are initialized. +- Follow existing namespace patterns: `CodeQLToolkit.Features.*`, `CodeQLToolkit.Shared.*`, `CodeQLToolkit.Core.*` +- Use the existing logging pattern: `Log.G().LogInformation()` for logging +- Prefer `Path.Combine()` for file path construction instead of string concatenation + +## Architecture Patterns + +- **Feature Pattern**: Features are organized under `CodeQLToolkit.Features` with main registration classes like `QueryFeatureMain`, `TestFeatureMain`, etc. +- **Command Pattern**: Use `System.CommandLine` for CLI command implementation with proper option handling +- **Template Pattern**: Lifecycle targets inherit from `BaseLifecycleTarget` and implement specific automation workflows +- **Dependency Injection**: Use constructor injection and register services appropriately + +## Key Classes and Patterns + +- `BaseLifecycleTarget`: Abstract base for lifecycle automation targets (Actions, Local, etc.) +- `ILifecycleTarget`: Interface for lifecycle operations with `Run()` method +- `TemplateUtil`: Use for rendering Liquid templates with `TemplateFromFile()` and `RawTemplateFromFile()` +- `QLTConfig`: Configuration management with JSON serialization using Newtonsoft.Json +- `Query`: Utility class for managing CodeQL query file paths and structure + +## File Organization + +- Keep automation-specific logic in separate targets under `Lifecycle/Targets/Actions/`, `Lifecycle/Targets/Local/` +- Templates should be organized by feature: `Templates/Query/`, `Templates/Test/`, `Templates/Bundle/` +- Shared utilities go in `CodeQLToolkit.Shared/Utils/` + +## Error Handling + +- Use proper exception handling and meaningful error messages +- Log important operations and errors using the established logging framework +- Validate file paths and directory existence before operations + +## Testing + +- Follow the existing test structure in `test/CodeQLToolkit.*.Tests/` +- Use NUnit testing framework consistently with the existing patterns +- Consider using constraint model: `Assert.That(actual, Is.EqualTo(expected))` instead of classic model \ No newline at end of file diff --git a/.github/instructions/liquid.instructions.md b/.github/instructions/liquid.instructions.md new file mode 100644 index 0000000..f1a02bb --- /dev/null +++ b/.github/instructions/liquid.instructions.md @@ -0,0 +1,66 @@ +--- +applyTo: "src/**/Templates/**/*.liquid" +description: "Liquid template structure and conventions for CodeQL file generation" +--- +# Liquid Template Instructions for CodeQL Development Toolkit + +## Template Purpose and Structure + +Liquid templates in this project generate CodeQL-related files, GitHub Actions workflows, and project configuration files. They are organized by feature area and automation type. + +## Template Organization + +- **Query Templates**: `Templates/Query/` - Generate CodeQL query files, qlpack.yml, test files +- **Test Templates**: `Templates/Test/Actions/` - Generate GitHub Actions for testing workflows +- **Bundle Templates**: `Templates/Bundle/Actions/` - Generate bundle integration test workflows +- **Validation Templates**: `Templates/Validation/Actions/` - Generate validation workflows + +## Variable Naming Conventions + +Use snake_case for template variables to match existing patterns: +- `query_name`, `query_pack_name`, `language`, `description` +- `num_threads`, `use_runner`, `dev_mode`, `branch` +- `codeql_args`, `extra_args`, `automation_type` + +## Common Template Patterns + +### CodeQL Query Headers +Always include proper metadata headers for CodeQL queries: +```liquid +/** + * @id {{language}}/{{query_pack_name}}/{{query_name}} + * @name {{query_name}} + * @description {{description}} + * @kind problem + * @precision medium + * @problem.severity error + * @tags {{query_pack_name}} + */ +``` + +### GitHub Actions Structure +For workflow templates: +- Use descriptive names and descriptions +- Include proper input/output definitions +- Use composite actions pattern with shell steps +- Include debug logging: `echo "::debug::message"` + +### File Path Construction +Use consistent path patterns: +- CodeQL queries: `{{language}}/{{query_pack_name}}/src/{{query_name}}/{{query_name}}.ql` +- Test files: `{{language}}/{{query_pack_name}}/test/{{query_name}}/{{query_name}}.{{language_extension}}` + +## Template Rendering Context + +Templates are rendered using Scriban engine with: +- `TemplateUtil.TemplateFromFile()` for parsing and rendering +- Variables passed as anonymous objects in C# code +- Access to language-specific helpers through utility classes + +## Best Practices + +- Keep templates focused on single responsibility +- Use meaningful variable names that reflect the generated content purpose +- Include appropriate comments in generated files +- Ensure generated files follow CodeQL and GitHub Actions best practices +- Use conditional logic sparingly - prefer multiple specialized templates \ No newline at end of file diff --git a/.github/instructions/repository.instructions.md b/.github/instructions/repository.instructions.md new file mode 100644 index 0000000..b350ab5 --- /dev/null +++ b/.github/instructions/repository.instructions.md @@ -0,0 +1,69 @@ +--- +applyTo: "**/*" +description: "High-level project context, repository structure, and development workflow guidance" +--- +# CodeQL Development Toolkit Repository Instructions + +## Project Overview + +The CodeQL Development Toolkit (QLT) is a command-line tool for CodeQL query development, testing, and automation. It provides scaffolding, lifecycle management, and CI/CD integration for CodeQL projects. + +## Repository Structure + +- `src/CodeQLToolkit.Core/` - Main CLI application entry point +- `src/CodeQLToolkit.Features/` - Feature implementations (Query, Test, Bundle, Validation) +- `src/CodeQLToolkit.Shared/` - Shared utilities, configuration, and base classes +- `test/` - Unit tests for each component +- `.github/workflows/` - CI/CD workflows for building and testing +- `.github/actions/` - Reusable actions for CodeQL and QLT installation + +## Key Dependencies + +- **.NET 6.0+**: Primary development framework +- **System.CommandLine**: CLI framework for command parsing +- **Scriban**: Liquid template engine for code generation +- **Newtonsoft.Json**: JSON serialization for configuration +- **NUnit**: Testing framework + +## Development Workflow + +1. **Building**: Use `dotnet build` and `dotnet restore` +2. **Testing**: Use `dotnet test` for unit tests +3. **CLI Usage**: The main executable is `qlt` with features: query, test, bundle, validation, pack, codeql + +## Feature Architecture + +Each feature follows a consistent pattern: +- `*FeatureMain.cs` - Feature registration and command setup +- `Commands/` - Command implementations +- `Lifecycle/` - Automation lifecycle targets +- `Templates/` - Liquid templates for file generation + +## Automation Types + +The toolkit supports multiple automation platforms: +- **Actions**: GitHub Actions integration +- **Local**: Local development workflows + +## Configuration + +- `qlt.conf.json` - Project configuration file +- Environment variables and CLI options for runtime configuration +- Template-based configuration file generation + +## Contributing Guidelines + +- Follow existing code patterns and conventions +- Add unit tests for new functionality +- Update documentation for user-facing changes +- Ensure compatibility with existing workflows +- Test changes against sample CodeQL projects + +## CLI Command Structure + +``` +qlt [options] +``` + +Features: query, test, bundle, validation, pack, codeql +Common actions: init, create, validate, run \ No newline at end of file diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml new file mode 100644 index 0000000..e607f39 --- /dev/null +++ b/.github/workflows/copilot-setup-steps.yml @@ -0,0 +1,64 @@ +name: Copilot Setup Steps + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + workflow_dispatch: + +jobs: + copilot-setup-steps: + name: Pre-install Dependencies for Copilot Environment + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup .NET 6.0.x + uses: actions/setup-dotnet@v4 + with: + dotnet-version: 6.0.x + + - name: Verify .NET installation + run: | + dotnet --version + echo "✅ .NET 6.0.x installed successfully" + + - name: Setup GitHub CLI (for QLT installation) + run: | + # GitHub CLI is typically pre-installed on GitHub runners + gh --version + echo "✅ GitHub CLI available" + + - name: Install QLT CLI dependencies + run: | + # Install dependencies required for QLT to run + sudo apt-get update + sudo apt-get install -y unzip curl + echo "✅ Required system dependencies installed" + + - name: Restore .NET dependencies + run: | + dotnet restore + echo "✅ .NET dependencies restored" + + - name: Build project to verify setup + run: | + dotnet build -c Release --no-restore + echo "✅ Project builds successfully" + + - name: Test QLT CLI availability + run: | + # Build and test that the qlt CLI can be executed + dotnet run --project src/CodeQLToolkit.Core -- version + echo "✅ QLT CLI is functional" + + - name: Verify Copilot environment readiness + run: | + echo "🤖 Copilot environment setup complete!" + echo "✅ .NET 6.0.x: $(dotnet --version)" + echo "✅ GitHub CLI: $(gh --version | head -n1)" + echo "✅ System tools: unzip, curl available" + echo "✅ QLT CLI: Ready for CodeQL development tasks"