sevgi-appendix 0.98.2

data/agents/skills/sevgi/references/ruby.md

@@ -0,0 +1,79 @@
+# Ruby Discipline
+
+A `.sevgi` file is executable Ruby evaluated with Sevgi's drawing vocabulary. It is not a separate template language or
+configuration format. Apply ordinary Ruby design and readability rules unless the compact DSL form is clearer.
+
+- Use local variables for local drawing state and constants for genuine module/script invariants.
+- Use Arrays, Hashes, ranges, loops, Enumerables, methods, and modules directly; do not recreate them as a second DSL.
+- Separate input data from drawing behavior when that makes either easier to read or test.
+- Extract reusable drawing behavior into ordinary methods or `SVG::Module`; use `SVG::Modules` for an owned nested
+  module family.
+- Prefer explicit arguments and return values over hidden global state, `eval`, monkey patches, or unnecessary
+  metaprogramming.
+- Keep side effects at the output boundary: build a document, then `Render`, `Save`, `Out`, `PDF`, or `PNG` deliberately.
+- Preserve the surrounding project's Ruby version, naming, error, test, and formatting conventions.
+- Hand-format `.sevgi` source for DSL readability. Do not run a broad Ruby formatter or autocorrect over `.sevgi`
+  files when it would flatten or obscure the drawing.
+
+## Preserve the DSL Shape
+
+Let drawing code read as a Sevgi program rather than mechanically parenthesized Ruby. Use braces for a one-line block,
+`do`/`end` for a multiline block, and omit optional parentheses from statement-like SVG elements and Sevgi operations.
+Keep parentheses when they bind a compact block or chained expression clearly, as in
+`SVG(:minimal) { circle r: 4 }.Render`.
+
+Avoid:
+
+```ruby
+SVG(:minimal) do
+  g({ id: "mark" }) do
+    rect({ x: 2, y: 2, width: 12, height: 8 })
+    circle({ cx: 8, cy: 6, r: 3 })
+  end
+end.Save("mark.svg")
+```
+
+Prefer:
+
+```ruby
+SVG :minimal do
+  g id: "mark" do
+    rect x: 2, y: 2, width: 12, height: 8
+    circle cx: 8, cy: 6, r: 3
+  end
+end.Save "mark.svg"
+```
+
+The first form is valid Ruby; the problem is loss of the drawing vocabulary's visual rhythm.
+
+## Callable Modules
+
+Extend a Ruby module with `SVG::Module`. Its public instance methods are drawing steps; name the only step `call`, or
+give several steps descriptive names. Private methods remain ordinary implementation helpers. A focused
+`require "sevgi/graphics"` consumer uses `Sevgi::Graphics::Module` and `Sevgi::Graphics::Modules` instead of the full
+facade constants.
+
+`base` registers argument-independent invariant SVG content that runs once per invocation before the public drawing
+steps. It is not general initialization or an ordering hook.
+
+```ruby
+Badge = Module.new do
+  extend SVG::Module
+
+  base { css ".badge" => { fill: "tomato" } }
+  def call(label:) = text label, class: "badge"
+end
+
+SVG(:minimal) { Call Badge, label: "OK" }.Render
+```
+
+`Call` draws directly. On an Inkscape profile, `Group`, `Layer`, and `Layer!` wrap the same invocation in a group,
+normal layer, or insensitive layer; `Symbols` expands the public steps into reusable symbols. Lowercase `layer` and
+`layer!` instead open explicit layer blocks without invoking a module. Use `SVG::Modules` only when one namespace owns
+a nested family of callable modules.
+
+Ruby arithmetic is appropriate for domain data and values the program must know. It does not supersede the renderer
+ownership rule in [drawing.md](drawing.md): idiomatic Ruby can still be the wrong layer for a rendering calculation.
+
+Use the [Library Mode guide](https://sevgi.roktas.dev/library-mode/) for facade and module composition, and the
+[Script Mode guide](https://sevgi.roktas.dev/script-mode/) for executable source behavior.

data/agents/skills/sevgi/references/svg.md

@@ -0,0 +1,35 @@
+# SVG Routing
+
+Use this page to identify the SVG mechanism, then verify exact behavior in MDN or the SVG specification. Do not turn
+this index into a cookbook of one-off drawing tips.
+
+| Rendering concept | Start with |
+| --- | --- |
+| Coordinate system and responsive scaling | `viewBox`, viewport dimensions, `preserveAspectRatio` |
+| Relative placement of an element tree | `transform`; use Sevgi's transform helpers when available |
+| Reusable drawing definitions | `defs`, `symbol`, `use` |
+| Repeated visual fill | `pattern` |
+| Paint | presentation attributes or CSS, gradients, opacity |
+| Visibility boundaries | `clipPath` for hard clipping; `mask` for luminance/alpha compositing |
+| Line decoration | `marker`, stroke width, line cap, line join, dash array |
+| Renderer effects | `filter` and filter primitives |
+| Text relationships | text positioning and anchoring attributes; leave font metrics to the renderer |
+
+Resolve questions in this order:
+
+1. Identify the relationship the drawing needs, not a guessed numeric result.
+2. Find the standard SVG element, attribute, or CSS behavior that owns it.
+3. Check target-renderer support and inheritance rules when the feature is context-sensitive.
+4. Express it through normal Sevgi element calls and attributes. Use `Element` only when a verified XML element name
+   cannot dispatch safely as a Ruby call, such as a name that conflicts with an existing Ruby or Sevgi method. Never use
+   it as a fallback for an unverified DSL word.
+5. Compute geometry only when SVG does not provide the value needed by the program.
+
+Authoritative references:
+
+- [MDN SVG reference](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference)
+- [W3C SVG 2 specification](https://www.w3.org/TR/SVG2/)
+- [Sevgi SVG Essentials](https://sevgi.roktas.dev/svg/)
+
+Do not invent an SVG name from memory when validation matters. Check MDN and let Sevgi Standard validate known element
+names, attributes, content, and nesting.

data/agents/skills/sevgi/references/toolkit.md

@@ -0,0 +1,48 @@
+# Toolkit Routing
+
+## Choose the Owner
+
+| Need | Component / entry point | Boundary |
+| --- | --- | --- |
+| Build SVG documents and element trees | Graphics; `SVG(...)`, SVG element calls | Default starting point for every drawing |
+| Choose paper size, canvas geometry, or root serialization metadata | `SVG.Paper`, `SVG.Canvas`, `SVG.Document` | Keep physical size, drawing surface, and document profile independent |
+| Validate SVG vocabulary and nesting | Standard | Use validation; do not hand-maintain element/attribute allowlists |
+| Calculate geometry SVG cannot supply | `Sevgi::Geometry` | Use for constructed values, intersections, sweeps, and algorithmic bounds—not renderer layout |
+| Fit rulers, grids, and reusable tile layouts | `Sevgi::Sundries`, `SVG.Grid` | Choose the exact model through `layout.md` |
+| Reuse supported cross-component helpers | `Sevgi::F` | Check before adding a project-local Sevgi helper; it is not a general utility library |
+| Import or inspect existing SVG/XML | Derender facade methods | Choose the source/evaluation relationship through `derender.md` |
+| Render SVG as PDF or PNG | Sundries export / document `PDF` and `PNG` | Choose the output boundary through `output.md` |
+
+Before reimplementing shared behavior, check `Sevgi::F` for degree trigonometry and precision, `.sevgi` discovery,
+generated-file I/O, argv-safe child processes, Sevgi-facing names, and status output.
+
+## In a Checkout
+
+When a Sevgi checkout is available, prefer its canonical sources:
+
+| Need | Source |
+| --- | --- |
+| Machine-readable DSL inventory and examples | `showcase/doc/data/dsl.yml` |
+| Task-oriented user semantics | `showcase/doc/content/` |
+| Runnable complete drawings | examples under `showcase/srv` that are linked from the user docs or DSL catalog |
+| Exact public contracts | the owning component's `lib/` YARD comments |
+| Rendered local YARD | `.local/var/ruby/doc/api` after `bundle exec rake doc` |
+
+## Lookup Order
+
+1. Read the task-relevant user guide for semantics and workflow.
+2. Search the structured DSL inventory and linked runnable Showcase examples for the nearest drawing pattern.
+3. Read the rendered DSL catalog for an exact drawing word and executable example.
+4. Read YARD for signatures, return values, and failure contracts.
+5. Read MDN or the SVG specification for renderer behavior.
+
+| Topic | User guide | YARD |
+| --- | --- | --- |
+| Script and library forms | [Getting Started](https://sevgi.roktas.dev/getting-started/), [Library Mode](https://sevgi.roktas.dev/library-mode/) | [`sevgi`](https://www.rubydoc.info/gems/sevgi) |
+| SVG documents and DSL | [SVG Essentials](https://sevgi.roktas.dev/svg/), [DSL Catalog](https://sevgi.roktas.dev/dsl/) | [`sevgi-graphics`](https://www.rubydoc.info/gems/sevgi-graphics) |
+| Geometry | [Geometry](https://sevgi.roktas.dev/geometry/) | [`sevgi-geometry`](https://www.rubydoc.info/gems/sevgi-geometry) |
+| Rulers, grids, tiles, export | [Sundries](https://sevgi.roktas.dev/sundries/) | [`sevgi-sundries`](https://www.rubydoc.info/gems/sevgi-sundries) |
+| Shared helpers | [Functions](https://sevgi.roktas.dev/functions/) | [`sevgi-function`](https://www.rubydoc.info/gems/sevgi-function) |
+| SVG/XML import and round trip | [Derender](https://sevgi.roktas.dev/derender/) | [`sevgi-derender`](https://www.rubydoc.info/gems/sevgi-derender) |
+
+When working in a Sevgi checkout, prefer the checked-out docs and source over an installed gem's online YARD version.

data/lib/rubocop/cop/sevgi/block_delimiters.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rubocop/cop/style/block_delimiters"
+
+module RuboCop
+  module Cop
+    # Cops that preserve the visual rhythm of executable Sevgi DSL source.
+    module Sevgi
+      # Uses braces for one-line blocks and do/end for multiline blocks.
+      class BlockDelimiters < Style::BlockDelimiters
+      end
+    end
+  end
+end

data/lib/rubocop/cop/sevgi/parentheses.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rubocop/cop/style/method_call_with_args_parentheses"
+
+module RuboCop
+  # RuboCop's custom-cop namespace.
+  module Cop
+    module Sevgi
+      # Omits optional parentheses from bare DSL-shaped calls and capitalized Sevgi operations.
+      #
+      # Ordinary Ruby calls with explicit receivers retain their normal style. The inherited RuboCop implementation
+      # still preserves parentheses where Ruby syntax or expression binding benefits from them.
+      class Parentheses < Style::MethodCallWithArgsParentheses
+        # Checks a method call when its shape belongs to the Sevgi drawing vocabulary.
+        # @param node [RuboCop::AST::SendNode] method call
+        # @return [void]
+        def on_send(node)
+          return if node.method_name.end_with?("?")
+
+          super if node.receiver.nil? || node.method_name.match?(/\A[A-Z]/)
+        end
+
+        alias on_csend on_send
+      end
+    end
+  end
+end

data/lib/rubocop/cop/sevgi/string_literals.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rubocop/cop/style/string_literals"
+
+module RuboCop
+  module Cop
+    module Sevgi
+      # Uses double-quoted strings consistently in Sevgi DSL source.
+      class StringLiterals < Style::StringLiterals
+      end
+    end
+  end
+end

data/lib/rubocop/cop/sevgi_cops.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "sevgi/block_delimiters"
+require_relative "sevgi/parentheses"
+require_relative "sevgi/string_literals"

data/lib/rubocop/sevgi/plugin.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "lint_roller"
+
+require_relative "../../sevgi/appendix"
+
+# RuboCop integration shipped with Sevgi Appendix.
+module RuboCop
+  # Sevgi DSL integration for RuboCop.
+  module Sevgi
+    # Connects Sevgi's `.sevgi` rules to RuboCop's plugin system.
+    class Plugin < LintRoller::Plugin
+      # Describes this plugin to lint_roller.
+      # @return [LintRoller::About] plugin metadata
+      def about
+        LintRoller::About.new(
+          name: "sevgi-appendix",
+          version: ::Sevgi::Appendix::VERSION,
+          homepage: "https://sevgi.roktas.dev",
+          description: "RuboCop rules for the Sevgi SVG DSL"
+        )
+      end
+
+      # Reports whether this plugin supports the requested lint engine.
+      # @param context [LintRoller::Context] lint engine context
+      # @return [Boolean] true for RuboCop
+      def supported?(context) = context.engine == :rubocop
+
+      # Returns the RuboCop configuration bundled with this gem.
+      # @param _context [LintRoller::Context] lint engine context
+      # @return [LintRoller::Rules] path-backed RuboCop rules
+      def rules(_context)
+        LintRoller::Rules.new(
+          type: :path,
+          config_format: :rubocop,
+          value: File.expand_path("../../../rubocop/config/default.yml", __dir__)
+        )
+      end
+    end
+  end
+end

data/lib/rubocop/sevgi.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+require_relative "cop/sevgi_cops"
+require_relative "sevgi/plugin"

data/lib/sevgi/appendix/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Appendix
+    # Appendix package version.
+    VERSION = "0.98.2"
+  end
+end

data/lib/sevgi/appendix.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "appendix/version"
+
+module Sevgi
+  # Development extras distributed with Sevgi but kept outside its drawing runtime.
+  module Appendix
+  end
+end

data/lib/sevgi-appendix.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "sevgi/appendix"
+require_relative "rubocop/sevgi"

data/rubocop/config/default.yml

@@ -0,0 +1,67 @@
+AllCops:
+  Include:
+    - "**/*.sevgi"
+
+Sevgi:
+  Enabled: true
+  Include:
+    - "**/*.sevgi"
+
+Sevgi/BlockDelimiters:
+  Description: "Use braces for one-line blocks and do/end for multiline blocks in Sevgi DSL source."
+  EnforcedStyle: line_count_based
+  SupportedStyles:
+    - line_count_based
+    - semantic
+    - braces_for_chaining
+    - always_braces
+  ProceduralMethods:
+    - benchmark
+    - bm
+    - bmbm
+    - create
+    - each_with_object
+    - measure
+    - new
+    - realtime
+    - tap
+    - with_object
+  FunctionalMethods:
+    - let
+    - let!
+    - subject
+    - watch
+  AllowedMethods:
+    - lambda
+    - proc
+    - it
+  AllowedPatterns: []
+  AllowBracesOnProceduralOneLiners: false
+  BracesRequiredMethods: []
+  VersionAdded: "0.97.0"
+
+Sevgi/Parentheses:
+  Description: "Omit optional parentheses from bare DSL calls and capitalized Sevgi operations."
+  EnforcedStyle: omit_parentheses
+  SupportedStyles:
+    - require_parentheses
+    - omit_parentheses
+  IgnoreMacros: true
+  AllowedMethods: []
+  AllowedPatterns: []
+  IncludedMacros: []
+  IncludedMacroPatterns: []
+  AllowParenthesesInMultilineCall: true
+  AllowParenthesesInChaining: true
+  AllowParenthesesInCamelCaseMethod: false
+  AllowParenthesesInStringInterpolation: true
+  VersionAdded: "0.97.0"
+
+Sevgi/StringLiterals:
+  Description: "Use double-quoted strings in Sevgi DSL source."
+  EnforcedStyle: double_quotes
+  SupportedStyles:
+    - single_quotes
+    - double_quotes
+  ConsistentQuotesInMultiline: false
+  VersionAdded: "0.97.0"

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: sevgi-appendix
+version: !ruby/object:Gem::Version
+  version: 0.98.2
+platform: ruby
+authors:
+- Recai Oktaş
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lint_roller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.72.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.72.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Packages the Sevgi agent skill and RuboCop rules for readable .sevgi
+  source.
+email: roktas@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- agents/skills/sevgi/SKILL.md
+- agents/skills/sevgi/agents/openai.yaml
+- agents/skills/sevgi/references/derender.md
+- agents/skills/sevgi/references/drawing.md
+- agents/skills/sevgi/references/dsl.md
+- agents/skills/sevgi/references/inspection.md
+- agents/skills/sevgi/references/layout.md
+- agents/skills/sevgi/references/output.md
+- agents/skills/sevgi/references/ruby.md
+- agents/skills/sevgi/references/svg.md
+- agents/skills/sevgi/references/toolkit.md
+- lib/rubocop/cop/sevgi/block_delimiters.rb
+- lib/rubocop/cop/sevgi/parentheses.rb
+- lib/rubocop/cop/sevgi/string_literals.rb
+- lib/rubocop/cop/sevgi_cops.rb
+- lib/rubocop/sevgi.rb
+- lib/rubocop/sevgi/plugin.rb
+- lib/sevgi-appendix.rb
+- lib/sevgi/appendix.rb
+- lib/sevgi/appendix/version.rb
+- rubocop/config/default.yml
+homepage: https://sevgi.roktas.dev
+licenses:
+- GPL-3.0-or-later
+metadata:
+  changelog_uri: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/roktas/sevgi/tree/main/appendix
+  bug_tracker_uri: https://github.com/roktas/sevgi/issues
+  rubygems_mfa_required: 'true'
+  default_lint_roller_plugin: RuboCop::Sevgi::Plugin
+  sevgi_skill_path: agents/skills/sevgi
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Development extras for the Sevgi SVG DSL.
+test_files: []