llm-docs-builder 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac257dad79f49ed6993f784f8a28ee1e996e735fef4581449ad521ea9414a5d4
-  data.tar.gz: 29e1d2d578d57ea6f17aafca070c61b6161b6313d6614f0e4f798933ceae082d
+  metadata.gz: 2a55f2ba08f239388d3f4834df0c1caeef9c138278726b442f6533e000a3554c
+  data.tar.gz: 173e4950404e3a4b83bd5213520a29b5b6f70b374dd18c58a8374c9b5bf55b21
 SHA512:
-  metadata.gz: f82216cca621e942c0e6ad3d92aba5d099159cc9c0d10c1d010a85e2a740511103cebd0198c0056195775064853e749472dcb7f0939b8d3fda7753d291a5b0da
-  data.tar.gz: 31aa5737e215439b11a2e79d793dabb9ff342206b660a2ecd846920bc2f6501c3d5910da4cdc52ecfcfa9f7b9acef14213b17936edd23d86808c0bcb2f391952
+  metadata.gz: d8769c0a92e29025165900ff3a1c65b1acbd42b51b8f6402353c157dfd4755ddd84dce8fdb26c334d4cba456c04f83af322ceb9fb554aea4ff4ac3a5330f81c5
+  data.tar.gz: 305ea0aa8cc44144079988e4faf80125fbf765331d3801ec8273f183c9b77cbc1430bf5b10eba5b09f0068ca526c4bc2b5d8a90a48179583270de1f62df12f77

data/.github/workflows/ci.yml

@@ -23,19 +23,19 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
+          - '4.0'
           - '3.4'
           - '3.3'
-          - '3.2'
         include:
-          - ruby: '3.4'
+          - ruby: '4.0'
             coverage: 'true'
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
+        uses: ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f # v1.306.0
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
@@ -58,15 +58,32 @@ jobs:
     timeout-minutes: 5
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
+        uses: ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f # v1.306.0
         with:
-          ruby-version: '3.4.7'
+          ruby-version: '4.0.3'
           bundler-cache: true
       - name: Run yard-lint
         run: bundle exec yard-lint lib/
 
+  lostconf:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+      - name: Run lostconf
+        run: npx lostconf --fail-on-stale
+
   ci-success:
     name: CI Success
     runs-on: ubuntu-latest
@@ -74,6 +91,7 @@ jobs:
     needs:
       - specs
       - yard-lint
+      - lostconf
     steps:
       - name: Check all jobs passed
         if: |

data/.github/workflows/docker.yml

@@ -25,13 +25,13 @@ jobs:
       id-token: write
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6
         with:
           images: |
             mensfeld/llm-docs-builder
@@ -45,28 +45,28 @@ jobs:
             type=raw,value=latest,enable={{is_default_branch}}
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4
 
       - name: Login to Docker Hub
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Login to GitHub Container Registry
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build and push
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7
         with:
           context: .
           platforms: linux/amd64,linux/arm64

data/.github/workflows/push.yml

@@ -19,12 +19,12 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@d5126b9b3579e429dd52e51e68624dda2e05be25 # v1.267.0
+        uses: ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f # v1.306.0
         with:
           bundler-cache: false
 
@@ -32,4 +32,4 @@ jobs:
         run: |
           bundle install --jobs 4 --retry 3
 
-      - uses: rubygems/release-gem@1c162a739e8b4cb21a676e97b087e8268d8fc40b # v1.1.2
+      - uses: rubygems/release-gem@6317d8d1f7e28c24d28f6eff169ea854948bd9f7 # v1.2.0

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 3.2
+  TargetRubyVersion: 3.3
   NewCops: enable
   SuggestExtensions: false
 
@@ -11,38 +11,25 @@ Style/StringLiterals:
 
 Layout/LineLength:
   Max: 120
-  Exclude:
-    - 'lib/llms_txt/cli.rb'
 
 Metrics/ClassLength:
   Max: 200
-  Exclude:
-    - 'lib/llms_txt/cli.rb'
 
 Metrics/MethodLength:
   Max: 35
