Code Analysis — AST, Dependency Graphs & Knowledge Graphs

Parse, analyze, and visualize code structure through AST analysis, dependency graphing, and knowledge extraction. Supports Python (via ast module) and JavaScript/TypeScript (via grep -based import parsing and optional @babel/parser / ts-morph ).

When to use

Use this skill when:

• Building or updating a dependency graph of the codebase

• Analyzing imports to detect circular dependencies or layer violations

• Parsing Python AST to extract class hierarchies, function signatures, or call graphs

• Parsing JavaScript/TypeScript source to extract React component trees, ESM imports, and hook usage

• Generating a knowledge graph of code entities and their relationships

• Measuring code complexity (cyclomatic, cognitive, LOC) per module

• Identifying dead code, unused imports, or orphan modules

• Mapping how data flows through the SDK layers or SPA component hierarchy

• Understanding coupling between modules before a refactor

• Analyzing a SPA's source code structure (component graph, barrel exports, route tree)

Instructions

Step 1: AST Parsing

Parse Python source files to extract structured representations of code entities.

import ast from pathlib import Path

def parse_module(filepath: str) -> dict: """Extract entities from a Python module via AST.""" source = Path(filepath).read_text() tree = ast.parse(source, filename=filepath)

entities = {
    "module": filepath,
    "classes": [],
    "functions": [],
    "imports": [],
    "constants": [],
}

for node in ast.walk(tree):
    if isinstance(node, ast.ClassDef):
        entities["classes"].append({
            "name": node.name,
            "bases": [ast.dump(b) for b in node.bases],
            "methods": [n.name for n in node.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))],
            "decorators": [ast.dump(d) for d in node.decorator_list],
            "lineno": node.lineno,
        })
    elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
        if not any(isinstance(parent, ast.ClassDef) for parent in ast.walk(tree)):
            entities["functions"].append({
                "name": node.name,
                "args": [arg.arg for arg in node.args.args],
                "returns": ast.dump(node.returns) if node.returns else None,
                "is_async": isinstance(node, ast.AsyncFunctionDef),
                "lineno": node.lineno,
            })
    elif isinstance(node, ast.Import):
        for alias in node.names:
            entities["imports"].append({"module": alias.name, "alias": alias.asname})
    elif isinstance(node, ast.ImportFrom):
        entities["imports"].append({
            "module": node.module,
            "names": [alias.name for alias in node.names],
            "level": node.level,
        })

return entities

Step 2: Dependency Graph Construction

Build a directed graph of module-to-module dependencies.

Quick import graph using grep

grep -rn "from pplx_sdk" pplx_sdk/ --include="*.py" |
awk -F: '{print $1 " -> " $2}' |
sed 's|pplx_sdk/||g' | sort -u

Or using Python AST for precision

python3 -c " import ast, os, json graph = {} for root, dirs, files in os.walk('pplx_sdk'): for f in files: if f.endswith('.py'): path = os.path.join(root, f) module = path.replace('/', '.').replace('.py', '') tree = ast.parse(open(path).read()) deps = set() for node in ast.walk(tree): if isinstance(node, ast.ImportFrom) and node.module: if node.module.startswith('pplx_sdk'): deps.add(node.module) elif isinstance(node, ast.Import): for alias in node.names: if alias.name.startswith('pplx_sdk'): deps.add(alias.name) if deps: graph[module] = sorted(deps) print(json.dumps(graph, indent=2)) "

Expected Layer Dependencies

graph TD subgraph Valid["✅ Valid Dependencies"] client --> domain client --> transport client --> shared domain --> transport domain --> shared domain --> core transport --> shared transport --> core shared --> core end

subgraph Invalid["❌ Layer Violations"]
    core -.->|VIOLATION| shared
    core -.->|VIOLATION| transport
    shared -.->|VIOLATION| transport
    transport -.->|VIOLATION| domain
end

style Valid fill:#e8f5e9
style Invalid fill:#ffebee

Step 3: Knowledge Graph Extraction

Build a knowledge graph connecting code entities with typed relationships.

Entity Types

Entity Source Example

Module

File path pplx_sdk.transport.sse

Class

AST ClassDef SSETransport , PerplexityClient

Function

AST FunctionDef stream_ask , retry_with_backoff

Protocol

typing.Protocol Transport , StreamParser

Exception

Exception subclass TransportError , RateLimitError

Type

TypeAlias Headers , JSONData , Mode

Constant

Module-level assign SSE_ENDPOINT , DEFAULT_TIMEOUT

Relationship Types

Relationship Meaning Example

IMPORTS

Module imports another transport.sse IMPORTS core.protocols

