@codacy/tools-unsupported-tools

Table of Contents

• Overview
• What "unsupported" means
• Contents
• Framework mappings
• Regenerating the manifest
• How it's consumed
• Development
• Notes for maintainers

Overview

This package holds a generated, committed manifest of every Codacy Cloud tool that does not have a local analyzer adapter in this CLI — the "unsupported" (cloud-only) tools. It lets the CLI treat those tools as first-class citizens of the configuration and of the info / analyze / init flows, even though they are never executed locally.

What "unsupported" means

A tool is tracked here when it is in the Codacy catalog (/api/v3/tools), has no local adapter (its UUID is not referenced by any sibling tool package's prefetch script), and is trackable — i.e. not deprecated and not client-side/standalone-only (those run only in the customer environment).

Descriptors carry unsupported: true, which is how the rest of the CLI tells them apart from real adapters.

Contents

• src/descriptors.json — one AdapterDescriptor per tool (unsupported: true, uuid set, supportedRunners: ["container"]).
• src/patterns/<toolId>.json — that tool's full pattern set (same shape as a supported adapter's patterns.json). Tools with no patterns have no file.
• src/index.ts — exports unsupportedDescriptors (eager, tiny) and loadUnsupportedPatterns(toolId) (lazy disk read, cached).
• src/framework-mappings.json — hand-curated framework matching rules (see below).

Framework mappings

Several cloud-only tools ship framework-specific patterns (PHPCS → CakePHP/WordPress/Drupal/Magento/ Symfony; dartanalyzer → Flutter/Angular; SonarCSharp → ASP.NET Core/Entity Framework/xUnit/…; CodeNarc → Grails/Spock/…; Codacy ScalaMeta Pro → Play Framework). src/framework-mappings.json maps tool ID → FrameworkMappings so init --auto can include those patterns only when the framework is actually detected (and exclude them otherwise), exactly like supported tools.

• It is hand-curated and committed — unlike descriptors.json/patterns/, it is not touched by generate, so it survives regeneration. index.ts merges it onto each descriptor's frameworkMappings at load time.
• Choose the mechanism per tool from its pattern shape: prefixes when pattern IDs are namespaced by framework (e.g. PHPCS_CakePHP_), tags otherwise (e.g. flutter, aspnetcore, grails).
• Each key must be a DEPENDENCY_ENTITIES key (packages/tooling/src/dependency-entities.ts) — the stable slug, not the display name — since that is what auto-init matches against. Display names are not unique (angular is Angular 2+, angular-dart is AngularDart), so the key is what keeps a Dart tool's patterns from gating on an npm dependency. If discovery cannot detect the framework yet, add a telltale to the right ecosystem module in packages/runner/src/discover/ecosystems/.
• test/framework-mappings.test.ts enforces that every key maps to a real tool, the merge applied, and every prefix/tag still matches ≥1 committed pattern (guards against drift after regeneration).
• Codacy ScalaMeta Pro: its six Custom_Scala_Play* patterns are all default-on and read Play's request/header API, so before being mapped they fired in every Scala repo. play-framework is detected from the sbt-plugin coordinate addSbtPlugin declares and from the conf/routes layout — Play is declared as an sbt plugin, which is why the telltale keys on group:artifact. Its other 80 patterns carry no tags at all and are genuinely general Scala rules, so they stay universal.

Regenerating the manifest

From the repo root:

pnpm generate-unsupported

or from this package:

pnpm generate

The script (scripts/generate.mjs) fetches the catalog, subtracts locally supported tools (by UUID, read from sibling prefetch scripts — no list to keep in sync), filters out deprecated/client-side tools, and rewrites descriptors.json + patterns/. Commit the result. On network failure it warns and exits 0, leaving committed files untouched.

Run this whenever Codacy adds/removes tools or you implement a new local adapter (which should then disappear from this manifest on the next regeneration).

How it's consumed

• packages/cli/src/index.ts registers every descriptor via registerUnsupportedTool() so they appear in getRegisteredDescriptors().
• init --auto calls loadUnsupportedPatterns() to fill cloud-only tools offline.
• init --remote / --default fetch patterns from the API at runtime, so they do not read this package's pattern files — only its descriptors/registration.

Development

pnpm build   # tsup bundle + copy src/patterns → dist/patterns
pnpm test    # manifest shape + drift invariants
pnpm lint

loadUnsupportedPatterns reads dist/patterns/<toolId>.json at runtime (__dirname-relative) and src/patterns/ during tests.

Notes for maintainers

• The patterns directory is recreated on every generate run so removed tools don't leave stale files behind.
• The package is named with the @codacy/tools- prefix on purpose: the CLI keeps those external from its bundle, so __dirname resolves to this package's own dist/ and the pattern files are found.
• filePatterns is ["*"] for all entries — unsupported tools never route files locally, so the value is cosmetic.