Evidence Sources

<TrackedFiles paths="crates/supersigil-verify/src/explicit_evidence.rs, crates/supersigil-rust/src/**/*.rs, crates/supersigil-js/src/**/*.rs" />

Coverage in Supersigil is not a vague statement about “having tests.” A criterion is covered only when the graph can point to specific evidence for it.

The Evidence Model

Every criterion starts as an uncovered verification target. It becomes covered when Supersigil can resolve at least one evidence source for that criterion.

The built-in evidence paths are:

Source	Best for	Strength
Ecosystem plugins	Rust and JavaScript/TypeScript projects	Structured discovery from the code itself
<VerifiedBy strategy="tag">	Existing test suites in any language	Explicit mapping with very low setup cost
<VerifiedBy strategy="file-glob">	Broad file-level coverage	Fastest way to connect criteria to known test locations

Ecosystem Plugins

Plugins let Supersigil discover evidence directly from the code itself. Each plugin parses test source files and emits evidence records automatically — no <VerifiedBy> component is needed in the spec.

Rust Plugin

The Rust plugin is enabled by default and discovers #[verifies] annotations:

use supersigil_rust::verifies;

#[verifies("auth/req#valid-creds")]
#[test]
fn login_with_valid_credentials_returns_token() {
    // ...
}

JavaScript/TypeScript Plugin

The JS plugin discovers verifies() calls in Vitest test files. Enable it in your config and install the helper package:

supersigil.toml

paths = ["specs/**/*.md"]
tests = ["tests/**/*.test.ts"]

[ecosystem]
plugins = ["rust", "js"]

pnpm add -D @supersigil/vitest

Then annotate tests with verifies():

import { verifies } from '@supersigil/vitest'
import { test } from 'vitest'

test('login with valid credentials', verifies('auth/req#valid-creds'), () => {
  // ...
})

The plugin uses oxc to parse test files statically — no Node.js runtime is needed during supersigil verify. It recognizes both the verifies() helper and the raw { meta: { verifies: [...] } } form, and tracks describe nesting for full test names.

Tip

Install @supersigil/eslint-plugin for editor-time validation of criterion refs. It checks ref strings against your specs via supersigil refs and reports unknown documents or criteria as lint errors.

Tag-Based Evidence

For projects without an ecosystem plugin, tags are a portable bridge from criteria to tests:

<Criterion id="valid-creds">
  WHEN a user submits valid credentials
  THE SYSTEM SHALL issue a session token.
  <VerifiedBy strategy="tag" tag="auth:valid-creds" />
</Criterion>

Then in a test file:

// supersigil: auth:valid-creds

#[test]
fn login_with_valid_credentials_returns_token() {
    // ...
}

Tag comments are recognized with //, #, ///, --, and /* */ comment styles, so they work across languages.

File-Glob Evidence

File globs trade precision for speed:

<VerifiedBy strategy="file-glob" paths="tests/auth/login_*.rs" />

This is useful when a criterion is verified by a small, stable set of files and you do not need per-test granularity.

Caution

File globs show that matching files exist; they do not tell you which specific test case inside those files satisfies the criterion.

Choosing the Right Source

• Use the Rust plugin for Rust projects — #[verifies] annotations with compile-time validation.
• Use the JS plugin for JavaScript/TypeScript projects — verifies() calls in Vitest tests.
• Use tags for other languages that want explicit criterion-to-test mapping.
• Use file globs when you only need coarse evidence and the test location is stable.

Related Reading

• Verification — Rule severities, draft gating, and exit codes.
• CLI Commands — context, status, refs, and verify.