CSharpDoctor.Cli 0.1.0

CSharp Doctor

Hybrid .NET code health scanner: Roslyn analyzers + CLI, modeled after react-doctor.

Quick start (like npx react-doctor@latest)

Prerequisites: .NET SDK 8+ (SDK 10+ recommended for dnx).

From your repo root (where .sln or .csproj files live):

# One-shot, no global install (.NET 10+ SDK) — closest to npx
dnx CSharpDoctor.Cli@latest -- .

# Same via dotnet CLI
dotnet tool exec CSharpDoctor.Cli@latest -- .

Pin a version in CI:

dnx CSharpDoctor.Cli@0.1.0 -- . --fail-on error

If the package is not on NuGet.org yet, use install from source or a local feed first.

Run against a project

csharp-doctor scans C# under a directory. It auto-detects .sln / .csproj, loads rules, and reads .csharp-doctor.json from the scan path or a parent folder.

Example workflow

cd /path/to/your/dotnet-repo

# First run (install globally once)
dotnet tool install -g CSharpDoctor.Cli

# Full scan
csharp-doctor .

# Pre-commit: only what you changed
csharp-doctor --staged

# PR CI: diff against main
csharp-doctor --diff origin/main --fail-on error --annotations

Optional config at the solution root: .csharp-doctor.json (rule severity, ignores, surface filters).

Install & distribute

1. Global tool (recommended for daily use)

After publishing to NuGet:

dotnet tool install -g CSharpDoctor.Cli
csharp-doctor --help

Update:

dotnet tool update -g CSharpDoctor.Cli

2. One-shot / npx style (dnx or dotnet tool exec)

No global install; downloads the package to the NuGet cache and runs it (.NET 10.0.100+ SDK for dnx):

dnx CSharpDoctor.Cli@latest -- .
dotnet tool exec CSharpDoctor.Cli@latest -- .

3. Local tool (pin version per repo)

In your repository root:

dotnet new tool-manifest   # once, creates .config/dotnet-tools.json
dotnet tool install CSharpDoctor.Cli --version 0.1.0
dotnet tool run csharp-doctor -- .
# or: dotnet csharp-doctor .

Commit .config/dotnet-tools.json so everyone (and CI) uses the same version.

4. GitHub Actions

Use the composite action in this repo (action.yml):

- uses: your-org/csharp-doctor@v1
  with:
    directory: .
    fail-on: error
    diff: main          # optional
    annotations: true   # optional

Or install the tool in a step:

- uses: actions/setup-dotnet@v4
  with:
    dotnet-version: '10.0.x'
- run: dotnet tool install -g CSharpDoctor.Cli
- run: csharp-doctor . --fail-on error

5. Build and install from source

git clone https://github.com/your-org/csharp-doctor.git
cd csharp-doctor
dotnet pack src/CSharpDoctor.Cli/CSharpDoctor.Cli.csproj -c Release -o ./nupkg
dotnet tool install -g --add-source ./nupkg CSharpDoctor.Cli

# Smoke test against the bundled sample (expects CSD0001 + CSD0002)
csharp-doctor samples/Sample

See samples/README.md for tool-path install and DOTNET_ROOT notes on macOS.

6. Run without installing (development)

dotnet run --project src/CSharpDoctor.Cli/CSharpDoctor.Cli.csproj -- /path/to/your/project

CLI reference

csharp-doctor [path]              # full scan (default: current directory)
csharp-doctor --project <path>    # specific .csproj or .sln
csharp-doctor --diff <ref>        # changed files only (e.g. main, origin/main)
csharp-doctor --staged            # staged files only
csharp-doctor --format json       # JSON report
csharp-doctor --format sarif      # SARIF (redirect to a file)
csharp-doctor --fail-on error     # exit 1 when errors present (CI gate)
csharp-doctor --fail-on warning   # stricter gate
csharp-doctor --fail-on none      # never fail on findings
csharp-doctor --annotations       # GitHub Actions workflow commands
csharp-doctor --no-lint           # skip Roslyn analyzers (config-only path)

Rules

45 rules across Security, Correctness, Performance, Maintainability, and ASP.NET Core. ASP.NET rules apply only to web projects (detected from .csproj).

See docs/rules/README.md for the full index, CA complement matrix, and recommended .editorconfig preset.

Configuration

Create .csharp-doctor.json at solution root. See docs/configuration.md.

Development

dotnet test

Follow TDD: write failing tests first (see .cursor/rules/csharp-tdd-test-first.mdc).

Releasing to NuGet

The CLI is packaged as a .NET Global Tool. Versions are driven by git tags via .github/workflows/release.yml.

One-time setup

1. Reserve the CSharpDoctor.* prefix on nuget.org (account → ID Prefix Reservations).
2. Create an API key scoped to Push new packages and package versions for glob CSharpDoctor.*.
3. Store it as the NUGET_API_KEY repository secret in GitHub.
4. (Optional, recommended) After the first publish, enable NuGet Trusted Publishing for this repo + workflow and switch the release job to OIDC (the workflow has a commented-out nuget/login@v1 block ready to flip on, then delete the secret).

Cut a release

# Pre-release (recommended for first ship — System.CommandLine dep is still prerelease)
git tag v0.1.0-preview.1 && git push --tags

# Stable
git tag v0.1.0 && git push --tags

The workflow restores, builds, tests, packs, pushes .nupkg + .snupkg to nuget.org with --skip-duplicate, and creates a GitHub Release (marked prerelease automatically if the version contains -).

Manual / dry-run pack

dotnet pack src/CSharpDoctor.Cli/CSharpDoctor.Cli.csproj \
  -c Release -o ./artifacts /p:Version=0.1.0-preview.1

# Smoke test install from local feed
mkdir /tmp/csd-smoke && cd /tmp/csd-smoke
dotnet new tool-manifest
dotnet tool install CSharpDoctor.Cli --version 0.1.0-preview.1 \
  --add-source $OLDPWD/artifacts
dotnet csharp-doctor --help

Privacy

No telemetry by default. Optional OTLP: set CSHARP_DOCTOR_OTLP_ENDPOINT and CSHARP_DOCTOR_OTLP_AUTH_HEADER.