metanorma-document 0.3.0 → 0.5.0

data/.rubocop_todo.yml

@@ -1,220 +0,0 @@
-# This configuration was generated by
-# `rubocop --auto-gen-config`
-# on 2026-07-18 16:00:24 UTC using RuboCop version 1.86.1.
-# The point is for the user to remove these configuration records
-# one by one as the offenses are removed from the code base.
-# Note that changes in the inspected code, or installation of new
-# versions of RuboCop, may require this file to be generated again.
-
-# Offense count: 1
-Gemspec/RequiredRubyVersion:
-  Exclude:
-    - 'metanorma-document.gemspec'
-
-# Offense count: 703
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
-# URISchemes: http, https
-Layout/LineLength:
-  Enabled: false
-
-# Offense count: 2
-# Configuration parameters: AllowedMethods.
-# AllowedMethods: enums
-Lint/ConstantDefinitionInBlock:
-  Exclude:
-    - 'spec/metanorma/html/renderer/class_ownership_spec.rb'
-    - 'spec/metanorma/html/renderer/liquid_templates_spec.rb'
-
-# Offense count: 3
-# Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
-Lint/DuplicateBranch:
-  Exclude:
-    - 'lib/metanorma/html/base_renderer.rb'
-    - 'lib/metanorma/html/renderers/inline_renderer.rb'
-    - 'lib/metanorma/html/standard_renderer.rb'
-
-# Offense count: 2
-# Configuration parameters: AllowComments, AllowEmptyLambdas.
-Lint/EmptyBlock:
-  Exclude:
-    - 'spec/metanorma/iso_document/metadata/title_roundtrip_spec.rb'
-
-# Offense count: 4
-# Configuration parameters: AllowedParentClasses.
-Lint/MissingSuper:
-  Exclude:
-    - 'lib/metanorma/html/drops/figure_drop.rb'
-    - 'lib/metanorma/html/drops/formula_drop.rb'
-    - 'lib/metanorma/html/drops/sourcecode_drop.rb'
-    - 'lib/metanorma/mirror/id_strategy/positional.rb'
-
-# Offense count: 1
-Lint/StructNewOverride:
-  Exclude:
-    - 'lib/metanorma/html/component/index_term_collector.rb'
-
-# Offense count: 23
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
-# NotImplementedExceptions: NotImplementedError
-Lint/UnusedMethodArgument:
-  Exclude:
-    - 'lib/metanorma/mirror/handlers/formula.rb'
-    - 'lib/metanorma/mirror/handlers/sourcecode.rb'
-    - 'lib/metanorma/mirror/output/html_renderers/block_renderers.rb'
-    - 'lib/metanorma/mirror/output/html_renderers/list_renderers.rb'
-    - 'lib/metanorma/mirror/output/html_renderers/section_renderers.rb'
-    - 'lib/metanorma/mirror/output/html_renderers/structural_renderers.rb'
-    - 'lib/metanorma/mirror/output/html_renderers/table_renderers.rb'
-    - 'spec/metanorma/mirror/handler_registry_spec.rb'
-    - 'spec/metanorma/mirror/html_renderer_spec.rb'
-
-# Offense count: 114
-# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
-Metrics/AbcSize:
-  Enabled: false
-
-# Offense count: 12
-# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
-# AllowedMethods: refine
-Metrics/BlockLength:
-  Max: 76
-
-# Offense count: 3
-# Configuration parameters: CountBlocks, CountModifierForms.
-Metrics/BlockNesting:
-  Max: 4
-
-# Offense count: 84
-# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
-Metrics/CyclomaticComplexity:
-  Enabled: false
-
-# Offense count: 149
-# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
-Metrics/MethodLength:
-  Max: 102
-
-# Offense count: 3
-# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
-Metrics/ParameterLists:
-  Max: 7
-
-# Offense count: 68
-# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
-Metrics/PerceivedComplexity:
-  Enabled: false
-
-# Offense count: 52
-# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
-# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
-Naming/MethodParameterName:
-  Exclude:
-    - 'lib/metanorma/html/base_renderer.rb'
-    - 'lib/metanorma/html/component/footnote_collector.rb'
-    - 'lib/metanorma/html/drops/sourcecode_drop.rb'
-    - 'lib/metanorma/html/iso_renderer.rb'
-    - 'lib/metanorma/html/renderers/block_renderer.rb'
-    - 'lib/metanorma/html/renderers/inline_renderer.rb'
-    - 'spec/metanorma/html/renderer/footnote_collector_spec.rb'
-
-# Offense count: 4
-# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
-# AllowedMethods: call
-# WaywardPredicates: infinite?, nonzero?
-Naming/PredicateMethod:
-  Exclude:
-    - 'lib/metanorma/html/base_renderer.rb'
-    - 'lib/metanorma/html/drops/biblio_entry_drop.rb'
-    - 'lib/metanorma/html/renderers/inline_renderer.rb'
-
-# Offense count: 3
-# Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
-# NamePrefix: is_, has_, have_, does_
-# ForbiddenPrefixes: is_, has_, have_, does_
-# AllowedMethods: is_a?
-# MethodDefinitionMacros: define_method, define_singleton_method
-Naming/PredicatePrefix:
-  Exclude:
-    - 'spec/**/*'
-    - 'lib/metanorma/html/base_renderer.rb'
-    - 'lib/metanorma/html/drops/biblio_entry_drop.rb'
-
-# Offense count: 1
-Performance/MapMethodChain:
-  Exclude:
-    - 'spec/metanorma/flavor_roots/flavor_roots_spec.rb'
-
-# Offense count: 7
-RSpec/BeforeAfterAll:
-  Exclude:
-    - '**/spec/spec_helper.rb'
-    - '**/spec/rails_helper.rb'
-    - '**/spec/support/**/*.rb'
-    - 'spec/metanorma/flavor_roots/flavor_roots_spec.rb'
-
-# Offense count: 14
-# Configuration parameters: Prefixes, AllowedPatterns.
-# Prefixes: when, with, without
-RSpec/ContextWording:
-  Exclude:
-    - 'spec/metanorma/html/renderer/theme_spec.rb'
-    - 'spec/metanorma/mirror/html_renderer_spec.rb'
-
-# Offense count: 32
-# Configuration parameters: IgnoredMetadata.
-RSpec/DescribeClass:
-  Enabled: false
-
-# Offense count: 234
-# Configuration parameters: CountAsOne.
-RSpec/ExampleLength:
-  Max: 37
-
-# Offense count: 2
-RSpec/LeakyConstantDeclaration:
-  Exclude:
-    - 'spec/metanorma/html/renderer/class_ownership_spec.rb'
-    - 'spec/metanorma/html/renderer/liquid_templates_spec.rb'
-
-# Offense count: 5
-RSpec/MultipleDescribes:
-  Exclude:
-    - 'spec/metanorma/document_spec.rb'
-    - 'spec/metanorma/html/flavor_registry_spec.rb'
-    - 'spec/metanorma/mirror/handlers/remaining_handlers_spec.rb'
-    - 'spec/metanorma/mirror/serialization_spec.rb'
-    - 'spec/metanorma/standard_document/sections_spec.rb'
-
-# Offense count: 1
-# Configuration parameters: AllowSubject.
-RSpec/MultipleMemoizedHelpers:
-  Max: 7
-
-# Offense count: 30
-# Configuration parameters: EnforcedStyle, IgnoreSharedExamples.
-# SupportedStyles: always, named_only
-RSpec/NamedSubject:
-  Exclude:
-    - 'spec/metanorma/flavor_roots/flavor_roots_spec.rb'
-
-# Offense count: 1076
-# Configuration parameters: AllowedPatterns.
-# AllowedPatterns: ^expect_, ^assert_
-RSpec/NoExpectationExample:
-  Enabled: false
-
-# Offense count: 29
-# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
-# SupportedInflectors: default, active_support
-RSpec/SpecFilePathFormat:
-  Enabled: false
-
-# Offense count: 5
-# This cop supports safe autocorrection (--autocorrect).
-Style/ComparableClamp:
-  Exclude:
-    - 'lib/metanorma/html/iso_renderer.rb'
-    - 'lib/metanorma/html/renderers/section_renderer.rb'
-    - 'lib/metanorma/html/standard_renderer.rb'

