/source-analysis

name: source-analysis
description: Layer 1 skill for source code analysis — decompose any codebase into analyzable units, extract behavioral claims with provenance. Supports three target shapes (source tree, bundle, decompiled binary), with per-language grep patterns and analysis templates.

Source Analysis Methodology

Extract behavioral intelligence from source code. Decompose the codebase into analyzable units, then systematically analyze each unit for behavioral claims with full provenance.

When to Use This Mode

Source analysis activates when:

• The discovery inventory identifies source code files at the target path
• Any source code needs behavioral analysis (any language, bundled or not)
• Decompiled output exists at `workspace/raw/source/decompiled/`

General Approach

Source analysis takes three shapes depending on what the target looks like:

• **Source tree** — a repository with a package manifest and conventional directory layout (Python, Rust, Go, Swift, Java, Node/TS, C++, etc.). Follow the **Source Tree Pipeline** below.
• **Bundle** — a single-file minified or packed artifact (JavaScript bundle, Electron asar, webpack/esbuild output). Follow the **Bundle Pipeline** below.
• **Decompiled binary** — a compiled artifact where source isn't directly available. Decompile first via the **Decompilation Path**, then analyze the decompiled output using whichever of the above shapes fits.

Regardless of shape, the pipeline follows the same logical steps:

1. **Assess the source.** What language? How is it organized? How large is it? 2. **Decompose into analyzable units.** Use the language's natural boundaries (modules, packages, files) when they exist. Split bundled artifacts into chunks when they don't. 3. **Analyze each unit exhaustively.** Read every line. Identify every function, method, class. Understand what each does behaviorally. 4. **Extract behavioral specifications.** Write what the code DOES (observable behavior), not how it's structured (implementation details). Every claim gets a provenance citation.

Phases 6-8 (per-unit analysis, per-function deep analysis, targeted extraction) are shape-agnostic and apply to all three paths.

Decompilation Path

When source code isn't directly available, decompile binaries into structured source before analysis.

Language-Specific Decompilation Tools

| Language/Platform | Tools | Notes | |-------------------|-------|-------| | JVM (Java, Kotlin) | cfr, procyon, fernflower | cfr is standalone JAR; fernflower is IntelliJ's built-in decompiler | | .NET (C#, F#) | ilspy, dotPeek CLI | ilspy has a command-line mode suitable for automation | | Python (.pyc, .pyo) | uncompyle6, decompyle3 | decompyle3 targets Python 3.7+; uncompyle6 covers older versions | | JavaScript (bundled/obfuscated) | js-beautify | Also covered by the Bundle Pipeline below | | Native (x86, ARM, etc.) | ghidra headless, radare2 | Produces pseudocode, not true source; useful for behavioral extraction but lower fidelity |

Process

1. **Identify binary type.** Determine the platform and format (JAR, DLL, .pyc, ELF, Mach-O, etc.). 2. **Check tool availability.** Verify the appropriate decompiler is installed and accessible. If tools are unavailable, warn and fall back to binary analysis (strings, symbols, imports/exports). 3. **Decompile to workspace.** Output decompiled source to `workspace/raw/source/decompiled/`. Preserve directory structure from the binary where possible (e.g., Java package paths). 4. **Treat decompiled output as structured source.** Once decompiled, analyze using the same General Approach above — each decompiled file is an analyzable unit.

mkdir -p workspace/raw/source/decompiled

# Example: JVM with cfr
java -jar cfr.jar target.jar --outputdir workspace/raw/source/decompiled/

# Example: Python with uncompyle6
uncompyle6 -o workspace/raw/source/decompiled/ target.pyc

# Example: .NET with ilspy
ilspycmd target.dll -o workspace/raw/source/decompiled/

# Example: Native with Ghidra headless
analyzeHeadless /tmp/ghidra_project proj -import target.bin -postScript ExportDecompiled.java workspace/raw/source/decompiled/

Quality Notes

Decompiled code differs from original source in predictable ways:

• **Variable and parameter names are lost.** Decompilers generate synthetic names (e.g., `var1`, `a0`). Focus on behavioral patterns, not identifier semantics.
• **Comments are lost.** All inline documentation is gone. Rely on string constants, API calls, and control flow for behavioral understanding.
• **Control flow may be less readable.** Optimized bytecode can decompile into awkward `goto`-style structures or deeply nested conditionals.

These limitations are acceptable for behavioral extraction. The goal is to understand what the code does, not to recover the original source.

Source Tree Pipeline

Source tree analysis is the common path for Python, Rust, Go, Swift, Java, C++, and similar languages that ship as a repository rather than a single compiled artifact. The target is a directory with a package manifest and a conventional source layout.

The Source Tree Pipeline defines Phases ST1-ST3 (survey, enumeration, and unit preparation). After ST3, control flows into the shape-neutral Phases 6-8 shared with the Bundle Pipeline.

digraph source_tree_analysis {
    rankdir=TB;

    "Start (source tree)" [shape=doublecircle];
    "Phase ST1: Manifest discovery" [shape=box];
    "Phase ST2: Module enumeration" [shape=box];
    "Phase ST3: Prepare for per-unit analysis" [shape=box];
    "→ Phase 6 (shape-neutral)" [shape=box, style=filled, fillcolor="#f0f0f0"];

    "Start (source tree)" -> "Phase ST1: Manifest discovery";
    "Phase ST1: Manifest discovery" -> "Phase ST2: Module enumeration";
    "Phase ST2: Module enumeration" -> "Phase ST3: Prepare for per-unit analysis";
    "Phase ST3: Prepare for per-unit analysis" -> "→ Phase 6 (shape-neutral)";
}

Phase ST1: Manifest Discovery

Identify