.. _config_guide:

Calyntro Configuration File
============================

The ``config.yaml`` file is the central place to configure the analysis performed by Calyntro. It defines the project settings, what to include and exclude from the analysis, and how to map users to teams.

Generating a Draft Configuration
--------------------------------

Instead of writing the configuration from scratch, you can generate a draft by scanning your repository. This will automatically populate users, common file exclusions, and suggest logical components based on your directory structure.

.. code-block:: bash

   ./scripts/generate_config.sh /path/to/your/repository -o config/config.yaml

This script runs within the Calyntro backend Docker image and does not require local Python dependencies.

Manual Configuration
--------------------

If you prefer to write the file manually, follow the structure below.

Project Section
---------------

The ``project`` section contains general settings for the project and the analysis.

.. code-block:: yaml

   project:
     name: "mongodb"
     db_path: "./data_tmp"
     db_basename: "calyntro"
     repo_path: "/home/user/projects/mongo"
     branch: "master"
     analysis_since: "2025-01-01"

*   **name**: A string representing the name of the project.
*   **db_path**: The file system path where the database files will be stored.
*   **db_basename**: The base name for the generated database files (e.g., ``calyntro.duckdb``).
*   **repo_path**: The absolute or relative path to the Git repository that you want to analyze.
*   **branch**: The specific branch of the repository to be analyzed.
*   **analysis_since**: The start date for the analysis in ``YYYY-MM-DD`` format. Commits older than this date will be ignored.

Analysis Section
----------------

The ``analysis`` section defines the scope of the code analysis, including which parts of the codebase to analyze and which to ignore.

.. code-block:: yaml

   analysis:
     components:
       - component_name: "client"
         path_prefix: "src/mongo/client/"
         display_name: "Client"
       # ... other components

     excluded_prefixes:
       - "bazel/"
       - "buildfarm/"
       # ... other prefixes

     excluded_extensions:
       - ".json"
       - ".md"
       # ... other extensions

     excluded_patterns:
       - "_test\\.(cpp|cc|py|go|java|ts|js)$"
       - "/(test|tests|spec|__tests__)/"

*   **components**: A list of objects, each representing a logical component of the software.

    *   **component_name**: A unique identifier for the component.
    *   **path_prefix**: A single directory path that identifies files belonging to this component. Use ``paths`` instead if you need to map multiple directories to one component.
    *   **paths**: A list of directory paths, all mapped to the same component. Use this when the component's source is spread across multiple directories (e.g. ``src/core/`` and ``lib/core/``). Mutually exclusive with ``path_prefix`` — use one or the other per entry.
    *   **display_name**: A user-friendly name for the component that will be used in the UI.

    **Single-path example** (classic format, still supported):

    .. code-block:: yaml

       components:
         - component_name: "client"
           path_prefix: "src/mongo/client/"
           display_name: "Client"

    **Multi-path example** (new format):

    .. code-block:: yaml

       components:
         - component_name: "core"
           paths:
             - "src/core/"
             - "lib/core/"
           display_name: "Core"

    File assignment uses longest-prefix matching: if a file path matches multiple components, the component with the longest matching prefix wins. If the same ``path_prefix`` appears in two different components, Calyntro raises a configuration error at sync time.

.. note::

   Component assignments are pre-computed at import time and stored in the database.
   If you change the ``components`` section of your config (including switching from
   ``path_prefix`` to ``paths``), run ``calyntro import config`` to re-sync the
   configuration and re-assign all files. Existing databases imported before version 1.4
   will have unpopulated component assignments and require a full ``calyntro import analysis``
   to populate them.

*   **excluded_prefixes**: A list of directory paths to be excluded from the analysis. Any file or directory starting with one of these prefixes will be ignored.

*   **excluded_extensions**: A list of file extensions to be excluded from the analysis. Files with these extensions will be ignored.

