Skip to content

docs: document external ALCops configuration #161

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
someC0d3r wants to merge 2 commits into
base: main
Choose a base branch
from
+33 −0
Draft

docs: document external ALCops configuration #161

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
80909d0
docs: document external alcops configuration
someC0d3r Sep 1, 2026
c3f378b
docs: clarify anonymous configuration URLs
someC0d3r Sep 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions content/docs/getting-started/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ The `alcops.json` file provides analyzer-specific configuration. Place it in the

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Extends` | object | `null` | Loads one external `alcops.json` as the base configuration |
| `CognitiveComplexityThreshold` | integer | `15` | Maximum cognitive complexity before a diagnostic is reported |
| `CyclomaticComplexityThreshold` | integer | `8` | Maximum cyclomatic complexity before a diagnostic is reported |
| `MaintainabilityIndexThreshold` | integer | `20` | Minimum maintainability index before a diagnostic is reported |
Expand All @@ -32,6 +33,38 @@ The `alcops.json` file provides analyzer-specific configuration. Place it in the

Property names are case-insensitive. Comments and trailing commas are allowed.

### Extending a central configuration

Use `Extends.Source` to load a centrally maintained `alcops.json` as the base for the project configuration:

```json
{
"Extends": {
"Source": "https://example.com/company.alcops.json"
},
"SubscriberNamingPattern": "{Event Source}_{Event Name}[_{Element Name}]"
}
```

`Source` supports one anonymously accessible HTTP(S) URL or one absolute local file path. HTTP(S) URLs containing embedded credentials, such as `https://user:pass@example.com/alcops.json`, are rejected before a network request is made. For example, a Windows file path must be escaped in JSON:

```json
{
"Extends": {
"Source": "C:\\ALCops\\company.alcops.json"
}
}
```

The referenced configuration provides the base values, and settings specified in the local `alcops.json` take precedence. The merge follows these rules:

- Scalar values are replaced by the local value.
- Arrays are replaced as a whole rather than combined.
- Nested objects are merged property by property.
- A referenced configuration cannot declare its own `Extends` section; inheritance chains are not supported.

The external configuration is loaded once for each workspace path during the analyzer session. HTTP requests use a five-second timeout. If the source is unavailable, cannot be read, contains invalid JSON or incompatible setting values, ALCops ignores it and continues with the local configuration. This keeps local development and CI builds functional when a central configuration service is temporarily unavailable.

### NamingPatterns

Override the default naming validation patterns per target. Each target accepts `AllowPattern`, `DisallowPattern`, `AllowDescription`, and `DisallowDescription`.
Expand Down