> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp/analysing-a-project/overview.md).

# Overview

{% hint style="info" %}
Project analysis is available in sfp-pro.
{% endhint %}

The project analysis command helps you analyze your Salesforce project for potential issues and provides detailed reports in various formats. This command is particularly useful for identifying issues such as duplicate components, compliance violations, hardcoded IDs and URLs, and other code quality concerns.

### Usage

```bash
sfp project:analyze [flags]
```

### Common Use Cases

The analyze command serves several key purposes:

1. Runs various available linters across the project
2. Generating comprehensive analysis reports
3. Integration with CI/CD pipelines for automated checks

### Available Linters

The analyzer runs the following linters on an analysis:

| Linter           | What It Checks                                                                              | Default State           |
| ---------------- | ------------------------------------------------------------------------------------------- | ----------------------- |
| `compliance`     | Salesforce metadata rules (hardcoded IDs, permissions, missing docs, etc.)                  | Enabled                 |
| `code-analyzer`  | Static analysis via Salesforce Code Analyzer (PMD, ESLint, CPD)                             | Enabled                 |
| `duplicates`     | Duplicate metadata components across packages                                               | Enabled                 |
| `architecture`   | AI-powered architectural review of changed code                                             | Disabled                |
| `version-assist` | AI-decided semantic version intent for server-managed packages (posts a `/version` comment) | Disabled (opt-in addon) |

{% hint style="info" %}
The `version-assist` addon is enabled differently from the other linters — it is gated by the project's `versionManagement.enabled` and `analyzeConfig.versionAssistEnabled` settings rather than by `excludeLinters`, and only runs when the PR impacts a server-managed package. See [AI Assisted Version Intent](/flxbl/sfp/analysing-a-project/ai-version-assist.md).
{% endhint %}

### Available Flags

| Flag                           | Description                                               | Required | Default                      |
| ------------------------------ | --------------------------------------------------------- | -------- | ---------------------------- |
| `--package, -p`                | The name of the package to analyze                        | No       | -                            |
| `--domain, -d`                 | The domain to analyze                                     | No       | -                            |
| `--source-path, -s`            | The path to analyze                                       | No       | -                            |
| `--exclude-linters`            | Comma-separated list of linters to exclude                | No       | \[]                          |
| `--fail-on`                    | Linters that should cause command failure if issues found | No       | \[]                          |
| `--show-aliasfy-notes`         | Show notes for aliasified packages                        | No       | true                         |
| `--fail-on-unclaimed`          | Fail when duplicates are found in unclaimed packages      | No       | false                        |
| `--output-format`              | Output format (markdown, json, github)                    | No       | markdown                     |
| `--report-dir`                 | Directory for analysis reports                            | No       | -                            |
| `--compliance-rules`           | Path to compliance rules YAML file                        | No       | config/compliance-rules.yaml |
| `--code-analyzer-config`       | Path to Salesforce Code Analyzer config file              | No       | config/code-analyzer.yml     |
| `--duplicates-config`          | Path to duplicates exclusion config file                  | No       | config/duplicates.yaml       |
| `--generate-compliance-config` | Generate sample compliance rules configuration            | No       | false                        |

### Scoping Analysis

The command provides three mutually exclusive ways to scope your analysis:

1. **By Package**: Analyze specific packages

   ```bash
   sfp project:analyze -p core,utils
   ```
2. **By Domain**: Analyze all packages in a domain

   ```bash
   sfp project:analyze -d sales
   ```
3. **By Source Path**: Analyze a specific directory

   ```bash
   sfp project:analyze -s ./force-app/main/default
   ```

### Output Formats

The command supports multiple output formats:

* **Markdown**: Human-readable documentation format
* **JSON**: Machine-readable format for integration with other tools
* **GitHub**: Special format for GitHub Checks API integration

### GitHub Integration

When running in GitHub Actions, the command automatically:

1. Creates GitHub Check runs for each analysis
2. Adds annotations to the code for identified issues
3. Provides detailed summaries in the GitHub UI

### Examples

1. Basic analysis of all packages:

   ```bash
   sfp project:analyze
   ```
2. Analyze specific packages with JSON output:

   ```bash
   sfp project:analyze -p core,utils --output-format json
   ```
3. Analyze with strict validation:

   ```bash
   sfp project:analyze --fail-on duplicates --fail-on-unclaimed
   ```
4. Generate reports in a specific directory:

   ```bash
   sfp project:analyze --report-dir ./analysis-reports
   ```
5. Generate compliance configuration:

   ```bash
   sfp project:analyze --generate-compliance-config
   ```
6. Run compliance checks with custom rules:

   ```bash
   sfp project:analyze --compliance-rules config/compliance-rules.yaml --fail-on compliance
   ```

### Analyzer Orchestration — `config/analyze.yaml`

The `config/analyze.yaml` file controls which linters are enabled and which ones cause a non-zero exit code (failing the CI check). This is the first file the analyzer reads before it invokes any linter.

#### Config Source Priority

The analyzer resolves its orchestration config in this order:

1. **CLI flags** (`--exclude-linters`, `--fail-on`) — highest priority, always wins
2. **`config/analyze.yaml`** — local file in the repo
3. **Server project config** (`analyzeConfig` field on the project) — fallback when no local file exists
4. **Defaults** — all linters enabled, none fail the check

#### Schema

