pandorga 1.2.1

data/_plugins/content_writing_index.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "date"
+require "pathname"
+require "set"
+require "yaml"
+
+require_relative "git_chronology"
+require_relative "content_keys"
+require_relative "content_writing_paths"
+require_relative "lib/text_excerpt"
+require_relative "lib/writing_entry"
+
+# Indexes articles and posts from /content for timeline and network features
+# without emitting Jekyll collection pages (those load from the content API).
+module Jekyll
+  class ContentWritingIndex < Generator
+    safe true
+    priority :high
+
+
+    def generate(site)
+      return if site.config["shell_content_agnostic"]
+
+      content_root = File.join(site.source, site.config["content_root"] || "content")
+      entries = []
+
+      if File.directory?(content_root)
+        ContentWritingPaths::INDEX_BY_COLLECTION.each do |collection, relative_path|
+          directory = File.join(content_root, relative_path)
+          next unless File.directory?(directory)
+
+          Dir.glob(File.join(directory, "*.{md,markdown}")).sort.each do |absolute_path|
+            entry = build_entry(absolute_path, collection)
+            entries << entry if entry
+          end
+        end
+      end
+
+      site.data["writing_index"] = entries
+    end
+
+    private
+
+    def build_entry(absolute_path, collection)
+      repo_relative_path = ContentWritingPaths.repo_relative_for_index_collection(
+        collection, File.basename(absolute_path)
+      )
+      WritingEntry.build(absolute_path, collection, repo_relative_path)
+    end
+  end
+end

data/_plugins/content_writing_paths.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Canonical filesystem locations for articles and posts under content/.
+# Shared by writing indexers, slug validation, and content-key resolution.
+module ContentWritingPaths
+  CONTENT_ROOT_SEGMENT = "content"
+
+  BY_COLLECTION = {
+    "articles" => "collections/articles",
+    "posts" => "collections/posts"
+  }.freeze
+
+  BY_TYPE = {
+    "article" => "collections/articles",
+    "post" => "collections/posts"
+  }.freeze
+
+  TYPE_FOR_COLLECTION = {
+    "articles" => "article",
+    "posts" => "post"
+  }.freeze
+
+  COLLECTION_FOR_TYPE = TYPE_FOR_COLLECTION.invert.freeze
+
+  # Slim runtime index covers every keyed collection xcite can resolve.
+  INDEX_BY_COLLECTION = BY_COLLECTION.merge(
+    "products" => "collections/products",
+    "projects" => "collections/projects"
+  ).freeze
+
+  INDEX_TYPE_FOR_COLLECTION = TYPE_FOR_COLLECTION.merge(
+    "products" => "product",
+    "projects" => "project"
+  ).freeze
+
+  module_function
+
+  def content_relative(type_or_collection)
+    BY_COLLECTION[type_or_collection] || BY_TYPE.fetch(type_or_collection)
+  end
+
+  def repo_relative(type)
+    File.join(CONTENT_ROOT_SEGMENT, BY_TYPE.fetch(type))
+  end
+
+  def repo_relative_for_collection(collection, filename = nil)
+    base = File.join(CONTENT_ROOT_SEGMENT, BY_COLLECTION.fetch(collection))
+    filename ? File.join(base, filename) : base
+  end
+
+  def repo_relative_for_index_collection(collection, filename = nil)
+    base = File.join(CONTENT_ROOT_SEGMENT, INDEX_BY_COLLECTION.fetch(collection))
+    filename ? File.join(base, filename) : base
+  end
+end

data/_plugins/force_utf8_encoding.rb

@@ -0,0 +1,13 @@
+# Force UTF-8 as the process-wide default encoding.
+#
+# Some build environments (e.g. the Cloudflare build image) run under a non-UTF-8
+# locale such as `C`/`POSIX`, which makes Ruby's `Encoding.default_external` be
+# US-ASCII. Jekyll/kramdown then raise "The source text contains invalid
+# characters for the used encoding US-ASCII" when rendering non-ASCII content
+# (accents, em-dashes, etc.). Netlify defaulted to a UTF-8 locale, which hid this.
+#
+# Plugins are loaded before content is read and rendered, so setting the defaults
+# here makes the build locale-independent regardless of how `jekyll build` is
+# invoked. This is a no-op where the locale is already UTF-8 (local dev, CI).
+Encoding.default_external = Encoding::UTF_8 unless Encoding.default_external == Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8 unless Encoding.default_internal == Encoding::UTF_8

data/_plugins/git_chronology.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "date"
+require "shellwords"
+require "open3"
+
+# Derives publication and last-modification dates for articles and posts.
+# Shared by the content JSON export script and Jekyll build-time indexers.
+#
+# `date` — editorial creation date: front matter `date`, else the YYYY-MM-DD filename
+#   prefix, else the first Git add (legacy files without a dated name).
+# `last_updated` — latest commit where the markdown body (after the closing ---) changed;
+#   front-matter-only edits do not advance it.
+#
+# Pitfall (see docs/content/architecture.md): history often crosses renames. git log --follow
+# reaches pre-migration commits, but git show <sha>:<current-path> does not — the path did
+# not exist yet. A failed show must never be treated as an empty body; resolve the path per
+# commit via git_commit_entries (--name-only) before comparing bodies.
+module GitChronology
+  WRITING_TYPES = %w[article post].freeze
+  FILENAME_DATE_RE = /\A(\d{4}-\d{2}-\d{2})-/.freeze
+
+  module_function
+
+  def reset_cache!
+    @chronology_memo = {}
+  end
+
+  def git_repo?
+    system("git rev-parse --is-inside-work-tree > /dev/null 2>&1")
+  end
+
+  def git_date(repo_relative_path, mode)
+    return nil unless git_repo?
+
+    path = repo_relative_path.to_s
+    case mode
+    when :creation
+      raw_out, _status = Open3.capture2("git", "log", "--follow", "--diff-filter=A", "--format=%ad", "--date=short", "--", path)
+      raw = raw_out.strip.split("\n").last
+    when :updated
+      # AM skips pure rename/copy commits (e.g. content migration) while still
+      # returning the add date for files that have only been created once.
+      raw_out, _status = Open3.capture2("git", "log", "--follow", "--diff-filter=AM", "-1", "--format=%ad", "--date=short", "--", path)
+      raw = raw_out.strip
+    else
+      return nil
+    end
+
+    raw unless raw.nil? || raw.empty?
+  end
+
+  def split_front_matter(text)
+    text = text.to_s.sub(/\A\xEF\xBB\xBF/, "")
+    return ["", text] unless text.start_with?("---\n")
+
+    parts = text.split(/^---\s*$\n?/, 3)
+    return ["", text] unless parts.length == 3
+
+    [parts[1], parts[2]]
+  end
+
+  def markdown_body(text)
+    _front_matter, body = split_front_matter(text)
+    body
+  end
+
+  # Chronology compares semantic body content, not formatting noise from CMS saves
+  # (line endings, trailing spaces, or blank lines added/removed without text edits).
+  def normalize_body_for_chronology(body)
+    body.to_s
+        .gsub(/\r\n?/, "\n")
+        .each_line
+        .map(&:strip)
+        .reject(&:empty?)
+        .join("\n")
+  end
+
+  def bodies_changed_for_chronology?(body_a, body_b)
+    normalize_body_for_chronology(body_a) != normalize_body_for_chronology(body_b)
+  end
+
+  SHA_RE = /\A[0-9a-f]{40}\z/i
+
+  # Newest-first [commit_sha, repo_relative_path_at_that_commit] pairs.
+  #
+  # --follow alone is insufficient for body chronology: each revision must be read at the
+  # path that existed in that commit (_posts/… before the 2026-06-19 content/ migration,
+  # content/collections/posts/… after). Without --name-only, git show sha:current_path
+  # fails on older commits and last_updated incorrectly snaps to the rename date.
+  def git_commit_entries(repo_relative_path)
+    return [] unless git_repo?
+
+    path = repo_relative_path.to_s
+    out, _status = Open3.capture2("git", "log", "--follow", "--name-only", "--format=%H", "--", path)
+    lines = out.each_line.map(&:strip).reject(&:empty?)
+    return [] if lines.empty?
+
+    entries = []
+    index = 0
+    while index < lines.length
+      sha = lines[index]
+      break unless sha.match?(SHA_RE)
+
+      index += 1
+      paths = []
+      while index < lines.length && !lines[index].match?(SHA_RE)
+        paths << lines[index]
+        index += 1
+      end
+
+      path_at_commit = paths.empty? ? repo_relative_path.to_s : pick_path_at_commit(paths, repo_relative_path)
+      entries << [sha, path_at_commit]
+    end
+    entries
+  end
+
+  def pick_path_at_commit(paths, repo_relative_path)
+    basename = File.basename(repo_relative_path.to_s)
+    paths.find { |candidate| candidate.end_with?(basename) } || paths.last
+  end
+
+  def commit_date(sha)
+    out, _status = Open3.capture2("git", "log", "-1", "--format=%ad", "--date=short", sha)
+    out.strip
+  end
+
+  def file_content_at_commit(path_at_commit, sha)
+    # path_at_commit comes from git_commit_entries, not the caller's present-day path.
+    path = path_at_commit.to_s
+    content, status = Open3.capture2("git", "show", "#{sha}:#{path}", err: File::NULL)
+    return nil unless status.success?
+    return nil if content.nil? || content.empty?
+
+    content
+  end
+
+  def git_body_updated_date(repo_relative_path)
+    entries = git_commit_entries(repo_relative_path)
+    return nil if entries.empty?
+
+    # Walk newest → oldest; stop at the first pair where bodies differ.
+    # Do not substitute "" when file_content_at_commit returns nil — that was the
+    # migration bug (missing historical path read as an empty body edit).
+    entries.each_with_index do |(sha, path_at_commit), idx|
+      body = markdown_body(file_content_at_commit(path_at_commit, sha) || "")
+      if idx == entries.length - 1
+        return nil
+      end
+
+      older_sha, older_path = entries[idx + 1]
+      older_body = markdown_body(file_content_at_commit(older_path, older_sha) || "")
+      return commit_date(sha) if bodies_changed_for_chronology?(body, older_body)
+    end
+
+    nil
+  end
+
+  def filename_date(repo_relative_path)
+    stem = File.basename(repo_relative_path.to_s, File.extname(repo_relative_path.to_s))
+    match = stem.match(FILENAME_DATE_RE)
+    normalize_date_value(match[1]) if match
+  end
+
+  def editorial_date(front_matter, repo_relative_path)
+    normalize_date_value(front_matter["date"]) ||
+      filename_date(repo_relative_path) ||
+      git_date(repo_relative_path, :creation)
+  end
+
+  def chronology_for(repo_relative_path, type: nil, front_matter: nil)
+    return {} unless type.nil? || WRITING_TYPES.include?(type)
+
+    @chronology_memo ||= {}
+    memo_key = [repo_relative_path.to_s, type, normalize_date_value(front_matter&.dig("date"))]
+    return @chronology_memo[memo_key] if @chronology_memo.key?(memo_key)
+
+    fm = front_matter || {}
+    creation = editorial_date(fm, repo_relative_path)
+    updated = git_body_updated_date(repo_relative_path)
+    last_updated = updated || creation
+
+    result = {}
+    result["date"] = creation if creation
+    result["last_updated"] = last_updated if last_updated
+    @chronology_memo[memo_key] = result
+    result
+  end
+
+  def normalize_date_value(value)
+    case value
+    when Date then value.iso8601
+    when Time then value.to_date.iso8601
+    when String
+      stripped = value.strip
+      stripped.empty? ? nil : stripped
+    else
+      raw = value&.to_s&.strip
+      raw.nil? || raw.empty? ? nil : raw
+    end
+  end
+
+  def apply!(front_matter, repo_relative_path, type)
+    return front_matter unless WRITING_TYPES.include?(type)
+
+    chronology = chronology_for(repo_relative_path, type: type, front_matter: front_matter)
+    front_matter["date"] = chronology["date"] if chronology["date"]
+    front_matter["last_updated"] = chronology["last_updated"] if chronology["last_updated"]
+    front_matter
+  end
+end

data/_plugins/git_metadata.rb

@@ -0,0 +1,43 @@
+require 'date'
+require 'time'
+
+# This plugin automatically derives 'date' and 'last_updated' from Git history
+# for articles and posts, ensuring Git is the single source of truth for chronology.
+module Jekyll
+  class GitMetadataGenerator < Generator
+    safe true
+    priority :high
+
+    def generate(site)
+      return unless GitChronology.git_repo?
+
+      article_docs = site.collections["articles"]&.docs || []
+      post_docs = site.collections["posts"]&.docs || []
+      return if article_docs.empty? && post_docs.empty?
+
+      (article_docs + post_docs).each do |doc|
+        next unless doc.path.match?(/\.(md|markdown)$/)
+
+        doc.data['language'] = doc.collection.label == 'articles' ? 'enus' : 'ptbr'
+        GitChronology.apply!(doc.data, doc.path, doc.collection.label == 'articles' ? 'article' : 'post')
+
+        if doc.data['date']
+          begin
+            doc.data['date'] = Time.parse(doc.data['date'].to_s)
+          rescue ArgumentError
+          end
+        end
+
+        if doc.data['last_updated']
+          begin
+            doc.data['last_updated'] = Time.parse(doc.data['last_updated'].to_s)
+          rescue ArgumentError
+          end
+        end
+      end
+
+      article_docs.sort_by! { |d| d.data['last_updated'] || d.data['date'] || Time.now }.reverse!
+      post_docs.sort_by! { |d| d.data['last_updated'] || d.data['date'] || Time.now }.reverse!
+    end
+  end
+end

data/_plugins/job_sections.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Renders the private CV job body fields to HTML for the print layouts,
+# storing the result in doc.data["extended"/"single_page"].
+# body_public is not rendered here: the public CV page reads it straight
+# from the exported JSON through the client-side runtime.
+module Jekyll
+  class JobSectionsGenerator < Generator
+    safe true
+    priority :high
+
+    def generate(site)
+      return if site.config["shell_content_agnostic"]
+
+      converter = site.find_converter_instance(Jekyll::Converters::Markdown)
+
+      (site.collections["jobs"]&.docs || []).each do |doc|
+        %w[extended single_page].each do |key|
+          markdown = doc.data["body_#{key}"].to_s.strip
+          doc.data[key] = converter.convert(markdown) unless markdown.empty?
+        end
+      end
+    end
+  end
+end

data/_plugins/lib/content_validators.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "resource_validator"
+require_relative "tag_validator"
+require_relative "../writing_slug_limits"
+require_relative "../content_keys"
+
+# Single validation entry point for editorial content under content/.
+module ContentValidators
+  module_function
+
+  def validate_all!(repo_root = Pathname.pwd)
+    root = Pathname.new(repo_root)
+    errors = []
+    errors.concat(ResourceValidator.collect_errors(root))
+    errors.concat(TagValidator.collect_errors(root))
+    errors.concat(WritingSlugLimits.collect_errors(root))
+
+    unless errors.empty?
+      raise ArgumentError, "Content validation failed:\n  - #{errors.join("\n  - ")}"
+    end
+
+    ContentKeys.validate!(root)
+  end
+end

