Siemens.AspNet.CodeRules.Engine 7.7.4

Siemens.AspNet.CodeRules.Engine

Parse the solution once. Run every rule against it. Report findings a human and an AI agent can act on.

The code rule engine behind all hosts. It registers your rules with the usual IServiceCollection API, creates every analysis context once (the solution is parsed a single time, also across several projects), runs the rules in parallel and returns results with findings, skips and errors. It also contains ICodeRuleSetup, the composition root of a code rule test project, and RuleTester<TRule>, the unit test helper for single rules.

Most consumers never reference it directly: the test adapters (Siemens.AspNet.CodeRules.MSTest, .XUnit, .NUnit) and the coderules CLI bring it. Reference it yourself when you write rule tests or your own host.

services.AddCodeRuleEngine("My.slnx", o => o.AddRulePack<NamingRulePack>()
                                           .AddRulesFrom(typeof(MyLocalRule).Assembly)
                                           .UseDocumentationUrlTemplate("https://example.com/rules#{Id}"));

Installation

dotnet add package Siemens.AspNet.CodeRules.Engine

Rules themselves only need Siemens.AspNet.CodeRules.Contracts.

ICodeRuleSetup: one setup for every host

A code rule test project has no Program.cs, so it has exactly one class that implements ICodeRuleSetup:

public sealed class CodeRuleSetup : ICodeRuleSetup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddCodeRuleEngine("My.slnx", o => o.AddRulePack<NamingRulePack>());
    }
}

It is the single source for all hosts:

• the source generators of the test adapters read it at build time and write one test per registered rule,
• the test adapters call it at test time and run the rule of each test,
• the CLI (coderules run) loads it from the built project and runs it natively.

So dotnet test and coderules always run the same rules with the same result.

Registering rules

AddCodeRuleEngine(solution, configure) registers the rules, the catalog, the context cache and ICodeRuleEngine as singletons. solution is a file name or path (e.g. My.slnx), searched from the running assembly upwards.

All options combine, in any order; registering the same rule twice is harmless. The generators understand AddRule<TRule>(), Add<TRule>(), AddRulePack<TPack>() and AddRulesFrom(typeof(X).Assembly).

Own contexts with one public constructor that takes other contexts (e.g. ControllerContext(CodeContext code)) need no registration: the engine creates them once per run.

Accepting a single finding in the code

A skip in the setup is for whole rules, packs, groups, tags or scopes. A single finding is accepted where it is, the same way as an analyzer finding, always with a reason:

[SuppressMessage("CodeRules", "NAMING_001", Justification = "Name is part of the public contract of v1")]
public sealed class LegacyOrderManager { /* ... */ }

#pragma warning disable NAMING_001 // Generated by the legacy importer, removed with #1234
public sealed class ImportManager { /* ... */ }
#pragma warning restore NAMING_001

• [SuppressMessage] counts on every declaration that contains the finding line (member, accessor, parameter, type, outer type). The category is free, the check ID is the rule ID ("NAMING_001:Title" works too).
• #pragma warning disable <ID> counts from the next line up to the matching restore (or the end of the file). A pragma without an ID is ignored.
• Without a reason it does not count: no Justification, or no // comment after the pragma, keeps the finding and says why. The same happens for rules with AllowSuppression => false.
• Accepted findings do not fail the rule; they are listed as Suppressed in the result and in both outputs, so they stay visible. Only findings with a line in a C# file can be accepted this way.

Output mode: human or AI

Every host can write its output for people (Human, the default) or as JSON for AI agents (Ai, the same schema in every host). How you switch depends on the host:

In the setup: the default of the project

public sealed class CodeRuleSetup : ICodeRuleSetup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddCodeRuleEngine("My.slnx", o => o.AddRulePack<NamingRulePack>()
                                                   .UseOutputMode(CodeRuleOutputMode.Ai));
    }
}

Good when the project is mostly run by an AI agent: every dotnet test writes the JSON, without any setup on the machine.

With an environment variable: per machine, CI or agent

$env:CodeRuleSettings__OutputMode = "ai"     # PowerShell

export CodeRuleSettings__OutputMode=ai       # bash

