Codacy TSQLLint

This is the docker engine we use at Codacy to have TSQLLint support. You can also create a docker to integrate the tool and language of your choice! See the codacy-engine-scala-seed repository for more information.

Usage

You can create the docker by doing:

docker build . -t <DOCKER_NAME>:<DOCKER_VERSION>

The docker is ran with the following command:

docker run -it -v $srcDir:/src -v $configFile:/.codacyrc <DOCKER_NAME>:<DOCKER_VERSION>

Generate Docs

1. Update the version in tsqllint.version
2. Run scripts/bootstrap.sh
3. Run the DocGenerator

dotnet run --project src/DocsGenerator

Test

We use the codacy-plugins-test to test our external tools integration. You can follow the instructions there to make sure your tool is working as expected.

Agent Playbook: Updating This Repository End-to-End

This section is written for an AI coding agent (or a human) tasked with updating this repo — most commonly bumping the wrapped TSQLLint version, but also base image / orb / dependency bumps. Follow it top to bottom; it tells you what to change, how to regenerate derived files, how to test locally, and how to interpret CI so you can iterate on failures without guessing.

1. What this repository is

This is a Codacy engine: a .NET/C# wrapper (src/Analyzer, built on Codacy.Engine.Seed) that packages TSQLLint as a Docker image Codacy's platform can run against a customer's SQL source code. Unlike a typical dotnet tool install -g wrapper, TSQLLint is not consumed as a NuGet package — its source is downloaded as a tarball and built from source alongside this repo:

• tsqllint.version — pins the exact upstream TSQLLint release tag (currently 1.16.0). This is the single source of truth for the wrapped version.
• scripts/bootstrap.sh — reads tsqllint.version, downloads https://github.com/tsqllint/tsqllint/archive/refs/tags/<VERSION>.tar.gz, extracts it, and renames the extracted folder to ./tsqllint/ (git-ignored — see .gitignore).
• src/Analyzer/Analyzer.csproj and src/DocsGenerator/DocsGenerator.csproj both have <ProjectReference>s pointing at ../../tsqllint/source/TSQLLint.Core/... and ../../tsqllint/source/TSQLLint.Infrastructure/... — i.e. they compile directly against the TSQLLint source tree that bootstrap.sh just extracted. scripts/bootstrap.sh must be run before any dotnet restore/build/test/run command, or these project references won't resolve.
• docs/ is machine-consumed configuration, not just documentation:
  • docs/patterns.json — the list of TSQLLint rules ("patterns") Codacy knows about, with level/category/enabled-by-default per rule. Generated file, do not hand-edit.
  • docs/description/description.json + docs/description/*.md — per-pattern titles and the rule docs copied verbatim from TSQLLint's own tsqllint/documentation/rules/ folder. Generated/copied file, do not hand-edit.
  • docs/tests/*.sql and docs/multiple-tests/*/ — fixtures used by codacy-plugins-test to validate the engine's real output against sample SQL files.
  • docs/tool-description.md — short blurb about the tool, hand-maintained.

