From da833f8b157ae501c9f6eec827dd4a965bfa7265 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Thu, 24 Sep 2026 11:12:28 -0400 Subject: format 2.0: the version gate The reader as it stood when the format reached 2.0, in D: a parser of the .ssp with no dependency beyond phobos, and outputs from it - a heading tree, an html scroll, breadcrumbed text, chunked jsonl for embedding pipelines, an image manifest, and a check of image records against the images on disk. Brought to abstraction format 2.0, and made able to say what it does not understand, so a reader can check that its format specification is complete. Previously the reader ignored what it did not recognise and reported nothing, which made it seem it had understood a 2.0 file (and drop things in silence). Now: - the banner is read, and the major part checked. A major this reader does not know is refused, exit 3, because an unknown major means a property may have changed meaning or gone away and loading it half populated in silence is the failure the check exists to prevent. --any-version reads it regardless, for looking at a file rather than trusting one. A file with no banner warns and is read. - @source is a preamble block beside @meta, @make and @doc_has, and the summary line shows the language and the markup digest. - tail is a section like the rest. - --report-unknown lists every property, block and line shape met and not understood, with counts. Ignoring them remains the conforming behaviour within a major version; the counting is so that it is not silent. Over the markup document samples that report names 18 properties, from .is_of_type at 56,882 occurrences down to .attrib at 1. Several are legitimately of no interest to a renderer and several are not. Deciding which is which is the next pass, and it now has a measured work list rather than a guess. (assisted by Claude-Code) --- src/main.d | 148 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 src/main.d (limited to 'src/main.d') diff --git a/src/main.d b/src/main.d new file mode 100644 index 0000000..78ceb69 --- /dev/null +++ b/src/main.d @@ -0,0 +1,148 @@ +import std.getopt; +import std.stdio : writeln, stderr; +import ssp_parser; +import ssp_types; +import output_tree; +import output_html; +import output_llm_breadcrumbs; +import output_llm_jsonl; +import output_images; +import verify_images; +import report_unknown; + +int main(string[] args) { + bool do_tree = false; + bool do_html = false; + bool do_llm_text = false; + bool do_llm_jsonl = false; + bool do_images = false; + bool do_verify = false; + bool do_report_unknown = false; + bool any_version = false; + string image_dir = ""; + string output_file = ""; + + auto helpInfo = getopt(args, + "tree", "output document tree outline", &do_tree, + "html", "output HTML scroll", &do_html, + "llm-text", "output plain text with heading breadcrumbs", &do_llm_text, + "llm-jsonl", "output JSONL with embeddings-ready chunks", &do_llm_jsonl, + "images", "output image manifest (digest, size, pixels)", &do_images, + "verify", "verify .image records against --image-dir", &do_verify, + "image-dir", "image directory to verify against", &image_dir, + "output", "output file (default: stdout)", &output_file, + "report-unknown", "list what was read and not understood", &do_report_unknown, + "any-version", "read a format major version this reader does not know", &any_version, + ); + + if (helpInfo.helpWanted || args.length < 2) { + defaultGetoptPrinter( + "ssp-reader - reads .ssp files and produces output\n\n" + ~ "Usage: ssp-reader [options] \n", + helpInfo.options, + ); + return 0; + } + + string input_file = args[1]; + + SspDocument doc; + try { + doc = parseSspFile(input_file); + } catch (Exception e) { + stderr.writeln("Error reading ", input_file, ": ", e.msg); + return 2; + } + + /+ ↓ the version gate. A reader checks the major part and refuses what it + does not know: an unknown major means a property may have changed + meaning or gone away, and loading it half populated in silence is the + failure this exists to prevent. --any-version overrides, for looking + at a file rather than trusting one. + +/ + if (doc.format_version.length == 0) { + stderr.writeln("warning: ", input_file, + " declares no format version (no \"% SiSU Document Abstraction v\" line)"); + } else if (doc.formatVersionMajor != ssp_format_major_read) { + if (any_version) { + stderr.writeln("warning: ", input_file, " is format v", doc.format_version, + ", this reader knows v", ssp_format_major_read, ".x; reading anyway"); + } else { + stderr.writeln("error: ", input_file, " is format v", doc.format_version, + ", this reader knows v", ssp_format_major_read, ".x"); + stderr.writeln(" a major version differs: a property may have", + " changed meaning or gone away."); + stderr.writeln(" --any-version reads it regardless."); + return 3; + } + } + + writeln("Parsed: ", input_file); + if (doc.format_version.length > 0) { + writeln(" Format: v", doc.format_version); + } + if (auto _lang = "language" in doc.source) { + writeln(" Source: ", *_lang, + ("languages" in doc.source) ? " of " ~ doc.source["languages"] : "", + ("digest" in doc.source) ? ", markup digest " ~ doc.source["digest"][0 .. 16] ~ "..." : ""); + } + writeln(" Title: ", doc.meta("title.main")); + writeln(" Author: ", doc.meta("creator.author")); + writeln(" Sections: head=", doc.head.length, + " toc=", doc.toc.length, + " body=", doc.body.length, + " endnotes=", doc.endnotes.length, + " glossary=", doc.glossary.length, + " bibliography=", doc.bibliography.length, + " bookindex=", doc.bookindex.length, + " blurb=", doc.blurb.length, + " tail=", doc.tail.length); + auto image_records = imageRecordCount(doc); + if (image_records > 0) { + writeln(" Images: ", image_records, " record", + (image_records == 1) ? "" : "s"); + } + + if (do_tree) { + outputTree(doc, output_file); + } + + if (do_html) { + outputHtmlScroll(doc, output_file); + } + + if (do_llm_text) { + outputLlmBreadcrumbs(doc, output_file); + } + + if (do_llm_jsonl) { + outputLlmJsonl(doc, output_file); + } + + if (do_images) { + outputImages(doc, output_file); + } + + + int _verify_failures = 0; + if (do_verify) { + if (image_dir.length == 0) { + stderr.writeln("--verify needs --image-dir="); + return 2; + } + _verify_failures = verifyImages(doc, image_dir, output_file); + } + + if (do_report_unknown) { + reportUnknown(doc); + } + + if (!do_tree && !do_html && !do_llm_text && !do_llm_jsonl && !do_images + && !do_verify && !do_report_unknown) { + writeln("\nUse --tree, --html, --llm-text, --llm-jsonl, --images," + ~ " --verify --image-dir=" + ~ " or --report-unknown to produce output."); + } + + return (_verify_failures > 0) ? 1 : 0; +} -- cgit v1.2.3