This page describes the two tools that keep a change formatted and building: the Git pre-commit hook and
scripts/format-all.cs. Back to the README.
The first dotnet restore of a clone installs the hook. The hook runs the pre-commit group of
.husky/task-runner.json through Husky.Net. Set HUSKY=0 to skip the hook. A restore with CI=true does not install it.
Husky.Net runs a task only when a staged file matches its include patterns. A commit that stages no C# or project file
therefore skips all three tasks. The tasks run in this order, and a failed task stops the commit:
| Step | Runs when a staged file matches | What it does |
|---|---|---|
format-staged |
**/*.cs |
Formats each fully staged C# file and stages the result again. Checks, but does not rewrite, a partly staged file. |
build |
**/*.cs, **/*.csproj, **/*.props, **/*.targets, **/*.slnx, global.json |
Runs dotnet build --no-restore --configuration Release -p:CI=true. With CI=true, an analyzer warning fails the build, as it does in CI. |
test |
The same files as build |
Runs dotnet test --no-build --configuration Release. It runs the whole test suite of the solution, not only the tests for the staged files. |
scripts/format-staged.cs splits the staged C# files into two groups.
- A fully staged file has no unstaged edits. The script runs CSharpier, then
dotnet format, then CSharpier again. It then checks the file with both tools and stages the formatted file. A commit never fails on the formatting of such a file. - A partly staged file also has unstaged edits. The script cannot stage the formatted file without also staging those edits. It only checks the file with both tools. If the file needs formatting, the commit fails. Format the file, then stage the hunks that you want.
If the check fails for a fully staged file, CSharpier and dotnet format disagree about some code. Change the shape of
the code. Do not suppress the finding, and do not edit .editorconfig for it.
Roslynator does not run in the hook. It runs in CI and in scripts/format-all.cs.
Run dotnet run scripts/format-all.cs before you push. It works on the whole repository, not only on staged files.
By default the script rewrites files in your working tree. It runs these steps and stops at the first failure:
dotnet csharpier format .dotnet format TruthWeaver.slnx --no-restore --severity infodotnet csharpier format .again, becausedotnet formatcan move a token that CSharpier then moves back.dotnet csharpier check .dotnet format TruthWeaver.slnx --no-restore --verify-no-changes --severity infodotnet roslynator analyze TruthWeaver.slnx --ignore-compiler-diagnostics
Steps 4 to 6 are the formatting gates of the CI build job. Read the whole output, because findings at the info level fail the CI step too.
Pass --check-only to skip steps 1 to 3. The script then changes no file and only runs the three gates:
dotnet run scripts/format-all.cs -- --check-onlyThe hook builds and tests only the files that you stage, and it does not run Roslynator. Run format-all, then
dotnet test, before you push. The full list of checks is in the Required validation section of CLAUDE.md.
- Try first. Every public member named
XOrThrowhas a public sibling namedTryXthat returnsbooland reports the failure through anoutparameter. For example,CompilationResult<TContext>.GetRuleOrThrowhasTryGetRule.TruthWeaver.Architecture.Testsfails when a sibling is missing. - Docs show the
Tryform first. An example in a documentation page uses theTryform. It uses theOrThrowform only where a failure is a bug, such as at startup or in a test, and says so.
Every package version is in Directory.Packages.props. These rules apply to every project:
- One version per package. A project writes
<PackageReference Include="X" />with no version. AVersionOverrideattribute is an error (CentralPackageVersionOverrideEnabledisfalse). - Analyzers are global. The analyzer packages and MinVer are
GlobalPackageReferenceitems withPrivateAssets="all", so they apply to every project and never become a dependency of a shipped package. The pack check (scripts/check-packages.cs) fails when a package contains an unexpected file. - Transitive pinning is on. A
PackageVersionitem for a package that only a dependency pulls in raises that package to the version in the item. Use it to fix a vulnerable transitive package, and name the advisory in a comment. If a pin is lower than a dependency needs, restore fails with NU1109. Raise the pin. - NuGetAudit checks every package. The audit covers direct and transitive packages at every severity
(
NuGetAuditModeisall,NuGetAuditLevelislow). A vulnerability warning (NU1900 to NU1904) is a warning in a local build and an error whenCI=true. - Restore is mapped.
NuGet.confighas one source, nuget.org, and apackageSourceMappingentry with the pattern*. When you add a source, add its own patterns in the same change. Run restore with--locked-mode.
Dependabot (.github/dependabot.yml) checks NuGet packages and GitHub Actions once a week and opens grouped pull
requests: analyzers, test packages, and all other packages (and Microsoft.Extensions.* after .NET 11 GA). It updates
the versions in Directory.Packages.props. The deliberate pins are on its ignore list, each with a reason: the
Microsoft.Extensions.* RC line, StyleCop.Analyzers beta, Microsoft.CodeAnalysis.CSharp and
Microsoft.CodeAnalysis.Analyzers. When you change a pin, change the ignore list in the same pull request.
Dependabot does not check the local tools in dotnet-tools.json. Check them by hand with dotnet tool list and update the
versions in the file.
MinVer derives the version of every package from the Git tags. No project sets a
Version. All packages share one version. The settings are in Directory.Build.props and the MinVer package reference
is in Directory.Packages.props. Only projects that pack get MinVer.
| Commit | Version |
|---|---|
A commit with the tag v1.2.3 |
1.2.3 |
The 4th commit after the tag v1.2.3 |
1.2.4-preview.0.4 |
Any commit, when the repository has no v tag |
1.0.0-preview.0.N (N is the commit height) |
Any commit, with a tag below v1.0 |
1.0.0-preview.0.N (MinVerMinimumMajorMinor is 1.0) |
To make a release version, put a tag with the prefix v on the commit, for example v1.0.0. A tag without the prefix
is ignored. To make an alpha version, add a pre-release suffix with the UTC date and time in basic ISO 8601 form, for
example v1.0.0-alpha.20261018T201500Z. A colon is not valid in a version or a tag, so the basic form is used, and the
suffixes sort in time order. The release workflow marks a tag with a hyphen as a pre-release and the tag must be on a
commit in main. To override the version for one build, pass -p:MinVerVersionOverride=1.2.3.
MinVer needs the tags and the commit history. CI checks out with fetch-depth: 0 for this reason. In a shallow clone
the version is wrong. After git clone --depth, run git fetch --unshallow --tags.
To see the version without packing, run dotnet msbuild src/TruthWeaver -t:MinVer -getProperty:PackageVersion.
The pack job in .github/workflows/ci.yml packs every package and checks the result. It never pushes or publishes a
package. It has no NuGet API key and the job permission is contents: read. The job runs these steps:
dotnet pack TruthWeaver.slnx --configuration Release -warnaserror. A pack warning fails the job. Package validation (EnablePackageValidationinsrc/Directory.Build.props) runs in this step. It checks the package layout and the public API across target frameworks.dotnet run scripts/check-packages.cs -- <directory>. For each of the ten library packages and the tool package, the script checks that the.nupkgexists, containsREADME.mdand contains only the expected files. It also checks that the symbol package (.snupkg) contains the.pdbfile.TruthWeaver.Generatorsis an analyzer-only package and has no symbol package. The script fails when it finds a symbol package for it.
To run the same checks on your machine, pack into a directory outside the repository, then run the script on it:
dotnet pack TruthWeaver.slnx --configuration Release -warnaserror --output $env:TEMP/tw-packages
dotnet run scripts/check-packages.cs -- $env:TEMP/tw-packagesPackageValidationBaselineVersion is not set, because no version has been released. After the first release, set it to
that version so that pack fails on a breaking API change.
New repository scripts are .NET file-based apps. You run them with dotnet run scripts/<name>.cs. Shared helpers are in
scripts/shared/. A script includes a helper with a literal-path #:include shared/<file>.cs line.
scripts/list-open-done-tickets.cs lists the .scratch files marked done that still have an unticked checklist item. It exits
with code 1 when an open item has no note:
dotnet run scripts/list-open-done-tickets.csscripts/check-packages.cs checks the .nupkg and .snupkg files that dotnet pack wrote: the expected package set, a
README in each package, symbol packages where expected and no unexpected files. The package directory is a required
argument. The script exits with code 1 when a check fails:
dotnet pack --output artifacts/packages
dotnet run scripts/check-packages.cs -- artifacts/packagesscripts/normalize-text.cs makes text files valid UTF-8 with no byte order mark, LF line endings, no trailing whitespace
and one final newline, and replaces em dashes, ellipsis characters and curly quotes. It rewrites the files that Git tracks
or would track. Pass --check-only to rewrite nothing and exit with code 1 when a file needs a change. Pass file paths to
limit the run to those files. The script also exits with code 1 for a file that is not valid UTF-8 or that holds a hidden
character:
dotnet run scripts/normalize-text.cs
dotnet run scripts/normalize-text.cs -- --check-only
dotnet run scripts/normalize-text.cs -- docs/contributing.md README.mdscripts/validate-triage-labels.cs checks every Status:/**Status:** line in an issue file
(.scratch/<effort>/issues/*.md) or an effort's top-level spec.md, plan.md or map.md: it must lead with one of
the five triage labels (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix) or done,
case-insensitively. It is wired into the pre-commit hook (.husky/task-runner.json) and exits with code 1 when any
line does not:
dotnet run scripts/validate-triage-labels.csscripts/format-data.cs runs the pinned Prettier over the JSON, YAML and YML files, and only checks that the test
fixture folders parse. It needs Node.js and stops with a message and exit code 1 when node is not on PATH. Pass
--check-only to exit with code 1 when a file needs formatting. Pass file paths to limit the run to those files:
dotnet run scripts/format-data.cs
dotnet run scripts/format-data.cs -- --check-onlyscripts/format-staged.cs is the pre-commit step for C# files. It formats the fully staged .cs files (CSharpier, dotnet format,
CSharpier again) and stages them again. It only checks a partly staged file (one with unstaged edits) and exits with code 1
when that file needs formatting. scripts/normalize-text-staged.cs and scripts/format-data-staged.cs do the same with
normalize-text.cs (all staged files) and format-data.cs (staged JSON, YAML and YML files). They take no arguments:
dotnet run scripts/format-staged.cs
dotnet run scripts/normalize-text-staged.cs
dotnet run scripts/format-data-staged.csscripts/format-all.cs formats the whole repository and then runs the CI gates, in this order: normalize-text, format-data,
csharpier format, dotnet format, csharpier format again, the normalize-text and format-data checks, csharpier check,
dotnet format check and Roslynator. It stops at the first failing step, names the step and exits with code 1. Pass
--check-only to skip the first five (apply) steps:
dotnet run scripts/format-all.cs
dotnet run scripts/format-all.cs -- --check-onlyEvery project under src/ and tests/ has a README.md in its folder. The README states the purpose of the project and
its direct TruthWeaver dependencies. Use these sections, in this order:
| Section | Content | Required for |
|---|---|---|
# <ProjectName> |
The project name and one sentence. | Every project |
## Purpose |
What the project is for. | Every project |
## Use |
How to use it: install, first run and a command or key table for the tools; a compile-and-evaluate example for the core library. | TruthWeaver, TruthWeaver.Tool, TruthWeaver.Tool.Tui |
## Depends on |
One bullet for each direct ProjectReference: a link to the README of that project and half a sentence on why. |
Every project |
## Key types |
The main public types. | src/ projects |
## Notes |
A gotcha that a reader needs to know. | Only when one exists |
A project with no ProjectReference holds the single line No TruthWeaver packages. under ## Depends on. List a new
reference only after the change that adds it has landed.
TruthWeaver.Architecture.Tests checks the rule (ProjectReadmeTests). It fails for a project that has no README. It also
fails when the ## Depends on bullets differ from the ProjectReference items of the project file, and the failure names
the project. A bullet names its project by the link text or the link target.
Releasing lists the steps to publish a version and the checks to make afterwards.