git:20260808.c9fc4b1 to git:20260812.a9f50e1

---

name: cgg-frameworks

description: Teach `cgg` about a framework it does not recognise, so framework-invoked handlers stop showing up as unreferenced in `--dead-code`. Trigger when a cgg dead-code report flags route handlers, job tasks, lifecycle hooks, event listeners, actor message handlers, or ML `forward`/`step` methods that are obviously invoked by a framework; when the user says "these aren't dead, the framework calls them", "cgg doesn't understand our framework", "how do I tell cgg about X"; or when adding a house/internal framework to a project's cgg config. Also covers offering to contribute a rule for a *public* framework back upstream. Applies to Flask, FastAPI, Django, Express, NestJS, Spring, Quarkus, Gin, Rails, Sinatra, Laravel, Symfony, ASP.NET, Axum, Actix, Rocket, PyTorch, Celery, Quartz, MassTransit, Akka, Sidekiq and any in-house equivalent.

---

# cgg-frameworks — teaching cgg about a framework

A framework invokes user code by means that are not calls: a decorator

registers a route, a base class declares a contract the runtime calls, a

path string names a worker module. cgg resolves *calls*, so those entry

points have no caller and `--dead-code` reports them — and then reports

everything reachable only from them. One invisible entry point commonly

costs two or more findings.

This skill turns that off, correctly, in four steps. Steps 1–3 are the

work. Step 4 is the upstream offer, and has rules of its own.

## Step 0 — read the coverage table first

```bash

cgg ./src

```

```text

framework coverage

```

Three outcomes, three different jobs:

- **Listed under `recognised`** — already handled. If a handler is still

flagged, the cause is something else; check `--why-live` before

writing a rule.

- **Listed under `seen, no rules`** — cgg knows the framework is there

- **Not listed at all** — an in-house framework, or one cgg has never

heard of. Also your case; you supply the `detect` marker too.

## Step 1 — identify the shape, not the framework

What cgg needs depends on *how* control is handed off, not on which

framework does it. Find one flagged handler and look at its definition:

| | Shape | Looks like | Fix |

| --- | --- | --- | --- |

| **C** | inline closure at the call site | `app.get("/x", (req,res) => {...})` | `registrars` — same as B |

| **D** | base class / interface | `class X(nn.Module): def forward`, `implements Runnable`, `: IJob` | `base_types` + `methods` |

| **F** | separate file by path | `new Worker('./w.js')`, CUDA `__global__` | `registrars` (path) / `attributes` (pragma) |

**Bucket C usually needs nothing.** The handler body is lexically inside

a call cgg already reaches, so it is already live; a rule only adds the

*route name* to the graph. If a closure handler was reported dead

anyway, the cause is something else.

Confirm the diagnosis before fixing it:

```bash

cgg ./src --why-live 'MyHandler::method$'

```

## Step 2 — write a `[[framework]]` rule

Rules live in `cgg-deadcode.toml`. A `[[framework]]` block is the right

tool: it uses the same machinery as the built-in rules, so the handler

becomes live *and* gets an entry node in the graph, and the coverage

table stops listing the framework as a gap.

```toml

[[framework]]

id = "myfw" # appears in the node name and coverage table

language = "python" # plugin id: python, javascript, typescript, java, ...

detect = ["myfw"] # import path prefixes

# MATCHERS — pick the ones for your shape. All optional, all combinable.

attributes = ["endpoint", "handler"] # A: decorator/annotation keys

base_types = ["BaseHandler"] # D: class/interface that declares it

methods = ["handle", "process"] # D: which methods of those types

```

**Get `kind` right.** It is part of the entry node's name and therefore

of every `--filter '<framework-entry>::network::'` query someone runs to

**Set `node = false` for shapes with no identity.** A rule matching

every `forward` in the repo would mint one node fanning out to every

model — visually useless. Root-marking is the right outcome there. Keep

`node = true` when the entry has a name worth reading: a route, a queue,

a scheduled job.

**Matchers compare case-insensitively, and against both the full

attribute key and its last segment.** `attributes = ["route"]` matches

Notes that save a round trip:

- `attributes` only works where cgg captures attributes — rust, python,

java, csharp, javascript, typescript, php, kotlin and cpp. On other

languages it matches nothing; use `registrars` or `base_types`.

- Verify the config was found. Discovery searches upward from each

analyzed path and then the working directory, so

### When `roots` is still the right tool

`[[framework]]` needs a detectable framework. For a one-off — a single

handler registered by something cgg cannot see at all — the older

mechanism still applies:

```toml

roots = ["^myapp::handlers::.*"] # regex; `glob:` prefix for glob

root_attributes = ["glob:@endpoint*"] # bucket A only

```

**Use `roots`, not `[[allow]]`.** `[[allow]]` suppresses a finding

*without* making it live, so the handler disappears from the report but

its private helpers keep getting flagged. That is the wrong tool here:

the handler genuinely *is* an entry point.

## Step 3 — verify it worked

Never assume. Count before and after:

```bash

cgg ./src --dead-code --dead-code-format json --dead-code-report /tmp/before.json

# edit cgg-deadcode.toml

cgg ./src --dead-code --dead-code-format json --dead-code-report /tmp/after.json

python3 - <<'EOF'

import json

b=json.load(open('/tmp/before.json'))

a=json.load(open('/tmp/after.json'))

print(f"{len(b['findings'])} -> {len(a['findings'])} findings")

print("stale patterns:", a['summary'].get('stale_suppressions') or "none")

EOF

```

