Artifacts Lint: attribute Spectral findings per template and document the expected baseline

[hdamker]

What type of PR is this?

• bug

What this PR does / why we need it:

The Spectral step of the Artifacts Lint workflow (#673) linted all four templates in one invocation. Spectral loses the source file of most findings when several input documents share $ref targets (stoplightio/spectral#2640), so the step reported 9 problems in its summary, emitted 152 ::warning lines, and produced 10 annotations of which 3 pointed at . line 1 — while the two real findings in api-templates/sample-service.yaml had no annotation at all. Details and the reproduction in #684.

Spectral now runs once per template and the results are merged, which is what CAMARA Validation already does for the same reason. Six findings that the old view hid become visible, and the log, the annotations and the summary now describe one set of 15 findings instead of three different numbers:

• .github/scripts/spectral_annotations.py merges the per-template JSON, deduplicates on (file, line, rule), emits the annotations, and prints a reconciliation table to the log and to the run summary.
• The 10 findings that are the documented common-library baseline are collapsed into one notice annotation per source file, pointing at artifacts/linting_rules/README.md. The remaining 5 keep an individual annotation at their native severity.
• The allowlist behind that split is read from validation/rules/spectral-rules.yaml in camaraproject/tooling (rule S-313 suppress_schema_paths) — added to the existing sparse-checkout rather than copied, so it cannot drift from what API repositories apply. Matching replicates the tooling semantics, including the dot-boundary prefix rule, so a newly added unconstrained string in a common schema still surfaces on its own.

Annotation budget, per step: 5 of 10 warning slots used, plus 2 notices — against 10 of 10 consumed by the baseline before this change, where a warning introduced by a pull request could go unannotated.

artifacts/linting_rules/README.md gains the expected-findings section from #676: all 15 findings with their rationale, keyed on schema path rather than line number so it does not go stale, and marked collapsed or individual so it can be checked against what the workflow actually annotates.

Which issue(s) this PR fixes:

Fixes #684
Fixes #676

Does this PR introduce a breaking change?

• Yes
• No

Special notes for reviewers:

• The two halves are mutually dependent: the aggregate annotation points at the README section, and the section's baseline is the corrected 15-finding set — so they are reviewable only together.
• All numbers were reproduced against main with the pinned toolchain (Spectral 6.16.2, .spectral-r4.yaml): 152 raw results with 9 sourced for one invocation over four templates, versus 26 raw results with none unsourced and 15 unique for one invocation per template.
• Bare Spectral reads no rule metadata, so the 15-finding baseline is irreducible here: camaraproject/tooling#401 will not change what this CI shows. Under this change, however, the pagination Link header finding stops being annotated individually the moment S-313: suppress the unactionable finding on the common pagination Link header tooling#401 lands, with no edit needed in this repository.
• Two groups from Document the expected lint warnings of the artifacts (fix-or-document standard) #676 need no documentation: the 9 oas3-unused-component findings are gone since tooling made unused-component detection discriminator-aware, and the gplint findings are being fixed (Feature file templates: fix the remaining gplint findings (placeholder syntax, scenario names) #682, via Fix remaining gplint findings in the feature templates #683) rather than documented as expected. The section therefore covers Spectral only.
• Verified on a dispatched run before this PR (hdamker/Commonalities run 30483686070): the Spectral step produces 5 warning annotations at the five locations listed in the README section plus 2 notice aggregates, and no annotation points at . line 1.
• A Spectral runtime error on one template no longer hides the other three: the step reports what the rest found, annotates the failed template, and then fails.

Changelog input

 release-note
- Artifacts Lint: Spectral runs per template so findings keep their source file; annotations now cover the findings that need review, the documented baseline is collapsed into one notice per file, and the log and run summary report one reconciled count
- Documented the expected lint findings of the artifacts in artifacts/linting_rules/README.md

Additional documentation

docs
artifacts/linting_rules/README.md — new "Expected lint findings" section

[rartych]

LGTM

[PedroDiez]

LGTM

[bigludo7]

LGTM