TestSdkSettings__OutputMode=ai (the variable of AspNetCore.Simple.MsTest.Sdk) also works and switches API tests and code rules together. Without a shell, put the variable in a .runsettings file of the test project:

<RunSettings>
  <RunConfiguration>
    <EnvironmentVariables>
      <CodeRuleSettings__OutputMode>ai</CodeRuleSettings__OutputMode>
    </EnvironmentVariables>
  </RunConfiguration>
</RunSettings>

Which one wins

1. CodeRuleSettings__OutputMode, if set to ai or human,
2. otherwise TestSdkSettings__OutputMode, if set to ai or human,
3. otherwise UseOutputMode(...) of the setup,
4. otherwise Human.

So the environment always overrides the setup: a project with UseOutputMode(CodeRuleOutputMode.Ai) still shows the human output with CodeRuleSettings__OutputMode=human. Other values, such as the SDK's hybrid, leave the decision to the setup. The mode is resolved once per test run, after the setup ran, so Environment.SetEnvironmentVariable inside ConfigureServices has no effect: use UseOutputMode(...) there.

The CLI has its own --format option because one call can run several code rule projects with different setups.

Your own host

var services = new ServiceCollection();
services.AddCodeRuleEngine("My.slnx", o => o.AddRulePack<NamingRulePack>());

await using var provider = services.BuildServiceProvider();
var engine = provider.GetRequiredService<ICodeRuleEngine>();

var run = await engine.RunAllAsync(cancellationToken);                        // every rule
var naming = await engine.RunAsync(RuleFilter.Tag("Naming"), cancellationToken); // a selection
var single = await engine.RunAsync("NAMING_001", cancellationToken);           // exactly one rule

run.EnsureSuccess();   // throws with a readable report when a rule failed or could not run

Output

• RuleResultFormatter.Format(results): the human report.
• AiResultFormatter.Format(results, rerun): the JSON schema shared by all hosts (test adapters and CLI), including the instructions for AI agents ("fix the code, not the rule") and, with the optional rerun callback, the command that checks a fix per result.
• RepositoryPath: repository relative, clickable path:line:column locations.
• The test adapters switch with UseOutputMode(...) in the setup or CodeRuleSettings__OutputMode=ai, see Output mode; CodeRuleOutput.Resolve(configured) applies the same order in your own host.

Testing a rule: RuleTester<TRule>

Every rule deserves its own unit tests. RuleTester<TRule> (namespace Siemens.AspNet.CodeRules.Engine) runs one rule against inline code. No solution is parsed and every test gets its own engine, so the tests run in parallel. It works with any test framework: a failure is a RuleTestException with a readable message.

[TestClass]
public sealed class RecordPropertiesMustBeImmutable_Tests(TestContext testContext)
{
    private readonly RuleTester<RecordPropertiesMustBeImmutable> _rule = new();

    [TestMethod]
    public async Task Should_Report_Finding_When_Record_Property_Has_A_Setter()
    {
        // The rule must report exactly the code marked with [| ... |].
        await _rule.ViolatesAsync("""
                                  public record Order(int Id)
                                  {
                                      [|public string Status { get; set; } = "";|]
                                  }
                                  """, testContext.CancellationToken);
    }

    [TestMethod]
    public async Task Should_Report_No_Finding_When_Record_Property_Is_Immutable()
    {
        await _rule.CompliesAsync("""
                                  public record Order(int Id)
                                  {
                                      public string Status { get; init; } = "";
                                  }
                                  """, testContext.CancellationToken);
    }

    [TestMethod]
    public async Task Should_Suggest_An_Init_Accessor()
    {
        var finding = await _rule.ViolatesOnceAsync("""
                                                    public record Order(int Id)
                                                    {
                                                        [|public string Status { get; set; } = "";|]
                                                    }
                                                    """, testContext.CancellationToken);

        Assert.AreEqual("public string Status { get; init; } = \"\";", finding.ShouldBe);
    }
}

Every method also takes several files: TestFile.Production("Order.cs", code) and TestFile.Test("OrderTests.cs", code) fill ProductionTrees and TestTrees. new RuleTester<TRule>(o => ...) adds own contexts (AddContext, AddContextProvider) or services (ConfigureServices).

License

Copyright (c) Siemens AG. See LICENSE.md in the package.