The type checker asks “does this binding fit its slot”. The graph
lint asks the questions a code reviewer asks of a composition: is
this fn-def a copy of one that already exists, is this private helper
still used, is this the same graph as that one once the helpers are
inlined. It runs over EDN-shape fn-defs — the form the package loader
produces and crud/type-check/reconstruct-fn-def rebuilds from DB
rows — so one engine serves both authoring worlds.
| Where | What |
|---|---|
src/graphden/lint/core.clj |
the pure engine — lint over a fn-def seq |
src/graphden/lint/similar.clj |
opt-in, pure structural template suggestions over the same fn-defs |
src/graphden/lint/corpus.clj |
bb graph-lint — the first-party fns.edn corpus, no DB, ~10 s |
src/graphden/lint/graph.clj |
the live branch — graph snapshot → fn-defs → lint, memoised per snapshot |
| editor ⚐ lint filter chip + Inspector Lint section | GET /api/lint primes the chip; POST /partials/inspector-lint/{suppress,restore} — “Not an issue” / “Restore” write the branch’s lint-suppressions const |
| Rule | Fires when | Severity |
|---|---|---|
:duplicate-definition |
≥ 2 named composed fn-defs have the same shallow signature — parents, canonical args (refs resolved to identities, literals as written), :return-type, :lambda-params, effects, :branch-local?. Names, namespaces and every :description are ignored. |
weight ≥ 3 |
:duplicate-after-expansion |
the same, over the deep signature — every ref to a _-private fn-def is replaced by that fn-def’s own signature. Catches the same graph factored through differently-named helpers, or spread over two namespaces. Groups already equal shallowly are not repeated. |
same line |
:unreferenced-private |
a _-private composed fn-def or type-row no fn-def references (parents, args, list items, return types, type-row fields; string names count — the value-form / repr registries hand names out as strings). A private shape a base-fn declaration names as an arg or return type is referenced too: the corpus gate roots the names base-fn declarations use (lint/names-referenced-by). |
warning |
:unreferenced-public |
corpus gate only (bb graph-lint, :check-public? true) — a PUBLIC composed fn-def nothing outside a tests namespace references is shipped vocabulary with no witness. The finding asks for a caller, or a :vocabulary line in tools/graph-reachability.edn naming the lesson or doc the name is for (the surface audit found nine such names that had quietly died; a public fn-def used to be a live root by definition). The editor’s ⚐ lens never files it: in a user’s graph a public fn-def IS the entry point. |
warning |
:unreachable-private |
a _-private fn-def that IS referenced, but only from fn-defs no live root reaches — the rest of a dead cluster whose head is the :unreferenced-private finding. Live roots: every public fn-def, type-row and base-fn declaration, the by-name entry points, the platform’s own rows. Deleting the head no longer leaves a trail of one new finding per round. |
warning |
:shadowed-override |
a fn-def re-binds an arg to exactly the value its closest ancestors already bind (closest-fn-wins over the parent closure; two parents that disagree leave nothing to restate). A bare ref, a {:value …} / {:ref …} spec or a scalar literal counts; a type pin, a rename, a doc-only spec or a list binding (which appends to the chain) says something new and does not. One finding per fn-def, naming the args. |
warning |
:fan-in-extract-parent |
≥ 2 named fn-defs with the same parents bind ≥ 1 identical value — PACKAGES.md § 1’s extraction rule. Each fn-def’s shared bindings (those a sibling repeats) are a candidate parent; the group is every sibling that binds all of it, reported once under its heaviest candidate. A group that is the same definition outright is :duplicate-definition’s. |
same line as the duplicate rules |
:deep-hierarchy |
a chain of composed fn-defs deep-hierarchy-depth (8) or more levels above its base-fn, reported at the chain’s TIP only — PACKAGES.md § 4 puts the justification line at 6, and the shipped corpus justifies its 6–7-level chains (the MCP surface’s tool envelopes carry a concept per level), so the engine speaks two levels past that line. |
warning |
Weight is the number of bound values a shared structure carries:
a ref or a non-nil literal counts one, an inline fn-def counts one
plus its own args, a rename ({:as …}), a type pin and :default
nil count nothing. graphden.lint.core/warning-weight (3) is the
line between “a copied graph” and “two accessors that happen to read
the same key” — {:parent :get :args {:coll {:as :row} :key {:value
:id} :default nil}} written twice is the let-rule’s separate child
per code path, not copy-paste, and is not filed.
Every finding is a warning. The engine files nothing it would not
ask the author to act on: a “lighter” tier of matches nobody should
extract would be a false recommendation, and the first-party corpus
must pass its own linters outright — bb graph-lint is green at zero
findings, not zero warnings. (Previously the sub-line matches
were filed as info “for calibration”; 517 of them sat there, and the
calibration they offered was that the line was right.) There is no private-alias rule: a private fn-def that only
renames its parent is the let-rule’s “separate child per code path”,
and listing it would be noise dressed as a finding.
What the duplicate rules deliberately do not treat as findings:
_anon-<hash> / nameless fn-defs are
per-use-site by design (graphden-fn-design § 2).anonymous-hash.{:name :_merge-body :parent :parse-json-body}
ten times over) — weight 0. Naming a parent per handler is the
sanctioned way to give each code path its own child.warning duplicate-after-expansion 3 fn-defs are the same graph once their
private helpers are expanded (17 bound values): app.editor/_pstats-day-avg-cell,
app.editor/_pstats-fn-avg-cell, app.editor/_pstats-org-avg-cell — extract a
shared parent and inherit it
The fix is the DRY rule from PACKAGES.md § 1:
keep one definition and either reference it (when the use sites are
different requests / different :map callbacks — the value is not
shared at runtime, only the definition is) or extract it as a parent
and inherit it (when each site must stay its own entity). A
cross-namespace duplicate gets a public name in the lower-level
namespace — a _-private referenced from another namespace is no
longer private (graphden-fn-design § 10).
What the lint deliberately does NOT re-check, because another layer already rejects or records it — a rule here would be a second copy of the same verdict:
schema/services, SERVICES.md);:expects-effects does not
declare — :types/expects-effects-drift, a hard reject at package
sync and a recorded diagnostic (the ⚠ type errors chip) on a user write;[:secret T] (SECRETS.md), a type error, not a style
finding.The sweep that shipped the lint brought the corpus from 131 warnings to zero. The shapes it found, for calibration:
_pstats-{day,fn,org}-*);?path=, the
known-path check and the classpath baseline (238 bound values twice);_parse-{bli,bnd,fn-slot,ns}-form-*-fragment) and the
update handler’s apply stage re-deriving what its parse stage
already had;<span hidden> placeholders, two deploy-config :hub-url
reads, three “(str (:name body))” wrappers per handler.The sweep that shipped the fan-in rule found 24 warning
groups (0 after): mostly :zipmap record constructors written per
site with the same :keys (error envelopes in branches / secrets /
prefs / registry, the execute and value-form parse records shared by
the HTTP body parse, the editor previews and the MCP tools — now
:execute-parsed-record, :value-form-record, :create-branch-record),
six hand-built {:status 200 :headers …} responses that were
:json-ok-response, an :if test repeated across two branches
(_dispatched-merge, _mk-on-executor, _mcp-with-read-fn), two
div popover bodies that became :plain-div children, and the diff
routes’ guard chain, which the two routes now {:append …} their apply
clause to. :shadowed-override and :unreachable-private fired
nothing on the corpus; :deep-hierarchy starts two levels above the
MCP tools’ chains.
bb graph-lint --similar also reports structural template similarity.
It expands private helpers and compares the resulting parent, operation,
slot, list, type, effect and binding-policy structure while allowing
terminal text or number literals to differ. The output names the fn-defs
and the paths of differing literals, never their values. This is a review
candidate, not proof of semantic equivalence or permission to merge the
functions: a differing get key, for example, may be essential. The
suggestion requires at least four expanded fn-defs and three differing
literal paths, so short accessors do not become noise. Guard branch
values and public references stay exact, including through private helpers.
The advisory never changes the normal gate verdict or live lint. Each
subject has finite expansion limits (24 private levels, 512 expanded
fn-defs, 128 structural levels, 32768 structural visits). A cycle or
limit skips the whole subject; the report gives analyzed/total counts
and skip reasons, and bb graph-lint --similar --details lists up to
50 skipped identities. Zero candidates only describes analyzed subjects.
bb graph-lint is in bb ci (group :clj, diff-scoped to
fns.edn / the engine / the reachability registry). Warnings fail
it unless listed in graphden.lint.corpus/allowed-warnings with a
reason; an allowlisted finding that stops firing fails it too — the
same two-way contract as the type-check sweep’s allowlist, so the
list cannot rot. Exemptions for :unreferenced-private come from
tools/graph-reachability.edn (:roots, :registry-fns,
:vocabulary) — the fn-defs src/ runs by name.
The lint is local (each rule reads one fn-def and its direct
references); the global dead-code question — “is this reachable
from any root at all” — stays with tools/reachability_audit.clj,
which BFS-walks from the same registry.
bb native-inventory > target/native-inventory.edn produces advisory source
data for reviewing logic hidden behind base functions. It reads literal
impls registrations and their fns.edn declarations, then uses the pinned
clj-kondo analyzer and existing defbase hook to resolve native var usages.
It does not evaluate package code, connect to a database, or run graph roots.
The EDN report contains registered graph identities, implementation symbols,
declared types/effects, registration metadata (including taint), native source
locations and dependency edges. :entry-location points to the registration
value (the implementation symbol or metadata map), with that anchor stated
explicitly; :registration-map-location points to the enclosing map. Values
without source metadata have an unresolved entry location, not the map’s
location disguised as an exact entry location. Each registration has one
shortest helper path per reachable source var. Paths follow calls and var values, so a
callback passed to a higher-order function remains visible. These paths show
static dependencies, not proof that a callback executes. Kondo may also infer
a call at a callback’s source position. Lexically shadowed symbols are not
mistaken for same-named native helpers.
The report embeds the existing tools/graph-reachability.edn registry for
review context; the reachability audit remains responsible for its roots and
external-consumer rules. The inventory never declares a function pure, dead,
or suitable for graph composition. Reviewers must identify the actual
parse/validate/decision/formatting seam and preserve security, transaction,
runtime and resource-budget boundaries.
Coverage is deliberately explicit: dynamic registration is unsupported, unresolved var usages remain edges, external library vars are leaves, and dynamic dispatch is not resolved. Macro analysis is limited to kondo and its configured hooks. Helper traversal stops at depth six or 128 source vars per entry and reports truncation; cycles terminate. An empty path is not evidence of an atomic primitive. Analyzer findings accompany the report, while missing analysis is a hard error. The inventory is advisory; its regression selftest runs in CI when the analyzer, inventory, or task configuration changes.
The coverage summary is also printed to stderr, leaving stdout as EDN. It
counts depth and node-limit reasons separately (an entry can hit both).
The nested :coverage :corpus retains those totals over all registrations,
even in a targeted report, using the requested traversal limits.
For a focused review with larger traversal limits:
bb native-inventory --entry app.reprs/tabulate-records --max-depth 12 --max-nodes 512 > target/tabulate-inventory.edn
This still analyzes the source corpus to resolve aliases, but includes only
the selected registration and its visited source vars in the output. Reports
are generated artifacts; do not commit them. Every entry stays :unreviewed
even when traversal completes: neither a complete nor a truncated path gets
an automatic atomic/native classification.
:source-identity records Git HEAD, its committed tree, an explicit dirty
flag, and a SHA-256 fingerprint of the actual source/package bytes, analyzer
configuration/hooks, dependency declaration, reachability registry and
inventory implementation. The fingerprint includes untracked inputs and
excludes kondo caches. A dirty report does not claim to describe the committed
tree. Compare identities before reusing review evidence; a matching HEAD
alone is insufficient. The scanner compares identity before and after its
analysis and fails if inputs changed during the run.
pg_trgm
— those buy fuzzy name similarity, which is not a structural
question. (Both ARE available on the managed Postgres the cloud
runs, should a “similar description” hint ever be wanted.)types.diagnostics already sets the
rule — derived, in-memory, recomputed on write. The lint follows it.lint.graph/lint-branch keeps
a state per (org, branch, concealed set) (a small LRU — each tenant org
reads its own org-sliced view, memoised per snapshot so its identity
holds between writes; a fn whose composition the viewer may not see —
SECURITY_MODEL.md layer 9 — lints as a leaf, so no
finding states how it is built): the last snapshot object, its :ns
rows, the per-fn EDN fn-defs, the engine’s memos and the findings. A
read with the same snapshot object and the same :ns rows answers
from it. After a write the
new snapshot is diffed against the old one row by row by identity
(a write splices fresh row objects for the fns it touched and keeps
every other object — executor.context/splice-graph-cache!), so the
fns whose rows moved are known without a walk; those fns and the fns
that reference them (a renamed target changes the referrer’s
spelling) are rebuilt as EDN and handed to
lint.core/lint-with-state as changed. The engine drops the memos
of the changed keys plus their referrer closure — a deep signature
expands the privates it reaches, an inherited value is read off the
ancestors, a chain depth off the parents — recomputes only those on
demand, and runs the rules as one pass of lookups and set operations
over the memos. A write costs its referrer closure, not the graph.
A namespace change (every dotted path may have moved — a :ns write
moves no graph row and :ns is not branch-versioned, so every read
re-reads the :ns rows and compares them: that holds on every branch
and on every pod, where a write-time invalidation would reach only the
writer’s), a moved
type-row or base-fn (the referrer index only knows composed fn-defs),
or a first read lints from scratch through the same code with
everything stale, and
incremental-state-equivalence-test pins that the two agree._helper is
unreferenced until the next write points at it, so refusing the row
would break ordinary editing. Its subject is also not a row: a
signature is the fn-def after branch resolution (version rows,
soft-deletes, merge-on-read) and after the whole write unit landed —
a per-row check sees half a fn-def and every branch’s rows at once.
One engine over EDN fn-defs serves the corpus (no DB) and the live
branch alike; a SQL twin would be a second implementation of the
same rules.Findings reach the author as an Explorer filter chip and an Inspector section (the Lint tab shipped in a drawer under the canvas and was retired the next day, once the problem chips landed; the Tests and Debug panels followed the same day and the drawer is gone).
GET /api/lint is the JSON read (same base-fn as
the section), cached client-side (editor-problems.js)
and re-primed per graph load, after runs and after an Inspector
action; the chip counts findings, a namespace row counts its fns
with findings, a fn row and its card carry ⚐N. The response carries
a weak ETag over the JSON and Cache-Control: no-cache, so a
re-prime after a run that changed nothing is a conditional request
answered 304 (api-lint-handler — an :if over :header-get
"if-none-match", :not-modified-response on a match).#hash links, the engine’s message, Not an issue; the
branch’s hidden entries naming the fn with Restore. The two
actions POST to /partials/inspector-lint/{suppress,restore} which
render the section back.Suppression lives in the graph. “Not an issue” POSTs the finding’s
key (rule + the sorted member fn-ids); the handler appends
{:rule :fn-ids} to the value of the root fn lint-suppressions — a
:const created on first use through the ordinary CRUD write unit, so
it is versioned per branch, merges with the branch, and is visible and
editable on the canvas like any fn. The key is the member ids:
renaming a member keeps the suppression, adding a third copy is a new
finding. No new entity, no new table, no derived state persisted —
only what the author explicitly said.
The flow is graph composition (app/editor-panels/fns.edn _plint-*
for the store and the entry, app/editor-provenance/fns.edn
_insp-lint-* for the section) over one base-fn,
:branch-lint-findings, whose impl is a single
lint.graph/lint-branch call plus the coercion of its findings to wire
data; :branch-lint-warnings reshapes each into a display row in the
graph. The section is parametrised by
:suppressed so the POST handlers render from the list they just
wrote — the store’s own thunk was forced before the write
(ADR-thunk-once). Every reader lints the per-ctx graph snapshot: a
write splices it inline before its response returns, and a load-on-miss
that a write outran is discarded rather than installed
(executor.context/fill-graph-cache!, epoch-guarded), so a read right
after an edit is the post-edit graph.