antoinette 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 275b763ee10f623e9fd499510bcd6da5dde6a8c99d38a0cd1dfd91f97de569ef
-  data.tar.gz: 632150c5438f87310f1c10112d412a7dbcafa0abb081404f534069ae08e49d02
+  metadata.gz: 795388e48b4799e7b321bc12ce0050797fee44d3bc6008f289c7367efe839dbd
+  data.tar.gz: 788964274ce4ed2c0061017aee248dd58e93864d86ce56eefe65b9d13f2a115a
 SHA512:
-  metadata.gz: c47b5b82eee6fee5e9c597f1fae507948acaa1e14696b5b6086f712593dd4fc24a1e99b20d16f98351744802deca6794a5d85ff7b10b2ab2c82d5f83ac5871ad
-  data.tar.gz: ec7681daf22bf110d3a39b005969d1959c88f63a4234ebb5e15b7768bb16ab3aaea4fb77d5cd7538fc01ba8e28329e9f6c9e1caf2b6e3d17b41434e95a460fe3
+  metadata.gz: 329ab030c6192c1af402741a0050c67059a353e8a16c3f445a99343b600666d6c1c9062d7a78ccddbf0fbc8f751c63c835d4953d9b855dd3da84b7b6458217b2
+  data.tar.gz: 778cd2d85170e35ef3ff5a6ffe987eef2d6c728a2072466336e13307847b1ba9eec6d0b2a89fa19dc44227529d065482a9801deeb7b6b4235abb3905c7b00d8a

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0] - 2024
+
+- Initial extraction from Gridular Mod
+- Core functionality:
+  - Elm app usage analysis
+  - Bundle generation with haiku-styled names
+  - Script tag injection (idempotent)
+  - Partial template resolution
+- CLI commands: config, build, clear, update
+- Rails engine with admin dashboard
+- Install generator

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2026 Giles Bowkett
+Copyright (c) 2024 Giles Bowkett
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,43 +1,144 @@
 # Antoinette
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/antoinette`. To experiment with that code, run `bin/console` for an interactive prompt.
+![Actors from the Sofia Coppola "Marie Antoinette" film](images/antoinette.png)
 
-TODO: Delete this and the text above, and describe your gem
+Imagine you have a Rails app with numerous Elm features. You haven't gone the
+SPA route; some Elm apps control the entire page, but many just provide bits
+and pieces of useful functionality. This is [the officially recommended way to
+bring Elm into a project](https://elm-lang.org/news/how-to-use-elm-at-work);
+Evan Czaplicki called it "_the_ success path."
+
+However, if you take that far enough, you reach a threshold where you have a
+bunch of little Elm features throughout your site. If you don't want to switch
+to an SPA, but you don't also want to send code down the wire that your app
+won't use, you're at a crossroads.
+
+This is the problem Antoinette solves.
+
+Antoinette is a lightweight JS bundler which weaves Elm apps into JavaScript
+bundles, and weaves JavaScript bundles into Rails templates.
+
+The name comes from mansion weave, a style of flooring based on woven elm wood,
+which was popular in French mansions from the 16th century onwards.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'antoinette'
+gem "antoinette"
 ```
 
-And then execute:
+Run the installer:
 
-    $ bundle
+```bash
+bin/rails generate antoinette:install
+```
 
-Or install it yourself as:
+This creates:
+- `config/antoinette.json` - Bundle configuration
+- `app/client/` - Directory for Elm source files
+- `app/client/BundleGraph.elm` and `app/client/Sankey.elm` - Admin visualization
+- `bin/antoinette` - CLI binstub
+- `app/assets/javascripts/antoinette/` - Bundle output directory
 
-    $ gem install antoinette
+It also adds a route for `/antoinette` admin page, and adds
+`app/assets/javascripts/antoinette` to your `.gitignore`.
 
 ## Usage
 
-TODO: Write usage instructions here
+### Configuration
 
-## Development
+Generate bundle configuration by analyzing which Elm apps are used in your Rails views:
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```bash
+bin/antoinette config
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To include custom view directories (outside `app/views/`):
 
-## Contributing
+```bash
+bin/antoinette config --custom_views app/content/layouts/
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/antoinette. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+### Building
 
