Auditing a corpus

Construct frequencies, unknown-name census, and no document text in the output.

orgo audit ~/notes

The audit answers two questions about a body of org files:

Coverage. Of the constructs this corpus uses, which are supported? A construct that is common here and unsupported is a problem with the tool's scope, not with your writing.
Blind spots. Which names appear that orgo has no opinion about at all? These are the dangerous ones — not "known unsupported" but unknown.

Reading the output

corpus: 180 file(s), 29742 line(s)

CONSTRUCTS (by frequency)
     construct                            uses   files  first seen
IN   list item                            1309     111  blog/2018-11-28-aes-encryption.org:53
IN   heading                              1148     176  blog/2018-11-28-aes-encryption.org:7
IN   verbatim                             1048     130  blog/2018-11-28-aes-encryption.org:79
...
IN   table formula (#+TBLFM:)                4       1  blog/2024-08-11-org-mode-features.org:191
IN   special block                           1       1  blog/2026-03-03-auditing-aws-s3.org:50

coverage: 9002 in-scope use(s) (100.0%), 0 out-of-scope (0.0%)

KEYWORDS
   SLUG                                  180     180  blog/2018-11-28-aes-encryption.org:4
   TITLE                                 180     180  blog/2018-11-28-aes-encryption.org:2
...

IN is supported; OUT is excluded by design and degrades as described in Org support.
The coverage line is the number to look at first.
??? marks a name orgo does not recognise at all. That is the blind-spot signal — not "known unsupported", but unknown — and this corpus has none. Block names never carry it: an unrecognised one is still a special block, and still renders.

Four censuses follow the construct table: every distinct #+KEYWORD:, block type, drawer name and link scheme in the corpus. A ??? in any of them is worth a look.

It never prints your writing

Names, counts and file:line locations only. That is a deliberate constraint so that an audit of private notes — work notes, a journal — is safe to paste into an issue or share with someone helping you.

Why it is a separate scanner

The audit deliberately does not reuse the parser. Auditing with the parser could only ever find constructs the parser already knows about, which is exactly the wrong instrument for the second question: it would report a blind spot as clean.

Comparing against Emacs

The second half of the same idea is a differential test suite. cargo test --test oracle exports each fixture with org's own HTML exporter through emacs --batch, reduces both outputs to a semantic skeleton, and snapshots the disagreement.

cargo test --test oracle

Snapshotting rather than asserting agreement is deliberate: a checked-in divergence report gets reviewed and shows up in code review, where a permanently red test gets ignored. Three invariants are asserted outright — heading structure, list nesting and source-block text — and all three hold.

The suite skips cleanly with no Emacs installed, so a machine without it still gets a green run; it simply measures one thing less.

Using the audit before a migration

# What is in there?
orgo audit ~/notes

# Build it and see what the builder itself complains about.
orgo build ~/notes -o /tmp/preview --strict

# Look at the result.
orgo serve ~/notes -o /tmp/preview

--strict surfaces broken internal links and malformed constructs as failures rather than warnings, which is the fastest way to find the handful of files that need attention before you commit to anything.