From baca5f8b54d031b20be61d9af19e0dd63a258d0a Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Sat, 17 Feb 2024 12:43:48 -1000
Subject: [PATCH] fix:check:tags: add date and date2 to the implicitly-declared
 special tags

And add tests/comments.
---
 hledger-lib/Hledger/Data/JournalChecks.hs | 31 +++++++++---------
 hledger/test/check-tags.test              | 39 +++++++++++++++++++++++
 2 files changed, 55 insertions(+), 15 deletions(-)

diff --git a/hledger-lib/Hledger/Data/JournalChecks.hs b/hledger-lib/Hledger/Data/JournalChecks.hs
index 37d5aa404..9aa556792 100644
--- a/hledger-lib/Hledger/Data/JournalChecks.hs
+++ b/hledger-lib/Hledger/Data/JournalChecks.hs
@@ -198,22 +198,23 @@ journalCheckTags j = do
       ])
 
 -- | Tag names which have special significance to hledger.
+-- Keep synced with check-tags.test and hledger manual > Special tags.
 builtinTags = [
-   "type"  -- declares an account's type
-  ,"t"     -- declares the (user defined, single letter) type of a 15m unit of time parsed from timedot format
-  -- generated by close
-  ,"balances"  -- balance assertions transaction
-  ,"retain"    -- retain earnings transaction
-  ,"start"     -- opening balances, closing balances or balance assignment transaction
-  -- optionally generated on periodic transactions and auto postings
-  ,"generated-transaction"
-  ,"generated-posting"
-  ,"modified"
-  -- used internally, not shown (but queryable)
-  ,"_generated-transaction"
-  ,"_generated-posting"
-  ,"_modified"
-  ,"_conversion-matched"
+   "date"                   -- overrides a posting's date
+  ,"date2"                  -- overrides a posting's secondary date
+  ,"type"                   -- declares an account's type
+  ,"t"                      -- appears on postings generated by timedot letters
+  ,"assert"                 -- appears on txns generated by close --assert
+  ,"retain"                 -- appears on txns generated by close --retain
+  ,"start"                  -- appears on txns generated by close --migrate/--close/--open/--assign
+  ,"generated-transaction"  -- with --verbose-tags, appears on generated periodic txns
+  ,"generated-posting"      -- with --verbose-tags, appears on generated auto postings
+  ,"modified"               -- with --verbose-tags, appears on txns which have had auto postings added
+  -- hidden tags used internally (and also queryable):
+  ,"_generated-transaction" -- always exists on generated periodic txns
+  ,"_generated-posting"     -- always exists on generated auto postings
+  ,"_modified"              -- always exists on txns which have had auto postings added
+  ,"_conversion-matched"    -- exists on postings which have been matched with a nearby @/@@ cost notation
   ]
 
 -- | In each tranaction, check that any conversion postings occur in adjacent pairs.
diff --git a/hledger/test/check-tags.test b/hledger/test/check-tags.test
index 21c0d4bba..766595eb9 100644
--- a/hledger/test/check-tags.test
+++ b/hledger/test/check-tags.test
@@ -39,3 +39,42 @@ $ hledger -f - check tags
 $ hledger -f - check tags
 >2 /tag "ptag" has not been declared/
 >=1
+
+# ** 6. Built-in special tags are implicitly declared and won't make check tags fail.
+# Keep synced with JournalChecks.builtinTags.
+<
+2024-01-01
+  ; date:
+  ; date2:
+  ; type:
+  ; t:
+  ; assert:
+  ; retain:
+  ; start:
+  ; generated-transaction:
+  ; generated-posting:
+  ; modified:
+  ; _generated-transaction:
+  ; _generated-posting:
+  ; _modified:
+  ; _conversion-matched:
+$ hledger -f - check tags
+
+# ** 7. Declaring the built-in special tags is harmless.
+# Keep synced with JournalChecks.builtinTags.
+<
+tag date                    ; overrides a posting's date
+tag date2                   ; overrides a posting's secondary date
+tag type                    ; declares an account's type
+tag t                       ; generated by letters in timedot data (with the letter as tag value)
+tag assert                  ; appears on txns generated by close --assert
+tag retain                  ; appears on txns generated by close --retain
+tag start                   ; appears on txns generated by close --migrate/--close/--open/--assign
+tag generated-transaction   ; with --verbose-tags, appears on generated periodic txns
+tag generated-posting       ; with --verbose-tags, appears on generated auto postings
+tag modified                ; with --verbose-tags, appears on txns which have had auto postings added
+tag _generated-transaction  ; always exists on generated periodic txns
+tag _generated-posting      ; always exists on generated auto postings
+tag _modified               ; always exists on txns which have had auto postings added
+tag _conversion-matched     ; exists on postings which have been matched with a nearby @/@@ cost notation
+$ hledger -f - check tags