code-discovery

Code Discovery Tools

When to use: Before writing code that calls existing modules, or when exploring unfamiliar parts of the codebase.

Instead of: Reading entire files to find function signatures, use these scripts.

---

discover_api.py

Purpose: Inspect real module APIs—functions, classes, constants, signatures.

Use when:

• About to call a function but unsure of its parameters
• Exploring a module's public surface
• Verifying an API exists before using it

Usage:

# Text output (human-readable)
python scripts/discover_api.py nomarr.workflows.processing.process_file_wf

# JSON output (machine-readable)
python scripts/discover_api.py nomarr.components.ml --format=json

# Example output:
# ================================================================================
# Module: nomarr.components.ml.ml_embed_comp
# ================================================================================
#
# FUNCTIONS:
#
#   def compute_embeddings(file_path: str, models_dir: str, backbone: str) -> np.ndarray:
#       Compute embeddings for an audio file.

Decision rule: If you're about to read_file a module just to find what functions exist → use discover_api.py instead.

---

discover_import_chains.py

Purpose: Trace import dependencies from a module and detect architecture violations.

Use when:

• Checking if a new import would violate layering rules
• Debugging circular imports
• Understanding what a module depends on

Usage:

# Trace imports from a module
python scripts/discover_import_chains.py nomarr.workflows.library.scan_library_wf

# JSON output
python scripts/discover_import_chains.py nomarr.services.domain.tagging_svc --format=json

# Can also accept file paths
python scripts/discover_import_chains.py nomarr/interfaces/api/v1/library.py

Output shows:

• Full import chain (what imports what)
• Architecture violations (e.g., "workflow imports service")
• Depth-limited to prevent infinite recursion

---

build_code_graph.py

Purpose: Build a complete code graph for dead code detection and reachability analysis.

Use when:

• Checking if code is reachable from entrypoints
• Finding unused functions/classes
• Understanding call relationships

Usage:

python scripts/build_code_graph.py

Output: Writes to scripts/outputs/code_graph.json with:

• Nodes: All modules, classes, functions
• Edges: CONTAINS, IMPORTS, CALLS relationships
• Reachability from interface entrypoints

Use with: check_dead_nodes.py to analyze the graph.

---

Workflow: Discovering an Unfamiliar Module

1. Find the module's API:

   python scripts/discover_api.py nomarr.components.tagging
   

2. Check its dependencies:

   python scripts/discover_import_chains.py nomarr.components.tagging
   

3. Verify no violations before adding imports:

   python scripts/discover_import_chains.py nomarr.workflows.new_workflow_wf
   

---

Common Patterns

Before calling a function

# Instead of reading the whole file:
python scripts/discover_api.py nomarr.persistence.db

# Get exact signature:
# def get_next_job(self, status: str = "pending") -> QueueJobDict | None:

Before adding an import

# Check if it would violate architecture:
python scripts/discover_import_chains.py nomarr.services.domain.tagging_svc

# If you see "VIOLATION: services importing interfaces" → don't add that import

Understanding a subsystem

# Get all public APIs in a package
python scripts/discover_api.py nomarr.components.ml
python scripts/discover_api.py nomarr.components.ml.ml_embed_comp
python scripts/discover_api.py nomarr.components.ml.ml_inference_comp

---

Key Rule

Never guess function names, parameters, or return types.

Use discover_api.py to verify APIs before calling them. This prevents:

• Inventing non-existent functions
• Wrong parameter orders
• Type mismatches