DEFINES

Module defines entity core.exceptions DEFINES TransportError

INHERITS

Class extends another AuthenticationError INHERITS TransportError

IMPLEMENTS

Class implements protocol SSETransport IMPLEMENTS Transport

CALLS

Function calls another stream_ask CALLS retry_with_backoff

RETURNS

Function returns type stream_ask RETURNS Iterator[StreamChunk]

RAISES

Function raises exception request RAISES AuthenticationError

USES_TYPE

Function uses type hint request USES_TYPE Headers

BELONGS_TO

Entity belongs to layer SSETransport BELONGS_TO transport

Knowledge Graph as Mermaid

graph LR subgraph core["core/"] Transport[/"Transport<br/>(Protocol)"/] PerplexitySDKError["PerplexitySDKError"] TransportError["TransportError"] end

subgraph transport["transport/"]
    SSETransport["SSETransport"]
    HttpTransport["HttpTransport"]
end

subgraph shared["shared/"]
    retry["retry_with_backoff()"]
end

SSETransport -->|IMPLEMENTS| Transport
HttpTransport -->|IMPLEMENTS| Transport
TransportError -->|INHERITS| PerplexitySDKError
SSETransport -->|RAISES| TransportError
HttpTransport -->|CALLS| retry

style core fill:#e1f5fe
style transport fill:#fff3e0
style shared fill:#f3e5f5

Step 4: Code Complexity Analysis

Lines of code per module

find pplx_sdk -name "*.py" -exec wc -l {} + | sort -n

Cyclomatic complexity (if radon is available)

pip install radon 2>/dev/null && radon cc pplx_sdk/ -s -a

Function count per module

grep -c "def " pplx_sdk/**/.py 2>/dev/null ||
find pplx_sdk -name ".py" -exec grep -c "def " {} +

Class count per module

find pplx_sdk -name "*.py" -exec grep -c "class " {} +

Step 5: Pattern Detection

Detect common patterns and anti-patterns in the codebase:

Check Command What to Look For

Circular imports AST import graph cycle detection Cycles in the dependency graph

Layer violations Import direction analysis Lower layers importing higher layers

Unused imports ruff check --select F401

Imports that are never used

Dead code vulture pplx_sdk/ (if available) Functions/classes never called

Missing types mypy pplx_sdk/ --strict

Untyped functions or Any usage

Large functions AST line count per function Functions > 50 lines

Deep nesting AST indent depth analysis Nesting > 4 levels

Protocol conformance Compare class methods vs Protocol Missing protocol method implementations

Step 6: JavaScript/TypeScript Code Graph (SPA)

When analyzing a SPA codebase (React, Next.js, Vite), build a code graph from JavaScript/TypeScript source files.

Import Graph Extraction

ESM imports (import ... from '...')

grep -rn "import .* from " src/ --include=".ts" --include=".tsx" --include=".js" --include=".jsx" |
sed "s/:/ → /" | sort -u

Re-exports / barrel files

grep -rn "export .* from " src/ --include=".ts" --include=".tsx" | sort -u

Dynamic imports (lazy loading / code splitting)

grep -rn "import(" src/ --include=".ts" --include=".tsx" | sort -u

CommonJS requires (legacy)

grep -rn "require(" src/ --include="*.js" | sort -u

React Component Tree

Find all React components (function components)

grep -rn "export (default )?function |export const .* = (" src/ --include=".tsx" --include=".jsx"

Find component usage (JSX self-closing or opening tags)

grep -rn "<[A-Z][a-zA-Z][\ />\n]" src/ --include=".tsx" --include=".jsx" |
grep -oP '<[A-Z][a-zA-Z]' | sort | uniq -c | sort -rn

Find hooks usage

grep -rn "use[A-Z][a-zA-Z](" src/ --include=".ts" --include=".tsx" |
grep -oP 'use[A-Z][a-zA-Z]' | sort | uniq -c | sort -rn

Find context providers

grep -rn "createContext|.Provider" src/ --include=".tsx" --include=".ts"

Route Tree (Next.js / React Router)

Next.js App Router pages

find app/ -name "page.tsx" -o -name "page.jsx" -o -name "layout.tsx" 2>/dev/null

Next.js Pages Router

find pages/ -name ".tsx" -o -name ".jsx" 2>/dev/null

React Router route definitions

grep -rn "Route|createBrowserRouter|path:" src/ --include=".tsx" --include=".ts"

SPA Dependency Graph as Mermaid

graph TD subgraph pages["Pages / Routes"] SearchPage["SearchPage"] ThreadPage["ThreadPage"] end