data/TODO.finalize/01-split-multi-class-files.md

@@ -1,8 +0,0 @@
-# 01 — Split multi-class files into one-class-per-file — DONE
-
-All model files now contain exactly one class per file. Verified: every file under `lib/metanorma/document/`, `lib/metanorma/standard_document/`, `lib/metanorma/iso_document/`, `lib/metanorma/bipm_document/`, `lib/metanorma/itu_document/`, `lib/metanorma/ietf_document/`, `lib/metanorma/cc_document/` is single-class.
-
-Nested classes that are only used internally by their parent (e.g. `AnnotationContainer::Annotation`) are legitimate and NOT split.
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/02-remove-data-dist-iso-document-frontend.md

@@ -1,6 +0,0 @@
-# 02 — Remove misplaced `data/dist/iso_document/frontend/` artifacts — DONE
-
-`data/dist/iso_document/frontend/` directory no longer exists. Frontend build artifacts are correctly placed in `frontend/dist/` and included in gemspec via `Dir.glob("frontend/dist/*")`.
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/03-align-frontend-iife-and-gha-build.md

@@ -1,11 +0,0 @@
-# 03 — Align frontend IIFE build and GHA gem release with docbook pattern — DONE
-
-Aligned with docbook project:
-- `Rakefile` has `build_frontend` task + release hook
-- `gemspec` includes `frontend/dist/*`
-- `.github/workflows/rake.yml` has `after-setup-ruby: cd frontend && npm install && npm run build`
-- `frontend/vite.config.ts` produces `app.iife.js` + `app.css`
-- `.gitignore` has `frontend/node_modules/` and `frontend/dist/`
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/04-theme-per-flavor-config-driven.md

