diff --git a/documentation/SupportingDocuments/CAMARA-Release-Workflow-and-Metadata-Concept.md b/documentation/SupportingDocuments/CAMARA-Release-Workflow-and-Metadata-Concept.md index 5faac2d..48555fd 100644 --- a/documentation/SupportingDocuments/CAMARA-Release-Workflow-and-Metadata-Concept.md +++ b/documentation/SupportingDocuments/CAMARA-Release-Workflow-and-Metadata-Concept.md @@ -220,7 +220,7 @@ After approval and Release PR merge to snapshot branch: 4. **Codeowner publishes** via `/publish-release --confirm ` → creates git tag (e.g., `r4.1`) 5. CI builds and publishes artifacts 6. GitHub Release with artifacts is finalized: - - Bundled OpenAPI specifications (later phase) + - Standalone OpenAPI specifications (bundled on the snapshot branch, included in the auto-generated source archive) - Generated documentation - Release metadata files diff --git a/documentation/SupportingDocuments/CAMARA-Validation-Framework-Detailed-Design.md b/documentation/SupportingDocuments/CAMARA-Validation-Framework-Detailed-Design.md index ee8a94b..7250f13 100644 --- a/documentation/SupportingDocuments/CAMARA-Validation-Framework-Detailed-Design.md +++ b/documentation/SupportingDocuments/CAMARA-Validation-Framework-Detailed-Design.md @@ -1,7 +1,7 @@ # Validation Framework — Detailed Design **Status**: Work in progress -**Last updated**: 2026-03-18 +**Last updated**: 2026-03-26 > This document supplements the [Validation Framework Requirements](CAMARA-Validation-Framework-Requirements.md) with design and implementation detail for developers and architects. It is expected to migrate to the `tooling` repository alongside the implementation. @@ -18,7 +18,8 @@ id: "042" # flat sequential ID, stable across engine changes name: path-kebab-case # human-readable name engine: spectral # spectral | yamllint | gherkin | python | manual engine_rule: "camara-parameter-casing-convention" # native engine rule ID (if applicable) -hint: "Use kebab-case for all path segments: /my-resource/{resourceId}" +message_override: null # replaces engine message entirely (optional, rare) +hint: "Use kebab-case for all path segments: /my-resource/{resourceId}" # additional fix guidance alongside engine message (optional) applicability: # only list fields that constrain; omitted = no constraint branch_types: [main, release] @@ -51,7 +52,7 @@ conditional_level: overrides: - condition: target_api_status: [draft] - level: off + level: muted ``` ### 1.2 Condition Evaluation @@ -82,14 +83,14 @@ The framework uses Spectral's severity names (`error`, `warn`, `hint`) as its na | `warn` | `warn` | Identity | | `hint` | `hint` | Identity | | `info` | `hint` | Mapped (rarely used) | -| `off` | `off` | Identity (disable rule) | +| `off` | `muted` | Mapped (disable rule) | Spectral rules already include `message` fields with fix guidance. Therefore, **Spectral rules that do not need context-dependent severity or applicability filtering do not require explicit framework metadata entries**. Their findings pass through with direct severity mapping and native messages. Framework metadata is only needed for Spectral rules when: - The level should change based on context (e.g., error on release branch, hint on feature branch) - The rule should be suppressed in certain contexts (applicability filtering) -- The fix hint should be overridden or augmented +- The engine message should be replaced (`message_override`) or additional fix guidance should be added (`hint`) This minimizes the metadata surface: only rules with context-dependent behavior need explicit entries. @@ -685,7 +686,7 @@ applicability: conditional_level: default: error description: "Release review PR may only modify CHANGELOG and README files" -hint: "Only CHANGELOG.md (or CHANGELOG/ directory) and README.md may be modified on the release review branch. API specs and other files are immutable on the snapshot branch." +hint: "Only CHANGELOG.md (or CHANGELOG/ directory) and README.md may be modified on the release review branch. API specs and other files are immutable on the snapshot branch." # additional guidance shown alongside the engine message ``` ### 7.4 Pre-Snapshot Invocation Detail @@ -994,7 +995,7 @@ All engine outputs are normalized into a common findings format before post-filt line: 47 # line in source file (mapped back if bundled) column: 5 # column (if available from engine) api_name: "quality-on-demand" # which API this finding belongs to - hint: "Use kebab-case: /quality-on-demand/{sessionId}" + hint: "Use kebab-case: /quality-on-demand/{sessionId}" # additional fix guidance (from rule metadata, optional) ``` | Field | Source — Spectral | Source — yamllint | Source — gherkin-lint | Source — Python | @@ -1008,9 +1009,10 @@ All engine outputs are normalized into a common findings format before post-filt | `line` | `range.start.line` (0-indexed → 1-indexed) | Line number from output | Line number from output | Set directly | | `column` | `range.start.character` | Column from output | Column from output (or null) | Set directly (or null) | | `api_name` | Derived from file path | Derived from file path | Derived from file path | Set directly | -| `hint` | From rule metadata `hint` field (if present); otherwise engine `message` serves as hint | From rule metadata | From rule metadata | Set directly | +| `message` (post-filter) | If rule metadata has `message_override`: replaces engine message. Otherwise: engine message preserved | Same | Same | Set directly (no override) | +| `hint` | From rule metadata `hint` field (optional additional fix guidance); absent if no metadata or no hint defined | From rule metadata | From rule metadata | Set directly (optional) | -Spectral rules **without** explicit framework metadata entries pass through with identity mapping (section 1.3): `rule_id` is auto-assigned, `hint` defaults to the engine's `message`, and the level maps directly. This means the check inventory does not need to be complete before the framework can run — new Spectral rules work immediately. +Spectral rules **without** explicit framework metadata entries pass through with identity mapping (section 1.3): `rule_id` is auto-assigned, the engine's `message` is preserved, no `hint` is added, and the level maps directly. This means the check inventory does not need to be complete before the framework can run — new Spectral rules work immediately. ### 8.5 Composite Action Boundaries @@ -1055,9 +1057,9 @@ The post-filter evaluates each raw finding against the rule metadata (section 1) 2. **Applicability evaluation**: Apply the rule's `applicability` conditions against the current context (section 1.2). If any condition does not match, the finding is silently removed — it does not apply in this context. -3. **Conditional level resolution**: Apply `conditional_level` overrides against the context (section 1.2). The first matching override determines the resolved level; if none match, the default level is used. The resolved level replaces the engine-reported level. If the resolved level is `off`, the finding is removed. +3. **Conditional level resolution**: Apply `conditional_level` overrides against the context (section 1.2). The first matching override determines the resolved level; if none match, the default level is used. The resolved level replaces the engine-reported level. If the resolved level is `muted`, the finding is removed. -4. **Pass-through**: Spectral rules without explicit framework metadata entries pass through with identity mapping (section 1.3). Their engine-reported severity becomes the resolved level, and the engine's `message` serves as the hint. This is the common case for most Spectral rules — the framework runs without requiring a complete metadata inventory. +4. **Pass-through**: Spectral rules without explicit framework metadata entries pass through with identity mapping (section 1.3). Their engine-reported severity becomes the resolved level, the engine's `message` is preserved, and no `hint` is added. This is the common case for most Spectral rules — the framework runs without requiring a complete metadata inventory. **Per-API evaluation**: Findings associated with a specific API (identified by `api_name`) are evaluated against that API's context fields (`target_api_status`, `target_api_maturity`, `api_pattern`). Repository-level findings (e.g., release-plan.yaml checks) are evaluated against the repository-level context. @@ -1134,7 +1136,7 @@ Commit: abc1234 | Tooling: def5678 | [Full workflow run]({workflow_run_url}) One annotation per finding, mapped to the source file and line number: - Annotation level: `failure` for error, `warning` for warn, `notice` for hint -- Annotation message: includes the rule ID, engine rule name, and fix hint +- Annotation message: includes the rule ID, engine rule name, message (or `message_override` if set), and hint (if present) - Annotation title: rule name from metadata (or engine rule name if no metadata) GitHub limits annotations to **50 per step**. If more findings exist: diff --git a/documentation/SupportingDocuments/CAMARA-Validation-Framework-Requirements.md b/documentation/SupportingDocuments/CAMARA-Validation-Framework-Requirements.md index 8dad0ac..4abb5d2 100644 --- a/documentation/SupportingDocuments/CAMARA-Validation-Framework-Requirements.md +++ b/documentation/SupportingDocuments/CAMARA-Validation-Framework-Requirements.md @@ -89,7 +89,7 @@ The profile (section 2.1) then determines which levels block. This separates thr | **error** | Must be fixed | standard, strict | | **warn** | Should be fixed | strict | | **hint** | Recommendation, never blocking | *(none)* | -| **off** | Suppressed, finding not shown | *(n/a)* | +| **muted** | Suppressed, finding not shown | *(n/a)* | #### Applicability conditions @@ -110,7 +110,7 @@ Range comparison for `commonalities_release` uses `packaging.specifiers` (Python #### Conditional level -`default` is always present. `overrides` is a list of `{condition, level}` pairs evaluated in order; first match wins. Conditions use the same field/value model as applicability (AND across fields, OR within arrays). The level `off` can be used in overrides to suppress a finding in specific contexts. +`default` is always present. `overrides` is a list of `{condition, level}` pairs evaluated in order; first match wins. Conditions use the same field/value model as applicability (AND across fields, OR within arrays). The level `muted` can be used in overrides to suppress a finding in specific contexts. #### Execution context