Merge pull request #376 from LarryHu0217/codex/x-correlator-doc-371

hdamker · web-flow · commit 49bb5a9f11de · 2026-07-16T12:50:29.000+02:00
feat(validation): check x-correlator documentation
diff --git a/linting/config/.spectral-r4.yaml b/linting/config/.spectral-r4.yaml
@@ -16,6 +16,7 @@
 #   array items description, notification content-type
 # - 14.06.2026: Added camara-integer-safe-range rule (S-038)
 # - 08.07.2026: Reworded S-038 description and message to the OpenAPI Format Registry framing
+# - 15.07.2026: Added x-correlator documentation rules (S-039, S-040)
 
 
 # Note: @stoplight/spectral-owasp-ruleset is installed via validation/package.json.
@@ -37,6 +38,7 @@ functions:
   - camara-notification-content-type
   - camara-no-numeric-resource-ids
   - camara-integer-safe-range
+  - camara-x-correlator-documentation
 functionsDir: "./lint_function"
 rules:
   #  Built-in OpenAPI Specification ruleset. Each rule then can be enabled individually.
@@ -552,6 +554,28 @@ rules:
       function: camara-integer-safe-range
     recommended: true
 
+  camara-x-correlator-request-parameter:
+    description: "Every operation MUST document the x-correlator request header parameter."
+    message: "{{error}}"
+    severity: warn
+    given: "$"
+    then:
+      function: camara-x-correlator-documentation
+      functionOptions:
+        target: request
+    recommended: true
+
+  camara-x-correlator-response-header:
+    description: "Every documented response MUST document the x-correlator response header."
+    message: "{{error}}"
+    severity: warn
+    given: "$"
+    then:
+      function: camara-x-correlator-documentation
+      functionOptions:
+        target: response
+    recommended: true
+
   # ===== OWASP API Security Top 10 2023 =====
   # Source: Commonalities Linting-rules.md section 5
   # Severity overrides per CAMARA agreement (Commonalities #539, #548, #551, #552)
diff --git a/linting/config/lint_function/camara-x-correlator-documentation.js b/linting/config/lint_function/camara-x-correlator-documentation.js
@@ -0,0 +1,94 @@
+// CAMARA Project - support function for Spectral linter
+// Checks x-correlator documentation on regular and callback operations.
+
+const OPERATION_METHODS = ["get", "put", "post", "delete", "patch", "options"];
+
+function isObject(value) {
+  return value !== null && typeof value === "object";
+}
+
+function hasXCorrelatorParameter(parameters) {
+  return Array.isArray(parameters) && parameters.some((parameter) => (
+    isObject(parameter) &&
+    String(parameter.in).toLowerCase() === "header" &&
+    String(parameter.name).toLowerCase() === "x-correlator"
+  ));
+}
+
+function hasXCorrelatorHeader(response) {
+  return isObject(response?.headers) && Object.keys(response.headers).some(
+    (name) => name.toLowerCase() === "x-correlator"
+  );
+}
+
+export default (document, options, context) => {
+  const target = options?.target;
+  if (target !== "request" && target !== "response") return [];
+
+  const findings = [];
+
+  function checkOperation(operation, inheritedParameters, path, ancestors) {
+    if (!isObject(operation)) return;
+
+    if (target === "request") {
+      const effectiveParameters = [
+        ...(Array.isArray(inheritedParameters) ? inheritedParameters : []),
+        ...(Array.isArray(operation.parameters) ? operation.parameters : []),
+      ];
+      if (!hasXCorrelatorParameter(effectiveParameters)) {
+        findings.push({
+          message: "Operation must document the 'x-correlator' request header parameter",
+          path: [...path, "parameters"],
+        });
+      }
+    } else if (isObject(operation.responses)) {
+      for (const [status, response] of Object.entries(operation.responses)) {
+        if (!hasXCorrelatorHeader(response)) {
+          findings.push({
+            message: `Response '${status}' must document the 'x-correlator' response header`,
+            path: [...path, "responses", status, "headers"],
+          });
+        }
+      }
+    }
+
+    if (!isObject(operation.callbacks)) return;
+    for (const [callbackName, callback] of Object.entries(operation.callbacks)) {
+      if (!isObject(callback)) continue;
+      for (const [expression, pathItem] of Object.entries(callback)) {
+        walkPathItem(
+          pathItem,
+          [...path, "callbacks", callbackName, expression],
+          ancestors
+        );
+      }
+    }
+  }
+
+  function walkPathItem(pathItem, path, ancestors) {
+    if (!isObject(pathItem) || ancestors.has(pathItem)) return;
+
+    const nextAncestors = new Set(ancestors);
+    nextAncestors.add(pathItem);
+    const inheritedParameters = pathItem.parameters;
+
+    for (const method of OPERATION_METHODS) {
+      if (isObject(pathItem[method])) {
+        checkOperation(
+          pathItem[method],
+          inheritedParameters,
+          [...path, method],
+          nextAncestors
+        );
+      }
+    }
+  }
+
+  if (isObject(document?.paths)) {
+    for (const [pathName, pathItem] of Object.entries(document.paths)) {
+      walkPathItem(pathItem, [...context.path, "paths", pathName], new Set());
+    }
+  }
+
+  return findings;
+};
diff --git a/validation/rules/spectral-rules.yaml b/validation/rules/spectral-rules.yaml
@@ -219,6 +219,16 @@
   engine_rule: camara-integer-safe-range
   short_title: "Integer value exceeds safe range"
 
