diff --git a/content/features/te-cli/te-cli-commands.md b/content/features/te-cli/te-cli-commands.md index 50eb3f17..57c8f503 100644 --- a/content/features/te-cli/te-cli-commands.md +++ b/content/features/te-cli/te-cli-commands.md @@ -407,7 +407,7 @@ Run Best Practice Analyzer rules against a model. `te bpa run` accepts: - `` - positional argument: path to model (alternative to the `--model` global flag). -- `-r, --rules ` - path(s) or URL(s) to additional BPA rule file(s) in JSON format. Repeatable. +- `-r, --rules ` - path(s) or URL(s) to BPA rule file(s) in JSON format. Repeatable. Replaces the user-rule layer for this invocation: see [Rule sources and resolution](#rule-sources-and-resolution) below. - `--no-model-rules` - exclude BPA rules embedded in the model's annotations. - `--no-defaults` - exclude built-in default BPA rules. - `--vpax ` - load VertiPaq Analyzer stats from a `.vpax` file to enable VPA-aware rules. @@ -433,6 +433,25 @@ te bpa run --path 'Sa*' # Wildcard - every table starting with Sa te bpa run --path Sales/Measures # Path filter applied to the matched tables ``` +#### Rule sources and resolution + +Each `te bpa run` invocation assembles rules from three independent layers: + +1. **User rules** - exactly one source wins, in priority order: + - `-r, --rules ` flag, accepts a file path or URL (highest) + - `TE_BPA_RULES` environment variable + - `bpa.rules` array from CLI config (`~/.config/te/config.json`) +2. **Built-in defaults** - loaded unless `--no-defaults` is passed or [`bpa.builtInRules`](xref:te-cli-config#built-in-bpa-rules) is `false` in config. Individual built-ins listed in `bpa.disabledBuiltInRuleIds` are skipped. +3. **Model-embedded rules** - rules in the model's `BestPracticeAnalyzer_Rules` annotation, loaded unless `--no-model-rules` is passed. External URL annotations are skipped unless `--allow-external-rules` is also passed. + +Duplicate rule IDs are de-duplicated (user rules win over built-ins). Rule IDs in the model's `BestPracticeAnalyzer_IgnoreRules` annotation are then removed. + +The `Rules loaded:` line in the output attributes each contributing layer, for example: + +``` +Rules loaded: 41 from 1 file(s) from bpa.rules config + built-in defaults + model annotations +``` + ### bpa rules Manage BPA rule collections — list, inspect, initialize, and toggle rules in your local rules file or in model annotations. Built-in rules are read-only - to skip one without losing the rest, use `te bpa rules disable` (do not edit the built-in set directly). diff --git a/content/features/te-cli/te-cli-config.md b/content/features/te-cli/te-cli-config.md index 95c442a4..647ff232 100644 --- a/content/features/te-cli/te-cli-config.md +++ b/content/features/te-cli/te-cli-config.md @@ -121,7 +121,7 @@ Set these in your config to avoid passing the same paths on every command. Per-c | Key | Meaning | | -- | -- | | `macros` | Explicit path to a macros JSON file (typically `MacroActions.json`). Resolved by every `te macro` command. Point at a shared file (network share, repo-local, or even the TE3 desktop file) to reuse the same set of macros across machines and between the CLI and TE3 Desktop. | -| `bpa.rules` | Ordered list of paths or URLs to BPA rule files. The deploy/save gate loads **every** existing entry; `te bpa rules list` and `te config paths` use the first existing entry. Comma-separated values on `te config set bpa.rules ...` are split into the array. | +| `bpa.rules` | Ordered list of paths or URLs to BPA rule files. `te bpa run` and the deploy/save gate load **every** existing entry; `te bpa rules list` and `te config paths` use the first existing entry. Comma-separated values on `te config set bpa.rules ...` are split into the array. | | `te3ExePath` | Explicit path to the Tabular Editor 3 Desktop executable (`TabularEditor.exe`). Used **only** by `te open` to launch the desktop app; safe to leave unset on Linux/macOS or when you don't use `te open`. If unset, `te open` falls back to a `PATH` lookup. | | `queryLog` | Path to a log file where every `te query` invocation appends its query text and execution metadata. Useful for audit trails or analyzing query patterns over time. Supports `~` for the home directory (e.g., `~/.config/te/queries.log`). | diff --git a/content/features/te-cli/te-cli-limitations.md b/content/features/te-cli/te-cli-limitations.md index 1e52055d..09371a14 100644 --- a/content/features/te-cli/te-cli-limitations.md +++ b/content/features/te-cli/te-cli-limitations.md @@ -44,8 +44,8 @@ The CLI runs C# scripts (`te script`) against the same `Model` object you use in | -- | -- | | **BPA rule sources must be HTTPS URLs or local file paths** | Only `https://` URLs and bare local file paths are accepted. `http://` is recognized but deliberately rejected at load time with a clear error - BPA rules are executable rule expressions, and fetching them over an unauthenticated channel would be a tampering risk. Other URL schemes (`file://`, `ftp://`, …) are not supported. Applies to both `te bpa run --rules` and the rule list configured via [`te config set`](xref:te-cli-commands#config-show--paths--init--set). | | **Rule-URL validation runs at gate time, not on `te config set`** | A typo such as `http://` is accepted by `te config set` and only surfaces when BPA actually runs. After editing the configured rule sources, run `te bpa run` (or `te validate`) once to verify each URL loads. | -| **`--rules` does not suppress built-in rules** | When `te bpa run --rules ` is passed, the supplied rules replace the entries in [`bpa.rules`](xref:te-cli-commands#config-show--paths--init--set) and `TE_BPA_PATH` for that invocation, but the built-in defaults still load alongside. To run only the explicit rule file, also pass `--no-defaults`. | -| **No per-invocation flag to skip `bpa.rules` config** | Once `bpa.rules` is configured, every `te bpa run` loads those rules in addition to the built-ins. There is currently no flag to skip the configured rule files for a single run. Workaround: pass `--rules ` explicitly - the flag fully replaces `bpa.rules` and `TE_BPA_PATH` for that invocation. | +| **`--rules` does not suppress built-in rules** | When `te bpa run --rules ` is passed, the supplied rules replace the entries in [`bpa.rules`](xref:te-cli-commands#config-show--paths--init--set) and `TE_BPA_RULES` for that invocation, but the built-in defaults still load alongside. To run only the explicit rule file, also pass `--no-defaults`. | +| **No per-invocation flag to skip `bpa.rules` config** | Once `bpa.rules` is configured, every `te bpa run` loads those rules in addition to the built-ins. There is currently no flag to skip the configured rule files for a single run. Workaround: pass `--rules ` explicitly - the flag fully replaces `bpa.rules` and `TE_BPA_RULES` for that invocation. | ## Validation