fix: Added more information into documentation for targets.

.gitignore

@@ -324,5 +324,8 @@ ASALocalRun/
 # MSBuild Binary and Structured Log
 *.binlog
 
+# Visual Studio 2022 folders
+Visual Studio 2022/
+
 # Custom
 Hx_Artifacts/

Directory.Build.props

@@ -12,23 +12,20 @@
     <PackageProjectUrl>https://heleonix.github.io/docs/Heleonix.Build/</PackageProjectUrl>
     <PackageIconUrl>https://raw.githubusercontent.com/Heleonix/docs/master/images/heleonix-logos/Heleonix-logo-128x128.jpg</PackageIconUrl>
 
-    <NoPackageAnalysis>true</NoPackageAnalysis>
-    <ContentTargetFolders>.\</ContentTargetFolders>
-    <BuildOutputTargetFolder>.\</BuildOutputTargetFolder>
+    <NoWarn>NU5048;SA0001</NoWarn>
     <PackageLicenseFile>LICENSE</PackageLicenseFile>
     <PackageReadmeFile>README.md</PackageReadmeFile>
   </PropertyGroup>
 
   <ItemGroup>
-    <None Include="..\..\LICENSE" Pack="true" PackagePath=""/>
-    <None Include="..\..\README.md" Pack="true" PackagePath="\"/>
+    <None Include="..\..\LICENSE" Pack="true" PackagePath="/" />
+    <None Include="..\..\README.md" Pack="true" PackagePath="/" />
   </ItemGroup>
 
   <PropertyGroup>
     <ImplicitUsings>enable</ImplicitUsings>
     <LangVersion>latest</LangVersion>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
-    <NoWarn>SA0001</NoWarn>
     <NeutralLanguage>en-US</NeutralLanguage>
     <SatelliteResourceLanguages>en-US</SatelliteResourceLanguages>
   </PropertyGroup>

README.md

@@ -43,7 +43,7 @@ So, if you follow well-known standards too, you do not even neeed to write custo
 4. [Request review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) from the code owner
 5. Once approved, merge your Pull Request via [Squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits)
 
