Imports analyzer reference¶

The imports analyzer extracts import and dependency information from source code using UAST parsing. It operates in both static mode (per-file analysis aggregated over a tree) and history mode (tracking import usage per developer over time).

For the conceptual model — what it measures and how the history-mode pipeline works — see Understanding import and dependency analysis. To run it, see the Quick start.

Running static analysis¶

codefang run -a static/imports --format json ./path/to/repo
codefang run -a static/imports --format json --per-file ./path/to/repo
codefang run -a static/imports --format yaml ./path/to/repo
codefang run -a static/imports --format json ./path/to/single/file.go

• The root may be a directory (walked recursively, .git and cache-tagged directories skipped, vendor/generated paths excluded by the path policy, --languages honoured) or a single file.
• Every supported file counts towards Total Files, including files with no imports.
• A root with no analyzable files produces the empty report (status No import data available, Unique Imports 0, Total Files 0) with exit code 0.
• Output is deterministic: two runs over the same tree emit identical bytes.

What counts as one import¶

Each file contributes the set of modules, packages or files its import statements name — once per file, in first-seen order. Aliases, specifier lists and keywords never appear as imports. The aggregate value of an import is the number of files importing it.

Not reported: re-exports (export { x } from './m') and dynamic calls whose argument is not a string literal (require(name)). Kotlin imports are read back from the source span (the Kotlin grammar lowers imports without tokens); both the static and the history path hand the extractor the file bytes.

Classification¶

The yaml and bin formats classify every unique import by the language of the first file that imported it:

external_ratio is external_imports / total_imports.

Configuration options¶

Static mode¶

No configuration options. Uses UAST directly.

History mode¶

No analyzer-specific options. The shared history flags apply: --tick-size (the tick width in hours, default 24), the commit window (--head, --limit, --since, --first-parent), the identity flags (--people-dict, --exact-signatures, --anonymize) and the change filter (--languages, vendor / generated policy). Blobs above 256 KiB are not parsed.

Example output¶

For a tree with a.go (fmt, os) and b.py (import os, sys):

{
  "overall_score_label": "Info",
  "sections": [
    {
      "title": "IMPORTS",
      "score_label": "Info",
      "status": "Found 3 unique imports",
      "metrics": [
        { "label": "Unique Imports", "value": "3" },
        { "label": "Total Files", "value": "2" }
      ],
      "issues": [
        { "name": "os", "location": "", "value": "2", "severity": "info" },
        { "name": "fmt", "location": "", "value": "1", "severity": "info" },
        { "name": "sys", "location": "", "value": "1", "severity": "info" }
      ],
      "score": -1
    }
  ],
  "overall_score": -1
}

{
  "file_path": "b.py",
  "score_label": "Info",
  "status": "Found 2 unique imports",
  "metrics": [
    { "label": "Unique Imports", "value": "2" },
    { "label": "Total Files", "value": "1" }
  ],
  "issues": [
    { "name": "os", "location": "b.py", "value": "1", "severity": "info" },
    { "name": "sys", "location": "b.py", "value": "1", "severity": "info" }
  ],
  "score": -1
}

import_list:
    - path: fmt
      category: stdlib
      is_external: false
    - path: os
      category: stdlib
      is_external: false
    - path: sys
      category: stdlib
      is_external: false
categories:
    - category: stdlib
      count: 3
dependencies: []
aggregate:
    total_imports: 3
    external_imports: 0
    internal_imports: 3
    unique_packages: 3
    external_ratio: 0

codefang run -a history/imports --format json ./path/to/repo

{
  "tick_size": 86400,
  "author_index": ["alice|alice@x.io", "bob|bob@x.io"],
  "imports": {
    "alice|alice@x.io": {
      "go": {
        "fmt": { "0": 1, "2": 1 },
        "net/http": { "2": 1 },
        "os": { "0": 1 }
      }
    },
    "bob|bob@x.io": {
      "go": { "encoding/json": { "1": 1 }, "fmt": { "1": 1 } },
      "python": { "os": { "1": 1 }, "sys": { "1": 1 } }
    }
  }
}

codefang (v2):
  version: ...
  hash: ...
ImportsPerDeveloper:
  tick_size: 86400
  author_index:
    - alice|alice@x.io
    - bob|bob@x.io
  imports:
    alice|alice@x.io:
      go:
        fmt:
          0: 1
          2: 1
        net/http:
          2: 1
        os:
          0: 1
    bob|bob@x.io:
      go:
        encoding/json:
          1: 1
        fmt:
          1: 1
      python:
        os:
          1: 1
        sys:
          1: 1

See also¶

• Understanding import and dependency analysis — the mental model, history-mode architecture, and limitations.
• Quick start — run static and history analysis.