refactor(traceability): parameterise the extractor for all three components

The tool is moving into the jray-project submodule to be shared by
scene-actor-extraction (C++/Python), jRay (C#) and JRay-public-server
(Rust). Two constants blocked that: LOCAL_TYPES and SOURCE_SUFFIXES were
hardcoded to this repo, so either sibling parsed zero requirements and
scanned zero files. Both, plus the register path, scan roots, system-spec
path, exclude list and CI-executable tier set, are now configuration.

One implementation, parameterised. A second copy for "the other language"
is how two implementations start drifting apart, so there is exactly one -
the same code path now produces:

  scene-actor-extraction  AR/DP/IR/GR/VR   59 defined   0 tagged    0.0%
  jRay                    JR               46 defined  24 covered  52.2%
  JRay-public-server      UR/DR            32 defined  23 covered  71.9%

Configuration is traceability.toml at the component repo root, CLI flags,
or both (flags win). Its directory defines the repo root, so the gate works
from any subdirectory. `--print-example-config` emits the annotated schema.
The JSON report echoes the settings it ran with, since a shared tool's
output is otherwise ambiguous about which repo it describes.

The refusal behaviour is kept and sharpened, because parameterising is
exactly what makes it easy to point a repo at the wrong prefixes or the
wrong suffixes. Zero requirements parsed or zero files scanned is still a
hard failure, and the message now names the setting that is wrong rather
than printing a plausible 0%. Config errors exit 2, not 1: a broken config
is not a coverage failure, and conflating them makes CI logs lie about why
the job went red.

Also fixed while adapting to the sibling registers, which are read but not
modified here:

  * escaped `\|` inside a markdown cell no longer shifts every later column
    (the server's register contains `small-\|M\|`);
  * a tag above an attribute-decorated declaration attributes to the
    declaration, not to `[HttpGet(...)]` or `#[derive(...)]` - the gap
    jRay's register calls out;
  * Rust and C# declaration patterns for context extraction;
  * the missing-tier warning is suppressed for a register that assigns no
    tiers at all, rather than listing every requirement in it.

The workflow is now component-agnostic too: the changed-file check reads
its extension list out of the report the gate just wrote, so the definition
of "source file" lives in one place.

79 tests, still fixture-based, now including the cross-repo cases: the same
parser over JR and UR/DR registers, the same scanner over Rust and C#, and
both misconfigurations failing loudly.
This commit is contained in:
2026-07-30 18:35:56 +02:00
parent 054c4c8b8f
commit faaa71fa09
6 changed files with 1257 additions and 447 deletions
+34
View File
@@ -0,0 +1,34 @@
# Traceability configuration for scene-actor-extraction.
#
# Read by the shared extractor (scripts/traceability/extract_traces.py), which
# is the same implementation every JRay component uses. Everything repo-specific
# lives here rather than in the tool; run `extract_traces.py
# --print-example-config` for the annotated schema.
#
# This file's directory is taken as the repo root, so the gate works from any
# subdirectory.
# The prefixes this repo's register defines. Nothing else enters the fraction:
# UT/IT are evidence for requirements, PR/SR belong to the system spec.
requirement_types = ["AR", "DP", "IR", "GR", "VR"]
# C++ pipeline plus the Python tooling, optimizer and validation scripts.
languages = ["cpp", "python"]
source_roots = ["src", "tests", "scripts", "experiments", "eval"]
# CI is an Intel N100 with no discrete GPU. T4 is deliberately absent: a
# requirement verifiable only on GPU hardware is reported as tagged but
# unexecuted and never counted as covered, because counting a test that cannot
# run is the same failure mode as JellyTau's 158% coverage bug.
ci_executable_tiers = ["T1", "T2", "T3", "static"]
# Threshold policy. 0 today because almost nothing is tagged yet - tags land as
# the pipeline is built. This is not a gate that cannot fail: orphan tags, a
# >100% ratio, a register that parses to nothing and an empty source scan are
# all hard failures already. Ratchet this up as tags land; never reset it down.
min_coverage = 0.0
# The system spec owning PR/SR is vendored per-component as a submodule. Point
# at it once that lands to turn on PR/SR orphan checking:
# system_spec = "scripts/vendor/jray-project/SPEC.md"