feat(ezra-graph): dotted-attribute resolution + alias pass + ranking (#54)

[Antman316]

Summary

ezra-graph builds a static code graph over Python/JS files and supports callers, blast-radius, and orphans queries for triage-driven impact analysis.

Changes in this update

• tools/ezra_graph.py: portable defaults, explicit missing-DB errors, dotted-import alias fix, JS declaration self-call fix, and from-package reverse-dependency matching.
• skills/software-development/codebase-semantic-graph/SKILL.md: Hermes-format frontmatter plus When to Use, Quick Reference, Procedure, Pitfalls, and Verification sections.
• tests/tools/test_ezra_graph.py: regression tests for dotted imports without aliases, missing-DB errors, JS declaration self-calls, and reverse-dependency matching.
• tests/skills/test_codebase_semantic_graph.py: validates the skill file's frontmatter and required documentation sections.

Review findings addressed

Review finding	Resolution
Dotted import pkg.submodule without as binds only pkg	collect_top_level_aliases() only stores aliases for explicit as or non-dotted imports; regression test added.
Hard-coded /Users/Prime/... defaults	DEFAULT_DB uses EZRA_GRAPH_DB or get_hermes_home()/ezra/graph/ezra-graph.sqlite; roots use EZRA_GRAPH_ROOTS or Path.cwd().
Query commands silently create missing DB	Added _require_db(); query commands exit clearly when DB is missing.
JS declarations recorded as self-calls	scan_js() skips the declaration name on its own line; caller scope is line-local.
from package import target missed by blast-radius	blast_radius() normalizes module.imported for exact matching.
Skill doc uses absolute Prime paths / lacks frontmatter	SKILL.md has required frontmatter and portable defaults.
No dedicated skill format test	Added tests/skills/test_codebase_semantic_graph.py.

Test results

$ python3 -m py_compile tools/ezra_graph.py tests/tools/test_ezra_graph.py tests/skills/test_codebase_semantic_graph.py
compile: ok

$ python3 -m unittest tests.tools.test_ezra_graph -v
Ran 9 tests — OK

$ python3 -m unittest tests.skills.test_codebase_semantic_graph -v
Ran 4 tests — OK

Portability statement

• No absolute machine or user paths remain in code or skill docs.
• Database path: EZRA_GRAPH_DB or ~/.hermes/ezra/graph/ezra-graph.sqlite (profile-aware via HERMES_HOME).
• Scan roots: EZRA_GRAPH_ROOTS or --root; default is the current working directory.

Remaining limitations

• JS/TS extraction is regex-based and best-effort.
• blast-radius is static-import based; dynamic dispatch is not captured.
• Full ruff/mypy was not run locally (no project venv in this session). Focused unit tests and py_compile pass.

Ready for maintainer re-review.

[Copilot]

Pull request overview

Adds a new ezra-graph CLI tool to generate/query a lightweight static code graph (imports, symbols, dotted call edges) to support impact analysis across Hermes-related repos, with improved Python dotted-attribute call extraction, import-alias resolution, and ranked caller results.

Changes:

• Introduces tools/ezra_graph.py with refresh, callers, blast-radius, and orphans commands backed by a SQLite schema (v2) and ranking logic for caller output.
• Adds unit tests validating dotted call extraction and basic alias resolution behavior.
• Documents the workflow as a new skill and exposes the CLI via pyproject.toml (ezra-graph = tools.ezra_graph:main).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
tools/ezra_graph.py	New CLI implementation: scanning, alias resolution, schema management, and query commands (ranked callers, blast radius, orphans).
tests/tools/test_ezra_graph.py	Unittest coverage for dotted call path extraction and aliased import resolution.
skills/software-development/codebase-semantic-graph/SKILL.md	New skill documentation describing artifact location, refresh, resolution model, and queries.
pyproject.toml	Adds ezra-graph as an installable console script entry point.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[teknium1]

Thanks for the static-analysis contribution. Current main has no ezra-graph implementation, so this is a new feature rather than a stale bug fix.

Problems

• tools/ezra_graph.py:167-189 mis-resolves dotted imports without as: import pkg.submodule binds pkg, but the code maps it to pkg.submodule. The existing inline finding is valid and still unresolved.
• tools/ezra_graph.py:272-283 records function unused() {} / method declarations as self-calls because CALL_RE sees the declaration name. That makes orphans suppress uncalled JS functions; current also never leaves the last detected function scope.
• blast_radius() stores from package import target as separate module/imported fields at :207-212, but queries only i.module at :394-397; those reverse dependencies are missed.
• The unresolved hard-coded /Users/Prime defaults and query-time DB creation at :23-28, :91-96, and :346-424 make the installed command nonportable. See existing defaults and query DB comments.
• The new skill fails AGENTS.md:882-950 standards: its description is 66 characters at SKILL.md:3, and it lacks the required author/section structure.

Suggested changes

• Add the import and reverse-dependency regression cases; use syntax-aware JS/TS extraction or explicitly limit scope to Python.
• Use portable, profile-aware paths and make query commands require an existing database.
• Modernize the skill and add its required skill test.

Automated hermes-sweeper review.

[Antman316]

All review findings addressed on feat/ezra-graph-dotted-calls-54 @ 65e2824. Focused tests green (9 tool + 4 skill). Ready for maintainer re-review.