# Muga

Muga is a compiler-first programming language project named after the Japanese idea of muga, often translated as selflessness. Its current design emphasizes readable local reasoning through immutable-by-default bindings, local type inference, value semantics, records plus functions, and predictable package boundaries.

This repository tracks the language design, examples, and the current Rust compiler/runtime implementation as Muga moves toward v1.

## Installation

Install the published command with Cargo:

```bash
cargo install muga
```

Run a source file with:

```bash
muga path/to/file.muga
muga check path/to/file.muga
muga emit-artifacts --artifact-root path/to/artifacts path/to/package/main.muga
muga emit-interface --artifact-root path/to/artifacts --package util::numbers path/to/package/main.muga
muga emit-check-cache --artifact-root path/to/artifacts path/to/package/main.muga
muga check --artifact-root path/to/artifacts path/to/package/main.muga
muga run --artifact-root path/to/artifacts path/to/package/main.muga
```

## Quickstart

Prerequisites: Rust 1.95 or later.

Clone the repository and run one of the bundled samples:

```bash
git clone https://github.com/lef237/muga.git
cd muga
cargo run -- samples/println_sum.muga
```

Expected output (the first line is `println`, the second line is the return value of `main`):

```text
10
10
```

Try another sample that chains function calls:

```bash
cargo run -- samples/number_chain.muga
# => 4
```

Only validate the front end (parse, name resolution, typing) without executing:

```bash
cargo run -- check samples/println_sum.muga
# => ok
```

Package mode is also available through a file entrypoint:

```bash
cargo run -- check samples/packages/app/main/main.muga
cargo run -- samples/packages/app/main/main.muga
```

For explicit artifact-backed package workflows, `emit-artifacts` writes reachable `.mgi` interface files, reachable `.mgb` package implementation artifacts containing MIR-lowered bytecode bodies, and the entry package `.mgc` check cache file. `emit-check-cache` writes `.mgc` only after the package checks successfully against the available `.mgi` artifacts. Use `emit-interface` with `--package` only when you want to restrict interface emission to one package.

```bash
artifact_root=$(mktemp -d)
cargo run -- emit-artifacts --artifact-root "$artifact_root" samples/packages/app/artifact_facade/main.muga
cargo run -- check --artifact-root "$artifact_root" samples/packages/app/artifact_facade/main.muga
cargo run -- run --artifact-root "$artifact_root" samples/packages/app/artifact_facade/main.muga
```

Artifact roles are deliberately separate:

- `.mgi` is the public interface artifact used to check downstream packages without reading dependency implementation bodies.
- `.mgc` is the entry package check-cache proof keyed by entry source plus direct and transitive dependency interface hashes.
- `.mgb` is the dependency execution artifact. It stores MIR-lowered bytecode bodies, is structurally validated on load, and is rejected when missing, stale, hash-mismatched, for the wrong package, or inconsistent with loaded dependency interface hashes.

Run your own file by pointing `cargo run` at any `.muga` source. `run` is the default subcommand, so it can be omitted:

```bash
cargo run -- run path/to/file.muga
cargo run -- path/to/file.muga
```

A program may either define a zero-argument `main()` or run top-level statements directly. When `main()` exists, its return value is printed after execution:

```muga
fn main(): Int {
  println(1 + 2)
}
```

