sevgi-graphics 0.95.0 → 0.98.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7f7d46384f89f99b807f703fdec7a4519d9504899fa6ad6e08133d4cf2cbba7
-  data.tar.gz: 74822aa3dbed9221c2caebd5d163d6c2ad96427a6957e73bbba19612d930070c
+  metadata.gz: 753194f4865e2c8b099f788588a684a72a116004b3e56bb40cfd626a7b14043f
+  data.tar.gz: d443e433a8c86e4d902b31a4dadb71a244905f83aca4b67d8d56c64fdd7cb6c7
 SHA512:
-  metadata.gz: baaeb127304fd553d7fb49f119d9179e4ff6023f24181d61f282faafdcebc0fb2174c7a076d8483044917a17987994e8fd87b60995be14354a6543ba40a1d302
-  data.tar.gz: 53101304229cde02e71911654b14b28cffb17d69ddd4d02afa1ae513abb4d999e28aedb3b28c76849c74f452a841ae9d2cf2c4204edf2e671cbec60bd33a8463
+  metadata.gz: 05517e6f426cc1cd7ce0077705f147db602346bfba518500551dfce4008d669935f1fe3f21fc83b4531f33a44e4eec38e5b3ff82ccceff1bf1968a30f7ce8998
+  data.tar.gz: d19ec2a6d3e5e093876ab72eaa594220241f5ff8f5c744124330ee69adff71f12a67159779b9894a6bd4589ea0b3af78ad16ed768d41b422ffc18bca77248075

data/CHANGELOG.md

@@ -5,6 +5,131 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## Unreleased
 
