Codacy Agentlinter

This is an integration created so that Codacy can run the agentlinter tool in its infrastructure, or using its CLI.

agentlinter is a static analysis tool for AI agent configuration files (CLAUDE.md, AGENTS.md, etc.).

Generating documentation

npm install
npm run build:docs

Build docker image

docker build -t codacy-agentlinter .

Test changes to codacy-seed locally

You may need to test changes that come from our codacy-engine-typescript-seed.

1. Create a package with your changes on the seed:

   • Don't forget to update the dependencies: npm install
   • Compile the library: npm run compile
   • Package the library: npm pack

     This should generate a codacy-seed-0.0.1.tgz on your codacy-seed repository

2. Copy the codacy-seed-0.0.1.tgz into the root of this repository

3. Install the package: npm install codacy-seed-0.0.1.tgz

4. Update Dockerfile and .dockerignore so you copy the codacy-seed-0.0.1.tgz inside the docker you will be building

   • Add !codacy-seed-0.0.1.tgz to your .dockerignore
   • Add the package to the docker before RUN npm install: COPY codacy-seed-0.0.1.tgz ./
   • Remove multi-stage docker steps
     • Lines from FROM node:$NODE_IMAGE_VERSION to RUN rm -rf /package.json /package-lock.json

     This way you skip copying the files to the other docker, and another npm install

5. Publish your docker locally as normal: docker build -t codacy-agentlinter .

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 agentlinter npm dependency version, but also Node base image / CircleCI orb / other npm 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 thin TypeScript wrapper (src/index.ts, src/engineImpl.ts, built on the codacy-seed library) that packages agentlinter — a third-party static analysis tool for AI agent configuration files (CLAUDE.md, AGENTS.md, etc.) — as a Docker image Codacy's platform can run against a customer's repository. Unlike some Codacy engines, this repo does not hand-maintain its rule catalogue: src/docGenerator.ts fetches the current rule set directly from the seojoonkim/agentlinter GitHub repo (main branch, packages/cli/src/engine/rules) over the GitHub API at doc-generation time and writes it out. So docs/ is machine-generated, not machine-consumed static config:

• docs/patterns.json — the full list of agentlinter rules ("patterns") Codacy knows about, generated by npm run build:docs. Do not hand-edit.
• docs/description/*.md + docs/tool-description.md — human-readable titles/descriptions per pattern, also generated by npm run build:docs, sourced from the rule descriptions in the upstream repo. Do not hand-edit.
• docs/multiple-tests/* — fixtures used by codacy-plugins-test (via the CircleCI codacy_plugins_test orb) to validate the engine actually produces the results it claims for real sample projects.

2. Files that encode versions

File	What it pins
package.json (dependencies.agentlinter)	The wrapped third-party tool's version (currently >=0.3.3 — a floating range, not an exact pin)
package-lock.json	The resolved, locked version actually installed
Dockerfile (FROM node:20-alpine3.20)	The Node base image used to build and run the engine
.circleci/config.yml (orbs:)	The codacy/base, codacy/plugins-test, and circleci/node orb versions used by CI
package.json (devDependencies/other dependencies)	Build/lint/test tooling versions (typescript, eslint, mocha, axios, glob, etc.)

There is no Scala-style codacy-engine-scala-seed version to bump here — the Node/TypeScript equivalent is the codacy-seed npm dependency, which is versioned independently and only needs bumping if Codacy's own seed library changes.

3. Step-by-step update procedure

1. Bump the version(s) as scoped by the task — e.g. change agentlinter's version/range in package.json, then run npm install so package-lock.json picks up the new resolved version. For a Node base image or CircleCI orb bump, edit Dockerfile / .circleci/config.yml directly.
2. Regenerate the docs: npm install && npm run build:docs (this compiles the TypeScript and runs dist/src/docGenerator.js, which pulls the current rule set live from seojoonkim/agentlinter's GitHub repo and rewrites docs/patterns.json and docs/description/*.md). Review the diff — a dependency bump can add, remove, or reword rules.
3. Lint, compile, run unit tests, build the Docker image locally:
   • npm run lint (ESLint, auto-fixes what it can)
   • npm run build (tsc)
   • npm test (mocha over src/test/**/*.spec.ts, includes integration.spec.ts and convertResults.spec.ts)
   • docker build -t codacy-agentlinter .
4. Commit, push, open a PR.
5. Poll the PR's real CI checks until they all pass — local validation is NOT the finish line. CI here is CircleCI (.circleci/config.yml): node/test, a local Docker build/save, codacy_plugins_test/run against the fixtures in docs/multiple-tests, and (on master only) a Docker publish + version tag. After every push, run gh pr checks <pr-url> and keep re-polling until all checks finish. If a check fails, fetch its actual log, find the true root cause, fix it, push again, re-poll. Repeat until every check is green, or you hit a genuine product/infra decision needing a human.

4. Definition of done

• The version bump (or other change) is reflected consistently in package.json and package-lock.json (and Dockerfile/.circleci/config.yml if that's what was bumped).
• docs/patterns.json and docs/description/*.md have been regenerated via npm run build:docs and the diff has been reviewed for unexpected rule changes.
• npm run lint, npm run build, and npm test all pass locally, and the Docker image builds successfully.
• After pushing and opening/updating the PR, every CircleCI check on it is green — in particular node/test and plugins_test (the Docker-publish and version-tag jobs only run on master, after merge, so they are not expected to run on the PR itself).

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.