audit: stop reporting gaps orgo's own docs do not have !2

merged merged by cmc on 2026-08-30 06:55 UTC · krz/orgo:audit-overstated-gaps into main

5 files changed, +96 −31

Layout: unified · split

docs/guide/09-auditing.org +9 −3

 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
+    SLUG                                 180     180  blog/2018-11-28-aes-encryption.org:4
-   TITLE                                 180     180  blog/2018-11-28-aes-encryption.org:2
+    TITLE                                180     180  blog/2018-11-28-aes-encryption.org:2
+—   LEDE                                  14      14  blog/2018-11-28-aes-encryption.org:3
 ...
 #+END_EXAMPLE
 - 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.
+  carry it: an unrecognised one is still a special block, and still renders. Keyword
+  names never carry it either — see below.
+- =—= marks a keyword with no dedicated handling. It is not a gap: the keyword reaches
+  your layout as ={{ page.keywords.<name> }}=, which is the designed behaviour, so the
+  marker tells you which of your keywords orgo reads by name and which rely on that
+  pass-through.
 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.

fixtures/audit-keywords.org added +5

@@ -0,0 +1,5 @@
	1	#+TITLE: Keyword census
	2	#+LEDE: A keyword the shipped docs template reads.
	3	#+PROJECT_STATUS: A keyword nothing reads by name.
	4
	5	Body text.

fixtures/audit-verbatim-constructs.org added +4

@@ -0,0 +1,4 @@
	1	#+TITLE: Verbatim mentions
	2
	3	A doc explaining syntax, where every mention is inside verbatim:
	4	=${x^2}$=, ={{{name}}}=, =<<<radio>>>=, =[1/3]=, =CLOCK: [2024-01-01]=.

src/audit.rs +46 −28

     pub link_schemes: BTreeMap<String, Tally>,
 }
-/// Names the implementation understands, so the census can flag everything else. These
+/// Names the implementation reads by name, so the census can mark everything else. These
-/// are the *recognized* sets, not the supported ones: `INCLUDE` is recognized (it is
+/// are the *recognized* sets, not the supported ones: `INCLUDE` is recognized and
-/// deliberately inert) while an unlisted keyword is a genuine blind spot.
+/// deliberately inert.
 const KNOWN_KEYWORDS: &[&str] = &[
     "TITLE", "AUTHOR", "DATE", "EMAIL", "LANGUAGE", "OPTIONS", "FILETAGS", "DESCRIPTION",
     "KEYWORDS", "CAPTION", "NAME", "ATTR_HTML", "RESULTS", "TBLFM", "INCLUDE", "TODO",
     "relative",
 ];
+/// The census markers. A name with dedicated handling carries none; `PASS_THROUGH` says
+/// nothing reads the name but it works anyway; `UNKNOWN` is the blind-spot signal.
+const HANDLED: &str = "";
+const PASS_THROUGH: &str = "\u{2014}";
+const UNKNOWN: &str = "???";
 impl Audit {
-    /// Is this name one the implementation recognizes?
+    /// How the report marks a census name: the recognized set to look the name up in,
-    pub fn is_known(kind: Census, name: &str) -> bool {
+    /// and what an unlisted name means for that census.
-        let known = match kind {
+    pub fn marker(kind: Census, name: &str) -> &'static str {
-            Census::Keyword => KNOWN_KEYWORDS,
+        let (known, unlisted) = match kind {
+            // An unlisted keyword is not a blind spot. Reaching templates as
+            // `page.keywords.<name>` is the designed behaviour, so every keyword name
+            // works; what the census reports is which ones have dedicated handling.
+            // `LEDE`, read by the shipped docs theme's template, was the case that made
+            // this concrete: `???` on it was a claim about orgo's source, not a gap.
+            Census::Keyword => (KNOWN_KEYWORDS, PASS_THROUGH),
             // Every block name renders, and renders as org renders it: the names in
             // `block_construct` through dedicated handling, every other name as a special
             // block — a div carrying the name, holding parsed org, which is exactly what
             // org's exporter emits. No block name is a blind spot.
-            Census::Block => return true,
+            Census::Block => return HANDLED,
-            Census::Drawer => KNOWN_DRAWERS,
+            Census::Drawer => (KNOWN_DRAWERS, UNKNOWN),
-            Census::Scheme => KNOWN_SCHEMES,
+            Census::Scheme => (KNOWN_SCHEMES, UNKNOWN),
         };
-        known.iter().any(|k| k.eq_ignore_ascii_case(name))
+        if known.iter().any(|k| k.eq_ignore_ascii_case(name)) {
+            HANDLED
+        } else {
+            unlisted
+        }
     }
 }
             rest = &after[end..];
         }