For more entry points, browse the [Samples](#samples) section below.

## Language Shape

- no `let`; bindings are immutable by default and `mut` opts into mutation
- `x = e` is resolved statically as either a new immutable binding or an update to an existing mutable binding
- shadowing and mutation across function boundaries are rejected
- type inference is local-first; annotations are required only when inference is ambiguous or intentionally bounded by the current implementation
- comments use `//`; statements are newline-separated
- data uses nominal `record` declarations; behavior uses functions
- `expr.name` is field access, `expr.name(...)` is chained-call syntax, and `expr.with(...)` is record update
- classes, inheritance, function-valued record fields, traits, protocols, typeclasses, overloaded dispatch, and ordinary source-level references are out of scope for v1
- source values use value semantics; the implementation may share immutable storage internally when that is not observable
- recoverable failures use explicit `Result[T, E]`; prefix `try expr` propagates `Result` errors, while postfix `?` remains out of scope for v1

## Documentation

- Language overview: [mini-language-spec-v1.md](./mini-language-spec-v1.md)
- Split specification:
  - [spec/001-core-language.md](./spec/001-core-language.md)
  - [spec/002-name-resolution.md](./spec/002-name-resolution.md)
  - [spec/003-typing.md](./spec/003-typing.md)
  - [spec/004-functions.md](./spec/004-functions.md)
  - [spec/005-records.md](./spec/005-records.md)
  - [spec/006-packages.md](./spec/006-packages.md) (draft)
  - [spec/007-concurrency-draft.md](./spec/007-concurrency-draft.md) (draft)
  - [spec/008-collections.md](./spec/008-collections.md) (draft)
  - [spec/009-generics.md](./spec/009-generics.md) (draft)
  - [spec/010-references-draft.md](./spec/010-references-draft.md) (decision note)
  - [spec/011-value-semantics.md](./spec/011-value-semantics.md) (draft)
  - [spec/012-protocols-deferred.md](./spec/012-protocols-deferred.md) (decision note)
  - [spec/013-enums-results.md](./spec/013-enums-results.md) (draft)
- Error catalog: [errors.md](./errors.md)
- Implementation roadmap and next priority: [ROADMAP.md](./ROADMAP.md)
- Practical language readiness backlog: [docs/practical-language-readiness.md](./docs/practical-language-readiness.md)
- Implementation ledger, resume checklist, and next-slice test plan: [docs/implementation-resume-plan.md](./docs/implementation-resume-plan.md)
- Ideal compiler architecture: [docs/ideal-compiler-architecture.md](./docs/ideal-compiler-architecture.md)
- Language design reference: [docs/language-design-reference.md](./docs/language-design-reference.md)
- Syntax marker case study: [docs/syntax-marker-case-study.md](./docs/syntax-marker-case-study.md)
- Compiler identity note: [docs/internal/identity-model.md](./docs/internal/identity-model.md)

## Examples

### Valid

- [examples/valid/001-basic-bindings.md](./examples/valid/001-basic-bindings.md)
- [examples/valid/002-read-from-outer-scope.md](./examples/valid/002-read-from-outer-scope.md)
- [examples/valid/003-local-mutable-loop.md](./examples/valid/003-local-mutable-loop.md)
- [examples/valid/004-inferred-parameter-type.md](./examples/valid/004-inferred-parameter-type.md)
- [examples/valid/005-recursive-function.md](./examples/valid/005-recursive-function.md)
- [examples/valid/006-mutual-recursion.md](./examples/valid/006-mutual-recursion.md)
- [examples/valid/007-record-with-update.md](./examples/valid/007-record-with-update.md)
- [examples/valid/008-local-higher-order-inference.md](./examples/valid/008-local-higher-order-inference.md)
- [examples/valid/009-explicit-arrow-callback.md](./examples/valid/009-explicit-arrow-callback.md)

### Invalid

- [examples/invalid/001-immutable-update.md](./examples/invalid/001-immutable-update.md)
- [examples/invalid/002-duplicate-mutable-binding.md](./examples/invalid/002-duplicate-mutable-binding.md)
- [examples/invalid/003-shadowing-in-block.md](./examples/invalid/003-shadowing-in-block.md)
- [examples/invalid/004-outer-scope-mutation.md](./examples/invalid/004-outer-scope-mutation.md)
- [examples/invalid/005-ambiguous-identity.md](./examples/invalid/005-ambiguous-identity.md)
- [examples/invalid/006-unannotated-recursion.md](./examples/invalid/006-unannotated-recursion.md)
- [examples/invalid/007-unannotated-mutual-recursion.md](./examples/invalid/007-unannotated-mutual-recursion.md)
- [examples/invalid/008-invalid-record-update.md](./examples/invalid/008-invalid-record-update.md)
- [examples/invalid/009-ambiguous-higher-order-parameter.md](./examples/invalid/009-ambiguous-higher-order-parameter.md)
- [examples/invalid/010-ambiguous-println-callback.md](./examples/invalid/010-ambiguous-println-callback.md)

## Rust Implementation

Implemented:

- lexer, parser, resolver, typechecker, typed HIR lowering, MIR lowering, bytecode compilation, and VM runtime
- `check` for front-end validation and `run` for VM execution
- `Unit` type with the `()` literal for effect-only success values
- compiler-provided `std::io` / `std::fs` package slice with `IOError`, `fs::read_text`, and `fs::write_text`
- `print` / `println` prelude builtins for `Int`, `Bool`, and `String`
- records, field access, `record.with(...)`, chained calls, package-qualified chained calls, arrow function types, local binding annotations, and local bidirectional inference for selected higher-order cases
- `List[T]`, `Option[T]`, `Result[T, E]`, and `Map[K, V]` type expressions
- list literals, direct list indexing, `len`, `is_empty`, `push`, `get`, and `set`
- string helpers `is_empty`, `contains`, `trim`, `char_count`, `starts_with`, `ends_with`, `replace`, `split`, `concat`, `slice_chars`, `parse_int`, and `parse_bool`
- explicit formatting helpers `to_string` for `Int`, `Bool`, and `String`
- `Option::Some`, `Option::None`, `Result::Ok`, `Result::Err`, and exhaustive `match` for `Option` and `Result`
- user-defined `enum` declarations with optional unconstrained type parameters, zero-payload and one-payload variants, qualified construction/patterns, exhaustive `match`, VM execution, typed HIR, and in-memory package interface summaries
- prefix `try expr` propagation for `Result[T, E]` with exact error-type matching
- `Map.empty`, `contains`, `get`, `insert`, and `remove` for `Int`, `Bool`, and `String` keys
- file-based package mode with `package`, `import`, `pkg`, `pub`, `as`, module-private top-level items, and `alias::Name`
- minimal `muga.toml` project mode with `[package] name/source`
- unflattened package graph loading for package/module/item/export metadata, used by the default package-aware checking path
- typed HIR with resolved call shape, call origin, expression types, local binding identity, and package item identity
- in-memory package interface summaries for public records/enums/functions plus validation of public package references against those summaries
- hardened enum diagnostics, package enum visibility checks, imported `alias::Enum::Variant` constructors/patterns, and package enum call-target identity
- deterministic v2 package interface text persistence with stable artifact package/item IDs, content hashes, direct dependency metadata, file write/read helpers, artifact path naming, round-trip validation, and loaded-interface validation for public records/enums/functions
- downstream typed checking can use loaded package interfaces or discovered `.mgi` artifacts, including transitive public-signature type dependencies, without reading dependency implementation bodies
- package check cache keys combine entry package source content with loaded direct/transitive dependency interface hashes, and `.mgc` check artifacts are rejected when missing or stale
- `muga check --artifact-root <dir>` validates package entries through package-aware checks against `.mgi` and `.mgc` artifacts without reading dependency implementation bodies
- `muga emit-interface` and `muga emit-artifacts` write reachable `.mgi` interfaces from package-aware typed HIR; `emit-artifacts` also writes `.mgb` package implementation artifacts as MIR-lowered bytecode programs and the entry `.mgc` check cache
- `muga run --artifact-root <dir>` validates `.mgi` / `.mgc` / structurally checked `.mgb` artifacts and executes direct and transitive package dependencies without reading dependency source files from the source tree
- artifact-backed `run` remaps independently generated `.mgb` package item references onto the loaded `.mgi` interface identities, while reserving private implementation item ids so dependency bodies do not collide with the entry package during bytecode merge
- structured diagnostics with related notes and suggestions in selected resolver, typechecker, record, and package errors
- library-only package-aware checking entrypoint that validates package boundary, import, visibility, and public-signature rules over the unflattened package graph before package-aware module checking
- package-aware source and per-module signature environments derived from the unflattened package graph, preserving package item identity, module/same-package/import visibility, and generic enum signature arity
- package-aware module body resolution/typechecking against those module signature environments, with per-module resolver/typecheck outputs and typed HIR programs retained by the package-aware API
- package-aware checks aggregate per-module typed HIR from the unflattened module check outputs instead of the legacy flattened typed path
- package-aware checking and loaded/interface-artifact typed compilation collect dependency signatures directly from in-memory or persisted package interfaces without reading dependency source bodies
- loaded-interface package-aware checks build dependency package graph metadata directly from package interfaces instead of loading dependency AST stubs
- package-aware typed HIR can lower through the MIR/bytecode VM path, including imported package records/enums/functions
- default package `run` lowers package-aware typed HIR through MIR before bytecode generation
- bytecode/runtime name references carry semantic binding identity, lowered local identity, and display symbols; runtime environments are slot-backed by lowered `LocalId`
- user-defined generic records and generic functions with explicit declaration type parameters, ordinary call/literal inference, and persisted package-interface support for public generic signatures

Not implemented yet:

- map literals, `Set[T]`, arbitrary `Map` key types, and broad collection APIs
- public-signature inference for `pub fn`; public functions currently need explicit signatures
- resource handles, `Path`, binary `Bytes`, directory APIs, stdout/stderr handles, project-mode artifact-root config, dependency declarations, registries, full incremental package artifact reuse, control-flow-oriented MIR, and native code generation

## Planned Priority

The explicit package artifact workflow remains the v1 package boundary: artifact-backed `check` consumes `.mgi` and `.mgc` artifacts without dependency implementation bodies, and artifact-backed `run` consumes `.mgi`, `.mgc`, and structurally validated MIR-lowered bytecode `.mgb` artifacts without reading dependency source files from the source tree. With generic records/functions, `Result` propagation, first string helpers, explicit scalar formatting, `Unit`, and the first `std::io` / `std::fs` text-file slice now landed, the next priority is hardening practical stdlib/package behavior without expanding into handles, `Path`, binary IO, or control-flow MIR prematurely.

Control-flow MIR, native backend work, wildcard-heavy pattern matching, broad collection APIs, and full incremental project artifact reuse remain deferred. The detailed breakdown lives in [ROADMAP.md](./ROADMAP.md), [docs/implementation-resume-plan.md](./docs/implementation-resume-plan.md), and the practical-language backlog in [docs/practical-language-readiness.md](./docs/practical-language-readiness.md).

## Samples

- [samples/sum_to.muga](./samples/sum_to.muga)
- [samples/println_sum.muga](./samples/println_sum.muga)
- [samples/inferred_types.muga](./samples/inferred_types.muga) (runnable sample showing that parameter and return type annotations can be omitted when inference succeeds)
- [samples/no_main.muga](./samples/no_main.muga) (runnable sample showing that `main()` is optional — top-level statements run directly)
- [samples/closure_capture.muga](./samples/closure_capture.muga)
- [samples/record_field_access.muga](./samples/record_field_access.muga) (runnable sample for `record` and field access)
- [samples/record_counter_loop.muga](./samples/record_counter_loop.muga) (runnable sample for mutable bindings and `record.with(...)`)
- [samples/nested_record_access.muga](./samples/nested_record_access.muga) (runnable sample for nested record access)
- [samples/record_with_update.muga](./samples/record_with_update.muga) (runnable sample for `record`, field access, and `record.with(...)`)
- [samples/record_user.muga](./samples/record_user.muga) (runnable sample for record declarations, receiver-shaped parameters, and chained calls)
- [samples/method_chain_user.muga](./samples/method_chain_user.muga) (runnable sample for chained UFCS-style calls)
- [samples/number_chain.muga](./samples/number_chain.muga) (runnable sample for chaining plain functions on `Int`)
- [samples/println_chain.muga](./samples/println_chain.muga) (runnable sample for chaining through builtin `println`)
- [samples/print_then_println.muga](./samples/print_then_println.muga) (runnable sample for mixing `print` and `println`)
- [samples/mixed_chain_pipeline.muga](./samples/mixed_chain_pipeline.muga) (runnable sample that mixes UFCS calls, record update, and field access)
- [samples/string_helpers.muga](./samples/string_helpers.muga) (runnable sample for `String` helper builtins, including `String.char_count()` / `String.slice_chars()`, and chained calls)
- [samples/string_format_helpers.muga](./samples/string_format_helpers.muga) (runnable sample for explicit `to_string()` plus `String.concat()`)
- [samples/string_parse_int.muga](./samples/string_parse_int.muga) (runnable sample for `String.parse_int()` and `try` propagation)
- [samples/string_parse_bool.muga](./samples/string_parse_bool.muga) (runnable sample for `String.parse_bool()` and `try` propagation)
- [samples/unit_result.muga](./samples/unit_result.muga) (runnable sample for `Unit` as a `Result` success value)
- [samples/higher_order_functions.muga](./samples/higher_order_functions.muga) (runnable sample for higher-order functions with minimal annotations)
- [samples/higher_order_local_inference.muga](./samples/higher_order_local_inference.muga) (runnable sample for locally inferred higher-order parameters and anonymous functions)
- [samples/higher_order_explicit_arrow.muga](./samples/higher_order_explicit_arrow.muga) (runnable sample for explicit arrow annotations on callbacks)
- [samples/generic_box.muga](./samples/generic_box.muga) (runnable sample for generic records, generic functions, and record literal type-argument inference)
- [samples/packages/app/main/main.muga](./samples/packages/app/main/main.muga) (runnable package entrypoint that imports `util::numbers` and `util::users`, and demonstrates `expr.alias::name(...)` chained calls)
- [samples/packages/app/split_main/main.muga](./samples/packages/app/split_main/main.muga) (runnable package sample where the entry package is split across multiple files)
- [samples/packages/app/alias_demo/main.muga](./samples/packages/app/alias_demo/main.muga) (runnable package sample that uses `import ... as ...` to avoid alias collisions)
- [samples/packages/app/enum_demo/main.muga](./samples/packages/app/enum_demo/main.muga) (runnable package sample that exports and consumes a public generic enum)
- [samples/packages/app/artifact_facade/main.muga](./samples/packages/app/artifact_facade/main.muga) (runnable package sample with `app -> api -> model` imports, useful for artifact-backed transitive execution)
- [samples/projects/my_service/src/main/main.muga](./samples/projects/my_service/src/main/main.muga) (runnable manifest project sample where package declarations are inferred from `muga.toml` and directories)

Planned concurrency draft samples:

- [samples/planned_concurrency_group.muga](./samples/planned_concurrency_group.muga) (recommended Phase 1 direction: `group` / `spawn` / `join`)
- [samples/planned_concurrency_channels.muga](./samples/planned_concurrency_channels.muga) (later-phase extension after the structured task core is stable)

Sample note:

- In [samples/mixed_chain_pipeline.muga](./samples/mixed_chain_pipeline.muga), `10.start().inc().inc().value.double()` has the same meaning as `double(inc(inc(start(10))).value)`. Both chain style and ordinary call style are valid.

Higher-order annotation guide:

- Omit an arrow annotation when the callback type is uniquely determined inside the same function body, as in [samples/higher_order_functions.muga](./samples/higher_order_functions.muga) and [samples/higher_order_local_inference.muga](./samples/higher_order_local_inference.muga).
- Keep an arrow annotation when local inference is still ambiguous, or when you want the callback contract to be obvious at the declaration site, as in [samples/higher_order_explicit_arrow.muga](./samples/higher_order_explicit_arrow.muga).
- Current `pub fn` declarations require explicit signatures for v1. A post-v1 direction is to infer public signatures in the defining package and store resolved signatures in package interfaces.

Package alias note:

- `import company::analytics::numbers` gives the default local alias `numbers`.
- If two imports would produce the same alias, the file is rejected with `PK007`.
- Use `as` to disambiguate, as shown in [samples/packages/app/alias_demo/main.muga](./samples/packages/app/alias_demo/main.muga).

Package layout note:

- Muga's package draft uses `directory = package` and `file = module`.
- Source files import logical package paths such as `my_service::users`, not filesystem paths such as `../users`.
- In manifest project mode, `name = "my_service"` and `source = "src"` let `src/users/` map to `my_service::users` without nesting another `my_service/` directory under `src/`.
- Without a nearby `muga.toml`, a package file must start with an explicit `package ...` declaration before it can use `import`, `pub`, or `pkg`.
- The target distribution model is manifest-based and should use cached package interfaces and implementation artifacts for fast rebuilds. The compiler library and CLI can emit and consume `.mgi`, `.mgb`, and `.mgc` artifacts for explicit artifact-backed checks and runs, but project-mode artifact-root config and automatic artifact reuse are not implemented yet.
- See [spec/006-packages.md](./spec/006-packages.md) for the large-project layout and distribution model.

## License

Licensed under the [MIT License](./LICENSE.txt).