+## 0.98.2 - 2026-07-25
+
+### Fixed
+
+- Restored the `sevgi` CLI's main-object scope so bare toolkit calls remain available inside script helper classes.
+
+## 0.98.1 - 2026-07-20
+
+### Changed
+
+- Changed the `sevgi` CLI to use the executor's isolated scope by default.
+
+### Removed
+
+- Removed the redundant `-n` and `--nomain` CLI options; library consumers can still select `main: true` through
+  `Sevgi.execute` and `Sevgi.execute_file` when needed.
+
+## 0.98.0 - 2026-07-20
+
+### Added
+
+- Added standard-input support to `sevgi`, `igves`, and `igsev`; `sevgi --as NAME` and
+  `Sevgi.execute_file(..., as: NAME)` supply the logical source basename used by implicit SVG, PDF, and PNG
+  destinations without changing physical load identity.
+
+## 0.97.0 - 2026-07-19
+
+### Added
+
+- Added `sevgi-appendix`, containing the Sevgi agent skill and a RuboCop plugin for preserving readable `.sevgi` DSL
+  source alongside rubyfmt-formatted Ruby; the umbrella `sevgi` gem installs the matching Appendix version.
+- Added `sevgi --skill` to report the validated path of the matching packaged agent skill for product-neutral setup.
+- Added `igsev` to the umbrella gem for normalizing an SVG file through a complete SVG-to-Sevgi-to-SVG round trip.
+
+### Changed
+
+- Made Homebrew the recommended complete CLI installation while retaining Bundler and focused component gems for Ruby
+  application dependencies.
+
+## 0.96.0 - 2026-07-18
+
+### Added
+
+- Added exact, subtree-wide attribute omission to Derender content/file conversion, evaluation, and inclusion APIs;
+  `igves --omit` exposes the same behavior from the command line.
+- Added `Sevgi.SVG` as the explicit namespaced form of the top-level SVG document entrypoint.
+- Added the opt-in recursive `SVG::Modules` contract for callable drawing namespaces.
+- Added callable drawing-module `base` blocks, document and paper registry introspection, Canvas structural equality,
+  renderer options on `RenderChildren`, axis translation helpers, and a CC BY RDF helper.
+- Formalized non-rendering `-` metadata and `+` attribute updates as `Attributes::META_PREFIX` and
+  `Attributes::UPDATE_SUFFIX`; repeated Array updates now concatenate into a stable flat value.
+
+### Changed
+
+- Breaking: replaced the `SVG = Sevgi::Graphics` alias with an independent SVG facade. Facade operations now use
+  capitalized names such as `SVG.Canvas` and `SVG.Document`; lowercase component helpers remain on
+  `Sevgi::Graphics`, and the stuttering `SVG.SVG` form was removed.
+- Breaking: made low-level `Executor.execute` and `execute_file` runners private; consumers use
+  `Sevgi.execute` and `Sevgi.execute_file` while retaining the public result and error types.
+- Breaking: removed the abstract `Document::Base` layer from the selectable document-profile registry; `Minimal` and
+  `Default` are now sibling concrete profiles, and custom profile hierarchies should derive from `Base`.
+- Breaking: renamed Parallelogram segment and constraint arguments by geometric role: `base`, `side`, and
+  `constraint` replace axis-implying constructor names.
+- Made degree-based sine and cosine exact at integer quarter turns, eliminating cardinal Geometry residue.
+- Documented complete file-system failure families for file comparison, output, touch, and upward location helpers.
+- Formalized generated Tile ids, positional CSS classes, template placement, and per-use callback signatures.
+- Formalized String and Symbol ids across Derender selection APIs and documented file-read failures consistently.
+- Breaking: made top-level `Decompile`, `Derender`, `Evaluate`, and `EvaluateChildren` consume inline SVG/XML;
+  file inputs now use the corresponding `File`-suffixed entrypoints.
+- Breaking: replaced callable drawing module `call` block registration with argument-independent `base` blocks;
+  inherited bases run parent-first, and modules with one drawing method conventionally name it `call`.
+- Breaking: made bracket and call notation the canonical Geometry constructors. Among Data value types, bracket notation
+  is public only for Point, Segment, LengthAngle, Margin, and Paper; use `.new` for Location and result carriers, and
+  `Stay` for traversal stop tokens.
+- Breaking: aligned Point and Segment comparison with Ruby `Comparable`; malformed or unrelated comparison operands now
+  return nil from `<=>`.
+- Breaking: executor entrypoints now return immutable `Executor::Result` values and expose only `execute` and
+  `execute_file`; inspect `result.error`, `result.stack`, and `result.value` instead of executor scopes or lifecycle state.
+- Breaking: wrapper attributes and callable arguments use distinct channels, `With` rejects parentless receivers, and
+  unsupported direct constructors are private; use the documented factories for Content, concrete Geometry lined
+  elements, and Grid query values.
+- Breaking: Canvas uses `.new` for explicit fields, `.from_paper(paper, **overrides)` for paper conversion, and
+  `.call`/`Graphics.canvas` for dispatch; the misleading keyword-only `.from_paper(width:, height:)` form was removed.
+- Breaking: `Save`, `Write`, `PNG`, `PDF`, and Sundries native export normalize successful destinations to expanded
+  String paths and create missing parent directories; change-aware SVG writes still return nil when unchanged.
+- Breaking: renamed `Derender.evaluate_file_children` to `evaluate_children_file`; decompiled nodes now own immutable
+  public state while parser, strategy, and construction plumbing remain private.
+- Expanded runtime/YARD parity checks and exact contracts for inherited, extended, generated, and dynamic API surfaces,
+  forwarded options, error channels, path ownership, whitespace, namespaces, nil behavior, and return values.
+
+### Fixed
+
+- Rejected directories from default file discovery while preserving custom locator matchers.
+- Kept `Ancestral` context in non-rendering `-context` metadata instead of leaking it into SVG attributes.
+- Preserved source Canvas units and names when deriving fitted Grid canvases.
+- Prevented stale documentation assets from mixing old layouts with new HTML, and moved sidebar navigation into the
+  tablet menu at 1024px and below.
+- Normalized numeric slots owned by path, shape, transform, tile, and Inkscape page helpers to finite SVG number spelling;
+  arbitrary user-supplied attributes remain untouched.
+- Made named callable wrapper and symbol ids stable while omitting defaults for anonymous modules, and indexed every
+  rendered id value, including false and numeric values, through its serialized string.
+- Preserved signed Geometry constraint directions, rejected invalid sweep/export channels through Sevgi error families,
+  and validated raw output paths before expansion or rendering.
+- Made callable module configuration copy-owned and freeze-aware, document subclasses inherit their nearest profile, and
+  false executor boot receivers remain explicit rather than defaulting to an internal scope.
+- Made element trees, attributes, identifiers, locator results, document profiles, Derender nodes, shell results, and
+  executor results retain owned immutable snapshots where their public contracts promise value semantics.
+- Corrected Shell combined-output separators, nil export density errors, document render-option routing, executor source
+  snapshots, selected-node namespace/whitespace documentation, and Standard character-data validation.
+
+### Removed
+
+- Removed public access to pluralization tables and the internal SVG save extension; pluralization rules are now deeply
+  immutable.
+- Removed public documentation and constant access for command-line implementation modules; the `sevgi` and `igves`
+  executables remain unchanged.
+- Removed eager loading and public documentation of private Showcase build/test support; explicit support entrypoints
+  now keep the harness under the Showcase namespace.
+- Removed public access to document profile name normalizers; registry operations retain them as private plumbing.
+- Removed the redundant `Margin.margin` constructor; use canonical bracket notation.
+- Removed public executor orchestration, obsolete callable-module hooks, the old public attribute syntax constants, and
+  direct construction of abstract or internally wired Content, Element, and Grid query types.
+- Removed accidental public access to abstract Lined factories, internal element-name/export maps, result/location
+  bracket constructors, and direct Stop construction.
+
 ## 0.95.0 - 2026-07-11
 
 ### Security

