nexus-query — Precise Code Structure Query

"Calculate clearly before making changes — numbers speak louder than guesses."

This Skill encapsulates three scripts:

extract_ast.py

git_detective.py

, and

query_graph.py

, into a development assistant tool: generate data on demand and provide precise answers to your questions.

📌 Differences from nexus-mapper

Dimension	nexus-mapper	nexus-query
Purpose	Build persistent project memory for AI ( `.nexus-map/` )	Answer developers' immediate specific questions
Timing	One-time full detection at project initiation	On-demand invocation during development
Output	Structured knowledge base documents	Precise text answers (results in seconds)
Prerequisite	Requires running the complete 5-stage PROBE process	Only requires ast_nodes.json to exist

nexus-query is the lightweight companion of nexus-mapper: If

.nexus-map/

already exists, reuse it directly; if not, run

extract_ast.py

first to generate ast_nodes.json before starting queries.

📌 When to Invoke

Scenario	Invoke?
What classes/methods does this file have, and what does it depend on?	✅
Which files will be affected if I modify this interface/module?	✅
What is the impact scope of this change?	✅
Which module is the true core dependency node in the project?	✅
How is the entire project roughly structured?	✅
User wants to build a complete `.nexus-map/` knowledge base	❌ → Use nexus-mapper instead
No shell execution capability in the runtime environment	❌
No local Python 3.10+ on the host machine	❌

⚙️ Prerequisite: Ensure ast_nodes.json is Available

Before starting a query → Check if ast_nodes.json exists
├── Exists (at .nexus-map/raw/ast_nodes.json or user-specified path) → Proceed with query directly
└── Does not exist → Run extract_ast.py to generate it → Then start query

bash

# Default path (compatible with nexus-mapper's .nexus-map/, interoperable)
AST_JSON="$repo_path/.nexus-map/raw/ast_nodes.json"
GIT_JSON="$repo_path/.nexus-map/raw/git_stats.json"    # Optional

# If ast_nodes.json does not exist, create directory first then generate (takes a few seconds)
mkdir -p "$repo_path/.nexus-map/raw"
python $SKILL_DIR/scripts/extract_ast.py $repo_path > $AST_JSON

# If git risk data is needed (optional, only if .git exists)
python $SKILL_DIR/scripts/git_detective.py $repo_path --days 90 \
  > $GIT_JSON

$SKILL_DIR
is the installation path of this Skill (
.agent/skills/nexus-query
or independent repo path).

Dependency Installation (First Use):

bash

pip install -r $SKILL_DIR/scripts/requirements.txt

🔍 Five Query Modes

bash

# View the class/function structure and import list of a specific file
python $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path>
python $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path> --git-stats $GIT_JSON

# Reverse dependency query: Which modules import this one
python $SKILL_DIR/scripts/query_graph.py $AST_JSON --who-imports <module_or_path>

# Impact scope: Upstream dependencies + downstream dependents (recommended to combine with git-stats)
python $SKILL_DIR/scripts/query_graph.py $AST_JSON --impact <path>
python $SKILL_DIR/scripts/query_graph.py $AST_JSON --impact <path> --git-stats $GIT_JSON

# Identify core nodes with high in-degree/out-degree
python $SKILL_DIR/scripts/query_graph.py $AST_JSON --hub-analysis [--top N]

# Structure summary aggregated by top-level directory
python $SKILL_DIR/scripts/query_graph.py $AST_JSON --summary

--file <path> — File Skeleton Analysis

Output: Classes, methods, line number ranges, all imports (internal imports resolved to real paths). Add

--git-stats

to append change heat and coupled files.

Deep Value: AI can grasp the file structure down to line numbers without reading the source code; it is especially effective for large legacy codebases — a 3000-line legacy module may have dozens of classes, and line-by-line reading is extremely inefficient.

--file

generates the skeleton in seconds, enabling precise jumps by line numbers.

Applicable Scenarios:

Taking over a huge legacy module ("spaghetti code"), build a structure map before making changes
During continuous refactoring tasks, confirm the complete method signatures of the target file to avoid missing other overloads after modifying one
Bug investigation: Quickly confirm the line number range of candidate classes/functions to narrow down the reading range of
```
view_file
```
Code Review: Confirm whether the methods involved in a PR are within the expected boundaries

--who-imports <path or module name> — Reverse Dependency Tracking

Output: All files that reference this module (distinguishing between source code files and test files).

Deep Value: The only command you must run before modifying an interface. Skipping this step when modifying public function signatures, deleting methods, or renaming classes is a gamble that nothing will break.

Applicable Scenarios:

Before deleting functions, modifying signatures, or migrating modules, confirm the "bomb list" — list all callers that need synchronous modifications
During continuous development tasks, after modifying the interface in step 1, confirm which subsequent steps 2~N are affected and plan the work sequence
Determine testing strategies: Only by knowing who depends on the target module can you perform precise regression testing instead of full-scale testing
Evaluate "whether it is worth refactoring this old interface": The more dependents there are, the higher the refactoring cost; 0 dependents = can refactor freely

--impact <path> [--git-stats] — Impact Scope Quantification

Output: Upstream dependencies (who this file references) + downstream dependents (who references this file), finally giving the numbers

X upstream, Y downstream

. Add

--git-stats

to append git risk levels and coupled pairs.

Deep Value: The most practically valuable single command.

0 upstream, 24 downstream

tells you at a glance that this is a base layer, and changes will have the widest impact; a high

upstream

number often means it depends on many things and is prone to chain reactions. When combined with git-stats: high-risk + high downstream = the most dangerous change point currently.

Applicable Scenarios:

Measure the risk and actual workload of a feature modification, which has direct reference value for Sprint estimation/technical debt repayment decisions
Evaluate "whether the current change is a local or global operation" — the downstream number determines the testing scope
During architecture reviews, quantify the impact of "candidate refactoring modules": Which one has the lowest refactoring cost?
Legacy system splitting planning: Leave modules with high downstream dependencies untouched first, and start cleaning from edge modules

--hub-analysis [--top N] — Architecture Core Node Identification

Output: A list of all repository modules sorted by in-degree (how many modules reference it) and out-degree (how many modules it references), directly revealing the true core nodes.

Deep Value: Directory name ≠ importance. A module named

core/

is not necessarily the actual core; true high-coupling nodes are often hidden in unassuming utility classes, data models, or configuration modules. High in-degree = many dependents, high out-degree = depends on many others, both high = "spider web center", the most dangerous to modify.

Applicable Scenarios:

Architecture review: Identify the "star module" — the one that everyone depends on but never appears in the roadmap
Technical debt priority ranking: High in-degree + high git-stats risk = the most worthy refactoring target (high risk, high impact)
Legacy code cleanup entry point: Modules with extremely high out-degree but low in-degree are "isolated nodes" that can be safely replaced or split
New team members taking over the project: First look at the top 5 modules by in-degree; understanding these modules will clarify half of the project's architecture

--summary — Global Directory Aggregation

Output: Statistics on the number of modules/classes/functions/lines partitioned by top-level directory, along with import relationships between regions.

Deep Value: Establish a system layering awareness with one command. Which directory is the "business logic layer", which is the "infrastructure layer", and which is the "test layer" — reading directly from the import relationship graph is more objective than reading any document.

Applicable Scenarios:

First contact with the project (grasp the whole picture in 5 seconds): More objective than reading the README, more structured than manual ls
Identify circular dependency risk areas: Mutual imports between two top-level directories are an architecture smell, and
```
--summary
```
exposes it immediately
Handing over the project to new members: An aggregation table replaces lengthy architecture introduction documents
Evaluate test coverage balance: The ratio of the number of functions in the tests directory to that in the src directory, whether the ratio is reasonable

Scenario Quick Reference

Your Current Question	Which to Use
What classes/methods does this file have, and which lines are they on?	`--file`
Which files need to be modified along with this interface change/function deletion?	`--who-imports`
How many modules will be ultimately affected by this change?	`--impact`
How high is the risk of this change (add git heat)?	`--impact --git-stats`
Which is the true high-coupling center in the project?	`--hub-analysis`
What is the module distribution and hierarchical relationship of the entire project?	`--summary`
During continuous refactoring tasks, check the impact chain after modifying one part	`--who-imports` → `--impact`
Estimate the workload of technical debt transformation	`--hub-analysis` → `--impact`

🧠 Execution Guidelines

Guideline 1: Read References Before Querying

Before using

--impact

--who-imports

to analyze a module, it is recommended to first use

--file

to read its skeleton, understand its responsibilities and existing imports, to avoid misjudging the query results.

Guideline 2: git-stats is a Bonus, Not a Hard Block

When there is no

.git

or insufficient git history, skip

git_detective.py

and only use AST data for queries. Do not stop querying due to the lack of git data; continue with degraded functionality.

Guideline 3: Flexible Path Matching but Needs Verification

query_graph.py

supports path fragment matching (e.g.,

vision.py

can match

src/core/vision.py

). When the result returns

[NOT FOUND]

, first use

--summary

to confirm the module path format existing in the repository, then query again.

Guideline 4: Present Results Directly, Do Not Over-Interpret

The

X upstream, Y downstream

returned by

--impact

are objective numbers; inform the user directly. Do not use vague terms like "may have a large impact" to replace the numbers — let the numbers speak.

✅ Output Quality Self-Check

Confirm the
```
ast_nodes.json
```
path is correct and the file is non-empty before querying
If
```
[NOT FOUND]
```
: Verified the path format with
```
--summary
```
and queried again
```
--impact
```
results: Clearly provided specific numbers for upstream/downstream
```
--who-imports
```
results: Displayed by source code files / test files for better intuitiveness
If
```
--git-stats
```
is used: Explained the meaning of git risk levels (high=many changes within 90 days)

nexus-query

NPX Install

Tags

SKILL.md Content (Chinese)

nexus-query — Precise Code Structure Query

📌 Differences from nexus-mapper

📌 When to Invoke

⚙️ Prerequisite: Ensure ast_nodes.json is Available

🔍 Five Query Modes

--file <path> — File Skeleton Analysis

--who-imports <path or module name> — Reverse Dependency Tracking

--impact <path> [--git-stats] — Impact Scope Quantification

--hub-analysis [--top N] — Architecture Core Node Identification

--summary — Global Directory Aggregation

Scenario Quick Reference

🧠 Execution Guidelines

Guideline 1: Read References Before Querying

Guideline 2: git-stats is a Bonus, Not a Hard Block

Guideline 3: Flexible Path Matching but Needs Verification

Guideline 4: Present Results Directly, Do Not Over-Interpret

✅ Output Quality Self-Check