llm-docs-builder 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: deeae74a329018b4a43d7845a3be8b7c31347699c3ff7abd93d7b697a48982a3
-  data.tar.gz: f9c842caa93a45b4d75c45a15e116e6f98d8463e5268e2de32e498c725877e4f
+  metadata.gz: 2a55f2ba08f239388d3f4834df0c1caeef9c138278726b442f6533e000a3554c
+  data.tar.gz: 173e4950404e3a4b83bd5213520a29b5b6f70b374dd18c58a8374c9b5bf55b21
 SHA512:
-  metadata.gz: 94575eced147bd6740b5395acd41d3f46ffcadf40908831df081d5e03f56b35a2e1e9acfdfc7642af775b2aa86fe48ea322dd11baf48512d2f2ef43a1a491079
-  data.tar.gz: 52b7d40d4a95acd20a408f4d453f32c7154637ce42ec210cf67010ce10dbe14ad711c4cbfd4060d8ce5018b91668315d552732ea7118374e69228a869792ff0f
+  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
@@ -54,6 +54,35 @@ jobs:
           GITHUB_COVERAGE: ${{ matrix.coverage }}
         run: bin/rspecs
 
+  yard-lint:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f # v1.306.0
+        with:
+          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
@@ -61,6 +90,8 @@ jobs:
     if: always()
     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@c1e51972afc2121e065aed6d45c65596fe445f3f # 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@29109295f81e9208d7d86ff1c6c12d2833863392 # 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@4ff6f3611a42bc75eee1e5138240eb1613f48c8f # v1.266.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@a25424ba2ba8b387abc8ef40807c2c85b96cbe32 # v1.1.1
+      - uses: rubygems/release-gem@6317d8d1f7e28c24d28f6eff169ea854948bd9f7 # v1.2.0

data/.gitignore

@@ -10,6 +10,8 @@
 /test/version_tmp/
 /tmp/
 mise.toml
+.DS_Store
+.vscode/launch.json
 
 # Used by dotenv library to load environment variables.
 .env
@@ -64,3 +66,9 @@ llms.txt
 # Config files that might contain sensitive data
 llms-txt.yml
 .llms-txt.yml
+
+# AI coding agent
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+

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,21 @@
 # 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
+  - Integrates seamlessly with the transformer pipeline
+  - Useful for converting web-based docs to markdown for further processing
+  - By @Eric-Guo in PR #32.
+
 ## 0.11.0 (2025-11-03)
 - [Feature] **Transform from URL** — The `transform` command now accepts a remote URL via `--url` and processes fetched content through the standard transformer pipeline.
   - Example: `llm-docs-builder transform --url https://example.com/docs/page.html`

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,5 +6,5 @@ gemspec
 
 group :development do
   gem 'pry'
-  gem 'pry-byebug'
+  gem 'yard-lint'
 end

data/Gemfile.lock

@@ -1,36 +1,41 @@
 PATH
   remote: .
   specs:
-    llm-docs-builder (0.11.0)
+    llm-docs-builder (0.13.0)
+      nokogiri (~> 1.17)
       zeitwerk (~> 2.6)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
-    byebug (12.0.0)
     coderay (1.1.3)
     diff-lcs (1.6.2)
     docile (1.4.1)
-    json (2.15.2)
+    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)
-    parallel (1.27.0)
-    parser (3.3.10.0)
+    mini_portile2 (2.8.9)
+    nokogiri (1.19.3)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    parallel (2.1.0)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
-    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)
+      reline (>= 0.6.0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.1)
-    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)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -40,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.6)
+    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.6)
+    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)
@@ -67,22 +72,25 @@ GEM
     simplecov_json_formatter (0.1.4)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
-    unicode-emoji (4.1.0)
-    zeitwerk (2.7.3)
+    unicode-emoji (4.2.0)
+    yard (0.9.43)
+    yard-lint (1.5.1)
+      yard (~> 0.9)
+      zeitwerk (~> 2.6)
+    zeitwerk (2.7.5)
 
 PLATFORMS
   ruby
-  x86_64-linux
 
 DEPENDENCIES
-  bundler (~> 2.0)
+  bundler
   llm-docs-builder!
   pry
-  pry-byebug
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (~> 1.0)
   simplecov (~> 0.21)
+  yard-lint
 
 BUNDLED WITH
-   2.7.2
+   2.6.9