jekyll-obsidian-site 0.2.0

data/website/lib/jekyll_obsidian/raw_html_manifest.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JekyllObsidian
+  # Owns the serialized contract shared by the compiler, production audit, and
+  # URL verifier. Filesystem safety remains the responsibility of each
+  # consumer after this structural validation succeeds.
+  module RawHtmlManifest
+    PATH = "assets/website/raw-html.v1.json"
+    ROUTE = "/#{PATH}"
+    SCHEMA_VERSION = 1
+    KEYS = %w[documents files schema_version].freeze
+    DOCUMENT_KEYS = %w[output route].freeze
+
+    class Invalid < StandardError; end
+
+    module_function
+
+    def generate(documents:, files:)
+      # Destination preflight owns duplicate-route diagnostics and runs after
+      # the manifest object is assembled. Keep generation total so collisions
+      # remain structured compiler failures; readers still validate strictly.
+      payload = {
+        "schema_version" => SCHEMA_VERSION,
+        "documents" => documents,
+        "files" => files
+      }
+      "#{JSON.generate(payload)}\n"
+    end
+
+    def parse(content)
+      payload = JSON.parse(content)
+      validate!(payload)
+      payload
+    rescue JSON::ParserError => exception
+      raise Invalid, "invalid JSON: #{exception.message}"
+    end
+
+    def validate!(payload)
+      unless payload.is_a?(Hash) && payload.keys.sort == KEYS && payload["schema_version"] == SCHEMA_VERSION
+        raise Invalid, "expected the exact v#{SCHEMA_VERSION} object"
+      end
+
+      documents = payload["documents"]
+      files = payload["files"]
+      unless documents.is_a?(Array) && files.is_a?(Array) &&
+          documents.uniq == documents && files.uniq == files && files.all? { |route| route.is_a?(String) }
+        raise Invalid, "documents and files must be unique arrays"
+      end
+
+      documents.each do |document|
+        unless document.is_a?(Hash) && document.keys.sort == DOCUMENT_KEYS &&
+            document.values.all? { |value| value.is_a?(String) }
+          raise Invalid, "document entries must contain string route and output values"
+        end
+        unless files.include?(document.fetch("output"))
+          raise Invalid, "document output is not listed as a file: #{document.fetch('output').inspect}"
+        end
+      end
+
+      payload
+    end
+    private_class_method :validate!
+  end
+end

data/website/lib/jekyll_obsidian/runtime.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "date"
+require "fileutils"
+require "open3"
+require "pathname"
+require "rbconfig"
+require "tmpdir"
+require "yaml"
+require "jekyll"
+require_relative "version"
+require_relative "workspace_layout"
+require_relative "adapter"
+
+module JekyllObsidian
+  class Runtime
+    class Error < StandardError; end
+
+    PACKAGE_ROOT = File.realpath(File.expand_path("../..", __dir__))
+    CONFIG_PATH = ".github/jekyll-obsidian.yml"
+    PUBLIC_KEYS = %w[title description lang url baseurl website].freeze
+    SITE_OPTIONS = {
+      "safe" => false, "incremental" => false, "disable_disk_cache" => true,
+      "strict_front_matter" => true, "permalink" => "pretty", "encoding" => "UTF-8",
+      "markdown" => "kramdown", "highlighter" => "none", "plugins" => [], "plugins_dir" => [],
+      "liquid" => { "error_mode" => "strict", "strict_filters" => true, "strict_variables" => false }
+    }.freeze
+
+    attr_reader :root, :config_path, :cache_root, :destination, :assets_root
+
+    def self.discover_root(start = Dir.pwd)
+      Pathname.new(File.expand_path(start)).ascend do |path|
+        return path.to_s if File.exist?(path.join(CONFIG_PATH)) || File.symlink?(path.join(CONFIG_PATH))
+      end
+      raise Error, "Missing #{CONFIG_PATH}. Run jekyll-obsidian init from your repository root."
+    end
+
+    def initialize(root:, config_path: nil, assets_root: nil, destination_name: "site")
+      @root = File.realpath(root)
+      @config_path = config_path || File.join(@root, CONFIG_PATH)
+      @assets_root = assets_root || File.join(PACKAGE_ROOT, "assets")
+      @cache_root = File.join(@root, WorkspaceLayout::CACHE_DIRECTORY)
+      unless destination_name.match?(/\Asite(?:-[A-Za-z0-9][A-Za-z0-9._-]*)?\z/)
+        raise Error, "destination name must be site or site-NAME"
+      end
+      @destination = File.join(@cache_root, destination_name)
+    end
+
+    def configuration
+      WorkspaceLayout.assert_path!(@root, @config_path, "configuration")
+      raise Error, "configuration must be a regular file" unless File.file?(@config_path)
+
+      user = YAML.safe_load_file(@config_path, permitted_classes: [Date, Time], aliases: true)
+      raise Error, "#{CONFIG_PATH} must be a mapping" unless user.is_a?(Hash)
+      unknown = user.keys - PUBLIC_KEYS
+      raise Error, "unsupported site configuration: #{unknown.first}" unless unknown.empty?
+      if user.key?("website") && !user["website"].is_a?(Hash)
+        raise Error, "website must be a mapping"
+      end
+      defaults = YAML.safe_load_file(File.join(PACKAGE_ROOT, "_config.yml"), aliases: false)
+      Jekyll::Utils.deep_merge_hashes(defaults, user)
+    rescue Psych::Exception => exception
+      raise Error, "Cannot read #{CONFIG_PATH}: #{exception.message}"
+    end
+
+    def source_root(config = configuration)
+      source = WorkspaceLayout.relative_source(config.fetch("website").fetch("source"))
+      path = File.join(@root, source)
+      WorkspaceLayout.assert_path!(@root, path, "website.source")
+      raise Error, "website.source must be a directory: #{source}" unless File.directory?(path)
+      path
+    end
+
+    def build(url: nil, baseurl: nil, theme: nil, environment: "production", quiet: false)
+      config = configuration
+      config["website"]["theme"] = theme if theme
+      config["url"] = url unless url.nil?
+      config["baseurl"] = baseurl unless baseurl.nil?
+      validate_urls!(config, environment)
+      # Validate content before creating or changing any build state.
+      source_root(config)
+      with_lock do
+        runtime_root = prepare_runtime
+        staging = Dir.mktmpdir("site-build.", @cache_root)
+        previous_environment = ENV["JEKYLL_ENV"]
+        begin
+          ENV["JEKYLL_ENV"] = environment
+          site_config = Jekyll.configuration(config.merge(SITE_OPTIONS).merge(
+            "config" => [], "source" => runtime_root, "destination" => staging,
+            "cache_dir" => ".jekyll-cache", "quiet" => quiet,
+            "layouts_dir" => "_layouts", "includes_dir" => "_includes",
+            "data_dir" => "_data", "collections_dir" => "",
+            WorkspaceLayout::CONTEXT_KEY => { "workspace_root" => @root, "assets_root" => @assets_root }
+          ))
+          Jekyll::Site.new(site_config).process
+          audit!(staging, config, quiet:) if environment == "production"
+          publish!(staging)
+        ensure
+          previous_environment.nil? ? ENV.delete("JEKYLL_ENV") : ENV["JEKYLL_ENV"] = previous_environment
+          FileUtils.remove_entry(staging) if File.exist?(staging)
+        end
+      end
+      @destination
+    end
+
+    def clean
+      return unless File.exist?(@cache_root) || File.symlink?(@cache_root)
+
+      with_lock do
+        Dir.children(@cache_root).each do |entry|
+          next if %w[.lock .gitignore].include?(entry)
+
+          FileUtils.remove_entry(File.join(@cache_root, entry))
+        end
+      end
+    end
+
+    private
+
+    def validate_urls!(config, environment)
+      origin = config.fetch("url", "").to_s.delete_suffix("/")
+      baseurl = config.fetch("baseurl", "").to_s.delete_suffix("/")
+      if environment == "production" && origin.empty?
+        raise Error, "production builds require --url or url in #{CONFIG_PATH}"
+      end
+      unless origin.empty? || origin.match?(%r{\Ahttps?://(?:[A-Za-z0-9][A-Za-z0-9.-]*|\[[0-9A-Fa-f:]+\])(?::[0-9]+)?\z})
+        raise Error, "url must be an HTTP or HTTPS origin without a path, query, or fragment"
+      end
+      unless baseurl.empty? || (baseurl.match?(%r{\A(/[A-Za-z0-9._~!$&()*+,;=:@%-]+)+\z}) &&
+          baseurl.split("/").none? { |part| %w[. ..].include?(part) })
+        raise Error, "baseurl must be empty or a normalized site path such as /project"
+      end
+      config["url"] = origin
+      config["baseurl"] = baseurl
+    end
+
+    def with_lock
+      WorkspaceLayout.assert_path!(@root, @cache_root, "application cache", missing: true)
+      FileUtils.mkdir_p(@cache_root)
+      ignore = File.join(@cache_root, ".gitignore")
+      WorkspaceLayout.assert_path!(@root, ignore, "cache ignore file", missing: true)
+      File.write(ignore, "*\n") unless File.exist?(ignore)
+      lock_path = File.join(@cache_root, ".lock")
+      WorkspaceLayout.assert_path!(@root, lock_path, "build lock", missing: true)
+      File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock|
+        raise Error, "another jekyll-obsidian command is using this workspace" unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+        yield
+      ensure
+        lock.flock(File::LOCK_UN)
+      end
+    end
+
+    def prepare_runtime
+      runtime_root = File.join(@cache_root, "runtime")
+      WorkspaceLayout.assert_path!(@root, runtime_root, "Jekyll source", missing: true)
+      FileUtils.remove_entry(runtime_root) if File.exist?(runtime_root)
+      FileUtils.mkdir_p(runtime_root)
+      %w[_layouts _includes].each do |directory|
+        FileUtils.cp_r(File.join(PACKAGE_ROOT, directory), File.join(runtime_root, directory))
+      end
+      runtime_root
+    end
+
+    def audit!(staging, config, quiet:)
+      [
+        ["audit-site.rb", staging],
+        ["verify-site-urls.rb", staging, config.fetch("url"), config.fetch("baseurl")]
+      ].each do |script, *arguments|
+        output, status = Open3.capture2e(RbConfig.ruby, File.join(PACKAGE_ROOT, "scripts", script), *arguments)
+        raise Error, output.strip unless status.success?
+        puts output unless quiet
+      end
+    end
+
+    def publish!(staging)
+      WorkspaceLayout.assert_path!(@root, @destination, "destination", missing: true)
+      if File.exist?(@destination) && !File.directory?(@destination)
+        raise Error, "destination must be a directory"
+      end
+      backup = File.join(@cache_root, "site-backup")
+      raise Error, "stale site backup exists: #{backup}" if File.exist?(backup) || File.symlink?(backup)
+
+      moved_previous = false
+      begin
+        if File.exist?(@destination)
+          File.rename(@destination, backup)
+          moved_previous = true
+        end
+        File.rename(staging, @destination)
+      rescue SystemCallError
+        File.rename(backup, @destination) if moved_previous && !File.exist?(@destination)
+        raise
+      end
+      FileUtils.remove_entry(backup) if moved_previous
+    end
+  end
+end

data/website/lib/jekyll_obsidian/site_compilation.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "set"
+
+module JekyllObsidian
+  # Owns the impure boundary for remote build inputs. VaultCompiler remains a
+  # deterministic projection over one immutable snapshot.
+  class SiteCompilation
+    TRANSLATION_PREFIX = "_translations/"
+
+    PlannedReference = ImmutableRecord.define(:physical_path, :logical_path, :reference)
+
+    def self.compile(request, transport: nil, cache_root: nil, manifest: nil)
+      new(request, transport:, cache_root:, manifest:).compile
+    end
+
+    def initialize(request, transport:, cache_root:, manifest:)
+      @request = request
+      @transport = transport
+      @cache_root = cache_root
+      @manifest = manifest
+    end
+
+    def compile
+      baseline = VaultCompiler.compile(@request)
+      return baseline unless baseline.success?
+
+      plan, diagnostics = build_plan(baseline)
+      return failure(baseline.diagnostics + diagnostics) unless diagnostics.empty?
+      if plan.empty?
+        GitHubMarkdown.materialize([], manifest: @manifest) unless @manifest.nil?
+        return baseline
+      end
+
+      documents = GitHubMarkdown.materialize(
+        plan.map(&:reference),
+        transport: @transport,
+        cache_root: @cache_root,
+        manifest: @manifest
+      )
+      documents_by_path = plan.each_with_index.to_h do |item, index|
+        [item.physical_path, documents.fetch(index)]
+      end
+      snapshot = Snapshot.new(entries: @request.snapshot.entries.map do |entry|
+        document = documents_by_path[entry.path.to_s]
+        document ? SnapshotEntry.new(**entry.to_h.merge(external_document: document)) : entry
+      end)
+      final_request = BuildRequest.new(snapshot: snapshot, config: @request.config)
+      result = VaultCompiler.compile(final_request)
+      return result unless result.success?
+
+      BuildSuccess.new(**result.to_h.merge(
+        github_markdown_manifest: GitHubMarkdown.dump_manifest(documents)
+      ))
+    rescue GitHubMarkdown::ManifestError => exception
+      failure([diagnostic("github_markdown_manifest_invalid", exception.message)])
+    rescue GitHubMarkdown::Error => exception
+      failure([diagnostic("github_markdown_fetch_failed", exception.message)])
+    end
+
+    private
+
+    def build_plan(result)
+      published = result.notes.map(&:id).to_set
+      portfolio_path = configured_portfolio_path
+      physical_note_paths = @request.snapshot.entries.filter_map do |entry|
+        path = entry.path.to_s
+        path if entry.kind.to_sym == :note && !path.start_with?(TRANSLATION_PREFIX)
+      end
+      portfolio_index_path = DirectoryIndexes.resolve(physical_note_paths)[portfolio_path]
+      locales = Array(result.site_data.dig("website_i18n", "locales")).map { |item| item.fetch("code") }
+      default_locale = @request.config.lang.to_s
+      plan = []
+      diagnostics = []
+
+      @request.snapshot.entries.sort_by { |entry| entry.path.to_s.b }.each do |entry|
+        next unless entry.kind.to_sym == :note
+
+        physical_path = entry.path.to_s
+        locale, logical_path = translated_path(physical_path, locales, default_locale)
+        next if physical_path.start_with?(TRANSLATION_PREFIX) && locale.nil?
+
+        parsed = FrontMatter.parse(physical_path, entry.bytes.to_s)
+        reference = parsed.properties["github_markdown"]
+        next unless reference
+        next if parsed.properties["publish"] == false
+        next unless published_note?(published, logical_path, locale)
+
+        unless logical_path.start_with?("#{portfolio_path}/") && logical_path != portfolio_index_path
+          diagnostics << diagnostic(
+            "github_markdown_scope",
+            "github_markdown is only supported by project wrappers below the configured portfolio path",
+            physical_path
+          )
+          next
+        end
+        unless parsed.body.strip.empty?
+          diagnostics << diagnostic(
+            "github_markdown_body_conflict",
+            "a github_markdown project wrapper must have an empty local body",
+            physical_path
+          )
+          next
+        end
+
+        plan << PlannedReference.new(
+          physical_path: physical_path,
+          logical_path: logical_path,
+          reference: reference
+        )
+      end
+      [plan.freeze, diagnostics.freeze]
+    end
+
+    def configured_portfolio_path
+      navigation = @request.config.navigation
+      value = navigation.is_a?(Hash) ? navigation.dig("portfolio", "path") : nil
+      (value || "portfolio").to_s.unicode_normalize(:nfc)
+    end
+
+    def translated_path(path, locales, default_locale)
+      return [nil, path] unless path.start_with?(TRANSLATION_PREFIX)
+
+      suffix = path.delete_prefix(TRANSLATION_PREFIX)
+      locale, logical = suffix.split("/", 2)
+      return [nil, nil] unless logical && locale != default_locale && locales.include?(locale)
+
+      [locale, logical]
+    end
+
+    def published_note?(published, logical_path, locale)
+      return published.include?(logical_path) unless locale
+
+      published.include?(logical_path) && published.include?("#{locale}:#{logical_path}")
+    end
+
+    def diagnostic(code, message, path = nil)
+      Diagnostic.new(severity: :error, code: code, message: message, path: path, span: nil)
+    end
+
+    def failure(diagnostics)
+      BuildFailure.new(diagnostics: diagnostics.sort_by do |item|
+        [item.path.to_s, item.code.to_s, item.message.to_s]
+      end.freeze)
+    end
+  end
+end