From be8a7632289f052b35ff1d7be7dc2142724f6107 Mon Sep 17 00:00:00 2001
From: Ralph Amissah <ralph.amissah@gmail.com>
Date: Wed, 30 Sep 2026 10:51:57 -0400
Subject: options: request absent flag, warn; --strict fails

unrecognised options are named on stderr before any work is done, and
--strict makes such fatal (exit 1). (prior to this commit a mistyped
or retired flag was ignored without acknowledgement). This applies to
options only, an argument that is not a source, such as a README beside
pods being processed, is still passed over quietly.

(assisted by Claude-Code)
---
 org/spine.org       | 29 +++++++++++++++++++++++++++++
 src/sisudoc/spine.d | 13 +++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/org/spine.org b/org/spine.org
index 65bebff..67574f5 100644
--- a/org/spine.org
+++ b/org/spine.org
@@ -61,6 +61,7 @@ string program_name = "spine";
   <<spine_args_init_opts>>
   <<spine_args_init_settings>>
   <<spine_args_get_options_aa>>
+  <<spine_unrecognized_option>>
 <<spine_args_get_help>>
   <<read_spine_ssp_back_into_abstraction>>
   <<read_spine_ocda_db_back_into_abstraction>>
@@ -802,6 +803,34 @@ if (opts["po4a-cfg"]) {
 }
 #+END_SRC
 
+***** unrecognized option
+
+getopt runs with passThrough, so an unknown option stays among the arguments,
+and the loop over sources below does not take it for one: a mistyped or retired
+flag was accepted and did nothing. Done here, before any work, naming the
+option;
+--strict makes it fatal.
+
+Only options: an argument that is not a source (a README beside the pods, say)
+is still passed over quietly.
+
+#+NAME: spine_unrecognized_option
+#+BEGIN_SRC d
+/+ ↓ an option getopt did not recognise +/
+{
+  string[] _unknown_options
+    = args[1..$].filter!(a => a.length > 1 && a[0] == '-').array;
+  foreach (_o; _unknown_options) {
+    stderr.writeln("WARNING: option not recognised, ignored: ", _o);
+  }
+  if (_unknown_options.length > 0 && opts["strict"]) {
+    stderr.writeln("~ run FAILED ~ --strict: option not recognised");
+    import core.stdc.stdlib : exit;
+    exit(1);
+  }
+}
+#+END_SRC
+
 ***** help info
 
 #+NAME: spine_args_get_help
diff --git a/src/sisudoc/spine.d b/src/sisudoc/spine.d
index db6c8ac..e1e5d62 100644
--- a/src/sisudoc/spine.d
+++ b/src/sisudoc/spine.d
@@ -395,6 +395,19 @@ string program_name = "spine";
   if (opts["po4a-cfg"]) {
     _run_banner = false;
   }
+  /+ ↓ an option getopt did not recognise +/
+  {
+    string[] _unknown_options
+      = args[1..$].filter!(a => a.length > 1 && a[0] == '-').array;
+    foreach (_o; _unknown_options) {
+      stderr.writeln("WARNING: option not recognised, ignored: ", _o);
+    }
+    if (_unknown_options.length > 0 && opts["strict"]) {
+      stderr.writeln("~ run FAILED ~ --strict: option not recognised");
+      import core.stdc.stdlib : exit;
+      exit(1);
+    }
+  }
   if (helpInfo.helpWanted) {
     /+ ↓ the undocumented alias is registered so that it still works, and is
          not listed, so that --ocda-db is the one flag the help offers
-- 
cgit v1.2.3