.editorconfig

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 4

[*.{json,yml,yaml,csproj,props,targets,slnx}]
indent_size = 2

[*.md]
trim_trailing_whitespace = false   # two trailing spaces are a hard line break

[*.cs]
# Namespace = folder path, no exceptions — tooling and humans both rely on it.
csharp_style_namespace_declarations = file_scoped:error

# Explicit over implicit; boring over clever (principle P12).
csharp_style_var_when_type_is_apparent = true:suggestion
csharp_style_var_elsewhere = false:suggestion
dotnet_style_qualification_for_field = false:error
# Interface members are implicitly public; writing it out is noise that no C#
# codebase does. Everywhere else an explicit modifier is required.
dotnet_style_require_accessibility_modifiers = for_non_interface_members:error
csharp_prefer_braces = true:error
csharp_style_prefer_pattern_matching = true:suggestion

# Correctness rules promoted to errors — each of these is a real defect class.
dotnet_diagnostic.CA2007.severity = error   # ConfigureAwait(false) in library code
dotnet_diagnostic.CA1848.severity = warning # LoggerMessage over interpolation on hot paths
dotnet_diagnostic.CA1031.severity = error   # do not swallow general exceptions
dotnet_diagnostic.CA2016.severity = error   # forward CancellationToken
dotnet_diagnostic.CA1062.severity = error   # validate public arguments
dotnet_diagnostic.IDE0055.severity = warning

# Public contract surface must be documented (constraint C7).
dotnet_diagnostic.CS1591.severity = error

# CA1716 (identifier conflicts with a reserved language keyword) is disabled for
# the whole repository. It fires on Step, Return, When, Then, Error, Get and Set
# — which is to say, on the FlowX DSL's entire vocabulary. The rule protects
# VB.NET and F# consumers; FlowX is a C#-first platform whose DSL readability IS
# the product. Renaming Step to ExecuteStep to please a language FlowX does not
# target would damage every call site to protect a scenario that does not exist.
# This is a decision, not debt — see ADR-0013.
dotnet_diagnostic.CA1716.severity = none

# CA1711 reserves the 'Stack' suffix for types deriving from Stack<T>, so that a
# suffix never misleads about behaviour. CompensationStack does not derive from it
# but is exactly a LIFO of completed compensable steps, and that LIFO ordering is
# the saga's safety property — undo newest-first or two systems end up disagreeing.
# The suffix communicates the invariant rather than obscuring it, so the suffix is
# allowed here rather than the rule being switched off.
dotnet_code_quality.CA1711.allowed_suffixes = Stack

[tests/**/*.cs]
# Tests legitimately capture context and assert on exceptions.
dotnet_diagnostic.CA2007.severity = none
dotnet_diagnostic.CA1031.severity = none
dotnet_diagnostic.CS1591.severity = none

# ===========================================================================
# SonarAnalyzer.CSharp
# ===========================================================================
# The package is referenced from Directory.Build.props so that the S#### rules
# docs/21-Quality-Gates.md §2.1 and §2.2 name as build gates actually run.
# Thresholds live in SonarLint.xml — .editorconfig carries severities only, and
# a threshold written here is silently ignored.
#
# Policy, in one sentence: the package's default profile gates the build, and
# every deviation from it is written down below with the reason and the sites.
#
# Two things about this package are worth knowing before editing this section.
#
# 1. Four of the rules §2.1 names are shipped IsEnabledByDefault=false, so
#    referencing the package is NOT sufficient to make those rows true. They
#    are switched on or off explicitly below; nothing is left to the default.
# 2. Rule severities cannot be set per category here. Roslyn's .editorconfig
#    key parser accepts no spaces in a key, and every Sonar category contains
#    one ("Major Code Smell"), so `dotnet_analyzer_diagnostic.category-*` lines
#    for this package parse as nothing and silently do nothing. Per-rule keys
#    are the only mechanism that works.

[*.cs]

# --- §2.2, promoted to error as the document says -------------------------
dotnet_diagnostic.S2245.severity = error   # no insecure randomness
dotnet_diagnostic.S4507.severity = error   # no debug features in production

# --- §2.1 complexity and size: OFF, and this is a measured decision --------
# These four are the rows §2.1 calls build gates. They are off. Turning them on
# is a one-word edit per line, and the reason they are not on is not that the
# rules are wrong — it is that the repository does not currently satisfy them:
#
#   S1541 cyclomatic ≤ 10   24 methods over, worst 20 (DeadlineCoherenceAnalyzer)
#   S107  parameters ≤ 7    14 members over, worst 15 (FlowModel's constructor)
#   S3776 cognitive  ≤ 15   12 methods over, worst 47 (FlowEngine.RunRangeAsync)
#   S138  lines      ≤ 60    4 methods over, worst 118 (FlowEngine.RunRangeAsync)
#
# 54 findings, all of them in existing code. Enabling any of these rows without
# first paying that down would stop the build on day one, and lowering a
# threshold to whatever today's code happens to score would make the number in
# the document a description of the past rather than a limit. Neither is a gate.
# docs/21-Quality-Gates.md §2.6 carries the list; the thresholds are already
# pinned in SonarLint.xml so that flipping a line here needs no other change.
#
# S1541 additionally has a reason to stay off permanently: Sonar deprecated it
# in favour of S3776, which measures the same property in a way that does not
# count a flat switch over a syntax kind as complexity. If one of these four is
# retired rather than paid down, it should be this one.
dotnet_diagnostic.S3776.severity = none
dotnet_diagnostic.S1541.severity = none
dotnet_diagnostic.S138.severity = none
dotnet_diagnostic.S107.severity = none

