From 51549f11d60cd353564486b3598e69259fb01b66 Mon Sep 17 00:00:00 2001
From: Ralph Amissah <ralph.amissah@gmail.com>
Date: Wed, 22 Apr 2026 13:52:21 -0400
Subject: document abstraction as per document sqlite db

  --show-abstraction-db flag to write per-document

- SQLite database of document abstraction
  (Claude-Code primary assist)

- Add a new output mode that serializes the in-memory document
  abstraction to a per-document SQLite database. This complements
  the .ssp text format (--show-abstraction) with a queryable
  database representation of the same data.

- Schema:
    metadata table - key/value pairs for document metadata
      (title, creator, dates, rights, classify, identifiers,
      language, notes, make settings, doc_has counts)
    objects table - one row per document object with columns:
      section, seq (position within section), ocn, is_a,
      is_of_part, is_of_type, heading_level, identifier,
      parent_ocn, last_descendant_ocn, ancestors,
      indent/bullet/lang, has_* flags, segment/anchor tags,
      table/code properties, text content
    Indexed on: section, ocn, parent_ocn, is_a, heading_level

- Uses prepared statements via d2sqlite3 (existing dependency)
  for safe and efficient insertion. Each document produces a
  standalone .abstraction.db file in the abstraction/ output
  directory.

- New files:
    src/sisudoc/io_out/create_abstraction_db.d
      Follows the same pattern as create_abstraction_txt.d.
      Creates schema, populates metadata via key/value inserts,
      then iterates all sections writing objects with prepared
      statements within a single transaction.

- Changes to spine.d:
    - Add "show-abstraction-db" to opts init, getopt, OptActions
    - Add to abstraction(), require_processing_files(), and
      meta_processing_general() gates
    - Insert call at both spineAbstraction sites

- Tested against all 35 sample documents (including 9-language
  live-manual) - zero failures. Works standalone or combined
  with --show-abstraction and other output flags.

- Example queries the database supports:
    SELECT ocn, heading_level, text FROM objects
      WHERE is_a = 'heading' AND section = 'body';
    SELECT * FROM objects WHERE parent_ocn = 10;
    SELECT key, value FROM metadata WHERE key LIKE 'title.%';

  Co-Authored-By: Anthropic Claude Opus 4.6 (1M context)
---
 org/spine.org | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

(limited to 'org/spine.org')

diff --git a/org/spine.org b/org/spine.org
index 1eef0a3..abc4b07 100644
--- a/org/spine.org
+++ b/org/spine.org
@@ -342,6 +342,7 @@ bool[string] opts = [
   "pod"                         : false,
   "serial"                      : false,
   "show-abstraction"            : false,
+  "show-abstraction-db"         : false,
   "show-config"                 : false,
   "show-curate"                 : false,
   "show-curate-authors"         : false,
@@ -478,6 +479,7 @@ auto helpInfo = getopt(args,
   "serial",                     "serial processing",                                              &opts["serial"],
   "skip-output",                "skip output",                                                    &opts["skip-output"],
   "show-abstraction",           "show document abstraction (write .ssp file)",                    &opts["show-abstraction"],
+  "show-abstraction-db",        "show document abstraction (write .db sqlite file)",              &opts["show-abstraction-db"],
   "show-config",                "show config",                                                    &opts["show-config"],
   "show-curate",                "show curate",                                                    &opts["show-curate"],
   "show-curate-authors",        "show curate authors",                                            &opts["show-curate-authors"],
@@ -699,6 +701,9 @@ struct OptActions {
   @trusted bool show_abstraction() {
     return opts["show-abstraction"];
   }
+  @trusted bool show_abstraction_db() {
+    return opts["show-abstraction-db"];
+  }
   @trusted bool show_curate() {
     return opts["show-curate"];
   }
@@ -948,6 +953,7 @@ struct OptActions {
     return (
       opts["abstraction"]
       || show_abstraction
+      || show_abstraction_db
       || concordance
       || source_or_pod
       || curate
@@ -975,6 +981,7 @@ struct OptActions {
       || odt
       || manifest
       || show_abstraction
+      || show_abstraction_db
       || show_make
       || show_metadata
       || show_summary
@@ -990,6 +997,7 @@ struct OptActions {
     return (
       opts["abstraction"]
       || show_abstraction
+      || show_abstraction_db
       || curate
       || html
       || epub
@@ -1543,7 +1551,8 @@ if ((doc.matters.opt.action.debug_do)
 <<spine_each_file_do_debugs_checkdoc_1>>
 <<spine_each_file_do_debugs_checkdoc_2>>
 <<spine_each_file_do_debugs_checkdoc_3>>
-<<spine_each_file_show_abstraction>>
+<<spine_each_file_show_abstraction_peg>>
+<<spine_each_file_show_abstraction_db>>
 <<spine_each_file_do_debugs_checkdoc_4>>
 <<spine_each_file_do_debugs_checkdoc_5>>
 #+END_SRC
@@ -1598,7 +1607,7 @@ if (doc.matters.opt.action.show_config) {
 ***** show abstraction (PEG)
 --show-abstraction
 
-#+NAME: spine_each_file_show_abstraction
+#+NAME: spine_each_file_show_abstraction_peg
 #+BEGIN_SRC d
 /+ ↓ document abstraction text representation +/
 if (doc.matters.opt.action.show_abstraction) {
@@ -1607,6 +1616,18 @@ if (doc.matters.opt.action.show_abstraction) {
 }
 #+END_SRC
 
+***** show abstraction (sqlite db)
+--show-abstraction-db
+
+#+NAME: spine_each_file_show_abstraction_db
+#+BEGIN_SRC d
+/+ ↓ document abstraction sqlite database +/
+if (doc.matters.opt.action.show_abstraction_db) {
+  import sisudoc.io_out.create_abstraction_db;
+  spineAbstractionDb!()(doc);
+}
+#+END_SRC
+
 ***** abstraction curate :abstraction:curate:
 - abstraction curate
 
-- 
cgit v1.2.3