# Svelixir Scaffolder for Elixir/Phoenix projects with a Svelte 5 UI layer. Svelixir generates a project and then keeps it upgradable. `svelixir.exs` records what the project asked for; `fireside.exs` records what was actually written, and with which content hashes, so a later regeneration can tell an untouched file from one the developer has edited. Every reader here works against an explicit project root rather than the current working directory — `Svelixir.Target` exists for exactly that reason, and `Svelixir.BoundaryGuard` enforces it mechanically over `lib/`. ## The two perimeters The work is split across two repositories, and the split is structural rather than organisational. | perimeter | repository | what it is | | --------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 — the package | `wimwian-org/svelixir` (this one) | the library a generated project depends on: `Svelixir.Target`, `Svelixir.Config`, `Svelixir.Manifest`, `Svelixir.Exs`, `Svelixir.Hash`, `Svelixir.Baseline` | | 2 — the archive | `wimwian-org/svelixir_new` | the `mix svelixir.new` Mix archive, checked out at `priv/svelixir_new` | Perimeter 2 is its own project because a Mix archive has to ship with **zero hex requirements**: it is unpacked straight onto the developer's code path, where a dependency of its own would be unresolvable. A separate Mix project is what lets `mix archive.build` produce that, and it is also what keeps the two code paths disjoint — neither perimeter's ebin is ever on the other's, so a change to one cannot quietly compile against the other. The two meet exactly once: the archive writes a `svelixir.exs` and this package reads it back with `Svelixir.Config.read!/1`. There is no shared encoder and no digest pinned in two files. `priv/svelixir_new` is gitignored here. Clone it alongside before running the cross-perimeter tests: ```sh git clone git@github.com:wimwian-org/svelixir_new.git priv/svelixir_new ``` Everything degrades visibly without it rather than silently: `test/test_helper.exs` excludes the `:archive` tag when `priv/svelixir_new/mix.exs` is absent, `bin/check` skips that perimeter's gates, and CI annotates the run with a `::warning` naming what did not run. ## Running the checks `bin/check` is the commit gate — format, `credo --strict`, coveralls at `minimum_coverage: 100`, doctor and dialyzer, in both perimeters: ```sh bin/check ``` It does **not** run the tagged tests, and a green `bin/check` alone is therefore not a green suite. Three tags are excluded by default, and they are disjoint **by dependency**: no test carries more than one, because ExUnit's include filter beats its exclude filter per tag, so a doubly-tagged test would run in an environment that cannot support it. | tag | what it needs | how it runs | | -------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `:toolchain` | the external toolchain only (`mix new`, `phx_new`) — safe anywhere | `mix test --include toolchain` | | `:determinism` | a subprocess probe re-run under a reversed atom-interning order | `mix test --include determinism` | | `:archive` | `priv/svelixir_new`, to build and install the archive | runs in a plain `mix test` when the perimeter is present; excluded when it is not | The full local sequence: ```sh bin/check mix test --include toolchain --include determinism (cd priv/svelixir_new && mix test --include toolchain) ``` `Svelixir.TagCoverageTest` asserts mechanically that every tag the suite excludes is **named** by an `--include` on an **unguarded** CI step, so a newly excluded tag cannot go unnamed by every workflow step. It reads `ci.yml` as text, so what it proves is that a step exists which would run the tag — never that the step ran. `:archive` is exempted from the unguarded half by name: its CI step is guarded on the perimeter 2 checkout, which reads a private repository through the `SVELIXIR_NEW_TOKEN` secret and 404s whenever that secret is absent, expired or withheld — so `:archive` coverage in CI is contingent on a credential, and the `::warning` in the run summary is what makes its absence visible. That failure mode is the one this project calls F4: tests that silently did not run. ## The hex dependency source `mix svelixir.new` splices `{:svelixir, "~> 0.1", only: [:dev], runtime: false}` into the generated project by default, and accepts `--svelixir-path` to splice a **path** dependency instead. The default resolves: the package is published, and `~> 0.1` admits every 0.x release. Both end-to-end tests still pass `--svelixir-path`, so the `{:hex, requirement}` branch of the generator's `dep_line/1` stays uncovered end to end. That is deliberate rather than an oversight: the honest test needs the network, and as an untagged test it would turn `bin/check` red for any offline developer, for reasons unrelated to their change. What publishing changed is the failure mode — the branch is no longer guaranteed to fail, so it is untested rather than known-broken. ## Installation ```elixir def deps do [ {:svelixir, "~> 0.1", only: [:dev], runtime: false} ] end ``` `only: [:dev]` and `runtime: false` are deliberate rather than incidental: Svelixir is a build-time scaffolder, and nothing it defines is needed once the generated application is running. To work against an unreleased checkout, depend on it by path instead — this is what `--svelixir-path` generates: ```elixir {:svelixir, path: "../svelixir", only: [:dev], runtime: false} ``` Documentation is generated with [ExDoc](https://github.com/elixir-lang/ex_doc) and published at . The vendored libraries in `vendor/` compile into this application but are filtered out of the docs by `filter_modules` — their API is not ours to document. ## Acknowledgements ### Prior art Svelixir's central idea — that a generated project should stay **upgradable**, which means telling a file the generator wrote from a file a human has since edited — is not original to it. - **[Fireside](https://github.com/ibarakaiev/fireside)** by Ihor Barakaiev (MIT) is where `fireside.exs` gets both its name and its shape. Fireside imports code components into an _existing_ project together with their dependencies and can upgrade them later, which is the same problem this project solves for a whole scaffold. The `svelixir.exs` / `fireside.exs` split — intent in one file, what was actually written in the other — is Fireside's insight applied to a generator. The name is kept deliberately rather than rebranded: it should be obvious where the idea came from. - **[Igniter](https://github.com/ash-project/igniter)** by Zach Daniel and the Ash team (MIT) is the code-generation and project-patching framework Fireside is built on, and the reference for what patching an existing project well looks like — composable tasks over a parsed project rather than string surgery. Svelixir does not depend on Igniter; the structural-placement modules (`Svelixir.MixExs`, `Svelixir.ConfigExs`, `Svelixir.ApplicationEx`) solve a deliberately narrower problem against a vendored Sourceror. Igniter is the right tool for the general case. - **[Sourceror](https://github.com/doorgan/sourceror)** by doorgan (Apache-2.0) is what makes structural placement possible at all, and it is vendored here (see below). `get_range/1` plus `patch_string/2` edits a range of an existing file and leaves every other byte untouched — as opposed to reprinting the AST, which reformats code the user never asked to change. Every `mix.exs`, `config/*.exs` and `application.ex` edit this project makes goes through it. Fireside depends on Igniter, and Igniter depends on Sourceror. Svelixir sits at the end of that chain and owes all three. ### Vendored libraries Four libraries are compiled directly into this application from `vendor/` rather than resolved as Hex dependencies, so that the generated archive perimeter can carry zero Hex requirements. Each directory holds the upstream `lib/` tree and the upstream licence file, unmodified except for two recorded one-line patches. Full provenance, checksums and patch notes are in [`vendor/README.md`](vendor/README.md). | Library | Version | Licence | Author | Used for | | ----------------------------------------------------------- | ------- | ---------- | ------------------------------------- | ----------------------------------------------- | | [`sourceror`](https://github.com/doorgan/sourceror) | 1.12.2 | Apache-2.0 | doorgan | structural placement — parse and patch by range | | [`vex`](https://github.com/CargoSense/vex) | 0.9.2 | MIT | Bruce Williams | validating `svelixir.exs` sections | | [`typedstruct`](https://github.com/saleyn/typedstruct) | 0.5.4 | MIT | Jean-Philippe Cugnet and contributors | the config and manifest structs | | [`simple_enum`](https://github.com/ImNotAVirus/simple_enum) | 1.0.0 | MIT | DarkyZ aka NotAVirus | enumerated section values | These are other people's work carrying other people's licences. Nothing in `vendor/` is formatted, linted or documented by this project's gates, and the vendored modules are filtered out of the published docs — their API is theirs, not ours. ### Generated projects Generated projects get their UI components from [sv5ui](https://sv5ui.vercel.app), a skin over the [bits-ui](https://bits-ui.com) headless components, with the [sveltic](https://sv5ui.vercel.app/templates) theme template. The project skeleton itself comes from [Phoenix](https://www.phoenixframework.org)'s own `phx.new`, which Svelixir composes on top of rather than replaces.