seamcheck 0.1.0__py3-none-any.whl

seamcheck/AGENTS.md

@@ -0,0 +1,96 @@
+# Seamcheck — instructions for an AI agent
+
+Seamcheck is a static-analysis tool that maps what a Django + JavaScript project connects
+to what: which URLs exist, which views they route to, which `fetch()` calls resolve to
+them, which DOM elements the JavaScript writes, and which CSS rules and design tokens
+anything still references.
+
+You are likely reading this because someone wants you to use it before committing, or to
+act on something it reported. Read the four statuses first — the whole tool turns on them.
+
+## The four statuses, and the one that matters most
+
+| Status | Means | What you should do |
+|---|---|---|
+| `connected` | Something reaches it, and the evidence is attached | Nothing |
+| `unused` | **Both** sides of the contract are observable and nothing uses it | Safe to investigate for removal |
+| `unresolved` | Something reaches for it and it does not exist | Usually a real bug — fix it |
+| `uncertain` | The scan found **no evidence either way** | **Do not act on it** |
+
+**`uncertain` is not a soft `unused`.** It means the scan cannot see the evidence that
+would settle the question — a page URL reached by `<a href>`, a class applied by code the
+extractor does not read. Deleting something because it is `uncertain` is the single most
+damaging thing you can do with this tool's output. If a human asks you to "clean up
+everything Seamcheck found", ask them whether they mean the `unused` and `unresolved`
+findings, and say plainly that `uncertain` is not a finding.
+
+Every symbol carries the file, the line, and the snippet that produced it. **Quote that
+evidence when you report a finding.** A claim without its snippet is not actionable.
+
+## Commands
+
+```bash
+python manage.py seamcheck                       # scan + human summary
+python manage.py seamcheck --check               # exit 1 on blocking findings
+python manage.py seamcheck --check --format markdown   # digest AND exit code
+python manage.py seamcheck --format markdown     # digest for a chat or PR
+python manage.py seamcheck --format map          # the UI: the map plus the
+                                                             # review sections, one file
+python manage.py seamcheck --format map --since REF    # what changed
+python manage.py seamcheck --format map --serve          # open it from a phone on this wifi
+python manage.py seamcheck --format map --serve --tunnel  # ... or off it
+python manage.py seamcheck --backfill 20   # scan the last 20 commits, so the
+                                                       # map's commit picker has history
+python manage.py seamcheck --backfill 20 --backfill-ref development
+python manage.py seamcheck --format json         # the whole graph
+python manage.py seamcheck --explain <symbol-id> # one symbol's evidence
+python manage.py seamcheck --triage <symbol-id> --status approved --reason "..."
+```
+
+A full scan takes roughly 15 seconds. `--check` is the CI gate: it exits 1 only on
+`unresolved`/`unused` findings that are untriaged or explicitly confirmed, and never on
+`uncertain`.
+
+## Over MCP
+
+If the MCP server is attached, prefer these over shelling out:
+
+- `seamcheck_check(repo_root)` — `{passed, new_unresolved, new_unused, triage_invalidated, counts}`
+- `seamcheck_report(fmt, repo_root)` — the rendered digest (`terminal`, `markdown`, `html`)
+- `seamcheck_explain(symbol_id, repo_root)` — one symbol's evidence as markdown
+- `seamcheck_triage(symbol_id, status, repo_root, reason)` — record a disposition
+
+## The workflow you are probably being asked to run
+
+1. `--check` before the commit. If it exits 0, say so in one line and stop.
+2. If it exits 1, `--explain` each reported id and decide, per finding:
+   - **a real defect** → fix it, quoting the evidence in your explanation
+   - **correct detection, deliberate code** → `--triage <id> --status approved --reason "..."`
+   - **the tool is wrong** → say so and why; that is a bug report worth making
+3. A `triage invalidated` line means a human dispositioned that finding earlier and the
+   underlying evidence has since changed. **Re-read the code before re-approving it.**
+
+## Known gaps — do not over-trust these
+
+The tool is honest about what it cannot see, and so should you be:
+
+- **CSS selectors reported `uncertain`** are not dead code. Class-applying JavaScript is
+  read (`className`, `classList`, `setAttribute`, markup strings), but coverage is not
+  proven complete.
+- **Response fields** are matched one view against a whole consuming module, so a field can
+  be proven read but never proven unread.
+- **WebSocket payloads, Celery tasks, Redis keys and Stripe hooks are not traced at all.**
+  Anything reached only through those is invisible to the scan.
+- **A commit that changed no connection reports nothing.** The graph holds URLs, views,
+  calls, selectors and tokens - not values. A commit that adds an entry to a constant
+  correctly shows no change; that is not the picker failing.
+- **Selectors and fetch targets built at runtime** are `uncertain` by design, never guessed.
+
+## Rules for you specifically
+
+- Never delete code because a symbol is `uncertain`.
+- Never report a finding without its `file:line` and snippet.
+- Never claim the scan is clean because a command exited 0 — check that it actually ran and
+  what it counted.
+- If you are asked to fix a multi-writer element, the fix is to pick one canonical owner and
+  route the others through it, not to patch the writer you happened to find first.

