lilac-cli 0.2.0

data/lib/lilac/cli/watcher.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "listen"
+
+module Lilac
+  module CLI
+    # Thin wrapper around `listen` that coalesces bursts of file events
+    # into a single `on_change` callback. Editors that "save" via
+    # write-then-rename or "mtime touch" frequently emit 2–5 events in
+    # rapid succession; without debouncing we would rebuild that many
+    # times.
+    #
+    # The implementation timer-resets on each event: after the most
+    # recent event, we wait `debounce` seconds of quiet, then fire.
+    class Watcher
+      DEFAULT_DEBOUNCE = 0.15
+
+      def initialize(paths, debounce: DEFAULT_DEBOUNCE, &on_change)
+        raise ArgumentError, "block required" unless on_change
+
+        @paths = paths
+        @debounce = debounce
+        @on_change = on_change
+        @listener = nil
+        @pending = nil
+        @mutex = Mutex.new
+      end
+
+      def start
+        # No `only:` filter: callers pass `components/`, `pages/`, and
+        # `public/`, and the public mirror needs to react to arbitrary
+        # static assets (.js, .css, .wasm, images). Listen's default
+        # ignore list already filters .git, swap files, OS metadata.
+        @listener = Listen.to(*@paths) do |_modified, _added, _removed|
+          schedule_change
+        end
+        @listener.start
+      end
+
+      def stop
+        @listener&.stop
+        @mutex.synchronize { @pending&.kill }
+      end
+
+      private
+
+      def schedule_change
+        @mutex.synchronize do
+          @pending&.kill
+          @pending = Thread.new do
+            sleep @debounce
+            begin
+              @on_change.call
+            rescue StandardError => e
+              warn "lilac watcher: callback raised #{e.class}: #{e.message}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lilac/cli.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "cli/version"
+require_relative "cli/build/sfc"
+require_relative "cli/build/compiled_runtime_resolver"
+require_relative "cli/package_discovery"
+require_relative "cli/build/builder"
+require_relative "cli/config_loader"
+require_relative "cli/config"
+require_relative "cli/live_reload"
+require_relative "cli/watcher"
+require_relative "cli/dev_server"
+require_relative "cli/scaffold"
+require_relative "cli/doctor"
+require_relative "cli/command"
+
+module Lilac
+  module CLI
+  end
+end

data/lib/lilac/directives/class_parser.rb

@@ -0,0 +1,179 @@
+module Lilac
+  module Directives
+    # Parser for the `data-class` hash literal grammar.
+    #
+    # Duplicate pair (build-time / runtime). See decisions §17.
+    #
+    #   { active: @is_active, 'btn-primary': @primary, "hover:bg-blue": @h }
+    #
+    # Returns Array<[key_string, value_string]> in source order. Keys
+    # are returned as plain strings (quotes stripped); values are the
+    # raw text between `:` and the next `,` / `}`, leaving value-
+    # grammar validation (ivar / bare ident) to the caller (Scanner).
+    #
+    # Quoted keys may contain `:` (Tailwind variants like
+    # `'hover:bg-blue-500'`), so a naive split-on-colon would break.
+    # The grammar is stricter than JSON (forbids `;`, control chars,
+    # whitespace inside keys) and looser elsewhere (bare Ruby idents
+    # as keys, no string quoting on values).
+    #
+    # Per-character checks use char comparisons rather than JS-bridged
+    # Regexp.test calls because they run in inner loops; whole-string
+    # validates use Regexp.
+    class ClassParser
+      class Error < StandardError; end
+
+      BARE_KEY = /^[a-zA-Z_][a-zA-Z0-9_]*$/
+
+      # Spec 6.4: quoted-key body forbids whitespace, control chars
+      # (\x00-\x1F + \x7F), `;`, and any quote character. Checked via
+      # `valid_quoted_body?` (char-walk) instead of a Regexp because
+      # mruby-regexp-compat doesn't support `\xHH` hex escapes inside
+      # character classes — `[^\s\\'";\x00-\x1F\x7F]` mis-parses as a
+      # class containing literal `x`/`0`/etc.
+
+      def self.parse(source)
+        new(source).parse
+      end
+
+      def initialize(source)
+        @src = source.to_s
+        @pos = 0
+      end
+
+      def parse
+        skip_ws
+        expect("{")
+        skip_ws
+        pairs = []
+        unless peek == "}"
+          pairs << parse_pair
+          loop do
+            skip_ws
+            break unless peek == ","
+            advance
+            skip_ws
+            pairs << parse_pair
+          end
+        end
+        skip_ws
+        expect("}")
+        skip_ws
+        if @pos < @src.length
+          raise Error, "unexpected trailing content: #{@src[@pos..].inspect}"
+        end
+        pairs
+      end
+
+      private
+
+      def parse_pair
+        skip_ws
+        key = parse_key
+        skip_ws
+        expect(":")
+        skip_ws
+        value = parse_value
+        [key, value]
+      end
+
+      def parse_key
+        case peek
+        when "'" then parse_quoted("'")
+        when '"' then parse_quoted('"')
+        else parse_bare_ident
+        end
+      end
+
+      def parse_quoted(quote)
+        advance
+        start = @pos
+        @pos += 1 while @pos < @src.length && @src[@pos] != quote
+        raise Error, "unterminated #{quote} string" if @pos >= @src.length
+        body = @src[start...@pos]
+        advance
+        unless valid_quoted_body?(body)
+          raise Error,
+                "invalid character(s) in quoted key #{body.inspect} " \
+                "(whitespace, control chars, `;`, and quotes are forbidden)"
+        end
+        body
+      end
+
+      def parse_bare_ident
+        start = @pos
+        @pos += 1 while @pos < @src.length && bare_key_char?(@src[@pos])
+        body = @src[start...@pos]
+        raise Error, "expected hash key at position #{start}, got #{peek.inspect}" if body.empty?
+        unless BARE_KEY.match?(body)
+          raise Error,
+                "bare hash key #{body.inspect} is not a Ruby identifier " \
+                "(use quoted form for kebab / special chars)"
+        end
+        body
+      end
+
+      # Values are ivar (`@x`) / bare ident (`x`) — neither contains
+      # the hash delimiters `,` / `}` nor whitespace, so stop at the
+      # first whitespace or delimiter. Grammar validation happens in
+      # the caller (Scanner.dispatch_class via Value.parse).
+      def parse_value
+        start = @pos
+        until @pos >= @src.length
+          ch = @src[@pos]
+          break if ch == "," || ch == "}" || ws_char?(ch)
+          @pos += 1
+        end
+        raise Error, "expected value, got #{peek.inspect} at #{start}" if @pos == start
+        @src[start...@pos]
+      end
+
+      def skip_ws
+        @pos += 1 while @pos < @src.length && ws_char?(@src[@pos])
+      end
+
+      def peek
+        @src[@pos]
+      end
+
+      def advance
+        c = @src[@pos]
+        @pos += 1
+        c
+      end
+
+      def expect(ch)
+        actual = @src[@pos]
+        if actual != ch
+          raise Error, "expected #{ch.inspect}, got #{actual.inspect} at position #{@pos}"
+        end
+        @pos += 1
+      end
+
+      # Per-char predicates inlined to avoid a JS-bridged Regexp.test
+      # call per character (which would dominate cost in tight loops).
+
+      def ws_char?(c)
+        c == " " || c == "\t" || c == "\n" || c == "\r" || c == "\f" || c == "\v"
+      end
+
+      def bare_key_char?(c)
+        (c >= "a" && c <= "z") || (c >= "A" && c <= "Z") ||
+          (c >= "0" && c <= "9") || c == "_"
+      end
+
+      # Whole-body validator for quoted keys. Rejects empty, any of
+      # `\\`, `'`, `"`, `;`, whitespace, control chars (< 0x20 or == 0x7F).
+      def valid_quoted_body?(body)
+        return false if body.empty?
+        body.each_char do |c|
+          return false if c == "\\" || c == "'" || c == "\"" || c == ";"
+          return false if ws_char?(c)
+          code = c.ord
+          return false if code < 0x20 || code == 0x7F
+        end
+        true
+      end
+    end
+  end
+end

data/lib/lilac/directives/collision_rules.rb

@@ -0,0 +1,49 @@
+module Lilac
+  module Directives
+    # Collision rules SSOT — duplicate pair (build-time / runtime).
+    # See decisions §17.
+    #
+    # The data here is consumed by both halves of `Lints`:
+    #   - build-time: `Lilac::Directives::Lints.check!` (raises)
+    #   - runtime:    `Lilac::Directives::Lints.check!` (warn+skip /
+    #                 raise depending on severity)
+    #
+    # Each row in COLLISION_PAIRS is `[attrs, message]` where `attrs`
+    # is the unordered pair of `data-*` attribute names that may not
+    # coexist on the same element, and `message` is the human-readable
+    # rationale used in both build-error and runtime warning text.
+    # Attribute-name form (not Symbol kinds) lets the same rules apply
+    # uniformly to built-in directives and class-based Handler packages
+    # (ADR-0027) — the public surface a user actually writes is the
+    # attribute name, so matching against it removes the Symbol-pivot
+    # indirection on both sides.
+    module Lints
+      COLLISION_PAIRS = [
+        [
+          %w[data-text data-unsafe-html],
+          "data-text and data-unsafe-html cannot coexist (both write the element body)",
+        ],
+        [
+          %w[data-text data-each],
+          "data-text and data-each cannot coexist (data-each generates children; data-text would overwrite them)",
+        ],
+        [
+          %w[data-unsafe-html data-each],
+          "data-unsafe-html and data-each cannot coexist (data-each generates children; data-unsafe-html would overwrite them)",
+        ],
+        [
+          %w[data-show data-hide],
+          "data-show and data-hide cannot coexist (use one; the inverse is implicit)",
+        ],
+        [
+          %w[data-component data-each],
+          "data-component and data-each cannot coexist (wrap with another element — put the child component inside the iteration body)",
+        ],
+        [
+          %w[data-bind data-field],
+          "data-bind and data-field cannot coexist (both wire the input value — pick one: data-bind for form-independent binding, data-field for form-scope binding)",
+        ],
+      ].freeze
+    end
+  end
+end

data/lib/lilac/directives/grammar.rb

@@ -0,0 +1,76 @@
+module Lilac
+  module Directives
+    # Predicates for the *name-shaped* tokens that appear in directives —
+    # event-handler method names, the X parts of `data-attr-X` /
+    # `data-css-X`, and the banned-attribute deny-list.
+    #
+    # Duplicate pair (build-time / runtime). See decisions §17.
+    #
+    # Reactive *values* (`@ivar` / bare ident) live on `Value`
+    # so they can carry their kind polymorphically rather than as a
+    # string-prefix check.
+    #
+    # Anchors: mruby-regexp-compat supports `^`/`$` but not `\A`/`\z`.
+    # Since directive values are always single-line strings, `^/$` are
+    # equivalent here.
+    #
+    # Module methods are defined via `class << self` instead of
+    # `module_function` because mruby's `module_function` doesn't
+    # behave like MRI's (see runtime/mruby-lilac/mrblib/html.rb:60).
+    module Grammar
+      # `?` predicate suffix allowed (used by `@active?` ivars and
+      # bare-ident predicate field reads). Bang `!` is rejected — the
+      # regex stops before any trailing `!`.
+      METHOD_IDENT = /^[a-zA-Z_][a-zA-Z0-9_]*$/
+
+      # X part of `data-attr-X` / `data-css-X`: kebab-lowercase,
+      # letter-first, no `--` prefix (clashes with CSS variable prefix
+      # the framework auto-prepends).
+      KEBAB_NAME = /^[a-z][a-z0-9-]*$/
+
+      # Inline event handlers (`on*`), `srcdoc` (iframe HTML injection
+      # vector), and `style` (use `data-css-X` or `RefElement#set_style`
+      # instead) are banned from `data-attr-X`.
+      BANNED_ATTR = /^on[a-z]+$|^srcdoc$|^style$/
+
+      # `data-*` attribute names that map to a directive (one of the
+      # `Directive::Kind` values aside from `:component`). This is the
+      # SSOT for both:
+      #   * build-time: TemplateAST uses it to identify directive-bearing
+      #     elements that need a synthetic `lilN` slot.
+      #   * runtime: `Refs` / `TemplateRefs` use it to walk the mounted
+      #     subtree in DFS and resolve `refs.lilN` positionally.
+      # Anything matching here counts toward a scope's directive-bearing
+      # index; markers like `data-ref` / `data-component` / `data-template`
+      # / `data-arg-*` are excluded.
+      DIRECTIVE_ATTR = /^data-(?:text|unsafe-html|bind|show|hide|each|key|class|form|field|button|on-.+|attr-.+|css-.+)$/
+
+      class << self
+        # `increment` / `add_todo`. Event-handler method names — no `?`
+        # suffix so a typoed `save?` is caught at mount time.
+        def method_ident?(s)
+          !!METHOD_IDENT.match?(s.to_s)
+        end
+
+        # `progress` / `theme-color`. Rejects uppercase, digit-start,
+        # leading `-` (which would collide with the auto-prepended `--`).
+        def kebab_name?(s)
+          str = s.to_s
+          !!KEBAB_NAME.match?(str) && !str.start_with?("-")
+        end
+
+        def banned_attr?(s)
+          !!BANNED_ATTR.match?(s.to_s)
+        end
+
+        # True when `s` is a `data-*` attribute name that triggers
+        # codegen (i.e. occupies a `lilN` slot in its scope). Used by
+        # both build-time TemplateAST and runtime Refs to keep their
+        # DFS counters in lockstep.
+        def directive_attribute?(s)
+          !!DIRECTIVE_ATTR.match?(s.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/lilac/directives/lints.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Lilac
+  module Directives
+    # Build-time validation of directive composition rules. Called after
+    # directive collection so violations surface as a build error rather
+    # than a runtime failure on the user's page.
+    #
+    # Duplicate pair (build-time / runtime). See decisions §17. The
+    # build-time half raises on every violation; the runtime half
+    # (runtime/mruby-lilac-directives/mrblib/lilac_directives_lints.rb)
+    # applies warn+skip for ergonomics violations.
+    #
+    # Currently checks pair collisions, tag-level applicability, and
+    # `<input>` type-attribute constraints. Not yet enforced:
+    #   - data-arg-X validations — data-arg has no emitter yet
+    module Lints
+      # `COLLISION_PAIRS` lives in `collision_rules.rb` (the duplicate-
+      # pair SSOT). This file consumes it via the constant lookup below.
+      class Error < Lilac::CLI::BuildError; end
+
+      def self.check!(directives, file:)
+        # Group by (scope_id, ref_id) so directives that share a `lilN`
+        # NAME but live in different ref scopes (top-level vs each
+        # iteration body) are not falsely flagged as colliding. With
+        # the per-scope positional counter (decisions §19), ref_ids are
+        # only unique WITHIN a scope.
+        directives.group_by { |d| [d.scope_id, d.ref_id] }.each_value do |dirs_on_element|
+          check_collisions(dirs_on_element, file)
+          check_gn_hidden_conflict(dirs_on_element, file)
+        end
+        check_form_scope!(directives, file)
+      end
+
+      # Scope rules for the form gem (form-spec §8 / §10.2):
+      # - `data-form` is only allowed on `<form>` elements
+      # - multiple bare `<form>` (no data-form attr) within the same
+      #   component would collide on the `:default` scope, so flag the
+      #   second occurrence as an error
+      def self.check_form_scope!(directives, file)
+        seen_default_form = false
+        directives.each do |d|
+          next unless d.kind == :form
+
+          if d.element_tag != "form"
+            raise Error.new(
+              "data-form is only allowed on <form> elements " \
+              "(found on <#{d.element_tag}>).",
+              at: d.source_location(file),
+              suggestion: "Move data-form to a <form> element, or drop it if scope isn't needed.",
+            )
+          end
+
+          # `value == ""` is the synthetic marker injected by TemplateAST
+          # for bare <form>. Track the first; flag any second occurrence.
+          if d.value.to_s.empty?
+            if seen_default_form
+              raise Error.new(
+                "second bare <form> in the same component would collide on the " \
+                ":default scope.",
+                at: d.source_location(file),
+                suggestion: %(Add `data-form="..."` to one of them to distinguish.),
+              )
+            end
+            seen_default_form = true
+          end
+        end
+      end
+
+      def self.check_collisions(dirs, file)
+        attr_names = dirs.map { |d| attribute_for(d) }
+        COLLISION_PAIRS.each do |pair, message|
+          next unless pair.all? { |a| attr_names.include?(a) }
+
+          # Report at the line of the second (later) directive in the
+          # pair so users see where the conflict was introduced.
+          offenders = dirs.select { |d| pair.include?(attribute_for(d)) }
+          raise Error.new(
+            "Directive collision: #{message}",
+            at: offenders.last.source_location(file),
+          )
+        end
+      end
+
+      # Derive the `data-*` attribute name from a TemplateAST directive.
+      # Mirrors the runtime helper of the same name: both built-in
+      # directive kinds and CLI-registered emitter kinds (form's
+      # `:form` / `:field` / `:button`) follow the `data-<kind>` rule
+      # with `_` → `-` and a trailing `_` stripped.
+      def self.attribute_for(directive)
+        "data-#{directive.kind.to_s.tr('_', '-').chomp('-')}"
+      end
+
+      # `lil-hidden` is reserved by data-show / data-hide. If the user
+      # puts `'lil-hidden': @x` in data-class on the same element, three
+      # signals can race over the class — fail at build time and tell
+      # the user to drop the data-class entry.
+      #
+      # Note: parses the data-class hash literal purely for this check.
+      # The substring guard above keeps the cost zero for the common
+      # case (no `lil-hidden` anywhere in the value).
+      def self.check_gn_hidden_conflict(dirs, file)
+        return unless dirs.any? { |d| %i[show hide].include?(d.kind) }
+
+        class_dir = dirs.find { |d| d.kind == :class_ }
+        return unless class_dir
+        return unless class_dir.value.to_s.include?("lil-hidden")
+
+        pairs =
+          begin
+            ClassParser.parse(class_dir.value)
+          rescue ClassParser::Error
+            # Malformed data-class — the runtime scanner surfaces the
+            # parse error at mount; skip the conflict check here.
+            return
+          end
+        return unless pairs.any? { |key, _| key == "lil-hidden" }
+
+        raise Error.new(
+          "data-class uses the reserved class `lil-hidden` on an element " \
+          "that also has data-show / data-hide.",
+          at: class_dir.source_location(file),
+          suggestion: "Drop the `lil-hidden` key from data-class — data-show/data-hide manage it.",
+        )
+      end
+    end
+  end
+end

data/lib/lilac/directives/value.rb

@@ -0,0 +1,85 @@
+module Lilac
+  module Directives
+    # The right-hand side of a directive that takes a reactive value.
+    # Two kinds exist, both single-identifier (no dot / no path / no
+    # expression):
+    #
+    #   - `@ivar`     — a host Signal/Computed. Resolves via
+    #                   `Evaluator#lookup_ivar` and feeds into
+    #                   `bind ref, prop: signal` directly.
+    #   - bare ident  — a field of the current iteration item.
+    #                   `Evaluator#read` reads `item[name]` (Hash key
+    #                   first, then String fallback, then public_send).
+    #                   Only meaningful inside a `data-each` body;
+    #                   value-binding dispatch silent-skips when
+    #                   `item.nil?` (= scanning the host root).
+    #
+    # Duplicate pair (build-time / runtime). See decisions §17.
+    #
+    # `Value.parse` returns `Ivar`, `BareIdent`, or `nil` for invalid
+    # input — callers raise their own error with directive context.
+    # Match precedence: `@ivar` first (unambiguous prefix), then bare
+    # ident (everything else that looks like a Ruby identifier).
+    class Value
+      # Anchors use `^`/`$` not `\A`/`\z` — see Grammar for the
+      # mruby-regexp-compat compatibility note.
+      IVAR       = /^@[a-zA-Z_]\w*\??$/
+      BARE_IDENT = /^[a-zA-Z_]\w*\??$/
+
+      def self.parse(raw)
+        s = raw.to_s.strip
+        if IVAR.match?(s)
+          Ivar.new(s)
+        elsif BARE_IDENT.match?(s)
+          BareIdent.new(s)
+        end
+      end
+
+      attr_reader :raw
+
+      def initialize(raw)
+        @raw = raw
+      end
+
+      def to_s
+        @raw
+      end
+
+      def inspect
+        @raw.inspect
+      end
+
+      def ivar?
+        false
+      end
+
+      def bare_ident?
+        false
+      end
+    end
+
+    class Value::Ivar < Value
+      # `@count` -> :@count
+      def ivar_sym
+        @raw.to_sym
+      end
+
+      def ivar?
+        true
+      end
+    end
+
+    # Bare identifier referring to a field of the current iteration item.
+    # Outside `data-each` scope (item.nil?), value-binding dispatch
+    # silent-skips.
+    class Value::BareIdent < Value
+      def field
+        @raw
+      end
+
+      def bare_ident?
+        true
+      end
+    end
+  end
+end

data/lib/lilac/directives.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Build-time loader for `Lilac::Directives::*` files. The files under
+# `directives/` are intentional duplicates of the runtime mrbgem at
+# `runtime/mruby-lilac-directives/mrblib/` — they share class names so
+# `diff(1)` between the pair surfaces only semantic differences. Per
+# decisions §17, this means the individual files must NOT carry
+# `require_relative` statements (the runtime mrbgem also has none —
+# mruby-config drives load order there). MRI load order is owned here.
+
+require_relative "cli/build/build_error" # lints.rb references Lilac::CLI::BuildError
+require_relative "directives/value"
+require_relative "directives/grammar"
+require_relative "directives/class_parser"
+require_relative "directives/collision_rules" # COLLISION_PAIRS SSOT, consumed by lints.rb
+require_relative "directives/lints"