docs: document external ALCops configuration

content/docs/analyzers/Common/CM0001.md

@@ -10,9 +10,9 @@ linkTitle = 'CM0001'
   ignoreObsolete = false
 +++
 
-`CM0001` warns when an [`alcops.json`](/docs/getting-started/configuration/) configuration file was found but could not be fully applied. Without this warning a broken configuration silently falls back to the default settings, and it can be hard to understand why your settings have no effect.
+`CM0001` warns when an [`alcops.json`](/docs/getting-started/configuration/) configuration file was found but could not be fully applied, or when its declared `Extends.Source` could not be resolved. The warning explains why the intended configuration is not in effect.
 
-The message names the file and the reason:
+The message names the file or external source and the reason:
 
 ```
 The ALCops configuration 'C:\Source\MyApp\alcops.json' could not be fully loaded: unknown setting 'CognitivComplexityThreshold'
@@ -24,17 +24,23 @@ The ALCops configuration 'C:\Source\MyApp\alcops.json' could not be fully loaded
 |---|---|
 | The file exists but cannot be read (I/O or permission error) | Defaults are used |
 | The file contains invalid JSON (syntax error, wrong value type, unknown enum value) | Defaults are used |
-| The file is valid JSON but contains an unrecognized top-level setting (for example a typo in the name) | All recognized settings still apply; one warning per unknown setting |
+| A declared `Extends` source cannot be resolved (unreachable source, HTTP error, timeout, oversized HTTP response, unreadable file, invalid JSON or setting values, rejected URL credentials, invalid source declaration, or inheritance chain) | The entire configuration uses built-in defaults; local overrides are discarded too |
+| The local or inherited file is valid JSON but contains an unrecognized top-level setting (for example a typo in the name) | All recognized settings still apply; one warning per unknown setting |
 
-No warning is reported when no `alcops.json` exists — using the defaults without a configuration file is perfectly fine.
+No warning is reported when no `alcops.json` exists, or when the local file is empty, whitespace-only, comment-only or JSON null. These cases use defaults. A declared inherited source must still contain a JSON object. Cancelling analysis also does not produce CM0001.
 
 ### Notes
 
-- Setting names are matched case-insensitively, and the `$schema` key is always allowed.
+- Setting names are matched case-insensitively; `$schema` and the local `Extends` declaration are allowed. An inherited file cannot declare its own `Extends`.
 - The warning has no source location because `alcops.json` is not part of the compilation. Visual Studio Code shows such diagnostics against `app.json`.
 - An unreadable `alcops.json` in the app folder does **not** fall back to a configuration in a parent directory: the app-level file was intended to win, so ALCops uses the defaults and reports the problem instead.
+- HTTP response content is limited to 1 MiB (1,048,576 bytes), with a five-second timeout. A rejected URL's username and password are omitted from the diagnostic source.
 - Typos *inside* nested settings (for example a misspelled key under `StatementBlockSpacing`) are not detected by this rule; reference the [JSON schema](https://raw.githubusercontent.com/ALCops/Analyzers/main/src/ALCops.Common/Settings/alcops.schema.json) via `$schema` to have your editor validate those.
 
 ### How to fix
 
-Open the `alcops.json` named in the message and correct the reported problem — fix the JSON syntax, correct the setting name, or resolve the file permission issue. The warning disappears once the file loads cleanly.
+Correct the reported problem in the local configuration or its referenced source: fix the JSON or setting value, restore source access, remove an inheritance chain, or reduce an oversized HTTP response. Only reference sources that the project trusts.
+
+Failed HTTP requests are cached per workspace path for 30 seconds after each failure. Compilations inside that cooldown reuse defaults and CM0001 without fetching again; cache hits do not extend the wait. After connectivity recovers and the cooldown expires, the first new compilation requesting settings can load the source without restarting the language server. Concurrent compilations share that retry, and another failure starts a new cooldown. The original compilation keeps its defaults and diagnostic so its rules use consistent settings. Cancelling a request does not start a new cooldown.
+
+Successfully loaded settings and deterministic configuration errors remain cached for the analyzer session. After correcting malformed JSON, invalid setting values or a source declaration, restart the analyzer process; in VS Code, use **Developer: Reload Window**. The warning disappears when the configuration loads cleanly.

content/docs/getting-started/configuration.md

@@ -23,14 +23,61 @@ 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 |
 | `LanguagesToTranslate` | string[] | `null` | Language codes to check for missing translations |
 | `NamingPatterns` | object | `null` | Per-target naming pattern overrides |
 | `UseSequentialGuidScope` | string | `null` | Set to `"AllGuidFields"` to require sequential GUIDs on all GUID fields |
 
-Property names are case-insensitive. Comments and trailing commas are allowed.
+Property names are case-insensitive. Comments and trailing commas are allowed. An empty, whitespace-only, comment-only or JSON-null local file uses defaults without CM0001. A declared inherited configuration must still contain a JSON object.
+
+### 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. The username and password are omitted from the resulting diagnostic. Committing an `alcops.json` that references an external source means trusting that source to supply analyzer settings.
+
+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.
+
+Successfully loaded configurations are cached per workspace path during the analyzer session. Each compilation uses a consistent configuration snapshot. HTTP requests use a five-second timeout and accept at most **1 MiB (1,048,576 bytes)** of response content. The size limit also applies to chunked responses and responses without a `Content-Length` header.
+
+If a declared `Extends` source cannot be resolved, **the entire configuration falls back to the built-in defaults**. Neither the inherited settings nor the local overrides are applied. This includes unreachable sources, HTTP errors, timeouts, oversized HTTP responses, unreadable files, malformed JSON, incompatible setting values, invalid `Extends.Source` declarations, and inheritance chains. A [CM0001 warning](/docs/analyzers/common/cm0001/) identifies the failing source and reason, so the fallback is visible in VS Code and command-line builds.
+
+For example, with a local `CyclomaticComplexityThreshold` of `41` and an unavailable base configuration, the effective threshold is the built-in default `8`. Keeping `41` would apply only part of the intended configuration.
+
+Unknown top-level setting names are handled separately: recognized settings still apply, with one `CM0001` warning per unknown name in either configuration. An invalid value in the base configuration is still an error even when a local override would replace it.
+
+Failed HTTP requests are cached per workspace path for **30 seconds after the failed request completes**. This covers network errors, timeouts, HTTP error statuses and oversized response bodies. Compilations during this cooldown reuse defaults and CM0001 without fetching again, so offline editing does not trigger another request on every analysis pass. Cache hits do not extend the cooldown. After it expires, the first new compilation requesting settings makes one shared retry; another failed request starts a new 30-second cooldown. A successful retry stays cached for the analyzer session. Existing compilations keep their original settings and diagnostic snapshot, even after recovery. There is no timer or background refresh.
+
+The first analysis using an uncached HTTP source, and each retry after the cooldown, can wait for up to the five-second request timeout. Cancelling that analysis also cancels the request. Cancellation does not produce CM0001, cache a failed result or start a new cooldown.
+
+Successfully loaded settings and deterministic configuration errors, such as malformed JSON or an invalid source declaration, remain cached for the analyzer session. After changing these, restart the analyzer process; in VS Code, use **Developer: Reload Window**. Command-line builds reload settings when a new compiler process starts.
 
 ### NamingPatterns