Gat Modules & Package Manager Specification

1. Import System & Namespaces

Gat supports two modes of importing code:

1.1 Relative-Path Intra-Project Imports

Imports with relative file paths inline declarations into the root AST scope (for intra-project files and standard library):

import "std/str.gat";
import "std/io.gat";
import "helpers.gat";

1.2 Namespaced Module Imports (as <namespace>)

To prevent naming collisions between independent packages or modules, use import "path" as alias; or import module_name;:

import "examples/modules/pkg_a/lib.gat" as pkg_a;
import "examples/modules/pkg_b/lib.gat" as pkg_b;

fn main() -> i64 {
    let a = pkg_a.compute(10);
    let b = pkg_b.compute(10);
    let pt = new pkg_a.Point { x: 1, y: 2 };
    return 0;
}

All top-level functions, structs, classes, and enums declared within the imported module are isolated and accessed via namespace.SymbolName.

1.3 Collision Detection on Unaliased Flat Imports

If two flatly-imported files declare the same top-level symbol (e.g. fn helper() or struct Config), the compiler detects the conflict during type registration and emits a fatal diagnostic:

[Type Error] duplicate declaration of function 'helper' across flat imports
[Error] Type checking failed due to semantic errors.

To resolve the collision, import at least one of the conflicting files using a namespaced alias (import "..." as pkg;).

---

2. Manifest (gat.mod) & Lockfile (gat.lock)

2.1 Manifest Format (gat.mod)

Every Gat package can declare its identity and external dependencies in gat.mod:

module my_project

// Dependencies: require <git_url_or_local_path> <version_tag_or_branch>
require github.com/user/gat-json v1.0.0
require ./packages/math_utils v0.2.0

2.2 Lockfile (gat.lock)

Running gat fetch generates or updates gat.lock to record the exact resolved dependencies:

# Auto-generated by gat. DO NOT EDIT.
lock gat-json github.com/user/gat-json v1.0.0
lock math_utils ./packages/math_utils v0.2.0

---

3. Package Manager CLI Commands

• gat init [module_name]: Initialize a fresh gat.mod in the current directory.
• gat fetch (or gat get): Read gat.mod, clone/copy dependencies into .gat/deps/<pkg_name>, and write gat.lock.
• gat build <file.gat>: Compile project. Named imports automatically resolve against .gat/deps/.