Graphden documentation

Graph lint — structural linters for the graph

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

Rules

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:

Reading a finding

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:

The sweep that shipped the lint brought the corpus from 131 warnings to zero. The shapes it found, for calibration:

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.

Gate

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.

Feasibility notes (why it is shaped this way)

Native helper inventory

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.

Graph engine

The editor: filter chip + Inspector

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).

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.