*   **excluded_patterns**: A list of regular expression patterns matched against the full file path (using ``re.search``). Files matching any of these patterns will be excluded from import and all analysis views. This is useful for excluding test files or specific directory patterns that cannot be easily captured by prefixes or extensions alone.

*   **excluded_authors**: A list of author name patterns to exclude from all analyses. Supports glob-style wildcards (``*``). Use this to filter out bot accounts, CI users, or automation commits that would otherwise inflate commit counts and distort ownership metrics.

.. code-block:: yaml

   excluded_authors:
     - "*[bot]"           # matches dependabot[bot], renovate[bot], etc.
     - "GitHub Actions"   # exact name match

Wildcard rules:

* ``*`` matches any sequence of characters.
* Patterns are matched against the ``author_name`` field of each commit.
* The filter propagates to **all** analyses and views — hotspots, ownership, silos, and trend data.

.. note::

   ``excluded_authors`` filters are applied at the database view level (``v_file_commits``), not at parse time. This means you can add new patterns to ``config.yaml`` and re-run ``importer analysis`` without re-importing the full Git history. Only a configuration sync (``importer config``) followed by a view refresh is required.

Users and Teams
---------------

This part of the configuration allows you to define users and group them into teams. This is useful for attributing code changes and for team-level analysis.

.. code-block:: yaml

   users:
     - name: "jsteemann"
       aliases:
         - "jsteemann"
     # ... other users

   teams:
     - name : "TeamF"
       members:
         - "jsteemann"
         - "allisoneaston"
     # ... other teams

*   **users**: A list of user objects.

    *   **name**: The canonical name of the user.
    *   **aliases**: A list of aliases (e.g., different usernames for different systems) that should be mapped to this user.

*   **teams**: A list of team objects.

    *   **name**: The name of the team.
    *   **members**: A list of user names (as defined in the ``users`` section) that belong to this team. This creates implicit team memberships that are valid from the ``analysis_since`` date onwards with no end date.

Team Memberships
----------------

The ``team_memberships`` section provides a way to track temporal membership of users in teams. This is useful for historical analysis, understanding how team composition changed over time, and correlating team changes with code metrics.

.. code-block:: yaml

   team_memberships:
     columns:
       - developer
       - team
       - valid_from
       - valid_to

     format:
       valid_from: "YYYY-MM-DD or ISO8601 datetime (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)"
       valid_to: "nullable; same format as valid_from; omit or set to null for active membership"

     entries:
       - developer: "jsteemann"
         team: "TeamF"
         valid_from: "2024-01-01"
         valid_to: null

       - developer: "allisoneaston"
         team: "TeamF"
         valid_from: "2023-06-01"
         valid_to: "2024-12-31"

*   **team_memberships**: Configuration for tracking when users belonged to teams.

    *   **columns**: Informational field documenting the expected data structure. Not used during import but helpful for understanding the schema.

    *   **format**: Format specifications and notes for the date fields used in memberships.

        *   **valid_from**: The start date of the membership. Must be a valid date in ``YYYY-MM-DD`` format or ISO 8601 datetime format.
        *   **valid_to**: The end date of the membership. Optional; can be omitted or set to ``null`` to indicate an ongoing membership (i.e., the user is currently a member). Must use the same format as ``valid_from``.

    *   **entries**: A list of membership records, each specifying a time-bounded relationship between a developer and a team.

        *   **developer**: The name or alias of the user (as defined in the ``users`` section). Aliases are automatically resolved to the corresponding user.
        *   **team**: The name of the team (as defined in the ``teams`` section). If a team in a membership entry does not exist in the ``teams`` section, it will be created automatically.
        *   **valid_from**: The date when the user joined the team.
        *   **valid_to**: The date when the user left the team. Set to ``null`` or omit to indicate ongoing membership.


**Important**: The relationship between users and teams is defined exclusively through the ``team_memberships`` table. The ``teams`` table contains only the team identifiers and names. To query which users belong to a team, always join ``teams`` with ``team_memberships`` on the ``team_id`` field.