moq-analyzers-config-and-flags

moq.analyzers configuration and flags catalog

Every knob in this repo, what it defaults to, who may change it, and what catches a bad change. This repo ships a Roslyn analyzer (a plugin that runs inside consumers' compilers and IDEs), so several "configuration" entries are actually load-bearing safety pins — changing them can crash customer builds.

All file paths are repo-root relative. All quotes verified against the working tree on 2026-07-02 (commit 05135b2).

Change control baseline: CODEOWNERS is * @rjmurillo — every file below is owner-reviewed. Nothing here documents a way around that; see moq-analyzers-change-control before touching any axis marked LOAD-BEARING.

Axis map (read this first)

#	Axis	File(s)	Blast radius if wrong
1	MSBuild properties	build/targets/*/*.props, build/targets/codeanalysis/CodeAnalysis.targets, Directory.Build.props/.targets	Local build passes, CI fails (or vice versa)
2	Analyzer severity layers	.editorconfig (root + 3 nested), build/targets/codeanalysis/.globalconfig, stylecop.json, GlobalSuppressions.cs	Warnings silently vanish, or CI self-locks
3	Banned APIs	src/BannedSymbols.txt	Wrong Roslyn API patterns re-enter the codebase
4	Test run settings	build/targets/tests/test.runsettings, Tests.targets, xunit.runner.json	Coverage numbers lie; tests serialize
5	CI/env variables	.github/workflows/main.yml, build/scripts/hooks/Invoke-PrePushBuild.ps1, build/scripts/perf/PerfCore.ps1	Perf gate runs wrong suite; pre-push breaks
6	Renovate rules	renovate.json	CS8032 crash ships to customers (LOAD-BEARING)
7	Perf baseline	build/perf/baseline.json	Perf gate compares against wrong commit
8	Versioning	version.json, global.json	Wrong package version pushed to nuget.org
9	Pinned CLI tools	.config/dotnet-tools.json	Hooks/CI tool steps fail or drift

---

Axis 1 — MSBuild properties

MSBuild properties are name/value pairs evaluated during dotnet build. This repo centralizes them in build/targets/<area>/{*.props,*.targets} pairs, imported by root Directory.Build.props (props) and Directory.Build.targets (targets), which MSBuild auto-imports into every project.

PedanticMode — the single most important flag

Exact text of build/targets/codeanalysis/CodeAnalysis.targets (entire file, 2026-07-02):

<Project>
  <PropertyGroup Label="Computed properties">
    <PedanticMode Condition=" '$(PedanticMode)' == '' ">$([MSBuild]::ValueOrDefault('$(ContinuousIntegrationBuild)', 'false'))</PedanticMode>
    <TreatWarningsAsErrors>$(PedanticMode)</TreatWarningsAsErrors>
    <MSBuildTreatWarningsAsErrors>$(PedanticMode)</MSBuildTreatWarningsAsErrors>
  </PropertyGroup>
</Project>

Semantics:

• PedanticMode defaults to whatever ContinuousIntegrationBuild is (false when unset). It drives BOTH TreatWarningsAsErrors (C# compiler warnings become errors) and MSBuildTreatWarningsAsErrors (MSBuild-level warnings become errors).
• CI always builds with /p:ContinuousIntegrationBuild=true (see .github/actions/setup-restore-build/action.yml, Build step), so CI is always pedantic. A plain local dotnet build is NOT.
• Consequence: any warning passes locally and fails CI. Always run the CI-parity build before pushing:

dotnet build Moq.Analyzers.sln --configuration Release /p:PedanticMode=true /p:Deterministic=true /p:ContinuousIntegrationBuild=true /p:UseSharedCompilation=false /p:BuildInParallel=false /nodeReuse:false

(That is verbatim the flag set from build/scripts/hooks/Invoke-PrePushBuild.ps1, which the pre-push git hook runs for you.)

Full property table

Property	Value	Set in	Why
PedanticMode	default = $(ContinuousIntegrationBuild), else false	build/targets/codeanalysis/CodeAnalysis.targets:3	Warnings-as-errors switch (above)
TreatWarningsAsErrors / MSBuildTreatWarningsAsErrors	$(PedanticMode)	same file	Escalation
ContinuousIntegrationBuild / Deterministic	not set in repo files; passed as /p: by CI composite action and pre-push hook	.github/actions/setup-restore-build/action.yml, build/scripts/hooks/Invoke-PrePushBuild.ps1	Reproducible builds (DotNet.ReproducibleBuilds 2.0.5, build/targets/reproducible/)
ArtifactsPath	$(RepoRoot)/artifacts	build/targets/artifacts/Artifacts.props	All bin/obj/test/package output lands under artifacts/
ArtifactsTestResultsPath	$(ArtifactsPath)/TestResults	same file	TRX + coverage output root
LangVersion	default	build/targets/compiler/Compiler.props	Deliberately floats with the SDK pinned in global.json. Do NOT hard-pin a C# version; the shipped assembly still compiles against Roslyn 4.8 (ADR-003)
Nullable	enable	same file	Repo-wide nullable reference types
ImplicitUsings	enable	same file	Global usings on
EnableNETAnalyzers	true	build/targets/codeanalysis/CodeAnalysis.props	Built-in CA rules on
EnforceCodeStyleInBuild	true	same file	IDExxxx style rules fail the build (under PedanticMode)
AnalysisMode	preview	same file	Most aggressive built-in analyzer mode, including preview rules
WarningLevel	9999	same file	All current and future compiler warning waves enabled
GenerateDocumentationFile	true	same file	XML docs required (missing-doc warnings become CI errors)
EnforceExtendedAnalyzerRules	true, only for projects Moq.Analyzers and Moq.Analyzers.Test	same file, conditioned on $(MSBuildProjectName)	Opts into analyzer-authoring rules (resolves RS1036); the RS-family rules police analyzer correctness
RepoRoot	$(MSBuildThisFileDirectory)	Directory.Build.props	Used by every other path
ManagePackageVersionsCentrally + CentralPackageTransitivePinningEnabled	true	Directory.Packages.props	Central Package Management (CPM): every package version lives in Directory.Packages.props or an imported build/targets/*/Packages.props; transitive dependencies are pinned too (ADR-005)
HUSKY	env var; 0 skips git-hook install	Directory.Build.targets HuskyInstall target	Hooks auto-install on restore unless CI or HUSKY=0

• Who may change: repo owner via PR. Property changes are infrastructure changes — cite the affected build/targets/ file in the PR.
• Guard: CI-parity build (pre-push hook + main.yml build job). There is no guard that detects loosening (e.g., lowering WarningLevel) other than code review — treat any diff under build/targets/ as high-scrutiny.

The one property trap with an incident behind it (2026-07-02)

Never configure S1135 ("track TODO tags") above suggestion. Under PedanticMode, S1135 = warning turns every TODO comment into a CI error and locks CI against itself (commit 3d4f7ff did this and was reverted the next day by b1439ab; the tripping build error was an issue-linked TODO(#1012) comment — #1012 itself tracks an unrelated enhancement, not this incident; see moq-analyzers-failure-archaeology §4). The current, correct setting is .editorconfig:420 → dotnet_diagnostic.S1135.severity = suggestion. TODO discipline is enforced by a different mechanism entirely (build/scripts/todo-scanner/Scan-TodoComments.ps1, pre-push).

---

Axis 2 — Analyzer severity configuration (the precedence story)

"Severity" is how loudly a diagnostic (e.g. CA1016, SA1101, Moq1200) reports: error > warning > suggestion > silent > none. Multiple files can set it; precedence, strongest first:

Level	Mechanism	This repo's instances
1	In-source: #pragma warning disable <ID> / [SuppressMessage] (incl. GlobalSuppressions.cs)	src/Analyzers/GlobalSuppressions.cs and tests/Moq.Analyzers.Test/GlobalSuppressions.cs — each suppresses exactly one rule: SA1503 (braces). Inline [SuppressMessage] also appears in code with written justifications (e.g. MA0051 in the MockBehavior analyzers)
2	.editorconfig dotnet_diagnostic.<ID>.severity — nearest file to the source wins; deeper folders override shallower	Root .editorconfig (422 lines, root = true) plus three nested overrides: tests/.editorconfig, src/tools/.editorconfig, src/tools/PerfDiff/.editorconfig
3	Global AnalyzerConfig (.globalconfig) — loses to any .editorconfig entry for the same ID	build/targets/codeanalysis/.globalconfig, wired via <GlobalAnalyzerConfigFiles> in CodeAnalysis.props:17
4	The rule's own DiagnosticDescriptor default (defaultSeverity, isEnabledByDefault)	Each analyzer source file in src/Analyzers/

On top of whichever severity wins, PedanticMode=true escalates every surviving warning to error (Axis 1). There are no <NoWarn> properties and no .ruleset files anywhere in this repo (verified 2026-07-02) — do not introduce them; the layers above are the sanctioned mechanisms.

What each file is for

• Root .editorconfig — the main severity ledger plus formatting rules. Notable pinned entries (2026-07-02): SA1633 = silent (no file headers), SA1101 = silent (no this. prefix), SA1600 = silent, CA1016 = none (line 407 — Codacy false positive, suppressed deliberately per incident 58924f7/2a7ee34; do not "fix" it), MA0040 = error, CA2016 = error (CancellationToken forwarding — load-bearing for analyzer responsiveness), S1135 = suggestion (NEVER raise; see Axis 1 trap), MA0026 = none. It also carries the ADR-010 section forcing end_of_line = lf for *.ps1/psm1/psd1 (a CRLF PowerShell file once broke the pre-push hook, issue #1081) and a section protecting Verify snapshot files (*.{received,verified}.*) from newline/whitespac

---

Content truncated.