+- id: S-039
+  engine: spectral
+  engine_rule: camara-x-correlator-request-parameter
+  short_title: "x-correlator request header is undocumented"
+
+- id: S-040
+  engine: spectral
+  engine_rule: camara-x-correlator-response-header
+  short_title: "x-correlator response header is undocumented"
+
 # ===== Built-in OAS rules (S-200+) =====
 
 - id: S-200
diff --git a/validation/tests/test_rule_metadata_integrity.py b/validation/tests/test_rule_metadata_integrity.py
@@ -89,7 +89,7 @@ def test_expected_rule_counts(self, all_rules):
         for r in all_rules:
             counts[r.engine] = counts.get(r.engine, 0) + 1
         assert counts["python"] == 36
-        assert counts["spectral"] == 86
+        assert counts["spectral"] == 88
         assert counts["gherkin"] == 25
         assert counts["yamllint"] == 13
 
diff --git a/validation/tests/test_spectral_x_correlator.py b/validation/tests/test_spectral_x_correlator.py
@@ -0,0 +1,217 @@
+"""Regression tests for x-correlator documentation rules S-039 and S-040."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+_RULESET = _REPO_ROOT / "linting" / "config" / ".spectral-r4.yaml"
+_NODE_MODULES = _REPO_ROOT / "validation" / "node_modules"
+_REQUEST_RULE = "camara-x-correlator-request-parameter"
+_RESPONSE_RULE = "camara-x-correlator-response-header"
+
+
+def _run_spectral(files: dict[str, str], entrypoint: str = "api.yaml") -> list[dict]:
+    with tempfile.TemporaryDirectory() as directory:
+        root = Path(directory)
+        for name, content in files.items():
+            target = root / name
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+
+        env = {
+            "PATH": os.environ.get("PATH", ""),
+            "NODE_PATH": str(_NODE_MODULES),
+            "HOME": os.environ.get("HOME", ""),
+        }
+        result = subprocess.run(
+            [
+                "node",
+                str(_NODE_MODULES / ".bin" / "spectral"),
+                "lint",
+                str(root / entrypoint),
+                "-r",
+                str(_RULESET),
+                "--format",
+                "json",
+            ],
+            capture_output=True,
+            text=True,
+            env=env,
+            timeout=30,
+        )
+        assert result.stdout.strip(), result.stderr
+        return json.loads(result.stdout)
+
+
+def _for_rule(findings: list[dict], rule: str) -> list[dict]:
+    return [finding for finding in findings if finding["code"] == rule]
+
+
+_SPEC = """\
+openapi: 3.0.3
+info:
+  title: Correlator Test
+  version: wip
+paths:
+  /widgets:
+    get:
+      operationId: getWidgets
+      parameters:
+        - name: x-correlator
+          in: header
+          schema:
+            type: string
+      responses:
+        "200":
+          description: OK
+          headers:
+            x-correlator:
+              schema:
+                type: string
+"""
+
+
+def test_documented_request_and_response_pass():
+    findings = _run_spectral({"api.yaml": _SPEC})
+    assert _for_rule(findings, _REQUEST_RULE) == []
+    assert _for_rule(findings, _RESPONSE_RULE) == []
+
+
+def test_path_level_request_parameter_applies_to_operation():
+    spec = _SPEC.replace(
+        "    get:\n      operationId: getWidgets\n      parameters:\n",
+        "    parameters:\n      - name: x-correlator\n        in: header\n        schema:\n          type: string\n    get:\n      operationId: getWidgets\n      parameters:\n",
+    ).replace(
+        "        - name: x-correlator\n          in: header\n          schema:\n            type: string\n",
+        "        - name: limit\n          in: query\n          schema:\n            type: integer\n",
+    )
+    findings = _run_spectral({"api.yaml": spec})
+    assert _for_rule(findings, _REQUEST_RULE) == []
+
+
+def test_missing_request_parameter_reports_operation_path():
+    spec = _SPEC.replace("        - name: x-correlator", "        - name: traceparent")
+    findings = _for_rule(_run_spectral({"api.yaml": spec}), _REQUEST_RULE)
+    assert len(findings) == 1
+    assert findings[0]["path"] == ["paths", "/widgets", "get", "parameters"]
+
+
+def test_each_response_without_header_is_reported():
+    spec = _SPEC.replace(
+        "          headers:\n            x-correlator:\n              schema:\n                type: string\n",
+        "",
+    ) + """\
+        "400":
+          description: Bad request
+          headers: {}
+"""
+    findings = _for_rule(_run_spectral({"api.yaml": spec}), _RESPONSE_RULE)
+    assert len(findings) == 2
+    assert any("200" in finding["path"] for finding in findings)
+    assert any("400" in finding["path"] for finding in findings)
+
+
+def test_component_references_are_resolved():
+    spec = """\
+openapi: 3.0.3
+info:
+  title: Correlator Test
+  version: wip
+paths:
+  /widgets:
+    get:
+      operationId: getWidgets
+      parameters:
+        - $ref: "#/components/parameters/XCorrelator"
+      responses:
+        "200":
+          $ref: "#/components/responses/CorrelatedResponse"
+components:
+  parameters:
+    XCorrelator:
+      name: x-correlator
+      in: header
+      schema:
+        type: string
+  responses:
+    CorrelatedResponse:
+      description: OK
+      headers:
+        x-correlator:
+          schema:
+            type: string
+"""
+    findings = _run_spectral({"api.yaml": spec})
+    assert _for_rule(findings, _REQUEST_RULE) == []
+    assert _for_rule(findings, _RESPONSE_RULE) == []
+
+
+def test_external_references_are_resolved():
+    spec = """\
+openapi: 3.0.3
+info:
+  title: Correlator Test
+  version: wip
+paths:
+  /widgets:
+    get:
+      operationId: getWidgets
+      parameters:
+        - $ref: "./common.yaml#/components/parameters/XCorrelator"
+      responses:
+        "200":
+          $ref: "./common.yaml#/components/responses/CorrelatedResponse"
+"""
+    common = """\
+openapi: 3.0.3
+info:
+  title: Common
+  version: wip
+paths: {}
+components:
+  parameters:
+    XCorrelator:
+      name: x-correlator
+      in: header
+      schema:
+        type: string
+  responses:
+    CorrelatedResponse:
+      description: OK
+      headers:
+        x-correlator:
+          schema:
+            type: string
+"""
+    findings = _run_spectral({"api.yaml": spec, "common.yaml": common})
+    assert _for_rule(findings, _REQUEST_RULE) == []
+    assert _for_rule(findings, _RESPONSE_RULE) == []
+
+
+def test_callback_operation_is_in_scope():
+    spec = _SPEC.replace(
+        "      responses:\n",
+        "      callbacks:\n"
+        "        onEvent:\n"
+        "          '{$request.body#/sink}':\n"
+        "            post:\n"
+        "              operationId: onEvent\n"
+        "              responses:\n"
+        "                '204':\n"
+        "                  description: Accepted\n"
+        "      responses:\n",
+        1,
+    )
+    findings = _run_spectral({"api.yaml": spec})
+    request_findings = _for_rule(findings, _REQUEST_RULE)
+    response_findings = _for_rule(findings, _RESPONSE_RULE)
+    assert len(request_findings) == 1
+    assert "callbacks" in request_findings[0]["path"]
+    assert len(response_findings) == 1
+    assert "callbacks" in response_findings[0]["path"]