-## License
+Compile all Elm bundles and inject script tags into templates:
+
+```bash
+bin/antoinette build
+```
+
+### Updating Specific Apps
+
+Rebuild only the bundles for specific Elm apps:
+
+```bash
+bin/antoinette update app/client/SearchForm.elm app/client/CaseBuilder.elm
+```
+
+### Clearing
+
+Remove all generated bundles and script tags:
+
+```bash
+bin/antoinette clear
+```
+
+### Admin Dashboard
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Visit `/antoinette` to see an interactive Sankey diagram showing how Elm apps
+flow into bundles and then into Rails templates.
 
-## Code of Conduct
+## How It Works
+
+1. **Analysis**: Scans Rails views for `Elm.AppName.init` patterns
+2. **Grouping**: Groups templates that use the same combination of Elm apps
+3. **Bundling**: Compiles each group into a single JavaScript bundle (with a haiku-styled name like `holy-waterfall-8432`)
+4. **Injection**: Adds `javascript_include_tag` to templates with SHA1 digest comments for idempotent updates
+
+### Script Tag Format
+
+Antoinette injects script tags like:
+
+```erb
+<%= javascript_include_tag "antoinette/holy-waterfall-8432" %> <!-- antoinette a1b2c3d4... -->
+```
+
+Embedding a hash in the comment ensures that tags only get updated when bundle content changes.
+
+## Requirements
+
+- Rails 7.0+
+- Elm (customize via `elm_path` in `config/antoinette.json`)
+
+## Configuration
+
+The `config/antoinette.json` file structure:
+
+```json
+{
+  "elm_path": "elm",
+  "bundles": [
+    {
+      "name": "holy-waterfall-8432",
+      "elm_apps": ["CaseBuilder", "SearchForm"],
+      "templates": ["app/views/cases/new.html.erb"]
+    }
+  ],
+  "custom_view_paths": ["app/content/layouts/"]
+}
+```
+
+## Rake Integration
+
+The `antoinette:build` task runs automatically before `assets:precompile`:
+
+```bash
+rake antoinette:build
+rake assets:precompile  # runs antoinette:build first
+```
+
+## License
 
-Everyone interacting in the Antoinette project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/antoinette/blob/master/CODE_OF_CONDUCT.md).
+MIT