seamcheck/api.py

@@ -0,0 +1,315 @@
+"""The one implementation the CLI, the MCP server, and any future UI all call."""
+
+from __future__ import annotations
+
+import datetime as dt
+import glob
+import os
+import pathlib
+
+from django.conf import settings
+
+from seamcheck.diff import DiffResult, diff_graphs
+from seamcheck.graph import Graph, Status, relativise
+from seamcheck.pipeline import run_scan
+from seamcheck.roots import discover_css_files, discover_js_roots, tailwind_classes
+from seamcheck.snapshot import current_git_sha, load_snapshot, save_snapshot
+from seamcheck.triage import (
+    TriageEntry,
+    TriageStatus,
+    apply_triage,
+    fingerprint_for_symbol,
+    has_blocking_findings,
+    load_triage,
+    save_triage,
+)
+
+
+def _config() -> dict:
+    return getattr(settings, "SEAMCHECK_CONFIG", {})
+
+
+def _js_roots(config: dict, repo_root: str) -> tuple[list[str], str]:
+    if "js_entry_files" in config:
+        return list(config["js_entry_files"]), config.get("js_project_root", repo_root)
+    roots = discover_js_roots(
+        vite_config=os.path.join(repo_root, "vite.config.js"),
+        templates_root=os.path.join(repo_root, config["templates_root"]),
+        static_root=os.path.join(repo_root, "pointless", "static"),
+    )
+    return roots, repo_root
+
+
+def _entry_point_files(config: dict, repo_root: str) -> set[str]:
+    if "entry_point_files" in config:
+        return set(config["entry_point_files"])
+    return {
+        os.path.abspath(path)
+        for prefix in config.get("first_party_prefixes", [])
+        for path in glob.glob(os.path.join(repo_root, prefix, "**", "*.py"), recursive=True)
+        if "migrations" not in path
+    }
+
+
+def scan(repo_root: str = ".") -> Graph:
+    config = _config()
+    js_entry_files, js_project_root = _js_roots(config, repo_root)
+    asgi_module = config.get("asgi_module")
+    asgi_file = (
+        os.path.join(repo_root, asgi_module.replace(".", os.sep) + ".py") if asgi_module else None
+    )
+    templates_root = config.get("templates_root")
+    template_files = (
+        [str(p) for p in pathlib.Path(repo_root, templates_root).rglob("*.html")]
+        if templates_root and os.path.isdir(os.path.join(repo_root, templates_root))
+        else []
+    )
+    css_root = config.get("css_source_root")
+    css_files = (
+        discover_css_files(os.path.join(repo_root, css_root))
+        if css_root and os.path.isdir(os.path.join(repo_root, css_root))
+        else []
+    )
+    build_output = config.get("tailwind_build_output")
+
+    return relativise(run_scan(
+        urlconf_module=config["urlconf_module"],
+        js_entry_files=js_entry_files,
+        js_project_root=js_project_root,
+        entry_point_files=_entry_point_files(config, repo_root),
+        asgi_file=asgi_file if asgi_file and os.path.isfile(asgi_file) else None,
+        first_party_prefixes=config.get("first_party_prefixes"),
+        app_labels=[label.split(".")[0] for label in config.get("app_configs", [])] or None,
+        template_files=template_files,
+        css_files=css_files,
+        tailwind_build_classes=(
+            tailwind_classes(os.path.join(repo_root, build_output)) if build_output else set()
+        ),
+    ), repo_root)
+
+
+def explain(graph: Graph, symbol_id: str) -> str:
+    symbol = next((s for s in graph.symbols if s.id == symbol_id), None)
+    if symbol is None:
+        return f"No symbol with id `{symbol_id}` in the current scan."
+    lines = [
+        f"## {symbol.label}  ({symbol.kind})",
+        "",
+        f"- **status:** {symbol.status.value}",
+        f"- **where:** {symbol.file}:{symbol.line}" if symbol.file else "- **where:** (not a file)",
+        f"- **chain:** {' -> '.join(symbol.chain)}" if symbol.chain else "",
+        "",
+        "```",
+        symbol.snippet,
+        "```",
+    ]
+    if symbol.note:
+        lines += ["", f"> {symbol.note}"]
+    return "\n".join(line for line in lines if line != "")
+
+
+def diff_against(graph: Graph, ref: str, repo_root: str = ".") -> tuple[DiffResult | None, str, str]:
+    """Diff `graph` against the snapshot for `ref`, or say plainly that there isn't one.
+
+    Returns `(result, sha, message)`. `sha` is the commit `ref` actually resolved to -
+    the baseline the diff describes, which is not necessarily HEAD - so a caller that
+    needs to name that commit (the report header, "NEW SINCE ...") never has to
+    re-resolve `ref` itself and risk naming the wrong commit. `sha` is `""` only when
+    `ref` itself could not be resolved at all.
+    """
+    try:
+        sha = current_git_sha(repo_root) if ref == "HEAD" else _rev_parse(ref, repo_root)
+    except Exception as error:  # noqa: BLE001 - surfaced to the user, never swallowed
+        return None, "", f"No baseline: could not resolve `{ref}` ({error})."
+
+    baseline = load_snapshot(sha, repo_root)
+    if baseline is None:
+        return None, sha, f"No baseline snapshot stored for {sha[:12]} yet - nothing to diff against."
+    return diff_graphs(baseline, graph, load_triage(repo_root)), sha, ""
+
+
+def _rev_parse(ref: str, repo_root: str) -> str:
+    import subprocess
+
+    return subprocess.run(
+        ["git", "-C", repo_root, "rev-parse", ref], capture_output=True, text=True, check=True
+    ).stdout.strip()
+
+
+def check(repo_root: str = ".", graph: Graph | None = None) -> dict:
+    if graph is None:
+        graph = scan(repo_root)
+    entries = load_triage(repo_root)
+    graph = apply_triage(graph, entries)
+    result, _, message = diff_against(graph, "HEAD", repo_root)
+
+    def _ids(symbols):
+        return [{"id": s.id, "label": s.label, "kind": s.kind, "note": s.note} for s in symbols]
+
+    return {
+        "passed": not has_blocking_findings(graph, entries),
+        "message": message,
+        "new_unresolved": _ids(result.new_unresolved) if result else [],
+        "new_unused": _ids(result.new_unused) if result else [],
+        "triage_invalidated": result.triage_invalidated if result else [],
+        "counts": {
+            status.value: sum(1 for s in graph.symbols if s.status is status) for status in Status
+        },
+    }
+
+
+def report(
+    repo_root: str = ".", fmt: str = "terminal", ref: str = "HEAD", graph: Graph | None = None
+) -> str:
+    """Render the report. One model, chosen serializer - ordering lives in report.py."""
+    from seamcheck.renderers import html as html_renderer
+    from seamcheck.renderers import markdown as markdown_renderer
+    from seamcheck.renderers import terminal as terminal_renderer
+    from seamcheck.report import build_report
+
+    renderers = {
+        "terminal": terminal_renderer.render,
+        "markdown": markdown_renderer.render,
+        "html": html_renderer.render,
+    }
+    if fmt == "map":
+        return _render_map(repo_root, ref)
+    if fmt == "console":
+        # The review sections live inside the map now: one document, one link, one render
+        # of the same scan. Kept as an alias so an existing caller does not break.
+        return _render_map(repo_root, ref)
+    if fmt not in renderers and fmt not in ("map", "console"):
+        raise ValueError(f"Unknown format {fmt!r}. Use one of: {', '.join(sorted(renderers))}.")
+
+    if graph is None:
+        graph = scan(repo_root)
+    diff, baseline_sha, message = diff_against(graph, ref, repo_root)
+    try:
+        sha = current_git_sha(repo_root)
+    except Exception:  # noqa: BLE001 - a report is still useful outside a git checkout
+        sha = "unknown"
+
+    built = build_report(
+        graph=graph,
+        diff=diff,
+        entries=load_triage(repo_root),
+        git_sha=sha,
+        # baseline_sha names the commit the diff was actually taken against - the
+        # resolved `ref`, not `sha` (the commit just scanned). They coincide only when
+        # `ref == "HEAD"` and nothing changed since; conflating them is what made the
+        # header and the "NEW SINCE" heading print the same commit for a real --since.
+        baseline_sha=None if diff is None else baseline_sha,
+        baseline_message=message,
+    )
+    return renderers[fmt](built)
+
+
+def triage(symbol_id: str, status: str, repo_root: str = ".", reason: str = "") -> dict:
+    try:
+        triage_status = TriageStatus(status)
+    except ValueError:
+        allowed = ", ".join(s.value for s in TriageStatus)
+        return {"ok": False, "message": f"Unknown status `{status}`. Use one of: {allowed}."}
+
+    graph = scan(repo_root)
+    symbol = next((s for s in graph.symbols if s.id == symbol_id), None)
+    if symbol is None:
+        return {"ok": False, "message": f"No symbol with id `{symbol_id}` in the current scan."}
+
+    entries = [e for e in load_triage(repo_root) if e.symbol_id != symbol_id]
+    entries.append(
+        TriageEntry(
+            symbol_id=symbol_id,
+            fingerprint=fingerprint_for_symbol(symbol),
+            status=triage_status,
+            who=os.environ.get("USER", "unknown"),
+            when=dt.date.today().isoformat(),
+            reason=reason,
+        )
+    )
+    save_triage(entries, repo_root)
+    return {"ok": True, "message": f"{symbol_id} marked {triage_status.value}."}
+
+
+def write_map(graph: Graph, repo_root: str = ".") -> str:
+    import json
+
+    from seamcheck.graph import graph_to_dict
+
+    path = pathlib.Path(repo_root) / "docs" / "maps" / "connectivity-map.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(graph_to_dict(graph), indent=2), encoding="utf-8")
+    save_snapshot(graph, current_git_sha(repo_root), repo_root)
+    return str(path)
+
+
+def _page_files(repo_root: str) -> dict[str, set[str]]:
+    """Which JS files each page entry reaches. Computed only for the map: the import
+    walk costs ~13s and the CI path has no use for page attribution."""
+    import os as _os
+
+    from seamcheck.extractors.js_extractor import discover_js_files
+    from seamcheck.roots import discover_js_roots
+
+    config = _config()
+    roots = discover_js_roots(
+        vite_config=_os.path.join(repo_root, "vite.config.js"),
+        templates_root=_os.path.join(repo_root, config["templates_root"]),
+        static_root=_os.path.join(repo_root, "pointless", "static"),
+    )
+    return {
+        _os.path.splitext(_os.path.basename(root))[0]: set(discover_js_files([root], repo_root))
+        for root in roots
+    }
+
+
+def _render_map(repo_root: str, ref: str) -> str:
+    js_entry_files, _ = _js_roots(_config(), repo_root)
+    from seamcheck.console import build_console
+    from seamcheck.filetree import build_file_tree
+    from seamcheck.history import commit_series
+    from seamcheck.mapdata import build_map
+    from seamcheck.pagenames import page_names
+    from seamcheck.renderers import map_html
+    from seamcheck.report import build_report
+
+    graph = scan(repo_root)
+    baseline = None
+    baseline_sha = None
+    if ref and ref != "HEAD":
+        try:
+            baseline_sha = _rev_parse(ref, repo_root)
+            baseline = load_snapshot(baseline_sha, repo_root)
+        except Exception:  # noqa: BLE001 - a missing baseline degrades to current mode
+            baseline, baseline_sha = None, None
+    try:
+        sha = current_git_sha(repo_root)
+    except Exception:  # noqa: BLE001
+        sha = "unknown"
+    # One document: the map and the review sections describe the same scan, and a second
+    # render of the same graph bought a second link and nothing else.
+    diff, baseline_message_sha, message = diff_against(graph, ref, repo_root)
+    console = build_console(graph, build_report(
+        graph=graph, diff=diff, entries=load_triage(repo_root), git_sha=sha,
+        baseline_sha=baseline_message_sha, baseline_message=message,
+    ))
+    return map_html.render(
+        build_map(graph, _page_files(repo_root), git_sha=sha,
+                  baseline=baseline, baseline_sha=baseline_sha if baseline else None,
+                  names=page_names(repo_root, _config(), graph),
+                  commits=[
+                      {"sha": entry.sha, "subject": entry.subject, "date": entry.date,
+                       "symbols": entry.symbols, "changed": entry.changed,
+                       "baseline": entry.baseline_sha, "head": entry.sha == sha,
+                       # Capped: a large refactor can change thousands, and a browser
+                       # needs the first screenful, not the whole set.
+                       "changes": entry.changes[:300], "change_total": len(entry.changes)}
+                      for entry in commit_series(repo_root)
+                  ]),
+        console=console,
+        files=[
+            {"path": record.path, "counts": record.counts,
+             "declarations": record.declarations, "known": record.known}
+            for record in build_file_tree(graph, js_entry_files)
+        ],
+    )