data/README.md

@@ -1,6 +1,6 @@
 # Sevgi Graphics
 
-Core SVG DSL, document profiles, and rendering behavior.
+Sevgi Graphics implements the SVG DSL, document profiles, and rendering.
 
 ## Install
 
@@ -17,21 +17,21 @@ require "sevgi/graphics"
 ## Example
 
 ```ruby
-doc = Sevgi::Graphics.SVG(:minimal) { rect(width: 3, height: 5) }
+doc = Sevgi::Graphics.SVG(:minimal) { rect width: 3, height: 5 }
 doc.call
 ```
 
 ## Ruby compatibility
 
-Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4.0 and the current development Ruby from `.ruby-version`.
+Requires Ruby 3.4.0 or newer. CI verifies the current Ruby 3.4 release and the development Ruby from `.ruby-version`.
 
 ## Native prerequisites
 
-None beyond Ruby and this gem's Ruby dependencies.
+This gem needs only Ruby and its Ruby dependencies.
 
 ## Links
 
-- Documentation: https://sevgi.roktas.dev
-- API documentation: https://www.rubydoc.info/gems/sevgi-graphics
-- Source: https://github.com/roktas/sevgi/tree/main/graphics
-- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md
+- Documentation: <https://sevgi.roktas.dev>
+- API documentation: <https://www.rubydoc.info/gems/sevgi-graphics>
+- Source: <https://github.com/roktas/sevgi/tree/main/graphics>
+- Changelog: <https://github.com/roktas/sevgi/blob/main/CHANGELOG.md>

data/lib/sevgi/graphics/attribute.rb

@@ -4,11 +4,16 @@
 
 module Sevgi
   module Graphics
-    # Internal store syntax; not part of the SVG DSL command surface.
-    ATTRIBUTE_INTERNAL_PREFIX = "-"
-
-    # Attribute suffix that merges new values into an existing attribute.
-    ATTRIBUTE_UPDATE_SUFFIX = "+"
+    # Mutable facade for SVG attributes and non-rendering element metadata.
+    class Attributes
+      # Prefix marking supported non-rendering metadata names. Prefixed entries remain available through the facade but
+      # are omitted from SVG output.
+      META_PREFIX = "-"
+
+      # Suffix requesting an update of an existing value. String and Symbol values are space-joined, Arrays are
+      # concatenated, and Hashes are merged. When the attribute is absent, assignment uses normal replacement behavior.
+      UPDATE_SUFFIX = "+"
+    end
 
     # Attribute name normalization helpers.
     # @api private
