Static Analysis Module API Specification

Version: v1.3.0 | Status: Stable | Last Updated: July 2026

1. Overview

The static_analysis module provides AST-based code analysis for import scanning, architectural layer-boundary violation detection, export auditing, dead code detection, and unused function detection. It operates on Python source files without executing them.

This module exposes only a Python import API — it has no MCP tools. See MCP_TOOL_SPECIFICATION.md.

2. Core Components

2.1 Import Analysis (imports.py)

Layer Constants: Four sets define the architectural hierarchy (from SPEC.md):

• FOUNDATION: config_management, environment_setup, exceptions, logging_monitoring, model_context_protocol, telemetry, terminal_interface, validation
• CORE: cache, coding, git_operations, llm, performance, search, static_analysis, and others
• SERVICE: api, auth, ci_cd_automation, cloud, orchestrator, and others
• SPECIALIZED: agentic_memory, agents, cerebrum, cli, events, utils, and all remaining modules

Functions:

Function	Signature	Returns	Description
get_layer	(module: str) -> str	`"foundation" \	"core" \ "service" \ "specialized" \ "other"` Classify a module by architectural layer
extract_imports_ast	(filepath: Path) -> List[str]	List[str]	Extract imported codomyrmex module names from a single file using AST
scan_imports	(src_dir: Path) -> List[Dict[str, Any]]	List[edge dicts]	Scan all .py files; each edge has src, dst, file, src_layer, dst_layer
check_layer_violations	(edges: List[Dict]) -> List[Dict]	List[violation dicts]	Apply layer rules; violations add a reason field
get_upward_interface_contract	(edge: Mapping[str, Any]) -> str | None	Optional rationale	Resolve an exact file-scoped upward-import contract
audit_upward_interface_contracts	(edges, contracts=UPWARD_INTERFACE_CONTRACTS) -> dict	{"used": [...], "stale": [...]}	Verify that every declared exception still matches an upward edge

Layer violation rules (lower-ranked layers cannot import higher-ranked):

• Foundation (0) must not import Core (1), Service (2), or Specialized (3)
• Core (1) must not import Service (2) or Specialized (3)
• Service (2) must not import Specialized (3)

UPWARD_INTERFACE_CONTRACTS is an immutable registry keyed by exact source module, destination module, and repository-relative file. A matching entry exempts only that adapter; another file with the same module pair remains a violation. The repository audit also fails when a registry entry becomes stale.

2.2 Export Analysis (exports.py)

Functions:

Function	Signature	Returns	Description
get_modules	(src_dir: Path) -> list[Path]	list[Path]	Return module dirs that have __init__.py
check_all_defined	`(init_path: Path) -> tuple[bool, list[str] \	None]`	(has_all, names) Parse __init__.py for __all__ definition
audit_exports	(src_dir: Path) -> list[dict]	Findings with module, issue, detail	Find modules missing __all__
find_dead_exports	(src_dir: Path) -> list[dict]	Findings with module, export_name, detail	Find __all__ exports never imported elsewhere
find_unused_functions	(src_dir: Path) -> list[dict]	Findings with file, function_name, detail	Find top-level public functions never referenced
full_audit	(src_dir: Path) -> dict[str, Any]	{missing_all, dead_exports, unused_functions, summary}	Run all audits; summary has counts

3. Usage Example

from pathlib import Path
from codomyrmex.static_analysis.imports import scan_imports, check_layer_violations
from codomyrmex.static_analysis.exports import full_audit

src = Path("src/codomyrmex")

# Check for architectural violations
edges = scan_imports(src)
violations = check_layer_violations(edges)
for v in violations:
    print(f"VIOLATION: {v['reason']} in {v['file']}")

# Full export audit
report = full_audit(src)
print(f"Modules missing __all__: {report['summary']['modules_missing_all']}")
print(f"Dead exports: {report['summary']['dead_export_count']}")
print(f"Unused functions: {report['summary']['unused_function_count']}")