zard-doc 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4a7ff58279b52ea8ca3e15ffdf25f54214d20c5ececaeb641282e85050d3d5a
-  data.tar.gz: 9ede39071e88157e47387cf29ae4b4c04a8af656c396e26c783824b671c52ce4
+  metadata.gz: 2bb123e1e6f985214a4916cb89bbec02b5bbb1ecd9e93ef56d4881b8ffa738bc
+  data.tar.gz: d6891457dad716acd147f3b63a2d1218688fd1c968f14e3f0f97cdef1dc9d1d4
 SHA512:
-  metadata.gz: ed9d9d91a23b003910e34db882cfec727154822a60bf66c92e2f996bd9c2c94d0796c15e9603be569846b43985585eae8f74a24a722ca0fe3e60b7d985217ebe
-  data.tar.gz: 9d9d1e2a24d28de2d6080bc397734ab2f1de2d4623dc9cc4c3e70335e3801c0e8ee6d3aeff7b48e36a1234fd3d950407eb660d7452e9ab0c0f31c2a1ec657d45
+  metadata.gz: 4b24539a15c3464ab8b92a168fb52523603aaa968716e67b5012c968a0aa49eea44a7629fb43e58d9dd1fda6ef587a1e9683acccd7a88ae1b17870eac4b8354e
+  data.tar.gz: 0024cafbd06fa78029dc2b9997d51ec0ee59db984e89d25ca34f82f8b59c0e69e522eafc16a94d0347dcf3a19ba2cd01b5f32ec8bc252be3b91e43027c6cc96f

data/README.md

@@ -2,18 +2,11 @@
 
 `zard-doc` renders API documentation from the versioned model produced by `zard`.
 
-See the [ZARD usage guide](https://github.com/rigortype/zard/blob/master/docs/usage.md) for installation, canonical tag syntax, model access, limitations, and exit codes. The `0.0.1` candidate is not yet published on RubyGems. Until then, install both gems from the repository:
+See the [ZARD usage guide](https://github.com/rigortype/zard/blob/master/docs/usage.md) for installation, canonical tag syntax, model access, limitations, and exit codes. Install the 0.0.2 pair with Bundler:
 
 ```ruby
-gem "zard", github: "rigortype/zard"
-gem "zard-doc", github: "rigortype/zard"
-```
-
-After publication, use the released pair:
-
-```ruby
-gem "zard", "~> 0.0.1"
-gem "zard-doc", "~> 0.0.1"
+gem "zard", "~> 0.0.2"
+gem "zard-doc", "~> 0.0.2"
 ```
 
 ```ruby
@@ -39,6 +32,20 @@ Render Markdown to standard output with:
 zard-doc render lib
 ```
 
+Version 0.0.2 provides hierarchical monorepo documentation with `zard-doc build --config zard-doc.yml`. Named scopes separate applications; namespace or file layouts, direct documentation dependencies, and managed output updates are described in the [usage guide](https://github.com/rigortype/zard/blob/master/docs/usage.md#build-a-documentation-tree). Optional experimental Rigor lens integration is provided by the separate `zard-rigor` gem.
+
+`zard-doc build --config zard-doc.yml --format json` exports one experimental JSON document to stdout instead of publishing Markdown. It includes public declarations with or without prose, unparsed contracts, source provenance and digests, and scoped page assignments and links. See the [JSON export contract](https://github.com/rigortype/zard/blob/master/docs/json-export.md). The export needs no Rigor installation and is not a Rigor lens result.
+
+Version 0.0.2 also provides annotation formatting:
+
+```console
+zard-doc format lib/example.rb
+zard-doc format --check lib
+zard-doc format --write lib
+```
+
+Formatting preserves contract payloads, descriptions, and line endings. Ambiguous documentation and unsafe contract reorderings retain their text with diagnostics. Plain mode prints one input; check mode exits with 1 when changes are needed; write mode validates all inputs before changing files. Source errors exit with 1 and invocation or I/O errors with 2. Formatting diagnostics go to standard error.
+
 Directories are searched recursively for Ruby source files. Files are processed in stable sorted order and duplicate paths are ignored.
 Unreadable inputs are reported together; rendering never emits partial Markdown when any input cannot be read.
 Use `-` as a path to read Ruby source from standard input.

data/lib/zard/doc/build.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "zard/doc"
+
+module Zard
+  module Doc
+    class BuildError < StandardError
+      attr_reader :status
+
+      def initialize(message, status: 2)
+        super(message)
+        @status = status
+      end
+    end
+  end
+end
+
+require_relative "build_configuration"
+require_relative "build_publisher"
+require_relative "build_renderer"
+require_relative "build_export"
+
+module Zard
+  module Doc
+    class Build
+      attr_reader :diagnostics
+
+      def initialize(path, layout: nil, scopes: [], format: "markdown", stdout: $stdout, enricher: nil)
+        raise BuildError, "format must be markdown or json" unless %w[markdown json].include?(format)
+
+        @configuration = BuildConfiguration.new(path, layout: layout, scopes: scopes)
+        @format = format
+        @stdout = stdout
+        @enricher = enricher
+        @partial = !scopes.empty?
+        @diagnostics = []
+      end
+
+      def run
+        files = {}
+        documents = {}
+        digests = {}
+        input_errors = []
+        @configuration.selected_scopes.each do |name|
+          files[name] = @configuration.source_files(name)
+          documents[name] = files.fetch(name).keys.filter_map do |path|
+            source = File.read(path)
+            digests[path] = Digest::SHA256.hexdigest(source)
+            document = Zard.parse(source, path: path)
+            document.diagnostics.each { |diagnostic| @diagnostics << format_diagnostic(diagnostic) }
+            document
+          rescue SystemCallError => error
+            input_errors << "#{path}: #{error.message}"
+            nil
+          end
+        end
+        @diagnostics.concat(input_errors)
+        return 2 unless input_errors.empty?
+        return 1 if documents.values.flatten.any? { |document| document.diagnostics.any? { |diagnostic| diagnostic.severity == :error } }
+
+        renderer = BuildRenderer.new(scope_documents: documents, scope_files: files,
+          scopes: @configuration.scopes, layout: @configuration.layout, include_undocumented: @format == "json")
+        pages = renderer.render
+        @diagnostics.concat(renderer.diagnostics)
+        if @format == "json"
+          export = BuildExport.new(@configuration, documents, digests)
+          json = export.render(renderer, enricher: @enricher)
+          @diagnostics |= renderer.diagnostics
+          @stdout.write(json)
+          return 0
+        end
+
+        destinations = @configuration.selected_scopes.to_h do |name|
+          [name, @configuration.scopes.fetch(name).fetch(:destination)]
+        end
+        publisher = BuildPublisher.new(@configuration.docroot)
+        if @partial
+          pages["index.md"] = scope_index(publisher.scopes.merge(destinations))
+          publisher.publish(pages, selected_scopes: destinations, links: renderer.links)
+        else
+          publisher.publish(pages, scopes: destinations, links: renderer.links)
+        end
+        0
+      end
+
+      private
+
+      def scope_index(destinations)
+        links = destinations.sort.map do |name, destination|
+          label = name.gsub(/[&<>]/, "&" => "&amp;", "<" => "&lt;", ">" => "&gt;").gsub(/[\\\[\]`*_~]/) { |character| "\\#{character}" }
+          path = "#{destination}/index.md".b.gsub(/[^A-Za-z0-9._~\/-]/) { |byte| "%%%02X" % byte.ord }
+          "- [#{label}](#{path})"
+        end
+        "# API documentation\n\n#{links.join("\n")}\n"
+      end
+
+      def format_diagnostic(diagnostic)
+        span = diagnostic.span
+        "#{span.path}:#{span.start_line}:#{span.start_column + 1}: #{diagnostic.severity} #{diagnostic.code} #{diagnostic.message}"
+      end
+    end
+
+    private_constant :BuildError, :BuildConfiguration, :BuildPublisher, :BuildRenderer, :BuildExport, :Build
+  end
+end

data/lib/zard/doc/build_configuration.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module Zard
+  module Doc
+    class BuildConfiguration
+      attr_reader :base, :docroot, :layout, :selected_scopes, :scopes
+
+      def initialize(path, layout: nil, scopes: [])
+        base = @base = File.realpath(File.dirname(File.expand_path(path)))
+        text = File.read(path)
+        validate_yaml_keys(Psych.parse_stream(text))
+        raw = YAML.safe_load(text, permitted_classes: [], permitted_symbols: [], aliases: false)
+        mapping(raw, %w[docroot layout scopes], "configuration")
+        @docroot = File.expand_path(string(raw["docroot"], "docroot"), base)
+        @layout = layout || raw.fetch("layout", "namespace")
+        fail_build("layout must be namespace or file") unless %w[namespace file].include?(@layout)
+        definitions = raw["scopes"]
+        fail_build("scopes must be a nonempty mapping") unless definitions.is_a?(Hash) && !definitions.empty?
+        @scopes = definitions.to_h do |name, definition|
+          string(name, "scope name")
+          mapping(definition, %w[destination references sources], "scope #{name}")
+          sources = definition["sources"]
+          fail_build("scope #{name} sources must be a nonempty array") unless sources.is_a?(Array) && !sources.empty?
+          [name, {destination: relative(definition["destination"], "destination"),
+                  references: strings(definition.fetch("references", []), "references"),
+                  sources: sources.map { |source| source_mapping(source, base) }}]
+        end
+        @scopes.each do |name, definition|
+          definition[:references].each { |reference| fail_build("unknown dependency #{reference} in scope #{name}") unless @scopes.key?(reference) }
+        end
+        requested = scopes.empty? ? @scopes.keys : scopes
+        @selected_scopes = []
+        visit = lambda do |name|
+          fail_build("unknown scope #{name}") unless @scopes.key?(name)
+          next if @selected_scopes.include?(name)
+          @selected_scopes << name
+          @scopes.fetch(name)[:references].sort.each { |reference| visit.call(reference) }
+        end
+        requested.sort.each { |name| visit.call(name) }
+        @selected_scopes.sort!
+        @selected_scopes.combination(2) do |left, right|
+          a = @scopes.fetch(left).fetch(:destination)
+          b = @scopes.fetch(right).fetch(:destination)
+          fail_build("overlapping scope destinations: #{left} and #{right}") if a == b || a.start_with?(b + "/") || b.start_with?(a + "/")
+        end
+      rescue Psych::Exception, SystemCallError, ArgumentError => error
+        fail_build("cannot load configuration #{path}: #{error.message}")
+      end
+
+      def source_files(name)
+        definition = @scopes.fetch(name)
+        roots = definition[:sources].map { |source| File.realpath(source[:root]) }
+        files = {}
+        definition[:sources].each do |source|
+          source[:include].flat_map { |glob| Dir.glob(glob, base: source[:root], flags: File::FNM_DOTMATCH) }.uniq.sort.each do |relative_path|
+            next unless relative_path.end_with?(".rb")
+            next if source[:exclude].any? { |glob| File.fnmatch?(glob, relative_path, File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH) }
+            path = File.join(source[:root], relative_path)
+            canonical = File.realpath(path)
+            fail_build("source symlink escapes declared roots: #{path}") unless roots.any? { |root| canonical.start_with?(root + File::SEPARATOR) }
+            next unless File.file?(canonical)
+            fail_build("unreadable source: #{path}") unless File.readable?(canonical)
+            output = [source[:prefix], relative_path.sub(/\.rb\z/, ".md")].reject(&:empty?).join("/")
+            fail_build("conflicting output assignments for #{canonical}") if files.key?(canonical) && files[canonical] != output
+            files[canonical] = output
+          end
+        end
+        fail_build("scope #{name} selects no Ruby files") if files.empty?
+        files.sort.to_h
+      rescue SystemCallError => error
+        fail_build("cannot discover scope #{name}: #{error.message}")
+      end
+
+      private
+
+      def validate_yaml_keys(node)
+        if node.is_a?(Psych::Nodes::Mapping)
+          keys = node.children.each_slice(2).map(&:first)
+          values = keys.map { |key| key.respond_to?(:value) ? key.value : nil }
+          fail_build("duplicate or invalid YAML mapping key") if values.include?(nil) || values.uniq.length != values.length
+        end
+        node.children&.each { |child| validate_yaml_keys(child) }
+      end
+
+      def source_mapping(source, base)
+        mapping(source, %w[root include exclude prefix], "source")
+        root = File.expand_path(string(source["root"], "source root"), base)
+        fail_build("missing source root: #{root}") unless File.directory?(root)
+        includes = strings(source.fetch("include", ["**/*.rb"]), "include")
+        excludes = strings(source.fetch("exclude", []), "exclude")
+        (includes + excludes).each { |glob| relative(glob, "source glob") }
+        {root: root, include: includes, exclude: excludes, prefix: relative(source.fetch("prefix", ""), "prefix", empty: true)}
+      end
+
+      def mapping(value, keys, label)
+        fail_build("#{label} must be a mapping") unless value.is_a?(Hash)
+        unknown = value.keys - keys
+        fail_build("unknown #{label} fields: #{unknown.join(", ")}") unless unknown.empty?
+      end
+
+      def strings(value, label)
+        fail_build("#{label} must be an array") unless value.is_a?(Array)
+        value.each { |entry| string(entry, label) }
+        value
+      end
+
+      def string(value, label)
+        fail_build("#{label} must be a nonempty string") unless value.is_a?(String) && !value.empty? && !value.include?("\0")
+        value
+      end
+
+      def relative(value, label, empty: false)
+        return "" if empty && value == ""
+        string(value, label)
+        fail_build("#{label} must be a relative nonescaping path: #{value}") if Pathname.new(value).absolute? || value.split(/[\\\/]/).any? { |part| part == ".." || part == "." } || value.include?("\\")
+        value.sub(%r{/+\z}, "")
+      end
+
+      def fail_build(message)
+        raise BuildError.new(message, status: 2)
+      end
+    end
+  end
+end

data/lib/zard/doc/build_export.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module Zard
+  module Doc
+    class BuildExport
+      def initialize(configuration, documents, digests)
+        @configuration = configuration
+        @documents = documents
+        @digests = digests
+      end
+
+      def render(renderer, enricher: nil)
+        declarations = renderer.export_declarations
+        data = {schema: "zard-doc/v0", revision: 1,
+                producer: {zard: Zard::VERSION, zard_doc: Zard::Doc::VERSION},
+                layout: @configuration.layout,
+                scopes: @configuration.selected_scopes.map { |name| scope(name, declarations.fetch(name)) },
+                links: renderer.links.sort.to_h,
+                warnings: renderer.diagnostics.map { |message| relative_message(message) }}
+        data = enricher.call(data, base: @configuration.base) if enricher
+        JSON.pretty_generate(data) + "\n"
+      rescue JSON::GeneratorError => error
+        raise BuildError, "cannot export documentation JSON: #{error.message}"
+      end
+
+      private
+
+      def scope(name, entries)
+        config = @configuration.scopes.fetch(name)
+        declarations = entries.map { |entry| declaration(name, entry) }
+        {name: name, destination: config.fetch(:destination),
+         references: config.fetch(:references).uniq.sort,
+         files: @documents.fetch(name).sort_by(&:path).map { |document| source_file(document) },
+         declarations: declarations,
+         pages: declarations.group_by { |item| item.fetch(:page) }.sort.map do |path, items|
+           {path: path, declarations: items.map { |item| item.fetch(:id) }}
+         end}
+      end
+
+      def source_file(document)
+        {path: relative_path(document.path), digest: @digests.fetch(document.path),
+         diagnostics: document.diagnostics.map do |diagnostic|
+           {code: diagnostic.code, severity: diagnostic.severity,
+            message: relative_message(diagnostic.message), span: span(diagnostic.span)}
+         end}
+      end
+
+      def declaration(scope, entry)
+        item = entry.fetch(:declaration)
+        {id: "#{scope}:#{entry.fetch(:anchor)}", kind: item.kind, name: item.name,
+         namespace: item.namespace, display_name: entry.fetch(:display_name),
+         visibility: item.visibility, parameters: item.parameters,
+         parameter_details: item.parameter_details&.map do |parameter|
+           {kind: parameter.kind, name: parameter.name, source: parameter.source, span: span(parameter.span),
+            default: parameter.default, default_span: span(parameter.default_span)}
+         end,
+         page: entry.fetch(:page), anchor: entry.fetch(:anchor), references: entry.fetch(:references),
+         receiver: item.receiver, receiver_span: span(item.receiver_span),
+         refinement: item.refinement, refinement_span: span(item.refinement_span),
+         alias_target: item.alias_target, superclass: item.superclass, superclass_span: span(item.superclass_span),
+         container_builder: item.container_builder, container_builder_span: span(item.container_builder_span),
+         mixins: item.mixins.map { |mixin| {kind: mixin.kind, target: mixin.target, span: span(mixin.span)} },
+         relationships: entry.fetch(:relationships).map { |relationship| relationship.merge(span: span(relationship.fetch(:span))) },
+         span: span(item.span), comment_span: span(item.comment_span),
+         documentation: item.documentation.map { |tag| documentation(tag, entry.fetch(:descriptions).fetch(tag)) },
+         contracts: item.contracts.map { |contract| contract(contract) }}
+      end
+
+      def documentation(tag, rendered)
+        {name: tag.name, owner: tag.owner, subject: tag.subject, claim: tag.claim,
+         description: tag.description, rendered_description: rendered, raw: tag.raw, span: span(tag.span)}
+      end
+
+      def contract(item)
+        {channel: item.channel, payload: item.payload, note: item.note, raw: item.raw, span: span(item.span)}
+      end
+
+      def span(item)
+        return unless item
+
+        {path: relative_path(item.path), start_line: item.start_line, end_line: item.end_line,
+         start_column: item.start_column, end_column: item.end_column,
+         start_offset: item.start_offset, end_offset: item.end_offset}
+      end
+
+      def relative_path(path)
+        Pathname.new(path).relative_path_from(Pathname.new(@configuration.base)).to_s
+      end
+
+      def relative_message(message)
+        @digests.keys.sort_by { |path| -path.length }.reduce(message) do |text, path|
+          text.gsub(path, relative_path(path))
+        end
+      end
+    end
+  end
+end

data/lib/zard/doc/build_publisher.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "fileutils"
+require "tmpdir"
+require "pathname"
+
+module Zard
+  module Doc
+    class BuildPublisher
+      MANIFEST = ".zard-manifest.json"
+
+      def initialize(docroot)
+        expanded = File.expand_path(docroot)
+        fail_build("output symlink is not allowed: #{expanded}") if File.symlink?(expanded)
+        ancestor = File.dirname(expanded)
+        suffix = [File.basename(expanded)]
+        until File.exist?(ancestor) || File.symlink?(ancestor)
+          suffix.unshift(File.basename(ancestor))
+          ancestor = File.dirname(ancestor)
+        end
+        @docroot = File.join(File.realpath(ancestor), *suffix)
+        @case_insensitive = Dir.mktmpdir(".zard-case-", File.realpath(ancestor)) do |probe|
+          alternate = File.join(File.dirname(probe), File.basename(probe).swapcase)
+          File.exist?(alternate) && File.identical?(probe, alternate)
+        end
+      rescue SystemCallError => error
+        fail_build("cannot resolve documentation root: #{error.message}")
+      end
+
+      def scopes
+        manifest.fetch("scopes")
+      end
+
+      def publish(pages, selected_scopes: nil, scopes: {}, links: {})
+        previous = manifest
+        old_pages = previous.fetch("pages")
+        old_pages.each do |path, checksum|
+          target = safe_path(path)
+          fail_build("managed page was edited or removed: #{target}; restore it before rebuilding") unless File.file?(target) && Digest::SHA256.file(target).hexdigest == checksum
+        end
+        scope_map = selected_scopes ? previous.fetch("scopes").merge(selected_scopes) : scopes
+        validate_scopes(scope_map)
+        destinations = selected_scopes&.flat_map { |name, destination| [destination, previous.fetch("scopes")[name]] }&.compact
+        removed = old_pages.keys.select { |path| !selected_scopes || path == "index.md" || destinations.any? { |destination| path.start_with?(destination + "/") } }
+        retained = old_pages.except(*removed)
+        if selected_scopes && !retained.empty? && previous["version"] == 1
+          fail_build("retained pages lack link metadata; run a full build before rebuilding individual scopes")
+        end
+        pages.each do |path, content|
+          target = safe_path(path)
+          fail_build("page content must be text: #{path}") unless content.is_a?(String)
+          fail_build("output collides with retained scope: #{path}") if retained.key?(path)
+          if File.exist?(target) && !old_pages.key?(path)
+            owner = old_pages.keys.find { |old| File.identical?(safe_path(old), target) }
+            fail_build("output collides with retained scope: #{path}") if owner && retained.key?(owner)
+            fail_build("output collides with unowned file: #{target}") unless owner
+          end
+        end
+        all_paths = retained.keys + pages.keys
+        filesystem_paths = all_paths.map { |path| @case_insensitive ? path.downcase : path }
+        fail_build("output paths collide on this filesystem") if filesystem_paths.uniq.length != filesystem_paths.length
+        filesystem_paths.each { |path| fail_build("output file/directory collision: #{path}") if filesystem_paths.any? { |other| other.start_with?(path + "/") } }
+        checksums = retained.merge(pages.transform_values { |content| Digest::SHA256.hexdigest(content) })
+        combined_links = previous.fetch("links", {}).select { |path, _| retained.key?(path) }.merge(links)
+        validate_links(combined_links, checksums)
+        validate_link_destinations(combined_links, pages, retained)
+        payload = JSON.pretty_generate({"version" => 2, "pages" => checksums.sort.to_h, "scopes" => scope_map.sort.to_h, "links" => combined_links.sort.to_h}) + "\n"
+        transaction(pages.merge(MANIFEST => payload), (removed + pages.keys + [MANIFEST]).uniq)
+      rescue SystemCallError, IOError => error
+        fail_build("cannot publish documentation: #{error.message}")
+      end
+
+      private
+
+      def manifest
+        target = safe_path(MANIFEST, manifest: true)
+        return {"version" => 2, "pages" => {}, "scopes" => {}, "links" => {}} unless File.exist?(target)
+        fail_build("invalid manifest: #{target}") unless File.file?(target)
+        data = JSON.parse(File.read(target))
+        valid = data.is_a?(Hash) && data["pages"].is_a?(Hash) &&
+          ((data["version"] == 1 && data.keys.sort == %w[pages scopes version]) ||
+           (data["version"] == 2 && data.keys.sort == %w[links pages scopes version]))
+        fail_build("invalid manifest schema: #{target}") unless valid
+        data["pages"].each do |path, checksum|
+          safe_path(path)
+          fail_build("invalid manifest checksum for #{path}") unless checksum.is_a?(String) && /\A[0-9a-f]{64}\z/.match?(checksum)
+        end
+        validate_scopes(data["scopes"])
+        validate_links(data["links"], data["pages"]) if data["version"] == 2
+        data
+      rescue JSON::ParserError, SystemCallError => error
+        fail_build("cannot read generation manifest: #{error.message}")
+      end
+
+      def validate_links(links, pages)
+        fail_build("invalid manifest links") unless links.is_a?(Hash)
+        links.each do |source, targets|
+          fail_build("invalid manifest link source: #{source}") unless pages.key?(source) && targets.is_a?(Array)
+          targets.each do |target|
+            valid = target.is_a?(Hash) && target.keys.sort == %w[anchor path] &&
+              pages.key?(target["path"]) && target["anchor"].is_a?(String) && /\Azard-[0-9a-f]+\z/.match?(target["anchor"])
+            fail_build("retained or generated page #{source} has an invalid link target; include affected scopes or run a full build") unless valid
+          end
+        end
+      end
+
+      def validate_link_destinations(links, pages, retained)
+        contents = {}
+        links.each do |source, targets|
+          targets.each do |target|
+            path = target.fetch("path")
+            text = (contents[path] ||= pages.fetch(path) { File.read(safe_path(path)) })
+            next if text.include?(%(<a id="#{target.fetch("anchor")}"></a>))
+
+            label = retained.key?(source) ? "retained" : "generated"
+            fail_build("#{label} page #{source} links to a missing anchor in #{path}; include affected scopes or run a full build")
+          end
+        end
+      end
+
+      def validate_scopes(scope_map)
+        fail_build("invalid manifest scopes") unless scope_map.is_a?(Hash)
+        scope_map.each do |name, destination|
+          fail_build("invalid scope name") unless name.is_a?(String) && !name.empty?
+          safe_path(destination)
+        end
+        scope_map.to_a.combination(2) do |(left, a), (right, b)|
+          a = a.downcase if @case_insensitive
+          b = b.downcase if @case_insensitive
+          fail_build("overlapping scope destinations: #{left} and #{right}") if a == b || a.start_with?(b + "/") || b.start_with?(a + "/")
+        end
+      end
+
+      def safe_path(path, manifest: false)
+        invalid = !path.is_a?(String) || path.empty? || path.include?("\0") || path.include?("\\") || Pathname.new(path).absolute? || path.split("/", -1).any? { |part| ["", ".", ".."].include?(part) }
+        fail_build("unsafe output path: #{path.inspect}") if invalid || (!manifest && path == MANIFEST)
+        target = File.join(@docroot, path)
+        current = target
+        loop do
+          fail_build("output symlink is not allowed: #{current}") if File.symlink?(current)
+          parent = File.dirname(current)
+          break if parent == current
+          current = parent
+        end
+        target
+      end
+
+      def transaction(pages, affected)
+        FileUtils.mkdir_p(File.dirname(@docroot))
+        staging = Dir.mktmpdir(".zard-build-", File.dirname(@docroot))
+        backup = File.join(staging, "backup")
+        prepared = File.join(staging, "prepared")
+        existed = {}
+        affected.each do |path|
+          target = safe_path(path, manifest: path == MANIFEST)
+          existed[path] = File.file?(target)
+          next unless existed[path]
+          saved = File.join(backup, path)
+          FileUtils.mkdir_p(File.dirname(saved))
+          FileUtils.cp(target, saved)
+        end
+        pages.each do |path, content|
+          target = File.join(prepared, path)
+          FileUtils.mkdir_p(File.dirname(target))
+          File.write(target, content)
+        end
+        changed = []
+        begin
+          affected.each do |path|
+            target = safe_path(path, manifest: path == MANIFEST)
+            changed << path
+            if pages.key?(path)
+              FileUtils.mkdir_p(File.dirname(target))
+              File.rename(File.join(prepared, path), target)
+            elsif File.exist?(target)
+              File.unlink(target)
+            end
+          end
+        rescue SystemCallError, IOError, BuildError => error
+          begin
+            changed.reverse_each do |path|
+              target = safe_path(path, manifest: path == MANIFEST)
+              if existed[path]
+                FileUtils.cp(File.join(backup, path), target)
+              elsif File.file?(target)
+                File.unlink(target)
+              end
+            end
+          rescue SystemCallError, IOError, BuildError => recovery_error
+            retained_backup = true
+            fail_build("publication failed: #{error.message}; recovery failed: #{recovery_error.message}; restore files from #{backup}")
+          end
+          fail_build("publication failed; previous pages restored: #{error.message}")
+        end
+      ensure
+        FileUtils.remove_entry(staging) if staging && !retained_backup
+      end
+
+      def fail_build(message)
+        raise BuildError.new(message, status: 2)
+      end
+    end
+  end
+end