# --- Rules switched off because they do not fit this codebase -------------
# Each of these fired, was read, and was judged wrong here rather than
# inconvenient. Sites are named so the judgement can be re-checked.

# S3267 asks that loops be rewritten as Where/Select. On the paths it fired on
# — ForEachOutcome, ParallelOutcome, the emitter's step scans — that trades a
# non-allocating loop for an iterator plus a closure. Budget B2 forbids exactly
# that, and EngineAllocationTests fails if it happens, so the two gates would
# contradict each other. The loop is the correct code.
dotnet_diagnostic.S3267.severity = none

# S3236 says passing an argument that has a [CallerArgumentExpression] default
# hides caller information. In Identifiers.RequireIdentity/RequireSemanticVersion
# the explicit paramName is the point: these are validation helpers, and letting
# the compiler fill it in would name the helper's own local ("value") in every
# ArgumentException instead of the caller's parameter. Following the rule here
# would introduce the defect the rule exists to prevent.
dotnet_diagnostic.S3236.severity = none

# S2094 wants empty classes removed. They are load-bearing: IsExternalInit and
# friends in FlowX.Compiler/Polyfills.cs exist only so the netstandard2.0
# compiler can bind records and init accessors, and the rest are marker types
# in generic tests. An empty type is the whole design in both cases.
dotnet_diagnostic.S2094.severity = none

# S127 objects to advancing the loop variable inside the body. FlowEngine's step
# loop, the CLI's argument parser and FlowAnalyzer's step scan all do it on
# purpose — a branch advances the index to a jump target rather than by one —
# and each carries a comment explaining why. Rewriting them as while loops to
# satisfy the rule would hide the invariant those comments state.
dotnet_diagnostic.S127.severity = none

# Stylistic, no behavioural difference, and disagreeing with the house style:
dotnet_diagnostic.S8969.severity = none   # redundant null-forgiving operator (20 sites, all after an assertion that the compiler cannot see through)
dotnet_diagnostic.S3358.severity = none   # nested ternary in expression-bodied mapping code
dotnet_diagnostic.S6618.severity = none   # string.Create over FormattableString, in test helpers
dotnet_diagnostic.S4136.severity = none   # method overloads must be adjacent

# --- OPEN FINDINGS: real defects, silenced only because this change cannot fix them
# The rule below found a genuine problem in files outside this change's scope.
# It is off so the build stays green, NOT because the finding is wrong.
# Do not delete these lines as cleanup — deleting one turns the build red until
# the sites below are fixed, which is the intended behaviour once they are.
# Tracked in docs/21-Quality-Gates.md §2.6.
#
# S8949 (semantic-model calls dropping context.CancellationToken) and S2365
# (FlowModel.ComposedFlows / .ReferencedCapabilities allocating a List per read)
# were listed here. Both are fixed, so both entries are gone and the two rules
# now run at their default severity and guard the fix.

# S6966 was here, off repository-wide, for the three
# CancellationTokenSource.Cancel() calls in FlowX.Runtime/FlowEngine.cs. All three
# now await CancelAsync() through FlowEngine.StopSiblingsAsync, so the rule is back
# on its default severity and those three lines are no longer listed above. The
# block's own instruction was that deleting one of these lines turns the build red
# until the sites are fixed; they are, so it does not.
#
# The entry also cited samples/ecommerce/Program.cs:43. That site was real but was
# not a Cancel() call and never was — the two findings were filed as one, which is
# why fixing the engine did not clear it. It was then scoped to that one file with
# the argument that blocking the main thread is what a host entry point does. That
# argument was true and the suppression was still worth losing: the sample's last
# line is now `await app.RunAsync()`, which is identical in behaviour under
# top-level statements, so S6966 runs at its default severity everywhere.

[tests/**/*.cs]
# Sonar rules that are wrong about test code specifically.
dotnet_diagnostic.S1215.severity = none   # GC.Collect is the measurement in the allocation tests, not a mistake
dotnet_diagnostic.S2699.severity = none   # "no assertion" — the assertion is that StartAsync does not throw
dotnet_diagnostic.S2326.severity = none   # unused type parameters are phantom types under test
dotnet_diagnostic.S3218.severity = none   # a nested test type shadowing an outer member is local and deliberate
dotnet_diagnostic.S5034.severity = none   # reading ValueTask.IsCompleted then GetAwaiter().GetResult() is the documented synchronous-completion pattern
dotnet_diagnostic.S3241.severity = none   # a test helper may return a value that only some callers use
dotnet_diagnostic.S3878.severity = none   # explicit array in a params call, for readability in a table-driven test