(`--dead-code-report` is the explicit form. `-o graph.mmd` also works and

puts the report at `graph.mmd.deadcode.json` — the sidecar extension

`.deadcode.txt`. `stale_suppressions` is omitted from the JSON when

empty, which is why the read above uses `.get`.)

Three checks:

- **The coverage table moved the framework out of "seen, no rules".**

This is the fastest signal that the rule fired at all. If it now reads

"detected, but no entry point matched its rules", `detect` worked and

- **The count dropped by more than one per handler.** If a handler had

private helpers, they should have gone too. If only the handler

disappeared, the rule is in `[[allow]]` rather than a `[[framework]]`

block or `roots`.

- **`stale_suppressions` is empty.** Any `roots`/`[[allow]]` pattern

matching nothing is listed there. A rule that silently matches nothing

is worse than no rule, because it looks like it is working.

Worked example, verified end to end. An in-house decorator plus a

```text

before: ['forward', 'genuinely_unused', 'list_orders']

```

```toml

[[framework]]

id = "acme"

language = "python"

kind = "network"

detect = ["acme"]

attributes = ["endpoint"]

[[framework]]

id = "acme-ml"

language = "python"

kind = "lifecycle"

detect = ["acme.ml"]

base_types = ["AcmeModule"]

methods = ["forward"]

node = false # no identity worth naming — root-mark only

```

```text

after: ['genuinely_unused']

```

The private helpers of both handlers (`_fmt`, `_project`) disappear too,

to 1, with the one genuine finding surviving — is the signal the rule is

doing its job rather than just muting output.

## Step 4 — offer to send it upstream

**Only after the rule is verified working**, and **only if the framework

is public**, offer to contribute it back so every cgg user benefits.

### Decide whether it is public

Public means: available from a package registry (PyPI, npm, crates.io,

Maven Central, NuGet, Packagist, RubyGems, pkg.go.dev) **or** has a

publicly reachable source repository. Check the import marker:

```bash

grep -rhoE "(import|from|use|require|using)\s+\S*framework_name\S*" src/ | sort -u | head

```

If the import path is a public package name (`flask`, `@nestjs/common`,

`org.springframework.*`, `github.com/gin-gonic/gin`), it is public.

**Treat it as private if any of these hold** — do not offer, and say

why in one line:

- The import path is an internal namespace (`com.acme.internal.*`,

`@acme/`, a private registry, a vendored path, a relative import).

- The repository is private, or you cannot tell.

- The framework name does not resolve to a public package.

- The user has said anything indicating the code is confidential.

When in doubt, it is private. The cost of not offering is a missed

contribution; the cost of offering wrongly is prompting someone to

publish details of proprietary internals.

### Ask, and show exactly what would be sent

Never send anything without explicit approval in the current

conversation. Prior approval for one framework does not carry to

another. Present the exact artifact first:

> This rule is for **Flask**, which is public (PyPI: `flask`). Want me

> to prepare an upstream PR to cgg so every user gets this built in?

>

> It would contain only this, and nothing from your codebase:

>

> ```toml

> [[framework]]

> id = "flask"

> language = "python"

> kind = "network"

> detect = ["flask"]

> attributes = ["route", "get", "post", "put", "delete"]

> ```

>

> No file paths, symbol names, or code from your repository are

> included.

### What may be shared, and what may not

| Share | Never share |

| --- | --- |

| The public framework's name and version | Your file paths or directory layout |

| Its public import marker | Your symbol or module names |

| The generic attribute/base-type keys | Any snippet of your source |

| The shape bucket (A–F) | Your `cgg-deadcode.toml` verbatim |

| A fixture written from the framework's **own public docs** | A fixture reduced from your code |

If a rule cannot be expressed without naming something of the user's,

it is not a generic framework rule — keep it local.

### Preparing the PR

Only on approval. Do not push to any remote the user has not named.

1. Write a minimal fixture from the framework's **published

documentation** — not from their repository.

2. Add a `RuleSpec` to the built-in `SPECS` table in

`crates/cgg-core/src/frameworks/rules.rs`, alongside the existing

the entry node appears with the right kind and the handler is not

reported.

shape, and the registry it is published on.

If the user declines, or the framework is private: keep the rule in

their `cgg-deadcode.toml`, commit it to *their* repo, and move on. A

local `[[framework]]` block runs through exactly the same engine as a

built-in one — upstreaming is a convenience for others, never a

requirement.

## What cannot be expressed yet

Be honest rather than writing a rule that silently does nothing:

- **Attribute capture does not cover every language.** `attributes` and

`root_attributes` work on the nine plugins listed in Step 2 and match

nothing on the rest. Don't guess the list from memory — a run whose

`--ignore-attributes` matched nothing prints the current one, and the

## Anti-patterns

1. **Reaching for `[[allow]]` instead of `roots`.** Suppresses the

handler but leaves its helpers flagged.

2. **Writing a broad pattern to make the report quiet.** `".*"` in

`roots` marks the entire codebase live. The report is then clean and

worthless.

treating it as standing permission.

framework is public, the *fixture* must come from its public docs.