-  Exclude:
-    - 'lib/llms_txt/cli.rb'
 
 Metrics/AbcSize:
   Max: 40
-  Exclude:
-    - 'lib/llms_txt/cli.rb'
 
 Metrics/CyclomaticComplexity:
   Max: 15
-  Exclude:
-    - 'lib/llms_txt/config.rb'
 
 Metrics/PerceivedComplexity:
   Max: 15
-  Exclude:
-    - 'lib/llms_txt/config.rb'
 
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
-    - 'lib/llms_txt/cli.rb'
     - '*.gemspec'
 
 Style/FrozenStringLiteralComment:

data/.ruby-version

@@ -1 +1 @@
-3.4.7
+4.0.3

data/.yard-lint.yml

@@ -0,0 +1,275 @@
+# YARD-Lint Configuration
+# See https://github.com/mensfeld/yard-lint for documentation
+
+# Global settings for all validators
+AllValidators:
+  YardOptions:
+  - "--private"
+  - "--protected"
+  Exclude:
+  - .git/**/*
+  - vendor/**/*
+  - node_modules/**/*
+  - spec/**/*
+  FailOnSeverity: convention
+  MinCoverage: 99.0
+  DiffMode:
+    DefaultBaseRef:
+
+# Documentation validators
+Documentation/UndocumentedObjects:
+  Description: Checks for classes, modules, and methods without documentation.
+  Enabled: true
+  Severity: error
+  ExcludedMethods:
+  - initialize/0
+  - "/^_/"
+
+Documentation/UndocumentedMethodArguments:
+  Description: Checks for method parameters without @param tags.
+  Enabled: true
+  Severity: error
+
+Documentation/UndocumentedBooleanMethods:
+  Description: Checks that question mark methods document their boolean return.
+  Enabled: true
+  Severity: error
+
+Documentation/UndocumentedOptions:
+  Description: Detects methods with options hash parameters but no @option tags.
+  Enabled: true
+  Severity: error
+
+Documentation/MarkdownSyntax:
+  Description: Detects common markdown syntax errors in documentation.
+  Enabled: true
+  Severity: error
+
+Documentation/EmptyCommentLine:
+  Description: Detects empty comment lines at the start or end of documentation blocks.
+  Enabled: true
+  Severity: convention
+  EnabledPatterns:
+    Leading: true
+    Trailing: true
+
+Documentation/BlankLineBeforeDefinition:
+  Description: Detects blank lines between YARD documentation and method definition.
+  Enabled: true
+  Severity: convention
+  OrphanedSeverity: convention
+  EnabledPatterns:
+    SingleBlankLine: true
+    OrphanedDocs: true
+
+# Tags validators
+Tags/Order:
+  Description: Enforces consistent ordering of YARD tags.
+  Enabled: true
+  Severity: error
+  EnforcedOrder:
+  - param
+  - option
+  - return
+  - raise
+  - example
+
+Tags/InvalidTypes:
+  Description: Validates type definitions in @param, @return, @option tags.
+  Enabled: true
+  Severity: error
+  ValidatedTags:
+  - param
+  - option
+  - return
+
+Tags/TypeSyntax:
+  Description: Validates YARD type syntax using YARD parser.
+  Enabled: true
+  Severity: error
+  ValidatedTags:
+  - param
+  - option
+  - return
+  - yieldreturn
+
+Tags/MeaninglessTag:
+  Description: Detects @param/@option tags on classes, modules, or constants.
+  Enabled: true
+  Severity: error
+  CheckedTags:
+  - param
+  - option
+  InvalidObjectTypes:
+  - class
+  - module
+  - constant
+
+Tags/CollectionType:
+  Description: Validates Hash collection syntax consistency.
+  Enabled: true
+  Severity: error
+  EnforcedStyle: long
+  ValidatedTags:
+  - param
+  - option
+  - return
+  - yieldreturn
+
+Tags/TagTypePosition:
+  Description: Validates type annotation position in tags.
+  Enabled: true
+  Severity: error
+  CheckedTags:
+  - param
+  - option
+  EnforcedStyle: type_after_name
+
+Tags/ApiTags:
+  Description: Enforces @api tags on public objects.
+  Enabled: false
+  Severity: error
+  AllowedApis:
+  - public
+  - private
+  - internal
+
+Tags/OptionTags:
+  Description: Requires @option tags for methods with options parameters.
+  Enabled: true
+  Severity: error
+
+Tags/ExampleSyntax:
+  Description: Validates Ruby syntax in @example tags.
+  Enabled: true
+  Severity: warning
+
+Tags/RedundantParamDescription:
+  Description: Detects meaningless parameter descriptions that add no value.
+  Enabled: true
+  Severity: convention
+  CheckedTags:
+  - param
+  - option
+  Articles:
+  - The
+  - the
+  - A
+  - a
+  - An
+  - an
+  MaxRedundantWords: 6
+  GenericTerms:
+  - object
+  - instance
+  - value
+  - data
+  - item
+  - element
+  EnabledPatterns:
+    ArticleParam: true
+    PossessiveParam: true
+    TypeRestatement: true
+    ParamToVerb: true
+    IdPattern: true
+    DirectionalDate: true
+    TypeGeneric: true
+
+Tags/InformalNotation:
+  Description: Detects informal tag notation patterns like "Note:" instead of @note.
+  Enabled: true
+  Severity: warning
+  CaseSensitive: false
+  RequireStartOfLine: true
+  Patterns:
+    Note: "@note"
+    Todo: "@todo"
+    TODO: "@todo"
+    FIXME: "@todo"
+    See: "@see"
+    See also: "@see"
+    Warning: "@deprecated"
+    Deprecated: "@deprecated"
+    Author: "@author"
+    Version: "@version"
+    Since: "@since"
+    Returns: "@return"
+    Raises: "@raise"
+    Example: "@example"
+
+Tags/NonAsciiType:
+  Description: Detects non-ASCII characters in type annotations.
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+  - param
+  - option
+  - return
+  - yieldreturn
+  - yieldparam
+
+Tags/TagGroupSeparator:
+  Description: Enforces blank line separators between different YARD tag groups.
+  Enabled: false
+  Severity: convention
+  TagGroups:
+    param:
+    - param
+    - option
+    return:
+    - return
+    error:
+    - raise
+    - throws
+    example:
+    - example
+    meta:
+    - see
+    - note
+    - todo
+    - deprecated
+    - since
+    - version
+    - api
+    yield:
+    - yield
+    - yieldparam
+    - yieldreturn
+  RequireAfterDescription: false
+
+# Warnings validators - catches YARD parser errors
+Warnings/UnknownTag:
+  Description: Detects unknown YARD tags.
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownDirective:
+  Description: Detects unknown YARD directives.
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidTagFormat:
+  Description: Detects malformed tag syntax.
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidDirectiveFormat:
+  Description: Detects malformed directive syntax.
+  Enabled: true
+  Severity: error
+
+Warnings/DuplicatedParameterName:
+  Description: Detects duplicate @param tags.
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownParameterName:
+  Description: Detects @param tags for non-existent parameters.
+  Enabled: true
+  Severity: error
+
+# Semantic validators
+Semantic/AbstractMethods:
+  Description: Ensures @abstract methods do not have real implementations.
+  Enabled: true
+  Severity: error

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.13.0 (2026-05-11)
+- [Breaking] Dropped Ruby 3.2 support. Minimum required Ruby version is now 3.3.
+- [Fix] **Heading Nesting in Normalize Mode** — Fixed `normalize_headings` producing incorrect heading levels when same-level headings are nested under a parent.
+  - Consecutive same-level headings (e.g., two `##` headings) now correctly adjust the child's markdown level to be deeper than the parent's (e.g., `##` → `###`)
+  - Effective level formula: `max(parent_effective_level + 1, original_level)`
+  - ATX closing hashes (`## Title ##`) are now stripped from titles before building hierarchical paths
+- [Fix] **HTML-to-Markdown Section Nesting** — Headings inside nested `<section>` elements now receive adjusted markdown levels based on section nesting depth.
+  - `<h2>` inside a nested `<section>` under another `<section>` with its own `<h2>` is now correctly rendered as `###` instead of `##`
+
 ## 0.12.0 (2025-11-12)
 - [Feature] **HTML to Markdown Reverse Converter** — Added support for converting HTML content to markdown format.
   - Enables processing of HTML documentation sources

