From fa553fd72ed852a85ced6e0999dd96ff9a73b7f1 Mon Sep 17 00:00:00 2001 From: Phil Scott Date: Thu, 24 Jun 2021 23:28:42 -0400 Subject: [PATCH] Adds documentation for analyzers --- docs/input/analyzer/rules/RULE_TEMPLATE.md | 38 +++++++++++++ docs/input/analyzer/rules/Spectre1021.md | 56 ++++++++++++++++++ docs/input/analyzer/rules/_ViewStart.cshtml | 3 + docs/input/analyzer/rules/_layout.cshtml | 10 ++++ docs/input/analyzer/rules/index.cshtml | 31 ++++++++++ docs/input/analyzer/rules/spectre1000.md | 27 +++++++++ docs/input/analyzer/rules/spectre1010.md | 63 +++++++++++++++++++++ docs/input/analyzer/rules/spectre1020.md | 46 +++++++++++++++ src/Spectre.Console.Analyzer/Descriptors.cs | 12 +++- 9 files changed, 284 insertions(+), 2 deletions(-) create mode 100644 docs/input/analyzer/rules/RULE_TEMPLATE.md create mode 100644 docs/input/analyzer/rules/Spectre1021.md create mode 100644 docs/input/analyzer/rules/_ViewStart.cshtml create mode 100644 docs/input/analyzer/rules/_layout.cshtml create mode 100644 docs/input/analyzer/rules/index.cshtml create mode 100644 docs/input/analyzer/rules/spectre1000.md create mode 100644 docs/input/analyzer/rules/spectre1010.md create mode 100644 docs/input/analyzer/rules/spectre1020.md diff --git a/docs/input/analyzer/rules/RULE_TEMPLATE.md b/docs/input/analyzer/rules/RULE_TEMPLATE.md new file mode 100644 index 0000000..407a13f --- /dev/null +++ b/docs/input/analyzer/rules/RULE_TEMPLATE.md @@ -0,0 +1,38 @@ +--- +Title: SpectreXxxx +Description: Rule title +Category: Usage +Severity: Hidden, Info, Warning, or Error +Excluded: true +--- + +## Cause + +A concise-as-possible description of when this rule is violated. If there's a lot to explain, begin with "A violation of this rule occurs when..." + +## Reason for rule + +Explain why the user should care about the violation. + +## How to fix violations + +To fix a violation of this rule, [describe how to fix a violation]. + +## Examples + +### Violates + +Example(s) of code that violates the rule. + +### Does not violate + +Example(s) of code that does not violate the rule. + +## How to suppress violations + +**If the severity of your analyzer isn't _Warning_, delete this section.** + +```csharp +#pragma warning disable Spectre1000 // +#pragma warning restore Spectre1000 // +``` \ No newline at end of file diff --git a/docs/input/analyzer/rules/Spectre1021.md b/docs/input/analyzer/rules/Spectre1021.md new file mode 100644 index 0000000..78584d2 --- /dev/null +++ b/docs/input/analyzer/rules/Spectre1021.md @@ -0,0 +1,56 @@ +--- +Title: Spectre1021 +Description: Avoid prompting for input while a current renderable is running. +Category: Usage +Severity: Warning +--- + +## Cause + +A violation of this rule occurs when a AnsiConsole prompt is called within the context of an executing renderable e.g. `Progress`, `Status` and `Live`. Concurrent LiveRenderable are not supported and will cause issues when running simultaneously. + +## Reason for rule + +When LiveRenderable such as `Progress`, `Status` or `Live` are running they expect to be running exclusively. They rely on ANSI sequences to draw and keep the console experience consistent. Prompts also rely on ANSI sequences for their drawing. Simultaneous running can result in corrupt output. + +## How to fix violations + +Redesign logic to allow one LiveRenderable to complete before using a prompt or prompt before starting the operation. + +## Examples + +### Violates + +```csharp +AnsiConsole.Progress().Start(ctx => +{ + // code to update progress bar + var answer = AnsiConsole.Confirm("Continue?"); +}); +``` + +### Does not violate + +```csharp +AnsiConsole.Progress().Start(ctx => +{ + // code to update progress bar + + // persist state to restart progress after asking question +}); + +var answer = AnsiConsole.Confirm("Continue?"); + +AnsiConsole.Progress().Start(ctx => +{ + // apply persisted state + // code to update progress bar +``` + +## How to suppress violations + +```csharp +#pragma warning disable Spectre1021 // + +#pragma warning restore Spectre1021 // +``` diff --git a/docs/input/analyzer/rules/_ViewStart.cshtml b/docs/input/analyzer/rules/_ViewStart.cshtml new file mode 100644 index 0000000..f0b09c8 --- /dev/null +++ b/docs/input/analyzer/rules/_ViewStart.cshtml @@ -0,0 +1,3 @@ +@{ + Layout = @"_layout.cshtml"; +} \ No newline at end of file diff --git a/docs/input/analyzer/rules/_layout.cshtml b/docs/input/analyzer/rules/_layout.cshtml new file mode 100644 index 0000000..e5ab11c --- /dev/null +++ b/docs/input/analyzer/rules/_layout.cshtml @@ -0,0 +1,10 @@ +@inherits StatiqRazorPage + +@{ + Layout = @"/_layout.cshtml"; +} + + +

@Document.GetString("Description")

+ +@RenderBody() \ No newline at end of file diff --git a/docs/input/analyzer/rules/index.cshtml b/docs/input/analyzer/rules/index.cshtml new file mode 100644 index 0000000..a566904 --- /dev/null +++ b/docs/input/analyzer/rules/index.cshtml @@ -0,0 +1,31 @@ +Title: Roslyn Analyzers +Order: 20 +--- + +Spectre.Console.Analyzer provides analyzers for common mistakes when using Spectre.Console. It can be installed via nuget + +
nuget install Spectre.Console.Analyzer
+ +