[src/FlowX.Runtime/Tenancy/ClaimTenantResolver.cs]
# "http://schemas.flowx.dev/claims/tenant" is a claim type, the same shape as the
# WS-Federation claim URIs. Its scheme is part of its identity — changing it to
# https would simply stop matching the claim in incoming tokens. It is never
# dereferenced, so there is no request to secure.
#
# The list used to live in plugins/FlowX.Http/HttpTriggerReader.cs and this
# exemption with it. It moved here when admission-time tenant resolution landed:
# both the transport and the resolver derive a tenant from the same claims, and
# two copies of the list would eventually disagree — so there is one list, in the
# layer both can reach, and the suppression follows the literal.
dotnet_diagnostic.S5332.severity = none   # http:// is insecure
dotnet_diagnostic.S1075.severity = none   # hardcoded URI

[plugins/FlowX.Http/ProblemDetailsMapper.cs]
# "https://flowx.dev/errors/" is the RFC 9457 Problem Details `type` prefix. The
# spec requires a stable URI, so it has to be written down somewhere, and it is
# already https. It identifies an error class rather than addressing a document,
# and this code never dereferences it.
dotnet_diagnostic.S1075.severity = none   # hardcoded URI

# samples/workflow's FLOWX-DEBT(people-ops, 2026-12-31) suppression of FLOWX1032 was
# deleted here when the policy engine landed PolicyStage.Resilience. The debt named one
# set — Policies.DirectoryService, a Timeout, a Retry and a CircuitBreaker — and all
# three of those kinds are now applied, so the rule was silent on that sample for the
# ordinary reason rather than a suppressed one. Its other set, FacilitiesUndo, is
# compensation-only and was always silent. Removed rather than left in place because a
# debt marker for debt that has been paid is the thing that teaches people to stop
# reading them; samples/workflow/Policies.cs still describes the old state in prose and
# is not this package's to edit.
#
# FLOWX1032 itself is now deleted, with the last of the gap it described: stages 1, 3, 5
# and 7 all execute, so there is no inert kind left for it to name. Its id is retired
# rather than reused — docs/diagnostics/README.md carries the record.

[src/FlowX.Runtime/FlowEngine.cs]
# The comment above the step loop quotes the for-loop it is deliberately NOT
# using, to explain why. S125 reads the quoted line as commented-out code.
dotnet_diagnostic.S125.severity = none

[{src/FlowX.Runtime/FlowExecutionContext.cs,src/FlowX.Testing/ContextValues.cs}]
# S2245 stays an error everywhere else. These two are the sanctioned exception
# §2.2 already names: CapabilityContext.Random is the flow's determinism source,
# journaled so a replay reproduces the run. Journalled and secret are opposites,
# so this Random is not in a security context by construction. A CSPRNG here
# would break replay and secure nothing.
dotnet_diagnostic.S2245.severity = none

# ===========================================================================
# Microsoft.VisualStudio.Threading.Analyzers
# ===========================================================================
# Referenced for one rule: VSTHRD002, which docs/21-Quality-Gates.md §2.2 names
# as a build gate and which no package in this repository previously provided.
# The other three rules this package raised on the existing tree are switched
# off below; none of them is named by the document.

[*.cs]

# §2.2, promoted to error as the document says. Sync-over-async in a runtime
# this hot is a thread-pool starvation incident waiting for load.
dotnet_diagnostic.VSTHRD002.severity = error

# VSTHRD200 wants an Async suffix on every awaitable-returning method. It fired
# only on BenchmarkDotNet entry points and test helpers, where the name is the
# benchmark's reported label — renaming them would rewrite the identifiers that
# docs/benchmarks/ compares runs by. The document does not ask for this rule.
dotnet_diagnostic.VSTHRD200.severity = none

# VSTHRD103 was off for exactly the three CancellationTokenSource.Cancel() calls
# that Sonar's S6966 also found (FlowEngine.cs:636,836,876) — one finding, two
# analyzers, tracked once. Those three sites now await CancelAsync(), so both
# rules are back on. Keeping this line would mean the next Cancel() written in an
# async method is caught by one analyzer instead of two, which is a worse gate
# than the one the original entry was protecting.

# VSTHRD003 (awaiting a Task started outside the current context) fired once, in
# DrainTests, on a task the test starts itself and hands to a helper. The rule
# targets deadlock via a captured synchronization context; xUnit has none.
dotnet_diagnostic.VSTHRD003.severity = none

[tests/**/*.cs]
# VSTHRD002's rationale is deadlock when a sync wait captures a synchronization
# context. Test code runs without one, so a blocking wait in a test blocks that
# test and nothing else. 24 of the 26 sites are here, and none of them is the
# defect the rule is about.
dotnet_diagnostic.VSTHRD002.severity = none

[src/FlowX.Runtime/FlowEngine.cs]
# FlowEngine.Observe reads `finished.Result` inside `if (finished.IsCompletedSuccessfully)`.
# That is a read of an already-completed task, not a wait — nothing blocks, and the
# guard is what makes the parallel fast path allocation-free. VSTHRD002 does not
# model the guard. The rule stays an error for the rest of src/ and plugins/.
dotnet_diagnostic.VSTHRD002.severity = none