data/Dockerfile

@@ -4,7 +4,7 @@
 # Creates a minimal Docker image (~50MB) for running the CLI without Ruby installation
 
 # Stage 1: Builder
-FROM ruby:3.4-alpine AS builder
+FROM ruby:4.0-alpine AS builder
 
 # Install build dependencies
 RUN apk add --no-cache \
@@ -36,17 +36,24 @@ RUN bundle config set --local without 'development test' && \
 RUN gem build llm-docs-builder.gemspec
 
 # Stage 2: Runtime
-FROM ruby:3.4-alpine
+FROM ruby:4.0-alpine
 
-# Install runtime dependencies only
+# Install runtime dependencies and build tools for native extensions
 RUN apk add --no-cache \
     ca-certificates \
-    tzdata
+    tzdata \
+    libxml2 \
+    libxslt
 
-# Copy built gem and install it
+# Copy built gem and install it (needs build tools for nokogiri)
 COPY --from=builder /gem/llm-docs-builder-*.gem /tmp/
-RUN gem install /tmp/llm-docs-builder-*.gem --no-document && \
-    rm /tmp/llm-docs-builder-*.gem
+RUN apk add --no-cache --virtual .build-deps \
+    build-base \
+    libxml2-dev \
+    libxslt-dev && \
+    gem install /tmp/llm-docs-builder-*.gem --no-document && \
+    rm /tmp/llm-docs-builder-*.gem && \
+    apk del .build-deps
 
 # Set working directory for user files
 WORKDIR /workspace