@@ -1,9 +0,0 @@
-# 04 — Data-centric theme system: config files per flavor — DONE
-
-All 13 flavor themes extracted to `data/themes/{flavor}.yaml`. `Theme.load(:iso)` reads YAML and applies overrides. BaseRenderer provides default `Theme.new`. Every flavor renderer uses `Theme.load(:flavor_name)`.
-
-### Remaining enhancement
-Publisher metadata (publishers, publisher_name, logo_map, font_url) still hardcoded in flavor renderers. These should move into theme YAML config so flavor renderers can be auto-generated from config alone.
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/05-migrate-all-html-to-liquid.md

@@ -1,16 +0,0 @@
-# 05 — Migrate all HTML generation to Liquid templates — DONE
-
-All HTML element generation uses Liquid templates. Zero raw HTML string injection via `@output <<` remains. The `tag()` helper has been removed from `base_renderer.rb`. All remaining `@output <<` calls are text streaming (`escape_html`, whitespace, raw content passthrough) — not HTML element generation.
-
-32+ Liquid templates exist in `lib/metanorma/html/templates/`. The generic `_element.html.liquid` handles most tag wrapping. Specialized templates exist for tables, lists, figures, headings, math, links, etc.
-
-### OOP Liquid pattern
-All rendering uses the `capture_output` + `render_liquid` pattern:
-1. Capture child content into a Ruby string via `capture_output`
-2. Pass captured content to `render_liquid("_template.html.liquid", assigns)`
-3. Result is appended to `@output` by the caller
-
-Drop classes (`Drops::*`) are used for complex objects that need pre-rendered HTML fields (e.g. `BiblioEntryDrop`, `FigureDrop`).
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/06-integrate-pubid-library.md

@@ -1,16 +0,0 @@
-# 06 — Integrate pubid library for publication identifier handling — DONE
-
-## What was done
-1. Added `pubid ~> 2.0` to gemspec dependency
-2. Added `gem "pubid", path: "../../mn/pubid"` to Gemfile for local dev
-3. Created `lib/metanorma/html/concerns/pubid_rendering.rb` — `PubidRendering` module with:
-   - `FLAVOR_PUBID_MAP` mapping document class names to pubid modules
-   - `parse_pubid(docidentifier_string)` — flavor-aware pubid parsing
-   - `pubid_to_html(identifier)` — renders to semantic HTML with CSS classes
-   - `resolve_pubid_module` — auto-detects flavor from renderer class
-4. Wired into `BaseRenderer` via `include PubidRendering`
-5. Refactored `render_bibitem_content` in `standard_renderer.rb` to try pubid first
-6. Created specs in `pubid_rendering_spec.rb`
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/07-replace-relaton-models-with-relaton-bib.md

