slop-csharpier

A greenfield, pure TypeScript port of CSharpier. It formats C#, C# scripts, project files, and XML without requiring the .NET runtime.

This is an independent, unofficial port and is not maintained by the CSharpier project.

Status

The formatter is feature-complete against the pinned CSharpier 1.3.0 behavior corpus. All 198 C#/C# Script cases and all 46 XML cases are byte-for-byte exact and idempotent, with no lexer/parser or syntax-preservation safety fallbacks.

Every formatted C# result is re-lexed and checked against the original token and significant-trivia stream. File formatting preserves UTF-8, UTF-8 BOM, UTF-16 LE, UTF-16 BE, detected line endings, and file permissions.

Requirements

• Node.js 20 or newer
• ESM (import) consumers

CommonJS require() and browser environments are not supported in the 0.x release line.

Installation

Install as a development dependency:

npm install --save-dev @tsoumdoa/slop-csharpier
pnpm add --save-dev @tsoumdoa/slop-csharpier
yarn add --dev @tsoumdoa/slop-csharpier

Library API

Format C# synchronously:

import { formatCSharp } from "@tsoumdoa/slop-csharpier";

const result = formatCSharp("class   Example{}", {
  printWidth: 100,
  indentSize: 4,
});

console.log(result.code);

Format XML synchronously:

import { formatXml } from "@tsoumdoa/slop-csharpier";

const result = formatXml("<Project><PropertyGroup /></Project>", {
  printWidth: 100,
  whitespaceSensitivity: "strict",
});

The root package exports only formatCSharp, formatXml, and their TypeScript option/result types. Results include a status and diagnostics. If syntax errors or the structural safety check prevent formatting, the original source is returned with an unchanged-* status.

Configuration-aware Node API

Use the /node entry point when formatting according to files and project configuration:

import { formatFile, formatText } from "@tsoumdoa/slop-csharpier/node";

const preview = await formatText("class   Example{}", "src/Example.cs");
console.log(preview.code);

await formatFile("src/Example.cs");
await formatFile("src/Example.cs", { write: false });

formatText discovers configuration relative to the supplied path. formatFile additionally handles ignore rules, source encoding, line endings, permissions, and atomic writes. Set write: false to inspect without changing the file.

CLI

Run a project-local installation:

pnpm exec slop-csharpier format .
npx slop-csharpier check .

Or install the executable globally:

npm install --global @tsoumdoa/slop-csharpier
slop-csharpier format .

Commands:

slop-csharpier format [path ...] [options]
slop-csharpier check [path ...] [options]
slop-csharpier pipe-files [options]
slop-csharpier help
slop-csharpier version

With no path, format reads stdin and writes stdout:

printf 'class   Example{}' | npx slop-csharpier format

Options:

--config-path <path>       Use an explicit .csharpierrc or .editorconfig
--ignore-path <path>       Use an explicit ignore file
--stdin-path <path>        Resolve stdin options as this path
--write-stdout             Write formatted file contents to stdout
--skip-write               Format and validate without changing files
--include-generated        Include generated C# files
--skip-validation          Skip structural output validation
--unformatted-as-warnings  Make check return zero for unformatted files
--log-level <level>        none, error, warning, information, or debug

For command-line compatibility, --no-cache, --use-cache, and --no-msbuild-check are accepted as no-ops. This implementation has no cache or MSBuild check to toggle. --syntax-errors-as-warnings and --log-format are currently rejected because silently ignoring them would change promised behavior.

Exit codes:

• 0: successful format or check
• 1: check found one or more unformatted files
• 2: argument, I/O, syntax, validation, or formatting error

Supported C# extensions are .cs and .csx. Supported XML extensions are .config, .csproj, .props, .slnx, .targets, .xaml, .axaml, and .xml.

Configuration and ignores

Configuration is discovered from the nearest .csharpierrc, .csharpierrc.json, .csharpierrc.yaml, .csharpierrc.yml, or .editorconfig, including documented per-file overrides.

Ignore discovery respects .gitignore, .csharpierignore, generated C# file patterns, explicit --ignore-path, and negated CSharpier ignore rules.

API stability

During the 0.x release line, the documented root and /node entry points are the supported public API. Parser, lexer, syntax-tree, Doc, printer, source-text, glob, and CLI implementation modules are private and may change without notice.

Development

The repository uses pnpm:

pnpm install --frozen-lockfile
pnpm run check
pnpm test
pnpm run conformance:check
pnpm run pack:check

The conformance command compares the port with vendored upstream fixtures and fails if exact output, idempotence, or fallback metrics regress. Run pnpm run conformance -- --json for the full machine-readable report.

See the npm release plan and the implementation roadmap for project details.