xamidimura 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e4794d563170d4e8044b61886a26dd0410ad329b0462c1daaf680fa994b72526
+  data.tar.gz: 448b8c2f55e29a185bda32f5068de0894124a687b45ebd745a99a16d3bb96792
+SHA512:
+  metadata.gz: d5af662e534c95e5ff7be4e91a77cd57fb8538aeb1a1abfc644a5623be5982fabcde5856f52566a84d2de79f2c5e5f4c5a87be4b5c02bdea5550131b5ff2ce43
+  data.tar.gz: 61f3560994e263cf249a8da92528b2e6158758b2d052e12e6b4bf71a650ca36b10a3a0919341cb6063a83866b04f5ffe30a77ca8d833ecc02d073505fb3e2632

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-09-23
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,21 @@
+# Xamidimura
+
+Xamidimura provides the shared file-revision contract used by Canopus, Hadar,
+and Rukbat. It reads a stable byte snapshot, records a filesystem signature,
+and computes a SHA-256 revision for optimistic save-conflict checks.
+
+The gem is named for μ¹ Scorpii: Xamidimura is an IAU-adopted Khoekhoe name
+derived from *xami di mura*, “eyes of the beast” ([All Skies Encyclopaedia](https://xing.fmi.uni-jena.de/mediawiki/index.php/Xamidimura)).
+
+```ruby
+snapshot = Xamidimura::SourceRevision.read("notes.md", reject_symlink: true)
+snapshot.bytes       # exact bytes read
+snapshot.signature   # stable filesystem signature
+snapshot.digest      # SHA-256 of those bytes
+```
+
+`read` retries if the file changes during the read. Use `signature` for cheap
+change checks, `digest` for bytes already in memory, and `file_digest` to hash
+a file without loading it all into memory.
+
+Xamidimura requires Ruby 3.2 or newer and has no runtime dependencies.

data/docs/adr/000-template.md

@@ -0,0 +1,16 @@
+# ADR-NNN: Title
+
+- Status: Proposed
+- Date: YYYY-MM-DD
+
+## Context
+
+What decision needs to be made?
+
+## Decision
+
+What did we decide?
+
+## Consequences
+
+What becomes easier or harder as a result?

data/docs/adr/001-source-revision.md

@@ -0,0 +1,29 @@
+# ADR-001: Share source revision checks, not application policy
+
+- Status: Accepted
+- Date: 2026-09-23
+
+## Context
+
+Canopus, Hadar, and Rukbat each prevent an application save from silently
+overwriting external edits, but they use different policies: Canopus and Rukbat
+compare content digests, while Hadar also uses filesystem signatures to avoid
+reading a deck on every poll. Their settings, commands, keymaps, and themes do
+not share an implementation contract.
+
+The gem is named for μ¹ Scorpii (Xamidimura), an IAU-adopted Khoekhoe name
+derived from *xami di mura*, “eyes of the beast.”
+
+## Decision
+
+Xamidimura owns only stable byte snapshots, filesystem signatures, and SHA-256
+content revisions. Application-specific reload, save, and conflict behavior
+stays in each application. Do not move settings, keymaps, command registries,
+theme loading, or file watchers here without a demonstrated three-application
+contract.
+
+## Consequences
+
+The three applications can agree on how a source revision is observed without
+coupling their editing models or conflict messages. The gem remains small; its
+scope can expand only when another shared behavior is proven by real use.

data/docs/adr/README.md

@@ -0,0 +1,5 @@
+# Architecture decision records
+
+ADRs record decisions that affect Xamidimura's public API or its role in the
+application ecosystem. Accepted decisions are append-only; supersede them with
+a new record rather than rewriting history.

data/lib/xamidimura/source_revision.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Xamidimura
+  class SourceRevision
+    Snapshot = Data.define(:bytes, :signature, :digest)
+
+    def self.digest(bytes)
+      raise TypeError, "source bytes must be a String" unless bytes.is_a?(String)
+
+      Digest::SHA256.hexdigest(bytes)
+    end
+
+    def self.file_digest(path)
+      raise TypeError, "path must be a String" unless path.is_a?(String)
+
+      Digest::SHA256.file(path).hexdigest
+    rescue SystemCallError => error
+      raise Error, error.message
+    end
+
+    def self.signature(path, reject_symlink: false)
+      raise TypeError, "path must be a String" unless path.is_a?(String)
+      unless reject_symlink == true || reject_symlink == false
+        raise ArgumentError, "reject_symlink must be true or false"
+      end
+
+      stat = reject_symlink ? File.lstat(path) : File.stat(path)
+      raise Error, "source path is not a regular file" unless stat.file? && !(reject_symlink && stat.symlink?)
+
+      [stat.dev, stat.ino, stat.size, stat.mtime.to_i, stat.mtime.nsec,
+       stat.ctime.to_i, stat.ctime.nsec].freeze
+    rescue SystemCallError => error
+      raise Error, error.message
+    end
+
+    def self.read(path, attempts: 3, reject_symlink: false)
+      unless attempts.is_a?(Integer) && attempts.between?(1, 10)
+        raise ArgumentError, "attempts must be an integer between 1 and 10"
+      end
+
+      attempts.times do
+        before = signature(path, reject_symlink: reject_symlink)
+        bytes = File.binread(path)
+        after = signature(path, reject_symlink: reject_symlink)
+        next unless before == after
+
+        return Snapshot.new(bytes.freeze, after, digest(bytes).freeze)
+      end
+      raise Error, "source file changed while it was being read; retry"
+    rescue SystemCallError => error
+      raise Error, error.message
+    end
+  end
+end

data/lib/xamidimura/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Xamidimura
+  VERSION = "0.1.0"
+end

data/lib/xamidimura.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "xamidimura/version"
+require_relative "xamidimura/source_revision"
+
+module Xamidimura
+  class Error < StandardError; end
+end

data/sig/xamidimura.rbs

@@ -0,0 +1,17 @@
+module Xamidimura
+  class Error < StandardError
+  end
+
+  class SourceRevision
+    class Snapshot
+      attr_reader bytes: String
+      attr_reader signature: [Integer, Integer, Integer, Integer, Integer, Integer, Integer]
+      attr_reader digest: String
+    end
+
+    def self.digest: (String bytes) -> String
+    def self.file_digest: (String path) -> String
+    def self.signature: (String path, ?reject_symlink: bool) -> [Integer, Integer, Integer, Integer, Integer, Integer, Integer]
+    def self.read: (String path, ?attempts: Integer, ?reject_symlink: bool) -> Snapshot
+  end
+end

data/test/source_revision_test.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require "minitest/mock"
+
+class SourceRevisionTest < Minitest::Test
+  def test_read_returns_bytes_digest_and_stable_signature
+    Dir.mktmpdir do |directory|
+      path = File.join(directory, "source.md")
+      File.binwrite(path, "hello\n")
+
+      snapshot = Xamidimura::SourceRevision.read(path)
+
+      assert_equal "hello\n", snapshot.bytes
+      assert_equal Xamidimura::SourceRevision.digest(snapshot.bytes), snapshot.digest
+      assert_equal snapshot.digest, Xamidimura::SourceRevision.file_digest(path)
+      assert_equal Xamidimura::SourceRevision.signature(path), snapshot.signature
+      assert_predicate snapshot.bytes, :frozen?
+      assert_predicate snapshot.signature, :frozen?
+      assert_predicate snapshot.digest, :frozen?
+    end
+  end
+
+  def test_reject_symlink_and_invalid_arguments
+    Dir.mktmpdir do |directory|
+      path = File.join(directory, "source")
+      link = File.join(directory, "link")
+      File.write(path, "bytes")
+      File.symlink(path, link)
+
+      assert_raises(Xamidimura::Error) { Xamidimura::SourceRevision.signature(link, reject_symlink: true) }
+      assert_raises(Xamidimura::Error) { Xamidimura::SourceRevision.read(link, reject_symlink: true) }
+      assert_raises(ArgumentError) { Xamidimura::SourceRevision.signature(path, reject_symlink: :yes) }
+      assert_raises(TypeError) { Xamidimura::SourceRevision.signature(Object.new) }
+      [0, 11, 1.5].each do |attempts|
+        assert_raises(ArgumentError) { Xamidimura::SourceRevision.read(path, attempts: attempts) }
+      end
+    end
+  end
+
+  def test_read_retries_if_the_file_changes_during_the_read
+    Dir.mktmpdir do |directory|
+      path = File.join(directory, "source")
+      File.write(path, "before")
+      original_read = File.method(:binread)
+      change_after_first_read = true
+
+      snapshot = File.stub(:binread, ->(target, *arguments) {
+        bytes = original_read.call(target, *arguments)
+        if change_after_first_read
+          change_after_first_read = false
+          File.write(path, "after")
+        end
+        bytes
+      }) do
+        Xamidimura::SourceRevision.read(path)
+      end
+
+      assert_equal "after", snapshot.bytes
+      assert_equal Xamidimura::SourceRevision.signature(path), snapshot.signature
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "tmpdir"
+require "xamidimura"

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: xamidimura
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Stable file snapshots and SHA-256 revisions for conflict-safe application
+  saves.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- docs/adr/000-template.md
+- docs/adr/001-source-revision.md
+- docs/adr/README.md
+- lib/xamidimura.rb
+- lib/xamidimura/source_revision.rb
+- lib/xamidimura/version.rb
+- sig/xamidimura.rbs
+- test/source_revision_test.rb
+- test/test_helper.rb
+homepage: https://github.com/noxdea/xamidimura
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/noxdea/xamidimura/tree/main
+  changelog_uri: https://github.com/noxdea/xamidimura/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Shared source revision primitives for Ruby desktop applications
+test_files: []