Supported Analyzers

+ + + + + + + + + + + + @foreach (IDocument child in OutputPages.GetChildrenOf(Document)) + { + + + + + + + } + +
AnalyzerDescriptionCategorySeverity
@Html.DocumentLink(child)@child.GetString("Description")@child.GetString("Category") @child.GetString("Severity")
\ No newline at end of file diff --git a/docs/input/analyzer/rules/spectre1000.md b/docs/input/analyzer/rules/spectre1000.md new file mode 100644 index 0000000..f3611b4 --- /dev/null +++ b/docs/input/analyzer/rules/spectre1000.md @@ -0,0 +1,27 @@ +--- +Title: Spectre1000 +Description: Use AnsiConsole instead of System.Console +Category: Usage +Severity: Warning +--- + +## Cause + +A violation of this rule occurs when `System.Console` is used for common methods exposed by Spectre.Console. + +## Reason for rule + +Methods implemented in Spectre.Console should be used over direct access to `System.Console` to allow for enhancements and +features to be enabled. + +## How to fix violations + +To fix a violation of this rule, change from `System.Console` to `Spectre.Console.AnsiConsole`. + +## How to suppress violations + +```csharp +#pragma warning disable Spectre1000 // Use AnsiConsole instead of System.Console + +#pragma warning restore Spectre1000 // Use AnsiConsole instead of System.Console +``` diff --git a/docs/input/analyzer/rules/spectre1010.md b/docs/input/analyzer/rules/spectre1010.md new file mode 100644 index 0000000..ad4036f --- /dev/null +++ b/docs/input/analyzer/rules/spectre1010.md @@ -0,0 +1,63 @@ +--- +Title: Spectre1010 +Description: Favor the use of the instance of AnsiConsole over the static helper +Category: Usage +Severity: Info +--- + +## Cause + +A violation of this rule occurs when the static helper `AnsiConsole` is used when a field or method parameter of type +`IAnsiConsole` is available. + +## Reason for rule + +Use of `IAnsiConsole` improves testability of the code, and also allows upstream callers the ability to customize the console +capabilities and features. When a field variable or parameter is available it should be used to ensure the code takes advantage +of that configuration. + +## How to fix violations + +To fix a violation of this rule, change from `AnsiConsole` to the name of the local instance. + +## Examples + +### Violates + +```csharp +class Example +{ + private IAnsiConsole _ansiConsole; + + public Example(IAnsiConsole ansiConsole) + { + _ansiConsole = ansiConsole; + } + + public Run() + { + AnsiConsole.WriteLine("Running..."); + } + +} +``` + +### Does not violate + +```csharp +class Example +{ + private IAnsiConsole _ansiConsole; + + public Example(IAnsiConsole ansiConsole) + { + _ansiConsole = ansiConsole; + } + + public Run() + { + _ansiConsole.WriteLine("Running..."); + } + +} +``` diff --git a/docs/input/analyzer/rules/spectre1020.md b/docs/input/analyzer/rules/spectre1020.md new file mode 100644 index 0000000..7f41b39 --- /dev/null +++ b/docs/input/analyzer/rules/spectre1020.md @@ -0,0 +1,46 @@ +--- +Title: Spectre1020 +Description: Avoid calling other live renderables while a current renderable is running. +Category: Usage +Severity: Warning +--- + +## Cause + +A violation of this rule occurs when a child LiveRenderable i.e. `Progress`, `Status` and `Live` are called within the context of an executing renderable. Concurrent LiveRenderable are not supported and will cause issues when running simultaneously. + +## Reason for rule + +When LiveRenderable such as `Progress`, `Status` or `Live` are running they expect to be running exclusively. They rely on ANSI sequences to draw and keep the console experience consistent. With simultaneous calls both renderables compete with the console causing concurrent writes corrupting the output. + +## How to fix violations + +Redesign logic to allow one LiveRenderable to complete before starting a second renderable. + +## Examples + +### Violates + +```csharp +AnsiConsole.Progress().Start(ctx => { + AnsiConsole.Status().Start("Running status too...", statusCtx => {}); +}); +``` + +### Does not violate + +```csharp +AnsiConsole.Progress().Start(ctx => { + // run progress and complete tasks +}); + +AnsiConsole.Status().Start("Running status afterwards...", statusCtx => {}); +``` + +## How to suppress violations + +```csharp +#pragma warning disable Spectre1020 // + +#pragma warning restore Spectre1020 // +``` diff --git a/src/Spectre.Console.Analyzer/Descriptors.cs b/src/Spectre.Console.Analyzer/Descriptors.cs index 8eb76fc..4cdccda 100644 --- a/src/Spectre.Console.Analyzer/Descriptors.cs +++ b/src/Spectre.Console.Analyzer/Descriptors.cs @@ -19,9 +19,17 @@ namespace Spectre.Console.Analyzer private static DiagnosticDescriptor Rule(string id, string title, Category category, DiagnosticSeverity defaultSeverity, string messageFormat, string? description = null) { - var helpLink = $"https://spectreconsole.net/spectre.console.analyzers/rules/{id}"; + var helpLink = $"https://spectreconsole.net/analyzer/rules/{id.ToLowerInvariant()}"; const bool IsEnabledByDefault = true; - return new DiagnosticDescriptor(id, title, messageFormat, _categoryMapping.GetOrAdd(category, c => c.ToString()), defaultSeverity, IsEnabledByDefault, description, helpLink); + return new DiagnosticDescriptor( + id, + title, + messageFormat, + _categoryMapping.GetOrAdd(category, c => c.ToString()), + defaultSeverity, + IsEnabledByDefault, + description, + helpLink); } ///