data/_plugins/lib/resource_validator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+# Shared resource collection validation (content/ source, not Jekyll collections).
+module ResourceValidator
+  module_function
+
+  def split_front_matter(text)
+    text = text.to_s.sub(/\A\xEF\xBB\xBF/, "")
+    return [{}, text] unless text.start_with?("---\n")
+
+    parts = text.split(/^---\s*$\n?/, 3)
+    return [{}, text] unless parts.length == 3
+
+    data = YAML.safe_load(parts[1], permitted_classes: [Date, Time], aliases: true) || {}
+    [data, parts[2]]
+  end
+
+  def collect_errors(repo_root)
+    root = Pathname.new(repo_root)
+    resources_dir = root.join("content/collections/resources")
+    return [] unless resources_dir.directory?
+
+    errors = []
+    resources_dir.glob("*.{md,markdown}").sort.each do |source|
+      front_matter, = split_front_matter(source.read)
+      name = front_matter["name"] || source.basename(source.extname).to_s
+      type = front_matter["type"].to_s.downcase
+      link = front_matter["link"].to_s
+
+      if link.empty?
+        errors << "#{name}: missing required 'link' field"
+        next
+      end
+
+      case type
+      when "youtube"
+        unless link.match?(%r{\Ahttps?://(www\.)?(youtube\.com|youtu\.be)/}i)
+          errors << "#{name}: type 'youtube' but link does not point to youtube.com or youtu.be (got: #{link})"
+        end
+      when "spotify"
+        unless link.match?(%r{\Ahttps?://(open\.)?spotify\.com/}i)
+          errors << "#{name}: type 'spotify' but link does not point to spotify.com (got: #{link})"
+        end
+      when "pdf"
+        unless link.end_with?(".pdf")
+          errors << "#{name}: type 'pdf' but link does not end with .pdf (got: #{link})"
+        end
+      end
+    end
+
+    errors
+  end
+end

data/_plugins/lib/tag_validator.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+require "date"
+
+# Tags replaced category as the single classification axis for articles and
+# rascunhos. Vocabulary is closed per collection and loaded from
+# `_config.yml` → `pandorga.taxonomies` (PLT Phase 1).
+module TagValidator
+  DEFAULT_MAX_TAGS = 3
+
+  COLLECTIONS_WITHOUT_REQUIRED_TAGS = %w[posts].freeze
+
+  module_function
+
+  def load_vocabularies(repo_root = Pathname.pwd)
+    root = Pathname.new(repo_root)
+    config_path = root.join("_config.yml")
+    return {} unless config_path.file?
+
+    config = YAML.safe_load(config_path.read, permitted_classes: [Date, Time], aliases: true) || {}
+    vocab = {}
+
+    taxonomies = config.dig("pandorga", "taxonomies")
+    if taxonomies.is_a?(Hash)
+      taxonomies.each do |collection, spec|
+        next unless spec.is_a?(Hash)
+
+        tags = spec["tags"]
+        next unless tags.is_a?(Array)
+
+        vocab[collection.to_s] = tags.map(&:to_s).freeze
+      end
+    end
+
+    # Page-local taxonomy (pandorga.pages[].taxonomy) fills gaps.
+    pages = config.dig("pandorga", "pages")
+    if pages.is_a?(Array)
+      pages.each do |page|
+        next unless page.is_a?(Hash)
+
+        collection = page["collection"].to_s
+        next if collection.empty? || vocab.key?(collection)
+
+        spec = page["taxonomy"]
+        next unless spec.is_a?(Hash)
+
+        tags = spec["tags"]
+        next unless tags.is_a?(Array)
+
+        vocab[collection] = tags.map(&:to_s).freeze
+      end
+    end
+
+    vocab
+  end
+
+  def max_tags_for(collection, repo_root = Pathname.pwd)
+    root = Pathname.new(repo_root)
+    config_path = root.join("_config.yml")
+    return DEFAULT_MAX_TAGS unless config_path.file?
+
+    config = YAML.safe_load(config_path.read, permitted_classes: [Date, Time], aliases: true) || {}
+    max = config.dig("pandorga", "taxonomies", collection.to_s, "max")
+    if max.nil?
+      pages = config.dig("pandorga", "pages")
+      if pages.is_a?(Array)
+        page = pages.find { |p| p.is_a?(Hash) && p["collection"].to_s == collection.to_s }
+        max = page.dig("taxonomy", "max") if page.is_a?(Hash)
+      end
+    end
+    max.nil? ? DEFAULT_MAX_TAGS : Integer(max)
+  rescue ArgumentError, TypeError
+    DEFAULT_MAX_TAGS
+  end
+
+  def collect_errors(repo_root = Pathname.pwd)
+    root = Pathname.new(repo_root)
+    errors = []
+    vocabulary = load_vocabularies(root)
+
+    if vocabulary.empty?
+      errors << "_config.yml: pandorga.taxonomies is missing or empty"
+      return errors
+    end
+
+    vocabulary.each do |collection, allowed|
+      dir = root.join("content", "collections", collection)
+      next unless dir.directory?
+
+      tags_required = !COLLECTIONS_WITHOUT_REQUIRED_TAGS.include?(collection)
+      max_tags = max_tags_for(collection, root)
+
+      Dir.glob(dir.join("*.md")).sort.each do |path|
+        relative = Pathname.new(path).relative_path_from(root)
+        front_matter = read_front_matter(path)
+        next if front_matter.nil?
+
+        if front_matter.key?("category")
+          errors << "#{relative}: uses `category`; tags replaced it as the " \
+                    "single classification axis"
+        end
+
+        tags = front_matter["tags"]
+        if tags.nil?
+          errors << "#{relative}: missing `tags`" if tags_required
+          next
+        end
+
+        unless tags.is_a?(Array)
+          errors << "#{relative}: `tags` must be a list, got #{tags.class}"
+          next
+        end
+
+        if tags.empty?
+          errors << "#{relative}: `tags` is empty; every entry needs at least one" if tags_required
+          next
+        end
+
+        if tags.size > max_tags
+          errors << "#{relative}: #{tags.size} tags exceeds the #{max_tags} " \
+                    "allowed — pick the ones that would actually be filtered on"
+        end
+
+        if tags.uniq.size != tags.size
+          errors << "#{relative}: duplicate tags #{(tags - tags.uniq).uniq.inspect}"
+        end
+
+        unknown = tags.reject { |tag| allowed.include?(tag.to_s) }
+        next if unknown.empty?
+
+        errors << "#{relative}: unknown #{collection} tag(s) #{unknown.inspect}. " \
+                  "Allowed: #{allowed.join(', ')}"
+      end
+    end
+
+    errors
+  end
+
+  def read_front_matter(path)
+    source = File.read(path)
+    return nil unless source.start_with?("---")
+
+    raw = source.split(/^---\s*$/, 3)[1]
+    return nil if raw.nil?
+
+    parsed = YAML.safe_load(raw, permitted_classes: [Date, Time], aliases: true)
+    parsed.is_a?(Hash) ? parsed : nil
+  rescue Psych::SyntaxError
+    nil
+  end
+end