Source: Generated from
openspec/project.mdduring the documentation build.
Project Context
Purpose
Livin is a cross-language CLI that checks whether a test suite actually exercises the boundary values a piece of code’s own shape implies exist — zero, empty, singleton, duplicate, overflow, every arm of a sum type — rather than only the values a property-based generator happens to sample.
The normative product requirements are in livin-ears-spec.md; OpenSpec
changes select reviewed implementation slices and do not override it. Preserve
its requirement IDs (REQ-*) in proposals, tests, findings, and traceability
notes.
Tech Stack
- Implementation language: Rust, organized as a Cargo workspace and exposed
as the
livinCLI binary. - Rust baseline: stable toolchain, rustfmt formatting, Clippy linting, and Cargo-native unit, integration, and documentation tests.
- Language analysis: tree-sitter or a language-native parser behind front-end plugins.
- Core model: a language-agnostic representation of shapes, shape kinds, boundary values, and reachability classes.
- CLI output: human-readable, JSON, and SARIF.
Project Conventions
Code Style
- Format with rustfmt and keep Clippy clean.
- Use domain terms from the EARS specification consistently: shape, shape kind, boundary value, boundary catalogue, coverage gap, reachability class, shape source, exercised.
- Keep built-in vocabularies closed and project extensions explicitly
declared and validated. Unknown shapes remain
opaque/unclassified; never silently coerce them to a successful/default case. - Use stable requirement and rule IDs. A finding always has a rule ID, file, line, boundary value, reachability class, and shape source.
Architecture Patterns
- Keep language-specific shape extraction and literal/constant-expression matching in versioned, conformance-tested front-end plugins.
- Maintain a versioned boundary catalogue mapping each shape kind to a finite set of named boundary values, validated by conformance fixtures.
- Prefer consuming shape data from an installed composability checker (Vampiro) when available; fall back to standalone extraction at reduced precision otherwise.
- Support diff-scoped analysis as the interactive/agent default and full repository analysis as an incremental mode.
- Never generate or modify test files; only report coverage gaps.
Testing Strategy
- Develop every behavior from an OpenSpec scenario traceable to one or more EARS requirement IDs.
- Maintain a shared, versioned conformance-fixture suite for every front-end plugin and boundary catalogue entry.
- The initial MVP analyzes stable Rust and discovers only built-in
#[test]functions; all other languages, doctests, macro-generated tests, and external test frameworks remain explicitly unsupported. - Test all supported output formats against the same underlying finding data.
- Include negative fixtures for opaque shapes, undefined matchers, unknown reachability, and unconfirmed refinements.
- Benchmark diff-scoped scans with the committed 500-node/100-test fixture and reproducible protocol specified by REQ-22.
Git Workflow
- Use OpenSpec changes for new capabilities, architecture changes, breaking behavior, and performance work. Do not implement a proposal before approval.
- Keep commits focused and preserve requirement IDs in change artifacts and test names where practical.
- Pull-request CI should run diff-scoped check in
gatemode at the configured severity threshold.
Domain Context
Livin asks whether the test suite hits the values most likely to contain a bug. Its core taxonomy of shape kinds:
numeric— zero, min/max, overflow point, NaN/Inf where applicablecollection— empty, singleton, duplicate, maximum declared cardinalitysum/union— each arm treated as a separate obligationrecursive/self-referential— self-reference or cycle instancestring/text— empty string, encoding boundaryrecord/product— field-level boundary compositionopaque— could not be classified
Every boundary obligation has state covered, uncovered, or
indeterminate. Only uncovered obligations are coverage gaps. Coverage gaps
also carry a reachability class (reachable, unreachable, or unknown)
derived from upstream constraints.
Important Constraints
- Static analysis must never execute analyzed source code.
- Unknown or unsupported shapes must be visible in output, never silently omitted.
- The tool must never generate or modify test files.
guidancemode never fails solely because of findings;gatemode fails only when coverage gaps on diff-touched nodes meet the configured threshold.- The repository is greenfield.
openspec/specs/describes built truth, so do not copy aspirational EARS requirements there before implementation; add them through reviewed changes and archive them as capabilities ship.
External Dependencies
- Git diff/repository metadata for diff-scoped analysis and reachability estimation.
- Per-language tree-sitter grammars or native parser APIs.
- Optionally: installed Vampiro composability checker for shape data.
- CI platforms capable of consuming generated pipeline configuration and SARIF.