ocda: one constructor for doc_matters

ST_DocumentMatters was declared inside spineAbstraction(), closing over
the parser's locals, so only the parser could build it. A document
loaded from a .ssp or a .ocda.db has to arrive at the same value from
what the artefact carries, and had nothing to build.

It is moved to sisudoc.ocda.meta.doc_matters as docMattersMake(), taking
the seven things a document is described by: the run (program_info,
opt_action), where it is and what it is called (manifest), its header
and the site config (conf_make_meta), its counts and indexes
(ST_DocHas), its source digests, and the files its markup inserted. The
parser fills them from what it has just parsed; the loader will fill
them from the artefact.

Pure refactor: the struct's members are unchanged, only where it is
declared and where its inputs come from.

(assisted by Claude-Code)

1 files changed, 200 insertions, 182 deletions

diff --git a/org/spine.org b/org/spine.org
index 50b9ce2..3ff3c05 100644
--- a/org/spine.org
+++ b/org/spine.org
@@ -188,6 +188,7 @@ import sisudoc.ocda.meta.defaults;
 import sisudoc.ocda.io_in.paths_source;
 import sisudoc.ocda.io_in.read_config_files;
 import sisudoc.ocda.io_in.read_source_files;
+import sisudoc.ocda.meta.doc_matters;
 #+END_SRC
 
 ****** notes
@@ -247,6 +248,7 @@ mixin outputHub;
 
 #+NAME: spine_metadoc_mixin
 #+BEGIN_SRC d
+mixin spineDocMatters;
 mixin spineBiblio;
 #+END_SRC
 