data/lib/antoinette/cli/commands.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require "json"
+
+module Antoinette
+  module CLI
+    def self.output
+      Rails.env.test? ? StringIO.new : $stdout
+    end
+
+    module Commands
+      extend Dry::CLI::Registry
+
+      class Config < Dry::CLI::Command
+        desc "Generate JSON configuration for Elm bundles"
+
+        option :stdout, type: :boolean, default: false, desc: "Output to stdout instead of file"
+        option :custom_views, type: :array, default: [], desc: "Additional view directories to scan"
+
+        def call(stdout:, custom_views: [], **)
+          out = Antoinette::CLI.output
+          config_path = Rails.root.join("config", "antoinette.json")
+
+          existing_config = if File.exist?(config_path)
+            JSON.parse(File.read(config_path))
+          else
+            {}
+          end
+          existing_custom = existing_config["custom_view_paths"] || []
+          existing_elm_path = existing_config["elm_path"] || "elm"
+          all_custom_views = (existing_custom + custom_views).uniq
+
+          analyzer = Antoinette::ElmAppUsageAnalyzer.new(
+            skip: "layouts/",
+            custom_view_paths: all_custom_views
+          )
+          weaver = Antoinette::Weaver.new(
+            elm_analyzer: analyzer,
+            custom_view_paths: all_custom_views
+          )
+
+          output = JSON.parse(weaver.generate_json)
+          output["elm_path"] = existing_elm_path
+          json_output = JSON.pretty_generate(output)
+
+          if stdout
+            out.puts json_output
+          else
+            File.write(config_path, json_output)
+            out.puts "Generated #{config_path}"
+          end
+        end
+      end
+
+      class Build < Dry::CLI::Command
+        desc "Build JavaScript bundles from config"
+
+        def call(**)
+          out = Antoinette::CLI.output
+          config_path = Rails.root.join("config", "antoinette.json")
+          config = JSON.parse(File.read(config_path))
+
+          elm_path = config["elm_path"] || "elm"
+          compiler = Antoinette::CompileElm.new(elm_path: elm_path)
+          concatenator = Antoinette::ConcatBundle.new
+          injector = Antoinette::InjectScriptTag.new
+
+          config["bundles"].each do |bundle|
+            out.puts "Building bundle: #{bundle["name"]}"
+
+            elm_js = compiler.compile(bundle["elm_apps"])
+            concatenator.concatenate(
+              bundle_name: bundle["name"],
+              elm_js: elm_js
+            )
+
+            bundle["templates"].each do |template_path|
+              injector.inject(template_path: template_path, bundle_name: bundle["name"])
+            end
+
+            out.puts "  Compiled Elm apps: #{bundle["elm_apps"].join(", ")}"
+            out.puts "  Injected script tags into #{bundle["templates"].length} template(s)"
+          end
+
+          out.puts "Build complete!"
+        end
+      end
+
+      class Clear < Dry::CLI::Command
+        desc "Clear generated bundles and script tags"
+
+        def call(**)
+          out = Antoinette::CLI.output
+          config_path = Rails.root.join("config", "antoinette.json")
+          config = JSON.parse(File.read(config_path))
+
+          clearer = Antoinette::ClearScriptTag.new
+
+          config["bundles"].each do |bundle|
+            out.puts "Clearing bundle: #{bundle["name"]}"
+
+            bundle_file = Rails.root.join(
+              "app", "assets", "javascripts", "antoinette", "#{bundle["name"]}.js"
+            )
+            if File.exist?(bundle_file)
+              File.delete(bundle_file)
+              out.puts "  Deleted bundle file: #{bundle["name"]}.js"
+            end
+
+            bundle["templates"].each do |template_path|
+              clearer.clear(template_path: template_path)
+            end
+
+            out.puts "  Cleared script tags from #{bundle["templates"].length} template(s)"
+          end
+
+          out.puts "Clear complete!"
+        end
+      end
+
+      class Update < Dry::CLI::Command
+        desc "Update bundle(s) and script tag(s) for specific Elm apps"
+
+        argument :elm_files, type: :array, required: true, desc: "Elm file paths"
+
+        def call(elm_files:, **)
+          out = Antoinette::CLI.output
+          elm_app_names = elm_files.map { |path| File.basename(path, ".elm") }
+
+          config_path = Rails.root.join("config", "antoinette.json")
+          config = JSON.parse(File.read(config_path))
+
+          filtered_bundles = config["bundles"].select do |bundle|
+            (bundle["elm_apps"] & elm_app_names).any?
+          end
+
+          if filtered_bundles.empty?
+            out.puts "No bundles found containing: #{elm_app_names.join(", ")}"
+            exit
+          end
+
+          elm_path = config["elm_path"] || "elm"
+          compiler = Antoinette::CompileElm.new(elm_path: elm_path)
+          concatenator = Antoinette::ConcatBundle.new
+          injector = Antoinette::InjectScriptTag.new
+
+          filtered_bundles.each do |bundle|
+            out.puts "Updating bundle: #{bundle["name"]}"
+
+            elm_js = compiler.compile(bundle["elm_apps"])
+            concatenator.concatenate(
+              bundle_name: bundle["name"],
+              elm_js: elm_js
+            )
+
+            bundle["templates"].each do |template_path|
+              injector.inject(template_path: template_path, bundle_name: bundle["name"])
+            end
+
+            out.puts "  Compiled Elm apps: #{bundle["elm_apps"].join(", ")}"
+            out.puts "  Injected script tags into #{bundle["templates"].length} template(s)"
+          end
+
+          out.puts "Update complete!"
+        end
+      end
+
+      register "config", Config
+      register "build", Build
+      register "clear", Clear
+      register "update", Update
+    end
+  end
+end

data/lib/antoinette/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Antoinette
+  class Engine < ::Rails::Engine
+    initializer "antoinette.assets" do |app|
+      app.config.assets.paths << root.join("app", "assets", "javascripts")
+    end
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+  end
+end