@@ -20,7 +25,7 @@ module Sevgi
         # @param given [String, Symbol] attribute name
         # @return [Boolean]
         def internal?(given)
-          (@internal ||= {})[given] ||= key(given).start_with?(ATTRIBUTE_INTERNAL_PREFIX)
+          (@internal ||= {})[given] ||= key(given).start_with?(Attributes::META_PREFIX)
         end
 
         # Returns the normalized attribute id.
@@ -28,7 +33,7 @@ module Sevgi
         # @return [Symbol]
         def id(given)
           (@id ||= {})[given] ||= begin
-            name = updateable?(given) ? key(given).delete_suffix(ATTRIBUTE_UPDATE_SUFFIX) : key(given)
+            name = updateable?(given) ? key(given).delete_suffix(Attributes::UPDATE_SUFFIX) : key(given)
             XML.name(name, context: "XML attribute name") unless internal?(given)
             name.to_sym
           end
@@ -38,7 +43,7 @@ module Sevgi
         # @param given [String, Symbol] attribute name
         # @return [Boolean]
         def updateable?(given)
-          (@updateable ||= {})[given] ||= key(given).end_with?(ATTRIBUTE_UPDATE_SUFFIX)
+          (@updateable ||= {})[given] ||= key(given).end_with?(Attributes::UPDATE_SUFFIX)
         end
 
         private
@@ -125,6 +130,25 @@ module Sevgi
       # @api private
       def self.capture(value, normalize_keys: false) = Snapshot.capture(value, normalize_keys:)
 
+      # Returns normalized owned attributes with defaults for absent names.
+      # @param attributes [Hash] source attributes
+      # @param defaults [Hash] values inserted only when their normalized names are absent
+      # @return [Hash{Symbol => Object}] normalized owned attributes
+      # @raise [Sevgi::ArgumentError] when input contains an invalid, colliding, or unsupported attribute
+      # @api private
+      def self.defaults(attributes, **defaults)
+        attributes = Attributes.new(attributes)
+        defaults.each { |name, value| attributes[name] = value unless attributes.has?(name) }
+        attributes.to_h
+      end
+
+      # Returns normalized owned attributes.
+      # @param attributes [Hash] source attributes
+      # @return [Hash{Symbol => Object}] normalized owned attributes
+      # @raise [Sevgi::ArgumentError] when input contains an invalid, colliding, or unsupported attribute
+      # @api private
+      def self.normalize(attributes) = Attributes.new(attributes).to_h
+
       # Returns the text form used for an XML attribute value before escaping.
       # @param value [Object] attribute value
       # @return [String]
@@ -144,7 +168,8 @@ module Sevgi
         XML.text(text, context: "XML attribute value")
       end
 
-      # Mutable SVG attribute store with Sevgi update syntax.
+      # Mutable backing store for SVG attributes.
+      # @api private
       class Store
         # Creates an attribute store from recursively owned snapshots. Mutable non-container leaves are stringified
         # once; later caller mutation cannot change the store.
@@ -164,22 +189,13 @@ module Sevgi
         # @raise [Sevgi::ArgumentError] when input is not a Hash or a name/value is invalid, cyclic, colliding, or cannot
         #   be converted
         def import(attributes)
-          ArgumentError.("Attributes must be imported from a Hash") unless attributes.is_a?(::Hash)
-
-          hash = attributes.each_with_object({}) do |(key, value), captured|
-            next if value.nil?
+          updated = @store.dup
+          entries(attributes).each { |entry| assign(updated, *entry) }
 
-            id = Attribute.id(key)
-            ArgumentError.("Attribute names collide after normalization: #{id}") if captured.key?(id)
-
-            captured[id] = Attribute.capture(value, normalize_keys: value.is_a?(::Hash))
-          end
-
-          @store.merge!(hash)
+          @store.replace(updated)
         end
 
-        # Returns a live stored attribute value. Mutating a returned container intentionally mutates this store; rendering
-        # revalidates the resulting value.
+        # Returns a stored attribute value for the public facade.
         # @param key [String, Symbol] attribute key
         # @return [Object, nil]
         # @raise [Sevgi::ArgumentError] when key is not a valid XML attribute name
