Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Source: Generated from openspec/project.md during 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 livin CLI 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 gate mode 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 applicable
  • collection — empty, singleton, duplicate, maximum declared cardinality
  • sum/union — each arm treated as a separate obligation
  • recursive/self-referential — self-reference or cycle instance
  • string/text — empty string, encoding boundary
  • record/product — field-level boundary composition
  • opaque — 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.
  • guidance mode never fails solely because of findings; gate mode 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.