feat(bookspec): the specification text and an example for the ledger's own laws (P13 step 4)

bookspec/spec holds the first edition: the model and the five laws
(00-model.md) and one file per area, each B-rule a section with its
status, a MUST/MAY statement, sources pinned either to a vendored source
with a verbatim quotation or to an exact external paragraph, its symbolic
form, its examples and its applicability. B-39, B-40, B-43 and B-45 are
reserved sections (allocated, not yet stated in rules.md); B-44 is stated
in rules.md and now carries its bookspec id and CONVENTION status.

Eight new examples show the laws that had none, each figure worked by
hand: an unbalanced entry is refused (Pacioli ch. 36, Pub. 583), a
negative or zero line is refused, a fraction of a cent is refused (ISO
4217), a child account takes its parent's type, the trial balance and the
accounting equation on one small book (cash 6550.25 = loan 2000 + capital
5000 + (sales 750.50 - rent 1200.25)), a reversal leaves the original
standing and a second reversal is refused, a close sweeps revenue and
expenses into Retained Earnings (3999) and the closed quarter takes no
late entry, and cents add exactly. The refusal vocabulary gains
unbalanced, negative_amount, zero_amount, too_few_lines,
finer_than_minor_unit, parent_type_mismatch, already_reversed and
period_closed; a refused entry may carry a non-positive amount.

The checker's spec.rs fails the build on a rule without its section, a
statement without MUST/SHOULD/MAY, a pin that is not verbatim in its
vendored source, examples that differ from the catalogue, or more than 60
pages.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HS8WZziDnyxunC23MUxrLp

bookspec/checker/tests/spec.rs

