Skip to content

style(csharp): apply the C# style rulebook to all handwritten code - #90

Draft
FLwolfy wants to merge 33 commits into
masterfrom
code-format
Draft

FLwolfy wants to merge 33 commits into
masterfrom
code-format

Conversation

@FLwolfy

@FLwolfy FLwolfy commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Summary

Applies the C# style rulebook (.agents/rulebook/csharp-style/) to all handwritten C#. This PR is stacked on #89 and stays a draft until #89 is merged.

What is in it so far

  • Tooling (feat(tooling): check and fix C# style by rulebook rule ID): a Roslyn style engine in Inno.Tooling.Architecture. InnoEngine.Build style check|fix ROOT reports findings by rule ID and fixes them. Layout fixes must keep the token sequence, every fix must reparse without syntax errors, and a failing fix is rejected and reported. Architecture verification runs the same engine over production and test sources and replaces the previous line-based validator.
  • Layout (style(csharp): apply the rulebook layout to all handwritten C#): style fix over 2,469 handwritten files; 2,088 changed. Layout only, except two token-adding changes that keep behavior: braces around single-statement control bodies (B-05) and parentheses around multi-line expression lambdas (B-04).
  • .git-blame-ignore-revs lists the layout commit.

Generated bindings, extern/ and auto-generated sources are untouched.

Phase 2 (batch 1)

  • Tooling (feat(tooling): check and fix typing, literal, attribute and comment style rules): nine more rulebook rules in the style command, each with fix and exemption tests:

    • E-01 local types
    • M-04 target-typed field initializers
    • E-07 string.Empty
    • E-11 lambda parameters
    • E-10 numeric literals
    • M-05 attributes
    • D-02/D-04 XML documentation layout
    • D-05 comments
    • B-09 one statement per line

    Overloaded equality operators are recorded as an E-04 exception in the rulebook.

  • Apply (style(csharp): apply the rulebook typing, null-check and qualification rules): the rules above applied to all handwritten C# (1,173 files changed), together with the semantic rules that need symbol information:

    • E-04 is null patterns, kept as == where a type overloads equality
    • E-08 this. in constructors
    • N-05 short names through usings or role-based aliases
    • N-06 alias names

    No behavior change. Generated and third-party sources are untouched.

  • .git-blame-ignore-revs also lists this apply commit.

Phase 2 (batch 2)

  • Tooling (feat(tooling): check and fix modifier, sealing, namespace and member order rules): eight more rules with fix and exemption tests: explicit accessibility modifiers, modifier order, sealed by default (T-03), record modifiers (T-04), file-scoped namespaces, using placement, built-in type keywords, member order (O-01/O-02).
  • Apply (style(csharp): apply the rulebook modifier, sealing and member order rules): the rules above applied to all handwritten C# (about 560 files). Member reordering leaves structs, [StructLayout] types, native interop types, serialized instance members, order-dependent static initializers and types with preprocessor directives in their original order. Classes with derived types or a documented extension contract stay unsealed.
  • .git-blame-ignore-revs also lists this apply commit.

Phase 3

  • Renames (style(csharp): rename non-public symbols to the rulebook naming): 1,448 private, internal and local symbols plus public symbols outside src/ and build/, in 588 files, renamed with Roslyn so every reference follows. No public engine API change.
  • .git-blame-ignore-revs also lists this rename commit.

Phase 4

  • Renames (style(csharp)!: rename public symbols to the rulebook naming): public symbol renames (about 830 symbols plus tuple element names, about 1,110 files, 60 file renames). Breaking for scripts and plugins that use the renamed public names.
  • Unchanged: serialized member names, JSON model members, MSBuild task parameters, native interop names and third-party names, so existing project data keeps loading.
  • Local evidence on Linux: style checker 0 findings over 2,486 files, compiler diagnostics identical to the pre-rename baseline, runnable test projects identical to the pre-rename baseline (architecture tests 262/262).
  • Not validated locally: Windows and macOS builds and native/editor test projects, which rely on this PR's CI.
  • .git-blame-ignore-revs also lists this rename commit.

Naming check

  • InnoEngine.Build style now checks NM-01 to NM-13 by rule ID; .editorconfig states the same naming table.
  • 353 remaining symbols renamed to make the check pass: 344 test methods without underscores, 6 private accessors, 2 static readonly fields, 1 parameter.
  • Local result: 0 style findings across 2,487 files; compiler diagnostics and the runnable test projects match the state before this batch; architecture tooling tests 291 passed.

Mechanical rules and checker coverage

  • Apply (dce88f2e, style(csharp): apply the remaining mechanical rulebook rules): 669 files changed by the remaining mechanical rules (E-05, E-06, I-02, P-03 names, W-04, ConfigureAwait in build code, D-06, M-02, E-09).
  • Tooling (e1404724, feat(tooling): check thirteen more rulebook rules): 16 files for the checker (12 new rule files covering 13 rule IDs, tests, decision record).
  • Local evidence: style check 0 findings on 2,499 files; compiler diagnostics identical to the baseline before the change; local test results identical to the previous batch except the architecture tool tests, 291 -> 330 passed; Windows/macOS and native tests rely on CI.
  • .git-blame-ignore-revs also lists this apply commit.

One type per file and rule boundaries

  • Apply (840d139f, style(csharp): keep one top-level type per file): F-02 applied repository-wide (about 780 new files, 78 group files removed or renamed, declarations moved verbatim).
  • Tooling (71992d96, feat(tooling): check the file and type name rule F-02): the checker now enforces F-02.
  • Rulebook (7ee69644, docs(rules): state the catch, blocking wait and record constructor boundaries): X-04 allows a failure boundary to catch Exception when it records the failure; X-05 allows a blocking wait where a contract fixes a synchronous signature and requires tests to await; T-07 lets a record use an ordinary constructor when it validates or normalizes its arguments.
  • Local results: style check 0 findings on 3,198 files; compiler diagnostics unchanged; architecture tooling tests 338 passed; other locally runnable tests unchanged; Windows/macOS/native tests rely on PR CI.
  • .git-blame-ignore-revs also lists this apply commit.

Parameter order, structs and catch handlers

  • P-03: the CancellationToken parameter is last in 28 more declarations; 147 call sites follow. This changes public signatures. 21 declarations keep a required token before optional parameters.
  • X-04: 24 bare catch handlers that do not rethrow are now catch (Exception); 11 handlers gained a comment that says why the failure is ignored.
  • T-05: four plain structs are readonly.
  • X-05: one test fixture no longer blocks on a task result. The remaining test waits run on an owner thread or inside a synchronous callback and stay.
  • Tooling: the P-03 check now covers the parameter position.
  • Local evidence (Linux): style check 3,198 files, 0 findings; compiler diagnostics unchanged; architecture tests 340 passed; the other runnable test projects match the previous batch. Windows, macOS and native tests rely on PR CI.

Still to come in this PR

  • Rules that change behaviour and need a decision per site: P-03 CancellationToken position, T-05 mutable structs, X-05 blocking waits in tests, X-04 bare catches.
  • InnoEngine.Docs: authored pages that mention renamed public names are updated after this lands on master.

Review notes

  • style check reports no findings on this branch.
  • On Linux the managed projects compile with no C# errors; native and entry projects need the Windows and macOS CI.
  • Review the layout commit with whitespace changes hidden; git blame skips it through .git-blame-ignore-revs.

The complete style text is committed before registration so the rule registry can pin every chapter to an immutable source revision.
Register every chapter of the C# code style rulebook as a complete unit and route C# paths to it. Replace the coding clauses it supersedes through recorded amendments.

Keep the documentation CI note in one workflow, index every decision and acceptance record, and point the Docs authority link at the published main branch.
…iles

Each rule file states its own paths and tags in front matter. The rule
script lists the files to read and checks front matter, size limits and
routing examples; it no longer needs Git history. coverage.json, line
hashes, amendments and rule-unit markers are removed without an archive.

The C# code style is one file per chapter, and the Editor and Build and
Native domains are directories. Paths are whole-path globs instead of
unanchored regular expressions. The validation planner no longer parses
a registry, and the agent document validator rejects unlisted skills.
Drop the local output drive from the root instructions, stop naming a
macOS sound file in the completion sound rule, and use a neutral author
placeholder in the contributor guide.
API synchronization now applies the API page rules to project guides. A project outside platforms/ that no project page owns receives a registered synchronized guide beside its owner kind: tests/ projects under contributing/testing/projects, backends/ projects under backends/projects, all others under architecture/projects. A removed project deletes its synchronized guide and keeps an authored guide with a warning.

Hand-authored pages without a registry entry are never registered, rewritten or deleted, and a checkout without the registry manages no guides. Synchronized guides no longer feed API category descriptions, so creating or removing one leaves every other planned page unchanged.
Add a Roslyn style engine to Inno.Tooling.Architecture that reports each
finding by rulebook rule ID and fixes it in place. Layout fixes must keep
the token sequence, reorder fixes the token multiset, and every fix must
reparse without syntax errors; a fix that fails is rejected and reported.

`InnoEngine.Build style check|fix` exposes the engine, and architecture
verification now runs it over production and test sources in place of
the previous line-based style validator. Generated and third-party
sources are skipped; a source that only writes a generated marker into
a string is still handwritten.

The rulebook record lists which rule IDs the tool reports today.
Run `style fix` over every handwritten C# file. Generated bindings,
extern and auto-generated sources are untouched.

The changes are layout only, with two exceptions that add tokens without
changing behavior: braces around single-statement control bodies (B-05)
and parentheses around multi-line expression lambdas (B-04).

`style check` reports no findings afterwards.
…tyle rules

Add nine rulebook rules to the style command, each with fix and exemption tests:
E-01 local types, M-04 target-typed field initializers, E-07 string.Empty,
E-11 lambda parameters, E-10 numeric literals, M-05 attributes, D-02/D-04 XML
documentation layout, D-05 comments and B-09 one statement per line.

Record overloaded equality operators as an E-04 exception in the rulebook.
…n rules

Apply the new style rules to all handwritten C#, together with the semantic
rules that need symbol information: E-04 `is null` patterns (kept as `==` where
a type overloads equality), E-08 `this.` in constructors, N-05 short names
through usings or role-based aliases, and N-06 alias names.

No behavior change. Generated and third-party sources are untouched.
…order rules

Add eight rulebook rules to the style command, each with fix and exemption
tests: T-01 explicit accessibility, T-02 modifier order, T-03 sealed classes,
T-04 record modifiers, N-01 file-scoped namespaces, N-03 using placement,
E-03 built-in type keywords and O-01/O-02 member order.

Member reordering leaves structs, explicit layouts, native interfaces,
serialized instance members, dependent static initializers and types that
contain directives in their declared order.

Record serializer-written record structs as a T-04 exception in the rulebook.
…rules

Apply the new style rules to all handwritten C#: explicit accessibility,
modifier order, built-in type keywords, `sealed` on classes that nothing
derives from, and the rulebook member order. Classes that are derived from or
designed for derivation stay open and state that contract.

No intended behavior change. Generated and third-party sources are untouched.
Rename private, internal and local symbols, and public symbols outside
the Engine API roots, to the rulebook naming: ID, IO and UI acronyms,
C_ constants, UPPER_SNAKE static readonly fields, s_ and m_ field
prefixes, camelCase parameters and locals, and the Async suffix. Five
source files follow their renamed types. Engine API names under src/
and build/, serialized member names, generated bindings and native
signatures are unchanged.
…tion

NM-13 now says a plural keeps the acronym upper case and adds a lower-case s (sourceIDs, GetAssetIDs).
The serialized wire name exception now says why it exists: the engine serializer and reflection-based JSON models write the member name as the persisted key, so serialized members keep the name stored in existing assets, scenes, settings and manifests.
Renames public and contract-bound symbols with Roslyn so every reference follows: two-letter acronyms (Id/Ui/Io to ID/UI/IO, including plurals), public constants (C_ prefix), static properties and events (camelCase), asynchronous method suffixes, tuple element names, and the matching file names and using aliases.

BREAKING CHANGE: public API names in src/ and build/ change, for example AssetSourceId to AssetSourceID, EditorUiSession to EditorUISession, Identity.persistentId to Identity.persistentID and StableTypeIdAttribute to StableTypeIDAttribute. Scripts and plugins that use these names must be updated.

Unchanged by design: serialized members whose name is the persisted key (AssetMeta.persistentId, PluginManifest.pluginId and similar), JSON model members, MSBuild task parameters, native interop names, third-party product names and the "Inno.StableTypeId" assembly metadata key. Existing assets, scenes, settings and manifests keep loading.
…g table

Test method names drop their underscores (TS-02), the private state
accessors of the tree widget lose the field prefix (NM-05), two static
readonly fields lose the `S_` prefix (NM-08) and one parameter uses the
`ID` acronym (NM-13). Renames are symbol-bound; behavior is unchanged.
The style engine reports names that break the naming table under their
own rule ID. The check reads syntax only, so it trusts overrides,
interface implementations, native interop declarations and serialized
members, and it exempts test methods from the `Async` suffix.
`.editorconfig` states the same naming table for editors.
Apply the rules that the checker did not cover yet to all handwritten C#.

- E-05: validate arguments with the ThrowIf helpers before the body.
- E-06: write the type of a created object in arguments and expressions.
- I-02: write arrays and lists as collection expressions where the
  declaration gives a target type.
- P-03: name CancellationToken parameters cancellationToken.
- W-04: keep `=` and the start of its value on one line.
- X-05: add ConfigureAwait(false) in the build CLI and the browser build
  target.
- D-06, M-02, E-09, E-08, E-04, N-05, N-06: remove regions, block
  comments and a file-level #nullable, and fix the remaining single sites.
- Name the fields and one method of the native backend tests by the
  naming table.

Generated bindings, extern code and serialized names are unchanged.
The style checker now reports E-04, E-05, E-06, E-08, E-09, E-12, I-02,
M-02, P-03, W-04, D-06, N-05 and N-06, and fixes W-04 and E-12.

The naming check no longer exempts the native backend tests. The
decision record lists what each syntax-only check reports and what it
leaves to review.
Apply F-02 to all handwritten C#. A file is named after its primary type, which comes first. Classes, structs, interfaces and records with a body move to their own files; an enum, a delegate or a positional record stays with the type it belongs to. Additional parts of a partial type are named Type.Part.cs. Using directives that a moved type no longer needs are removed.

Declarations are moved verbatim. Compiler diagnostics and local test results match the previous commit.
The style engine reports a file that declares no type named like it, a primary type that is not first, and a second top-level type other than an enum, a delegate or a positional record. Whether a companion is used only by the primary type stays in review.
…undaries

X-04 allows a failure boundary to catch Exception when it records the failure. X-05 allows a blocking wait where a contract fixes a synchronous signature and requires tests to await. T-07 lets a record use an ordinary constructor when it validates or normalizes its arguments.
Rule P-03. Move the `CancellationToken` parameter to the end of 28 declarations and reorder the arguments of their 147 call sites and the XML `<param>` entries.

A required token that precedes optional or `params` parameters stays where it is: it cannot move without gaining a default value.
Rule X-04. A bare `catch` that does not rethrow becomes `catch (Exception)`, and each handler that ignores the failure says why in a comment.

Rule T-05. The tree widget value structs and one test struct become `readonly`.

Rule X-05. `ValidationRepository.Git` reads the process output without blocking on a task result.
Rule P-03 now reports a `CancellationToken` parameter that is not last. A required token that precedes optional or `params` parameters is not reported.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant