asciidoctor-reducer 1.0.0-rc.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: de2091cf932e336783f5622831333d3461fc8ee8cf1b47431fe48ba257e759ef
+  data.tar.gz: 07e125f547be6892cba77ba5af468ab86a5b37009abe9da4167f3a2f71f45a5e
+SHA512:
+  metadata.gz: 9bfa607af1fe8339e4b8925d5e68d793d992c069b674ee40d00234b8e06c254b0d473f7ec4db140b1c95f4446218d347661872eaa72e306785fa9e6d8f593f13
+  data.tar.gz: 0ed27e9fbe39fd738cb7a48b22b2f5ea1d967a8cb0077e79dd4ec0e86a3328d9e546f249fb0debda4984485bcf2538905ba8b5da44485b79cd50e2e05001780a

data/CHANGELOG.adoc

@@ -0,0 +1,198 @@
+= Asciidoctor Reducer Changelog
+:url-repo: https://github.com/asciidoctor/asciidoctor-reducer
+
+This document provides a curated view of the changes to Asciidoctor Reducer in each release.
+For a detailed view of what has changed, refer to the {url-repo}/commits/main[commit history] on GitHub.
+
+== 1.0.0-rc.1 (2022-04-22) - @mojavelinux
+
+_No changes since previous release._
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0-rc.1[git tag] | {url-repo}/compare/v1.0.0-beta.1\...v1.0.0-rc.1[full diff]
+
+== 1.0.0-beta.1 (2022-04-21) - @mojavelinux
+
+=== Changed
+
+* Add names of include files which have been included partially in include mapping comment and prefix names with ~
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0-beta.1[git tag] | {url-repo}/compare/v1.0.0.alpha.10\...v1.0.0-beta.1[full diff]
+
+== 1.0.0.alpha.10 (2022-04-21) - @mojavelinux
+
+=== Changed
+
+* Set Ruby 2.7 as minimum Ruby version
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0.alpha.10[git tag] | {url-repo}/compare/v1.0.0.alpha.9\...v1.0.0.alpha.10[full diff]
+
+== 1.0.0.alpha.9 (2022-04-21) - @mojavelinux
+
+=== Added
+
+* Add `Asciidoctor::Reducer::IncludeMapper` auxiliary extension, required by `asciidoctor/reducer/include_mapper/extension` (#26)
+* Register `Asciidoctor::Reducer::IncludeMapper` extension when `asciidoctor/reducer/include_mapper` is required (#26)
+* Add `Asciidoctor::Reducer::Extensions.key` method that returns key for registering extension group
+* Update help text to note that the `-a` and `-r` CLI options may be specified multiple times
+* Automate the release process
+
+=== Changed
+
+* Rename x_include_replacements attr on reader to include_replacements since it's public
+* Don't pass `:to` option to `Asciidoctor.load_file`
+* Make `Asciidoctor::Reducer::Cli` a module instead of a class
+
+=== Fixed
+
+* Replace remote include with link if `allow-uri-read` attribute is not set
+* Don't raise error if `Asciidoctor::Reducer::Extensions.unregister` is called when extensions are not registered globally
+* Ensure output is written to file with universal newlines (\n) on Windows
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0.alpha.9[git tag] | {url-repo}/compare/v1.0.0.alpha.8\...v1.0.0.alpha.9[full diff]
+
+== 1.0.0.alpha.8 (2022-02-23) - @mojavelinux
+
+=== Added
+
+* Add secure mode as value of `-S` CLI option (#31)
+* Add `--trace` option to CLI to trace cause of application errors (#29)
+
+=== Changed
+
+* Replace include directive with link macro if safe mode is secure (#31)
+* Track line numbers in include replacements using 1-based index
+* Only mix in preprocessor conditional tracker if `:preserve_conditionals` option is not set (#36)
+
+=== Fixed
+
+* Handle signals gracefully (#33)
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0.alpha.8[git tag] | {url-repo}/compare/v1.0.0.alpha.7\...v1.0.0.alpha.8[full diff]
+
+== 1.0.0.alpha.7 (2022-02-14) - @mojavelinux
+
+=== Added
+
+* Add asciidoctor/reducer/api to require main API (#3)
+* Add `Asciidoctor::Reducer.reduce` and `Asciidoctor::Reducer.reduce_file` API methods (#3)
+* Add asciidoctor/reducer/extensions to require extensions API (#3)
+* Add `Asciidoctor::Reducer::Extensions` API (#3)
+
+=== Changed
+
+* Scope extensions to single call instead of registering them globally (#3)
+* Use `:safe` as the default safe mode when using the API
+* Make `CurrentPosition` module private to the `PreprocessorDirectiveTracker` module
+
+=== Fixed
+
+* Require asciidoctor/reducer/version automatically when `Asciidoctor::Reducer::VERSION` is accessed
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0.alpha.7[git tag] | {url-repo}/compare/v1.0.0.alpha.6\...v1.0.0.alpha.7[full diff]
+
+== 1.0.0.alpha.6 (2022-02-10) - @mojavelinux
+
+=== Added
+
+* Add `-S`, `--safe-mode` option to CLI to set safe mode (#13)
+* Add `-r`, `--require` option to CLI to specify additional libraries to require before running (#17)
+
+=== Changed
+
+* Sort CLI options in help text, except for the `-h`, `--help` option
+* Update CLI to always use a new logger instance
+* Defer initializing logger until run method is called
+
+=== Fixed
+
+* Replace include directives that follow an unresolved include (#19)
+* Don't activate reducer extensions on reduced document
+* Prevent custom extension registry from activating extensions twice during reload (#21)
+* Retain includes table in document catalog when reloading document (#23)
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0.alpha.6[git tag] | {url-repo}/compare/v1.0.0.alpha.5\...v1.0.0.alpha.6[full diff]
+
+== 1.0.0.alpha.5 (2022-02-06) - @mojavelinux
+
+=== Changed
+
+* Removing trailing empty lines after reducing when sourcemap is not enabled
+* Remove unnecessary override of lineno in preprocess_include_directive override
+* Simplify how include replacement target is tracked
+* Classify extensions in group named `:reducer`
+
+=== Fixed
+
+* Suppress log messages when reloading document (#14)
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0.alpha.5[git tag] | {url-repo}/compare/v1.0.0.alpha.4\...v1.0.0.alpha.5[full diff]
+
+== 1.0.0.alpha.4 (2022-02-03) - @mojavelinux
+
+=== Fixed
+
+* Fix replacement of nested empty and unresolved includes
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0.alpha.4[git tag] | {url-repo}/compare/v1.0.0.alpha.3\...v1.0.0.alpha.4[full diff]
+
+== 1.0.0.alpha.3 (2022-02-02) - @mojavelinux
+
+=== Changed
+
+* Rename PreprocessorReader ext module to PreprocessorReaderTracker
+* Encapsulate logic to enhance PreprocessorReader inside PreprocessorReaderTracker module
+* Only reload document if source lines have changed; otherwise, update source lines on reader directly
+* Change default safe mode for CLI to :unsafe
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0.alpha.3[git tag] | {url-repo}/compare/v1.0.0.alpha.2\...v1.0.0.alpha.3[full diff]
+
+== 1.0.0.alpha.2 (2022-01-27) - @mojavelinux
+
+=== Added
+
+* Add `-a`, `--attribute` option to CLI for setting an AsciiDoc document attribute at runtime (#6)
+
+=== Changed
+
+* Reduce preprocessor conditionals by default; add option (`--preserve-conditionals`, `:preserve_conditionals`) to preserve them (#8)
+* Don't enable sourcemap automatically (#4)
+* Don't override logger by default; instead, rely on `:logger` API option to change logger
+* Add `--log-level` option to CLI to set severity level on logger (#9)
+* Add `-q`, `--quiet` option to CLI to suppress log messages (#9)
+* Reserve zero index in include replacements for top-level document
+
+=== Fixed
+
+* Preserve return value when overridding `preprocess_include_directive` method
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0.alpha.2[git tag] | {url-repo}/compare/v1.0.0.alpha.1\...v1.0.0.alpha.2[full diff]
+
+== 1.0.0.alpha.1 (2022-01-12) - @mojavelinux
+
+Initial release.
+
+=== Details
+
+{url-repo}/releases/tag/v1.0.0.alpha.1[git tag]

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2021-present Dan Allen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.adoc

@@ -0,0 +1,363 @@
+= {project-name}
+Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
+v1.0.0-rc.1, 2022-04-22
+:idprefix:
+:idseparator: -
+ifndef::env-github[:icons: font]
+ifdef::env-github[]
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
+:project-name: Asciidoctor Reducer
+:project-handle: asciidoctor-reducer
+:url-rvm: https://rvm.io
+:url-repo: https://github.com/asciidoctor/{project-handle}
+
+{project-name} is a tool that reduces an AsciiDoc document containing include directives to a single AsciiDoc document by expanding the includes reachable from the parent document.
+Additionally, the tool evaluates preprocessor conditionals (unless the option to preserve them is enabled), only keeping those lines from conditions which are true.
+If the document does not contain any preprocessor directives, the tool returns the unmodified source.
+
+== Prerequisites
+
+{project-name} is a Ruby application that you install using Ruby packaging.
+To install and run {project-name}, you need Ruby 2.7 or better.
+
+Run the following command to check which version of Ruby you have installed, if any:
+
+ $ ruby -v
+
+If Ruby is not installed, you can install it using {url-rvm}[RVM] (or, if you prefer, the package manager for your system).
+We generally recommend using RVM as it allows you to install gems without requiring elevated privileges or messing with system libraries.
+
+== Installation
+
+{project-name} is published to RubyGems.org as the gem named *{project-handle}*.
+
+You can install the latest version of the gem using the following command:
+
+ $ gem install asciidoctor-reducer --pre
+
+Installing this gem makes the `asciidoctor-reducer` command available on your $PATH.
+You can also require the gem into the Ruby runtime to use it as a library or Asciidoctor extension.
+
+=== Project-scoped
+
+If you prefer to manage the application as a project-scoped dependency, you can declare the gem in the project's [.path]_Gemfile_:
+
+.Gemfile
+[,ruby]
+----
+source 'https://rubygems.org'
+
+gem 'asciidoctor-reducer'
+----
+
+You then install the gem using the `bundle` command:
+
+ $ bundle --path=.bundle/gems
+
+Installing the gem this way makes the `bundle exec asciidoctor-reducer` command available on your $PATH.
+
+== Usage
+
+=== Command
+
+You can run this tool using the provided command (i.e., CLI), named `asciidoctor-reducer`.
+To learn how to use the command, and to verify it's available, run the command with the `-h` option:
+
+ $ asciidoctor-reducer -h
+
+On the first line of the help text, you'll see a synopsis of the command:
+
+....
+asciidoctor-reducer [OPTION]... FILE
+....
+
+The argument `FILE` is the AsciiDoc file you want to reduce.
+The options, represented by `+[OPTION]...+`, are optional, as the name suggestions.
+
+Thus, to use the command, pass the AsciiDoc file as the sole argument:
+
+ $ asciidoctor-reducer input.adoc
+
+By default, the command will output the reduced AsciiDoc document to the terminal (via stdout).
+To write the output to a file, specify an output file using the `-o` option:
+
+ $ asciidoctor-reducer -o output.adoc input.adoc
+
+The command can also read the input document from stdin instead of a file.
+To use the command in this way, pass `-` as the first argument:
+
+ $ cat input.adoc | asciidoctor-reducer -
+
+To write the output to a file in this case, specify an output file using the `-o` option:
+
+ $ cat input.adoc | asciidoctor-reducer -o output.adoc -
+
+=== API
+
+You can also use this tool from a Ruby application using the provided API.
+To begin, require the API for this library.
+
+[,ruby]
+----
+require 'asciidoctor/reducer/api'
+----
+
+Next, reduce a parent document that contains includes.
+This works without having to specify the safe mode since the default safe mode when using the API is `:safe`.
+
+[,ruby]
+----
+doc = Asciidoctor::Reducer.reduce_file 'sample.adoc'
+----
+
+Finally, you can retrieve the reduced source from the returned document.
+
+[,ruby]
+----
+puts doc.source
+----
+
+The benefit of this approach is that you can access the reduced source and the parsed document that corresponds to it.
+
+If you don't need the parsed document, you can retrieve the reduced source directly by passing the `String` type to the `:to` option:
+
+[,ruby]
+----
+puts Asciidoctor::Reducer.reduce_file 'sample.adoc', to: String
+----
+
+You can write the reduced source directly to a file by passing a file path to the `:to` option:
+
+[,ruby]
+----
+Asciidoctor::Reducer.reduce_file 'sample.adoc', to: 'sample-reduced.adoc'
+----
+
+== Extension
+
+Instead of using the API for this library, you can use the load API provided by Asciidoctor.
+If you want to register the extension globally, require the library as follows:
+
+[,ruby]
+----
+require 'asciidoctor/reducer'
+----
+
+When you use the Asciidoctor load API, the document will automatically be reduced.
+
+[,ruby]
+----
+puts (Asciidoctor.load_file 'sample.adoc', safe: :safe).source
+----
+
+If you want to keep the extension scoped to the call, require the library as follows:
+
+[,ruby]
+----
+require 'asciidoctor/reducer/extensions'
+----
+
+Next, use the extensions API to prepare an extension registry and pass it to the Asciidoctor load API:
+
+[,ruby]
+----
+puts (Asciidoctor.load_file 'sample.adoc', safe: :safe, extension_registry: Asciidoctor::Reducer.prepare_registry).source
+----
+
+Working with the extension directly is intended for low-level operations.
+Most of the time, you should use the API provided by this library.
+
+== How it Works
+
+{project-name} uses a collection of Asciidoctor extensions to rebuild the AsciiDoc source as a single document.
+Top-level include files in the input AsciiDoc document are resolved relative to current working directory.
+
+It starts by using a preprocessor extension to enhance the PreprocessorReader class to be notified each time an include is entered (pushed) or exited (popped).
+When an include directive is encountered, the enhanced reader stores the resolved lines and location of the include directive, thus keeping track of where those lines should be inserted in the original source.
+This information is stored as a stack, where each successive entry contains lines to be inserted into a parent entry.
+The enhanced reader also stores the location of preprocessor conditionals and whether the lines they enclose should be kept or dropped.
+
+The reducer then uses a tree processor extension to fold the include stack into a single sequence of lines.
+It does so by working from the end of the stack and inserting the lines into the parent until the stack has been flattened.
+As it goes, it also removes lines that have been excluded by the preprocessor conditionals as well as the directive lines themselves (unless the option to preserve conditionals has been specified).
+
+Finally, it loads the document again and returns it.
+The reduced source is available on the reconstructed document (via `Document#source` or `Document#source_lines`).
+
+=== Impact on Extensions
+
+If the sourcemap is enabled, and the reducer finds lines to replace or filter, the reducer will load the document again using `Asciidoctor.load`.
+This step is necessary to synchronize the sourcemap with the reduced source.
+This call will cause extensions that run during the load phase to be invoked again.
+An extension can check for this secondary load by checking for the `:reduced` option in the `Document#options` hash.
+If this option is set (the value of which will be `true`), then Asciidoctor is loading the reduced document.
+
+== Include Mapper (Experimental)
+
+One of the challenges of reducing a document is that interdocument xrefs that rely on the includes being registered in the document catalog no longer work.
+That's because when the reduced document is converted, it has no includes and thus all interdocument xrefs are colocated in the same source file.
+To work around this shortcoming, {project-name} provides a utility extension named the include mapper that will carry over the includes in the document catalog to the reduced document so they can be imported during conversion.
+
+CAUTION: The include mapper is experimental and thus subject to change.
+
+To use the include mapper when using the CLI to reduce the document, require it using the `-r` option as follows:
+
+ $ asciidoctor-reducer -r asciidoctor/reducer/include_mapper -o input-reduced.adoc input.adoc
+
+To use the include mapper when converting the reduced document, again require it using the `-r` option as follows:
+
+ $ asciidoctor -r asciidoctor/reducer/include_mapper input-reduced.adoc
+
+To use the include mapper when using the API, first require the extension:
+
+[,ruby]
+----
+require 'asciidocotor/reducer/include_mapper/extension'
+----
+
+You then need to register the extension when reducing the document:
+
+[,ruby]
+----
+Asciidoctor::Reducer.reduce_file 'sample.adoc', to: 'sample-reduced.adoc', extensions: proc {
+  next if document.options[:reduced]
+  tree_processor Asciidoctor::Reducer::IncludeMapper
+}
+----
+
+Then register it again when converting the reduced document:
+
+[,ruby]
+----
+Asciidoctor.convert_file 'sample-reduced.adoc', safe: :safe, extensions: proc {
+  tree_processor Asciidoctor::Reducer::IncludeMapper
+}
+----
+
+You can also register the extension globally:
+
+[,ruby]
+----
+require 'asciidocotor/reducer/include_mapper'
+----
+
+In this case, you don't have to pass it to the API explicitly.
+
+=== How it Works
+
+The include mapper works by adding a magic comment to the bottom of the reduced file.
+Here's an example of that comment:
+
+[,asciidoc]
+----
+//# includes=chapters/chapter-a,chapters/chapter-b
+----
+
+When a document that contains the magic comment is converted, the include mapper reads the comma-separated paths in the value and loads them into the includes table of the document catalog.
+
+== Development
+
+Follow the instructions below to learn how to help develop the project or test-drive the development version.
+
+=== Retrieve the source code
+
+Copy the {url-repo}[GitHub repository URL] and pass it to the `git clone` command:
+
+[subs=attributes+]
+ $ git clone {url-repo}
+
+Next, switch to the project directory:
+
+[subs=attributes+]
+ $ cd {project-handle}
+
+=== Install the dependencies
+
+The dependencies needed to use {project-name} are defined in the [.path]_Gemfile_ at the root of the project.
+You'll use Bundler to install these dependencies.
+
+Use the `bundle` command to install the project dependencies under the project directory:
+
+ $ bundle --path=.bundle/gems
+
+You must invoke `bundle` from the project's root directory so it can locate the [.path]_Gemfile_.
+
+=== Run the tests
+
+The test suite is located in the [.path]_spec_ directory.
+The tests are based on RSpec.
+
+==== Run all tests
+
+You can run all of the tests using Rake:
+
+ $ bundle exec spec
+
+For more fine-grained control, you can also run the tests directly using RSpec:
+
+ $ bundle exec rspec
+
+To run all tests in a single spec, point RSpec at the spec file:
+
+ $ bundle exec rspec spec/reducer_spec.rb
+
+==== Run specific tests
+
+If you only want to run a single test, or a group of tests, you can do so by tagging the test cases, then filtering the test run using that tag.
+
+Start by adding the `only` tag to one or more specifications:
+
+[source,ruby]
+----
+it 'should do something new', only: true do
+  expect(true).to be true
+end
+----
+
+Next, run RSpec with the `only` flag enabled:
+
+ $ bundle exec rspec -t only
+
+RSpec will only run the specifications that contain this flag.
+
+You can also filter tests by keyword.
+Let's assume we want to run all the tests that have `leveloffset` in the description.
+Run RSpec with the example filter:
+
+ $ bundle exec rspec -e leveloffset
+
+RSpec will only run the specifications that have a description containing the text `leveloffset`.
+
+=== Generate code coverage
+
+To generate a code coverage report when running tests using simplecov, set the `COVERAGE` environment variable as follows when running the tests:
+
+ $ COVERAGE=deep bundle exec rake
+
+You'll see a total coverage score, a detailed coverage report, and a link to HTML report in the output.
+The HTML report helps you understand which lines and branches were missed, if any.
+
+=== Run the development version
+
+When running the `asciidoctor-reducer` command from source, you must prefix the command with `bundle exec`:
+
+[subs=attributes+]
+ $ bundle exec asciidoctor-reducer sample.adoc
+
+To avoid having to do this, or to make the `asciidoctor-reducer` command available from anywhere, you need to build the development gem and install it.
+
+== Copyright and License
+
+Copyright (C) 2021-present Dan Allen.
+Use of this software is granted under the terms of the MIT License.
+
+See the link:LICENSE[LICENSE] for the full license text.
+
+== Trademarks
+
+AsciiDoc(R) and AsciiDoc Language(TM) are trademarks of the Eclipse Foundation, Inc.

data/asciidoctor-reducer.gemspec

@@ -0,0 +1,39 @@
+begin
+  require_relative 'lib/asciidoctor/reducer/version'
+rescue LoadError
+  require 'asciidoctor/reducer/version'
+end
+
+Gem::Specification.new do |s|
+  s.name = 'asciidoctor-reducer'
+  s.version = Asciidoctor::Reducer::VERSION
+  s.summary = 'Reduces an AsciiDoc document containing includes and conditionals to a single AsciiDoc document.'
+  s.description = 'A tool that reduces an AsciiDoc document containing preprocessor directives (includes and conditionals) to a single AsciiDoc document by expanding all includes and evaluating all conditionals.'
+  s.authors = ['Dan Allen']
+  s.email = 'dan.j.allen@gmail.com'
+  s.homepage = 'https://asciidoctor.org'
+  s.license = 'MIT'
+  # NOTE required ruby version is informational only; it's not enforced since it can't be overridden and can cause builds to break
+  #s.required_ruby_version = '>= 2.7.0'
+  s.metadata = {
+    'bug_tracker_uri' => 'https://github.com/asciidoctor/asciidoctor-reducer/issues',
+    'changelog_uri' => 'https://github.com/asciidoctor/asciidoctor-reducer/blob/main/CHANGELOG.adoc',
+    'mailing_list_uri' => 'https://asciidoctor.zulipchat.com',
+    'source_code_uri' => 'https://github.com/asciidoctor/asciidoctor-reducer'
+  }
+
+  # NOTE the logic to build the list of files is designed to produce a usable package even when the git command is not available
+  begin
+    files = (result = `git ls-files -z`.split ?\0).empty? ? Dir['**/*'] : result
+  rescue
+    files = Dir['**/*']
+  end
+  s.files = files.grep %r/^(?:lib\/.+|LICENSE|(?:CHANGELOG|README)\.adoc|#{s.name}\.gemspec)$/
+  s.executables = (files.grep %r/^bin\//).map {|f| File.basename f }
+  s.require_paths = ['lib']
+
+  s.add_runtime_dependency 'asciidoctor', '~> 2.0'
+
+  s.add_development_dependency 'rake', '~> 13.0.0'
+  s.add_development_dependency 'rspec', '~> 3.11.0'
+end

data/bin/asciidoctor-reducer

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+asciidoctor_reducer_cli = File.join (File.dirname __dir__), 'lib/asciidoctor/reducer/cli.rb'
+require (File.file? asciidoctor_reducer_cli) ? asciidoctor_reducer_cli : 'asciidoctor/reducer/cli'
+exit Asciidoctor::Reducer::Cli.run

data/lib/asciidoctor/reducer/api.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+autoload :Pathname, 'pathname'
+require_relative 'extensions'
+
+module Asciidoctor::Reducer
+  autoload :VERSION, (::File.join __dir__, 'version.rb')
+
+  class << self
+    # Reduces the AsciiDoc source and either returns the reduced Asciidoctor::Document or writes the source to a file.
+    #
+    # This method accepts all the options supported by Asciidoctor.load.
+    #
+    # @param input [String, File, Pathname] the AsciiDoc source to reduce.
+    # @param opts [Hash] additional options to configure the behavior of the reducer.
+    # @option opts [File, Pathname, Class] :to (nil) the target to which to write the reduced source.
+    #
+    # @return [Asciidoctor::Document, nil] the reduced document object or nil if the :to option is specified.
+    def reduce input, opts = {}
+      opts = opts&.merge || {}
+      if (extension_registry = Extensions.prepare_registry opts[:extension_registry] || opts[:extensions])
+        opts[:extension_registry] = extension_registry
+      end
+      opts[:safe] ||= :safe
+      to = opts.delete :to
+      case input
+      when ::File
+        doc = ::Asciidoctor.load_file input, opts
+      when ::Pathname
+        doc = ::Asciidoctor.load_file input.to_path, opts
+      else
+        doc = ::Asciidoctor.load input, opts
+      end
+      write doc, to
+    end
+
+    # Reduces the AsciiDoc file and either returns the reduced Asciidoctor::Document or writes the source to a file.
+    #
+    # This method accepts all the options supported by Asciidoctor.load.
+    #
+    # @param input_file [String] the path of the AsciiDoc file to reduce.
+    # @param opts [Hash] additional options to configure the behavior of the reducer.
+    # @option opts [File, Pathname, Class] :to (nil) the target to which to write the reduced source.
+    #
+    # @return [Asciidoctor::Document, nil] the reduced document object or nil if the :to option is specified.
+    def reduce_file input_file, opts = {}
+      reduce (::Pathname.new input_file), opts
+    end
+
+    private
+
+    def write doc, to
+      return doc unless to && to != '/dev/null'
+      output = doc.source
+      return output if to == ::String
+      output += LF unless output.empty?
+      if ::Pathname === to || (!(to.respond_to? :write) && (to = ::Pathname.new to.to_s))
+        to.dirname.mkpath
+        to.write output, encoding: UTF_8, newline: :universal
+      else
+        to.write output
+      end
+      doc
+    end
+  end
+
+  LF = ?\n
+  UTF_8 = ::Encoding::UTF_8
+
+  private_constant :LF, :UTF_8
+end

data/lib/asciidoctor/reducer/cli.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative 'api'
+autoload :OptionParser, 'optparse'
+
+module Asciidoctor::Reducer
+  module Cli
+    class << self
+      def parse args
+        options = { attributes: {}, log_level: LOG_LEVELS['warn'], safe: :unsafe }
+
+        opt_parser = ::OptionParser.new do |opts|
+          opts.program_name = 'asciidoctor-reducer'
+          opts.banner = <<~END
+          Usage: #{opts.program_name} [OPTION]... FILE
+
+          Reduces a composite AsciiDoc document containing includes and conditionals to a single AsciiDoc document.
+
+          END
+
+          opts.on '-a KEY[=VALUE]', '--attribute=KEY[=VALUE]',
+            'set a document attribute in the AsciiDoc document: [key, key!, key=value]',
+            'may be specified multiple times' do |attr|
+            key, val = attr.split '=', 2
+            val ||= ''
+            options[:attributes][key] = val
+          end
+
+          opts.on '--log-level LEVEL', %w(debug info warn error fatal),
+            'set the minimum level of messages to log: [debug, info, warn, error, fatal] (default: warn)' do |level|
+            options[:log_level] = level
+          end
+
+          opts.on '-o FILE', '--output=FILE', 'set the output filename or stream' do |file|
+            options[:output_file] = file
+          end
+
+          opts.on '--preserve-conditionals', 'preserve preprocessor conditional directives in the reduced source' do
+            options[:preserve_conditionals] = true
+          end
+
+          opts.on '-q', '--quiet', 'suppress all application log messages' do
+            options[:log_level] = nil
+          end
+
+          opts.on '-rLIBRARY', '--require LIBRARY', 'require the specified library or libraries before reducing',
+            'may be specified multiple times' do |path|
+            (options[:requires] ||= []).concat path.split ','
+          end
+
+          opts.on '-S', '--safe-mode SAFE_MODE', ['unsafe', 'safe', 'server', 'secure'],
+            'set safe mode level: [unsafe, safe, server, secure] (default: unsafe)' do |name|
+            options[:safe] = name.to_sym
+          end
+
+          opts.on '--trace', 'trace the cause of application errors (default: false)' do
+            options[:trace] = true
+          end
+
+          opts.on '-v', '--version', 'display the version information and exit' do
+            print_version opts
+            return 0
+          end
+
+          opts.on '-h', '--help', 'display this help text and exit' do
+            print_help opts
+            return 0
+          end
+        end
+
+        if (args = opt_parser.parse args).empty?
+          opt_parser.warn 'Please specify an AsciiDoc file to reduce.'
+          print_help opt_parser
+          1
+        elsif args.size == 1
+          if (requires = options.delete :requires)
+            requires.uniq.each do |path|
+              require path
+            rescue ::LoadError
+              $stderr.puts %(#{opt_parser.program_name}: '#{path}' could not be required (reason: #{$!.message}))
+              return 1
+            end
+          end
+          options[:input_file] = args[0]
+          options[:output_file] = '-' unless options[:output_file]
+          [0, options]
+        else
+          opt_parser.warn %(extra arguments detected (unparsed arguments: #{(args.drop 1).join ' '}))
+          print_help opt_parser
+          1
+        end
+      rescue ::OptionParser::InvalidOption
+        $stderr.puts %(#{opt_parser.program_name}: #{$!.message})
+        print_help opt_parser
+        1
+      end
+
+      def run args = ARGV
+        code, options = parse (Array args)
+        return code unless code == 0 && options
+        trace = options.delete :trace
+        old_logger = ::Asciidoctor::LoggerManager.logger
+        if (log_level = options.delete :log_level)
+          (options[:logger] = ::Asciidoctor::Logger.new $stderr).level = log_level
+        else
+          options[:logger] = nil
+        end
+        options[:to] = (output_file = options.delete :output_file) == '-' ? $stdout : (::Pathname.new output_file)
+        input = (input_file = options.delete :input_file) == '-' ? $stdin : (::Pathname.new input_file)
+        ::Asciidoctor::Reducer.reduce input, options
+        0
+      rescue ::SignalException
+        $stderr.puts if ::Interrupt === $!
+        $!.signo
+      rescue
+        raise $! if trace
+        $stderr.puts %(asciidoctor-reducer: #{$!.message.delete_prefix 'asciidoctor: '})
+        $stderr.puts '  Use --trace to show backtrace'
+        1
+      ensure
+        ::Asciidoctor::LoggerManager.logger = old_logger if old_logger
+      end
+
+      private
+
+      def print_help opt_parser
+        $stdout.puts opt_parser.help.chomp
+      end
+
+      def print_version opt_parser
+        $stdout.puts %(#{opt_parser.program_name} #{VERSION})
+      end
+    end
+
+    LOG_LEVELS = (::Logger::Severity.constants false).each_with_object({}) do |level, accum|
+      accum[level.to_s.downcase] = (::Logger::Severity.const_get level) unless level == :UNKNOWN
+    end
+
+    private_constant :LOG_LEVELS
+  end
+end

data/lib/asciidoctor/reducer/conditional_directive_tracker.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Asciidoctor::Reducer
+  module ConditionalDirectiveTracker
+    def preprocess_conditional_directive keyword, target, delimiter, text
+      skip_active = @skipping
+      depth = @conditional_stack.size
+      cond_lineno = @lineno
+      result = super
+      return result if @skipping && skip_active
+      drop = @include_replacements.current[:drop] ||= []
+      if (depth_change = @conditional_stack.size - depth) < 0
+        if skip_active
+          drop.push(*(drop.pop..cond_lineno))
+        else
+          drop << cond_lineno
+        end
+      elsif depth_change > 0 || cond_lineno == @lineno
+        drop << cond_lineno
+      else
+        drop << [cond_lineno, text]
+      end
+      result
+    end
+  end
+end

data/lib/asciidoctor/reducer/extensions.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'asciidoctor' unless defined? Asciidoctor.load
+require_relative 'preprocessor'
+require_relative 'tree_processor'
+
+module Asciidoctor::Reducer
+  module Extensions
+    module_function
+
+    def group
+      proc do
+        next if document.options[:reduced]
+        preprocessor Preprocessor
+        tree_processor TreeProcessor
+      end
+    end
+
+    def key
+      :reducer
+    end
+
+    def prepare_registry registry = nil
+      registry = ::Asciidoctor::Extensions.create(&registry) if ::Proc === registry
+      return registry if ::Asciidoctor::Extensions.groups[key]
+      if registry
+        registry.groups[key] = group
+        registry
+      else
+        ::Asciidoctor::Extensions.create key, &group
+      end
+    end
+
+    def register
+      ::Asciidoctor::Extensions.register key, &group
+    end
+
+    def unregister
+      ::Asciidoctor::Extensions.groups.delete key # NOTE `Extensions.unregister key` fails if groups is not initialized
+    end
+  end
+end

data/lib/asciidoctor/reducer/include_directive_tracker.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Asciidoctor::Reducer
+  module IncludeDirectiveTracker
+    attr_reader :include_replacements
+    attr_writer :source_lines
+
+    def self.extended instance
+      instance.instance_variable_set :@include_replacements, ([{}].extend CurrentPosition)
+      instance.instance_variable_set :@x_reducer, {}
+    end
+
+    def preprocess_include_directive target, attrlist
+      @x_reducer[:include_directive_line] = %(include::#{target}[#{attrlist}])
+      @x_reducer[:include_pushed] = false
+      inc_lineno = @lineno # we're currently on the include line, which is 1-based
+      result = super
+      unless @x_reducer[:include_pushed]
+        if ((ln = peek_line true)&.end_with? ']') && !(unresolved = ln.start_with? 'Unresolved directive in ') &&
+            inc_lineno == @lineno && (unresolved = ln.start_with? 'link:')
+          ln = %(#{ln.slice 0, (ln.length - 1)}role=include])
+        end
+        push_include_replacement inc_lineno, (unresolved ? [ln] : []), unresolved
+      end
+      @x_reducer.clear
+      result
+    end
+
+    def push_include data, file, path, lineno, attrs
+      @x_reducer[:include_pushed] = true
+      inc_lineno = @lineno - 1 # we're below the include line, which is 1-based
+      prev_inc_depth = @include_stack.size
+      result = super
+      push_include_replacement inc_lineno, (@include_stack.size > prev_inc_depth ? lines : [])
+      result
+    end
+
+    def pop_include
+      @include_replacements.up unless @x_reducer[:include_pushed]
+      super
+    end
+
+    private
+
+    def push_include_replacement lineno, lines, unresolved = false
+      (inc_replacements = @include_replacements) << {
+        into: inc_replacements.pointer,
+        lineno: lineno,
+        line: @x_reducer[:include_directive_line],
+        lines: lines,
+      }
+      inc_replacements.to_end unless unresolved || lines.empty?
+      nil
+    end
+  end
+
+  module CurrentPosition
+    attr_reader :pointer
+
+    def self.extended instance
+      instance.to_end
+    end
+
+    def current
+      self[@pointer]
+    end
+
+    def to_end
+      @pointer = size - 1
+    end
+
+    def up
+      @pointer = current[:into]
+    end
+  end
+
+  private_constant :CurrentPosition
+end

data/lib/asciidoctor/reducer/include_mapper/extension.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Asciidoctor::Reducer
+  class IncludeMapper < ::Asciidoctor::Extensions::TreeProcessor
+    def process doc
+      if doc.extensions.groups[:reducer]
+        unless (includes = doc.catalog[:includes].map {|name, val| val ? name : %(~#{name}) }).empty?
+          doc.source_lines.concat ['', %(//# includes=#{includes.join ','})]
+        end
+      elsif (last_line = doc.source_lines[-1])&.start_with? '//# includes='
+        doc.catalog[:includes].update ((last_line.slice 13, last_line.length).split ',')
+          .map {|it| [(fragment = it.chr == '~') ? (it.slice 1, it.length) : it, !fragment] }.to_h
+      end
+      doc
+    end
+  end
+end

data/lib/asciidoctor/reducer/include_mapper.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'include_mapper/extension'
+
+Asciidoctor::Extensions.register do
+  next if document.options[:reduced]
+  tree_processor Asciidoctor::Reducer::IncludeMapper
+end

data/lib/asciidoctor/reducer/preprocessor.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'include_directive_tracker'
+require_relative 'conditional_directive_tracker'
+
+module Asciidoctor::Reducer
+  class Preprocessor < ::Asciidoctor::Extensions::Preprocessor
+    def process doc, reader
+      doc.options[:preserve_conditionals] ?
+        (reader.extend IncludeDirectiveTracker) : (reader.extend ConditionalDirectiveTracker, IncludeDirectiveTracker)
+    end
+  end
+end

data/lib/asciidoctor/reducer/tree_processor.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Asciidoctor::Reducer
+  class TreeProcessor < ::Asciidoctor::Extensions::TreeProcessor
+    def process doc
+      if (inc_replacements = doc.reader.include_replacements).size > 1 || !(inc_replacements[0][:drop] || []).empty?
+        inc_replacements[0][:lines] = doc.source_lines.dup
+        inc_replacements.reverse_each do |it|
+          if (into = it[:into])
+            target_lines = inc_replacements[into][:lines]
+            # adds extra bit of assurance that we're replacing the correct line
+            next unless target_lines[(idx = it[:lineno] - 1)] == it[:line]
+          end
+          lines = it[:lines]
+          unless (drop = it[:drop] || []).empty?
+            drop.reverse_each do |drop_it|
+              ::Array === drop_it ? (lines[drop_it[0] - 1] = drop_it[1]) : (lines.delete_at drop_it - 1)
+            end
+          end
+          target_lines[idx] = lines if target_lines
+        end
+        source_lines = inc_replacements[0][:lines].flatten
+        if doc.sourcemap
+          logger = ::Asciidoctor::LoggerManager.logger
+          opts = doc.options.merge logger: nil, parse: false, reduced: true
+          if (ext_reg = opts[:extension_registry])
+            opts[:extension_registry] = ::Asciidoctor::Extensions::Registry.new ext_reg.groups
+          end
+          includes = doc.catalog[:includes]
+          doc = ::Asciidoctor.load source_lines, opts
+          doc.catalog[:includes] = includes
+          doc.parse
+          ::Asciidoctor::LoggerManager.logger = logger
+        else
+          source_lines.pop while (source_lines[-1] || :eof).empty?
+          doc.reader.source_lines = source_lines
+        end
+      end
+      doc
+    end
+  end
+end

data/lib/asciidoctor/reducer/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Asciidoctor
+  module Reducer
+    VERSION = '1.0.0-rc.1'
+  end
+end

data/lib/asciidoctor/reducer.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'reducer/extensions'
+
+Asciidoctor::Reducer::Extensions.register

data/lib/asciidoctor-reducer.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'asciidoctor/reducer'

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: asciidoctor-reducer
+version: !ruby/object:Gem::Version
+  version: 1.0.0-rc.1
+platform: ruby
+authors:
+- Dan Allen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-04-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: asciidoctor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.11.0
+description: A tool that reduces an AsciiDoc document containing preprocessor directives
+  (includes and conditionals) to a single AsciiDoc document by expanding all includes
+  and evaluating all conditionals.
+email: dan.j.allen@gmail.com
+executables:
+- asciidoctor-reducer
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.adoc
+- LICENSE
+- README.adoc
+- asciidoctor-reducer.gemspec
+- bin/asciidoctor-reducer
+- lib/asciidoctor-reducer.rb
+- lib/asciidoctor/reducer.rb
+- lib/asciidoctor/reducer/api.rb
+- lib/asciidoctor/reducer/cli.rb
+- lib/asciidoctor/reducer/conditional_directive_tracker.rb
+- lib/asciidoctor/reducer/extensions.rb
+- lib/asciidoctor/reducer/include_directive_tracker.rb
+- lib/asciidoctor/reducer/include_mapper.rb
+- lib/asciidoctor/reducer/include_mapper/extension.rb
+- lib/asciidoctor/reducer/preprocessor.rb
+- lib/asciidoctor/reducer/tree_processor.rb
+- lib/asciidoctor/reducer/version.rb
+homepage: https://asciidoctor.org
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/asciidoctor/asciidoctor-reducer/issues
+  changelog_uri: https://github.com/asciidoctor/asciidoctor-reducer/blob/main/CHANGELOG.adoc
+  mailing_list_uri: https://asciidoctor.zulipchat.com
+  source_code_uri: https://github.com/asciidoctor/asciidoctor-reducer
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.3.7
+signing_key: 
+specification_version: 4
+summary: Reduces an AsciiDoc document containing includes and conditionals to a single
+  AsciiDoc document.
+test_files: []