hlsv 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7295d19e11dcf4c08317e5549598438fb5a27914c7ea950bb1c71d4e1e94f4a4
-  data.tar.gz: 4150f90f58274c3bba610afd96379d130ee81338243547574ac0c40a4d04469a
+  metadata.gz: f3b17a6ed8bef54db026c08b70fe32e9dde8f9911c8e6369729f182766a39f5d
+  data.tar.gz: b7d0a4f7b54af98bea7b745da32e0176a24cf8f4f48778dfe11e7fa316d7b43e
 SHA512:
-  metadata.gz: 6fbf1ef581651af787a0db80415a5dbbcb1099cf9dc89885aa26dfafd80e94d52329dd75994a0c718949ff3e39237596c1d3f9775d3108062b6505489e01218a
-  data.tar.gz: 386d33f35bd9b465f08c0b65379da7e881885953a01a4ad7372a0da23d5735cd0775efa7b310973b17fb9bfac603f0627b6d289dd0a24d250ac9e290c25381a0
+  metadata.gz: 1cb8f37f4361669ab689100d4ae1bbc3d4f4a0921ac8b4dd89ef1964eed361c8f85fd0327a8c9768e77e5e62c7e73a8a7872bdd269afb9d6fc4c31c797831e67
+  data.tar.gz: e2b4b360a4b825fdefb4a6c16ceb8f643a2e26871c4f525c5dec1b29a9cd224161ac8121d10bb61eb87cc93f8b10fba6b2df960f7482d093c0964ffcb9e8d10c

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
-## 1.0.0 (2026-02-23)
-- Initial release
-```
+All notable changes to this project are documented here.
+
+## [2.0.0] - 2026-08-31
+
+### Changed
+- Complete refactor of the application architecture: the monolithic `web_app.rb` was split into modular components
+  - `analysis_registry.rb`,
+  - `analysis_runner.rb`,
+  - `config_manager.rb`,
+  - `path_guard.rb`,
+  - `url_helper.rb`
+- Frontend `app.js` split into ES modules with `app.js` as the entry point re-exposing functions on `window` for inline `onclick` handlers in the ERB views:
+  - `config.js`,
+  - `analysis.js` ,
+  - `results.js`,
+  - `browser.js`,
+  - `utils.js`
+- `styles.css` restructured into:
+  - `css/base/` (reset, typography, layout),
+  - `css/components/` (header, footer, forms, buttons, status, file-tree),
+  - `css/features/` (file-browser modal, csv-table),
+  - `css/responsive/`,
+  - and `css/accessibility/`
+  , assembled via `@import` in `css/styles.css`
+- `report.erb` status boxes (info/warning/error/success) harmonized with the app's `status.css` palette, with text and TOC link colors matched to border colors for stronger contrast
+
+### Added
+- favicon.ico
+
+### Removed / Breaking
+- Calls to `abort`/`exit` replaced with `raise Hlsv::Error`: code relying on process-exit behavior (e.g. catching `SystemExit`) will need to catch `Hlsv::Error` instead
+- `mon_script.rb` renamed to `analysis_runner.rb`
+- `find_keys.rb` renamed to `sdtm_validation.rb`
+- `report_template.erb` renamed to `report.erb`
+
+## [1.0.0] - 2026-02-23
+
+- Initial release as a Ruby gem
+- Modern responsive web interface
+- Excel export with README sheet
+- ASCII validation
+- Define.xml key verification
+- Natural key discovery
+- Mobile responsive design

data/README.md

@@ -6,7 +6,7 @@
 An open-source SDTM structural validation tool for clinical data teams.
 
 [![Gem Version](https://img.shields.io/gem/v/hlsv.svg)](https://rubygems.org/gems/hlsv)
-![Ruby](https://img.shields.io/badge/ruby-%3E%3D3.0-red.svg)
+![Ruby](https://img.shields.io/badge/ruby-%3E%3D4.0-red.svg)
 ![License](https://img.shields.io/badge/license-GNU%20AGPLv3-green.svg)
 
 ---
@@ -52,7 +52,7 @@ All processing is performed locally, ensuring full data confidentiality.
 
 ## 🔧 Prerequisites
 
-- **Ruby** >= 3.0
+- **Ruby** >= 4.0
 - **RubyGems** (bundled with Ruby)
 
 All gem dependencies are installed automatically.
@@ -115,7 +115,6 @@ in the directory where you launch `hlsv`.
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `study_name` | string | Unique identifier for your study |
-| `output_type` | string | Output format: `csv` (web interface) |
 | `output_directory` | string | Directory to save duplicate files |
 | `data_directory` | string | Path to your `.xpt` dataset files |
 | `define_path` | string | Path to `define.xml`; use `"-"` to skip |
@@ -132,7 +131,6 @@ in the directory where you launch `hlsv`.
 
 ```yaml
 study_name: "MY_STUDY_001"