@@ -199,7 +215,7 @@ module Sevgi
 
           id = Attribute.id(key)
           value = Attribute.capture(value, normalize_keys: value.is_a?(::Hash))
-          @store[id] = @store.key?(id) && Attribute.updateable?(key) ? update(id, value) : value
+          @store[id] = @store.key?(id) && Attribute.updateable?(key) ? update(@store[id], value) : value
         end
 
         # Deletes an attribute by normalized key.
@@ -210,13 +226,13 @@ module Sevgi
           @store.delete(Attribute.id(key))
         end
 
-        # Returns public attributes ready for rendering. Nested values remain live store values.
+        # Returns rendering attributes, excluding non-rendering metadata. Nested values remain live store values.
         # @return [Hash] shallow attribute view
         def export
           hash = @store.reject { |id, _| Attribute.internal?(id) }
           return hash unless hash.key?(:id)
 
-          # A small aesthetic touch: always keep the id attribute first
+          # Keep id first for stable, readable SVG output.
           {id: hash.delete(:id), **hash}
         end
 
@@ -229,9 +245,8 @@ module Sevgi
         end
 
         # Copies the attribute store with recursively independent values.
-        # @param original [Sevgi::Graphics::Attribute::Store] store to copy
+        # @param original [Sevgi::Graphics::Attributes] store to copy
         # @return [void]
-        # @raise [Sevgi::ArgumentError] when live stored values became cyclic or invalid
         def initialize_copy(original)
           @store = {}
           original.store.each { |key, value| @store[key] = Attribute.capture(value) }
@@ -239,15 +254,14 @@ module Sevgi
           super
         end
 
-        # Returns public attribute names.
+        # Returns rendering attribute names, excluding non-rendering metadata.
         # @return [Array<Symbol>]
         def list
           export.keys
         end
 
-        # Returns the live internal attribute Hash. Mutating it intentionally mutates this store; rendering revalidates
-        # names and values.
-        # @return [Hash] live internal store
+        # Returns the internal attribute and metadata Hash.
+        # @return [Hash] backing store
         def to_h
           @store
         end
@@ -268,12 +282,32 @@ module Sevgi
         UPDATER = {
           ::String => proc { |old_value, new_value| [old_value, new_value].reject(&:empty?).join(" ") },
           ::Symbol => proc { |old_value, new_value| [old_value, new_value].reject(&:empty?).join(" ").to_sym },
-          ::Array => proc { |old_value, new_value| [old_value, new_value] },
-          ::Hash => proc { |old_value, new_value| old_value.merge(new_value.transform_keys(&:to_sym)) }
+          ::Array => proc { |old_value, new_value| old_value + new_value },
+          ::Hash => proc { |old_value, new_value| old_value.merge(new_value) }
         }.freeze
 
-        def update(id, new_value)
-          (old_value = @store[id]).nil? ? new_value : UPDATER[new_value.class].call(*sanitized(old_value, new_value))
+        def assign(store, key, id, value)
+          store[id] = store.key?(id) && Attribute.updateable?(key) ? update(store[id], value) : value
+        end
+
+        def entries(attributes)
+          ArgumentError.("Attributes must be imported from a Hash") unless attributes.is_a?(::Hash)
+
+          identities = {}
+          attributes.filter_map do |key, value|
+            next if value.nil?
+
+            id = Attribute.id(key)
+            ArgumentError.("Attribute names collide after normalization: #{id}") if identities.key?(id)
+
+            identities[id] = true
+            value = Attribute.capture(value, normalize_keys: value.is_a?(::Hash))
+            [key, id, value]
+          end
+        end
+
+        def update(old_value, new_value)
+          UPDATER[new_value.class].call(*sanitized(old_value, new_value))
         end
 
         def sanitized(old_value, new_value)
@@ -292,7 +326,96 @@ module Sevgi
       end
     end
 