subgraph components["Components"]
    SearchBar["SearchBar"]
    ResponseView["ResponseView"]
    SourceCard["SourceCard"]
end

subgraph hooks["Hooks"]
    useQuery["useQuery()"]
    useStreaming["useStreaming()"]
    useAuth["useAuth()"]
end

subgraph services["Services / API"]
    apiClient["apiClient"]
    sseHandler["sseHandler"]
end

SearchPage --> SearchBar
SearchPage --> useQuery
ThreadPage --> ResponseView
ThreadPage --> useStreaming
ResponseView --> SourceCard
useQuery --> apiClient
useStreaming --> sseHandler
SearchBar --> useAuth

style pages fill:#e1f5fe
style components fill:#fff3e0
style hooks fill:#f3e5f5
style services fill:#e8f5e9

SPA Entity Types

Entity Source Example

Component

Function returning JSX SearchBar , ResponseView

Hook

use* function useQuery , useAuth

Context

createContext()

AuthContext , ThemeContext

Route

Page/layout file /search , /thread/[id]

Service

API client module apiClient , sseHandler

Store

State management Zustand store, Redux slice

Type

TypeScript interface/type SearchResult , ThreadData

SPA Relationship Types

Relationship Meaning Example

RENDERS

Component renders another SearchPage RENDERS SearchBar

USES_HOOK

Component uses a hook SearchPage USES_HOOK useQuery

PROVIDES

Component provides context AuthProvider PROVIDES AuthContext

CONSUMES

Component consumes context SearchBar CONSUMES AuthContext

CALLS_API

Hook/service calls API endpoint useQuery CALLS_API /rest/search

IMPORTS

Module imports another SearchPage IMPORTS SearchBar

LAZY_LOADS

Dynamic import for code splitting App LAZY_LOADS SettingsPage

EXTENDS_TYPE

Type extends another ThreadResponse EXTENDS_TYPE BaseResponse

Step 7: Output Insights Report

Generate a structured report combining all analyses:

Code Analysis Report: pplx-sdk

Module Summary

SPA Component Summary (when analyzing JS/TS)

Dependency Graph

[Mermaid diagram]

Knowledge Graph

• N entities, M relationships
• [Mermaid diagram]

Layer Compliance

• ✅ No circular dependencies
• ✅ No upward layer violations
• ⚠️ 2 unused imports detected

Complexity Hotspots

Dead Code

Documentation Discovery

When analyzing dependencies or researching libraries, use these discovery methods to find LLM-optimized documentation:

llms.txt / llms-full.txt

The llms.txt standard provides LLM-optimized documentation at known URLs:

Check if a dependency publishes llms.txt

curl -sf https://docs.pydantic.dev/llms.txt | head -20 curl -sf https://www.python-httpx.org/llms.txt | head -20

Check for the full version (entire docs in one file)

curl -sf https://docs.pydantic.dev/llms-full.txt | head -20

Use the llms-txt MCP server for indexed search

Tools: list_llm_txt, get_llm_txt, search_llm_txt

.well-known/agentskills.io

Discover agent skills published by libraries and frameworks:

Check if a site publishes agent skills

curl -sf https://example.com/.well-known/agentskills.io/skills/ | head -20

Look for specific SKILL.md files

curl -sf https://example.com/.well-known/agentskills.io/skills/default/SKILL.md

MCP Documentation Servers

MCP Server Purpose Key Tools

context7

Library docs lookup Context-aware search by library name

deepwiki

GitHub repo documentation read_wiki_structure , read_wiki_contents , ask_question

llms-txt

llms.txt file search list_llm_txt , get_llm_txt , search_llm_txt

fetch

Any URL as markdown General-purpose URL fetching

Discovery Workflow

1. Check llms.txt at dependency's docs URL
2. Check .well-known/agentskills.io for skills
3. Query deepwiki for the dependency's GitHub repo
4. Query context7 for library-specific context
5. Fall back to fetch for raw documentation URLs

Integration with Other Skills

When code-analysis finds... Delegate to... Action

Layer violation architect

Produce corrected dependency diagram

Circular import code-reviewer

Review and suggest refactor

Missing protocol method scaffolder

Scaffold missing implementation

Dead code code-reviewer

Confirm and remove

High complexity code-reviewer

Review for refactor opportunity

New entity relationships architect

Update architecture diagrams

SPA component tree spa-expert

Cross-reference with runtime fiber tree

SPA API endpoints in source reverse-engineer

Validate against live traffic captures

SPA hook dependencies architect

Visualize hook → service → API chain

SPA barrel file cycles code-reviewer

Review circular re-exports