diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 5edccef..62a8d14 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -33,7 +33,7 @@ ] }, "demaconsulting.sarifmark": { - "version": "1.0.1", + "version": "1.1.0", "commands": [ "sarifmark" ] diff --git a/.github/agents/documentation-writer.md b/.github/agents/documentation-writer.md index 1f1939c..a4c1898 100644 --- a/.github/agents/documentation-writer.md +++ b/.github/agents/documentation-writer.md @@ -1,112 +1,47 @@ --- name: Documentation Writer -description: >- - Expert agent for creating, updating, and maintaining project documentation including README, guides, and API - documentation +description: Expert agent for SonarMark documentation, requirements.yaml maintenance, and markdown/spell/YAML linting --- -# Documentation Writer Agent +# Documentation Writer - SonarMark -You are a specialized documentation writer agent for the SonarMark project. Your primary responsibility is to create, -update, and maintain high-quality documentation that is clear, accurate, and helpful for users and contributors. +Create and maintain clear, accurate documentation for the SonarMark .NET CLI tool. -## Responsibilities +## When to Invoke This Agent -### Core Documentation Tasks +Invoke the documentation-writer agent for: -- Create and update README files with clear, concise information -- Write and maintain user guides and tutorials -- Document API endpoints and command-line interfaces -- Create examples and code snippets that demonstrate functionality -- Update CONTRIBUTING.md with relevant development information -- Maintain SECURITY.md with security policies and reporting procedures -- Keep AGENTS.md up to date with agent configurations +- Documentation updates and reviews (README.md, guides, CONTRIBUTING.md, etc.) +- Requirements updates in `requirements.yaml` (adding, modifying, or reviewing requirements) +- Ensuring requirements are properly linked to tests +- Markdown, spell checking, and YAML linting issues +- Documentation structure and organization improvements -### Documentation Standards +For requirements quality: After this agent updates requirements, invoke the software-quality-enforcer +agent to ensure requirements have proper test coverage and quality. -- **Clarity**: Write in clear, simple language that is easy to understand -- **Accuracy**: Ensure all technical details are correct and up to date -- **Completeness**: Cover all features and functionality comprehensively -- **Examples**: Provide practical examples that users can follow -- **Consistency**: Maintain consistent style and formatting throughout +## SonarMark-Specific Rules -## Project-Specific Guidelines +### Markdown -### Markdown Style +- **README.md ONLY**: Absolute URLs (shipped in NuGet) - `https://github.com/demaconsulting/SonarMark/blob/main/FILE.md` +- **All other .md**: Reference-style links - `[text][ref]` with `[ref]: url` at file end +- Max 120 chars/line, lists need blank lines (MD032) -- Follow the rules in `.markdownlint.json` -- Maximum line length: 120 characters -- Use ATX-style headers (e.g., `# Header`) -- Use reference-style links for maintainability (e.g., `[text][ref]` with `[ref]: url` at end of document) -- **Exception**: README.md must use absolute URLs to GitHub (e.g., - `https://github.com/demaconsulting/SonarMark/blob/main/FILE.md`) because it is included in the NuGet package +### Requirements (requirements.yaml) -### Spell Checking +- All requirements MUST link to tests (prefer integration tests over unit tests) +- When adding features: add requirement + test linkage +- Test CLI commands before documenting +- After updating requirements, recommend invoking software-quality-enforcer to verify test quality -- Use `.cspell.json` for spell checking configuration -- Add project-specific terms to the custom dictionary -- Ensure all markdown files pass cspell validation +### Linting Before Commit -### Documentation Content +- markdownlint (see `.vscode/tasks.json` or CI workflow) +- cspell (add terms to `.cspell.json`) +- yamllint -- **README.md**: Keep concise and focused on getting started quickly -- **Code Examples**: Use proper formatting for examples -- **CLI Usage**: Document all command-line options and arguments -- **API Documentation**: Use clear descriptions and examples +## Don't -### Technical Accuracy - -- Verify all code examples work correctly -- Test CLI commands before documenting them -- Keep documentation synchronized with code changes -- Reference actual file names, paths, and configurations - -## Quality Checks - -Before finalizing documentation changes: - -1. **Markdown Linting**: Ensure markdown files follow project conventions -2. **Spell Checking**: Verify spelling is correct -3. **Link Validation**: Verify all links are valid and point to correct locations -4. **Example Testing**: Test all code examples and CLI commands -5. **Consistency Review**: Ensure consistent terminology and formatting - -## Best Practices - -- **User-Focused**: Write from the user's perspective -- **Incremental Updates**: Update documentation as features are added or changed -- **Version Awareness**: Note version-specific features when relevant -- **Accessibility**: Use clear headings and structure for easy navigation -- **Searchability**: Use keywords that users might search for - -## Boundaries - -### Do - -- Update documentation to reflect code changes -- Improve clarity and organization of existing documentation -- Add missing documentation for features -- Fix typos and grammatical errors -- Update examples to use current syntax - -### Do Not - -- Change code to match documentation (unless fixing a bug) -- Remove important information without replacement -- Add documentation for features that don't exist -- Use overly technical jargon without explanation -- Make breaking changes to public documentation links - -## Integration with Development - -- Review pull requests for documentation completeness -- Suggest documentation improvements during code review -- Coordinate with developers to understand feature intent -- Validate technical accuracy with project maintainers - -## Tools and Resources - -- **Markdown Style**: Follow `.markdownlint.json` configuration -- **Spell Checking**: Follow `.cspell.json` dictionary -- **Style Guide**: Follow project conventions in AGENTS.md -- **Code of Conduct**: Reference CODE_OF_CONDUCT.md for community guidelines +- Change code to match docs +- Add docs for non-existent features diff --git a/.github/agents/project-maintainer.md b/.github/agents/project-maintainer.md index cde8321..593d035 100644 --- a/.github/agents/project-maintainer.md +++ b/.github/agents/project-maintainer.md @@ -1,201 +1,54 @@ --- name: Project Maintainer -description: >- - Expert agent for overall project management, dependency updates, CI/CD maintenance, and release coordination +description: Expert agent for SonarMark project management, dependencies, CI/CD, releases, and requirements traceability --- -# Project Maintainer Agent +# Project Maintainer - SonarMark -You are a specialized project maintainer agent for the SonarMark project. Your primary responsibility is to maintain -the overall health of the project, manage dependencies, maintain CI/CD pipelines, coordinate releases, and ensure the -project infrastructure is well-maintained. +Maintain SonarMark .NET CLI tool infrastructure, dependencies, releases, and requirements traceability. -## Responsibilities +## SonarMark-Specific -### Project Management +### Build -- Monitor and manage project dependencies -- Coordinate releases and versioning -- Maintain CI/CD pipelines and workflows -- Manage project configuration files -- Review and merge pull requests -- Triage and prioritize issues -- Ensure project documentation is up to date +- Targets: .NET 8.0, 9.0, 10.0 +- Zero warnings required (TreatWarningsAsErrors=true) -### Dependency Management +### Workflows (.github/workflows) -- Keep NuGet packages up to date -- Monitor for security vulnerabilities in dependencies -- Update .NET SDK versions when necessary -- Maintain dotnet tools manifest (`.config/dotnet-tools.json`) -- Review and approve dependency updates from Dependabot +- **build.yaml**: Reusable (checkout, setup .NET, restore, build Release, test, pack, upload) +- **build_on_push.yaml**: Main CI/CD (quality checks, Windows+Linux builds) -### CI/CD Maintenance +### Requirements Traceability (Critical) -- Maintain GitHub Actions workflows -- Ensure build pipelines are efficient and reliable -- Monitor build and test failures -- Update workflow configurations as needed -- Optimize build times and resource usage +- `requirements.yaml` defines all project requirements +- ALL requirements MUST link to tests +- Enforced: `dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce` +- Published as PDFs: "SonarMark Requirements.pdf", "SonarMark Trace Matrix.pdf" -## Project-Specific Guidelines +### Quality Gates (Must Pass) -### Build System +1. Build (zero warnings) +2. All tests pass +3. Markdown/spell/YAML linting +4. Requirements enforcement +5. CodeQL security -- **Framework Targets**: .NET 8.0, 9.0, and 10.0 -- **Build Tool**: dotnet CLI -- **Test Framework**: MSTest -- **Package Manager**: NuGet - -### CI/CD Workflows - -Located in `.github/workflows/`: - -- **build.yaml**: Reusable build workflow - - Checkout, setup .NET, restore tools, restore dependencies - - Build (Release), test (normal verbosity), package, upload artifacts -- **build_on_push.yaml**: Main CI/CD pipeline - - Quality checks (markdown lint, spell check, YAML lint) - - Build on Windows (windows-latest) and Linux (ubuntu-latest) - - Triggers: Push, manual dispatch, weekly schedule (Monday 5PM UTC) - -### Configuration Files - -- **`.editorconfig`**: Code style rules and naming conventions -- **`.cspell.json`**: Spell checking configuration -- **`.markdownlint.json`**: Markdown linting rules -- **`.yamllint.yaml`**: YAML linting rules -- **`.config/dotnet-tools.json`**: Dotnet tools manifest -- **`DemaConsulting.SonarMark.sln`**: Solution file - -### Quality Standards - -- All builds must succeed without warnings -- All tests must pass -- Code must pass static analysis -- Documentation must be up to date -- Markdown linting must pass -- Spell checking must pass -- YAML linting must pass - -## Release Process - -### Version Management - -- Follow semantic versioning (SemVer) -- Update version numbers in project files -- Create and tag releases appropriately -- Generate release notes - -## Quality Checks - -Before merging changes: - -1. **Build Validation**: Ensure builds succeed on all target frameworks -2. **Test Execution**: All tests pass with no failures -3. **Linting**: All linting checks pass (markdown, YAML, spell check) -4. **Static Analysis**: No new warnings or errors -5. **Code Review**: Changes reviewed by maintainers -6. **Security Scanning**: No new security vulnerabilities - -## Best Practices - -### Pull Request Management - -- Review PRs promptly -- Provide constructive feedback -- Ensure PRs meet quality standards -- Verify CI checks pass before merging -- Keep PRs focused and reasonably sized - -### Issue Management - -- Triage new issues quickly -- Label issues appropriately -- Prioritize based on impact and effort -- Close stale or resolved issues -- Keep issue discussions focused - -### Dependency Updates - -- Test thoroughly before merging -- Review release notes for breaking changes -- Update documentation if APIs change -- Consider impact on users - -### Communication - -- Keep stakeholders informed -- Document decisions and rationale -- Be responsive to community feedback -- Maintain professional and friendly tone - -## Boundaries - -### Do - -- Approve and merge well-reviewed PRs -- Update project dependencies regularly -- Maintain CI/CD pipelines -- Coordinate releases -- Triage and manage issues -- Ensure quality standards are met -- Update project configuration files - -### Do Not - -- Merge PRs without proper review -- Make breaking changes without discussion -- Ignore failing tests or builds -- Rush releases without proper validation -- Remove or disable quality checks -- Make unilateral architectural decisions - -## Security and Compliance - -- Monitor security advisories for dependencies -- Respond promptly to security reports -- Follow security disclosure procedures in SECURITY.md -- Ensure license compliance -- Maintain MIT license headers in source files - -## Tools and Commands - -### Build and Test +### Commands ```bash -# Restore tools -dotnet tool restore - -# Restore dependencies -dotnet restore - -# Build +dotnet tool restore && dotnet restore dotnet build --no-restore --configuration Release - -# Test -dotnet test --no-build --configuration Release --verbosity normal - -# Package +dotnet test --no-build --configuration Release dotnet pack --no-build --configuration Release ``` -### Linting Commands - -Use the project's CI pipeline configuration as the source of truth for linting commands. Linting tools and their -specific versions are managed through the CI/CD workflows. - -## Integration with Development +### VS Code Tasks -- Work closely with developers on architectural decisions -- Coordinate with documentation writer for release documentation -- Collaborate with quality enforcer on quality standards -- Engage with community on feature priorities +Use `.vscode/tasks.json` for common tasks: build, test, lint all, verify requirements, etc. -## Continuous Improvement +## Don't -- Regularly review and optimize build processes -- Update tooling and dependencies -- Improve documentation and processes -- Learn from issues and incidents -- Solicit feedback from contributors +- Merge without CI passing +- Ignore failing tests/builds +- Disable quality checks diff --git a/.github/agents/software-quality-enforcer.md b/.github/agents/software-quality-enforcer.md index 28eed54..e04c9b1 100644 --- a/.github/agents/software-quality-enforcer.md +++ b/.github/agents/software-quality-enforcer.md @@ -1,136 +1,38 @@ --- name: Software Quality Enforcer -description: Code quality specialist focused on enforcing testing standards and code coverage, running static analysis and linting, performing code reviews and quality gates, and ensuring zero-warning builds. +description: Code quality specialist for SonarMark - enforce testing, coverage >80%, static analysis, and zero warnings --- -# Software Quality Enforcer +# Software Quality Enforcer - SonarMark -Code quality specialist focused on maintaining high standards for the SonarMark -library. Enforces testing, linting, static analysis, and code review standards. -Ensures all changes meet quality gates before merging. +Enforce quality standards for SonarMark .NET CLI tool. -## Primary Responsibilities +## Quality Gates (ALL Must Pass) -1. **Enforce Quality Standards** - - Ensure all code changes have appropriate unit tests - - Verify code coverage meets thresholds (>80%) - - Run static analyzers and ensure zero warnings - - Check that code follows .editorconfig style rules +- Zero build warnings (TreatWarningsAsErrors=true) +- All tests passing on .NET 8/9/10 +- Code coverage >80% +- Static analysis (Microsoft.CodeAnalysis.NetAnalyzers, SonarAnalyzer.CSharp) +- Code formatting (.editorconfig compliance) +- Markdown/spell/YAML linting +- Requirements traceability (all linked to tests) -2. **Testing Standards** - - Verify new features have comprehensive unit tests - - Ensure tests follow AAA (Arrange, Act, Assert) pattern - - Check tests are isolated and don't depend on execution order - - Validate test names are descriptive (ClassName_MethodUnderTest_Scenario_ExpectedBehavior) - - Confirm both success and failure scenarios are tested - - Verify all requirements in `requirements.yaml` are linked to tests - - Ensure requirements traceability is maintained for all changes +## SonarMark-Specific -3. **Code Review** - - Review code for adherence to C# conventions - - Check nullable reference type usage - - Verify XML documentation exists for public APIs - - Ensure no external runtime dependencies are added - - Look for security vulnerabilities +- **Test Naming**: `ClassName_MethodUnderTest_Scenario_ExpectedBehavior` (for requirements traceability) +- **Test Linkage**: All requirements MUST link to tests (prefer integration tests) +- **XML Docs**: On ALL members (public/internal/private) with spaces after `///` +- **No external runtime deps**: Minimal dependencies only -4. **Build and CI/CD** - - Verify builds complete with zero warnings - - Ensure all tests pass on all target frameworks (.NET 8, 9, 10) - - Check SonarCloud quality gates pass - - Validate SBOM generation succeeds - -## Working Approach - -- **Run Checks First**: Always build and test before making changes -- **Use Existing Tools**: Leverage dotnet format, analyzers, and tests -- **Fix, Don't Suppress**: Address warnings rather than suppressing them -- **Be Thorough**: Check both obvious and edge cases -- **Provide Context**: Explain why changes improve quality -- **Automate**: Prefer automated checks over manual reviews - -## Commands You Use +## Commands ```bash -# Build with zero warnings -dotnet build --configuration Release - -# Run all tests -dotnet test --configuration Release - -# Check code formatting +dotnet build --configuration Release # Zero warnings required +dotnet test --configuration Release --collect "XPlat Code Coverage" dotnet format --verify-no-changes - -# Run with coverage -dotnet test --collect "XPlat Code Coverage" - -# Restore tools and dependencies -dotnet tool restore -dotnet restore - -# Validate requirements traceability dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce ``` -## Quality Gates - -All changes must pass: - -- ✅ Zero build warnings (warnings are errors) -- ✅ All unit tests passing -- ✅ Code coverage > 80% -- ✅ Static analysis (Microsoft.CodeAnalysis.NetAnalyzers, SonarAnalyzer.CSharp) -- ✅ SonarCloud quality gate -- ✅ Code formatting per .editorconfig -- ✅ Spell checking passes (cspell) -- ✅ Markdown linting passes (markdownlint) -- ✅ Requirements traceability (all requirements have tests, all tests pass) - -## Review Checklist - -For every code change, verify: - -- [ ] New code has unit tests -- [ ] Tests follow AAA pattern -- [ ] Tests are linked to requirements in `requirements.yaml` -- [ ] Public APIs have XML documentation -- [ ] No runtime dependencies added -- [ ] Nullable reference types used correctly -- [ ] No security vulnerabilities introduced -- [ ] Code follows naming conventions -- [ ] Methods are focused and concise -- [ ] No code duplication (DRY principle) -- [ ] Build succeeds with zero warnings -- [ ] All tests pass -- [ ] Requirements traceability is maintained - -## Common Issues to Catch - -- Missing unit tests for new functionality -- Insufficient test coverage -- Warnings being ignored -- Inconsistent code formatting -- Missing XML documentation -- Adding external runtime dependencies -- Security vulnerabilities (XXE, injection, etc.) -- Nullable reference type misuse -- Overly complex methods -- Code duplication - -## What NOT To Do - -- Don't suppress warnings without justification -- Don't reduce test coverage -- Don't disable or remove existing tests -- Don't add external runtime dependencies -- Don't bypass quality gates -- Don't merge changes that break builds or tests - -## Collaboration - -- Work with Documentation Writer to ensure documentation matches code quality -- Work with Project Maintainer to improve CI/CD pipelines -- Escalate architectural concerns that affect quality -- Provide constructive feedback to contributors +### VS Code Tasks -Remember: Quality is not negotiable. Your role ensures that SonarMark maintains -its reputation for reliability, performance, and maintainability. +Use `.vscode/tasks.json` for: build and test, lint all, test with coverage, verify requirements diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..eac1b29 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,166 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "build", + "command": "dotnet", + "type": "process", + "args": [ + "build", + "--configuration", + "Release", + "${workspaceFolder}/DemaConsulting.SonarMark.sln" + ], + "problemMatcher": "$msCompile", + "group": { + "kind": "build", + "isDefault": true + }, + "presentation": { + "reveal": "always", + "panel": "shared" + } + }, + { + "label": "test", + "command": "dotnet", + "type": "process", + "args": [ + "test", + "--configuration", + "Release", + "${workspaceFolder}/DemaConsulting.SonarMark.sln" + ], + "problemMatcher": "$msCompile", + "group": { + "kind": "test", + "isDefault": true + }, + "presentation": { + "reveal": "always", + "panel": "shared" + } + }, + { + "label": "build and test", + "dependsOn": [ + "build", + "test" + ], + "dependsOrder": "sequence", + "problemMatcher": [], + "presentation": { + "reveal": "always", + "panel": "shared" + } + }, + { + "label": "format", + "command": "dotnet", + "type": "process", + "args": [ + "format" + ], + "problemMatcher": [], + "presentation": { + "reveal": "always", + "panel": "shared" + } + }, + { + "label": "lint markdown", + "command": "npx", + "type": "shell", + "args": [ + "markdownlint-cli2", + "**/*.md", + "#node_modules" + ], + "problemMatcher": [], + "presentation": { + "reveal": "always", + "panel": "shared" + } + }, + { + "label": "spell check", + "command": "npx", + "type": "shell", + "args": [ + "cspell", + "**/*.{cs,md,json,yaml,yml}", + "--no-progress" + ], + "problemMatcher": [], + "presentation": { + "reveal": "always", + "panel": "shared" + } + }, + { + "label": "lint yaml", + "command": "npx", + "type": "shell", + "args": [ + "yamllint", + "." + ], + "problemMatcher": [], + "presentation": { + "reveal": "always", + "panel": "shared" + } + }, + { + "label": "lint all", + "dependsOn": [ + "format", + "lint markdown", + "spell check", + "lint yaml" + ], + "dependsOrder": "parallel", + "problemMatcher": [], + "presentation": { + "reveal": "always", + "panel": "shared" + } + }, + { + "label": "test with coverage", + "command": "dotnet", + "type": "process", + "args": [ + "test", + "--configuration", + "Release", + "--collect", + "XPlat Code Coverage", + "${workspaceFolder}/DemaConsulting.SonarMark.sln" + ], + "problemMatcher": "$msCompile", + "presentation": { + "reveal": "always", + "panel": "shared" + } + }, + { + "label": "verify requirements", + "command": "dotnet", + "type": "shell", + "args": [ + "reqstream", + "--requirements", + "requirements.yaml", + "--tests", + "test-results/**/*.trx", + "--enforce" + ], + "problemMatcher": [], + "presentation": { + "reveal": "always", + "panel": "shared" + } + } + ] +} diff --git a/AGENTS.md b/AGENTS.md index c95f33c..00d6dcf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,213 +1,64 @@ -# GitHub Copilot Agents - -This document provides comprehensive guidance for GitHub Copilot agents working on the SonarMark project. - -## Overview - -GitHub Copilot agents are AI-powered assistants that help with various development tasks. This document will be -updated as agents are configured for this repository. - -## Project Overview - -SonarMark is a .NET command-line tool for creating code quality reports from SonarQube/SonarCloud analysis results. -It provides functionality to generate markdown reports that summarize code quality metrics, issues, and violations. - -### Technology Stack - -- **Language**: C# 12 -- **Framework**: .NET 8.0, 9.0, and 10.0 -- **Testing Framework**: MSTest -- **Build System**: dotnet CLI -- **Package Manager**: NuGet - -## Project Structure - -```text -SonarMark/ -├── .config/ # Dotnet tools configuration -│ └── dotnet-tools.json # Local tool manifest -├── .github/ # GitHub Actions workflows -│ ├── agents/ # Agent configurations -│ ├── ISSUE_TEMPLATE/ # Issue templates -│ └── workflows/ -│ ├── build.yaml # Reusable build workflow -│ └── build_on_push.yaml # Main CI/CD pipeline -├── docs/ # Documentation -│ ├── guide/ # User guide -│ ├── requirements/ # Requirements documentation -│ └── tracematrix/ # Trace matrix documentation -├── src/ # Source code -│ └── DemaConsulting.SonarMark/ # Main application project -├── test/ # Test projects -│ └── DemaConsulting.SonarMark.Tests/ # Test project -├── .cspell.json # Spell checking configuration -├── .editorconfig # Code style configuration -├── .markdownlint.json # Markdown linting rules -├── .yamllint.yaml # YAML linting rules -├── AGENTS.md # This file -├── CODE_OF_CONDUCT.md # Code of Conduct -├── LICENSE # MIT License -├── README.md # Project documentation -├── requirements.yaml # Requirements definitions -└── SECURITY.md # Security policy -``` +# Agent Quick Reference -### Critical Files - -- **`.editorconfig`**: Defines code style rules, naming conventions, and formatting standards -- **`.cspell.json`**: Contains spell-checking configuration and custom dictionary -- **`.markdownlint.json`**: Markdown linting rules -- **`.yamllint.yaml`**: YAML linting rules -- **`DemaConsulting.SonarMark.sln`**: Solution file containing all projects -- **`requirements.yaml`**: Requirements definitions with test mappings - -## Testing Guidelines - -- **Test Framework**: MSTest v4 (Microsoft.VisualStudio.TestTools.UnitTesting) -- **Test File Naming**: `[Component]Tests.cs` (e.g., `ProgramTests.cs`) -- **Test Method Naming**: `ClassName_MethodUnderTest_Scenario_ExpectedBehavior` format - - Example: `Program_Main_NoArguments_ReturnsSuccess` clearly indicates testing the `Program.Main` method - - This pattern makes test intent clear for requirements traceability -- **Requirements Traceability**: All requirements in `requirements.yaml` should be linked to tests - - Integration tests are preferred for requirements evidence - - Unit tests may be used if no integration test provides appropriate evidence - - Integration tests use Test Source Linking format (`filepart@testname`) for platform/runtime requirements - - Example: `windows-latest@IntegrationTest_VersionFlag_OutputsVersion` links a Windows-specific test - - Example: `dotnet8.x@IntegrationTest_ReportGeneration_CreatesMarkdownFile` links a .NET 8 test -- **MSTest v4 APIs**: Use modern assertions: - - `Assert.HasCount(collection, expectedCount)` instead of `Assert.AreEqual(count, collection.Count)` - - `Assert.IsEmpty(collection)` instead of `Assert.AreEqual(0, collection.Count)` - - `Assert.DoesNotContain(item, collection)` for negative checks -- **Console Testing**: Save and restore `Console.Out` in tests that modify console output: - - ```csharp - var originalOut = Console.Out; - try { /* test code */ } - finally { Console.SetOut(originalOut); } - ``` - -- **All tests must pass** before merging changes -- **No warnings allowed** in test builds - -## Requirements Management - -- **Requirements Tool**: DemaConsulting.ReqStream is used for requirements management -- **Requirements File**: `requirements.yaml` defines all project requirements -- **Trace Matrix**: Requirements are traced to tests using the ReqStream tool -- **Documentation**: Requirements and trace matrix PDFs are generated as part of the build process -- **Enforcement**: The `--enforce` flag ensures all requirements have test coverage -- **Test Naming**: Tests must use the naming pattern that clearly indicates what they test for traceability - -## Code Style and Conventions - -### Naming Conventions - -- **Interfaces**: Must begin with `I` (e.g., `IReportGenerator`) -- **Classes, Structs, Enums**: PascalCase -- **Methods, Properties**: PascalCase -- **Parameters, Local Variables**: camelCase - -### Code Organization - -- **Namespace Declarations**: Use file-scoped namespaces (C# 10+) -- **Using Directives**: Sort system directives first -- **Braces**: Required for all control statements -- **Indentation**: 4 spaces for C#, 2 spaces for YAML/JSON/XML -- **Encoding**: UTF-8 with BOM, LF line endings with final newline - -### Documentation and Comments - -- **Copyright Headers**: All source files must include the MIT license header -- **XML Documentation**: Use triple-slash comments (`///`) for all public, internal, and private members - - **IMPORTANT**: Summary blocks must be indented with spaces after `///` - - ```csharp - /// - /// This is the correct indentation format for summary blocks. - /// - ``` - -- **Error Handling Patterns**: - - Argument parsing: Throw `ArgumentException` with descriptive messages - - Runtime errors during execution: Use `InvalidOperationException` - - Write methods (WriteLine/WriteError) are for output AFTER successful parsing -- **Code Reusability**: Create properties or methods to avoid code duplication - -## Quality Standards - -- **Static Analysis**: Built-in .NET analyzers enforce code style, naming rules, and nullable reference types -- **Documentation**: - - README.md uses absolute URLs (included in NuGet package) - - Other markdown files use link references: `[text][ref]` with `[ref]: url` at end -- **Linting**: - - **Markdown**: Must pass markdownlint (max line length: 120 chars) - - Lists must be surrounded by blank lines (MD032) - - Run locally: Check CI workflow for markdownlint-cli2-action usage - - **Spell Check**: Must pass cspell (custom dictionary in `.cspell.json`) - - Add project-specific terms to the custom dictionary if needed - - **YAML**: Must pass yamllint (2-space indentation, max line length: 120 chars) - - **All linting must pass locally before committing** - CI will reject changes with linting errors - -## CI/CD Pipelines - -The project uses GitHub Actions workflows in `.github/workflows/`: - -- **build_on_push.yaml**: Runs quality checks, builds on Windows and Linux -- **build.yaml**: Reusable workflow for restore, build, test, and package - -Build commands: +Project-specific guidance for agents working on SonarMark - a .NET CLI tool for creating code quality reports from +SonarQube/SonarCloud analysis results. -```bash -dotnet tool restore # Restore dotnet tools -dotnet restore # Restore dependencies -dotnet build --no-restore --configuration Release -dotnet test --no-build --configuration Release --verbosity normal -dotnet pack --no-build --configuration Release -``` +## Tech Stack + +- C# 12, .NET 8.0/9.0/10.0, MSTest, dotnet CLI, NuGet + +## Key Files -## Pre-Finalization Quality Checks +- **`requirements.yaml`** - All requirements with test linkage (enforced via `dotnet reqstream --enforce`) +- **`.editorconfig`** - Code style (file-scoped namespaces, 4-space indent, UTF-8+BOM, LF endings) +- **`.cspell.json`, `.markdownlint.json`, `.yamllint.yaml`** - Linting configs +- **`.vscode/tasks.json`** - VS Code tasks for build, test, lint, and quality checks -Before completing any task, you **MUST** perform these checks in order and ensure they all pass: +## Requirements (SonarMark-Specific) -1. **Build and Test**: Run `dotnet build --configuration Release && dotnet test --configuration Release` - all tests - must pass with zero warnings -2. **Code Review**: Use `code_review` tool and address all valid concerns -3. **Security Scanning**: Use `codeql_checker` tool after code review - must report zero vulnerabilities -4. **Linting**: Run all linters locally and fix any issues before pushing changes: - - **Markdown**: Run markdownlint on all changed `.md` files - must pass with zero errors - - **Spell Check**: Run cspell on all changed files - must pass with zero errors - - **YAML**: Run yamllint on all changed `.yaml` or `.yml` files - must pass with zero errors - - These linters run in CI and will fail the build if not passing +- Link ALL requirements to tests (prefer integration tests over unit tests) +- Enforced in CI: `dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce` +- When adding features: add requirement + link to test -## Project-Specific Guidelines +## Testing (SonarMark-Specific) -### Key Decisions from Recent Reviews +- **Test Naming**: `ClassName_MethodUnderTest_Scenario_ExpectedBehavior` (for requirements traceability) +- **MSTest v4**: Use `Assert.HasCount()`, `Assert.IsEmpty()`, `Assert.DoesNotContain()` (not old APIs) +- **Console Tests**: Always save/restore `Console.Out` in try/finally -These patterns emerged from code review feedback and should be followed: +## Code Style (SonarMark-Specific) -1. **XmlDoc Formatting**: Always indent summary content with spaces after `///` -2. **Error Handling**: Throw exceptions during parsing; use Write methods only after successful parsing -3. **Code Reuse**: Extract repeated code into properties or methods -4. **Console Testing**: Always save/restore `Console.Out` in try/finally blocks -5. **Modern Test APIs**: Prefer MSTest v4 assertions (HasCount, IsEmpty, DoesNotContain) +- **XML Docs**: On ALL members (public/internal/private) with spaces after `///` in summaries +- **Errors**: `ArgumentException` for parsing, `InvalidOperationException` for runtime, Write* only after success +- **No code duplication**: Extract to properties/methods -### What NOT to Do +## Linting (SonarMark-Specific) -- Don't delete or modify working code unless fixing a security vulnerability -- Don't remove or modify existing tests unless directly related to your changes -- Don't commit build artifacts (`bin/`, `obj/`, `node_modules/`) -- Don't use force push (`git reset`, `git rebase`) -- Don't create temporary files in the repository (use `/tmp` instead) -- Don't make changes to `.github/agents/` files (for other agents only) +- **README.md**: Absolute URLs only (shipped in NuGet package) +- **Other .md**: Reference-style links `[text][ref]` with `[ref]: url` at end +- **All linters must pass locally**: markdownlint, cspell, yamllint (see `.vscode/tasks.json` or CI workflows) + +## Build & Quality (Quick Reference) + +```bash +# Standard build/test +dotnet build --configuration Release && dotnet test --configuration Release + +# Pre-finalization checklist (in order): +# 1. Build/test (zero warnings required) +# 2. code_review tool +# 3. codeql_checker tool +# 4. All linters (markdownlint, cspell, yamllint) +# 5. Requirements: dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce +``` -## Available Agents +## Custom Agents -The following custom agents are configured for this repository. Each agent file contains detailed guidelines, -responsibilities, and project-specific conventions. +Delegate tasks to specialized agents for better results: -- **Documentation Writer** (`.github/agents/documentation-writer.md`) - Expert agent for creating, updating, and - maintaining project documentation -- **Project Maintainer** (`.github/agents/project-maintainer.md`) - Expert agent for overall project management, - dependency updates, CI/CD maintenance, and release coordination -- **Software Quality Enforcer** (`.github/agents/software-quality-enforcer.md`) - Expert agent for enforcing code - quality standards, testing requirements, and quality gates +- **documentation-writer** - Invoke for: documentation updates/reviews, requirements.yaml changes, + markdown/spell/YAML linting +- **project-maintainer** - Invoke for: dependency updates, CI/CD maintenance, releases, requirements + traceability enforcement +- **software-quality-enforcer** - Invoke for: code quality reviews, test coverage verification (>80%), + static analysis, zero-warning builds, requirements test quality diff --git a/build.bat b/build.bat new file mode 100644 index 0000000..a56a4b0 --- /dev/null +++ b/build.bat @@ -0,0 +1,12 @@ +@echo off +REM Build and test SonarMark (Windows) + +echo Building SonarMark... +dotnet build --configuration Release +if %errorlevel% neq 0 exit /b %errorlevel% + +echo Running tests... +dotnet test --configuration Release --verbosity normal +if %errorlevel% neq 0 exit /b %errorlevel% + +echo Build and test completed successfully! diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..6bf0f01 --- /dev/null +++ b/build.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +# Build and test SonarMark + +set -e # Exit on error + +echo "🔧 Building SonarMark..." +dotnet build --configuration Release + +echo "✅ Running tests..." +dotnet test --configuration Release --verbosity normal + +echo "✨ Build and test completed successfully!" diff --git a/lint.bat b/lint.bat new file mode 100644 index 0000000..25d2806 --- /dev/null +++ b/lint.bat @@ -0,0 +1,20 @@ +@echo off +REM Run all linters for SonarMark (Windows) + +echo Checking markdown... +call npx markdownlint-cli2 "**/*.md" "#node_modules" +if %errorlevel% neq 0 exit /b %errorlevel% + +echo Checking spelling... +call npx cspell "**/*.{cs,md,json,yaml,yml}" --no-progress +if %errorlevel% neq 0 exit /b %errorlevel% + +echo Checking YAML... +yamllint . +if %errorlevel% neq 0 exit /b %errorlevel% + +echo Checking code formatting... +dotnet format --verify-no-changes +if %errorlevel% neq 0 exit /b %errorlevel% + +echo All linting passed! diff --git a/lint.sh b/lint.sh new file mode 100755 index 0000000..9e04d3a --- /dev/null +++ b/lint.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +# Run all linters for SonarMark + +set -e # Exit on error + +echo "📝 Checking markdown..." +npx markdownlint-cli2 "**/*.md" "#node_modules" + +echo "🔤 Checking spelling..." +npx cspell "**/*.{cs,md,json,yaml,yml}" --no-progress + +echo "📋 Checking YAML..." +yamllint . + +echo "🎨 Checking code formatting..." +dotnet format --verify-no-changes + +echo "✨ All linting passed!" diff --git a/src/DemaConsulting.SonarMark/Validation.cs b/src/DemaConsulting.SonarMark/Validation.cs index 8022052..81d3e60 100644 --- a/src/DemaConsulting.SonarMark/Validation.cs +++ b/src/DemaConsulting.SonarMark/Validation.cs @@ -595,7 +595,7 @@ private sealed class TemporaryDirectory : IDisposable public TemporaryDirectory() { DirectoryPath = Path.Combine(Path.GetTempPath(), $"sonarmark_validation_{Guid.NewGuid()}"); - + try { Directory.CreateDirectory(DirectoryPath); diff --git a/test/DemaConsulting.SonarMark.Tests/IntegrationTests.cs b/test/DemaConsulting.SonarMark.Tests/IntegrationTests.cs index 11c151e..87feef2 100644 --- a/test/DemaConsulting.SonarMark.Tests/IntegrationTests.cs +++ b/test/DemaConsulting.SonarMark.Tests/IntegrationTests.cs @@ -38,7 +38,7 @@ public void TestInitialize() // because the test project references the main project var baseDir = AppContext.BaseDirectory; _dllPath = Path.Combine(baseDir, "DemaConsulting.SonarMark.dll"); - + Assert.IsTrue(File.Exists(_dllPath), $"Could not find SonarMark DLL at {_dllPath}"); }