# kettle-jem configuration file
#
# This file is both configuration and field guide for templated gems.
# In most projects this comment block is the first place to look when you
# want to understand what kettle-jem will merge, what it will copy as-is,
# and which values you may want to customize.
#
# High-level structure:
#   defaults  - default merge behavior for files that use strategy: merge
#   tokens    - values for {KJ|...} placeholders used across template files
#   patterns  - glob-based overrides for files/directories
#   files     - exact per-file overrides using a nested directory tree
#
# Default behavior:
#   If a file is NOT mentioned under files: and does NOT match a patterns:
#   entry, kettle-jem will merge it using the format-aware merge gem for that
#   file type.
#
# Strategies:
#   merge:
#     Resolve tokens, then merge template + destination using the appropriate
#     AST-aware/text-aware merger for the file type.
#   accept_template:
#     Resolve tokens, then write the template result without merging.
#     If the file is missing in the destination, it will be created from the template.
#   keep_destination:
#     Ignore this file during templating.
#     No merge. No replacement. No creation when the destination file is missing.
#     Use this when you want to permanently exclude a file from the template.
#   raw_copy:
#     Copy bytes exactly as they appear in the template.
#     No token resolution. No merge. Use for immutable/binary assets such as certs.
#
# Merge options (used only with strategy: merge):
#   preference:
#     template    - template wins when both sides define the same node/value
#     destination - destination wins when both sides define the same node/value
#   add_template_only_nodes:
#     true  - add nodes/entries that exist only in the template
#     false - do not add template-only nodes
#   freeze_token:
#     Marker name used for frozen sections (default: kettle-jem)
#   file_type:
#     Optional explicit merge-engine hint for extensionless or ambiguous files.
#     Supported values: ruby, gemfile, appraisals, gemspec, rakefile,
#     yaml, markdown, text, json, jsonc, toml, dotenv, rbs
#     Runtime-gated values requiring provider availability: bash
#   max_recursion_depth:
#     Limit for recursive merging when a merger supports it
#
# Other per-file options (apply to any strategy):
#   skip_unresolved_scan:
#     true  - do not scan this file for unresolved {KJ|...} tokens after writing.
#             Use when a file legitimately contains {KJ|...} text as documentation
#             or example content rather than as a template placeholder.
#
# Token values:
#   Precedence is:
#     1) ENV variables. During templating, known ENV-backed values are also
#        written back into this file so config and runtime agree.
#     2) tokens: values in this file
#     3) safe automatic derivation (author fields only, where possible)
#
# Safe automatic derivations currently implemented:
#   AUTHOR:NAME         <- first author from the gemspec
#   AUTHOR:EMAIL        <- first email from the gemspec
#   AUTHOR:DOMAIN       <- domain part of AUTHOR:EMAIL
#   AUTHOR:GIVEN_NAMES  <- AUTHOR:NAME minus the last word
#   AUTHOR:FAMILY_NAMES <- last word of AUTHOR:NAME
#
# Everything else should be set explicitly here or via ENV.

# This project's identifying emoji.
# Used as the leading emoji in the README H1 heading and in the gemspec
# summary and description. Every gem should have its own unique emoji.
#
# Set this to a single emoji that represents your gem. Examples: 🪙 🔑 🛠️ 🔮
# This key is REQUIRED. kettle-jem will abort if it is absent.
# ENV override: KJ_PROJECT_EMOJI
project_emoji: 🔮

# Engines this project supports.
# List the Ruby engines that your gem targets. kettle-jem uses this to decide
# which CI workflows, README compatibility rows, and badge references to
# include. Engines not listed here are pruned from generated files.
#
# Supported values: ruby, jruby, truffleruby
# Default (when key is absent): all three engines.
engines:
  - ruby
  - jruby
  - truffleruby

# Ruby version policy.
ruby:
  # Lowest MRI Ruby version for generated CI workflows, Appraisals, and
  # test/development dependency assumptions. This is intentionally separate
  # from the gemspec required_ruby_version, which describes the published
  # runtime contract. Effective CI minimum is max(gemspec minimum, this value).
  test_minimum: "2.4"

# RubyGems packaging/runtime shape.
rubygems:
  # Published runtime Ruby floor used for generated gemspec metadata and README
  # compatibility text. Omit this to derive the value from the gemspec.
  min_ruby: "2.3"

# Repository URL topology.
# This is independent from templates.profile. A gem may use the full template
# while still living as a sub-project inside a monorepo.
#
# Supported values:
#   standalone          - project URLs point at this gem's own repository
#   monorepo-subproject - project URLs point at a subdirectory in the repository root
#
# ENV override: KJ_REPOSITORY_TOPOLOGY
repository:
  topology: "standalone"