```yaml
# config/analyze.yaml

# Linter names to disable entirely for all PRs.
# Valid values: duplicates, compliance, code-analyzer, architecture
excludeLinters:
  - architecture

# Linters whose findings cause the check to fail (non-zero exit).
# Only linters that actually ran can appear here.
failOn:
  - compliance
  - code-analyzer

# When true, the architecture linter skips PRs whose diffs are
# below the significance thresholds defined in ai-assist.yaml.
# Has no effect when the architecture linter is excluded.
changeSignificanceEnabled: false

# Optional: per-target-branch overrides.
# Matched against the PR's target (base) branch using glob patterns.
# First matching rule wins; if nothing matches, the top-level values apply.
branchRules:
  - pattern: "release/*"
    failOn:
      - compliance
      - code-analyzer
      - duplicates
    changeSignificanceEnabled: false

  - pattern: "hotfix/*"
    excludeLinters:
      - architecture
      - duplicates
    failOn:
      - compliance

  - pattern: "main"
    failOn:
      - compliance
      - code-analyzer
      - duplicates
```

#### Field Reference

| Field                                     | Type           | Default  | Description                                                     |
| ----------------------------------------- | -------------- | -------- | --------------------------------------------------------------- |
| `excludeLinters`                          | `string[]`     | `[]`     | Linter names to skip. All run by default.                       |
| `failOn`                                  | `string[]`     | `[]`     | Linters whose results fail the check. Informational by default. |
| `changeSignificanceEnabled`               | `boolean`      | `false`  | Skip architecture AI when changes are trivial.                  |
| `branchRules`                             | `BranchRule[]` | `[]`     | Target-branch-specific overrides.                               |
| `branchRules[].pattern`                   | `string`       | —        | Glob pattern matched against the PR target branch.              |
| `branchRules[].excludeLinters`            | `string[]`     | inherits | Override `excludeLinters` for this branch pattern.              |
| `branchRules[].failOn`                    | `string[]`     | inherits | Override `failOn` for this branch pattern.                      |
| `branchRules[].changeSignificanceEnabled` | `boolean`      | inherits | Override `changeSignificanceEnabled` for this branch pattern.   |

### Configuration Files

All configuration files live inside the repository root under `config/`. If a file is absent the linter falls back to safe defaults.

| File                           | Purpose                                                              | Required |
| ------------------------------ | -------------------------------------------------------------------- | -------- |
| `config/analyze.yaml`          | Orchestration: which linters run, what causes failure                | No       |
| `config/compliance-rules.yaml` | Rules for the compliance linter                                      | No       |
| `config/code-analyzer.yml`     | Config for Salesforce Code Analyzer (PMD/ESLint/CPD)                 | No       |
| `config/ai-assist.yaml`        | Config for the AI architecture linter (preferred name)               | No       |
| `config/ai-architecture.yaml`  | Config for the AI architecture linter (legacy name, still supported) | No       |
| `config/duplicates.yaml`       | Exclusion config for the duplicates linter                           | No       |

#### Recommended Repository Layout

```
config/
├── analyze.yaml                # Orchestration (which linters run, what fails)
├── compliance-rules.yaml       # Compliance rule definitions
├── code-analyzer.yml           # Salesforce Code Analyzer engine config
├── ai-assist.yaml              # AI architecture linter config
└── duplicates.yaml             # Duplicates linter exclusions (optional)
```

### How Configuration Is Loaded at Runtime

```
sfp project:analyze
    │
    ├─ 1. Resolve orchestration config (analyze.yaml / server / CLI flags)
    │       └─ Determines: which linters run, which can fail the check
    │
    ├─ 2. Compliance linter
    │       └─ Loads config/compliance-rules.yaml
    │           └─ If extends: default → merges with built-in preset
    │
    ├─ 3. Code Analyzer linter
    │       └─ Finds config/code-analyzer.yml (or variants)
    │           └─ If not found → uses engine defaults
    │
    ├─ 4. Duplicates linter
    │       └─ Loads config/duplicates.yaml (optional exclusions)
    │
    └─ 5. Architecture linter (if not excluded)
            └─ Loads config/ai-assist.yaml (or config/ai-architecture.yaml)
                └─ Determines provider, patterns, significance thresholds
```

When run in PR context (triggered by a webhook or `--pr-number`), all linters restrict their analysis to the **changed files** in the PR diff. When run standalone (no PR context), linters scan the full project.

### Common Scenarios

#### Fail the PR check on compliance errors only

```yaml
# config/analyze.yaml
excludeLinters:
  - architecture
failOn:
  - compliance
```

#### Strict release branches, lenient feature branches

```yaml
# config/analyze.yaml
excludeLinters:
  - architecture
failOn: []

branchRules:
  - pattern: "release/*"
    failOn:
      - compliance
      - code-analyzer
      - duplicates
  - pattern: "main"
    failOn:
      - compliance
      - code-analyzer
```

#### Use architecture linter with significance filtering

```yaml
# config/analyze.yaml
changeSignificanceEnabled: true
```

```yaml
# config/ai-assist.yaml
provider: anthropic
changeSignificance:
  fileTypeThresholds:
    apex:
      lines: 30
      files: 2
    default:
      lines: 100
      files: 3
  ignoredFilePatterns:
    - "**/__tests__/**"
    - "**/*.test.js"
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp/analysing-a-project/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.