Faithful Spec Compliance
Implementing or developing a spec? You need Great Spectations!
$
pip install greatspectations
$
uv tool install greatspectations
$
greatspectate check --config specquotes.toml src/*.c
§1
Orphans and Convicts
- You quote the spec as you implement. A comment marker names the source and section; the text after it is the quote.
- Great Spectations checks the quote against the spec. Ignoring whitespace differences by default, or byte-exact if you prefer.
- If the spec changes, it notices. And tells you exactly which comment is now quoting text that no longer exists.
- A convenient format.
...wildcards, and a quote can pick up where the previous one left off: split one requirement list across multiple code chunks. - Coverage too. Ask which requirements in the spec no comment has quoted yet.
- Any language, any spec. C, Python, Rust comment syntax all handled. Markdown specs, MediaWiki, old-school RFC-editor plaintext, and more.
§2
The Period, in Two Languages
A real, runnable example: Python and Rust each quote different clauses of the same paragraph; one of them botches a quote, one clause never gets quoted at all. Generated straight from examples/generate.py running the actual tool — see examples/ in the repo.
"""Great Spectations demo: quoting Dickens instead of a protocol spec.
Nothing here is a real "requirement" -- it's just prose from a novel,
used to show that greatspectate checks any text source, not only specs.
"""
# DICKENS #1: it was the age of wisdom, it was the age of foolishness,
WISDOM = "the age of wisdom"
FOOLISHNESS = "the age of foolishness"
# DICKENS #1: it was the spring of hope, it was the winter of despair,
HOPE = "the spring of hope"
DESPAIR = "the winter of despair"
# DICKENS #1: we were all going direct to Heaven, we were all going
# direct the other way
HEAVEN = "direct to Heaven"
THE_OTHER_WAY = "direct the other way"
greatspectate check — all quotes match
$ greatspectate check --config specquotes.toml --coverage .coverage -v -k src/tale.py
src/tale.py:7:Matched 'it was the age of wisdom, it was the age of foolishness,'
src/tale.py:11:Matched 'it was the spring of hope, it was the winter of despair,'
src/tale.py:15:Matched 'we were all going direct to Heaven, we were all going direct the other way'§3
I say, Pip, old chap!
This is particularly useful when writing a specification and its implementation side by side: the spec becomes better because you use it to annotate the code, and can see whether it's sufficiently thorough, or logically laid out for other implementors.
Whoever implements your specification will thank you for it!