diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 88d4aa0..0367942 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -49,6 +49,12 @@ "commands": [ "versionmark" ] + }, + "demaconsulting.reviewmark": { + "version": "0.1.0-rc.3", + "commands": [ + "reviewmark" + ] } } } \ No newline at end of file diff --git a/.cspell.json b/.cspell.json index faa1a57..fbf8052 100644 --- a/.cspell.json +++ b/.cspell.json @@ -44,6 +44,10 @@ "Qube", "reqstream", "ReqStream", + "reviewmark", + "ReviewMark", + "reviewplan", + "reviewreport", "Sarif", "SarifMark", "SBOM", diff --git a/.github/agents/code-review-agent.md b/.github/agents/code-review-agent.md new file mode 100644 index 0000000..8348f32 --- /dev/null +++ b/.github/agents/code-review-agent.md @@ -0,0 +1,72 @@ +--- +name: Code Review Agent +description: Assists in performing formal file reviews - knows how to elaborate review-sets and perform structured review checks +--- + +# Code Review Agent - Template DotNet Library + +Perform formal file reviews for a named review-set, producing a structured findings report. + +## When to Invoke This Agent + +Invoke the code-review-agent for: + +- Performing a formal review of a named review-set +- Producing review evidence for the Continuous Compliance pipeline +- Checking files against the structured review checklist + +## How to Run This Agent + +When invoked, the agent will be told which review-set is being reviewed. For example: + +```text +Review the "Template-Review" review-set. +``` + +## Responsibilities + +### Step 1: Elaborate the Review-Set + +Run the following command to get the list of files in the review-set: + +```bash +dotnet reviewmark --elaborate [review-set-id] +``` + +For example: + +```bash +dotnet reviewmark --elaborate Template-Review +``` + +This will output the list of files covered by the review-set, along with their fingerprints +and current review status (current, stale, or missing). + +### Step 2: Review Each File + +For each file in the review-set, apply the checks from the standard review template at +[review-template.md](https://github.com/demaconsulting/ContinuousCompliance/blob/main/docs/review-template/review-template.md). +Determine which checklist sections apply based on the type of file (requirements, documentation, +source code, tests). + +### Step 3: Generate Report + +Write an `AGENT_REPORT_review-[review-set-id].md` file in the repository root with the +structured findings. This file is excluded from git and linting via `.gitignore`. + +## Report Format + +The generated `AGENT_REPORT_review-[review-set-id].md` must include: + +1. **Review Header**: Project, Review ID, review date, files under review +2. **Checklist Results**: Each applicable section with Pass/Fail/N/A for every check +3. **Summary of Findings**: Any checks recorded as Fail, and notable observations +4. **Overall Outcome**: Pass or Fail with justification + +## Don't + +- Make any changes to source files, tests, or documentation during a review — record all + findings in the report only +- Skip applicable checklist sections +- Record findings without an overall outcome +- Commit the `AGENT_REPORT_*.md` file (it is excluded from git via `.gitignore`) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 4f4d998..cd210d3 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -355,7 +355,7 @@ jobs: echo "Capturing tool versions..." dotnet versionmark --capture --job-id "build-docs" \ --output "artifacts/versionmark-build-docs.json" -- \ - dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream buildmark versionmark + dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream buildmark versionmark reviewmark echo "✓ Tool versions captured" # === CAPTURE OTS SELF-VALIDATION RESULTS === @@ -393,6 +393,12 @@ jobs: --validate --results artifacts/sonarmark-self-validation.trx + - name: Run ReviewMark self-validation + run: > + dotnet reviewmark + --validate + --results artifacts/reviewmark-self-validation.trx + # === GENERATE MARKDOWN REPORTS === # This section generates all markdown reports from various tools and sources. # Downstream projects: Add any additional markdown report generation steps here. @@ -440,6 +446,28 @@ jobs: echo "=== SonarCloud Quality Report ===" cat docs/quality/sonar-quality.md + - name: Generate Review Plan and Review Report with ReviewMark + shell: bash + run: > + dotnet reviewmark + --definition .reviewmark.yaml + --plan docs/reviewplan/review-plan.md + --plan-depth 1 + --report docs/reviewreport/review-report.md + --report-depth 1 + + - name: Display Review Plan + shell: bash + run: | + echo "=== Review Plan ===" + cat docs/reviewplan/review-plan.md + + - name: Display Review Report + shell: bash + run: | + echo "=== Review Report ===" + cat docs/reviewreport/review-report.md + - name: Generate Build Notes with BuildMark shell: bash env: @@ -534,6 +562,26 @@ jobs: --metadata date="$(date +'%Y-%m-%d')" --output docs/tracematrix/tracematrix.html + - name: Generate Review Plan HTML with Pandoc + shell: bash + run: > + dotnet pandoc + --defaults docs/reviewplan/definition.yaml + --filter node_modules/.bin/mermaid-filter.cmd + --metadata version="${{ inputs.version }}" + --metadata date="$(date +'%Y-%m-%d')" + --output docs/reviewplan/review-plan.html + + - name: Generate Review Report HTML with Pandoc + shell: bash + run: > + dotnet pandoc + --defaults docs/reviewreport/definition.yaml + --filter node_modules/.bin/mermaid-filter.cmd + --metadata version="${{ inputs.version }}" + --metadata date="$(date +'%Y-%m-%d')" + --output docs/reviewreport/review-report.html + # === GENERATE PDF DOCUMENTS WITH WEASYPRINT === # This section converts HTML documents to PDF using Weasyprint. # Downstream projects: Add any additional Weasyprint PDF generation steps here. @@ -580,6 +628,20 @@ jobs: docs/tracematrix/tracematrix.html "docs/TemplateDotNetLibrary Trace Matrix.pdf" + - name: Generate Review Plan PDF with Weasyprint + run: > + dotnet weasyprint + --pdf-variant pdf/a-3u + docs/reviewplan/review-plan.html + "docs/TemplateDotNetLibrary Review Plan.pdf" + + - name: Generate Review Report PDF with Weasyprint + run: > + dotnet weasyprint + --pdf-variant pdf/a-3u + docs/reviewreport/review-report.html + "docs/TemplateDotNetLibrary Review Report.pdf" + # === UPLOAD ARTIFACTS === # This section uploads all generated documentation artifacts. # Downstream projects: Add any additional artifact uploads here. diff --git a/.gitignore b/.gitignore index 467dfd7..ea71f55 100644 --- a/.gitignore +++ b/.gitignore @@ -95,6 +95,8 @@ docs/justifications/justifications.md docs/tracematrix/tracematrix.md docs/quality/codeql-quality.md docs/quality/sonar-quality.md +docs/reviewplan/review-plan.md +docs/reviewreport/review-report.md docs/buildnotes.md docs/buildnotes/versions.md diff --git a/.reviewmark.yaml b/.reviewmark.yaml new file mode 100644 index 0000000..c4e93a1 --- /dev/null +++ b/.reviewmark.yaml @@ -0,0 +1,26 @@ +--- +# ReviewMark Configuration File +# This file defines which files require review, where the evidence store is located, +# and how files are grouped into named review-sets. + +# Patterns identifying all files that require review. +# Processed in order; prefix a pattern with '!' to exclude. +needs-review: + - "**/*.cs" + - "!**/obj/**" + +# Evidence source: review data and index.json are located in the 'reviews' branch +# of this repository, accessed through the GitHub public HTTPS raw content access. +# Note: The 'reviews' branch must be created and populated with review evidence PDFs +# and an index.json before enforcement (--enforce flag) can be enabled in the pipeline. +evidence-source: + type: url + location: https://raw.githubusercontent.com/demaconsulting/TemplateDotNetLibrary/reviews/index.json + +# Review sets grouping files by logical unit of review. +reviews: + - id: Template-Review + title: Review of Template DotNet Library + paths: + - "**/*.cs" + - "!**/obj/**" diff --git a/.versionmark.yaml b/.versionmark.yaml index b8bf259..6fa4e84 100644 --- a/.versionmark.yaml +++ b/.versionmark.yaml @@ -26,39 +26,44 @@ tools: # SonarScanner for .NET (from dotnet tool list) dotnet-sonarscanner: command: dotnet tool list - regex: '(?i)dotnet-sonarscanner\s+(?\d+\.\d+\.\d+)' + regex: '(?i)dotnet-sonarscanner\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # Pandoc (DemaConsulting.PandocTool from dotnet tool list) pandoc: command: dotnet tool list - regex: '(?i)demaconsulting\.pandoctool\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.pandoctool\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # WeasyPrint (DemaConsulting.WeasyPrintTool from dotnet tool list) weasyprint: command: dotnet tool list - regex: '(?i)demaconsulting\.weasyprinttool\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.weasyprinttool\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # SarifMark (DemaConsulting.SarifMark from dotnet tool list) sarifmark: command: dotnet tool list - regex: '(?i)demaconsulting\.sarifmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.sarifmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # SonarMark (DemaConsulting.SonarMark from dotnet tool list) sonarmark: command: dotnet tool list - regex: '(?i)demaconsulting\.sonarmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.sonarmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # ReqStream (DemaConsulting.ReqStream from dotnet tool list) reqstream: command: dotnet tool list - regex: '(?i)demaconsulting\.reqstream\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.reqstream\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # BuildMark (DemaConsulting.BuildMark from dotnet tool list) buildmark: command: dotnet tool list - regex: '(?i)demaconsulting\.buildmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.buildmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # VersionMark (DemaConsulting.VersionMark from dotnet tool list) versionmark: command: dotnet tool list - regex: '(?i)demaconsulting\.versionmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.versionmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' + + # ReviewMark (DemaConsulting.ReviewMark from dotnet tool list) + reviewmark: + command: dotnet tool list + regex: '(?i)demaconsulting\.reviewmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' diff --git a/docs/reviewplan/definition.yaml b/docs/reviewplan/definition.yaml new file mode 100644 index 0000000..362a390 --- /dev/null +++ b/docs/reviewplan/definition.yaml @@ -0,0 +1,11 @@ +--- +resource-path: + - docs/reviewplan + - docs/template +input-files: + - docs/reviewplan/title.txt + - docs/reviewplan/introduction.md + - docs/reviewplan/review-plan.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/reviewplan/introduction.md b/docs/reviewplan/introduction.md new file mode 100644 index 0000000..27ce3de --- /dev/null +++ b/docs/reviewplan/introduction.md @@ -0,0 +1,32 @@ +# Introduction + +This document contains the review plan for the Template DotNet Library project. + +## Purpose + +This review plan provides a comprehensive overview of all files requiring formal review +in the Template DotNet Library project. It identifies which review-sets cover which +files and serves as evidence that every file requiring review is covered by at least +one named review-set. + +## Scope + +This review plan covers: + +- C# source code files requiring formal review +- Mapping of C# source files to named review-sets + +## Generation Source + +This report is automatically generated by the ReviewMark tool, analyzing the +`.reviewmark.yaml` configuration and the review evidence store. It serves as evidence +that every file requiring review is covered by a current, valid review. + +## Audience + +This document is intended for: + +- Software developers working on Template DotNet Library +- Quality assurance teams validating review coverage +- Project stakeholders reviewing compliance status +- Auditors verifying that all required files have been reviewed diff --git a/docs/reviewplan/title.txt b/docs/reviewplan/title.txt new file mode 100644 index 0000000..8015e01 --- /dev/null +++ b/docs/reviewplan/title.txt @@ -0,0 +1,13 @@ +--- +title: Template DotNet Library Review Plan +subtitle: File Review Plan for the Template DotNet Library +author: DEMA Consulting +description: File Review Plan for the Template DotNet Library +lang: en-US +keywords: + - Template DotNet Library + - Review Plan + - File Reviews + - .NET + - Library +--- diff --git a/docs/reviewreport/definition.yaml b/docs/reviewreport/definition.yaml new file mode 100644 index 0000000..671c73e --- /dev/null +++ b/docs/reviewreport/definition.yaml @@ -0,0 +1,11 @@ +--- +resource-path: + - docs/reviewreport + - docs/template +input-files: + - docs/reviewreport/title.txt + - docs/reviewreport/introduction.md + - docs/reviewreport/review-report.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/reviewreport/introduction.md b/docs/reviewreport/introduction.md new file mode 100644 index 0000000..6667592 --- /dev/null +++ b/docs/reviewreport/introduction.md @@ -0,0 +1,33 @@ +# Introduction + +This document contains the review report for the Template DotNet Library project. + +## Purpose + +This review report provides evidence that each review-set is current — the review +evidence matches the current file fingerprints. It confirms that all formal reviews +conducted for Template DotNet Library remain valid for the current state of the +reviewed files. + +## Scope + +This review report covers: + +- Current review-set status (current, stale, or missing) +- File fingerprints and review evidence matching +- Review coverage verification + +## Generation Source + +This report is automatically generated by the ReviewMark tool, comparing the current +file fingerprints against the review evidence store. It serves as evidence that all +review-sets are current and no reviewed file has changed since its review was conducted. + +## Audience + +This document is intended for: + +- Software developers working on Template DotNet Library +- Quality assurance teams validating review currency +- Project stakeholders reviewing compliance status +- Auditors verifying that all reviews remain valid for the current release diff --git a/docs/reviewreport/title.txt b/docs/reviewreport/title.txt new file mode 100644 index 0000000..64f18b1 --- /dev/null +++ b/docs/reviewreport/title.txt @@ -0,0 +1,13 @@ +--- +title: Template DotNet Library Review Report +subtitle: File Review Report for the Template DotNet Library +author: DEMA Consulting +description: File Review Report for the Template DotNet Library +lang: en-US +keywords: + - Template DotNet Library + - Review Report + - File Reviews + - .NET + - Library +--- diff --git a/requirements.yaml b/requirements.yaml index a94a411..71c451c 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -184,3 +184,15 @@ sections: - SonarMark_IssuesRetrieval - SonarMark_HotSpotsRetrieval - SonarMark_MarkdownReportGeneration + + - id: Template-OTS-ReviewMark + title: ReviewMark shall generate a review plan and review report from the review configuration. + justification: | + DemaConsulting.ReviewMark reads the .reviewmark.yaml configuration and the review + evidence store to produce a review plan and review report documenting file review + coverage and currency. It runs in the same CI pipeline that produces the TRX test + results, so a successful pipeline run is evidence that ReviewMark executed without error. + tags: [ots] + tests: + - ReviewMark_ReviewPlanGeneration + - ReviewMark_ReviewReportGeneration