dtourolleandClaude Opus 5
6ec6c5cbd6
The module doc said an extractor keyed on string literals would "lose six genuine tags to save two false ones". The six is right — `schema.rs` carries that many `-- TRACES:` lines inside Rust literals — but the two undercounted the false ones, which were R1 twice, FR-CAT-1 twice, FR-CAT-2, NFR-P1, one in `gestures.rs` and two emitted by `dr-pipeline/build.rs`. The comparison it was drawing does not need a number on that side to hold. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
680 lines
25 KiB
Rust
680 lines
25 KiB
Rust
//! Requirements traceability for DarkRoom.
|
|
//!
|
|
//! Extracts `TRACES:` tags from source, counts what `requirements.md` actually
|
|
//! defines, and reports coverage as the intersection of the two.
|
|
//!
|
|
//! # Why the arithmetic is written this way
|
|
//!
|
|
//! Adapted from the JellyTau tooling, including the bug it was repaired for.
|
|
//! That gate divided a traced count by *frozen literal* denominators; the
|
|
//! requirements file grew past them, and it reported **158% coverage**. A gate
|
|
//! reporting over 100% cannot fail its own threshold, so it silently stopped
|
|
//! being a gate at all.
|
|
//!
|
|
//! Two rules follow, and both are enforced by tests here:
|
|
//!
|
|
//! 1. **Denominators are parsed from `requirements.md` at run time.** Never
|
|
//! hardcoded, never cached.
|
|
//! 2. **Coverage is `|traced ∩ defined| / |defined|`.** Using the raw traced
|
|
//! count as the numerator is precisely what lets a ratio exceed 100%, since
|
|
//! a tag naming a deleted requirement would count as covered. Such tags are
|
|
//! reported as orphans instead.
|
|
//!
|
|
//! # And why the extractor is fussy about where a tag sits
|
|
//!
|
|
//! A third rule, learned the same way. `SOURCE_ROOTS` includes `tools`, so this
|
|
//! crate scans itself, and the fixtures below demonstrating tag extraction were
|
|
//! read as tags: R1 — cross-platform output within a bounded tolerance — was
|
|
//! reported implemented on the strength of two string literals in a unit test.
|
|
//!
|
|
//! 3. **A tag is a comment whose first word is `TRACES:`**, not a line in which
|
|
//! the string appears. See `tag_body`. It is a rule about position rather
|
|
//! than about string literals, because `schema.rs` writes six real tags
|
|
//! *inside* string literals — the SQL it embeds is commented with `--` — so
|
|
//! an extractor that refused string literals would lose more than it saved.
|
|
|
|
use std::collections::{BTreeMap, BTreeSet};
|
|
use std::path::{Path, PathBuf};
|
|
|
|
use serde::Serialize;
|
|
|
|
pub mod gestures;
|
|
|
|
/// Requirement ID prefixes that participate in coverage.
|
|
///
|
|
/// Test identifiers (UT, IT) are a separate taxonomy: they are *evidence* for
|
|
/// requirements, not requirements themselves. Counting them would inflate both
|
|
/// numerator and denominator, and flagging them as orphans would bury real
|
|
/// typos in noise.
|
|
pub const REQUIREMENT_TYPES: &[&str] = &["FR", "NFR", "R"];
|
|
|
|
/// Prefixes recognised in tags but deliberately excluded from coverage.
|
|
///
|
|
/// `D` are decisions, `S` spikes, `M` milestone items, `AC` acceptance
|
|
/// criteria, `UT`/`IT` tests. All are legitimate things to tag against, and
|
|
/// none is a requirement — counting them would inflate the denominator by 25
|
|
/// and make coverage look worse than it is, which is the same class of defect
|
|
/// as JellyTau's inflated ratio, just in the other direction.
|
|
pub const NON_REQUIREMENT_TYPES: &[&str] = &["UT", "IT", "AC", "M", "S", "D"];
|
|
|
|
/// One `TRACES:` tag found in source.
|
|
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
|
|
pub struct TraceEntry {
|
|
pub file: String,
|
|
pub line: usize,
|
|
pub context: String,
|
|
pub requirements: Vec<String>,
|
|
}
|
|
|
|
/// What `requirements.md` defines — the coverage denominators.
|
|
#[derive(Debug, Clone, Default)]
|
|
pub struct DefinedRequirements {
|
|
pub ids: BTreeSet<String>,
|
|
pub by_type: BTreeMap<String, usize>,
|
|
}
|
|
|
|
impl DefinedRequirements {
|
|
pub fn total(&self) -> usize {
|
|
self.ids.len()
|
|
}
|
|
}
|
|
|
|
/// The coverage result.
|
|
#[derive(Debug, Clone, Serialize, PartialEq)]
|
|
pub struct Coverage {
|
|
pub covered: usize,
|
|
pub total: usize,
|
|
pub percent: f64,
|
|
/// Tagged in source but absent from `requirements.md` — a typo, or a
|
|
/// requirement that was renumbered or deleted. Never counted as covered.
|
|
pub orphaned: Vec<String>,
|
|
/// Defined but never tagged anywhere.
|
|
pub untraced: Vec<String>,
|
|
}
|
|
|
|
/// Parse the requirement IDs a markdown document *defines*.
|
|
///
|
|
/// A requirement is defined by a bolded heading-style declaration
|
|
/// (`**FR-CAT-1 — …**`) or as the leading cell of a table row (`| R1 | … |`).
|
|
/// Both forms appear in DarkRoom's requirements.md.
|
|
///
|
|
/// Deliberately *not* a bare scan for anything matching the ID shape: that
|
|
/// counts cross-references in prose and in "relates to" columns as
|
|
/// definitions, inflating the denominator. IDs are deduplicated because a
|
|
/// requirement may legitimately appear in both a definition and a summary
|
|
/// table.
|
|
pub fn parse_defined_requirements(markdown: &str) -> DefinedRequirements {
|
|
let mut ids = BTreeSet::new();
|
|
|
|
for line in markdown.lines() {
|
|
let trimmed = line.trim_start();
|
|
|
|
// Form 1: a bolded definition, e.g. `**FR-CAT-1 — Scan.**`
|
|
if let Some(rest) = trimmed.strip_prefix("**") {
|
|
if let Some(id) = leading_id(rest) {
|
|
ids.insert(id);
|
|
continue;
|
|
}
|
|
}
|
|
|
|
// Form 2: leading table cell, e.g. `| **R1** | … |` or `| R1 | … |`
|
|
if let Some(rest) = trimmed.strip_prefix('|') {
|
|
let cell = rest.trim().trim_start_matches("**");
|
|
if let Some(id) = leading_id(cell) {
|
|
ids.insert(id);
|
|
}
|
|
}
|
|
}
|
|
|
|
// Only requirement types enter the register. Decisions, spikes, milestone
|
|
// items and test ids are all taggable, but none is a requirement, and
|
|
// counting them would inflate the denominator.
|
|
let ids: BTreeSet<String> = ids.into_iter().filter(|id| is_requirement(id)).collect();
|
|
|
|
let mut by_type: BTreeMap<String, usize> = BTreeMap::new();
|
|
for id in &ids {
|
|
*by_type.entry(type_of(id).to_string()).or_insert(0) += 1;
|
|
}
|
|
|
|
DefinedRequirements { ids, by_type }
|
|
}
|
|
|
|
/// Extract a requirement ID anchored at the start of `s`.
|
|
///
|
|
/// Accepts `FR-CAT-1`, `NFR-P13`, `R1`, `FR-DEV-3a` — DarkRoom uses
|
|
/// alphanumeric segments and an optional trailing letter, not the fixed
|
|
/// three-digit form JellyTau assumed.
|
|
fn leading_id(s: &str) -> Option<String> {
|
|
let bytes = s.as_bytes();
|
|
if bytes.is_empty() || !bytes[0].is_ascii_uppercase() {
|
|
return None;
|
|
}
|
|
|
|
let mut end = 0;
|
|
let mut seen_digit = false;
|
|
for (i, c) in s.char_indices() {
|
|
match c {
|
|
'A'..='Z' | '0'..='9' | '-' => {
|
|
if c.is_ascii_digit() {
|
|
seen_digit = true;
|
|
}
|
|
end = i + c.len_utf8();
|
|
}
|
|
'a'..='z' if seen_digit => {
|
|
// Trailing variant letter, e.g. FR-DEV-3a.
|
|
end = i + c.len_utf8();
|
|
}
|
|
_ => break,
|
|
}
|
|
}
|
|
|
|
if end == 0 || !seen_digit {
|
|
return None;
|
|
}
|
|
|
|
let id = s[..end].trim_end_matches('-').to_string();
|
|
// Must have a recognised prefix, or arbitrary capitalised words match.
|
|
let ty = type_of(&id);
|
|
if REQUIREMENT_TYPES.contains(&ty) || NON_REQUIREMENT_TYPES.contains(&ty) {
|
|
Some(id)
|
|
} else {
|
|
None
|
|
}
|
|
}
|
|
|
|
/// The type prefix of an ID: `FR-CAT-1` → `FR`, `R1` → `R`.
|
|
pub fn type_of(id: &str) -> &str {
|
|
let end = id
|
|
.find(|c: char| !c.is_ascii_uppercase())
|
|
.unwrap_or(id.len());
|
|
&id[..end]
|
|
}
|
|
|
|
/// Whether an ID participates in coverage.
|
|
pub fn is_requirement(id: &str) -> bool {
|
|
REQUIREMENT_TYPES.contains(&type_of(id))
|
|
}
|
|
|
|
/// Comment openers a tag may be introduced by.
|
|
///
|
|
/// `--` is here for the SQL embedded in `schema.rs`, which carries real tags
|
|
/// inside Rust string literals; `#` for YAML; `*` for the continuation lines of
|
|
/// a block comment.
|
|
const COMMENT_OPENERS: &[&str] = &["///", "//!", "//", "<!--", "/*", "*", "--", "#"];
|
|
|
|
/// The body of a tag comment, if this line is one.
|
|
///
|
|
/// **A tag is a comment whose first word is `TRACES:`** — not any line in which
|
|
/// the string appears. The tool scans `tools/`, which is its own source, so
|
|
/// without this rule its unit-test fixtures are tags: a one-line literal in
|
|
/// `context_looks_forward_then_backward` had R1 reported as implemented, and
|
|
/// the register believed it. That is not a quirk of this crate. `build.rs`
|
|
/// emits a tag into generated code from a string literal, and any test
|
|
/// anywhere that exercises the extractor would do the same.
|
|
///
|
|
/// The rule does not merely exclude string literals — it cannot tell one from a
|
|
/// comment, and `schema.rs` proves it must not try, since its `-- TRACES:` tags
|
|
/// live inside string literals and are entirely real. What it asks instead is
|
|
/// where on the line the tag sits: a tag written to be read is the first thing
|
|
/// in its comment, and a tag quoted inside an expression never is.
|
|
fn tag_body(line: &str) -> Option<&str> {
|
|
let line = line.trim_start();
|
|
let after_opener = COMMENT_OPENERS.iter().find_map(|o| line.strip_prefix(o))?;
|
|
after_opener.trim_start().strip_prefix("TRACES:")
|
|
}
|
|
|
|
/// Extract every `TRACES:` tag from a source file's text.
|
|
pub fn extract_from_text(text: &str, path: &str) -> Vec<TraceEntry> {
|
|
let lines: Vec<&str> = text.lines().collect();
|
|
let mut out = Vec::new();
|
|
|
|
for (idx, line) in lines.iter().enumerate() {
|
|
let Some(tail) = tag_body(line) else {
|
|
continue;
|
|
};
|
|
let ids = parse_ids(tail);
|
|
if ids.is_empty() {
|
|
continue;
|
|
}
|
|
out.push(TraceEntry {
|
|
file: path.to_string(),
|
|
line: idx + 1,
|
|
context: find_context(&lines, idx),
|
|
requirements: ids,
|
|
});
|
|
}
|
|
|
|
out
|
|
}
|
|
|
|
/// Parse the ID list from a tag body: `FR-CAT-1, FR-CAT-2 | NFR-P1`.
|
|
///
|
|
/// The pipe groups types for readability; both separators are treated alike.
|
|
fn parse_ids(s: &str) -> Vec<String> {
|
|
s.split(['|', ','])
|
|
.filter_map(|part| leading_id(part.trim()))
|
|
.collect()
|
|
}
|
|
|
|
/// The nearest preceding declaration, for the report's context column.
|
|
fn find_context(lines: &[&str], from: usize) -> String {
|
|
const MARKERS: &[&str] = &[
|
|
"pub fn ",
|
|
"fn ",
|
|
"pub struct ",
|
|
"struct ",
|
|
"pub enum ",
|
|
"enum ",
|
|
"impl ",
|
|
"pub trait ",
|
|
"trait ",
|
|
"#[test]",
|
|
"component ",
|
|
"export ",
|
|
];
|
|
|
|
// Look forward first — a doc comment precedes what it documents.
|
|
for line in lines.iter().skip(from + 1).take(6) {
|
|
if MARKERS.iter().any(|m| line.contains(m)) {
|
|
return trim_body(line);
|
|
}
|
|
}
|
|
// Then backward, for tags placed inside a body.
|
|
for i in (from.saturating_sub(6)..from).rev() {
|
|
if MARKERS.iter().any(|m| lines[i].contains(m)) {
|
|
return lines[i].trim().trim_end_matches('{').trim().to_string();
|
|
}
|
|
}
|
|
"—".to_string()
|
|
}
|
|
|
|
/// Strip a trailing body opener so the context reads as a signature.
|
|
///
|
|
/// Handles both `fn f() {` and `fn f() {}` — the latter is why this is a
|
|
/// helper rather than a single `trim_end_matches('{')`.
|
|
fn trim_body(line: &str) -> String {
|
|
line.trim()
|
|
.trim_end_matches("{}")
|
|
.trim_end()
|
|
.trim_end_matches('{')
|
|
.trim_end()
|
|
.to_string()
|
|
}
|
|
|
|
/// Compute coverage as the intersection of traced and defined IDs.
|
|
///
|
|
/// This signature is the fix for the 158% bug: `defined` is required, so there
|
|
/// is nowhere for a frozen denominator to hide.
|
|
pub fn compute_coverage(traced: &BTreeSet<String>, defined: &DefinedRequirements) -> Coverage {
|
|
let traced_reqs: BTreeSet<&String> = traced.iter().filter(|id| is_requirement(id)).collect();
|
|
|
|
let covered: Vec<&String> = traced_reqs
|
|
.iter()
|
|
.filter(|id| defined.ids.contains(**id))
|
|
.copied()
|
|
.collect();
|
|
|
|
let orphaned: Vec<String> = traced_reqs
|
|
.iter()
|
|
.filter(|id| !defined.ids.contains(**id))
|
|
.map(|s| s.to_string())
|
|
.collect();
|
|
|
|
let untraced: Vec<String> = defined
|
|
.ids
|
|
.iter()
|
|
.filter(|id| !traced.contains(*id))
|
|
.cloned()
|
|
.collect();
|
|
|
|
let total = defined.total();
|
|
Coverage {
|
|
covered: covered.len(),
|
|
total,
|
|
percent: if total == 0 {
|
|
0.0
|
|
} else {
|
|
(covered.len() as f64 / total as f64) * 100.0
|
|
},
|
|
orphaned,
|
|
untraced,
|
|
}
|
|
}
|
|
|
|
/// Source file extensions scanned for tags.
|
|
///
|
|
/// `.yaml` is here because a develop operation is now declared rather than
|
|
/// written: `core/dr-pipeline/ops/<id>.yaml` is the whole node, and the Rust
|
|
/// implementing it is generated into `OUT_DIR`, which is not scanned and could
|
|
/// not be linked to from the report if it were. Without this a node would have
|
|
/// nowhere to record the requirement it satisfies.
|
|
///
|
|
/// # What is deliberately absent, and why widening this is the wrong fix
|
|
///
|
|
/// `AndroidManifest.xml`, the Flatpak manifest, the Dockerfile and the CI
|
|
/// workflows all carry requirements — SAF grants, sandbox permissions, the API
|
|
/// levels NFR-COMPAT-1 names — and none of them can hold a tag. That reads like
|
|
/// a gap in this list. It is not one.
|
|
///
|
|
/// A tag proves that a tag exists, not that the file under it does the thing,
|
|
/// and a declarative manifest is the case where the difference bites hardest:
|
|
/// an intent filter can be deleted and the tag above it still says the
|
|
/// requirement is met. The convention already in the tree answers it better —
|
|
/// a Rust test `include_str!`s the file and asserts what must be in it, and
|
|
/// the tag goes on the test. That satisfies what CONTRIBUTING.md asks of any
|
|
/// tag, that it name something a test would fail without, which a comment in a
|
|
/// manifest never can.
|
|
///
|
|
/// So the list stays as it is, and a config file is tagged through the test
|
|
/// that reads it.
|
|
pub const SOURCE_SUFFIXES: &[&str] = &[".rs", ".slint", ".wgsl", ".yaml"];
|
|
|
|
/// Directories never scanned.
|
|
const EXCLUDED: &[&str] = &["target", "target-android", ".git", "node_modules", "temp"];
|
|
|
|
/// Walk `roots` under `base`, returning every source file.
|
|
pub fn collect_sources(base: &Path, roots: &[&str]) -> Vec<PathBuf> {
|
|
let mut out = Vec::new();
|
|
for root in roots {
|
|
let dir = base.join(root);
|
|
if dir.exists() {
|
|
walk(&dir, &mut out);
|
|
}
|
|
}
|
|
out.sort();
|
|
out
|
|
}
|
|
|
|
fn walk(dir: &Path, out: &mut Vec<PathBuf>) {
|
|
let Ok(entries) = std::fs::read_dir(dir) else {
|
|
return;
|
|
};
|
|
for entry in entries.flatten() {
|
|
let path = entry.path();
|
|
let name = entry.file_name();
|
|
let name = name.to_string_lossy();
|
|
|
|
if EXCLUDED.iter().any(|e| *e == name) {
|
|
continue;
|
|
}
|
|
if path.is_dir() {
|
|
walk(&path, out);
|
|
} else if SOURCE_SUFFIXES.iter().any(|s| name.ends_with(s)) {
|
|
out.push(path);
|
|
}
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
|
|
// ---- the 158% regression ------------------------------------------
|
|
|
|
#[test]
|
|
fn coverage_never_exceeds_one_hundred_percent() {
|
|
// The JellyTau failure, reproduced: more tags than the register
|
|
// defines. Every extra tag must land in `orphaned`, never inflate
|
|
// the numerator.
|
|
let defined = parse_defined_requirements("**FR-CAT-1 — Scan.**\n");
|
|
let traced: BTreeSet<String> = ["FR-CAT-1", "FR-CAT-2", "FR-CAT-3", "FR-CAT-4"]
|
|
.iter()
|
|
.map(|s| s.to_string())
|
|
.collect();
|
|
|
|
let cov = compute_coverage(&traced, &defined);
|
|
assert_eq!(cov.covered, 1);
|
|
assert_eq!(cov.total, 1);
|
|
assert_eq!(cov.percent, 100.0);
|
|
assert!(cov.percent <= 100.0, "coverage must never exceed 100%");
|
|
assert_eq!(cov.orphaned, vec!["FR-CAT-2", "FR-CAT-3", "FR-CAT-4"]);
|
|
}
|
|
|
|
#[test]
|
|
fn orphan_tags_are_reported_not_counted() {
|
|
let defined = parse_defined_requirements("**FR-CAT-1 — Scan.**\n");
|
|
let traced: BTreeSet<String> = ["FR-CAT-1", "FR-TYPO-9"]
|
|
.iter()
|
|
.map(|s| s.to_string())
|
|
.collect();
|
|
|
|
let cov = compute_coverage(&traced, &defined);
|
|
assert_eq!(cov.covered, 1);
|
|
assert_eq!(cov.orphaned, vec!["FR-TYPO-9"]);
|
|
}
|
|
|
|
#[test]
|
|
fn empty_register_is_zero_not_a_division_by_zero() {
|
|
let defined = parse_defined_requirements("");
|
|
let traced = BTreeSet::new();
|
|
let cov = compute_coverage(&traced, &defined);
|
|
assert_eq!(cov.percent, 0.0);
|
|
assert_eq!(cov.total, 0);
|
|
}
|
|
|
|
// ---- denominator parsing ------------------------------------------
|
|
|
|
#[test]
|
|
fn definitions_come_from_declarations_not_cross_references() {
|
|
// Only the first line defines FR-CAT-1. The prose reference and the
|
|
// "relates to" cell must not each count as another definition.
|
|
let md = "\
|
|
**FR-CAT-1 — Scan.** The app shall scan roots.
|
|
|
|
This is discussed in FR-CAT-1 and also FR-CAT-1 again.
|
|
|
|
| Spike | Answers | Relates to |
|
|
|---|---|---|
|
|
| S1 | whether it works | FR-CAT-1 |
|
|
";
|
|
let defined = parse_defined_requirements(md);
|
|
// FR-CAT-1 once, despite three mentions. S1 is a spike, not a
|
|
// requirement, so it does not enter the register at all.
|
|
assert_eq!(defined.total(), 1);
|
|
assert!(defined.ids.contains("FR-CAT-1"));
|
|
}
|
|
|
|
#[test]
|
|
fn decisions_and_spikes_are_not_requirements() {
|
|
// D and S are taggable but are not requirements; counting them would
|
|
// inflate the denominator and understate real coverage.
|
|
let md = "\
|
|
**FR-CAT-1 — Scan.**
|
|
| D1 | Language | Rust |
|
|
| S1 | Zero-copy spike | proves ARCH 6.1 |
|
|
";
|
|
let defined = parse_defined_requirements(md);
|
|
assert_eq!(defined.total(), 1, "only FR-CAT-1 is a requirement");
|
|
assert!(defined.ids.contains("FR-CAT-1"));
|
|
assert!(!defined.ids.contains("D1"));
|
|
assert!(!defined.ids.contains("S1"));
|
|
}
|
|
|
|
#[test]
|
|
fn tagging_a_decision_neither_covers_nor_orphans() {
|
|
let defined = parse_defined_requirements("**FR-CAT-1 — Scan.**\n");
|
|
let traced: BTreeSet<String> = ["FR-CAT-1", "D1"].iter().map(|s| s.to_string()).collect();
|
|
let cov = compute_coverage(&traced, &defined);
|
|
assert_eq!(cov.covered, 1);
|
|
assert!(cov.orphaned.is_empty(), "D1 is a valid tag, not an orphan");
|
|
}
|
|
|
|
#[test]
|
|
fn table_row_ids_are_definitions() {
|
|
let md = "| **R1** | Cross-platform | Same core on both |\n\
|
|
| R2 | Efficient display | 60fps |\n";
|
|
let defined = parse_defined_requirements(md);
|
|
assert!(defined.ids.contains("R1"));
|
|
assert!(defined.ids.contains("R2"));
|
|
}
|
|
|
|
#[test]
|
|
fn darkroom_id_shapes_parse() {
|
|
// Not JellyTau's fixed three-digit form.
|
|
assert_eq!(leading_id("FR-CAT-1 — Scan").as_deref(), Some("FR-CAT-1"));
|
|
assert_eq!(
|
|
leading_id("NFR-P13 — Next image").as_deref(),
|
|
Some("NFR-P13")
|
|
);
|
|
assert_eq!(
|
|
leading_id("FR-DEV-3a — Descriptors").as_deref(),
|
|
Some("FR-DEV-3a")
|
|
);
|
|
assert_eq!(leading_id("R1 | Cross-platform").as_deref(), Some("R1"));
|
|
}
|
|
|
|
#[test]
|
|
fn prose_is_not_an_id() {
|
|
assert_eq!(leading_id("The app shall scan"), None);
|
|
assert_eq!(leading_id("GPU results never"), None);
|
|
// A recognised prefix with no digits is not an ID either.
|
|
assert_eq!(leading_id("FR without a number"), None);
|
|
}
|
|
|
|
// ---- tag extraction -----------------------------------------------
|
|
|
|
#[test]
|
|
fn extracts_tags_with_both_separators() {
|
|
// **The ids here are UT and IT deliberately.** A multi-line literal is
|
|
// the one fixture shape `tag_body` cannot rule out: its lines begin
|
|
// with `///` in the file as well as in the string, so this really is a
|
|
// tag as far as any line-oriented reader can tell. Naming a
|
|
// requirement here would report it implemented by the traceability
|
|
// tool. UT and IT are excluded from coverage by `is_requirement`, so
|
|
// the fixture can be as tag-shaped as it likes and still cost nothing.
|
|
//
|
|
// The requirement id *shapes* are exercised by `darkroom_id_shapes_parse`
|
|
// below, which needs no `TRACES:` at all to do it.
|
|
let src = "\
|
|
/// TRACES: UT-001, UT-002 | IT-003
|
|
pub fn scan() {}
|
|
";
|
|
let traces = extract_from_text(src, "x.rs");
|
|
assert_eq!(traces.len(), 1);
|
|
assert_eq!(traces[0].requirements, vec!["UT-001", "UT-002", "IT-003"]);
|
|
assert_eq!(traces[0].line, 1);
|
|
assert_eq!(traces[0].context, "pub fn scan()");
|
|
}
|
|
|
|
#[test]
|
|
fn context_looks_forward_then_backward() {
|
|
// Doc comments precede their item.
|
|
let fwd = extract_from_text("// TRACES: R1\npub struct Catalog;", "x.rs");
|
|
assert_eq!(fwd[0].context, "pub struct Catalog;");
|
|
|
|
// A tag inside a body refers to the enclosing item.
|
|
let back = extract_from_text("pub fn render() {\n // TRACES: R1\n}", "x.rs");
|
|
assert_eq!(back[0].context, "pub fn render()");
|
|
}
|
|
|
|
#[test]
|
|
fn a_quoted_tag_is_not_a_tag() {
|
|
// What made the tool report `R1` as implemented: a fixture in this very
|
|
// module, scanned along with everything else, because a line mentioning
|
|
// `TRACES:` was taken for a line carrying it.
|
|
let quoted = extract_from_text(
|
|
r#"let s = "// TRACES: FR-CAT-1"; // and a real one below"#,
|
|
"x.rs",
|
|
);
|
|
assert!(quoted.is_empty(), "a tag inside an expression is not a tag");
|
|
|
|
// Emitted into generated code, which is the `build.rs` case.
|
|
let emitted = extract_from_text(r#" "/// TRACES: FR-DEV-3a\n","#, "x.rs");
|
|
assert!(emitted.is_empty(), "a tag being written out is not a tag");
|
|
|
|
// Prose about the mechanism, which is what this crate's own doc
|
|
// comments are full of.
|
|
let prose = extract_from_text("/// Extract every `TRACES:` tag. FR-CAT-1", "x.rs");
|
|
assert!(prose.is_empty(), "a tag named in prose is not a tag");
|
|
|
|
// And the forms that must keep working: SQL inside a Rust literal,
|
|
// which is how `schema.rs` tags its migrations, and YAML.
|
|
let sql = extract_from_text(" -- TRACES: FR-CULL-8\n", "x.rs");
|
|
assert_eq!(sql[0].requirements, vec!["FR-CULL-8"]);
|
|
let yaml = extract_from_text("# TRACES: FR-DEV-3a\nid: exposure\n", "x.yaml");
|
|
assert_eq!(yaml[0].requirements, vec!["FR-DEV-3a"]);
|
|
}
|
|
|
|
#[test]
|
|
fn this_crates_own_fixtures_cannot_reach_the_register() {
|
|
// `SOURCE_ROOTS` includes `tools`, so this crate is scanned by the tool
|
|
// it implements and a fixture below is indistinguishable from a tag on
|
|
// the code above. `tag_body` closes every shape but one — a multi-line
|
|
// literal whose lines begin with a comment opener — and this closes
|
|
// that one, by asking where the tag is rather than what it looks like.
|
|
//
|
|
// Tagging the tool's real code is still allowed; two such tags were
|
|
// wrong on other grounds and were removed, but the rule here is only
|
|
// that a fixture may not name a requirement. Use a `UT-` or `IT-` id.
|
|
for (name, src) in [
|
|
("lib.rs", include_str!("lib.rs")),
|
|
("gestures.rs", include_str!("gestures.rs")),
|
|
("main.rs", include_str!("main.rs")),
|
|
] {
|
|
let fixtures_begin = src
|
|
.lines()
|
|
.position(|l| l.trim_start().starts_with("mod tests"))
|
|
.map_or(usize::MAX, |i| i + 1);
|
|
|
|
for entry in extract_from_text(src, name) {
|
|
let reqs: Vec<&String> = entry
|
|
.requirements
|
|
.iter()
|
|
.filter(|id| is_requirement(id))
|
|
.collect();
|
|
assert!(
|
|
entry.line < fixtures_begin || reqs.is_empty(),
|
|
"{name}:{} is a test fixture naming {reqs:?}, which the \
|
|
register would read as implemented. Use a UT- or IT- id.",
|
|
entry.line,
|
|
);
|
|
}
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn a_tag_with_no_ids_is_ignored() {
|
|
let traces = extract_from_text("// TRACES: see the design doc\n", "x.rs");
|
|
assert!(traces.is_empty());
|
|
}
|
|
|
|
#[test]
|
|
fn test_ids_are_extracted_but_not_counted_as_requirements() {
|
|
let traces = extract_from_text("// TRACES: FR-CAT-1 | UT-001\nfn f(){}", "x.rs");
|
|
assert_eq!(traces[0].requirements, vec!["FR-CAT-1", "UT-001"]);
|
|
|
|
// UT is a separate taxonomy: evidence, not a requirement.
|
|
assert!(is_requirement("FR-CAT-1"));
|
|
assert!(!is_requirement("UT-001"));
|
|
|
|
// So it neither covers nor orphans.
|
|
let defined = parse_defined_requirements("**FR-CAT-1 — Scan.**\n");
|
|
let traced: BTreeSet<String> = ["FR-CAT-1", "UT-001"]
|
|
.iter()
|
|
.map(|s| s.to_string())
|
|
.collect();
|
|
let cov = compute_coverage(&traced, &defined);
|
|
assert_eq!(cov.covered, 1);
|
|
assert!(
|
|
cov.orphaned.is_empty(),
|
|
"UT must not be reported as orphaned"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn type_prefixes_split_correctly() {
|
|
assert_eq!(type_of("FR-CAT-1"), "FR");
|
|
assert_eq!(type_of("NFR-P13"), "NFR");
|
|
assert_eq!(type_of("R1"), "R");
|
|
assert_eq!(type_of("UT-001"), "UT");
|
|
}
|
|
|
|
#[test]
|
|
fn untraced_requirements_are_listed() {
|
|
let defined = parse_defined_requirements("**FR-A-1 — One.**\n**FR-B-2 — Two.**\n");
|
|
let traced: BTreeSet<String> = ["FR-A-1"].iter().map(|s| s.to_string()).collect();
|
|
let cov = compute_coverage(&traced, &defined);
|
|
assert_eq!(cov.untraced, vec!["FR-B-2"]);
|
|
}
|
|
}
|