@@ -1880,14 +1882,18 @@ template spineAbstraction() {
     <<spine_each_file_do_split_dr_markup_file_header_into_make_and_meta_structs>>
     <<spine_each_file_do_document_abstraction>>
     <<spine_each_file_do_document_matters_msg_step4_start>>
-    struct ST_DocumentMatters {
-      <<spine_each_file_do_document_matters_1_detail_program_time>>
-      <<spine_each_file_do_document_matters_2_meta>>
-      <<spine_each_file_do_document_matters_3_env>>
-      <<spine_each_file_do_document_matters_4_opt>>
-      <<spine_each_file_do_document_matters_5_doc>>
-    }
-    auto doc_matters = ST_DocumentMatters();
+    /+ ↓ doc_matters, built by the one constructor a loaded abstraction also
+         uses, so that the two paths cannot describe a document differently
+    +/
+    auto doc_matters = docMattersMake(
+      program_info,
+      _opt_action,
+      _manifest,
+      _make_and_meta_struct,
+      _doc_has_struct,
+      doc_digests,
+      _header_body_insertfilelist_imagelist.insert_file_list,
+    );
     <<spine_each_file_do_document_matters_msg_step4_end>>
     auto theDOC() {
       struct ST_DOC {
@@ -1906,6 +1912,192 @@ template spineAbstraction() {
 }
 #+END_SRC
 
+#+HEADER: :tangle "../src/sisudoc/ocda/meta/doc_matters.d"
+#+BEGIN_SRC d
+<<doc_header_including_copyright_and_license>>
+module sisudoc.ocda.meta.doc_matters;
+@safe:
+/+ ↓ doc_matters: the one description of what an output writer is given
+
+     spineAbstraction() builds this from the markup it has just parsed. A
+     document loaded from a .ssp or a .ocda.db has to arrive at the same
+     value from what the artefact carries, so the construction lives here
+     rather than inside the parser, and both paths fill the same arguments:
+
+       program_info           the run
+       opt_action             the run
+       manifest               where the document is, and what it is called
+       conf_make_meta         the document's header, plus the site config
+       doc_has                the counts, lists and indexes (ST_DocHas)
+       doc_digest             the source digests
+       insert_file_list       the files the markup inserted, for --pod2
+
+     Nothing downstream learns which path filled them, which is the point:
+     an output writer that has to know where the document came from is a
+     writer that has had something leak into it from upstream.
++/
+template spineDocMatters() {
+  import std.conv : to;
+  import std.datetime;
+  import std.stdio;
+  import sisudoc.ocda.meta.conf_make_meta_structs;
+  import sisudoc.ocda.io_in.paths_source;
+  auto docMattersMake(P,O,M,H,D)(
+    P             program_info,
+    O             _opt_action,
+    M             _manifest,
+    ConfComposite _make_and_meta_struct,
+    H             _doc_has_struct,
+    D             doc_digests,
+    string[]      _insert_file_list,
+  ) {
+    struct ST_DocumentMatters {
+      auto generator_program() {
+        struct Prog_ {
+          string project_name() {
+            return "spine";
+          }
+          string name() {
+            return program_info.name;
+          }
+          string ver() {
+            return program_info.ver;
+          }
+          @trusted string name_and_version() {
+            return program_info.name_and_version;
+          }
+          @trusted string name_version_and_compiler() {
+            return program_info.name_version_and_compiler;
+          }
+          string url_home() {
+            return "https://sisudoc.org";
+          }
+          string url_git() {
+            return "https://git.sisudoc.org/projects/";
+          }
+          auto compiler() {
+            return program_info.compiler;
+          }
+          auto time_output_generated() {
+            return program_info.time_output_generated;
+          }
+        }
+        return Prog_();
+      }
+      auto generated_time() {
+        auto _st = Clock.currTime(UTC());
+        auto _time = _st.year.to!string
+          ~ "-" ~ _st.month.to!int.to!string // prefer as month number
+          ~ "-" ~ _st.day.to!string
+          ~ " [" ~ _st.isoWeek.to!string ~ "/" ~ _st.dayOfWeek.to!int.to!string ~ "]"
+          ~ " " ~ _st.hour.to!string
+          ~ ":" ~ _st.minute.to!string
+          ~ ":" ~ _st.second.to!string;
+        return _time;
+      }
+      ConfComposite conf_make_meta() {
+        return _make_and_meta_struct;
+      }
+      auto doc_digest() {
+        return doc_digests;
+      }
+      auto has() {
+        return _doc_has_struct;
+      }
+      auto env() {
+        struct Env_ {
+          auto pwd() {
+            return _manifest.env.pwd;
+          }
+          auto home() {
+            return _manifest.env.home;
+          }
+        }
+        return Env_();
+      }
+      auto opt() {
+        struct Opt_ {
+          auto action() {
+            /+ getopt options, commandline instructions, raw
+             - processing instructions --epub --html etc.
+             - command line config instructions --output
+            +/
+            return _opt_action;
+          }
+        }
+        return Opt_();
+      }
+      auto src() {
+        return _manifest.src;
+      }
+      auto src_path_info() {
+        return spinePathsSRC!()(_manifest.env.pwd, _manifest.src.file_with_absolute_path); // would like (to have and use) relative path
+      }
+      auto pod() {
+        return _manifest.pod;
+      }
+      auto sqlite() {
+        struct SQLite_ {
+          string filename() {
+            string _fn = "";
+            string _pth = "";
+            if (_opt_action.sqliteDB_filename.length > 0) {
+              _fn = _opt_action.sqliteDB_filename;
+            } else if (_make_and_meta_struct.conf.w_srv_db_sqlite_filename.length > 0) {
+              _fn = _make_and_meta_struct.conf.w_srv_db_sqlite_filename;
+            }
+            return _fn;
+          }
+          string path() {
+            string _pth = "";
+            if (_opt_action.sqliteDB_path.length > 0) {
+              _pth = _opt_action.sqliteDB_path;
+            } else if (_make_and_meta_struct.conf.w_srv_db_sqlite_path.length > 0) {
+              _pth = _make_and_meta_struct.conf.w_srv_db_sqlite_path;
+            }
+            return _pth;
+          }
+          string cgi_filename() {
+            string _fn = "";
+            if (_opt_action.cgi_sqlite_search_filename.length > 0) {
+              _fn = _opt_action.cgi_sqlite_search_filename;
+            } else if (_make_and_meta_struct.conf.w_srv_cgi_search_script.length > 0) {
+              _fn = _make_and_meta_struct.conf.w_srv_cgi_search_script;
+            }
+            return _fn;
+          }
+          string cgi_filename_d() {
+            string _fn = "";
+            if (_opt_action.cgi_sqlite_search_filename_d.length > 0) {
+              _fn = _opt_action.cgi_sqlite_search_filename_d;
+            } else if (_make_and_meta_struct.conf.w_srv_cgi_search_script_raw_fn_d.length > 0) {
+              _fn = _make_and_meta_struct.conf.w_srv_cgi_search_script_raw_fn_d;
+            }
+            return _fn;
+          }
+        }
+        return SQLite_();
+      }
+      auto output_path() {
+        return _make_and_meta_struct.conf.output_path;
+      }
+      auto srcs() {
+        struct SRC_ {
+          auto file_insert_list() {
+            return _insert_file_list;
+          }
+          auto image_list() {
+            return _doc_has_struct.imagelist;
+          }
+        }
+        return SRC_();
+      }
+    }
+    return ST_DocumentMatters();
+  }
+}
+#+END_SRC
+
 ** Output & Curate pre-processing
 *** 1. raw file content split, doc: _header_, _content_ +(lists: subdocs? images?)
 - [[./source_read_files.org][source_read_files]] return tuple: header; body; insert file list; image list
@@ -2047,180 +2239,6 @@ if ((_opt_action.debug_do)
 }
 #+END_SRC
 
-**** DocumentMatters struct {
-
-**** generator related
-
-#+NAME: spine_each_file_do_document_matters_1_detail_program_time
-#+BEGIN_SRC d
-auto generator_program() {
-  struct Prog_ {
-    string project_name() {
-      return "spine";
-    }
-    string name() {
-      return program_info.name;
-    }
-    string ver() {
-      return program_info.ver;
-    }
-    @trusted string name_and_version() {
-      return program_info.name_and_version;
-    }
-    @trusted string name_version_and_compiler() {
-      return program_info.name_version_and_compiler;
-    }
-    string url_home() {
-      return "https://sisudoc.org";
-    }
-    string url_git() {
-      return "https://git.sisudoc.org/projects/";
-    }
-    auto compiler() {
-      return program_info.compiler;
-    }
-    auto time_output_generated() {
-      return program_info.time_output_generated;
-    }
-  }
-  return Prog_();
-}
-auto generated_time() {
-  auto _st = Clock.currTime(UTC());
-  auto _time = _st.year.to!string
-    ~ "-" ~ _st.month.to!int.to!string // prefer as month number
-    ~ "-" ~ _st.day.to!string
-    ~ " [" ~ _st.isoWeek.to!string ~ "/" ~ _st.dayOfWeek.to!int.to!string ~ "]"
-    ~ " " ~ _st.hour.to!string
-    ~ ":" ~ _st.minute.to!string
-    ~ ":" ~ _st.second.to!string;
-  return _time;
-}
-#+END_SRC
-
-***** config make & meta
-
-#+NAME: spine_each_file_do_document_matters_2_meta
-#+BEGIN_SRC d
-ConfComposite conf_make_meta() {
-  return _make_and_meta_struct;
-}
-auto doc_digest() {
-  return doc_digests;
-}
-auto has() {
-  return _doc_has_struct;
-}
-#+END_SRC
-
-***** env related
-
-#+NAME: spine_each_file_do_document_matters_3_env
-#+BEGIN_SRC d
-auto env() {
-  struct Env_ {
-    auto pwd() {
-      return _manifest.env.pwd;
-    }
-    auto home() {
-      return _manifest.env.home;
-    }
-  }
-  return Env_();
-}
-#+END_SRC
-
-***** opt
-
-#+NAME: spine_each_file_do_document_matters_4_opt
-#+BEGIN_SRC d
-auto opt() {
-  struct Opt_ {
-    auto action() {
-      /+ getopt options, commandline instructions, raw
-       - processing instructions --epub --html etc.
-       - command line config instructions --output
-      +/
-      return _opt_action;
-    }
-  }
-  return Opt_();
-}
-#+END_SRC
-
-***** output related
-
-#+NAME: spine_each_file_do_document_matters_5_doc
-#+BEGIN_SRC d
-auto src() {
-  return _manifest.src;
-}
-auto src_path_info() {
-  return spinePathsSRC!()(_manifest.env.pwd, _manifest.src.file_with_absolute_path); // would like (to have and use) relative path
-}
-auto pod() {
-  return _manifest.pod;
-}
-auto sqlite() {
-  struct SQLite_ {
-    string filename() {
-      string _fn = "";
-      string _pth = "";
-      if (_opt_action.sqliteDB_filename.length > 0) {
-        _fn = _opt_action.sqliteDB_filename;
-      } else if (_make_and_meta_struct.conf.w_srv_db_sqlite_filename.length > 0) {
-        _fn = _make_and_meta_struct.conf.w_srv_db_sqlite_filename;
-      }
-      return _fn;
-    }
-    string path() {
-      string _pth = "";
-      if (_opt_action.sqliteDB_path.length > 0) {
-        _pth = _opt_action.sqliteDB_path;
-      } else if (_make_and_meta_struct.conf.w_srv_db_sqlite_path.length > 0) {
-        _pth = _make_and_meta_struct.conf.w_srv_db_sqlite_path;
-      }
-      return _pth;
-    }
-    string cgi_filename() {
-      string _fn = "";
-      if (_opt_action.cgi_sqlite_search_filename.length > 0) {
-        _fn = _opt_action.cgi_sqlite_search_filename;
-      } else if (_make_and_meta_struct.conf.w_srv_cgi_search_script.length > 0) {
-        _fn = _make_and_meta_struct.conf.w_srv_cgi_search_script;
-      }
-      return _fn;
-    }
-    string cgi_filename_d() {
-      string _fn = "";
-      if (_opt_action.cgi_sqlite_search_filename_d.length > 0) {
-        _fn = _opt_action.cgi_sqlite_search_filename_d;
-      } else if (_make_and_meta_struct.conf.w_srv_cgi_search_script_raw_fn_d.length > 0) {
-        _fn = _make_and_meta_struct.conf.w_srv_cgi_search_script_raw_fn_d;
-      }
-      return _fn;
-    }
-  }
-  return SQLite_();
-}
-auto output_path() {
-  return _make_and_meta_struct.conf.output_path;
-}
-auto srcs() {
-  struct SRC_ {
-    auto file_insert_list() {
-      return _header_body_insertfilelist_imagelist.insert_file_list;
-    }
-    auto image_list() {
-      return _doc_has_struct.imagelist;
-    }
-  }
-  return SRC_();
-}
-#+END_SRC
-
-**** } close
-
 **** step complete message
 
 #+NAME: spine_each_file_do_document_matters_msg_step4_end