# Framework matrix workflows.
# When your gem tests against multiple versions of a framework (Rails,
# ActiveRecord, ActiveSupport, etc.), this section configures how
# kettle-jem generates the CI matrix strategy and gemfile references.
#
# preset: controls overall workflow strategy
#   modern       — Ruby-only matrix (default when absent)
#   framework    — Ruby × framework-version matrix
#   legacy-compat — supported / unsupported / ancient workflow split
#
# framework_matrix (only used when preset: framework):
#   dimension   — framework name used in the matrix key and display
#                 (e.g. activerecord, rails, actionmailer)
#   gem         — gem name to write into generated framework gemfiles.
#                 Defaults to dimension when absent.
#   versions    — ordered list of versions to test against. Entries may be
#                 strings, or mappings with:
#                   label       - display value used in CI
#                   slug        - path-safe value used in gemfile_pattern
#                   requirement - Bundler requirement written to the gemfile
#   gemfile_pattern — pattern for gemfile paths; {version} is replaced
#                     with each version slug (dots replaced by underscores
#                     when the pattern contains an underscore placeholder).
#                     Resolved relative to gemfiles/ unless it already contains
#                     a directory.
#                     Examples:
#                       "ar-{version}.x"      → gemfiles/ar-7.0.x
#                       "rails_{version}"      → gemfiles/rails_7_0.gemfile
#   Use this when you need a simple 2D matrix: Ruby × one framework gem/version axis.
#   For deeper or more complex matrices that are better modeled as Appraisals entries,
#   prefer kettle-jem-appraisals instead.
#
workflows:
  # Default command used by generated test workflows.
  # ENV override: KJ_EXEC_CMD
  exec_cmd: kettle-test
  # Include VCR/WebMock recording modular gemfiles in generated Appraisals.
  # Enable only for projects that actually require recording support.
  recording: false
  # preset: framework
  # framework_matrix:
  #   dimension: activerecord
  #   gem: activerecord
  #   versions:
  #     - "7.0"
  #     - "7.1"
  #     - "7.2"
  #     - label: "8.0+"
  #       slug: "8_0_plus"
  #       requirement: ">= 8.0"
  #   gemfile_pattern: "ar-{version}.x"

# README top logos.
# Comma-separated list of optional logo entries for the generated README header.
# top_logos render above the title; h2_synopsis_logos render inline with the Synopsis H2.
# Supported values: related-org, ruby, org, project, optionally followed by |width.
# Examples: org|12%, ruby|96px
# Default widths: top 1 logo => 14%, top 2 logos => 12%, Synopsis 1 logo => 10%, Synopsis 2 logos => 8%.
# Default (when keys are absent): top_logos: org,project; h2_synopsis_logos: related-org,ruby
# Legacy top_logo_mode values map as:
#   org => related-org,ruby,org
#   project => related-org,ruby,project
#   org_and_project => related-org,ruby,org,project
readme:
  top_logos: org
  h2_synopsis_logos: related-org,ruby
  # Optional package-family README block.
  # Supported values: structuredmerge
  # Leave unset for standalone kettle-rb gems and most projects.
  # package_family: structuredmerge
  # Sections to preserve from the destination README during template merging.
  # These section headings (case-insensitive) will keep the destination body
  # instead of being overwritten by the template. Default when absent:
  #   - synopsis
  #   - configuration
  #   - basic usage
  #
  # Built-in aliases (destination → template):
  #   summary → synopsis, usage → basic usage,
  #   configuration options → configuration, setup → basic usage
  #
  # preserve_sections:
  #   - synopsis
  #   - configuration
  #   - basic usage
  #   - usage
  #   - summary
  #
  # Glob patterns for additional sections to preserve (e.g. Note:* headings).
  # Default when absent: ["note:*"]
  #
  # preserve_patterns:
  #   - "note:*"
  #   - "setup*"
  #
  # Custom section aliases (destination heading → canonical template heading).
  # Merged with built-in aliases above.
  #
  # section_aliases:
  #   howto: basic usage
  #   options: configuration
  # README badges managed by the template.
  badges:
    # FOSSA license/security status badge.
    # false - omit the badge (default)
    # true  - derive project id from the GitHub repository slug
    # string or mapping project/project_id/slug - explicit FOSSA project id
    #
    # Example:
    # fossa: git+github.com/pboling/example
    fossa: false