-output_type: "csv"
 output_directory: "duplicates"
 data_directory: "/path/to/datasets"
 define_path: "/path/to/define.xml"
@@ -205,24 +203,41 @@ first column, with alternating row colors for visual clarity.
 ```
 hlsv/
 ├── bin/
-│   └── hlsv                    # Executable — starts the server
+│   └── hlsv                     # Executable — starts the server
 ├── lib/
-│   ├── hlsv.rb                 # Entry point — loads all components
+│   ├── hlsv.rb                  # Entry point — loads all components
 │   └── hlsv/
-│       ├── version.rb          # Gem version
-│       ├── web_app.rb          # Sinatra web application (routes, helpers)
-│       ├── mon_script.rb       # Orchestration layer
-│       ├── find_keys.rb        # Analysis engine
-│       ├── html2word.rb        # HTML to DOCX converter
-│       └── xpt.rb              # XPT file reader
-├── views/                      # ERB templates
-│   ├── index.erb               # Main interface
-│   ├── csv_view.erb            # CSV viewer
-│   └── report_template.erb     # HTML report template
-├── public/                     # Static assets
-│   ├── app.js
-│   ├── styles.css
-│   ├── styles_csv.css
+│       ├── version.rb           # Gem version
+│       ├── web_app.rb           # Sinatra web application (routes, helpers)
+│       ├── config_manager.rb    # Configuration loading/saving
+│       ├── analysis_registry.rb # In-memory fallback store for completed analyses, keyed by study name
+│       ├── path_guard.rb        # Path traversal protection
+│       ├── url_helper.rb        # URL building/parsing helpers
+│       ├── analysis_runner.rb   # Orchestration layer
+│       ├── sdtm_validation.rb   # Analysis engine
+│       ├── html2word.rb         # HTML to DOCX converter
+│       └── xpt.rb               # XPT file reader
+├── views/                       # ERB templates
+│   ├── index.erb                # Main interface
+│   ├── csv_view.erb             # CSV viewer
+│   └── report.erb               # HTML report template
+├── public/                      # Static assets
+│   ├── js/
+│   │   ├── app.js                   # Entry point — re-exposes functions on window
+│   │   ├── config.js
+│   │   ├── analysis.js
+│   │   ├── results.js
+│   │   ├── browser.js
+│   │   └── utils.js
+│   ├── css/
+│   │   ├── styles.css           # Assembles all partials via @import for index.erb
+│   │   ├── styles_csv.css       # Assembles all partials via @import for csv_view.erb
+│   │   ├── base/                # Reset, typography, layout
+│   │   ├── components/          # Header, footer, forms, buttons, status, file-tree
+│   │   ├── features/            # File-browser modal
+│   │   ├── responsive/
+│   │   └── accessibility/
+│   ├── favicon.ico
 │   └── logo.png
 ├── hlsv.gemspec                # Gem specification
 ├── Gemfile                     # Development dependencies
@@ -341,15 +356,7 @@ AdClin offers professional services related to this tool:
 
 ## 🗓️ Changelog
 
-### Version 1.0.0 (2026-02-23)
-
-- ✨ Initial release as a Ruby gem
-- 🎨 Modern responsive web interface
-- 📊 Excel export with README sheet
-- 🔍 ASCII validation
-- ✅ Define.xml key verification
-- 🔑 Natural key discovery
-- 📱 Mobile responsive design
+See [CHANGELOG.md](CHANGELOG.md) for the full version history.
 
 ---
 

data/lib/hlsv/analysis_registry.rb

@@ -0,0 +1,47 @@
+#######
+# Copyright (c) 2026 AdClin
+# Licensed under the GNU General Public License v3.0
+#######
+
+# frozen_string_literal: true
+
+module Hlsv
+  # Keeps completed SdtmValidation instances in memory, keyed by study name.
+  #
+  # Historically this was the only way to generate html/docx/excel reports
+  # on demand. Since '/proceed' now generates all report formats up front
+  # (see AnalysisRunner), this registry is no longer on the main path: it
+  # only serves as a fallback
+  #   - to regenerate a report format that failed to generate during
+  #     '/proceed' (see the per-format rescue blocks there), or
+  #   - for the per-dataset Excel export ('/report/:study/excel/:dataset'),
+  #     which is still generated on click rather than pre-generated.
+  #
+  # This is process-local, in-memory state: it is lost on server restart
+  # and is not shared across multiple server processes. That's an accepted
+  # trade-off for a single-user local tool. If this ever needs to survive
+  # restarts or run behind multiple workers, this is the place to swap the
+  # storage for something persistent.
+  class AnalysisRegistry
+    class << self
+      def store(study_name, engine)
+        mutex.synchronize { engines[study_name] = engine }
+      end
+
+      def fetch!(study_name)
+        mutex.synchronize { engines[study_name] } ||
+          raise(Hlsv::Error, "No analysis found in memory for '#{study_name}'. Please re-run the analysis.")
+      end
+
+      private
+
+      def engines
+        @engines ||= {}
+      end
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+    end
+  end
+end

data/lib/hlsv/analysis_runner.rb

@@ -0,0 +1,193 @@
+# Copyright (c) 2026 AdClin
+# Licensed under the GNU Affero General Public License v3.0 or later.
+# See the LICENSE file for details.
+
+# analysis_runner.rb
+# Orchestration layer between the web interface (web_app.rb) and the analysis engine (sdtm_validation.rb)
+
+require_relative 'sdtm_validation'
+require_relative 'analysis_registry'
+
+module Hlsv
+module AnalysisRunner
+  # Execute the complete analysis workflow.
+  #
+  # Note: this only runs the analysis and keeps the resulting engine in
+  # memory (see AnalysisRegistry). It does NOT generate any html/docx/excel
+  # report - those are generated on demand, only when the user clicks the
+  # corresponding button in the UI (see web_app.rb '/report/*' routes).
+  #
+  # @param config [Hash] Configuration parameters from the web interface
+  # @return [Hash] Detailed execution results including steps, files, and statistics
+  def self.run(config)
+    steps = []
+    temp_config = 'temp_config.yaml'
+
+    begin
+      # ========================================
+      # STEP 1: Configuration Validation
+      # ========================================
+      steps << {
+        step: 1,
+        name: "Configuration validation",
+        status: "in_progress"
+      }
+      puts "=" * 60
+      puts "\nStep 1/3: Configuration validation"
+
+      # Prefix study_name with "hlsv_results/" to create folders in hlsv_results/ directory
+      config_with_results = config.dup
+      original_study_name = config['study_name']
+      config_with_results['study_name'] = "hlsv_results/#{original_study_name}"
+
+      # Create temporary config file for SdtmValidation
+      File.write(temp_config, config_with_results.to_yaml)
+
+      # Initialize the engine (web_mode enables logo/base64 embedding etc. in later reports)
+      sv = SdtmValidation.new(temp_config, web_mode: true, verbose: false)
+
+      steps[0][:status]  = "completed"
+      steps[0][:message] = "Configuration validated successfully"
+
+      # ========================================
+      # STEP 2: Analysis Execution
+      # ========================================
+      steps << {
+        step: 2,
+        name: "Analysis execution",
+        status: "in_progress"
+      }
+      puts "\nStep 2/3: Analysis execution"
+
+      sv.validate
+
+      steps[1][:status]  = "completed"
+      steps[1][:message] = "Analysis completed successfully"
+
+      # ========================================
+      # STEP 3: Report Generation
+      # ========================================
+      # Generate all report formats up front so they're guaranteed present on
+      # disk (needed e.g. by "Download as ZIP"), even if the server restarts
+      # before the user clicks an individual '/report/*' button.
+      # Each format is generated independently: a failure on one (e.g. missing
+      # HTML template) must not block the others or fail the whole analysis,
+      # since the analysis itself already succeeded at this point.
+      steps << {
+        step: 3,
+        name: "Report generation",
+        status: "in_progress"
+      }
+      puts "\nStep 3/3: Report generation"
+
+      report_errors = []
+
+      begin
+        sv.report.html
+      rescue => e
+        puts "Warning: HTML report generation failed: #{e.message}"
+        report_errors << "html: #{e.message}"
+      end
+
+      begin
+        sv.report.docx
+      rescue => e
+        puts "Warning: Word report generation failed: #{e.message}"
+        report_errors << "docx: #{e.message}"
+      end
+
+      begin
+        sv.report.excel # no-op if no duplicates found
+      rescue => e
+        puts "Warning: Excel report generation failed: #{e.message}"
+        report_errors << "excel: #{e.message}"
+      end
+
+      if report_errors.empty?
+        steps[2][:status]  = "completed"
+        steps[2][:message] = "Reports generated successfully"
+      else
+        steps[2][:status]  = "completed"
+        steps[2][:message] = "Reports generated with #{report_errors.size} warning#{'s' if report_errors.size > 1} (see details below)"
+      end
+
+      # ========================================
+      # Keep the engine in memory for on-demand report *re*-generation
+      # (per-dataset excel exports, or regenerating after a manual fix)
+      # ========================================
+      AnalysisRegistry.store(original_study_name, sv)
+
+      # ========================================
+      # Post-Processing: Save Reference Config File
+      # ========================================
+      # Move the temp config file to the study directory for reference.
+      config_destination = "hlsv_results/#{original_study_name}/config.yaml"
+      File.write(config_destination, config.to_yaml) if Dir.exist?(File.dirname(config_destination))
+      File.delete(temp_config) if File.exist?(temp_config)
+
+      puts "All steps completed successfully"
+      puts "=" * 60
+
+      build_result_summary(sv: sv, steps: steps, original_study_name: original_study_name, report_errors: report_errors)
+
+    rescue => e
+      handle_execution_error(
+        error: e,
+        steps: steps,
+        temp_config: temp_config
+      )
+    end
+  end
+
+  private
+
+  # Build a comprehensive result summary. Note: no report path is returned
+  # here since nothing has been generated yet - the front-end uses
+  # `study_name` and `datasets_with_duplicates` to know which '/report/*'
+  # buttons to render.
+  def self.build_result_summary(sv:, steps:, original_study_name:, report_errors:)
+    ds_with_issues = sv.datasets.values.select do |ds|
+      ds.data_duplicate_file.any? || !ds.define_duplicate_file.to_s.empty?
+    end
+
+    invalid_ascii  = sv.datasets.values.select { |ds| ds.non_ascii_values&.any? }.map(&:name)
+    invalid_define = sv.datasets.values.select { |ds| ds.define_status == false }.map(&:name)
+
+    {
+      message: "Analysis completed successfully",
+      steps: steps,
+
+      study_name: original_study_name,
+      output_directory: sv.dir_out.split('/')[1..].join('/'),
+
+      analyzed_dataset_count: sv.datasets.size,
+      datasets_with_duplicates: ds_with_issues.map(&:name),
+
+      # Non-fatal report generation failures (html/docx/excel), if any -
+      # the analysis itself succeeded regardless
+      report_warnings: report_errors,
+
+      invalid_dataset_summary: {
+        invalid_dataset: ds_with_issues.size,
+        invalid_ascii:  invalid_ascii.empty?  ? nil : invalid_ascii.join(', '),
+        invalid_define: invalid_define.empty? ? nil : invalid_define.join(', '),
+        invalid_data:   ds_with_issues.empty? ? nil : ds_with_issues.map(&:name).join(', ')
+      }
+    }
+  end
+
+  # Handle execution errors gracefully
+  def self.handle_execution_error(error:, steps:, temp_config:)
+    current_step = steps.find { |st| st[:status] == "in_progress" }
+    if current_step
+      current_step[:status]  = "error"
+      current_step[:message] = error.message
+    end
+
+    File.delete(temp_config) if File.exist?(temp_config)
+
+    error_details = steps.map { |st| "#{st[:name]}: #{st[:status]}" }.join("\n")
+    raise "#{error.message}\n\nExecution steps:\n#{error_details}"
+  end
+end
+end

data/lib/hlsv/config_manager.rb

@@ -0,0 +1,125 @@
+#######
+# Copyright (c) 2026 AdClin
+# Licensed under the GNU General Public License v3.0
+#######
+
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Hlsv
+  # Centralizes everything related to config.yaml: field definitions,
+  # loading, saving, resetting, clearing and validating the configuration.
+  #
+  # Having a single FIELDS table avoids the previous situation where the
+  # same set of keys was duplicated across three different places
+  # (editable fields, required fields, empty-config template).
+  class ConfigManager
+    # key => { label:, required: }
+    # required: false means the field is editable/clearable but not
+    # mandatory for processing (e.g. excluded_ds).
+    FIELDS = {
+      'study_name'           => { label: 'Study name',           required: true  },
+      'output_directory'     => { label: 'Output directory',     required: true  },
+      'data_directory'       => { label: 'Data directory',       required: true  },
+      'define_path'          => { label: 'Define.xml path',      required: true  },
+      'excluded_ds'          => { label: 'Excluded datasets',    required: false },
+      'event_key'            => { label: 'Event key',            required: true  },
+      'intervention_key'     => { label: 'Intervention key',     required: true  },
+      'finding_key'          => { label: 'Finding key',          required: true  },
+      'finding_about_key'    => { label: 'Finding about key',    required: true  },
+      'ds_key'               => { label: 'DS key',               required: true  },
+      'relrec_key'           => { label: 'RELREC key',           required: true  },
+      'CO_key'               => { label: 'CO key',               required: true  },
+      'TA_key'               => { label: 'TA key',               required: true  },
+      'TE_key'               => { label: 'TE key',               required: true  },
+      'TI_key'               => { label: 'TI key',               required: true  },
+      'TS_key'               => { label: 'TS key',               required: true  },
+      'TV_key'               => { label: 'TV key',               required: true  }
+    }.freeze
+
+    EDITABLE_FIELDS  = FIELDS.keys.freeze
+    REQUIRED_FIELDS  = FIELDS.select { |_, v| v[:required] }.freeze
+
+    class << self
+      # Loads and returns config.yaml as a Hash. Halts with 500 if file is missing.
+      # `halt` is injected by the caller (Sinatra helper) since this class
+      # has no direct access to Sinatra's request context.
+      def load
+        return YAML.load_file(Hlsv.config_path) || {} if File.exist?(Hlsv.config_path)
+
+        raise "File config.yaml not found"
+      end
+
+      # Merges config_params into the existing config.yaml, for editable fields only.
+      # output_type is always forced to 'csv'.
+      def save(config_params)
+        current_config = File.exist?(Hlsv.config_path) ? (YAML.load_file(Hlsv.config_path) || {}) : {}
+
+        EDITABLE_FIELDS.each do |field|
+          current_config[field] = config_params[field] if config_params.key?(field)
+        end
+
+        current_config['output_type'] = 'csv'
+        File.write(Hlsv.config_path, current_config.to_yaml)
+        current_config
+      end
+
+      # Reloads config.yaml from config.default.yaml.
+      def reset
+        raise "File config.default.yaml not found in project root" unless File.exist?(Hlsv.default_config_path)
+
+        config_default = YAML.load_file(Hlsv.default_config_path)
+        File.write(Hlsv.config_path, config_default.to_yaml)
+        config_default
+      end
+
+      # Loads config.yaml from an arbitrary file picked by the user (via the
+      # config page's file browser). Same idea as reset above, just sourced
+      # from a chosen file instead of config.default.yaml.
+      def load_from(path)
+        raise "File not found: #{path}" unless File.exist?(path)
+
+        external_config = YAML.load_file(path)
+        raise "#{path} is not a valid configuration file" unless external_config.is_a?(Hash)
+
+        File.write(Hlsv.config_path, external_config.to_yaml)
+        external_config
+      end
+
+      # Resets all config fields to nil (keeps structure).
+      def clear
+        empty_config = EDITABLE_FIELDS.each_with_object({}) { |field, h| h[field] = nil }
+        empty_config['output_type'] = 'csv'
+
+        File.write(Hlsv.config_path, empty_config.to_yaml)
+        empty_config
+      end
+
+      # Validates the configuration hash.
+      # Checks all required fields are present and validates filesystem paths.
+      # Returns an array of error messages (empty if config is valid).
+      def validate(config)
+        errors = []
+
+        REQUIRED_FIELDS.each do |key, meta|
+          value = config[key]
+          errors << "#{meta[:label]} is empty" if value.nil? || value.to_s.strip.empty?
+        end
+
+        if config['data_directory'] && !config['data_directory'].to_s.strip.empty?
+          dir = config['data_directory'].gsub('\\', '/')
+          errors << "Data directory does not exist: #{dir}"      unless Dir.exist?(dir)
+          errors << "Directory is empty, no .xpt files detected" if Dir["#{dir}/*"].none? { |f| File.extname(f) == '.xpt' }
+        end
+
+        if config['define_path'] && config['define_path'] != '-'
+          errors << "Invalid path: #{config['define_path']}" unless File.exist?(config['define_path'])
+        end
+
+        config['output_type'] = 'csv'
+        errors
+      end
+    end
+  end
+end

data/lib/hlsv/html2word.rb

@@ -45,7 +45,7 @@ class RiReportParser
 
     downloaded_at = Time.now.strftime('Downloaded on %Y-%m-%d at %H:%M')
 
-    # Structure : <div class="info-box"><div flex><p>date</p><button>📄 Word</button></div></div>
+    # Structure: <div class="info-box"><div flex><p>date</p><button>📄 Word</button></div></div>
     # target <p> to ignore the button
     date_text = if info
       p_tag = info.at_css('p')
@@ -191,7 +191,7 @@ module OoxmlBuilder
     "<w:p><w:r><w:br w:type=\"page\"/></w:r></w:p>"
   end
 
-  # Construit le <w:pPr> avec les options communes
+  # Builds the <w:pPr> with the common options
   def self.build_ppr(opts = {})
     style        = opts[:style]
     align        = opts[:align]
@@ -209,7 +209,7 @@ module OoxmlBuilder
     "<w:pPr>#{inner}</w:pPr>"
   end
 
-  # Paragraphe générique
+  # Generic paragraph
   def self.paragraph(text, opts = {})
     sz    = opts[:sz]    || 20
     bold  = opts[:bold]  || false
@@ -224,13 +224,13 @@ module OoxmlBuilder
     "<w:p>#{ppr}<w:r><w:rPr>#{rpr}</w:rPr><w:t xml:space=\"preserve\">#{x(text)}</w:t></w:r></w:p>"
   end
 
-  # Paragraphe avec style Word nommé
+  # Paragraph with a named Word style
   def self.heading(text, opts = {})
     ppr = build_ppr(opts)
     "<w:p>#{ppr}<w:r><w:t xml:space=\"preserve\">#{x(text)}</w:t></w:r></w:p>"
   end
 
-  # Paragraphe coloré pour les statuts
+  # Colored paragraph for statuses
   def self.status_paragraph(text, opts = {})
     color = opts[:color] || '000000'
     ppr   = build_ppr(opts.merge(space_before: 0, space_after: 80))
@@ -239,7 +239,7 @@ module OoxmlBuilder
     "<w:p>#{ppr}<w:r><w:rPr>#{rpr}</w:rPr><w:t xml:space=\"preserve\">#{x(text)}</w:t></w:r></w:p>"
   end
 
-  # Item de liste à puces
+  # Bulleted list item
   def self.list_item(text, opts = {})
     color      = opts[:color]      || '000000'
     sz         = opts[:sz]         || 20
@@ -263,18 +263,18 @@ module OoxmlBuilder
     XML
   end
 
-  # ── Footer Word ────────────────────────────────────────────────────────────
-  # Deux zones séparées par une tabulation centrale/droite :
-  #   gauche  : titre du document
-  #   droite  : PAGE / NUMPAGES  (champs Word natifs)
+  # ── Word footer ────────────────────────────────────────────────────────────
+  # Two zones separated by a center/right tab stop:
+  #   left  : document title
+  #   right : PAGE / NUMPAGES  (native Word fields)
   #
-  # Les champs PAGE et NUMPAGES sont insérés via <w:fldChar> / <w:instrText>
-  # — mécanisme identique à la TOC, sans dépendance externe.
+  # The PAGE and NUMPAGES fields are inserted via <w:fldChar> / <w:instrText>
+  # - same mechanism as the TOC, with no external dependency.
   def self.footer_xml(doc_title)
     rpr_base = "<w:rFonts w:ascii=\"#{FONT}\" w:hAnsi=\"#{FONT}\" w:cs=\"#{FONT}\"/>" \
                "<w:sz w:val=\"18\"/><w:szCs w:val=\"18\"/><w:color w:val=\"666666\"/>"
 
-    # Champ PAGE
+    # PAGE field
     page_field = <<~XML
       <w:r><w:rPr>#{rpr_base}</w:rPr><w:fldChar w:fldCharType="begin"/></w:r>
       <w:r><w:rPr>#{rpr_base}</w:rPr><w:instrText xml:space="preserve"> PAGE </w:instrText></w:r>
@@ -283,7 +283,7 @@ module OoxmlBuilder
       <w:r><w:rPr>#{rpr_base}</w:rPr><w:fldChar w:fldCharType="end"/></w:r>
     XML
 
-    # Champ NUMPAGES
+    # NUMPAGES field
     numpages_field = <<~XML
       <w:r><w:rPr>#{rpr_base}</w:rPr><w:fldChar w:fldCharType="begin"/></w:r>
       <w:r><w:rPr>#{rpr_base}</w:rPr><w:instrText xml:space="preserve"> NUMPAGES </w:instrText></w:r>
@@ -315,7 +315,7 @@ module OoxmlBuilder
     XML
   end
 
-  # Page de couverture
+  # Cover page
   def self.cover_page(title:, date:, downloaded_at:)
     title_para = paragraph(title,
                            sz: 44, bold: true, color: '1F3864',
@@ -337,7 +337,7 @@ module OoxmlBuilder
     title_para + hr + date_para + downloaded_para + page_break
   end
 
-  # TOC sur sa propre page
+  # TOC on its own page
   def self.toc_field
     toc_title = heading('Table of Contents',
                         style: 'Heading1', space_before: 0, space_after: 160)
@@ -357,7 +357,7 @@ module OoxmlBuilder
     toc_title + toc_content + page_break
   end
 
-  # Corps du document
+  # Document body
   def self.document(blocks)
     paras = blocks.map do |b|
       m = b.meta
@@ -512,7 +512,7 @@ module OoxmlBuilder
     XML
   end
 
-  # Relations du document : styles, numbering, settings, header, footer
+  # Document relationships: styles, numbering, settings, header, footer
   def self.word_rels
     <<~XML
       <?xml version="1.0" encoding="UTF-8" standalone="yes"?>