> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codeant.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Analysis Configuration

> Configure which analyses run on your repository and how files are filtered

### Overview

CodeAnt AI allows you to configure analysis settings at multiple levels. You can control which analyses are enabled, set file include/exclude patterns, and tune thresholds like the maintainability index — all through a clear precedence hierarchy.

### Configuration Precedence

When multiple configuration sources exist, CodeAnt AI resolves them in the following order (highest priority first):

| Priority        | Source                        | Description                                                                                                                                  |
| --------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **1 (Highest)** | **Inline (CI/CD parameters)** | Parameters passed directly when triggering an analysis (e.g., `include_files`, `exclude_files` in API calls or CI/CD pipeline configuration) |
| **2**           | **Repository file**           | `.codeant/configuration.json` checked into your repository                                                                                   |
| **3 (Lowest)**  | **UI settings**               | Configuration set through the CodeAnt AI dashboard under Settings > Analysis Configuration                                                   |

Each level only overrides the specific fields it defines. If a field is not set at a higher-priority level, the value from the next level down is used.

**Example:** If your UI settings enable all analyses, but your `.codeant/configuration.json` disables `secrets_analysis`, secrets scanning will be skipped. If you then pass `include_files=src/**` inline via CI/CD, only the `src/` directory will be scanned — but the disabled secrets analysis from the repo config still applies.

### Repository Configuration File

Create a `configuration.json` file in the `.codeant` folder at your repository root:

```
your-repo/
├── .git/
├── .codeant/
│   └── configuration.json
├── src/
└── package.json
```

### Configuration Format

```json theme={null}
{
  "code_analysis": {
    "enabled": true,
    "features": {
      "sast_analysis": "enabled",
      "secrets_analysis": "enabled",
      "sca_analysis": "enabled",
      "iac_analysis": "enabled",
      "deadcode_analysis": "enabled",
      "duplicatecode_analysis": "enabled",
      "antipatterns_analysis": "enabled",
      "docstring_analysis": "enabled",
      "complex_function_analysis": "enabled"
    },
    "config": {
      "complexity": {
        "maintainability_index": 15
      }
    }
  },
  "file_filters": {
    "config": {
      "include_files": "",
      "exclude_files": ""
    }
  },
  "sbom_policy": {
    "exclude_packages": [],
    "approved_licenses": [],
    "package_overrides": {}
  }
}
```

### Configuration Options

#### Code Analysis

* **`enabled`** (boolean): Master toggle for all code analysis. Set to `false` to skip all analyses for this repository.

* **`features`** (object): Toggle individual analyses. Each key accepts `"enabled"` or `"disabled"`.

| Feature                     | Description                                                                   |
| --------------------------- | ----------------------------------------------------------------------------- |
| `sast_analysis`             | Static Application Security Testing — detects security vulnerabilities        |
| `secrets_analysis`          | Scans for exposed secrets like API keys and credentials                       |
| `sca_analysis`              | Software Composition Analysis — checks dependencies for known vulnerabilities |
| `iac_analysis`              | Infrastructure as Code scanning for misconfigurations                         |
| `deadcode_analysis`         | Identifies unused code that can be safely removed                             |
| `duplicatecode_analysis`    | Detects code duplication                                                      |
| `antipatterns_analysis`     | Detects common code antipatterns                                              |
| `docstring_analysis`        | Analyzes code documentation quality                                           |
| `complex_function_analysis` | Flags functions exceeding the maintainability index threshold                 |

* **`config.complexity.maintainability_index`** (number, 0-100): Threshold for complex function detection. Functions with a maintainability index below this value are flagged. Default: `15`.

#### File Filters

* **`config.include_files`** (string): Comma-separated glob patterns. Only files matching these patterns will be analyzed. Example: `"src/**,lib/**"`.

* **`config.exclude_files`** (string): Comma-separated glob patterns. Files matching these patterns will be excluded from analysis. Example: `"node_modules/**,dist/**,**/*.test.js"`.

<Note>
  If both `include_files` and `exclude_files` are specified, `include_files` takes precedence — only included files are considered, and exclude patterns are ignored.
</Note>

### SBOM Policy

`sbom_policy` lets you express your organization's risk acceptance decisions for third-party packages directly in the repository. CodeAnt AI applies the policy at scan time — packages you exclude are skipped entirely, and packages or licenses you approve are not flagged as issues in the SBOM report. Because the policy lives in git, every change is reviewed via pull request and recorded in your repository history, which doubles as your audit trail.

#### Resolution Order

For each package CodeAnt encounters, the policy is resolved top-down:

| Order | Rule                                                    | Effect                                                                                                                                 |
| ----- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **1** | `exclude_packages` match                                | Package is dropped entirely — not counted, not shown in the report, not present in API responses                                       |
| **2** | `package_overrides` match                               | Package is kept in the inventory; its policy is set to `approved` (`allow`) or `blocked` (`block`) using the justification you provide |
| **3** | `approved_licenses` contains the package's SPDX license | Package is kept in the inventory and marked as `allow`                                                                                 |
| **4** | No match                                                | Default classification from CodeAnt's license database is used                                                                         |

#### Format

```json theme={null}
{
  "sbom_policy": {
    "exclude_packages": [
      "internal-private-tool",
      "lodash@4.17.20"
    ],
    "approved_licenses": [
      "Apache-2.0",
      "MIT",
      "BSD-3-Clause"
    ],
    "package_overrides": {
      "psycopg2-binary": {
        "status": "approved",
        "justification": "LGPL DB driver; dynamic-link exemption applies"
      },
      "Oracle.ManagedDataAccess": {
        "status": "approved",
        "justification": "Commercial Oracle license, enterprise agreement"
      },
      "some-risky-lib@1.2.3": {
        "status": "blocked",
        "justification": "Known supply chain risk"
      }
    }
  }
}
```

#### Field Reference

* **`exclude_packages`** (array of strings): Package identifiers to drop from the SBOM entirely. Each entry is either a bare package name (`"psycopg2-binary"`) or a version-pinned form (`"lodash@4.17.20"`). Bare names match every version of that package; pinned names match only the exact version.

* **`approved_licenses`** (array of strings): SPDX license identifiers (case-sensitive, e.g. `"Apache-2.0"`, not `"apache-2.0"`) that should be considered accepted by your organization. Any package whose resolved license matches an entry here is marked `allow` and stops appearing as an issue.

* **`package_overrides`** (object): Per-package decisions that override the license-based default. Each key is a bare name or `name@version`, and each value is an object with:

  * **`status`** (required): `"approved"` (maps to `allow`) or `"blocked"` (maps to `block`).
  * **`justification`** (optional string): Human-readable reason. Shown in the SBOM details so auditors can see why a package was approved or blocked.

  If both a version-pinned key (`"lodash@4.17.20"`) and a bare-name key (`"lodash"`) exist, the version-pinned form wins for the matching version.

<Note>
  Approved packages (via `package_overrides` or `approved_licenses`) remain visible in your SBOM inventory — they simply stop counting as issues. Use `exclude_packages` only when a package should be completely invisible to CodeAnt (for example, internal tools you do not want indexed at all).
</Note>

### Sample Configurations

#### Security-focused scan only

```json theme={null}
{
  "code_analysis": {
    "enabled": true,
    "features": {
      "sast_analysis": "enabled",
      "secrets_analysis": "enabled",
      "sca_analysis": "enabled",
      "iac_analysis": "enabled",
      "deadcode_analysis": "disabled",
      "duplicatecode_analysis": "disabled",
      "antipatterns_analysis": "disabled",
      "docstring_analysis": "disabled",
      "complex_function_analysis": "disabled"
    }
  }
}
```

#### Scan only the src/ directory

```json theme={null}
{
  "file_filters": {
    "config": {
      "include_files": "src/**",
      "exclude_files": ""
    }
  }
}
```

#### Disable all analysis for a repository

```json theme={null}
{
  "code_analysis": {
    "enabled": false
  }
}
```

#### Accept common licenses and approve a specific package

```json theme={null}
{
  "sbom_policy": {
    "approved_licenses": ["Apache-2.0", "MIT", "BSD-3-Clause"],
    "package_overrides": {
      "psycopg2-binary": {
        "status": "approved",
        "justification": "LGPL DB driver; dynamic-link exemption applies"
      }
    }
  }
}
```

### Best Practices

* **Version control your config**: Checking `.codeant/configuration.json` into the repository ensures the whole team shares the same analysis settings and changes are reviewed via pull requests.
* **Start with defaults**: Only override what you need. Omitted fields inherit from UI settings or defaults.
* **Use inline parameters for one-off overrides**: If you need a different scope for a specific CI run, pass `include_files` or `exclude_files` inline rather than modifying the repo config.
* **Keep file filters focused**: Prefer narrow `include_files` patterns over broad `exclude_files` to make intent clear.
* **Prefer `approved_licenses` over per-package approvals**: Approving a license once covers every package that uses it, including future additions, so you avoid re-approving the same packages after every version bump.
* **Reserve `exclude_packages` for genuinely invisible dependencies**: For anything you want to remain auditable, use `package_overrides` or `approved_licenses` so the package stays in your SBOM inventory with a justification.