-        if has_timestamp(line) {
+        // The rest read a line that has had its `=verbatim=` and `~code~` spans blanked:
+        // a construct shown inside verbatim is displayed rather than rendered, so a page
+        // documenting org syntax is not a use of the syntax it names. Emphasis pairs
+        // below deliberately still see the raw line — `=` is one of the markers scanned.
+        let bare = without_literal_spans(line);
+        if has_timestamp(&bare) {
             self.count(Scope::In, "timestamp", at);
         }
-        if line.contains("{{{") {
+        if bare.contains("{{{") {
             self.count(Scope::Out, "macro call", at);
         }
-        if line.contains("<<<") {
+        if bare.contains("<<<") {
             self.count(Scope::Out, "radio target", at);
-        } else if line.contains("<<") && line.contains(">>") {
+        } else if bare.contains("<<") && bare.contains(">>") {
             self.count(Scope::Out, "internal target", at);
         }
-        if line.contains("\\begin{") || latex_inline(line) {
+        if bare.contains("\\begin{") || latex_inline(&bare) {
             self.count(Scope::Out, "LaTeX fragment", at);
         }
-        if entity_ref(line) {
+        if entity_ref(&bare) {
             // Rendered, and rendered as org renders it: `\alpha` becomes `&alpha;` in
             // both exporters. `fixtures/audit-entities.org` holds the oracle to that.
             self.count(Scope::In, "entity (\\name)", at);
 /// Only names org knows count, matching [`crate::parser`]'s rule for rendering one: a
 /// Windows path (`C:\Users\me`) and a namespaced identifier (`Tumblr\API\Client`) are not
 /// entity references.
-///
-/// Verbatim and code spans are skipped: `=\alpha=` shows the name rather than rendering
-/// the character, so it is not a use of the feature.
 fn entity_ref(line: &str) -> bool {
-    let line = without_literal_spans(line);
     let chars: Vec<char> = line.chars().collect();
     for (i, c) in chars.iter().enumerate() {
         if *c != '\\' {
         names.sort_by(|a, b| b.1.occurrences.cmp(&a.1.occurrences).then(a.0.cmp(b.0)));
         out.push_str(&format!("\n{title}\n"));
         for (name, tally) in names {
-            let flag = if Audit::is_known(kind, name) {
-                "   "
-            } else {
-                "??? "
-            };
             out.push_str(&format!(
-                "{flag}{:<32} {:>8} {:>7}  {}\n",
+                "{:<4}{:<32} {:>8} {:>7}  {}\n",
+                Audit::marker(kind, name),
                 name,
                 tally.occurrences,
                 tally.files,
             ));
         }
     }
-    out.push_str("\n`???` marks a name the implementation does not recognize at all.\n");
+    out.push_str(
+        "\n`???` marks a name the implementation does not recognize at all.\n\
+         `\u{2014}` marks a keyword with no dedicated handling; it reaches templates \
+         as `page.keywords.<name>`.\n",
+    );
     out
 }

tests/constructs.rs +32

	@@ -844,3 +844,35 @@ fn audit_counts_special_blocks_as_in_scope() {
844	"no block name is unrecognised — every one renders: {flagged:?}"	844	"no block name is unrecognised — every one renders: {flagged:?}"
845	);	845	);
846	}	846	}
		847
		848	/// A page that documents org syntax names constructs inside `=verbatim=`; the names are
		849	/// displayed, not rendered, so none of them is a use of the construct. Counting them
		850	/// reported orgo's own guide as using macros it does not support.
		851	#[test]
		852	fn audit_ignores_constructs_inside_verbatim() {
		853	let report = audit_fixture("audit-verbatim-constructs.org");
		854	for construct in ["macro call", "radio target", "internal target", "timestamp", "LaTeX fragment"]
		855	{
		856	assert!(
		857	!report.contains(construct),
		858	"{construct} was counted from a verbatim mention:\n{report}"
		859	);
		860	}
		861	}
		862
		863	/// An unlisted keyword is not a blind spot: reaching templates as `page.keywords.<name>`
		864	/// is the designed behaviour, so it is marked as pass-through rather than `???`, which
		865	/// claims orgo does not recognise the name at all.
		866	#[test]
		867	fn audit_marks_unhandled_keywords_as_pass_through() {
		868	let report = audit_fixture("audit-keywords.org");
		869	for name in ["LEDE", "PROJECT_STATUS"] {
		870	let line = report.lines().find(\|l\| l.contains(name)).expect("the keyword is censused");
		871	assert!(
		872	line.starts_with('\u{2014}'),
		873	"a keyword that reaches templates must not read as a blind spot:\n{line}"
		874	);
		875	}
		876	let flagged: Vec<&str> = report.lines().filter(\|l\| l.starts_with("???")).collect();
		877	assert!(flagged.is_empty(), "no keyword name is unrecognised: {flagged:?}");
		878	}