data/lib/antoinette/services/clear_script_tag.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Antoinette
+  class ClearScriptTag
+    def initialize(views_path: Rails.root.join("app", "views"))
+      @views_path = views_path
+    end
+
+    def clear(template_path:)
+      full_path = resolve_template_path(template_path)
+      content = File.read(full_path)
+
+      return unless content.match?(/<!-- antoinette [a-f0-9]+ -->/)
+
+      updated_content = content.gsub(/^.*<!-- antoinette [a-f0-9]+ -->.*\n?/, "")
+
+      File.write(full_path, updated_content)
+    end
+
+    private
+
+    def resolve_template_path(template_path)
+      if template_path.start_with?("app/")
+        Rails.root.join(template_path)
+      else
+        @views_path.join(template_path)
+      end
+    end
+  end
+end

data/lib/antoinette/services/compile_elm.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "uglifier"
+
+module Antoinette
+  class CompileElm
+    ELM_PURE_FUNCS = %w[F2 F3 F4 F5 F6 F7 F8 F9 A2 A3 A4 A5 A6 A7 A8 A9].freeze
+
+    def initialize(elm_path: "elm", environment: Rails.env.to_s)
+      @elm_path = elm_path
+      @environment = environment
+    end
+
+    def compile(elm_app_names)
+      elm_file_paths = elm_app_names.map { |name| "app/client/#{name}.elm" }
+      output_file = "tmp/elm_compiled.js"
+      optimize_flag = production? ? "--optimize" : ""
+
+      command = "#{@elm_path} make #{optimize_flag} --output=#{output_file} #{elm_file_paths.join(" ")}".squeeze(" ")
+
+      system(command)
+
+      unless Process.last_status.success?
+        raise "Elm compilation failed"
+      end
+
+      js = File.read(output_file)
+      production? ? minify(js) : js
+    ensure
+      File.delete(output_file) if output_file && File.exist?(output_file)
+    end
+
+    private
+
+    def production?
+      @environment == "production"
+    end
+
+    def minify(js)
+      Uglifier.compile(
+        js,
+        compress: {
+          pure_funcs: ELM_PURE_FUNCS,
+          pure_getters: true,
+          keep_fargs: false,
+          unsafe_comps: true,
+          unsafe: true
+        },
+        mangle: true
+      )
+    end
+  end
+end

data/lib/antoinette/services/concat_bundle.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Antoinette
+  class ConcatBundle
+    def initialize(assets_path: Rails.root.join("app", "assets", "javascripts", "antoinette"))
+      @assets_path = assets_path
+    end
+
+    def concatenate(bundle_name:, elm_js:)
+      output_path = @assets_path.join("#{bundle_name}.js")
+      File.write(output_path, elm_js)
+
+      output_path.to_s
+    end
+  end
+end

data/lib/antoinette/services/elm_app_usage_analyzer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Antoinette
+  class ElmAppUsageAnalyzer
+    ViewFile = Struct.new(:path, :elm_apps)
+    ElmApp = Struct.new(:name)
+    class Matrix < Hash; end
+
+    def initialize(skip: nil, custom_view_paths: [])
+      @skip = skip
+      @custom_view_paths = custom_view_paths
+    end
+
+    def views
+      @views ||= view_path_globs.each_with_object([]) do |glob_pattern, result|
+        Dir.glob(glob_pattern).each do |file_path|
+          content = File.read(file_path)
+          apps = elm_apps(content)
+          next if apps.empty?
+
+          relative_path = file_path.sub("#{Rails.root}/", "")
+          next if @skip && relative_path.include?("app/views/#{@skip}")
+
+          app_names = apps.map(&:name)
+          result << ViewFile.new(relative_path, app_names)
+        end
+      end
+    end
+
+    def view_path_globs
+      globs = [Rails.root.join("app", "views", "**", "*.html.erb")]
+      @custom_view_paths.each do |custom_path|
+        full_path = Rails.root.join(custom_path)
+        globs << if File.file?(full_path)
+          full_path
+        else
+          full_path.join("**", "*.html.erb")
+        end
+      end
+      globs
+    end
+
+    def elm_apps(content)
+      app_names = content.scan(/Elm\.(\w+)\.init/).flatten.uniq
+      app_names.map { |name| ElmApp.new(name) }
+    end
+
+    def matrix
+      @matrix ||= Matrix.new.tap do |m|
+        all_app_names.each do |app_name|
+          m[app_name] = views.select { |v| v.elm_apps.include?(app_name) }
+            .map(&:path)
+        end
+      end
+    end
+
+    def all_app_names
+      @all_app_names ||= views.flat_map(&:elm_apps).uniq.sort
+    end
+
+    def layout_apps
+      @layout_apps ||= Dir.glob(Rails.root.join("app", "views", "layouts", "*.html.erb"))
+        .flat_map do |file_path|
+          content = File.read(file_path)
+          elm_apps(content).map(&:name)
+        end.uniq
+    end
+
+    def per_file
+      @per_file ||= views.sort_by { |vf| -vf.elm_apps.count }
+        .each_with_object({}) do |view_file, result|
+          result[view_file.path] = view_file.elm_apps
+      end
+    end
+
+    def mappings
+      @mappings ||= views.group_by { |vf| vf.elm_apps.sort }
+        .sort_by { |apps, _| -apps.count }
+        .each_with_object({}) do |(apps, view_files), result|
+          result[apps] = view_files.map(&:path).sort
+        end
+    end
+
+    def generate_csv
+      CSV.generate do |csv|
+        csv << ["View File"] + all_app_names
+
+        views.each do |view_file|
+          row = [view_file.path]
+          all_app_names.each do |app_name|
+            row << (view_file.elm_apps.include?(app_name) ? "X" : "")
+          end
+          csv << row
+        end
+      end
+    end
+  end
+end

