Skip to content
kindspecPublic

About

A specification and conformance suite for prose documents that must survive version control — the block kind

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

blockspec

A file format and test suite for prose documents that must survive version control.

A blockspec document is a markdown file that renders and edits correctly in today's markdown tools. It adds one convention, a marker that lets an author name a part of the document. It refuses the markdown constructs that mature parsers read differently, or that hide what a merge did.

# Runbook

<!-- #restart -->
## Restart the service

Run `systemctl restart app`, then check the logs.

The marker names the heading after it, and renders as nothing. A comment or a transclusion can point at restart and keep working when the text around it moves.

Unlike a rowspec row, a block gets no minted id, so nothing has to be written into the prose. Identity is computed from content where it can be, and named by an author where it must be. DESIGN-BRIEF.md has the measurement behind that.

Status

Draft 0. SPEC.md is the format, conformance/cases/ encodes it, and reference/blockspec/ is the reference. reference/blockspec_alt/, written from the spec by an author who never read it, passes the same cases. Released on PyPI.

The experiment behind the format found that prose does have a silent wrong merge worth a format. That verdict came from a second run under an owner ruling made after the first run's result was public, so read the status page before relying on it.

Try it

From a clone, with Python 3.11 or newer and no dependencies:

git clone https://github.com/kindspec/blockspec
cd blockspec
PYTHONPATH=reference python3 -c '
import blockspec
doc = blockspec.parse("<!-- #intro -->\nHello.\n")
print(doc.names)
'

parse raises Refusal, with a SPEC.md §9 code, on a document it won't accept.

Check documents

pip install blockspec
blockspec check docs/    # refuses a document the profile cannot read safely

A document is refused for what would quietly break under a merge, including a link to a section that no longer exists and a marker that takes a name from a heading. It exits 0 when every document reads, 1 when one is refused, and 2 when nothing was checked or a file could not be read. --format github writes annotations. In CI:

- uses: actions/checkout@v7
- uses: kindspec/blockspec@v0.1.0
  with:
    paths: docs

The reference's API

reference/blockspec/ is standard library only, and run from its source tree (pythonpath = ["reference"]).

function what it does
parse(text) reads a document, or raises Refusal with a SPEC.md §9 code; the Document has frontmatter, blocks, leaves, names and resolve(name)
conform(text, queries) parse as the conformance runner calls it
resolve(repo, queries) §11's anchors and transclusions, as the runner calls it (anchor.py)
edit.replace_block(text, node, source) the text with block node's lines replaced by source
edit.insert_block(text, source, before=, after=) the text with source inserted as a block before or after a block, or after the last
edit.delete_block(text, node) the text without block node

A block is named by its node path, [i]. Each edit function reads its result back and raises Refusal, or its subclass edit.EditRefused for the API's own reasons, rather than return a document whose other blocks or names read differently. It never touches a <doc>.notes/ record. docs/editing-api.md gives the rules, and tests/edit-cases/ pins them.

Develop

just setup      # install dependencies
just check      # format and lint
just test       # the tests
just conform    # the conformance tree against the reference
just mutants    # break the reference; the suite must notice

More

About

A specification and conformance suite for prose documents that must survive version control — the block kind

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages