sargasso 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e993c1b7af47b4e9924c31ca18f9f8eab56235a3c35fc1b58509bf899e6e4a6c
+  data.tar.gz: 7be2a0c6a1ba3646b6428dbc8503dd0f0be774d4e5855a0ed70d1282720b553e
+SHA512:
+  metadata.gz: 96efae4db9533a137da49cbfc928261ede6d8ed7ed852fc00cc6c56e0299fcdf08b557eb8e0ff2b214212c60bb4f3397b7f9d12cbbbcdc22b6323035443f0992
+  data.tar.gz: 4e7a7cec1fdf01bdb7f7ac241b8efdaaa3fa80cc50bdb067dc21307e5e92dba5346647da3a97b95b89f060db472542d33692ccf26fe8b0ddb718b8b5c66babcf

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- Minimum Ruby version raised to 3.3.0 (the development toolchain requires it)
+
+## [0.0.1] - 2026-09-03
+
+### Added
+
+- Initial release
+- `Sargasso.convert(plantuml_string)` converts PlantUML source to Mermaid source
+- Sequence diagram support: messages, participant aliases, dashed/return arrows, `alt`/`else` blocks
+- Diagram-agnostic AST (`Parser` -> `AST` -> `Emitters::Mermaid`) so more diagram types and emitters can be added later
+- CLI (`sargasso`) with file argument, stdin via `-`, `--quiet`, and `--strict`
+- Unsupported PlantUML constructs are reported as warnings by default, or raise `Sargasso::UnsupportedConstructError` under `--strict`
+- Minitest suite with golden-file fixtures (`.puml` / `.mmd` pairs)

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at **kerrizor@kerrizor.com**. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing to Sargasso
+
+Thanks for your interest in contributing to Sargasso! This document covers how to get started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/kerrizor/sargasso.git
+cd sargasso
+bundle install
+```
+
+## Running Tests
+
+```bash
+bundle exec rake test
+```
+
+Or run the full default task (tests plus RuboCop):
+
+```bash
+bundle exec rake
+```
+
+All tests must pass and RuboCop must be clean before submitting a PR.
+
+## Code Style
+
+- Use `frozen_string_literal: true` at the top of all Ruby files
+- Follow standard Ruby conventions (enforced by RuboCop)
+- Keep methods small and focused
+- Add tests for new functionality
+- No em-dashes in prose (use commas, parentheses, or restructure)
+
+## Architecture
+
+Sargasso converts diagrams through a three-stage pipeline:
+
+```
+PlantUML source -> Sargasso::Parser -> Sargasso::AST -> Sargasso::Emitters::Mermaid -> Mermaid source
+```
+
+- **`Sargasso::Parser`** turns PlantUML source into AST nodes.
+- **`Sargasso::AST`** is a diagram-agnostic set of structs (`Diagram`, `Participant`, `Message`, `Alt`, `Branch`, `Unsupported`). It knows nothing about PlantUML or Mermaid syntax.
+- **`Sargasso::Emitters::Mermaid`** turns AST nodes into Mermaid source.
+
+Keeping the AST neutral is what lets new diagram types and new emitters (for example draw.io or graphviz) slot in without a rewrite. When you add support for a construct, add the AST node first, then teach the parser to produce it and the emitter to render it.
+
+## Adding Support for a New Construct
+
+The most common contribution is teaching Sargasso a PlantUML construct it does not yet understand (currently these become `AST::Unsupported` and produce a warning). Each addition is three coordinated changes plus a fixture pair.
+
+### 1. Add or reuse an AST node
+
+If the construct needs new structure, add a struct to `lib/sargasso/ast.rb`. Keep it source-agnostic and target-agnostic. For example, a note might be:
+
+```ruby
+# A note attached to one or more participants.
+#
+# position is a neutral placement: :left, :right, or :over.
+#
+Note = Struct.new(:position, :participants, :text, keyword_init: true)
+```
+
+### 2. Teach the parser to produce it
+
+In `lib/sargasso/parser.rb`, match the PlantUML line and build the AST node instead of falling through to `AST::Unsupported`.
+
+### 3. Teach the emitter to render it
+
+In `lib/sargasso/emitters/mermaid.rb`, handle the new node type and emit the equivalent Mermaid syntax. If Mermaid has no equivalent, record a warning (or raise `Sargasso::UnsupportedConstructError` under strict mode) rather than dropping it silently.
+
+### 4. Add a golden-file fixture pair
+
+Add a matching pair under `test/fixtures/`:
+
+- `test/fixtures/my_construct.puml` (the PlantUML input)
+- `test/fixtures/my_construct.mmd` (the expected Mermaid output)
+
+Then assert the conversion in `test/test_sargasso.rb`:
+
+```ruby
+def test_my_construct
+  assert_fixture_converts("my_construct")
+end
+```
+
+### 5. Update documentation
+
+- Update the feature/feasibility table in `README.md` if coverage changed
+- Add a changelog entry under `[Unreleased]`
+
+## Adding a New Diagram Type
+
+Sequence diagrams are the only supported type in v1. Adding another type (class, state, ER, and so on) follows the same pattern at a larger scale: add the AST nodes it needs, add a parser path that recognizes the diagram's opening syntax, and add emitter cases that render it. See the feasibility ranking in the README and in the idea doc for which types map cleanly to Mermaid.
+
+## Pull Request Process
+
+1. **Branch naming**: Use `your-username/description` (for example `kerrizor/support-notes`)
+
+2. **Changelog**: Add an entry to `CHANGELOG.md` under `[Unreleased]`:
+   ```markdown
+   ### Added
+   - **Notes** - `note left/right/over` now converts to Mermaid notes
+   ```
+
+3. **Tests**: Ensure `bundle exec rake` passes (tests plus RuboCop)
+
+4. **PR description**: Explain what the change does and why
+
+## Questions?
+
+Open an issue if you have questions or want to discuss a feature before implementing it.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Kerri Miller
+
+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,142 @@
+# Sargasso 🌊
+
+**PlantUML goes in, Mermaid comes out.**
+
+The Sargasso Sea is the one stretch of ocean defined by its seaweed rather than
+its shores, a floating tangle that catches whatever drifts through. This gem is
+that tangle for your diagrams: feed it PlantUML and it hands back the equivalent
+Mermaid, so your old diagrams wash up somewhere they can actually be rendered.
+
+```
+🧜 PlantUML sequence diagrams -> Mermaid, in pure Ruby
+🪸 Parser -> AST -> Emitter, so new diagram types can grow on the reef
+🐚 Nothing dropped silently: unknown syntax warns, or raises under --strict
+```
+
+It also fills a genuine gap: no Ruby gem does this today, and the wider
+ecosystem is thin (a couple of JavaScript tools, some hosted web apps).
+
+Named for the free-floating *Sargassum* seaweed of the Sargasso Sea.
+
+## Why parse the source directly (the no-clean-bridge rationale)
+
+PlantUML never exports a neutral, re-serializable semantic model. Its native
+exports are renders (PNG, SVG, PDF), and its structured exports are narrow and
+lossy (SCXML for state diagrams only, XMI for class diagrams only). There is no
+reliable intermediate format to lean on, so Sargasso parses PlantUML source
+directly and emits Mermaid.
+
+## Installation
+
+Install the gem from RubyGems (once published):
+
+```bash
+gem install sargasso
+```
+
+Or add it to a Gemfile:
+
+```ruby
+gem "sargasso"
+```
+
+Sargasso is pure Ruby with no Node or JavaScript runtime dependency.
+
+## Usage
+
+```ruby
+require "sargasso"
+
+plantuml = <<~PUML
+  @startuml
+  Alice -> Bob: Hello
+  Bob --> Alice: Hi back
+  @enduml
+PUML
+
+puts Sargasso.convert(plantuml)
+```
+
+Output:
+
+```
+sequenceDiagram
+    Alice->>Bob: Hello
+    Bob-->>Alice: Hi back
+```
+
+PlantUML `->` maps to Mermaid's solid arrow (`->>`), and `-->` maps to the
+dashed arrow (`-->>`). The `@startuml` and `@enduml` markers are stripped, and
+message lines are indented under `sequenceDiagram`.
+
+### Unsupported constructs
+
+By default, a construct Sargasso does not understand produces a warning and is
+skipped rather than silently dropped. You can collect those warnings, or opt
+into strict mode to raise instead:
+
+```ruby
+warnings = []
+Sargasso.convert(plantuml, warnings: warnings)  # warnings gathered here
+
+Sargasso.convert(plantuml, strict: true)        # raises on the first unsupported construct
+```
+
+## CLI
+
+```bash
+sargasso path/to/diagram.puml     # convert a file, write Mermaid to stdout
+cat diagram.puml | sargasso -     # read from stdin, write to stdout
+sargasso --quiet diagram.puml     # suppress warnings
+sargasso --strict diagram.puml    # exit non-zero on any unsupported construct
+```
+
+## Scope: v1 supports sequence diagrams only
+
+Sequence is the best-covered diagram type across every existing tool, so it is
+the v1 target. Other diagram types are not yet supported. The feasibility table
+below cross-references the design notes in the idea doc.
+
+| PlantUML diagram | Mermaid target      | Feasibility                       | Status        |
+|------------------|---------------------|-----------------------------------|---------------|
+| Sequence         | `sequenceDiagram`   | High (proven by pu2mm)            | v1 (this gem) |
+| Class            | `classDiagram`      | Medium (partial in other tools)   | planned (v2)  |
+| State            | `stateDiagram-v2`   | Medium (SCXML path possible)      | planned (v2)  |
+| Activity (beta)  | `flowchart`         | Low/Medium (structural mismatch)  | not planned   |
+| Component        | `flowchart`/`graph` | Low (approximate only)            | not planned   |
+| Use case         | `flowchart`         | Low (no native Mermaid use-case)  | not planned   |
+| ER               | `erDiagram`         | Medium                            | maybe         |
+| Gantt            | `gantt`             | Medium                            | maybe         |
+
+The pipeline is structured as `Parser -> AST -> Emitter` so additional diagram
+types and additional emitters (for example draw.io) can be added later without
+a rewrite.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run
+`rake test` to run the tests and `rake rubocop` to lint. You can also run
+`bin/console` for an interactive prompt.
+
+Tests use golden-file fixtures: each pair `test/fixtures/<name>.puml` and
+`test/fixtures/<name>.mmd` asserts that converting the PlantUML input produces
+the expected Mermaid output.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of notable changes to each release.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/kerrizor/sargasso. See [CONTRIBUTING.md](CONTRIBUTING.md) for
+development setup, the `Parser -> AST -> Emitter` architecture, and how to add
+support for a new construct or diagram type.
+
+Everyone interacting in the Sargasso project is expected to follow the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+Available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/exe/sargasso

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "sargasso/cli"
+
+exit Sargasso::CLI.new(ARGV).run

data/lib/sargasso/ast.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Sargasso
+  # Diagram-agnostic AST nodes.
+  #
+  # These structs describe the semantic content of a diagram independent of any
+  # source (PlantUML) or target (Mermaid) syntax. Parsers build them; emitters
+  # consume them. Keeping this layer neutral is what lets a future grammar or a
+  # future emitter (draw.io, graphviz) slot in without a rewrite.
+  #
+  module AST
+    # The root of a parsed diagram. For v1, kind is always :sequence.
+    #
+    Diagram = Struct.new(:kind, :nodes, keyword_init: true) do
+      def initialize(kind:, nodes: [])
+        super
+      end
+    end
+
+    # A declared participant or actor, with an optional display label.
+    #
+    # id is the identifier used in messages. label is the human display name
+    # (nil when the declaration had no alias).
+    #
+    Participant = Struct.new(:id, :label, keyword_init: true)
+
+    # A message from one participant to another.
+    #
+    # arrow is the neutral arrow kind: :solid or :dashed. The emitter decides
+    # the concrete target syntax.
+    #
+    Message = Struct.new(:from, :to, :text, :arrow, keyword_init: true)
+
+    # An alt/else group. branches is an array of Branch nodes.
+    #
+    Alt = Struct.new(:branches, keyword_init: true) do
+      def initialize(branches: [])
+        super
+      end
+    end
+
+    # One branch of a group (the alt label, or an else label).
+    #
+    Branch = Struct.new(:label, :nodes, keyword_init: true) do
+      def initialize(label:, nodes: [])
+        super
+      end
+    end
+
+    # A construct sargasso does not yet understand. Kept in the tree so the
+    # emitter can warn (or, under strict mode, raise) rather than silently
+    # dropping input.
+    #
+    Unsupported = Struct.new(:source, keyword_init: true)
+  end
+end

data/lib/sargasso/cli.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../sargasso"
+
+module Sargasso
+  # Command-line entry point.
+  #
+  #   sargasso path/to/diagram.puml     # -> stdout Mermaid
+  #   cat diagram.puml | sargasso -     # stdin -> stdout
+  #   sargasso --quiet ...              # suppress warnings
+  #   sargasso --strict ...             # fail on any unsupported construct
+  #
+  class CLI
+    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      @argv = argv
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @options = { quiet: false, strict: false }
+    end
+
+    # Returns a process exit status (0 success, non-zero failure).
+    #
+    def run
+      paths = parse_options
+      return 0 if @help
+
+      source = read_source(paths)
+      return 1 if source.nil?
+
+      convert_and_emit(source)
+    rescue Sargasso::UnsupportedConstructError => e
+      @stderr.puts("sargasso: #{e.message}")
+      1
+    end
+
+    private
+
+    def convert_and_emit(source)
+      warnings = []
+      output = Sargasso.convert(source, strict: @options[:strict], warnings: warnings)
+      @stdout.puts(output)
+      report_warnings(warnings)
+      0
+    end
+
+    def parse_options
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: sargasso [options] FILE|-"
+        opts.on("--quiet", "Suppress warnings") { @options[:quiet] = true }
+        opts.on("--strict", "Fail on any unsupported construct") { @options[:strict] = true }
+        opts.on("-h", "--help", "Show this help") do
+          @stdout.puts(opts)
+          @help = true
+        end
+      end
+      parser.parse(@argv)
+    end
+
+    def read_source(paths)
+      path = paths.first
+      if path.nil?
+        @stderr.puts("sargasso: no input file given (use '-' for stdin)")
+        return nil
+      end
+
+      path == "-" ? @stdin.read : File.read(path)
+    rescue Errno::ENOENT
+      @stderr.puts("sargasso: no such file: #{path}")
+      nil
+    end
+
+    def report_warnings(warnings)
+      return if @options[:quiet]
+
+      warnings.each { |w| @stderr.puts("sargasso: warning: #{w}") }
+    end
+  end
+end

data/lib/sargasso/emitters/mermaid.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "../ast"
+
+module Sargasso
+  module Emitters
+    # Emits Mermaid sequenceDiagram source from a Sargasso::AST::Diagram.
+    #
+    # Each message line is indented one level (4 spaces) under the
+    # "sequenceDiagram" header. Nested groups (alt/else) add further indentation.
+    #
+    class Mermaid
+      ARROWS = { solid: "->>", dashed: "-->>" }.freeze
+      INDENT = "    "
+
+      # warnings collects human-readable messages about unsupported constructs.
+      # In strict mode the first unsupported construct raises instead.
+      #
+      attr_reader :warnings
+
+      def initialize(strict: false)
+        @strict = strict
+        @warnings = []
+      end
+
+      def emit(diagram)
+        lines = ["sequenceDiagram"]
+        emit_nodes(diagram.nodes, lines, 1)
+        "#{lines.join("\n")}\n"
+      end
+
+      private
+
+      def emit_nodes(nodes, lines, depth)
+        nodes.each { |node| emit_node(node, lines, depth) }
+      end
+
+      def emit_node(node, lines, depth)
+        case node
+        when AST::Participant then lines << participant_line(node, depth)
+        when AST::Message then lines << message_line(node, depth)
+        when AST::Alt then emit_alt(node, lines, depth)
+        when AST::Unsupported then handle_unsupported(node)
+        end
+      end
+
+      def participant_line(node, depth)
+        line = "#{INDENT * depth}participant #{node.id}"
+        line += " as #{node.label}" if node.label
+        line
+      end
+
+      def message_line(node, depth)
+        "#{INDENT * depth}#{node.from}#{ARROWS.fetch(node.arrow)}#{node.to}: #{node.text}"
+      end
+
+      def emit_alt(alt, lines, depth)
+        alt.branches.each_with_index do |branch, index|
+          keyword = index.zero? ? "alt" : "else"
+          label = branch.label.empty? ? keyword : "#{keyword} #{branch.label}"
+          lines << "#{INDENT * depth}#{label}"
+          emit_nodes(branch.nodes, lines, depth + 1)
+        end
+        lines << "#{INDENT * depth}end"
+      end
+
+      def handle_unsupported(node)
+        message = "unsupported construct: #{node.source.inspect}"
+        raise Sargasso::UnsupportedConstructError, message if @strict
+
+        @warnings << message
+      end
+    end
+  end
+end

data/lib/sargasso/parser.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "ast"
+
+module Sargasso
+  # Parses PlantUML sequence-diagram source into Sargasso::AST nodes.
+  #
+  # v1 is deliberately line-oriented: PlantUML sequence syntax is largely
+  # line-based, so a set of per-line matchers gets us a useful walking skeleton
+  # fast. The AST layer sits between this and the emitter so a real grammar can
+  # replace this parser later without touching emitters.
+  #
+  class Parser
+    # Matches a message line: "A -> B: text" or "A --> B : text".
+    # Group 1: source, 2: arrow, 3: target, 4: optional text.
+    #
+    MESSAGE = /\A(\S+)\s*(-+>+)\s*(\S+)\s*(?::\s*(.*))?\z/
+
+    # Matches a participant/actor declaration, with optional quoted label and
+    # "as" alias:
+    #   participant Bob
+    #   participant "Bob B." as B
+    #   actor Alice
+    # Group 1: keyword, 2: quoted name (optional), 3: bare name (optional),
+    # 4: alias (optional).
+    #
+    PARTICIPANT = /\A(participant|actor)\s+(?:"([^"]+)"|(\S+))(?:\s+as\s+(\S+))?\z/i
+
+    ALT = /\Aalt\b\s*(.*)\z/i
+    ELSE = /\Aelse\b\s*(.*)\z/i
+    END_GROUP = /\Aend\b\z/i
+
+    def initialize(source)
+      @source = source
+    end
+
+    def parse
+      diagram = AST::Diagram.new(kind: :sequence)
+      # Stack of node lists; the top is where new nodes are appended. Groups
+      # (alt/else) push a new branch's node list onto this stack.
+      #
+      @stack = [diagram.nodes]
+
+      each_significant_line do |line|
+        parse_line(line)
+      end
+
+      diagram
+    end
+
+    private
+
+    def each_significant_line
+      @source.each_line do |raw|
+        line = raw.strip
+        next if line.empty?
+        next if line.start_with?("@startuml", "@enduml")
+        next if line.start_with?("'") # PlantUML single-line comment
+
+        yield line
+      end
+    end
+
+    def parse_line(line)
+      case line
+      when ALT then start_alt(Regexp.last_match(1))
+      when ELSE then start_else(Regexp.last_match(1))
+      when END_GROUP then end_group
+      when PARTICIPANT then push_participant(Regexp.last_match)
+      when MESSAGE then push_message(Regexp.last_match)
+      else current << AST::Unsupported.new(source: line)
+      end
+    end
+
+    def push_participant(match)
+      quoted = match[2]
+      bare = match[3]
+      alias_name = match[4]
+
+      # With an alias, the alias is the id and the name is the label. Without
+      # one, the name (quoted or bare) is the id and there is no separate label.
+      #
+      participant = if alias_name
+                      AST::Participant.new(id: alias_name, label: quoted || bare)
+                    else
+                      AST::Participant.new(id: quoted || bare, label: nil)
+                    end
+
+      current << participant
+    end
+
+    def push_message(match)
+      arrow = match[2].include?("--") ? :dashed : :solid
+      current << AST::Message.new(
+        from: match[1],
+        to: match[3],
+        text: match[4].to_s.strip,
+        arrow: arrow
+      )
+    end
+
+    def start_alt(label)
+      alt = AST::Alt.new
+      branch = AST::Branch.new(label: label.strip)
+      alt.branches << branch
+      current << alt
+      @open_alts ||= []
+      @open_alts << alt
+      @stack.push(branch.nodes)
+    end
+
+    def start_else(label)
+      # Replace the current branch's node list with a new else branch.
+      #
+      @stack.pop
+      alt = @open_alts.last
+      branch = AST::Branch.new(label: label.strip)
+      alt.branches << branch
+      @stack.push(branch.nodes)
+    end
+
+    def end_group
+      @stack.pop
+      @open_alts&.pop
+    end
+
+    def current
+      @stack.last
+    end
+  end
+end

data/lib/sargasso/version.rb

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

data/lib/sargasso.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "sargasso/version"
+require_relative "sargasso/ast"
+require_relative "sargasso/parser"
+require_relative "sargasso/emitters/mermaid"
+
+# Sargasso converts PlantUML diagram source into equivalent Mermaid source.
+#
+# v1 supports sequence diagrams only. The pipeline is:
+#   PlantUML source -> Sargasso::Parser -> Sargasso::AST -> Emitters::Mermaid
+#
+module Sargasso
+  class Error < StandardError; end
+
+  # Raised when strict mode encounters a construct sargasso cannot convert.
+  #
+  class UnsupportedConstructError < Error; end
+
+  module_function
+
+  # Convert PlantUML source into Mermaid source.
+  #
+  # strict: raise UnsupportedConstructError on any unsupported construct.
+  # warnings: an optional array that collected warnings are appended to.
+  #
+  def convert(plantuml_string, strict: false, warnings: nil)
+    diagram = Parser.new(plantuml_string).parse
+    emitter = Emitters::Mermaid.new(strict: strict)
+    output = emitter.emit(diagram)
+    warnings&.concat(emitter.warnings)
+    output
+  end
+end

data/sig/sargasso.rbs

@@ -0,0 +1,4 @@
+module Sargasso
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: sargasso
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Kerri Miller
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Sargasso parses PlantUML source directly and emits Mermaid diagram source.
+  v1 supports sequence diagrams. Pure Ruby, no Node or JavaScript runtime dependency.
+email:
+- kerrizor@kerrizor.com
+executables:
+- sargasso
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/sargasso
+- lib/sargasso.rb
+- lib/sargasso/ast.rb
+- lib/sargasso/cli.rb
+- lib/sargasso/emitters/mermaid.rb
+- lib/sargasso/parser.rb
+- lib/sargasso/version.rb
+- sig/sargasso.rbs
+homepage: https://github.com/kerrizor/sargasso
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kerrizor/sargasso
+  source_code_uri: https://github.com/kerrizor/sargasso/tree/main
+  changelog_uri: https://github.com/kerrizor/sargasso/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/kerrizor/sargasso/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Convert PlantUML diagram source into equivalent Mermaid source.
+test_files: []