data/lib/antoinette/services/inject_script_tag.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Antoinette
+  class InjectScriptTag
+    def initialize(
+      assets_path: Rails.root.join("app", "assets", "javascripts", "antoinette")
+    )
+      @assets_path = assets_path
+    end
+
+    def inject(template_path:, bundle_name:)
+      full_path = Rails.root.join(template_path)
+      content = File.read(full_path)
+
+      bundle_path = @assets_path.join("#{bundle_name}.js")
+      digest = Digest::SHA1.hexdigest(File.read(bundle_path))
+      script_tag = "<%= javascript_include_tag \"antoinette/#{bundle_name}\" %> <!-- antoinette #{digest} -->"
+
+      updated_content = if content.match?(/<!-- antoinette [a-f0-9]+ -->/)
+        content.gsub(/^.*<!-- antoinette [a-f0-9]+ -->.*$/, script_tag)
+      else
+        content + "\n" + script_tag
+      end
+
+      File.write(full_path, updated_content)
+    end
+  end
+end

data/lib/antoinette/services/partial_resolver.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Antoinette
+  class PartialResolver
+    RenderCall = Struct.new(:template_path, :partial_path)
+
+    def renders
+      @renders ||= begin
+        view_files = Dir.glob(Rails.root.join("app", "views", "**", "*.html.erb"))
+
+        view_files.each_with_object([]) do |file_path, result|
+          content = File.read(file_path)
+          relative_template_path = file_path.sub("#{Rails.root}/app/views/", "")
+          partial_paths = extract_partial_paths(content, relative_template_path)
+          next if partial_paths.empty?
+
+          partial_paths.each do |partial_path|
+            result << RenderCall.new(relative_template_path, partial_path)
+          end
+        end
+      end
+    end
+
+    def extract_partial_paths(content, template_path = nil)
+      paths = []
+
+      content.scan(/render\s+partial:\s*["']([^"']+)["']/) do |match|
+        paths << normalize_partial_path(match[0], template_path)
+      end
+
+      content.scan(/render\s+["']([^"']+)["']/) do |match|
+        paths << normalize_partial_path(match[0], template_path)
+      end
+
+      paths.uniq
+    end
+
+    def normalize_partial_path(path, template_path = nil)
+      if path.include?("/")
+        dir, name = path.split("/")[0..-2].join("/"), path.split("/").last
+        name = name.start_with?("_") ? name : "_#{name}"
+        "#{dir}/#{name}.html.erb"
+      else
+        name = path.start_with?("_") ? path : "_#{path}"
+
+        if template_path
+          template_dir = File.dirname(template_path)
+          "#{template_dir}/#{name}.html.erb"
+        else
+          "#{name}.html.erb"
+        end
+      end
+    end
+
+    def partials
+      @partials ||= begin
+        grouped = renders.group_by(&:partial_path)
+        grouped.transform_values do |render_calls|
+          render_calls.map(&:template_path).sort
+        end
+      end
+    end
+
+    def resolve(partial_path)
+      partials[partial_path] || []
+    end
+  end
+end