Both generated artifacts above are produced by src/DocsGenerator (src/DocsGenerator/Program.cs), which reflects over the freshly built TSQLLint.Infrastructure.dll to enumerate every ISqlRule subclass in TSQLLint.Infrastructure.Rules, and copies tsqllint/documentation/rules/* (from the bootstrapped source tree) into docs/description/. This means the generator needs the tsqllint/ source tree already bootstrapped and built — it does not hit the network itself, but its inputs come from scripts/bootstrap.sh.

2. Files that encode versions — check all of these on every update

File	What it controls	What to check
tsqllint.version	Which TSQLLint release is bundled/built from source	Bump to the target version tag; confirm a matching tag exists at https://github.com/tsqllint/tsqllint/releases.
docs/patterns.json → "version"	The version string Codacy displays for the tool	Regenerated by src/DocsGenerator — don't hand-edit, just re-run the generator.
.circleci/config.yml → codacy/base orb	Shared CircleCI steps (checkout/version, docker publish, tagging)	Check the latest published version on the CircleCI orb registry.
.circleci/config.yml → codacy/plugins-test orb	Runs codacy-plugins-test in CI	Same as above.
Dockerfile → mcr.microsoft.com/dotnet/sdk:<X> / dotnet/runtime:<X> base images, and .circleci/config.yml's docker: - image:	.NET SDK/runtime the build and runtime use	Only bump if the new TSQLLint version raises its minimum .NET requirement (this happened in the 1.15.3 bump, which moved the project to .NET 8 — see c68c5aa/c65d366). Keep the SDK version in Dockerfile, .circleci/config.yml, and the <TargetFramework> in all three .csproj files consistent.
Analyzer.csproj / DocsGenerator.csproj / Analyzer.Tests.csproj → <PackageReference> versions (Codacy.Engine.Seed, Newtonsoft.Json, Microsoft.NET.Test.Sdk, xunit, xunit.runner.visualstudio)	NuGet dependencies, mostly kept current by Dependabot	Only touch these if the task explicitly scopes a dependency bump.

3. Step-by-step update procedure

1. Bump tsqllint.version to the target release tag.
2. Run scripts/bootstrap.sh from the repo root to download and extract the new TSQLLint source into ./tsqllint/.
3. Restore and build against the new source: cd tsqllint/source && dotnet restore && dotnet build, then back at the repo root dotnet build Codacy.TSQLLint.sln (or dotnet build in src/Analyzer / src/DocsGenerator). Fix any compile errors caused by upstream API changes in TSQLLint.Core/TSQLLint.Infrastructure (this is exactly what commits c65d366 needed — it touched src/Analyzer/CodeAnalyzer.cs and src/DocsGenerator/Program.cs to adapt to renamed/removed TSQLLint APIs).
4. Regenerate the docs: dotnet run --project src/DocsGenerator from the repo root. Review the diff to docs/patterns.json and docs/description/ for new/removed/renamed rules, and update docs/tests/* and docs/multiple-tests/*/results.xml fixtures if pattern output changed (prior bumps had to delete/adjust stale fixture .sql/results.xml files — see docs/multiple-tests/*/results.xml changes in c65d366).
5. Run the .NET test suite: dotnet test (from repo root or test/Analyzer.Tests).
6. Build the Docker image: docker build . -t <DOCKER_NAME>:<DOCKER_VERSION> and sanity-check it runs: docker run -it -v $srcDir:/src -v $configFile:/.codacyrc <DOCKER_NAME>:<DOCKER_VERSION>.
7. Run codacy-plugins-test locally before pushing — clone https://github.com/codacy/codacy-plugins-test and follow its instructions to run against your local image tag (this repo's CI runs it with run_multiple_tests: true, exercising both docs/tests/ and docs/multiple-tests/).
8. Iterate on failures, re-running only the relevant command (dotnet build, dotnet test, the doc generator, or the plugins-test run) after each fix.
9. Commit the version bump (tsqllint.version), any .csproj/Dockerfile/CI changes it required, and the regenerated docs/ files together in one change.
10. Push and open a PR.
11. Poll the PR's real CI checks until they all pass — local validation is NOT the finish line. After every push, run gh pr checks <pr-url> and keep re-polling (short sleep while any check is pending) until all checks finish. If a check fails, fetch its actual log (don't guess), find the true root cause, fix it, push again (never --no-verify, never force-push), and re-poll. Repeat until every check is green. The CI environment's toolchain can differ from your local one, so a clean local run does not guarantee CI passes. Only stop iterating when every check passes, or you hit a genuine product/infra decision that needs a human.

4. Common failure modes and fixes

Symptom	Cause	Fix
dotnet restore/build fails with missing project errors for TSQLLint.Core/TSQLLint.Infrastructure	scripts/bootstrap.sh wasn't run (or was run before the version bump), so ./tsqllint/source/... doesn't exist or is stale	Bump tsqllint.version first, then run scripts/bootstrap.sh before any dotnet command.
dotnet build/dotnet run --project src/DocsGenerator fails after a version bump with API/type errors	Upstream TSQLLint renamed or removed classes/interfaces (ISqlRule, rule constructors, etc.) between versions	Update src/Analyzer/CodeAnalyzer.cs and src/DocsGenerator/Program.cs/Helpers/* to match the new upstream API, as was done in the 1.15.3 bump (c65d366).
New/renamed TSQLLint rules missing severity or category in docs/patterns.json after regeneration	src/DocsGenerator/Helpers/LevelHelper.cs, CategoryHelper.cs, and DefaultPatterns.cs map pattern IDs to levels/categories/enabled-by-default explicitly and need updating for genuinely new rule IDs	Add the new pattern ID to the appropriate helper before regenerating docs.
docs/multiple-tests/*/results.xml or fixture .sql files no longer match plugin-test output	A rule's behavior/output changed upstream between TSQLLint versions	Update or remove the stale fixture files so they reflect the new tool's actual output, then re-run codacy-plugins-test locally to confirm.

5. Definition of done

• tsqllint.version bumped, and scripts/bootstrap.sh run successfully against it.
• docs/patterns.json and docs/description/* regenerated via dotnet run --project src/DocsGenerator, with fixture inconsistencies in docs/tests/ and docs/multiple-tests/ resolved.
• dotnet build and dotnet test pass locally.
• Docker image builds successfully via docker build . -t <DOCKER_NAME>:<DOCKER_VERSION>.
• codacy-plugins-test commands all pass locally against the freshly built image.
• After pushing and opening/updating the PR, every CI check on it is green. Poll gh pr checks <pr-url> and iterate on any failure until all pass.

What is Codacy

Codacy is an Automated Code Review Tool that monitors your technical debt, helps you improve your code quality, teaches best practices to your developers, and helps you save time in Code Reviews.

Among Codacy’s features

• Identify new Static Analysis issues
• Commit and Pull Request Analysis with GitHub, BitBucket/Stash, GitLab (and also direct git repositories)
• Auto-comments on Commits and Pull Requests
• Integrations with Slack, HipChat, Jira, YouTrack
• Track issues in Code Style, Security, Error Proneness, Performance, Unused Code and other categories

Codacy also helps keep track of Code Coverage, Code Duplication, and Code Complexity.

Codacy supports PHP, Python, Ruby, Java, JavaScript, and Scala, among others.

Free for Open Source

Codacy is free for Open Source projects.