@@ -1,39 +0,0 @@
- # 07 — Integrate relaton-bib library (partially complete)
-
-## Status
-- **Done**: relaton-bib dependency added, 4 models replaced via inheritance, `require` at module level
-- **Blocked**: Most models have incompatible XML schemas (different attribute names/types, different XML mappings)
-
-## What was done
-1. Added `relaton-bib ~> 2.1` to gemspec dependency
-2. Added `require "relaton/bib"` to `lib/metanorma/document/relaton.rb`
-3. Replaced 4 models with inheritance from relaton-bib:
-   - `Phone` < `::Relaton::Bib::Phone` (exact match)
-   - `PriceType` < `::Relaton::Bib::Price` (exact match)
-   - `BibItemLocality` < `::Relaton::Bib::Locality` (exact match)
-   - `Edition` < `::Relaton::Bib::Edition` (inherits + adds `language` attribute)
-
-## Why most models can't be directly replaced
-The 53 relaton models in our project have different XML schemas from relaton-bib's models:
-
-| Difference | Our models | relaton-bib |
-|---|---|---|
-| Attribute names | `on` (BibliographicDate), `bib_locality` (LocalityStack), `validity_begins` (ValidityType) | `at`, `locality`, `begins` |
-| Attribute types | `Components::DataTypes::*` throughout | `LocalizedString`, `LocalizedMarkedUpString` |
-| XML mapping | `map_attribute` for medium, `map_all_content` for logo | `map_element` for medium, `map_element "image"` for logo |
-| Extra attributes | `language` on Edition, `id` on DocumentIdentifier, `stage_abbreviation` on DocumentStatus | Not present |
-| Mixed content | Used in TypedTitleString (em/fn/stem/strong/sub/sup/tt/variant) | Plain content |
-| Model nesting | `CopyrightOwner` wraps `Organization` | `Contributor` as owner |
-
-A full replacement requires updating all 86 consuming references and adapting to relaton-bib's API. This is a separate project-level migration.
-
-## Remaining work for full migration
-1. Update consuming code (86 references) to use relaton-bib attribute names
-2. For models with extra attributes: inherit from relaton-bib and add extras
-3. For models with structural differences: create adapter classes
-4. Remove `lib/metanorma/document/relaton/` once fully migrated
-5. Update autoload configuration
-6. Integration specs for relaton-bib model usage
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/08-refactor-renderer-architecture.md

@@ -1,25 +0,0 @@
-# 08 — Refactor renderer architecture for OCP and DRY — DONE
-
-### Completed decomposition (Phase 1)
-BaseRenderer originally included three concern modules:
-- `InlineRendering` (~590 lines, 39 methods)
-- `BlockRendering` (~295 lines, 24 methods)
-- `SectionRendering` (~90 lines, 8 methods)
-
-### Completed composition (Phase 2 — TODO 13)
-Module includes replaced with composition. Each module became a standalone class:
-- `Renderers::InlineRenderer` at `lib/metanorma/html/renderers/inline_renderer.rb`
-- `Renderers::BlockRenderer` at `lib/metanorma/html/renderers/block_renderer.rb`
-- `Renderers::SectionRenderer` at `lib/metanorma/html/renderers/section_renderer.rb`
-- `Renderers::PubidRenderer` at `lib/metanorma/html/renderers/pubid_renderer.rb`
-
-BaseRenderer is now a thin coordinator with delegation wrappers for backward compatibility.
-Old concern modules at `lib/metanorma/html/concerns/` are no longer referenced and can be removed.
-
-### Remaining enhancements
-- Publisher metadata (flavor_publishers, flavor_publisher_name, publisher_logo_map) duplicated across 12+ flavor renderers. See TODO 11 for config-driven migration.
-- Config-driven section ordering. See TODO 14.
-- Theme directories per flavor. See TODO 15.
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/09-eliminate-code-smells.md

