(GH-5) added warning CCG0005 for not referencing StyleCop.Analyzers

docs/input/guidelines/Analysers.md

@@ -0,0 +1,42 @@
+---
+Order: 3
+Title: Recommended References
+---
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Goals](#goals)
+- [Related rules](#related-rules)
+- [Usage](#usage)
+- [Settings](#settings)
+  - [Opt-Out](#opt-out)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Goals
+
+To have consistency in code-style among the different tools/plugins the use of Analysers is recommended, especially the use of [StyleCop](https://github.com/DotNetAnalyzers/StyleCopAnalyzers).
+
+## Related rules
+
+ * [CCG0005](../rules/ccg0005)
+
+## Usage
+
+Using this package automatically enables this guideline.
+
+## Settings
+
+### Opt-Out
+
+It it possible to opt-out of the check for StyleCop using the following setting:
+
+(*Keep in mind, though that it is not recommended to opt-out of this feature*)
+
+```xml
+<ItemGroup>
+    <CakeContribGuidelinesOmitRecommendedReference Include="StyleCop.Analyzers" />
+</ItemGroup>
+```

docs/input/rules/ccg0005.md

@@ -0,0 +1,35 @@
+---
+Order: 5
+Title: CCG0005
+Description: Usage of analysers is recommended
+---
+
+ > No reference to `StyleCop.Analyzers` found. Usage of `StyleCop.Analyzers` is strongly recommended.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Cause](#cause)
+- [Description](#description)
+- [How to fix violations](#how-to-fix-violations)
+- [Related guidelines](#related-guidelines)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Cause
+
+This warning is raised, when the recommended analyser [StyleCop](https://github.com/DotNetAnalyzers/StyleCopAnalyzers) is not referenced.
+
+## Description
+
+Usage of [StyleCop](https://github.com/DotNetAnalyzers/StyleCopAnalyzers) is recommended.
+
+## How to fix violations
+
+Add a reference to [StyleCop](https://github.com/DotNetAnalyzers/StyleCopAnalyzers).
+(Or opt-out of this rule, by setting `CakeContribGuidelinesOmitRecommendedReference`)
+
+## Related guidelines
+
+* [Usage of Analysers](../guidelines/Analysers)

e2e-tests/CCG0001/Default/Default.csproj

@@ -5,7 +5,10 @@
     </PropertyGroup>
 
     <ItemGroup>
-      <ProjectReference Include="..\..\CCG0002\Warning\CCG0002_Warning.csproj" />
+      <PackageReference Include="StyleCop.Analyzers" Version="1.1.118">
+        <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        <PrivateAssets>all</PrivateAssets>
+      </PackageReference>
     </ItemGroup>
 
 </Project>

e2e-tests/CCG0002/Default/Default.csproj

@@ -5,4 +5,11 @@
         <PackageIcon>$(CakeContribGuidelinesIconDestinationLocation)</PackageIcon>
     </PropertyGroup>
 
+    <ItemGroup>
+      <PackageReference Include="StyleCop.Analyzers" Version="1.1.118">
+        <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        <PrivateAssets>all</PrivateAssets>
+      </PackageReference>
+    </ItemGroup>
+
 </Project>

e2e-tests/CCG0003/Default/Default.csproj

@@ -6,4 +6,11 @@
         <PackageIconUrl>https://project/path/to/icon</PackageIconUrl>
     </PropertyGroup>
 
+    <ItemGroup>
+      <PackageReference Include="StyleCop.Analyzers" Version="1.1.118">
+        <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        <PrivateAssets>all</PrivateAssets>
+      </PackageReference>
+    </ItemGroup>
+
 </Project>

e2e-tests/CCG0003/ModifiedPath/ModifiedPath.csproj

@@ -7,4 +7,10 @@
         <PackageIconUrl>https://project/path/to/icon</PackageIconUrl>
     </PropertyGroup>
 
+    <ItemGroup>
+      <PackageReference Include="StyleCop.Analyzers" Version="1.1.118">
+        <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        <PrivateAssets>all</PrivateAssets>
+      </PackageReference>
+    </ItemGroup>
 </Project>

e2e-tests/CCG0004/Default/Default.csproj

@@ -8,6 +8,10 @@
 
     <ItemGroup>
       <PackageReference Include="Cake.Core" Version="0.38.5" PrivateAssets="all" />
+      <PackageReference Include="StyleCop.Analyzers" Version="1.1.118">
+        <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        <PrivateAssets>all</PrivateAssets>
+      </PackageReference>
     </ItemGroup>
 
 </Project>

e2e-tests/CCG0004/NoPrivateAssets/NoPrivateAssets.csproj

@@ -8,6 +8,10 @@
 
     <ItemGroup>
       <PackageReference Include="Cake.Core" Version="0.38.5" />
+      <PackageReference Include="StyleCop.Analyzers" Version="1.1.118">
+        <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        <PrivateAssets>all</PrivateAssets>
+      </PackageReference>
     </ItemGroup>
 
 </Project>

e2e-tests/CCG0005/Default/Default.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>netstandard2.0</TargetFramework>
+        <PackageIcon>$(CakeContribGuidelinesIconDestinationLocation)</PackageIcon>
+        <PackageIconUrl>https://project/path/to/icon</PackageIconUrl>
+    </PropertyGroup>
+
+</Project>

e2e-tests/CCG0005/Default/spec.json

@@ -0,0 +1,6 @@
+{
+    "description": "not referencing StyleCop.Analyzers yields a warning",
+    "exitCode": 0,
+    "errors": [],
+    "warnings": [ "CCG0005" ]
+}

e2e-tests/CCG0005/OmittingStyleCop/OmittingStyleCop.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>netstandard2.0</TargetFramework>
+        <PackageIcon>$(CakeContribGuidelinesIconDestinationLocation)</PackageIcon>
+        <PackageIconUrl>https://project/path/to/icon</PackageIconUrl>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <CakeContribGuidelinesOmitRecommendedReference Include="StyleCop.Analyzers" />
+    </ItemGroup>
+</Project>

e2e-tests/CCG0005/OmittingStyleCop/spec.json

@@ -0,0 +1,6 @@
+{
+    "description": "omitting StyleCop.Analyzers yields no warning",
+    "exitCode": 0,
+    "errors": [],
+    "warnings": [ ]
+}

src/Guidelines/build/CakeContrib.Guidelines.targets

@@ -1,10 +1,11 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- 
+<!--
   This file is automatically imported by NuGet into a user's project
   when it targets a single framework, or in classic (pre 2017) csproj projects.
   See https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package#include-msbuild-props-and-targets-in-a-package
 -->
 <Project ToolsVersion="14.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
     <Import Project="$(MSBuildThisFileDirectory)Icon.targets" />
-    <Import Project="$(MSBuildThisFileDirectory)CakeReference.targets" />
-</Project>
+    <Import Project="$(MSBuildThisFileDirectory)PrivateAssets.targets" />
+    <Import Project="$(MSBuildThisFileDirectory)RequiredReferences.targets" />
+</Project>

src/Guidelines/build/CakeReference.targets → src/Guidelines/build/PrivateAssets.targets

@@ -1,12 +1,12 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project ToolsVersion="14.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
 
-    <UsingTask 
-        TaskName="$(CakeContribGuidelinesCustomTasksNamespace).CheckPrivateAssetsOnReferences" 
-        AssemblyFile="$(CakeContribGuidelinesCustomTasksAssembly)"/>
+    <UsingTask
+        TaskName="$(CakeContribGuidelinesCustomTasksNamespace).CheckPrivateAssetsOnReferences"
+        AssemblyFile="$(CakeContribGuidelinesCustomTasksAssembly)" />
 
     <Target
-        Name="_CheckCakeReferenceIsPrivateIterator"
+        Name="_CheckPrivateAssets"
         AfterTargets="BeforeBuild"
         BeforeTargets="CoreBuild">
         <ItemGroup>
@@ -22,5 +22,4 @@
             References="@(PackageReference)"
             ProjectFile="$(MSBuildProjectFullPath)" />
     </Target>
-
 </Project>

src/Guidelines/build/RequiredReferences.targets

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project ToolsVersion="14.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+
+    <UsingTask
+        TaskName="$(CakeContribGuidelinesCustomTasksNamespace).RequiredReferences"
+        AssemblyFile="$(CakeContribGuidelinesCustomTasksAssembly)" />
+
+    <Target
+        Name="_CheckRequiredReferences"
+        AfterTargets="BeforeBuild"
+        BeforeTargets="CoreBuild">
+        <ItemGroup>
+            <CakeContribGuidelinesRequiredReference Include="StyleCop.Analyzers" />
+        </ItemGroup>
+
+        <RequiredReferences
+            Required="@(CakeContribGuidelinesRequiredReference)"
+            Omitted="@(CakeContribGuidelinesOmitRecommendedReference)"
+            References="@(PackageReference)"
+            ProjectFile="$(MSBuildProjectFullPath)" />
+    </Target>
+</Project>

src/Tasks.Tests/Fixtures/BaseBuildFixture.cs

@@ -0,0 +1,26 @@
+using Microsoft.Build.Utilities;
+
+namespace CakeContrib.Guidelines.Tasks.Tests.Fixtures
+{
+    public class BaseBuildFixture<T>
+        where T : Task, new()
+    {
+        public MockBuildEngine BuildEngine { get; }
+
+        protected T Task { get; }
+
+        public BaseBuildFixture()
+        {
+            BuildEngine = new MockBuildEngine();
+            Task = new T
+            {
+                BuildEngine = BuildEngine
+            };
+        }
+
+        public virtual bool Execute()
+        {
+            return Task.Execute();
+        }
+    }
+}

src/Tasks.Tests/Fixtures/CheckPrivateAssetsOnReferencesFixture.cs

@@ -6,35 +6,22 @@
 
 namespace CakeContrib.Guidelines.Tasks.Tests.Fixtures
 {
-    public class CheckPrivateAssetsOnReferencesFixture
+    public class CheckPrivateAssetsOnReferencesFixture : BaseBuildFixture<CheckPrivateAssetsOnReferences>
     {
-        public MockBuildEngine BuildEngine { get; }
-
-        private readonly CheckPrivateAssetsOnReferences task;
-        private readonly List<ITaskItem> references;
         private readonly List<ITaskItem> packagesToCheck;
+        private readonly List<ITaskItem> references;
 
         public CheckPrivateAssetsOnReferencesFixture()
         {
-            BuildEngine = new MockBuildEngine();
-            task = new CheckPrivateAssetsOnReferences
-            {
-                BuildEngine = BuildEngine
-            };
-            packagesToCheck = new List<ITaskItem>();
             references = new List<ITaskItem>();
+            packagesToCheck = new List<ITaskItem>();
         }
 
-        public bool Execute()
-        {
-            task.References = references.ToArray();
-            task.PackagesToCheck = packagesToCheck.ToArray();
-            return task.Execute();
-        }
-
-        public void WithProjectFile(string fileName)
+        public override bool Execute()
         {
-            task.ProjectFile = fileName;
+            Task.References = references.ToArray();
+            Task.PackagesToCheck = packagesToCheck.ToArray();
+            return base.Execute();
         }
 
         public void WithPackageToCheck(string packageName)
@@ -44,6 +31,11 @@ public void WithPackageToCheck(string packageName)
             packagesToCheck.Add(packageToCheck.Object);
         }
 
+        public void WithProjectFile(string fileName)
+        {
+            Task.ProjectFile = fileName;
+        }
+
         public void WithReferencedPackage(string packageName, string privateAssets = "")
         {
             var referencedPackage = new Mock<ITaskItem>();

src/Tasks.Tests/Fixtures/RequiredReferencesFixture.cs

@@ -0,0 +1,57 @@
+using System.Collections.Generic;
+
+using Microsoft.Build.Framework;
+
+using Moq;
+
+namespace CakeContrib.Guidelines.Tasks.Tests.Fixtures
+{
+    public class RequiredReferencesFixture : BaseBuildFixture<RequiredReferences>
+    {
+        private readonly List<ITaskItem> requiredReferences;
+        private readonly List<ITaskItem> omittedReferences;
+        private readonly List<ITaskItem> references;
+
+        public RequiredReferencesFixture()
+        {
+            references = new List<ITaskItem>();
+            requiredReferences = new List<ITaskItem>();
+            omittedReferences = new List<ITaskItem>();
+        }
+
+        public override bool Execute()
+        {
+            Task.References = references.ToArray();
+            Task.Required = requiredReferences.ToArray();
+            Task.Omitted = omittedReferences.ToArray();
+            return base.Execute();
+        }
+
+        public void WithRequiredReferences(string packageName)
+        {
+            var reference = new Mock<ITaskItem>();
+            reference.Setup(x => x.ToString()).Returns(packageName);
+            requiredReferences.Add(reference.Object);
+        }
+
+        public void WithOmittedReferences(string packageName)
+        {
+            var reference = new Mock<ITaskItem>();
+            reference.Setup(x => x.ToString()).Returns(packageName);
+            omittedReferences.Add(reference.Object);
+        }
+
+        public void WithProjectFile(string fileName)
+        {
+            Task.ProjectFile = fileName;
+        }
+
+        public void WithReferencedPackage(string packageName, string privateAssets = "")
+        {
+            var referencedPackage = new Mock<ITaskItem>();
+            referencedPackage.Setup(x => x.ToString()).Returns(packageName);
+            referencedPackage.Setup(x => x.GetMetadata("PrivateAssets")).Returns(privateAssets);
+            references.Add(referencedPackage.Object);
+        }
+    }
+}