DOCSEARCHbyAlgolia
Submit Docs

CodeCharta Documentation

repository·main·Indexed 19 days ago

https://github.com/maibornwolff/codecharta

An open-source toolset for visualizing and analyzing codebases in 3D. It includes a command-line shell (CCSH) for data analysis and a Web Studio for interactive visualization to help identify technical debt and hotspots. The toolset provides utilities for exporting data to CSV, merging multiple .cc.json files, modifying project structures, and importing temporal coupling data from Code Maat.

Tokens
100.9K
Snippets
222
Records
465
Agent score
66%

What's inside CodeCharta

  1. What is CodeCharta

    main

    CodeCharta is an open-source tool designed to visualize and analyze codebases. It transforms code metrics into a 3D city-like map where files are represented as buildings. The area, height, and color of these buildings can be mapped to different metrics, making it easy to identify hotspots and areas for improvement.

    Key characteristics:

    • Local Processing: All analysis and visualization happen entirely on your local machine. No data is uploaded or transmitted to external services.
    • Privacy: There is no built-in analytics, tracking, or telemetry.
    • 3D Visualization: Use the Web Studio to navigate your codebase in 3D or even download the map as a 3D model for printing.

  2. Overview of CodeCharta

    main

    CodeCharta is an open-source static code analysis and code visualization tool that transforms your codebase into an interactive 3D map. It uses a city metaphor where files are represented as "buildings" and folders as "districts."

    Key capabilities include:

    • Software Architecture Visualization: View the entire structure of your project in a 3D map to understand module relationships and sizes.
    • Code Hotspot Identification: Quickly find problematic areas (high complexity, frequent changes, or high risk) by looking for large or red-highlighted buildings on the map.
    • Technical Debt Analysis: Use color-coding and height indicators to visualize metrics like complexity, lines of code, churn, and duplications.
    • Software Health Checks: Consolidate metrics from various analyzers to monitor maintainability and assess the impact of refactoring or bug fixes.
    • CI/CD Integration: Use the CLI to automate map generation within pipelines like Jenkins or GitLab CI.

  3. Use the CodeCharta Web Studio for 3D code visualization

    main

    The Web Studio is the visualization component of CodeCharta. It takes metrics generated by the CodeCharta Shell (CCSH) and renders them as an interactive 3D code map in your browser. This allows you to explore your codebase's structure and metrics visually.

    Privacy Note: CodeCharta is designed to run entirely on your local machine. Metrics analyzed or visualized do not leave your computer unless you explicitly share them.

  4. Understand the CodeCharta ecosystem

    main

    CodeCharta is a communication tool designed to help manage complex codebases by transforming metrics into a "city-like map." It consists of two primary components:

    1. CodeCharta Shell (CCSH): The analysis engine used to extract metrics from your codebase and generate code maps.
    2. Web Studio: A visualization tool used to view the generated metrics as an interactive, navigable map (including 3D capabilities).

    Privacy Note: CodeCharta runs entirely on your local client. No metrics or code data leave your computer unless you choose to distribute them yourself.

  5. Use the Git-Log Parser to generate CodeCharta data

    main

    The Git-Log Parser is a CodeCharta parser that converts a Git repository log and a file list into a cc.json file for visualization. It specializes in tracking file changes across feature branches and the main branch, handling renames carefully and ignoring file deletions that were later reverted.

    Supported Metrics

    The parser calculates several metrics for each file:

    • age_in_weeks: Age in weeks since creation.
    • number_of_authors: Count of distinct authors/co-authors.
    • number_of_commits: Total commits to the file.
    • number_of_renames: Number of times the file was renamed.
    • range_of_weeks_with_commits: Span of weeks with commits.
    • successive_weeks_with_commits: Consecutive weeks with commits.
    • weeks_with_commits: Number of weeks modified.
    • highly_coupled_files: Files modified with this file (>=35% overlap).
    • median_coupled_files: Median number of files modified in tandem.
    • temporal_coupling: Degree of temporal coupling between two files (>=35%).

    Note: Author names are only included if the --add-author flag is used.

  6. Navigate the CodeCharta Web Studio User Controls

    main

    The CodeCharta Web Studio provides several interactive controls for visualizing and analyzing code maps. Key functional areas include:

    • Map Management: Load cc.json maps using the folder button (hold Shift to load multiple maps), switch between loaded maps using the Map selector, or switch to Compare mode to see the delta between two maps.
    • Navigation & View: Use the Viewcube to snap camera perspectives, the compass to recenter/fit the map, and the camera button to take screenshots. Use the zoom slider for depth.
    • Metrics & Visualization: Control the 3D treemap by selecting different Area metrics (footprint size), Height metrics (building height), and Color metrics. You can link height and color to the same metric or keep them separate.
    • Exploration: Use the Explorer panel to search for buildings using .gitignore-style patterns, view the file tree, and manage how rules divide the map via SHOWN, FLATTENED, and HIDDEN counters.
    • Output & Settings: Export the current view as a 3D printable model via 3D Print, or access Global Configuration (layout, background, quality) via Settings.

  7. What is a scenario in CodeCharta Visualization

    main

    A scenario is a saved bundle of visualization settings that allows you to switch between different views in a single click. Instead of manually adjusting metrics, colors, and camera settings, you can apply a pre-configured scenario.

    A scenario can store and apply the following groups of settings:

    • Metrics: Defines which metrics drive the building area, height, and color (including optional edge/distribution metrics and height/color linking).
    • Colors: Stores the color range, color mode, and positive/neutral/negative map colors.
    • Camera: Stores the camera position and target.
    • Filters: Stores the blacklist (hidden/excluded buildings) and the focused node path.
    • Labels & Folders: Stores label settings (size, amount, mode, floor labels, etc.) and marked packages.

  9. Use MIMO (Multiply Inputs Multiple Outputs) mode

    main

    MIMO mode is used to match multiple .cc.json files based on their prefix (e.g., myProject.git.cc.json). It attempts to match project names even with typos and prompts the user for confirmation.

    CI/CD Usage: To use MIMO in automated environments without user prompts, specify the -ld (levenshtein distance) and -f (force) flags.

    Output: The resulting file follows the schema: [prefix].merge.cc.json.

    ccsh merge myProjectFolder/ --mimo -ld 0 -f

  10. Interpret delta colors and metric changes in Compare mode

    main

    In Compare mode, building colors represent the change in the height metric rather than the metric value itself.

    Color Semantics

    By default, the colors follow these rules:

    • Green (positiveDelta, default #64d051): The height metric increased (positive delta).
    • Red (negativeDelta, default #ff0E0E): The height metric decreased (negative delta).
    • Grey: The building is unchanged (no delta) or has been flattened.

    Note: You can invert these colors in the color settings, which reverses the meaning of green and red.

    Reading the Metric Bar

    The metric bar at the bottom of the screen displays numerical deltas. For each metric, you will see:

    • Σ: The summed metric value of the current view.
    • Δ: The absolute change in that metric between the two maps (e.g., Σ 63.229 Δ22.949).

  11. Link Height and Color dimensions

    main

    To ensure that a building's height and its color are driven by the exact same metric, use the link icon located between the Height and Color columns in the metric bar.

    • When linked (icon highlighted): Changing the metric for Height automatically updates the Color metric, and vice versa. This is useful for visualizing a single metric through two different visual cues (e.g., a file is both tall and red because it has high complexity).
    • When unlinked: You can choose independent metrics for height and color.