nexus-query

nexus-query — Precise Code Structure Query

When to Invoke

Scenario	Invoke
"What classes/methods does this file have, and what does it depend on?"	Yes
"If I change this interface/module, which files are affected?"	Yes
"How large is the impact radius of this change?"	Yes
"Who are the real core dependency nodes in the project?"	Yes
"What are the main parts of the whole project?"	Yes
The user wants to generate a complete `.nexus-map/` knowledge base	No → use nexus-mapper instead
The runtime environment has no shell execution capability	No
The host machine has no local Python 3.10+	No

Prerequisite: Ensure ast_nodes.json is available

进入查询前 → 检查是否有 ast_nodes.json
├── 有（.nexus-map/raw/ast_nodes.json 或用户指定路径）→ 直接查询
└── 没有 → 运行 extract_ast.py 生成 → 再查询

When generating the AST, supports scan filtering consistent with nexus-mapper :

--exclude-dirs django_static,.go_root Ignore clutter directories by directory name or repository-relative path
--use-gitignore Enable the <repo_path>/.gitignore rules (enabled by default), ignoring the files and directories declared in it
--no-gitignore Do not apply the .gitignore rules; in this case, built-in exclusions and --exclude-dirs

# 默认路径（和 nexus-mapper 的 .nexus-map/ 兼容，可互通）
AST_JSON="$repo_path/.nexus-map/raw/ast_nodes.json"
GIT_JSON="$repo_path/.nexus-map/raw/git_stats.json"    # 可选

# 若 ast_nodes.json 不存在，先创建目录再生成（约数秒）
mkdir -p "$repo_path/.nexus-map/raw"
python $SKILL_DIR/scripts/extract_ast.py $repo_path > $AST_JSON

# 若仓库包含大批静态资源、生成物或杂物目录，可显式追加排除项
python $SKILL_DIR/scripts/extract_ast.py $repo_path \
  --exclude-dirs django_static,.go_root,third_party/assets \
  > $AST_JSON

# 若不希望读取 .gitignore，可显式关闭
python $SKILL_DIR/scripts/extract_ast.py $repo_path \
  --no-gitignore \
  > $AST_JSON

# 若需要 git 风险数据（可选，仅在存在 .git 时）
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 a standalone repo path). extract_ast.py By default, excludes .git/、.nexus-map/、node_modules/、__pycache__/、.venv/、dist/、build/ and other noise directories and files; by default, it also reads <repo_path>/.gitignore, ignoring the files and directories declared in it.--no-gitignore Only disables the .gitignore rules; it does not disable built-in exclusions, nor does it disable --exclude-dirs。

Dependency Installation (First Use)：

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

Five Query Modes

# 文件骨架：类、方法、行号、import 清单
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

# 反向依赖：谁 import 了这个模块（区分源码文件和测试文件）
python $SKILL_DIR/scripts/query_graph.py $AST_JSON --who-imports <module_or_path>

# 影响半径：上游依赖 + 下游被依赖（X upstream, Y downstream）
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

# 全仓库核心节点：按扇入（被引用最多）和扇出（引用最多）排序
python $SKILL_DIR/scripts/query_graph.py $AST_JSON --hub-analysis [--top N]

# 按顶层目录聚合结构摘要
python $SKILL_DIR/scripts/query_graph.py $AST_JSON --summary

Core Value of Each Mode

Mode	One-Sentence Value	Typical Trigger Timing
`--file`	Grasp the file skeleton without reading source code, precise to line numbers	Before taking over a large module; narrow the reading range during Bug investigation
`--who-imports`	The "bomb list" before changing an interface — lists all callers	Must be run before deleting a function/changing a signature/renaming a class
`--impact`	`0 upstream, 24 downstream` See the scope of changes at a glance	Sprint estimation; assess whether the modification is local surgery or global surgery
`--hub-analysis`	Find the真正 high-coupling core without guessing from directory names	Architecture review; technical debt priority ranking
`--summary`	Build a global layered understanding in 5 seconds, more objective than a README	First contact with a project; identify circular dependency risk areas

Scenario Quick Reference

Your Current Question	Which One to Use
What classes/methods does this file have, and on which lines are they	`--file`
If I change this interface/delete a function, which files will change accordingly	`--who-imports`
How many modules will this change ultimately affect	`--impact`
How high is the risk of this change (add git heat)	`--impact --git-stats`
Who are the真正 high-coupling centers in the project	`--hub-analysis`
The module distribution and hierarchy of the whole project	`--summary`
Continuous refactoring; after changing one place, need to see the impact chain	`--who-imports` → `--impact`
Estimate the workload of technical debt transformation	`--hub-analysis` → `--impact`

Execution Guidelines

Guideline 1: Skeleton First, Then Query Use --impact or --who-imports Before analyzing a module, it is recommended to first use --file Read its skeleton, understand its responsibilities and existing imports, and avoid misjudging the query results.

Rule 2: git-stats is a bonus, not a hard blocker When there is no .git or the git history is insufficient, skip git_detective.pyand query using only AST data.

Rule 3: Path matching is flexible but must be verified Path fragment matching is supported (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 that exists in the repository, then query again.

Rule 4: Present results directly, let the numbers speak --impact The X upstream, Y downstream returned is an objective number; tell the user directly, without replacing it with vague phrases like "may have a large impact."