@@ -0,0 +1,261 @@
+//! The specification text (`bookspec/spec/*.md`, P13 step 4): every rule
+//! has its section, its statement, its pinned sources, its symbolic form
+//! and its examples, and every citation resolves.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::path::{Path, PathBuf};
+
+use bookspec_checker::{Rule, rules};
+
+fn spec_dir() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("../spec")
+}
+
+fn sources_dir() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("../../docs/spec/sources")
+}
+
+/// A rule's section as the text gives it.
+#[derive(Default, Debug)]
+struct Section {
+    file: String,
+    heading: String,
+    fields: BTreeMap<String, Vec<String>>,
+}
+
+/// Every `### BS-...` section of the area files, by its identifier.
+fn sections() -> BTreeMap<String, Section> {
+    let mut out = BTreeMap::new();
+    let mut files: Vec<PathBuf> = std::fs::read_dir(spec_dir())
+        .unwrap()
+        .map(|e| e.unwrap().path())
+        .filter(|p| p.extension().is_some_and(|x| x == "md"))
+        .collect();
+    files.sort();
+    for f in files {
+        let name = f.file_name().unwrap().to_string_lossy().into_owned();
+        let text = std::fs::read_to_string(&f).unwrap();
+        let mut current: Option<(String, Section)> = None;
+        let mut field = String::new();
+        for line in text.lines() {
+            if let Some(h) = line.strip_prefix("### BS-") {
+                if let Some((id, s)) = current.take() {
+                    assert!(out.insert(id.clone(), s).is_none(), "{id} twice");
+                }
+                let id = format!("BS-{}", h.split(':').next().unwrap());
+                current = Some((
+                    id,
+                    Section {
+                        file: name.clone(),
+                        heading: h.to_string(),
+                        ..Section::default()
+                    },
+                ));
+                continue;
+            }
+            let Some((_, s)) = current.as_mut() else {
+                continue;
+            };
+            if let Some(rest) = line.strip_prefix("- **") {
+                let (key, value) = rest.split_once(":**").expect("a field: - **Name:** ...");
+                field = key.to_string();
+                let e = s.fields.entry(field.clone()).or_default();
+                if !value.trim().is_empty() {
+                    e.push(value.trim().to_string());
+                }
+            } else if let Some(item) = line.strip_prefix("  - ") {
+                s.fields
+                    .entry(field.clone())
+                    .or_default()
+                    .push(item.to_string());
+            }
+        }
+        if let Some((id, s)) = current.take() {
+            assert!(out.insert(id.clone(), s).is_none(), "{id} twice");
+        }
+    }
+    out
+}
+
+fn one<'a>(s: &'a Section, id: &str, field: &str) -> &'a str {
+    let v = s
+        .fields
+        .get(field)
+        .unwrap_or_else(|| panic!("{id}: no {field}"));
+    assert_eq!(v.len(), 1, "{id}: {field} is one line");
+    &v[0]
+}
+
+/// Whitespace and typographic quotes made plain, so a pin copied from a
+/// wrapped or curly-quoted source still matches.
+fn squash(s: &str) -> String {
+    let plain = s
+        .replace(['\u{2019}', '\u{2018}'], "'")
+        .replace(['\u{201c}', '\u{201d}'], "\"");
+    plain.split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+fn backticked(s: &str) -> Vec<&str> {
+    s.split('`').skip(1).step_by(2).collect()
+}
+
+/// Every one of the 45 rules has one section, in the file of its area,
+/// headed with its identifier and B-number.
+#[test]
+fn every_rule_has_its_section() {
+    let sections = sections();
+    assert_eq!(sections.len(), 45, "one section per rule");
+    for rule in rules() {
+        let s = sections
+            .get(rule.id.as_str())
+            .unwrap_or_else(|| panic!("{}: no section", rule.id));
+        assert_eq!(s.file, format!("{}.md", rule.area.key()), "{}", rule.id);
+        assert!(
+            s.heading.ends_with(&format!("(B-{})", rule.b)),
+            "{}: heading {:?} names B-{}",
+            rule.id,
+            s.heading,
+            rule.b
+        );
+    }
+}
+
+/// A stated rule has a status the catalogue agrees with, a normative
+/// statement, a symbolic form and applicability; a reserved one says so.
+#[test]
+fn every_stated_rule_is_complete() {
+    let sections = sections();
+    for rule in rules() {
+        let s = &sections[rule.id.as_str()];
+        let id = rule.id.as_str();
+        let status = one(s, id, "Status");
+        match rule.status {
+            Some(st) => {
+                assert!(status.starts_with(st.key()), "{id}: status {status:?}");
+                let statement = one(s, id, "Statement");
+                assert!(
+                    ["MUST", "SHOULD", "MAY"]
+                        .iter()
+                        .any(|w| statement.contains(w)),
+                    "{id}: a statement says MUST, SHOULD or MAY"
+                );
+                for field in ["Symbolic form", "Applicability"] {
+                    assert!(
+                        one(s, id, field).len() > 10 && !one(s, id, field).starts_with("none"),
+                        "{id}: {field}"
+                    );
+                }
+            }
+            None => assert!(status.starts_with("reserved"), "{id}: reserved"),
+        }
+    }
+}
+
+/// A section's examples are the catalogue's, exactly; "none yet" says why.
+#[test]
+fn the_examples_are_the_catalogues() {
+    let sections = sections();
+    for rule in rules() {
+        let s = &sections[rule.id.as_str()];
+        let id = rule.id.as_str();
+        let line = one(s, id, "Examples");
+        let listed: BTreeSet<&str> = backticked(line)
+            .into_iter()
+            .filter(|b| *b != "none yet")
+            .collect();
+        let want: BTreeSet<&str> = rule.examples.iter().copied().collect();
+        if rule.examples.is_empty() {
+            assert!(line.starts_with("none yet"), "{id}: {line}");
+            if rule.status.is_some() {
+                assert!(
+                    line.len() > "none yet. ".len() + 20,
+                    "{id}: a stated rule with no example says why"
+                );
+            }
+        } else {
+            assert_eq!(listed, want, "{id}: examples");
+        }
+    }
+}
+
+/// Every citation resolves: a vendored source exists, and a verbatim
+/// pin appears in it; an external reference names its paragraph.
+#[test]
+fn every_citation_resolves() {
+    let sections = sections();
+    let mut vendored = 0;
+    let mut external = 0;
+    let mut bad: Vec<String> = Vec::new();
+    for rule in rules() {
+        let s = &sections[rule.id.as_str()];
+        let id = rule.id.as_str();
+        let sources = s
+            .fields
+            .get("Sources")
+            .unwrap_or_else(|| panic!("{id}: no Sources"));
+        if rule.status.is_none() {
+            assert_eq!(sources, &vec!["none yet".to_string()], "{id}");
+            continue;
+        }
+        assert!(!sources.is_empty(), "{id}: sourced");
+        for item in sources {
+            if let Some(rest) = item.strip_prefix("vendored `") {
+                let (file, rest) = rest
+                    .split_once("`:")
+                    .unwrap_or_else(|| panic!("{id}: {item}"));
+                let path = sources_dir().join(file.strip_prefix("sources/").unwrap_or(file));
+                let text = std::fs::read_to_string(&path)
+                    .unwrap_or_else(|_| panic!("{id}: {file} is not vendored"));
+                let hay = squash(&text);
+                // Every quoted pin is verbatim in the file.
+                let quoted: Vec<&str> = rest.split('"').skip(1).step_by(2).collect();
+                for q in &quoted {
+                    if !hay.contains(&squash(q)) {
+                        bad.push(format!("{id}: {q:?} is not in {file}"));
+                    }
+                }
+                if quoted.is_empty() {
+                    bad.push(format!("{id}: {item} has no verbatim pin"));
+                }
+                vendored += 1;
+            } else if let Some(rest) = item.strip_prefix("external:") {
+                assert!(
+                    rest.trim().len() > 20,
+                    "{id}: an external reference is exact: {item}"
+                );
+                external += 1;
+            } else {
+                panic!("{id}: a source is `vendored` or `external`: {item}");
+            }
+        }
+    }
+    assert!(bad.is_empty(), "pins not found:\n{}", bad.join("\n"));
+    assert!(vendored >= 30, "vendored citations: {vendored}");
+    assert!(external >= 15, "external citations: {external}");
+}
+
+/// The first edition's page budget: 60 pages of 55 lines.
+#[test]
+fn the_edition_fits_its_page_budget() {
+    let mut lines = 0;
+    for e in std::fs::read_dir(spec_dir()).unwrap() {
+        let p = e.unwrap().path();
+        if p.extension().is_some_and(|x| x == "md") {
+            lines += std::fs::read_to_string(p).unwrap().lines().count();
+        }
+    }
+    assert!(lines <= 60 * 55, "{lines} lines is over 60 pages");
+}
+
+/// A stated rule with no example is exactly one an engine cannot claim.
+#[test]
+fn rules_without_examples_are_not_claimable() {
+    let uncovered: Vec<&Rule> = rules().iter().filter(|r| !r.has_examples()).collect();
+    let claimable: BTreeSet<_> = bookspec_checker::covered_rules()
+        .into_iter()
+        .map(|r| r.b)
+        .collect();
+    for r in uncovered {
+        assert!(!claimable.contains(&r.b), "B-{}", r.b);
+    }
+}