Analysis Specifications & Concepts Guide

Macondo is an offline, deterministic static reverse engineering platform built for Visual Basic 6.0 and C# / .NET codebases. It processes source code files directly without requiring runtime installations, COM registrations, or legacy IDE dependencies.

Formal Directed CodeGraph Model:

Persistent Disk Cache: Upon analysis completion, the semantic graph snapshot and impact indices are persisted to disk. Future project launches load instantaneously in milliseconds, with automatic file modification timestamp staleness verification.

Macondo features 4 specialized layout algorithms designed to expose architectural topologies, hierarchical dependency chains, and isolated subdomains:

• Standard Radial: Concentric orbital rings radiating outward from the application entry point. Ideal for broad architectural hierarchy.
• Affinity Radial: Concentric rings with angular attraction clustering frequently interacting components to minimize edge crossings.
• Clustered Islands: Physically groups the architecture into segregated functional islands: UI Forms, Logic Modules, Domain Classes, and User Controls.
• Force-Directed: Simulates electrostatic particle repulsion with spring-damper tension on call relations (Fruchterman-Reingold model), drawing high-traffic hubs to the canvas center.

Container Nodes: Primary project files rendered as main nodes with dynamic expansion support:

• Form (.frm): Blue (#4FA8E8) — UI windows and dialogs.
• Module (.bas): Purple (#C084F0) — Global procedural logic and utility routines.
• Class (.cls / .cs): Green (#54C08C) — Domain entities, services, and business logic.
• User Control (.ctl): Orange (#F08C4A) — ActiveX and custom graphical components.

Routine & Member Nodes: Sub-nodes displayed when expanding a container:

• Sub / Function: Slate (#7D7D8E) — Executable methods and procedural routines.
• Property (Get / Let / Set): Gold (#E8B838) — Encapsulated field accessors.
• Field / State Variable: Sky Blue (#60A5FA) — Module-level and static variables.
• Constants (Const): Coral (#F87171) — Declared immutable values.
• Type / Enum: Mint (#34D399) — User-Defined Types (UDT) and enumerations.

Semantic Edge Relations:

• CALLS: Teal arrow directed from caller procedure to invoked target routine.
• INSTANTIATES: Amber arrow indicating class creation (Set x = New Class or Dim x As New).
• USES_TYPE: Lavender arrow representing parameter, field, or return type dependencies.

Visual map detailing user interface transitions and form lifecycle events across the desktop application without requiring execution.

Tracked UI Invocations:

• Openings & Invocations: .Show, Load Form, and modal dialog openings (vbModal).
• Closings & Unloading: .Hide and Unload Me events.
• Screen Chains: Reconstructs full navigation sequences from main menu screens to modal confirmation workflows.

Decomposes a single Sub, Function, or Property routine into a directed graph of Basic Blocks of Instructions (BBI) and conditional branch edges.

Deconstructed Control Structures:

• Decision Nodes: If...Then...Else, Select Case.
• Loops: For...Next, For Each, Do...While, While...Wend.
• Error Handling & Jumps: On Error GoTo, Resume, GoTo branch labels.

Crucial for auditing high-complexity spaghetti logic, uncovering unreachable basic blocks, and designing complete unit test coverage.

Circular Chord ribbon visualization mapping cross-layer interaction volumes and namespace coupling across architectural tiers.

• Volumetric Ribbon Thickness: Scaled proportionally to the total invocation count between components or packages.
• Architectural Tier Grouping: Organizes components by layer (UI Presentation, Business Domain, Data Persistence, Common Utilities).
• Illegal Flow Spotting: Instantly highlights anti-pattern calls violating architectural boundaries (e.g. database persistence modules calling UI forms).

Transforms the entire codebase into an interactive 3D polymetric city inspired by the software visualization methodology of Wettel & Lanza:

• Districts / Neighborhoods: Represent folders, packages, or architectural sub-projects.
• Buildings: Represent individual files, classes, or modules.
• Building Footprint (Width × Depth): Proportional to Lines of Code (LOC).
• Building Height: Proportional to McCabe Cyclomatic Complexity.
• Building Color: Reflects risk level, change churn frequency, or technical debt density.

High-density N × N square dependency matrix where rows and columns represent modules and classes in the codebase.

• Cell Values (i, j): Quantifies total call and type dependencies from row component i to column component j.
• Circular Dependency Detection: Mirrored entries above the main diagonal immediately expose bidirectional coupling and recursive loops.
• Triangular Layer Sorting: Automatically partitions components into strict hierarchical dependency tiers.

Hierarchical space-filling treemap showing code volume distribution and complexity hotspots with interactive drill-down:

• Box Area: Proportional to effective Lines of Code (LOC) or routine count.
• Color Spectrum: Green (Low CC ≤ 5), Yellow (Moderate CC 6–15), Red (High Complexity CC > 15).
• Interactive Zoom: Double-click any module box to zoom into its constituent routines and procedures.

Evaluates architectural packaging, modularity, and maintainability based on Robert C. Martin's Clean Architecture principles:

• Zone of Pain (A=0, I=0): Concrete, highly rigid components upon which many others depend. Very difficult to refactor without widespread breaking changes.
• Zone of Uselessness (A=1, I=1): Highly abstract components with no incoming dependencies, representing over-engineering.
• Main Sequence (D ≈ 0): Optimal architectural balance between abstraction and stability.

Lack of Cohesion of Methods (LCOM4 / Hitz & Montazeri) constructs an undirected graph where nodes are class methods and edges represent shared instance variables or direct inter-method calls:

Additional C&K Metrics Suite:

• Tight Class Cohesion (TCC): Fraction of directly connected method pairs over M*(M-1)/2 total pairs.
• Weighted Methods per Class (WMC): Cumulative complexity sum across all methods.
• Coupling Between Objects (CBO): Count of coupled external classes.
• Response for a Class (RFC): Cardinality of methods invoked in response to a class message.

Standard software maintainability rating combining Halstead Software Science, McCabe Cyclomatic Complexity, and effective code lines:

• Green (80–100): High maintainability. Code is clear, modular, and easy to enhance.
• Yellow (60–79): Moderate maintainability. Moderate technical debt.
• Red (0–59): Low maintainability. Severe technical debt, fragile logic, high defect probability.

Automated architectural boundary verification executing continuous fitness checks against the CodeGraph:

• Domain Isolation: Business models and domain entities must not reference outer presentation or transport layers.
• No Direct DB Access from UI: Presentation Forms (.frm) are forbidden from opening direct database connections or queries without passing through designated service repositories.
• Pure Helper Modules: Standard utility modules (.bas) are barred from instantiating UI forms.

Calculates the transitive regression risk when refactoring or altering a method by executing reverse BFS/DFS traversal over the transposed graph G^T:

• Direct Callers: Functions containing explicit calls to the selected symbol.
• Indirect Callers: Higher-level routines transitively calling upstream functions.
• Interactive Audit Grid: Filterable table sorted by impact volume and call depth with 1-click graph centering.

2D scatter plot correlating Structural Complexity against Historical Change Churn / Fan-In around codebase-wide averages:

Items located in the Danger Zone represent fragile, high-risk components where changes are most likely to introduce regressions.

Performs exhaustive reachability traversal starting from all legitimate application entry points (Sub Main, startup Forms, UI event handlers, and public COM interfaces):

• Orphan Routines: Subroutines and functions never invoked across any execution flow.
• Unused Modules: Entire container files (.bas / .cls) unreferenced by the rest of the application.
• Recoverable LOC: Computes the exact line count that can be safely retired before migration.

Audits all Public global variables in .bas modules and mutable static fields in C#:

• Readers & Writers: Tracks precisely which procedures read or mutate each global variable.
• Mutation Risk: Identifies unencapsulated side-effects when distant modules modify shared state.
• Concurrency & Threading: Highlights state hubs requiring encapsulation into thread-safe services.

Mines commit history from Git or SVN repositories to discover file pairs that co-evolve together across commits:

Uncovers implicit architectural coupling, duplicate copy-pasted logic, and shared assumptions invisible to static AST analysis.

Token-based clone detection identifying copy-pasted routines and duplicate logic blocks:

• Type-1 Clones (Exact): Identical line count, parameter signatures, and call sequences.
• Type-2 Clones (Structural / Parameterized): Identical syntactic structure and branch density with renamed identifiers or variables.
• Refactoring Candidates: Calculates total lines saved by extracting shared utility methods.

Tracks propagation of variable values from Untrusted Input Sources to Critical Execution Sinks:

• Sources: User inputs (textbox controls, URL/HTTP requests, raw file streams).
• Sinks: Direct SQL execution (Recordset.Open, Execute), shell invocations (Shell, Process.Start), or file system writes.
• Def-Use Anomalies: Detects variables assigned/written whose values are never read (Dead Stores).

Cross-references business logic routines with database tables and relational entities:

• Entity Discovery: Automatically catalogs domain structs, UDT types, records, and database entity classes.
• Operation Classification:
  • Create (C): Instantiations, AddNew, SQL INSERT statements.
  • Read (R): Selection queries, Find, SQL SELECT statements.
  • Update (U): Field assignments, property mutations, SQL UPDATE statements.
  • Delete (D): Record deletions, Delete, SQL DELETE statements.

Compares two CodeGraph snapshots (e.g. baseline release vs current branch) to enforce SemVer 2.0.0 compliance:

• Major Breaking Change (MAJOR): Removal of public symbols, visibility reduction (Public → Private), or signature changes to mandatory parameters.
• Minor Compatible Feature (MINOR): Addition of new public types, methods, or backward-compatible optional parameters.
• Patch / Internal Fix (PATCH): Internal routine refactoring without altering public API contracts.

Evaluates knowledge ownership and organizational risk per developer authorship (Adam Tornhill / CodeScene methodology):

Macondo includes a headless CLI mode for automated quality gates in CI/CD pipelines (GitHub Actions, Azure DevOps, GitLab CI) and autonomous AI agent tool execution: