llm-docs-builder 0.12.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac257dad79f49ed6993f784f8a28ee1e996e735fef4581449ad521ea9414a5d4
-  data.tar.gz: 29e1d2d578d57ea6f17aafca070c61b6161b6313d6614f0e4f798933ceae082d
+  metadata.gz: a1d023947b940a99bfa254d72ff79e47eef15f378eeb2e46ca2f04859b5da6dd
+  data.tar.gz: 85448c820f8fce92e9a26c094a9dd8cd485619ac45eb72ad45ed5b058ff2dc69
 SHA512:
-  metadata.gz: f82216cca621e942c0e6ad3d92aba5d099159cc9c0d10c1d010a85e2a740511103cebd0198c0056195775064853e749472dcb7f0939b8d3fda7753d291a5b0da
-  data.tar.gz: 31aa5737e215439b11a2e79d793dabb9ff342206b660a2ecd846920bc2f6501c3d5910da4cdc52ecfcfa9f7b9acef14213b17936edd23d86808c0bcb2f391952
+  metadata.gz: 9b345c53110799db9429b5185c1f773ae7ed99bdfa4da73f038cacad8cd319aa378f483f928a76d7f73533da08201f930f74b98e28a0246042e85d5269dc0d24
+  data.tar.gz: 6f876f2ec8b9e41a8daf1626b87e0cfb610fe164ff47231587ab3cbb78d2ea1ed699d06a24ea2927426ea7a227996828fbdc82c3a4abbc3e37883bee3277923d

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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
         with:
-          ruby-version: '3.4.7'
+          ruby-version: '4.0.6'
           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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+      - name: Set up Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # 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@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
 
       - name: Login to Docker Hub
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # 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@dbcb813823bdd20940b903addbd779551569679f # 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@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # 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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@d5126b9b3579e429dd52e51e68624dda2e05be25 # v1.267.0
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.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@052cc82692552de3ef2b81fd670e41d13cba8092 # v1.4.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.6

data/.yard-lint.yml

@@ -0,0 +1,309 @@
+# 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
+
+Documentation/DuplicateNamespaceComment:
+  Description: Detects namespaces documented with a YARD comment in more than one file.
+  Enabled: true
+  Severity: error
+
+Documentation/UnderfilledLines:
+  Description: Detects documentation prose that wraps too early and wastes horizontal space.
+  Enabled: true
+  Severity: error
+  # Aligned with RuboCop's Layout/LineLength so documentation prose wraps to the same
+  # width as code.
+  MaxLength: 120
+
+Documentation/LineLength:
+  Description: Detects documentation lines that exceed the maximum length.
+  Enabled: true
+  Severity: error
+  # Aligned with RuboCop's Layout/LineLength.
+  MaxLength: 120
+
+Documentation/TextSubstitution:
+  Description: Detects em/en-dashes in documentation and replaces them with hyphens.
+  Enabled: true
+  Severity: error
+  Substitutions:
+    "—": "-"    # em-dash (U+2014)
+    "–": "-"    # en-dash (U+2013)
+
+# Tags validators
+Tags/Order:
+  Description: Enforces consistent ordering of YARD tags.
+  Enabled: true
+  Severity: error
+  EnforcedOrder:
+  - param
+  - option
+  - yield
+  - yieldparam
+  - yieldreturn
+  - return
+  - raise
+  - see
+  - example
+  - note
+  - todo
+
+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: error
+
+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,22 @@
 # Changelog
 
+## [Unreleased]
+
+## 1.0.0 (2026-08-24)
+- [Fix] **Link Expansion Corrupts Non-HTTP URI Schemes** — `LinkTransformer#expand_relative_links` no longer rewrites `mailto:`, `tel:`, and `ftp:` links into dead `https://...` URLs when `base_url` is set (#165).
+  - Any link whose scheme is in the known absolute-scheme list (`http`, `https`, `mailto`, `ftp`, `tel`) is now left untouched, matching `HtmlToMarkdownConverter`'s `SAFE_URI_SCHEMES`.
+  - Relative links (e.g. `./guide.md`) continue to expand as before.
+- [Enhancement] Add Ruby warning category opt-in to test helpers
+
+## 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,9 @@ gemspec
 
 group :development do
   gem 'pry'
-  gem 'pry-byebug'
   gem 'yard-lint'
 end
 
 group :test do
+  gem 'warning'
 end