module-lang 1.0.0

Module and import resolution for multi-file languages.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

# module-lang v0.1.0 — Scaffold

**The repository bootstrap.** v0.1.0 stands up the crate, the tooling, and the
quality gates the implementation is built on — and nothing more. There is no
domain logic in this release on purpose: the module graph, the stable module ids,
import resolution, visibility, and cycle detection land across the 0.x series, each
behind a passing gate. This tag exists so that the first line of real resolution
code is written against a green CI, a fixed toolchain contract, and a documented
plan, rather than into an empty directory.

## What is module-lang?

The module and import resolution layer for a compiler front-end. Given the modules
a front-end has already parsed — each exporting a set of named items — it answers
the question every `use`/`import` asks: *which item does this name refer to?* It
builds the module graph, resolves each import to its target, reports unresolved
names and import cycles as defined errors, and honours item visibility. It sits in
the SEMA tier above [`symbol-lang`](https://docs.rs/symbol-lang), which interns the
names, and [`source-lang`](https://docs.rs/source-lang), which owns the files those
modules came from. It owns module and import resolution only — parsing, type
checking, and code generation live elsewhere — and it is one of the SEMA-tier
crates of the `-lang` language-construction family.

## What's in 0.1.0

### Crate manifest and toolchain contract

`Cargo.toml` declares the full publish metadata — description, keywords,
categories, repository, homepage, dual `Apache-2.0 OR MIT` license, and authors —
on Rust 2024 edition with MSRV 1.85. The feature set is minimal and additive:
`std` on by default, with an opt-in `serde` feature reserved for graph metadata. No
first-party dependency is wired yet; `symbol-lang` and `source-lang` are added at
v0.2.0 when the resolution code first uses them, so the scaffold carries no unused
dependency.

### Quality gates, wired before the code

The CI matrix (`.github/workflows/ci.yml`) runs the full gate on Linux, macOS, and
Windows against both stable and the 1.85 MSRV: `cargo fmt --check`, clippy on
default and all features with `-D warnings`, the test suite on both feature sets,
and a documentation build with `-D warnings`. A separate security job runs
`cargo audit` and `cargo deny check`. `deny.toml`, `clippy.toml`, and
`rustfmt.toml` pin the license allow-list, the lint profile (MSRV-aligned at
1.85), and the import-grouping style. The crate root sets `#![forbid(unsafe_code)]`
and `#![deny(missing_docs)]` from the first commit.

### Documentation and plan

`README.md` and `docs/API.md` describe the intended surface and mark each item
still planned, so the public contract is legible before it is implemented.
`dev/DIRECTIVES.md` records the definition of done and the project-specific
invariants the property tests will hold to: every module gets a unique, stable id;
an import resolves to exactly the item the name refers to under the visibility
rules, or a defined error; a private item is never resolvable from outside its
module; and an import cycle is reported in bounded time, never as unbounded
recursion. `dev/ROADMAP.md` front-loads the hard part — module and import
resolution across multiple files at v0.2.0, where `symbol-lang` and `source-lang`
are wired — and carries an anti-deferral rule: no listed hard task slips to a later
phase without the file recording the move and the reason.

## Breaking changes

**None.** This is the first tag.

## Verification

Run on Windows x86_64 and Linux (WSL2 Ubuntu), Rust stable and the 1.85 MSRV;
identical commands run in the configured CI matrix:

```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo test --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo build --no-default-features
cargo +1.85 build --all-features
cargo deny check
cargo audit
```

All green. Counts at this tag: 1 unit test (a build smoke test), 0 doctests —
there is no public surface to exercise yet.

## What's next

- **0.2.0 — Module and import resolution.** Wire `symbol-lang` and `source-lang`;
  build the module graph, stable module ids, and the resolver that maps each import
  to its target with average `O(1)` name lookup. Unresolved imports, duplicate
  definitions, visibility violations, and import cycles become defined errors, each
  property-tested against a hand-traced resolution. This is the hard part, and it is
  not deferred.

## Installation

```toml
[dependencies]
module-lang = "0.1"
```

MSRV: Rust 1.85.

## Documentation

- [README](https://github.com/jamesgober/module-lang/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/module-lang/blob/main/docs/API.md)
- [CHANGELOG](https://github.com/jamesgober/module-lang/blob/main/CHANGELOG.md)

---

**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/module-lang/blob/main/CHANGELOG.md).