Shotness analyzer reference¶

The shotness analyzer measures structural hotness -- the change frequency of individual code entities (functions, methods, classes) across Git history, at the UAST node level.

For the conceptual model — what node-level hotness and coupling mean and how coupling strength is computed — see Understanding structural hotness. To run it, see the Quick start.

What an entity is¶

An entity is a declaration the structural DSL selects anywhere in a file's UAST — by default every node carrying the Function role, which covers top-level functions, class methods (Java, C#, TypeScript, JavaScript, Python, …), Go receiver methods and nested functions. Each entity is identified by three things:

Qualification uses the enclosing Class, Struct, Interface, Enum, Function and Method declarations (a Java method f in class A is A.f; a Python def inner inside def outer is outer.inner), and the receiver type of a method declared as func (a *A) String() (A.String). Two String() methods on two receivers are therefore two entities. A node whose name DSL yields nothing (an anonymous lambda) is not an entity.

Rust impl methods are qualified only by their enclosing module-level declarations: the mapping does not expose the impl target, so fn m in impl A is the entity m. Mappings that set no props.name on declarations (the real-world set in the shape contract does) yield no entities for that language.

Entity lifecycle¶

The walk visits the commit window oldest-first and records, per commit, what the commit did to each entity; every output format is a replay of those records.

The report therefore lists exactly the entities that exist at the newest commit of the window, each with the number of window commits that changed it. An entity removed and later re-added under the same name is a new entity.

--shotness-keep-ended (config key history.shotness.keep_ended) keeps every entity the window saw instead: the ones that no longer exist are marked "ended": true and keep their counts and couplings, the aggregate adds ended_nodes, and an entity removed and declared again under the same name and file is live again with its history. Hotspots and hot_nodes count only live entities, and the plot pages show only live ones. On long histories this grows the report: on 31,923 kubernetes commits the shotness report goes from 256 MB to 859 MB (18,499 ended entities, couplings 1.06 M → 3.45 M).

Bounds shared with every history analyzer: blobs larger than 256 KiB are not parsed (the file's entities are neither born nor touched by that commit), and a commit whose raw tree diff exceeds --max-changes-per-commit (default 10 000) is dropped before any analyzer sees it. A commit touching more than 500 entities counts the touches but skips the pairwise coupling update (a mass refactor is coupling noise).

Configuration options¶

Both expressions are compiled before the walk starts: an expression that does not parse is a flag error (invalid --shotness-dsl-struct "rfilter(": DSL parse error: …) and no report is produced. An empty value means the default. The DSL grammar — filter over the direct children, rfilter / rmap over the whole subtree, field access such as .props.name — is documented under uast query.

The structural query must be recursive to see methods: filter(...) looks at the file node's direct children only, so --shotness-dsl-struct 'filter(.roles has "Function")' tracks top-level functions and nothing inside a class.

Custom DSL examples¶

codefang run -a history/shotness --shotness-dsl-struct 'rfilter(.roles has "Class")' .

codefang run -a history/shotness --shotness-dsl-struct 'rfilter(.roles has "Interface")' .

codefang run -a history/shotness --shotness-dsl-name '.type' .

Methods carry the Function role, so the default already tracks functions and methods together.

Output formats¶

The shotness analyzer supports json, yaml, text, ndjson, timeseries, compact and plot output.

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Shotness Analysis                              42 nodes   ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

  Summary
  ──────────────────────────────────────────────────────────
  Total Nodes            42
  Total Changes          385
  Avg Changes/Node       9.2
  Total Couplings        156
  Avg Coupling Strength  34%
  Hot Nodes              8

  Hottest Functions
  ──────────────────────────────────────────────────────────
  Engine.processPayment  [████████████████████░] 1.0  (42 changes)
  Engine.validateInput ( [████████████████░░░░░] 0.8  (34 changes)

  Risk Assessment
  ──────────────────────────────────────────────────────────
  Engine.processPayment  HIGH    (42 changes)
  Engine.validateInput ( HIGH    (34 changes)

  Strongest Couplings
  ──────────────────────────────────────────────────────────
  Engine.processPayment ↔ Engine.validateInput   85%  (12 co-changes)
  handleRequest  ↔ parseBody       72%  (8 co-changes)

{
  "node_hotness": [
    {
      "name": "Engine.processFile",
      "type": "Method",
      "file": "pkg/core/engine.go",
      "change_count": 42,
      "coupled_nodes": 3,
      "hotness_score": 1.0
    }
  ],
  "node_coupling": [
    {
      "node1_name": "Engine.processFile",
      "node1_file": "pkg/core/engine.go",
      "node2_name": "validate",
      "node2_file": "pkg/core/engine.go",
      "co_changes": 15,
      "coupling_strength": 0.36
    }
  ],
  "hotspot_nodes": [
    {
      "name": "Engine.processFile",
      "type": "Method",
      "file": "pkg/core/engine.go",
      "change_count": 42,
      "risk_level": "HIGH"
    }
  ],
  "aggregate": {
    "total_nodes": 3,
    "total_changes": 105,
    "total_couplings": 3,
    "avg_changes_per_node": 35.0,
    "avg_coupling_strength": 0.42,
    "hot_nodes": 2
  }
}

node_hotness:
  - name: Engine.processFile
    type: Method
    file: pkg/core/engine.go
    change_count: 42
    coupled_nodes: 3
    hotness_score: 1.0
node_coupling:
  - node1_name: Engine.processFile
    node1_file: pkg/core/engine.go
    node2_name: validate
    node2_file: pkg/core/engine.go
    co_changes: 15
    coupling_strength: 0.36
hotspot_nodes:
  - name: Engine.processFile
    type: Method
    file: pkg/core/engine.go
    change_count: 42
    risk_level: HIGH
aggregate:
  total_nodes: 3
  total_changes: 105
  total_couplings: 3
  avg_changes_per_node: 35.0
  avg_coupling_strength: 0.42
  hot_nodes: 2

Metrics reference¶

Node hotness¶

Node coupling¶

Aggregate¶

See also¶

• Understanding structural hotness — the mental model, algorithm, architecture, interpretation, and limitations.
• uast query — the DSL the two options are written in.
• Quick start — run history analysis.