-   > [!IMPORTANT]  
+   > **IMPORTANT**  
    > While merging, enter a [Conventional Commits](https://www.conventionalcommits.org/) commit message.
    > This commit message will be used in automatically generated [Github Release Notes](https://github.com/Heleonix/Heleonix.Build/releases)
    > and [NuGet Release Notes](https://www.nuget.org/packages/Heleonix.Build/#releasenotes-body-tab)

src/Heleonix.Build/Heleonix.Build.csproj

@@ -37,15 +37,15 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Heleonix.Execution" Version="2.0.1" />
+    <PackageReference Include="Heleonix.Execution" Version="2.0.2" />
     <PackageReference Include="RazorEngineCore" Version="2022.8.1" />
     <PackageReference Include="System.Net.Http.Json" Version="7.0.0" />
     <PackageReference Include="Microsoft.Build.Utilities.Core" Version="17.5.0" />
 
-    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="7.0.3" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers" />
+    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="8.0.0" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers" />
     <PackageReference Include="codecracker.CSharp" Version="1.1.0" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers" />
     <PackageReference Include="SecurityCodeScan.VS2019" Version="5.6.7" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
-    <PackageReference Include="SonarAnalyzer.CSharp" Version="8.54.0.64047" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers" />
+    <PackageReference Include="SonarAnalyzer.CSharp" Version="9.23.0.88079" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers" />
     <PackageReference Include="StyleCop.Analyzers" Version="1.1.118" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers" />
   </ItemGroup>
 </Project>

src/Heleonix.Build/Program.cs

@@ -54,7 +54,9 @@ public static int Main(string[] args)
 
                 dotnetExePath = args[i + 1];
 
+#pragma warning disable S127 // "for" loop stop conditions should be invariant
                 i += 1;
+#pragma warning restore S127 // "for" loop stop conditions should be invariant
             }
             else
             {

src/Heleonix.Build/Schemas/Targets/Hx_ChangeLog.xsd

@@ -30,6 +30,20 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Hx_ChangeLog" type="xs:string">
+    <xs:annotation>
+      <xs:documentation>
+        The virtual target for variations of real targets to generate change logs from different sources
+        and in different ways to be further used in versioning of builds, generation of release notes etc.
+        Variations of this target should generate at least the 'semver.txt' containing the new semantic version
+        in the format 'Major.Minor.Patch' of the product to be released based on discovered changes,
+        and generate two files: 'ReleaseNotes.md' and 'ReleaseNotes.txt' containing textual descriptions
+        of discovered changes, which can be used by other targets, i.e. by the 'Hx_NetBuild' while building a solution
+        with enabled NuGet package generation, or by the 'Hx_Release_GitHub' while creating a release on GitHub etc.
+      </xs:documentation>
+    </xs:annotation>
+  </xs:element>
+
   <xs:element name="Hx_ChangeLog_ArtifactsDir" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>
@@ -41,7 +55,7 @@ Example custom property that allows string content only
   <xs:element name="Hx_ChangeLog_TemplateFiles" type="msb:SimpleItemType" substitutionGroup="msb:Item">
     <xs:annotation>
       <xs:documentation>
-        The list of Razor *.cshtml template files to generates change logs with using the Hx_FileRazorGenerate task.
+        The list of Razor *.cshtml template files to generate change logs using the Hx_FileRazorGenerate task.
         Default are two templates: 'ReleaseNotes.md.cshtml' and 'ReleaseNotes.txt.cshtml' from the Heleonix.Build.
       </xs:documentation>
     </xs:annotation>

src/Heleonix.Build/Schemas/Targets/Hx_ChangeLog_GitHubCommit.xsd

@@ -30,6 +30,18 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Hx_ChangeLog_GitHubCommit" type="xs:string">
+    <xs:annotation>
+      <xs:documentation>
+        Calculates a new release version and generates change log files from GitHub commit messages,
+        which are parsed with regular expressions. By default, it calculates a new release semantic version and
+        change log messages using regular expressions for parsing.
+        By default it recognizes https://www.conventionalcommits.org, but it's welcome to specify custom regular
+        expressions to recognize custom project/company specific formats of commit messages.
+      </xs:documentation>
+    </xs:annotation>
+  </xs:element>
+
   <xs:element name="Hx_ChangeLog_GitHubCommit_Token" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>A GitHub access token to authorize to the GitHub Releases API.</xs:documentation>

src/Heleonix.Build/Schemas/Targets/Hx_DocFX.xsd

@@ -30,6 +30,14 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Hx_DocFX" type="xs:string">
+    <xs:annotation>
+      <xs:documentation>
+        The virtual target for variations of real targets to generate documentation stored as a repository.
+      </xs:documentation>
+    </xs:annotation>
+  </xs:element>
+
   <xs:element name="Hx_DocFX_ArtifactsDir" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>A path to the DocFX artifacts directory. Default is '$Hx_Run_ArtifactsDir/DocFX'.</xs:documentation>

src/Heleonix.Build/Schemas/Targets/Hx_DocFX_Git.xsd

@@ -30,6 +30,17 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Hx_DocFX_Git" type="xs:string">
+    <xs:annotation>
+      <xs:documentation>
+        The target to generate documentation created as a Docfx project.
+        The target checks out a branch from a git repository containing a Docfx project, runs the 'docfx metadata' command,
+        then runs the 'docfx build', then commits generated changes with the specified $Hx_DocFX_Message and pushes
+        changes back to the remote repository.
+      </xs:documentation>
+    </xs:annotation>
+  </xs:element>
+
   <xs:element name="Hx_DocFX_Git_BranchName" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>

src/Heleonix.Build/Schemas/Targets/Hx_ExtentReport.xsd

@@ -30,6 +30,15 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Hx_ExtentReport" type="xs:string">
+    <xs:annotation>
+      <xs:documentation>
+        The target generates test reports using https://www.extentreports.com.
+        Under the hood this target uses the https://www.nuget.org/packages/extent package.
+      </xs:documentation>
+    </xs:annotation>
+  </xs:element>
+
   <xs:element name="Hx_ExtentReport_ArtifactsDir" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>

src/Heleonix.Build/Schemas/Targets/Hx_NetBuild.xsd

@@ -30,6 +30,19 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Hx_NetBuild" type="xs:string">
+    <xs:annotation>
+      <xs:documentation>
+        The target performs building of the specified solution file.
+        It deletes specified extra files, deletes speified extra folders, cleans specified extra folders,
+        runs the 'Restore' and then 'Clean' MSBuild targets, runs 'Restore' and then 'Build' MSBuild targets.
+        Afterwards, the target copies .sln, 'bin' and 'obj' folders, *.props, *.*proj and custom artifacts files
+        to the artifacts directory, which then can be uploaded to artifacts storage and then re-used by other targets,
+        i.e. 'Hx_NetTest', 'Hx_NetNugetPush' etc.
+      </xs:documentation>
+    </xs:annotation>
+  </xs:element>
+
   <xs:element name="Hx_NetBuild_ArtifactsDir" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>

src/Heleonix.Build/Schemas/Targets/Hx_NetNugetPush.xsd

@@ -30,6 +30,17 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Hx_NetNugetPush" type="xs:string">
+    <xs:annotation>
+      <xs:documentation>
+        Publishes specified package files to the specified NuGet registry using the 'dotnet nuget push' command.
+        If no package files are specified, the target tries to find them in the $Hx_NetBuild_ArtifactsDir
+        and if package files are not found, the target executes the MSBuild 'Pack' target against the solution file
+        found in the $Hx_NetBuild_ArtifactsDir to generate package files.
+      </xs:documentation>
+    </xs:annotation>
+  </xs:element>
+
   <xs:element name="Hx_NetNugetPush_ArtifactsDir" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>

src/Heleonix.Build/Schemas/Targets/Hx_NetTest.xsd

@@ -30,6 +30,22 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Hx_NetTest" type="xs:string">
+    <xs:annotation>
+      <xs:documentation>
+        Runs the 'dotnet test' command against the specified test files. By default, runs 'XPlat Code Coverage'
+        with NUnit test logger https://www.nuget.org/packages/NunitXml.TestLogger.
+        The target internally converts the generated test coverage into XMLSummary using the 'ReportGenerator' tool,
+        and verifies the specified thresholds of source code coverage.
+        This target also replaces source code paths using the specified regular expressions
+        in generated *.info, *.xml, *.json files with persistent paths,
+        i.e. paths of source code files on the particular build agent with corresponding GitHub urls,
+        so generated test or coverage reports become portable. Such solution is flexible to support different
+        formats of test or coverage files and different persistent paths, like GitHub, GitLab, SVN etc.
+      </xs:documentation>
+    </xs:annotation>
+  </xs:element>
+
   <xs:element name="Hx_NetTest_ArtifactsDir" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>

src/Heleonix.Build/Schemas/Targets/Hx_NetValidate.xsd

@@ -30,6 +30,16 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Hx_NetValidate" type="xs:string">
+    <xs:annotation>
+      <xs:documentation>
+        This target verifies that every file satisfies all the regular expressions specified in its metadata.
+        This is useful to verify that projects reference specific packages,
+        or projects contain specific MSBuild properties, or any custom file contains required content.
+      </xs:documentation>
+    </xs:annotation>
+  </xs:element>
+
   <xs:element name="Hx_NetValidate_RegExpOptions" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>Regular expression options to use when executing validation for each @Hx_NetValidate_Files.</xs:documentation>
@@ -39,7 +49,7 @@ Example custom property that allows string content only
   <xs:element name="Hx_NetValidate_Files" type="msb:GenericItemType" substitutionGroup="msb:Item">
     <xs:annotation>
       <xs:documentation>
-        The list of files with regular expressions defined as metadata to validate.
+        The list of files with regular expressions defined as metadata (metadata keys can be named in a free form) to validate.
         Defaults are project files, which must have the following packages:
         codecracker.CSharp, Microsoft.CodeAnalysis.NetAnalyzers, SecurityCodeScan.VS2019, SonarAnalyzer.CSharp, StyleCop.Analyzers.
       </xs:documentation>

src/Heleonix.Build/Schemas/Targets/Hx_Release_GitHub.xsd

@@ -30,6 +30,14 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Hx_Release_GitHub" type="xs:string">
+    <xs:annotation>
+      <xs:documentation>
+        Creates a release on GitHub using GitHub API. For example: https://github.com/Heleonix/Heleonix.Build/releases.
+      </xs:documentation>
+    </xs:annotation>
+  </xs:element>
+
   <xs:element name="Hx_Release_GitHub_Token" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>A GitHub access token to authorize to the GitHub Releases API.</xs:documentation>

src/Heleonix.Build/Schemas/Targets/Hx_ReportGenerator.xsd

@@ -30,6 +30,14 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Hx_ReportGenerator" type="xs:string">
+    <xs:annotation>
+      <xs:documentation>
+        This target runs https://www.nuget.org/packages/dotnet-reportgenerator-globaltool against coverage results files.
+      </xs:documentation>
+    </xs:annotation>
+  </xs:element>
+
   <xs:element name="Hx_ReportGenerator_ArtifactsDir" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>A path to the ReportGenerator artifacts directory. Default is '$Hx_Run_ArtifactsDir/ReportGenerator'.</xs:documentation>

src/Heleonix.Build/Schemas/Targets/Hx_TrxReport.xsd

@@ -30,6 +30,14 @@ Example custom property that allows string content only
            elementFormDefault="qualified"
            targetNamespace="http://schemas.microsoft.com/developer/msbuild/2003"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:element name="Hx_TrxReport" type="xs:string">
+    <xs:annotation>
+      <xs:documentation>
+        This target is not implemented yet, but the idea is to generate HTML test reports from the *.trx files.
+      </xs:documentation>
+    </xs:annotation>
+  </xs:element>
+
   <xs:element name="Hx_TrxReport_ArtifactsDir" type="msb:StringPropertyType" substitutionGroup="msb:Property">
     <xs:annotation>
       <xs:documentation>A path to the TrxReport artifacts directory. Default is '$Hx_Run_ArtifactsDir/TrxReport'</xs:documentation>

test/Heleonix.Build.Tests.ExeMock/Heleonix.Build.Tests.ExeMock.csproj

@@ -8,10 +8,10 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="7.0.3" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
+    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="8.0.0" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
     <PackageReference Include="codecracker.CSharp" Version="1.1.0" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers" />
     <PackageReference Include="SecurityCodeScan.VS2019" Version="5.6.7" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
-    <PackageReference Include="SonarAnalyzer.CSharp" Version="8.54.0.64047" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers" />
+    <PackageReference Include="SonarAnalyzer.CSharp" Version="9.23.0.88079" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers" />
     <PackageReference Include="StyleCop.Analyzers" Version="1.1.118" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers" />
   </ItemGroup>
 </Project>

test/Heleonix.Build.Tests.ExeMock/Program.cs

@@ -3,7 +3,7 @@
 // Licensed under the MIT license. See LICENSE file in the repository root for full license information.
 // </copyright>
 
-if (args.Any(a => a.Contains("ERROR")))
+if (Array.Exists(args, a => a.Contains("ERROR")))
 {
     Console.Error.Write("ERROR details");