Weld

Weld is a graph-native publication system for Elixir monorepos.

It keeps the source repo as a normal multi-project workspace, builds a workspace graph, resolves one artifact boundary from a repo-local manifest, projects a standalone Mix package, verifies that generated package with normal Mix tooling, and prepares an archiveable release bundle for publication.

What It Does

• discovers workspace projects from manifest globs, blitz_workspace, or filesystem fallback
• classifies projects as runtime, tooling, proof, or ignored
• separates publication role from project classification
• classifies internal edges by execution meaning
• exposes inspect, graph, query, affected, project, verify, and release tasks
• emits a deterministic projection.lock.json
• generates a standalone Mix package under dist/hex/<package>/ (package-projection mode) or dist/monolith/<package>/ (monolith mode)
• canonicalizes external workspace path or git deps into manifest-owned Hex deps
• synthesizes a merged application module when selected projects publish OTP children
• merges sources, tests, config, migrations, and priv from all selected projects in monolith mode
• supports explicit manifest-owned source-only monolith test support projects
• prepares a deterministic release bundle under dist/release_bundles/<package>/...
• archives released bundles without turning generated output into a long-lived source tree

Installation

Add weld to the root project that owns the repo's packaging and release flow.

def deps do
  [
    {:weld, "~> 0.6.0", runtime: false}
  ]
end

Release Lifecycle

The intended lifecycle is:

1. run the normal source-repo checks
2. run mix weld.release.prepare ...
3. optionally run mix weld.release.track ... to update a durable projection
4. run mix hex.publish from the prepared bundle when you are doing a release
5. run mix weld.release.archive ...

weld owns create, welded-package verification, and archive preparation. Hex publish remains external.

mix weld.release.track is for tracked projected source, including unreleased or pre-release snapshots. It updates projection/<package_name> by default and creates that branch as an orphan on first use so the projection history stays isolated from the source repo history.

Example Manifest

Package-projection mode (default):

[
  workspace: [
    root: "../..",
    project_globs: ["core/*", "runtime/*"]
  ],
  dependencies: [
    external_lib: [
      requirement: "~> 1.2",
      opts: []
    ]
  ],
  artifacts: [
    my_bundle: [
      roots: ["runtime/local"],
      package: [
        name: "my_bundle",
        otp_app: :my_bundle,
        version: "0.1.0",
        description: "My welded package"
      ],
      output: [
        docs: ["README.md", "guides/architecture.md"]
      ],
      verify: [
        artifact_tests: ["packaging/weld/my_bundle/test"],
        hex_build: true,
        hex_publish: true,
        smoke: [
          enabled: true,
          entry_file: "packaging/weld/my_bundle/smoke.ex"
        ]
      ]
    ]
  ]
]

Monolith mode:

[
  workspace: [
    root: "../..",
    project_globs: ["core/*", "runtime/*"]
  ],
  artifacts: [
    my_monolith: [
      mode: :monolith,
      roots: ["runtime/api"],
      monolith_opts: [
        shared_test_configs: ["core/contracts"],
        test_support_projects: ["tooling/test_support"]
      ],
      package: [
        name: "my_monolith",
        otp_app: :my_monolith,
        version: "0.1.0",
        description: "My welded monolith"
      ],
      output: [
        docs: ["README.md"]
      ]
    ]
  ]
]

Core Commands

mix weld.inspect packaging/weld/my_bundle.exs
mix weld.graph packaging/weld/my_bundle.exs --format dot
mix weld.query deps packaging/weld/my_bundle.exs runtime/local
mix weld.project packaging/weld/my_bundle.exs
mix weld.verify packaging/weld/my_bundle.exs
mix weld.release.prepare packaging/weld/my_bundle.exs
mix weld.release.track packaging/weld/my_bundle.exs
mix weld.release.archive packaging/weld/my_bundle.exs
mix weld.affected packaging/weld/my_bundle.exs --task verify.all --base main --head HEAD

Generated Output

Package-projection mode (default) projects under dist/hex/<package>/ using a component-preserving layout:

dist/
  hex/
    my_bundle/
      mix.exs
      projection.lock.json
      lib/
        my_bundle/
          application.ex
      components/
        core/contracts/
        runtime/local/
      test/

Monolith mode merges all selected packages into a single flat project under dist/monolith/<package>/:

dist/
  monolith/
    my_monolith/
      mix.exs
      projection.lock.json
      lib/
        my_monolith/
          application.ex
        fixture/
          store.ex
          api.ex
      test/
        core_store/
        runtime_api/
        support/
      config/
        config.exs
        sources/
        runtime_sources/
      priv/
        repo/migrations/

When selected projects expose OTP applications, weld synthesizes a merged lib/<otp_app>/application.ex that starts those children inside the welded package. In monolith mode this module also bootstraps per-package config at startup via Config.Reader.

When selected-package tests depend on non-selected workspace projects, declare those source-only support projects explicitly in monolith_opts[:test_support_projects]. weld copies that support code under test/support/weld_projects/ and fails closed if the discovered support set drifts from the manifest contract.

The welded artifact is a normal Mix project. weld.verify runs:

Package-projection mode:

• mix deps.compile
• mix compile --warnings-as-errors --no-compile-deps
• mix test
• mix docs --warnings-as-errors
• mix hex.build
• mix hex.publish --dry-run --yes
• optional smoke-app compilation

You can opt out of the Hex-only steps per artifact with:

• verify: [hex_build: false]
• verify: [hex_publish: false]

This is the correct setting for internal artifacts that intentionally depend on non-Hex git dependencies. When disabled, Weld records the step as :skipped instead of forcing a failing mix hex.build.

Monolith mode:

• per-package test baseline (asserts selected packages pass their own tests)
• mix deps.get
• mix compile --warnings-as-errors
• mix test (asserts test count ≥ baseline sum)
• mix docs --warnings-as-errors
• mix hex.build

Monolith artifacts can also disable hex.build with verify: [hex_build: false] when they are intentionally not Hex-packagable.

Prepared release bundles include release.json metadata with a repo-relative manifest path and the Weld version used to create the bundle, so bundle metadata remains portable across checkout locations.

Guides

• Getting Started
• Workflow
• CLI Reference
• Manifest Reference
• Architecture
• Testing Strategy
• Release Process
• Consumer Repo Integration

License

This project is licensed under the MIT License. See LICENSE for details.