data/Gemfile

@@ -6,9 +6,5 @@ gemspec
 
 group :development do
   gem 'pry'
-  gem 'pry-byebug'
   gem 'yard-lint'
 end
-
-group :test do
-end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    llm-docs-builder (0.12.0)
+    llm-docs-builder (0.13.0)
       nokogiri (~> 1.17)
       zeitwerk (~> 2.6)
 
@@ -9,48 +9,31 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
-    byebug (12.0.0)
     coderay (1.1.3)
-    date (3.5.0)
     diff-lcs (1.6.2)
     docile (1.4.1)
-    erb (5.1.3)
-    io-console (0.8.1)
-    irb (1.15.3)
-      pp (>= 0.6.0)
-      rdoc (>= 4.0.0)
-      reline (>= 0.4.2)
-    json (2.16.0)
+    io-console (0.8.2)
+    json (2.19.5)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     method_source (1.1.0)
-    nokogiri (1.18.10-x86_64-linux-gnu)
+    mini_portile2 (2.8.9)
+    nokogiri (1.19.3)
+      mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    parallel (1.27.0)
-    parser (3.3.10.0)
+    parallel (2.1.0)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
-    pp (0.6.3)
-      prettyprint
-    prettyprint (0.2.0)
-    prism (1.6.0)
-    pry (0.15.2)
+    prism (1.9.0)
+    pry (0.16.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    pry-byebug (3.11.0)
-      byebug (~> 12.0)
-      pry (>= 0.13, < 0.16)
-    psych (5.2.6)
-      date
-      stringio
+      reline (>= 0.6.0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.1)
-    rdoc (6.15.1)
-      erb
-      psych (>= 4.0.0)
-      tsort
-    regexp_parser (2.11.3)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
     reline (0.6.3)
       io-console (~> 0.5)
     rspec (3.13.2)
@@ -62,24 +45,24 @@ GEM
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.7)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.6)
-    rubocop (1.81.7)
+    rspec-support (3.13.7)
+    rubocop (1.86.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.47.1, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.1)
+    rubocop-ast (1.49.1)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
+      prism (~> 1.7)
     ruby-progressbar (1.13.0)
     simplecov (0.22.0)
       docile (~> 1.1)
@@ -87,26 +70,22 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    stringio (3.1.8)
-    tsort (0.2.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
-    unicode-emoji (4.1.0)
-    yard (0.9.37)
-    yard-lint (1.1.0)
-      irb
+    unicode-emoji (4.2.0)
+    yard (0.9.43)
+    yard-lint (1.5.1)
       yard (~> 0.9)
       zeitwerk (~> 2.6)
-    zeitwerk (2.7.3)
+    zeitwerk (2.7.5)
 
 PLATFORMS
-  x86_64-linux
+  ruby
 
 DEPENDENCIES
-  bundler (~> 2.0)
+  bundler
   llm-docs-builder!
   pry
-  pry-byebug
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (~> 1.0)
@@ -114,4 +93,4 @@ DEPENDENCIES
   yard-lint
 
 BUNDLED WITH
-   2.7.2
+   2.6.9

data/lib/llm_docs_builder/cli.rb

@@ -399,7 +399,6 @@ module LlmDocsBuilder
     end
 
     # Display version information
-    #
     def show_version
       puts "llm-docs-builder version #{LlmDocsBuilder::VERSION}"
     end

data/lib/llm_docs_builder/html_to_markdown_converter.rb

@@ -120,7 +120,8 @@ module LlmDocsBuilder
         text = collapsed_inline_for(element)
         return '' if text.empty?
 
-        "#{'#' * HEADING_LEVEL[tag]} #{text}"
+        effective_level = effective_heading_level(element, HEADING_LEVEL[tag])
+        "#{'#' * effective_level} #{text}"
       when 'blockquote'
         render_blockquote(element)
       when 'pre'
@@ -641,6 +642,39 @@ module LlmDocsBuilder
       out.join("\n\n")
     end
 
+    # Compute effective heading level adjusted for section nesting
+    #
+    # When HTML uses nested <section> elements with same-level headings,
+    # the inner headings should receive deeper markdown levels. The offset
+    # is calculated as the difference between the actual section ancestor
+    # count and the expected count for that heading tag (h1 expects 0
+    # sections, h2 expects 1, etc.), capped at heading level 6.
+    #
+    # @param element [Nokogiri::XML::Element] heading element
+    # @param base_level [Integer] HTML heading level (1-6)
+    # @return [Integer] effective markdown heading level (1-6)
+    def effective_heading_level(element, base_level)
+      depth = section_ancestor_count(element)
+      offset = [depth - (base_level - 1), 0].max
+      [base_level + offset, 6].min
+    end
+
+    # Count the number of <section> ancestor elements
+    #
+    # @param element [Nokogiri::XML::Element]
+    # @return [Integer] number of section ancestors
+    def section_ancestor_count(element)
+      count = 0
+      node = element.parent
+
+      while node
+        count += 1 if node.element? && node.name.downcase == 'section'
+        node = node.parent
+      end
+
+      count
+    end
+
     # Helpers
 
     # Normalize whitespace in text

data/lib/llm_docs_builder/output_formatter.rb

@@ -30,7 +30,7 @@ module LlmDocsBuilder
 
     # Format number with comma separators for readability
     #
-    # @param number [Integer] integer value
+    # @param number [Integer] value to format with comma separators
     # @return [String] formatted number with commas
     #
     # @example

data/lib/llm_docs_builder/text_compressor.rb

@@ -72,8 +72,8 @@ module LlmDocsBuilder
     # Removes common English stopwords that don't carry significant meaning.
     # Preserves code blocks, inline code, and technical terms.
     #
-    # WARNING: This is an aggressive optimization that may affect readability.
-    # Use with caution and test results carefully.
+    # @deprecated This is an aggressive optimization that may affect readability.
+    #   Use with caution and test results carefully.
     #
     # @param content [String] text to process
     # @return [String] text with stopwords removed

data/lib/llm_docs_builder/transformers/heading_transformer.rb

@@ -51,24 +51,36 @@ module LlmDocsBuilder
           next line if in_code_block
 
           # Match markdown headings (1-6 hash symbols followed by space and text)
-          heading_match = line.match(/^(#+)\s+(.+)$/)
+          # Supports optional ATX closing hashes (e.g., "## Title ##")
+          heading_match = line.match(/^(#+)\s+(.+?)(?:\s+#+)?\s*$/)
 
-          if heading_match && heading_match[1].count('#').between?(1, 6)
-            level = heading_match[1].count('#')
+          if heading_match && heading_match[1].length.between?(1, 6)
+            level = heading_match[1].length
             title = heading_match[2].strip
 
             # Update heading stack to current level
             heading_stack = heading_stack[0...level - 1]
-            heading_stack << title
+
+            # Compute the effective heading level. When same-level headings
+            # are nested under a parent (e.g., two consecutive ## headings),
+            # the child must receive a deeper markdown level so the output
+            # hierarchy is correct.
+            effective_level = if heading_stack.empty?
+                               level
+                             else
+                               [heading_stack.last[:effective_level] + 1, level].max
+                             end
+            effective_level = [effective_level, 6].min
+
+            heading_stack << { title: title, effective_level: effective_level }
 
             # Build hierarchical heading
             if level == 1
               # H1 stays as-is (top level)
               line
             else
-              # H2+ gets parent context
-              hierarchical_title = heading_stack.join(separator)
-              "#{'#' * level} #{hierarchical_title}\n"
+              hierarchical_title = heading_stack.map { |e| e[:title] }.join(separator)
+              "#{'#' * effective_level} #{hierarchical_title}\n"
             end
           else
             line

data/lib/llm_docs_builder/version.rb

@@ -2,5 +2,5 @@
 
 module LlmDocsBuilder
   # Current version of the LlmDocsBuilder gem
-  VERSION = '0.12.0'
+  VERSION = '0.13.0'
 end

data/llm-docs-builder.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
 
   spec.homepage = 'https://github.com/mensfeld/llm-docs-builder'
   spec.license = 'MIT'
-  spec.required_ruby_version = '>= 3.2'
+  spec.required_ruby_version = '>= 3.3'
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
   spec.metadata['homepage_uri'] = spec.homepage
@@ -38,7 +38,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'nokogiri', '~> 1.17'
   spec.add_dependency 'zeitwerk', '~> 2.6'
 
-  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop', '~> 1.0'

data/package-lock.json

@@ -0,0 +1,331 @@
+{
+  "name": "llm-docs-builder",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "llm-docs-builder",
+      "version": "1.0.0",
+      "devDependencies": {
+        "lostconf": "0.4.0"
+      }
+    },
+    "node_modules/@nodelib/fs.scandir": {
+      "version": "2.1.5",
+      "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz",
+      "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@nodelib/fs.stat": "2.0.5",
+        "run-parallel": "^1.1.9"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/@nodelib/fs.stat": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz",
+      "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/@nodelib/fs.walk": {
+      "version": "1.2.8",
+      "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz",
+      "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@nodelib/fs.scandir": "2.1.5",
+        "fastq": "^1.6.0"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/braces": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
+      "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fill-range": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/chalk": {
+      "version": "5.6.2",
+      "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.2.tgz",
+      "integrity": "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^12.17.0 || ^14.13 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/chalk?sponsor=1"
+      }
+    },
+    "node_modules/commander": {
+      "version": "12.1.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
+      "integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/fast-glob": {
+      "version": "3.3.3",
+      "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.3.tgz",
+      "integrity": "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@nodelib/fs.stat": "^2.0.2",
+        "@nodelib/fs.walk": "^1.2.3",
+        "glob-parent": "^5.1.2",
+        "merge2": "^1.3.0",
+        "micromatch": "^4.0.8"
+      },
+      "engines": {
+        "node": ">=8.6.0"
+      }
+    },
+    "node_modules/fastq": {
+      "version": "1.20.1",
+      "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.20.1.tgz",
+      "integrity": "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "reusify": "^1.0.4"
+      }
+    },
+    "node_modules/fill-range": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",
+      "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "to-regex-range": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/glob-parent": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz",
+      "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "is-glob": "^4.0.1"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/is-extglob": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
+      "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/is-glob": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
+      "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-extglob": "^2.1.1"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/is-number": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz",
+      "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.12.0"
+      }
+    },
+    "node_modules/lostconf": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/lostconf/-/lostconf-0.4.0.tgz",
+      "integrity": "sha512-VNbUnirRU7uESqMHslIRHTcuyx/rr4OZK+L7EQXtYUe5PorBgqBYvPu+6xOr0CoUy4n34NNUKO6BBH6TgwwGTA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "chalk": "^5.3.0",
+        "commander": "^12.1.0",
+        "fast-glob": "^3.3.2",
+        "micromatch": "^4.0.8",
+        "smol-toml": "^1.3.0",
+        "yaml": "^2.5.0"
+      },
+      "bin": {
+        "lostconf": "dist/cli.js"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/merge2": {
+      "version": "1.4.1",
+      "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz",
+      "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/micromatch": {
+      "version": "4.0.8",
+      "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz",
+      "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "braces": "^3.0.3",
+        "picomatch": "^2.3.1"
+      },
+      "engines": {
+        "node": ">=8.6"
+      }
+    },
+    "node_modules/picomatch": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
+      "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/queue-microtask": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
+      "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/reusify": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.1.0.tgz",
+      "integrity": "sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "iojs": ">=1.0.0",
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/run-parallel": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz",
+      "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "queue-microtask": "^1.2.2"
+      }
+    },
+    "node_modules/smol-toml": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.6.1.tgz",
+      "integrity": "sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">= 18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/cyyynthia"
+      }
+    },
+    "node_modules/to-regex-range": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
+      "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-number": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=8.0"
+      }
+    },
+    "node_modules/yaml": {
+      "version": "2.8.4",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.4.tgz",
+      "integrity": "sha512-ml/JPOj9fOQK8RNnWojA67GbZ0ApXAUlN2UQclwv2eVgTgn7O9gg9o7paZWKMp4g0H3nTLtS9LVzhkpOFIKzog==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    }
+  }
+}

data/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "llm-docs-builder",
+  "version": "1.0.0",
+  "description": "CI dependencies for llm-docs-builder",
+  "private": true,
+  "devDependencies": {
+    "lostconf": "0.4.0"
+  }
+}

data/renovate.json

@@ -3,13 +3,18 @@
   "extends": [
     "config:recommended"
   ],
+  "minimumReleaseAge": "7 days",
+  "includePaths": [
+    ".ruby-version",
+    "Gemfile",
+    "llm-docs-builder.gemspec",
+    ".github/workflows/**",
+    "Dockerfile*",
+    "package.json"
+  ],
   "ignorePaths": [
     "spec/integrations"
   ],
-  "github-actions": {
-    "enabled": true,
-    "pinDigests": true
-  },
   "packageRules": [
     {
       "matchCategories": [
@@ -21,13 +26,21 @@
       "matchManagers": [
         "github-actions"
       ],
-      "minimumReleaseAge": "7 days"
+      "pinDigests": true
     },
     {
-      "matchManagers": [
-        "bundler"
+      "description": "Group ruby/setup-ruby action with ruby version updates",
+      "matchPackageNames": [
+        "ruby/setup-ruby",
+        "ruby"
       ],
-      "minimumReleaseAge": "7 days"
+      "groupName": "ruby setup"
     }
-  ]
+  ],
+  "labels": [
+    "dependencies"
+  ],
+  "lockFileMaintenance": {
+    "enabled": true
+  }
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm-docs-builder
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -41,16 +41,16 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -130,6 +130,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- ".yard-lint.yml"
 - CHANGELOG.md
 - Dockerfile
 - Gemfile
@@ -172,6 +173,8 @@ files:
 - misc/diff.png
 - misc/logo.png
 - misc/logo_wide.png
+- package-lock.json
+- package.json
 - renovate.json
 homepage: https://github.com/mensfeld/llm-docs-builder
 licenses:
@@ -190,14 +193,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Build and optimize documentation for LLMs - generate llms.txt, transform
   markdown, and more