seamcheck/apps.py

@@ -0,0 +1,21 @@
+from django.apps import AppConfig
+from django.conf import settings
+
+# Without these, a scan cannot start: they name the URLconf to walk, the templates and
+# static roots to read, and which import prefixes count as this project's own.
+REQUIRED_CONFIG_KEYS = frozenset({
+    "urlconf_module",
+    "templates_root",
+    "first_party_prefixes",
+})
+
+
+def missing_config_keys() -> set[str]:
+    """Required keys absent from SEAMCHECK_CONFIG. Empty when the app can run."""
+    config = getattr(settings, "SEAMCHECK_CONFIG", {})
+    return set(REQUIRED_CONFIG_KEYS) - set(config)
+
+
+class SeamcheckConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "seamcheck"

seamcheck/attribution.py

@@ -0,0 +1,45 @@
+"""Labels that make a finding actionable: which feature, and which page, it belongs to."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from seamcheck.graph import Graph, Symbol
+
+
+def attribute_by_feature(graph: Graph, dom_roots: list[Symbol]) -> dict[str, list[str]]:
+    """Walk outward from each interactive root, labelling everything it reaches.
+
+    "This selector is unresolved" is a fact; "the Purchase button reaches an unresolved
+    selector" is something a person can act on without reading the graph.
+    """
+    outgoing: dict[str, list[str]] = defaultdict(list)
+    for edge in graph.edges:
+        outgoing[edge.from_id].append(edge.to_id)
+        outgoing[edge.to_id].append(edge.from_id)
+
+    labels: dict[str, set[str]] = defaultdict(set)
+    for root in dom_roots:
+        seen = {root.id}
+        queue = [root.id]
+        while queue:
+            current = queue.pop()
+            labels[current].add(root.label)
+            for neighbour in outgoing.get(current, []):
+                if neighbour not in seen:
+                    seen.add(neighbour)
+                    queue.append(neighbour)
+    return {symbol_id: sorted(names) for symbol_id, names in labels.items()}
+
+
+def attribute_by_page(js_symbols_by_entry: dict[str, list[Symbol]]) -> dict[str, list[str]]:
+    """Which bundler entry points reach each symbol.
+
+    A symbol reachable from several entries is shared, which is exactly what makes a
+    change to it risky - so the list is kept, never collapsed to a single owner.
+    """
+    pages: dict[str, set[str]] = defaultdict(set)
+    for entry, symbols in js_symbols_by_entry.items():
+        for symbol in symbols:
+            pages[symbol.id].add(entry)
+    return {symbol_id: sorted(entries) for symbol_id, entries in pages.items()}

seamcheck/classifier.py

@@ -0,0 +1,116 @@
+"""Final status per symbol, from the edges that actually constitute evidence of use."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from seamcheck.graph import Edge, Status, Symbol
+
+# Kinds whose status this module decides. Everything else (signal_receiver, admin_action,
+# template_tag, model, json_field, context_field) arrives already final from its extractor
+# and is passed through untouched rather than re-guessed.
+_OWNED_KINDS = frozenset({"view", "url", "js_call", "fetch_target"})
+
+# DOM and CSS kinds carry their verdict on the edges the matchers produced, so the
+# symbol has to read it back or every one of them reports "uncertain" forever.
+# CONNECTED wins: an element JS writes but CSS never styles is still in use.
+_EDGE_STATUS_KINDS = frozenset(
+    {"dom_attr", "dom_selector", "css_selector", "css_token_def", "css_token_use"}
+)
+
+# A CSS rule is matched against querySelector() calls and template class= attributes.
+# Nothing yet reads the four ways JavaScript applies a class, so 'nothing uses this'
+# is a claim the scan has not earned. Measured on this project: 5,318 selectors would
+# be reported unused while 3,205 class-application sites went unread.
+_UNPROVEN_UNUSED_KINDS = frozenset({"css_selector"})
+_UNPROVEN_UNUSED_NOTE = (
+    "No CSS-side or template-side reference found, but JavaScript that applies classes "
+    "via className, classList.add or setAttribute is not yet scanned - so this is not "
+    "evidence the rule is dead."
+)
+
+_NO_CALLER_EVIDENCE_NOTE = (
+    "No fetch() call resolves here. Not claimed unused: page URLs are reached by browser "
+    "navigation, {% url %} tags and <a href>, and Core Pipeline has no extractor for those "
+    "yet (DOM Wiring plan). Absence of evidence is not evidence of absence."
+)
+
+
+def _from_edges(symbol: Symbol, incoming: dict, outgoing: dict) -> Symbol:
+    touching = incoming.get(symbol.id, []) + outgoing.get(symbol.id, [])
+    if not touching:
+        return symbol
+    statuses = {edge.status for edge in touching}
+    for status in (Status.CONNECTED, Status.UNRESOLVED, Status.UNUSED):
+        if status not in statuses:
+            continue
+        if status is Status.UNUSED and symbol.kind in _UNPROVEN_UNUSED_KINDS:
+            return replace(symbol, status=Status.UNCERTAIN, note=symbol.note or _UNPROVEN_UNUSED_NOTE)
+        return replace(symbol, status=status)
+    return symbol
+
+
+def classify(symbols: list[Symbol], edges: list[Edge]) -> list[Symbol]:
+    by_id = {symbol.id: symbol for symbol in symbols}
+    incoming: dict[str, list[Edge]] = {}
+    outgoing: dict[str, list[Edge]] = {}
+    for edge in edges:
+        outgoing.setdefault(edge.from_id, []).append(edge)
+        incoming.setdefault(edge.to_id, []).append(edge)
+
+    def _sources(symbol_id: str, kind: str) -> list[Edge]:
+        return [
+            edge
+            for edge in incoming.get(symbol_id, [])
+            if (by_id.get(edge.from_id) or Symbol("", "", "", "", "", None, Status.UNUSED, "", [], "")).kind == kind
+        ]
+
+    # Pass 1: a URL is used when a fetch target resolves to it. A url -> view edge is
+    # routing, not usage, so it is deliberately not counted here.
+    url_status: dict[str, Status] = {}
+    for symbol in symbols:
+        if symbol.kind != "url":
+            continue
+        callers = _sources(symbol.id, "fetch_target")
+        url_status[symbol.id] = (
+            Status.CONNECTED
+            if any(edge.status == Status.CONNECTED for edge in callers)
+            else Status.UNCERTAIN
+        )
+
+    result: list[Symbol] = []
+    for symbol in symbols:
+        if symbol.kind in _EDGE_STATUS_KINDS:
+            result.append(_from_edges(symbol, incoming, outgoing))
+            continue
+        if symbol.status == Status.UNCERTAIN or symbol.kind not in _OWNED_KINDS:
+            result.append(symbol)
+            continue
+
+        if symbol.kind == "url":
+            status = url_status[symbol.id]
+            note = symbol.note or (_NO_CALLER_EVIDENCE_NOTE if status is Status.UNCERTAIN else "")
+            result.append(replace(symbol, status=status, note=note))
+            continue
+
+        if symbol.kind == "view":
+            # A view is used when at least one URL routing to it is used.
+            routes = [edge for edge in incoming.get(symbol.id, []) if edge.from_id in url_status]
+            status = (
+                Status.CONNECTED
+                if any(url_status[edge.from_id] is Status.CONNECTED for edge in routes)
+                else Status.UNCERTAIN
+            )
+            note = symbol.note or (_NO_CALLER_EVIDENCE_NOTE if status is Status.UNCERTAIN else "")
+            result.append(replace(symbol, status=status, note=note))
+            continue
+
+        touching = incoming.get(symbol.id, []) + outgoing.get(symbol.id, [])
+        if any(edge.status == Status.UNRESOLVED for edge in touching):
+            result.append(replace(symbol, status=Status.UNRESOLVED))
+        elif any(edge.status == Status.CONNECTED for edge in touching):
+            result.append(replace(symbol, status=Status.CONNECTED))
+        else:
+            result.append(symbol)
+
+    return result