omoteura 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b75d455c45d6bd7ea34a9f557ee45a71c595384d17fe077da82bd904b507bc8
+  data.tar.gz: 63882a5dfc1cd5aa0ac1371efeea35858b05222045621609862fa0c38ce9a0f1
+SHA512:
+  metadata.gz: 77e33fca85df39fa1e84e28dd692987aaac895343173141d67a9bfddf0afe4dc90a81d8a1abe3653a5507fce37f0e215f4f105a3a2696f628bc95f5c9839e2ff
+  data.tar.gz: f93a8834d735260608dfc5aea9fa4872fd6a8e9b788db5101bd2dc4a324c1ba8956419e70965763c4cc931c65980ffd3ae4e4cb1f728170f639d3f2fd14a242d

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format
+is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.1.0 - 2026-10-23
+
+The first release.
+
+### Added
+
+- Read Excalidraw (`.excalidraw`) and Obsidian Excalidraw (`.md`) drawings,
+  including compressed drawing data.
+- Attach a diagram to a code file by magic comment, `.omoteura.yml` or the
+  `ura/` path convention.
+- Resolve `omoteura:` links to specs, methods and statements.
+- `omoteura check` to report broken links and unattached diagrams.
+- `Omoteura::RSpec::Formatter` to record test results as JSON, and the lines
+  of the project's code that ran when SimpleCov or another tool measures
+  coverage.
+- `omoteura inspect` and `omoteura diagram`, which give editors one file's or
+  one diagram's data as JSON.
+- `omoteura draft` to draft a diagram from code, with every box linked, as
+  `.excalidraw` or, with `--format md`, as an Obsidian note; it never replaces
+  an existing diagram; `--merge` adds only what the diagram has no shape for
+  yet, beside what is drawn, and `--json` prints the results for editors.
+- Write Obsidian Excalidraw notes as the plugin does, keeping what the user
+  wrote above the drawing, and read links edited under its Element Links.
+- `omoteura links`, which lists the places in a code file a shape can link
+  to, each with a link that resolves to exactly that place.
+- `omoteura coverage`, which lists a file's declarations and public methods
+  and the examples that name them, for the editor's coverage panel;
+  `coverage_panel: false` turns it off.
+- `omoteura save` for editors to save a changed drawing in the file's own
+  format, in one step and never over a change made elsewhere since.
+- A clear message, instead of a crash, on Ruby older than 3.4.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KAIBYAKU K.K
+
+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,283 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/logo/omoteura-logo-vertical-dark.svg">
+    <img src="docs/logo/omoteura-logo-vertical.svg" alt="omoteura: code in front, context behind." width="300">
+  </picture>
+</p>
+
+# Omoteura [![CI](https://github.com/kaibyaku-jp/omoteura/actions/workflows/ci.yml/badge.svg)](https://github.com/kaibyaku-jp/omoteura/actions/workflows/ci.yml)
+
+Code in front, context behind.
+
+The code is the *omote* (front). Behind it sits an Excalidraw drawing, the
+*ura* (back): diagrams, notes and the reasons behind the code, with shapes
+that link to the specs and methods they describe.
+
+> **Status:** pre-release, not yet on RubyGems. The gems below already resolve
+> links, check them in CI and record test results. The VS Code extension in
+> [editors/vscode](editors/vscode) marks linked lines with their test results,
+> flips between the code and the drawing, and edits the drawing in place.
+
+
+## Features
+
+### Drawn by You
+
+Omoteura never generates diagrams. Draw them in Obsidian's Excalidraw plugin
+or on excalidraw.com, the way you would sketch on a whiteboard, and drop the
+file next to your code.
+
+### Linked by Name
+
+A shape's link names a spec description, a method or the start of a statement,
+not a line number, so links survive the edits around them.
+
+### Checked in CI
+
+`omoteura check` fails the build when a spec is renamed and a diagram still
+points at the old name, or when a diagram is left behind by a moved file.
+
+### Hands Off Your Code
+
+Omoteura only reads files. It runs from the command line and next to RSpec,
+never inside your application, never rewrites your code and does nothing at
+all where there is no diagram.
+
+### Light
+
+Omoteura reads every Ruby file in a project, so it is measured for allocations
+as well as time. Files without a magic comment are skipped without allocating.
+
+
+## Supported Versions
+
+* Ruby 3.4, 4.0
+
+* Rails 7.1, 7.2, 8.0, 8.1 projects; Omoteura reads their files and never loads Rails
+
+* RSpec 3.12+
+
+* Excalidraw (`.excalidraw`) and Obsidian Excalidraw (`.excalidraw.md`)
+
+
+## Installation
+
+Put this in your Gemfile:
+
+```ruby
+group :development, :test do
+  gem "omoteura", require: false
+end
+```
+
+`require: false` keeps Rails from loading Omoteura into your application; the
+`omoteura` command and RSpec load what they need. Then bundle:
+
+```sh
+% bundle
+```
+
+`omoteura` installs the following gems. You can also pick only the ones you need.
+
+| gem | contents |
+| --- | --- |
+| `omoteura-core` | Diagram files, `omoteura:` links and the `omoteura` command |
+| `omoteura-rspec` | A formatter that records test results for diagrams |
+
+
+## Attaching Diagrams
+
+### By Path
+
+Put the diagram under `ura/` at the same path as the code. Nothing else is
+needed.
+
+| code | diagram |
+| --- | --- |
+| `app/models/user.rb` | `ura/app/models/user.excalidraw.md` |
+| `spec/models/user_spec.rb` | `ura/spec/models/user_spec.excalidraw` |
+
+When both `.excalidraw.md` and `.excalidraw` exist, `.excalidraw.md` is used.
+
+### By Magic Comment
+
+To share one diagram between files or give it any name, write a magic comment
+on its own line at the top or the bottom of the file:
+
+```ruby
+class User < ApplicationRecord
+end
+
+# omoteura: ura/shared/user-validations.excalidraw.md
+```
+
+A path copied from Obsidian without its `.md` works too.
+
+### By `.omoteura.yml`
+
+To leave the code untouched, map files in `.omoteura.yml`:
+
+```yaml
+attach:
+  app/models/user.rb: ura/shared/user-validations.excalidraw.md
+```
+
+A magic comment wins over `.omoteura.yml`, which wins over the path.
+
+
+## Drafting a Diagram
+
+A blank page is the hardest part, so Omoteura can draft a diagram to draw on:
+
+```sh
+% bundle exec omoteura draft spec/models/user_spec.rb
+wrote ura/spec/models/user_spec.excalidraw (4 shapes)
+```
+
+A spec gets a column per example group and a box per example; other code gets
+a column per kind of declaration (validations, associations, callbacks, scopes,
+enums) and one for public methods. Every box already links to its code, so test
+results show up straight away. Then make it yours: move, delete, annotate.
+
+A draft never replaces a diagram. When the file already has one, it goes beside
+it as `user_spec.draft.excalidraw` for you to copy from, and `omoteura check`
+reminds you to delete it. `--format md` writes an Obsidian `.excalidraw.md`
+note instead, and `--dry-run`, `--only methods,validations` and `--out DIR`
+are available too.
+
+As the code grows, `--merge` adds what the diagram has no shape for yet, in
+columns to the right of everything drawn. A shape counts as drawn when its
+link points at the same code or its label is the same, and nothing drawn is
+moved or removed:
+
+```sh
+% bundle exec omoteura draft spec/models/user_spec.rb --merge
+added 2 shapes to ura/spec/models/user_spec.excalidraw
+```
+
+
+## Linking Shapes to Code
+
+Set a shape's link to text starting with `omoteura:`. Both Excalidraw and
+Obsidian let you edit a shape's link.
+
+| link | points to |
+| --- | --- |
+| `omoteura:#email is unique` | the spec whose description ends with "email is unique", in the attached file |
+| `omoteura:#display_name` | the `describe "#display_name"` group, or the method |
+| `omoteura:spec/models/user_spec.rb#validations email is unique` | the same, in another file |
+| `omoteura:app/models/user.rb#validates :email` | the statement that starts with that text |
+| `omoteura:app/models/user.rb` | the whole file |
+
+A fragment is tried as a spec description, then a method name, then the start
+of a statement. A link that matches nothing, or more than one place, is broken.
+
+
+## Checking Links
+
+```sh
+% bundle exec omoteura check
+ura/app/models/user.excalidraw: omoteura:#full_name matches nothing in app/models/user.rb (shape "Display name")
+Checked 12 diagrams and 48 links: 1 problem.
+```
+
+It reports broken links, missing or unreadable diagrams and diagrams no code
+file is attached to, and exits with status 1 when there are any. In GitHub
+Actions, add `--format github` to see the problems as annotations.
+
+
+## Recording Test Results
+
+Add the formatter to `.rspec`, next to your usual one:
+
+```text
+--format progress
+--format Omoteura::RSpec::Formatter --out tmp/omoteura/results.json
+```
+
+Each example's status and failure message go to `tmp/omoteura/results.json`.
+Keep `tmp/omoteura/` out of version control.
+
+When something already measures coverage, as SimpleCov does, the formatter
+also records which lines of your code ran, so the coverage panel can tell
+which methods the tests called. It never starts coverage itself.
+
+
+## In VS Code
+
+The extension in [editors/vscode](editors/vscode) marks each line a shape
+links to with the result of the tests behind it, explains it on hover, and
+flips between a file and its diagram with `⌥⌘U` (`Ctrl+Alt+U`). The diagram
+opens in Excalidraw with linked shapes outlined by test status; clicking a
+link opens the code. Saving writes the file's own format, so an Obsidian note
+keeps everything around the drawing, and a change made elsewhere since it
+opened is never overwritten. A coverage panel lists which declarations and
+public methods of the open file its specs cover.
+
+
+## Commands
+
+| command | does |
+| --- | --- |
+| `omoteura check` | Report broken links and diagrams not attached to code |
+| `omoteura draft FILE...` | Draft a diagram from code, as a starting point to draw on |
+| `omoteura inspect FILE` | Print one file's diagram, links and test results as JSON, for editors |
+| `omoteura diagram FILE` | Print one diagram's drawing, links and test results as JSON, for editors |
+| `omoteura links FILE` | Print the places in one code file a shape can link to, with their links, as JSON, for editors |
+| `omoteura coverage FILE` | Print which declarations and public methods of one file its specs cover, as JSON, for editors |
+| `omoteura save FILE` | Save a drawing an editor changed, read as JSON from stdin, in the file's format |
+| `omoteura version` | Print the version |
+
+Run `omoteura <command> --help` for options.
+
+
+## Configuring Omoteura
+
+`.omoteura.yml` at the project root is optional:
+
+| key | default | meaning |
+| --- | --- | --- |
+| `diagrams_dir` | `ura` | Where diagrams live, relative to the root |
+| `attach` | none | Code paths mapped to diagram paths |
+| `coverage_panel` | `true` | `false` turns off the editor's list of tested and untested declarations and methods |
+
+`.omoteura.local.yml` is read on top of it, entry by entry, for settings of
+your own. Keep it out of version control.
+
+
+## Questions, Feedback
+
+Open an issue on GitHub. Report security problems privately as described in
+[SECURITY.md](SECURITY.md).
+
+
+## Contributing to Omoteura
+
+Fork, fix, then send a pull request. [CONTRIBUTING.md](CONTRIBUTING.md) has the
+details.
+
+To run the specs and lint:
+
+```sh
+% nix develop          # or use Ruby 3.4+ without Nix
+% bundle install
+% bundle exec rake
+```
+
+To run the specs against the oldest supported rspec-core:
+
+```sh
+% BUNDLE_GEMFILE=gemfiles/rspec_3_12.gemfile bundle install
+% BUNDLE_GEMFILE=gemfiles/rspec_3_12.gemfile bundle exec rake spec
+```
+
+To measure allocations and time of the main code paths:
+
+```sh
+% bundle exec rake bench
+```
+
+
+## Copyright
+
+Copyright (c) 2026- KAIBYAKU K.K. See [LICENSE](LICENSE) for further details.

data/lib/omoteura.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "omoteura/core"
+require "omoteura/rspec"

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: omoteura
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- KAIBYAKU K.K
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: omoteura-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: omoteura-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: Meta gem that installs omoteura-core and omoteura-rspec.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/omoteura.rb
+homepage: https://github.com/kaibyaku-jp/omoteura
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kaibyaku-jp/omoteura
+  changelog_uri: https://github.com/kaibyaku-jp/omoteura/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Overlay hand-drawn Excalidraw diagrams on Rails and RSpec code
+test_files: []