-    # Public alias for the SVG attribute store.
-    Attributes = Attribute::Store
+    # Names beginning with {META_PREFIX} can be read, assigned, deleted, merged, and copied like ordinary
+    # attributes. They appear in {#to_h}, but public SVG attribute enumeration and rendered XML omit them. All values
+    # entering or leaving this facade are recursively owned snapshots. Appending {UPDATE_SUFFIX} to a name requests a
+    # same-family update: Strings and Symbols are space-joined, Arrays are concatenated, and Hashes are merged. An update
+    # to an absent name behaves as replacement, and nil assignments are ignored.
+    #
+    # @example Inspect and update element attributes
+    #   element = Sevgi::Graphics.SVG { rect id: "copy", "-source": "original" }.children.first
+    #   element.attributes[:"-source"] # => "original"
+    #   element.attributes.merge!(fill: "red")
+    #   element.attributes.to_h # => { id: "copy", :"-source" => "original", fill: "red" }
+    class Attributes
+      # Creates an attribute facade from recursively owned snapshots.
+      # @param attributes [Hash] initial attributes and non-rendering metadata
+      # @return [void]
+      # @raise [Sevgi::ArgumentError] when input is not a Hash or contains an invalid name or value
+      def initialize(attributes = {})
+        @store = Attribute::Store.new(attributes)
+      end
+
+      # Returns an owned snapshot of an attribute value.
+      # @param key [String, Symbol] attribute key
+      # @return [Object, nil] recursively owned value or nil when absent
+      # @raise [Sevgi::ArgumentError] when key is not a valid attribute name
+      def [](key) = snapshot(@store[key])
+
+      # Assigns or updates a recursively owned attribute value.
+      # @param key [String, Symbol] attribute key, optionally ending in {UPDATE_SUFFIX}
+      # @param value [Object, nil] attribute value; nil is ignored
+      # @return [Object, nil] recursively owned resulting value or nil when absent
+      # @raise [Sevgi::ArgumentError] when the name or value is invalid, or an existing update uses incompatible or
+      #   unsupported value families
+      def []=(key, value)
+        @store[key] = value
+        snapshot(@store[key])
+      end
+
+      # Deletes an attribute and returns an owned snapshot of its value.
+      # @param key [String, Symbol] attribute key
+      # @return [Object, nil] deleted value or nil when absent
+      # @raise [Sevgi::ArgumentError] when key is not a valid attribute name
+      def delete(key) = snapshot(@store.delete(key))
+
+      # Reports whether an attribute exists.
+      # @param key [String, Symbol] attribute key
+      # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when key is not a valid attribute name
+      def has?(key) = @store.has?(key)
+
+      # Copies the facade with recursively independent values.
+      # @param original [Sevgi::Graphics::Attributes] facade to copy
+      # @return [void]
+      # @raise [Sevgi::ArgumentError] when stored values became invalid
+      # @api private
+      def initialize_copy(original)
+        super
+        @store = original.store.dup
+      end
+
+      private :initialize_copy
+
+      # Returns rendering attribute names, excluding non-rendering metadata.
+      # @return [Array<Symbol>] frozen name snapshot
+      def keys = @store.list.freeze
+
+      # Atomically assigns or updates recursively owned attributes.
+      # @param attributes [Hash] attributes and non-rendering metadata; names may end in {UPDATE_SUFFIX}
+      # @return [Sevgi::Graphics::Attributes] self
+      # @raise [Sevgi::ArgumentError] when input is not a Hash, names collide, a name or value is invalid, or an existing
+      #   update uses incompatible or unsupported value families
+      def merge!(attributes)
+        @store.import(attributes)
+        self
+      end
+
+      # Returns a recursively owned Hash snapshot including non-rendering metadata.
+      # @return [Hash{Symbol => Object}] owned attribute and metadata snapshot
+      def to_h = snapshot(@store.to_h)
+
+      private
+
+      def snapshot(value) = Attribute.capture(value)
+
+      def xml_lines = @store.to_xml_lines
+
+      protected
+
+      attr_reader :store
+    end
+
+    private_constant :Attribute
   end
 end