A pull request can pass the compiler, the formatter, and the linter and still leave behind a serious engineering problem.
Maybe two independent network requests are being awaited one after another. Maybe a log line includes credentials or personal data. Maybe an error is being discarded without making it clear whether that was intentional. Maybe a persistence change works for new data but does not protect existing records.
None of these problems necessarily look like syntax errors.
The code can be valid. The tests can be green. The change can even look reasonable during a quick review.
That gap is why I built Nice Code.
The limits of local checks
Compilers and linters are extremely good at the rules they can prove locally.
They can tell us whether a type is valid, a variable is unused, a function is formatted correctly, or a known rule has been violated.
But some engineering questions are about context:
- Does this log contain enough information to debug the operation safely?
- Are these asynchronous operations actually independent?
- Is this error intentionally ignored?
- Does this migration preserve existing data?
- Is this performance claim supported by a measurement?
- Does this test protect real behavior or only exercise a happy path?
These questions involve intent, ownership, risk, and operational behavior. They are harder to reduce to a single syntax rule.
AI-assisted development makes this especially visible. A generated change can be completely plausible and still carry a weak assumption about concurrency, error handling, security, or state ownership.
Nice Code is designed for that layer of review.
A small review layer
Nice Code is not meant to replace a compiler, formatter, linter, or test suite.
It adds a conservative, evidence-oriented review on top of the tools a project already uses. The goal is not to produce a single quality score. The goal is to make recurring engineering questions visible, with enough context for someone to decide what should happen next.
The project covers patterns related to:
- Logging and observability
- Async work and concurrency
- Error handling
- API boundaries
- State and data flow
- Persistence and data integrity
- Testing and verification
- Security and secrets
- Performance measurement
- Reliability and operations
- Code review and AI-generated changes
The patterns are intentionally smaller than a general-purpose static-analysis system. Each one should have a source, a recurring problem, a practical review procedure, and a clear explanation of what it can and cannot prove.
Installing Nice Code
The public package provides a Node-compatible launcher:
npm install --global @sayanmohsin/nice-code
nice-code --changed --project .
The installed command is nice-code, while the npm package is scoped as @sayanmohsin/nice-code.
For a one-off run, the package can also be invoked without a global installation:
npx --yes @sayanmohsin/nice-code --changed --project .
End users do not need Bun, Cargo, or Rust installed. The launcher downloads and verifies the matching Rust engine from the project’s GitHub Releases.
A practical workflow
Nice Code defaults to focused work.
Run a changed-file check during local development or before committing:
nice-code --changed --project .
Run a deliberate full scan when you want to inspect the broader repository:
nice-code --all --project .
That distinction is useful. A full repository scan can be valuable, but it should be intentional rather than silently becoming part of every small edit.
Nice Code can also produce machine-readable output:
nice-code --project . --all --json > nice-code-report.json
JSON reports contain structured findings and scan information for automation, dashboards, or later review.
For GitHub code-scanning integrations, SARIF output can be uploaded as a CI artifact:
- name: Run Nice Code
run: nice-code --project . --changed --ci --format sarif > nice-code.sarif
- name: Upload Nice Code report
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: nice-code.sarif
Existing projects can adopt Nice Code gradually with a baseline:
nice-code --project . --all --write-baseline
The baseline makes it possible to focus on new findings while the project works through older review items deliberately.
What Nice Code claims
Trust depends on knowing what a tool is actually saying.
Nice Code classifies findings so that a contextual concern does not look identical to a proven defect:
-
FAILis a high-confidence issue that may block according to project policy. -
WARNis an actionable concern that normally needs review. -
REVIEWmeans context or engineering judgment is required. -
PASSmeans the relevant check ran without a finding. -
N/Ameans the check does not apply to the project or change.
The REVIEW status is important. If a tool cannot prove that a behavior is wrong, it should not pretend that it can.
For example, a sequential await may be correct if the second operation depends on the first. A log statement may be safe if the value is already sanitized. A persistence change may be valid if the migration is protected elsewhere.
The tool should identify the question and the evidence. A developer still needs to make the final decision.
How the tool is built
Nice Code keeps the review path small and explicit.
Public guidance is recorded in a source registry and adapted into independent engineering patterns. The Rust engine owns discovery, parsing, rules, reports, and exit decisions. Node.js provides the user-facing launcher, while Bun is used for development tooling, tests, and benchmarks.
When running in CI mode, Nice Code can also run available native project tools. Their status remains separate from Nice Code’s own findings, so a missing or failing native tool is not silently confused with a custom review rule.
The result can be consumed in several ways:
- Human-readable terminal output
- Compact output for coding agents
- JSON for automation
- SARIF for code-scanning systems
- Baselines for gradual adoption
The same review can therefore support a developer working locally, an agent preparing a change, or a CI workflow checking a pull request.
Exceptions should be specific
No review tool understands every project perfectly.
That does not mean the answer should be to disable an entire category of checks.
Nice Code supports project-specific configuration and exceptions, but exceptions should be narrow and documented. A good exception explains why a particular finding is safe in that location. It should not quietly remove an entire class of engineering questions from the project.
If a rule produces a false positive because the parser or heuristic is wrong, the better fix is usually to improve Nice Code itself. The target project should not be rewritten merely to make a checker quiet.
In practice, every finding should eventually fall into one of three categories:
- A genuine defect to fix.
- Safe or intentional behavior to document.
- A Nice Code parser or rule problem to improve.
That classification is more useful than pretending every result is equally certain.
Where Nice Code is today
Nice Code is an evolving project.
It is a review aid, not an autonomous engineering authority. It complements native tooling and human review rather than replacing either one.
The project is deliberately conservative about what it claims. Some checks can be automated. Some need a developer or agent to inspect the surrounding context. Others are ultimately product or operational decisions.
The useful outcome is not that every finding disappears.
It is that difficult engineering questions become visible earlier, with a clearer path for deciding what to do about them.
Explore Nice Code
You can find the project here:
Nice Code started from a simple observation: passing local checks is necessary, but it is not always enough to make a change trustworthy.
The project is an attempt to add a small, practical review layer for the questions that live between syntax and system behavior.
Top comments (1)
Separating deterministic failures from contextual review items is where most static analysis tools stumble. Once a linter treats a heuristic warning as a hard blocker, teams either disable the entire rule or wrap everything in ignore comments. Having an explicit review category that outputs structured evidence is especially helpful when pairing with coding agents, where the model needs to distinguish between a broken invariant and a design trade-off that requires human judgment.