@@ -1,14 +0,0 @@
-# 09 — Eliminate code smells and enforce project constraints — DONE
-
-## Fixed
-- `respond_to?` duck-typing eliminated from inline_rendering.rb (replaced with `is_a?`)
-- `tag()` helper removed from base_renderer (replaced with Liquid `_element.html.liquid`)
-- All `@output <<` raw HTML generation eliminated
-- `method_missing` + `respond_to_missing?` eliminated from RendererContext (replaced with explicit `def` methods)
-- `public_send(attr)` in boilerplate_to_xml replaced with explicit `collect_boilerplate_part` helper
-- `public_send(setter)` in Theme.load is acceptable — setter list validated via `VALID_KEYS`/`SETTERS` constants
-- `instance_variable_get`/`instance_variable_set` eliminated from Drops and Component::Base (replaced with `OutputProxy` wrapper)
-- `# frozen_string_literal: true` added to all 48 inline component files
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/10-comprehensive-spec-coverage.md

@@ -1,24 +0,0 @@
- # 10 — Comprehensive spec coverage for HTML rendering pipeline — DONE
-
-## Status
-All HTML renderer specs use real model instances (zero doubles). Coverage spans theme loading, config-driven ordering, composition, pubid, metadata, CSS generation, and Liquid templates.
-
-## Spec count
-- Current: 159+ examples passing (0 failures) — ~40 pre-existing moxml failures excluded (upstream lutaml-model issue)
-
-## Spec files
-1. `theme_spec.rb` — 111 specs: defaults, all 13 flavor loading, publisher metadata, directory-based themes, lutaml-model schema validation
-2. `config_metadata_spec.rb` — 8 specs: theme auto-resolution, publisher/logo config from YAML
-3. `config_preface_spec.rb` — 8 specs: config-driven preface ordering (ordered mode, wrapped mode, clause filtering, delegation) using real IsoPreface models
-4. `composition_spec.rb` — 10 specs: sub-renderer composition, delegation wrappers, theme resolution using real IsoClauseSection models
-5. `pubid_rendering_spec.rb` — 3 specs: pubid parsing and HTML generation via composition using real IsoDocument::Root
-6. `base_renderer_spec.rb` — 19 specs: escape_html, element_attrs, utility methods
-7. `liquid_templates_spec.rb` — 62 specs: all 48 templates + 12 individual template tests
-8. `relaton_bib_spec.rb` — relaton-bib model inheritance verification
-
-## Key decisions
-- **Zero doubles**: All specs use real lutaml-model instances (IsoPreface, IsoClauseSection, IsoForewordSection, IsoDocument::Root, Theme)
-- **Zero instance_variable_set**: Only used in pubid_rendering_spec for setting @document (coordinator's required state) — acceptable for test setup
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. Never use private send methods (breaks encapsulation), instance_variable_set/get, never use respond_to? (poor typing). NEVER use RSpec doubles — use real model instances.

data/TODO.finalize/11-config-driven-flavor-metadata.md

@@ -1,20 +0,0 @@
-# 11 — Config-driven flavor metadata: eliminate boilerplate renderers — DONE
-
-## What was done
-All 13 theme YAML files contain publisher metadata:
-```yaml
-publishers:
-  - "ISO"
-publisher_name: "ISO"
-logos:
-  "ISO": "iso-logo.svg"
-```
-
-BaseRenderer reads publishers/logos from theme via `theme.publishers`, `theme.publisher_name`, `theme.logos`. No renderer code overrides these.
-
-10 flavor renderers are empty shells (0 methods, just inherit IsoRenderer). They exist because `Generator` maps document classes to renderer classes, but all customization comes from theme YAML config.
-
-Theme auto-resolves from document type via `FLAVOR_MAP` — no manual `theme` override needed in any renderer.
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/12-add-frozen-string-literal.md

@@ -1,6 +0,0 @@
-# 12 — Add frozen_string_literal to all Ruby files — DONE
-
-All `lib/` and `spec/` Ruby files already have `# frozen_string_literal: true` on line 1. No changes needed.
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/13-extract-composition-from-god-class.md

@@ -1,96 +0,0 @@
-# 13 — Extract module includes into composition — DONE
-
-## Problem
-BaseRenderer is a God class with 180+ public methods from 4 mixed-in modules:
-- `InlineRendering` (~590 lines, 39 methods)
-- `BlockRendering` (~295 lines, 24 methods)
-- `SectionRendering` (~90 lines, 8 methods)
-- `PubidRendering` (~55 lines, 2 methods)
-
-Module includes break OCP and encapsulation — all module methods become public on the single class, making it impossible to reason about responsibilities in isolation.
-
-## Architecture
-
-Replace `include` with composition. Each module becomes a standalone class that receives a reference to the coordinator for cross-concern calls:
-
-```
-BaseRenderer (coordinator, ~50 methods)
-  ├── InlineRenderer (inline elements, 39 methods)
-  ├── BlockRenderer (block elements, 24 methods)
-  ├── SectionRenderer (sections, 8 methods)
-  └── PubidRenderer (pubid parsing, 2 methods)
-```
-
-### Cross-concern dependencies (one-way, clean extraction)
-
-InlineRenderer needs from coordinator:
-- `escape_html`, `safe_attr`, `element_attrs`, `capture_output`, `render_liquid`
-- `render_paragraph`, `render_inline_element` (recursive dispatch)
-- `@output`, `@footnote_collector`, `@index_term_collector`
-
-BlockRenderer needs from coordinator:
-- `escape_html`, `safe_attr`, `element_attrs`, `capture_output`, `render_liquid`
-- `render_mixed_inline`, `render_inline_element`, `render_mixed_content_in_order`
-- `walk_ordered`, `block_element?`, `render` (recursive dispatch)
-- `@output`, `renderer_context`
-
-SectionRenderer needs from coordinator:
-- `escape_html`, `safe_attr`, `element_attrs`, `capture_output`, `render_liquid`
-- `walk_ordered`, `render`, `render_note`, `extract_plain_text`
-- `@output`
-
-PubidRenderer needs from coordinator:
-- `escape_html`, `flavor_name`
-
-### Implementation plan
-
-1. Create `InlineRenderer` class at `lib/metanorma/html/renderers/inline_renderer.rb`
-   - Receives `coordinator` in constructor
-   - Moves all methods from `InlineRendering` module
-   - Delegates shared utility calls to coordinator
-2. Create `BlockRenderer` class at `lib/metanorma/html/renderers/block_renderer.rb`
-   - Same pattern
-3. Create `SectionRenderer` class at `lib/metanorma/html/renderers/section_renderer.rb`
-   - Same pattern
-4. Create `PubidRenderer` class at `lib/metanorma/html/renderers/pubid_renderer.rb`
-   - Same pattern
-5. Update `BaseRenderer` to instantiate sub-renderers and delegate
-6. Update `RendererContext` to delegate through coordinator's sub-renderers
-7. Update all flavor renderers (IsoRenderer, StandardRenderer, etc.) for new API
-8. Update all Drop classes that call `renderer.method_name`
-9. Ensure all existing specs pass
-
-### Delegation pattern
-
-```ruby
-class BaseRenderer
-  attr_reader :inline_renderer, :block_renderer, :section_renderer, :pubid_renderer
-
-  def initialize
-    @inline_renderer = InlineRenderer.new(self)
-    @block_renderer = BlockRenderer.new(self)
-    @section_renderer = SectionRenderer.new(self)
-    @pubid_renderer = PubidRenderer.new(self)
-    # ...
-  end
-
-  # Delegate for backward compatibility during migration
-  def render_paragraph(...) = @block_renderer.render_paragraph(...)
-  def render_em(...) = @inline_renderer.render_em(...)
-  # etc.
-end
-```
-
-### Flavor renderers
-
-Sub-renderers can be extended per flavor:
-```ruby
-class IsoSectionRenderer < SectionRenderer
-  def render_preface(preface, **)
-    # ISO-specific preface ordering
-  end
-end
-```
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/14-config-driven-section-ordering.md

@@ -1,31 +0,0 @@
-# 14 — Config-driven preface and clause ordering — DONE
-
-## What was done
-
-### Theme config attributes added:
-- `preface_order` — array of section names, controls rendering order (default: `foreword introduction abstract clause acknowledgements executivesummary`)
-- `preface_wrap` — boolean, wraps preface content in a container div with heading (default: `false`)
-- `clause_order` — array of section names for clause ordering (default: `sections annex bibliography indexsect`)
-- `toc_filter_types` — array of clause types to exclude from preface rendering (default: `[]`)
-
-### All 13 theme YAML files updated:
-- ISO, IEC, IEEE, IETF, ITU, IHO, CC, BIPM, OIML, PDFA, Ribose, ICC: default ordering
-- OGC: `preface_order: [clause]`, `preface_wrap: true`, `toc_filter_types: [toc]`
-
-### Code changes:
-- `Theme` — added `preface_order`, `preface_wrap`, `clause_order`, `toc_filter_types` to VALID_KEYS, attr_accessor, and defaults
-- `SectionRenderer` — config-driven `render_preface` reads from theme, delegates to `render_ordered_preface` or `render_wrapped_preface` based on `preface_wrap`
-- `BaseRenderer` — added `render_preface` delegation to section_renderer
-- `IsoRenderer` — deleted hardcoded `render_preface` method (config-driven version replaces it)
-- `OgcRenderer` — deleted hardcoded `render_preface` override (now empty shell, all behavior from YAML)
-- Template `_ogc_preface.html.liquid` renamed to `_wrapped_preface.html.liquid` (generic name)
-
-### Specs added:
-- `config_preface_spec.rb` — 8 specs covering ordered mode, wrapped mode, clause filtering, and delegation
-- `theme_spec.rb` — 4 specs for section ordering defaults and OGC overrides
-
-### Key principle enforced:
-No flavor-specific knowledge (no "ogc", no hardcoded ordering) in generic renderer code. All behavior comes from theme YAML config.
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/15-theme-directories-per-flavor.md

@@ -1,46 +0,0 @@
-# 15 — Theme directories per flavor with data-centric config — DONE
-
-## What was done
-
-### Theme class changes:
-- Added `theme_dir` attribute (set when loaded from directory, nil for flat file themes)
-- `Theme.load(flavor)` now checks for directory format first (`data/themes/{flavor}/theme.yaml`), falls back to flat file (`data/themes/{flavor}.yaml`)
-- Extracted `from_file`, `from_directory`, `apply_overrides` class methods for clean separation
-- Added `theme_templates_dir` — returns `{theme_dir}/templates/` if it exists
-- Added `theme_assets_dir` — returns `{theme_dir}/assets/` if it exists
-- Added `theme_css_path` — returns `{theme_dir}/custom.css` if it exists
-- Added `resolve_template(template_name)` — checks flavor templates dir first, falls back to shared templates
-- Added `resolve_asset(filename)` — checks flavor assets dir, returns nil if not found
-
-### BaseRenderer changes:
-- `render_liquid` uses `theme.resolve_template(template_name)` instead of hardcoded `File.join(TEMPLATES_ROOT, ...)`
-- `load_logo_svg` checks `theme.resolve_asset(filename)` before shared `LOGO_DIR`
-- `build_styles` appends `theme.theme_css_path` content if present
-
-### Directory-based theme structure (opt-in):
-```
-data/themes/
-  iso.yaml              # flat file — still works as before
-  ogc.yaml              # flat file — still works as before
-  {flavor}/             # directory format — new support
-    theme.yaml          # palette, fonts, layout, ordering, publisher metadata
-    custom.css          # per-flavor CSS overrides (optional)
-    templates/          # per-flavor Liquid template overrides (optional)
-      _cover.html.liquid
-    assets/             # per-flavor assets: logos, images (optional)
-      {flavor}-logo.svg
-```
-
-### Backward compatibility:
-- All 13 existing flat YAML theme files continue to work unchanged
-- `theme_dir` is nil for flat-file themes, so resolution always falls through to shared paths
-- No migration needed — directory format is opt-in
-
-### Specs added:
-- 12 new specs in `theme_spec.rb` covering directory loading, template/asset/CSS resolution, backward compat
-
-### Future consideration:
-When theme config moves to per-flavor gems, `Theme.load` can be extended to search gem data directories. The API (`theme.resolve_template`, `theme.resolve_asset`, etc.) stays the same — only the path resolution changes.
-
-## Code quality requirements
-Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).