# SPDX license identifiers for this project.
# List one or more licenses that apply to the gem. Users may use the software
# under the terms of any one license listed here (OR semantics, not AND).
#
# Accepted values (initial supported set):
#   MIT                              - MIT License (open source, permissive)
#   AGPL-3.0-only                    - GNU Affero General Public License v3
#   PolyForm-Noncommercial-1.0.0     - PolyForm Noncommercial License 1.0.0
#   PolyForm-Small-Business-1.0.0    - PolyForm Small Business License 1.0.0
#   LicenseRef-Big-Time-Public-License - Big Time Public License 2.0.2
#
# Defaults to spec.licenses from the gemspec when this key is absent.
#
# Template behaviour:
#   - Each listed license is copied as <SPDX-basename>.md into the project.
#   - A LICENSE.md index file is generated referencing all chosen licenses.
#   - Any non-MIT license adds a "contact for commercial license" prompt.
#   - When MIT (or AGPL), a PolyForm variant, AND LicenseRef-Big-Time-Public-License
#     are all present, a use-case guide table is added to README and LICENSE.md.
licenses:
  - MIT
# Apache SkyWalking Eyes dependency license overrides.
# Use these when license-eye cannot identify a dependency license from the
# package metadata or gem contents. Entries render under
# dependency.licenses in .licenserc.yaml.
#
# Supported fields:
#   name    - dependency name exactly as reported by license-eye
#   license - SPDX license identifier to assign
#   version - optional dependency version for a narrower override
license_eye:
  dependency_licenses:
    - name: simplecov-rcov
      version: 0.3.7
      license: MIT

# Machine / automation accounts to exclude from generated copyright output.
#
# When kettle-jem collects copyright information via `git blame`, it filters
# out known GitHub/GitLab bot accounts automatically.  Use this list to also
# exclude internal automation accounts that are not bots in the git sense
# (i.e. they do not follow the "[bot]" naming convention).
#
# Each entry is matched case-insensitively against the commit author name AND
# the commit author email, so you can list either form.
#
# Default (when key is absent or empty): ["autobolt"]
machine_users:
  - autobolt

# Self-test / templating CI threshold.
# Set to a number from 0 to 100 to fail `rake kettle:jem:selftest` once
# divergence exceeds that percent. Leave blank to report only.
# Divergence is currently measured as the percent of produced files that would
# change or be added during templating (100 - unchanged-file score).
# ENV override: KJ_MIN_DIVERGENCE_THRESHOLD
min_divergence_threshold:

# Hostname used for generated YARD documentation links.
# Defaults to <gem-name>.<author-email-domain>.
# ENV override: KJ_YARD_HOST
yard_host: "{KJ|YARD_HOST}"

# Full URL used for gemspec metadata["homepage_uri"].
# Defaults to https://{KJ|YARD_HOST}.
# ENV override: KJ_HOMEPAGE_URI
homepage_uri: "https://oauth.galtzo.com"

# Template source inventory.
# The packaged inventory is the canonical kettle-jem project template. It
# includes the detailed GitHub Actions workflow set, modular gemfiles,
# README badges, license files, config files, and support scripts.
templates:
  root: packaged
  apply: true
  # Template recipe profile.
  # Supported values:
  #   full            - full gem template
  #   monorepo-subgem - smaller sub-project template
  #   monorepo-root   - repository-root support template
  #
  # ENV override: KETTLE_JEM_TEMPLATE_PROFILE
  profile: "full"

# StructuredMerge Git diff driver setup.
# Default: semantic-diff installs local .gitattributes entries for semantic
# structured diffs. Use builtin-diff to retain Git's built-in language drivers,
# global to register driver commands in user config, include-file to write
# .git/smorg/config, check to verify setup, undo to remove managed entries, or
# none to opt out.
# ENV override: KETTLE_JEM_GIT_DRIVERS
git_drivers: semantic-diff

# Optional kettle-jem plugins.
# Each entry is a gem name. During bootstrap, kettle-jem ensures each plugin is
# added as a development dependency so it is available after bin/setup.
# During bundled templating, kettle-jem requires the plugin and calls
# `register_kettle_jem_plugin(registrar)` on its top-level handle.
#
# Phase callback names currently available:
#   - config_sync
#   - dev_container
#   - github_workflows
#   - quality_config
#   - modular_gemfiles
#   - spec_helper
#   - environment_templates
#   - remaining_files
#   - git_hooks
#   - license_files
#   - duplicate_check
#
# Phase guarantees:
#   - All plugin callbacks run during the bundled templating phase, after
#     bin/setup and bundle install have completed.
#   - kettle-jem, kettle-dev, and any plugin gems listed here are loadable.
#   - kettle-jem's parser / merger runtime is available to callbacks.
#   - `remaining_files` runs after the destination Rakefile, gemspec, README,
#     and most template-managed files already exist on disk.
#   - `duplicate_check` runs last, after all template writes are complete.
plugins:
  - kettle-drift

# Default merge options
defaults:
  preference: "template"
  add_template_only_nodes: true
  freeze_token: "kettle-jem"

# Token replacement values.
#
# General rules:
#   - Empty strings are treated as unset.
#   - Use the bare identifier/slug/handle expected by the inline comment.
#   - Do NOT paste full URLs unless the comment explicitly says to.
#
# Tip:
#   The author fields in a newly created destination config are normally seeded
#   from the gemspec via safe derivation. After that, destination values win.
tokens:
  forge:
    gh_user: "pboling"        # GitHub username only, no @, no URL. Used for GitHub Sponsors and profile links. ENV: KJ_GH_USER
    gl_user: "pboling"        # GitLab username only, no @, no URL. Used for profile links. ENV: KJ_GL_USER
    cb_user: "pboling"        # Codeberg username only, no @, no URL. Used for profile links. ENV: KJ_CB_USER
    sh_user: "galtzo"        # SourceHut username only, no leading ~, no URL. Used as https://sr.ht/~<value>/. ENV: KJ_SH_USER

  author:
    name: "Peter H. Boling"                 # Full display name. Example: Ada Lovelace. ENV: KJ_AUTHOR_NAME. Auto-seeded from gemspec authors.first
    given_names: "Peter H."   # Given/personal names only. Example: Ada. ENV: KJ_AUTHOR_GIVEN_NAMES. Auto-seeded when AUTHOR:NAME can be split
    family_names: "Boling" # Family/surname only. Example: Lovelace. ENV: KJ_AUTHOR_FAMILY_NAMES. Auto-seeded when AUTHOR:NAME can be split
    email: "floss@galtzo.com"               # Primary public email address. Example: floss@galtzo.com. ENV: KJ_AUTHOR_EMAIL. Auto-seeded from gemspec email.first
    domain: "galtzo.com"             # Bare domain only, no scheme, no email. Example: galtzo.com. ENV: KJ_AUTHOR_DOMAIN. Auto-seeded from AUTHOR:EMAIL
    orcid: "0009-0008-8519-441X"                                # ORCID identifier only, not the full URL. Example: 0000-0001-2345-6789. ENV: KJ_AUTHOR_ORCID

  funding:
    open_collective: "ruby-oauth" # Open Collective slug, true to enable with ENV/.opencollective.yml, false to disable. ENV: OPENCOLLECTIVE_HANDLE or FUNDING_ORG
    patreon: "galtzo"        # Patreon account slug only. Used as https://patreon.com/<value>. ENV: KJ_FUNDING_PATREON
    kofi: "pboling"           # Ko-fi handle/slug only. Used as https://ko-fi.com/<value>. ENV: KJ_FUNDING_KOFI
    paypal: "peterboling"         # PayPal.Me slug only. Used as https://www.paypal.com/paypalme/<value>. ENV: KJ_FUNDING_PAYPAL
    buymeacoffee: "pboling"   # Buy Me a Coffee slug only. Used as https://www.buymeacoffee.com/<value>. ENV: KJ_FUNDING_BUYMEACOFFEE
    polar: "pboling"          # Polar handle/slug only. Used as https://polar.sh/<value>. ENV: KJ_FUNDING_POLAR
    liberapay: "pboling"      # Liberapay account slug only. Used as https://liberapay.com/<value>/donate. ENV: KJ_FUNDING_LIBERAPAY
    issuehunt: "pboling"      # IssueHunt identifier/handle only, not a URL. ENV: KJ_FUNDING_ISSUEHUNT

  social:
    mastodon: "galtzo"       # Local handle only for the instance assumed by the template link. Current template uses https://ruby.social/@<value>. ENV: KJ_SOCIAL_MASTODON
    bluesky: "galtzo.com"        # Full Bluesky handle. Example: peterboling.dev or alice.bsky.social. Used as https://bsky.app/profile/<value>. ENV: KJ_SOCIAL_BLUESKY
    linktree: "galtzo"       # Linktree username only. Used as https://linktr.ee/<value>. ENV: KJ_SOCIAL_LINKTREE
    devto: "galtzo"          # DEV Community username only. Used as https://dev.to/<value>. ENV: KJ_SOCIAL_DEVTO

# Glob patterns evaluated in order (first match wins)
patterns:
  - path: "certs/**"
    strategy: raw_copy
  - path: ".github/workflows/**"
    strategy: accept_template

# Per-file configuration (nested directory structure)
# Only files that need overrides belong here. Everything else defaults to merge.
files:
  AGENTS.md:
    strategy: accept_template
  Appraisal.root.gemfile:
    strategy: accept_template
  Gemfile:
    strategy: accept_template
  Rakefile:
    strategy: accept_template
    preference: destination
    add_template_only_nodes: true
  .github:
    copilot_instructions.md:
      strategy: accept_template
  gemfiles:
    modular:
      templating.gemfile:
        strategy: accept_template
      templating_local.gemfile:
        strategy: accept_template
