//! Module graph and loader.

//!

//! This module tracks source files, parent/child relationships, and basic state for each

//! module so that later phases (parser, semantic analyzer) can resolve imports (`use`)

//! and avoid reloading the same file twice.

export mod printer;

@test mod tests;

use std::mem;

use std::lang::alloc;

use std::lang::ast;

use std::lang::strings;

/// Maximum number of modules tracked in a single compilation graph.

export constant MAX_MODULES: u32 = 192;

/// Maximum number of characters for a module path.

constant MAX_PATH_LEN: u32 = 256;

/// Maximum number of components that make up a logical module path.

constant MAX_MODULE_PATH_DEPTH: u32 = 16;

/// Filesystem separator used when constructing child paths.

constant PATH_SEP: u8 = '/';

/// Source file extension handled by the loader.

constant SOURCE_EXT: *[u8] = ".rad";

/// Lifecycle state for modules in the dependency graph.

export union ModuleState: Copy {

    /// Slot unused or yet to be initialized.

    Vacant,

    /// Module registered with a known path but not parsed yet.

    Registered,

    /// Module is currently being parsed (used for cycle detection).

    Parsing,

    /// Module finished parsing successfully.

    Parsed,

    /// Module is undergoing semantic analysis.

    Analyzing,

    /// Module finished semantic analysis and is ready for codegen.

    Ready,

}

/// Error categories that can be produced by the module graph.

export union ModuleError: Copy {

    /// Module not found.

    NotFound(u16),

    /// Adding the module would exceed the fixed storage.

    CapacityExceeded,

    /// Provided path is missing the required `.rad` extension or otherwise invalid.

    InvalidPath,

    /// Module graph path exceeded the maximum logical depth.

    PathTooDeep,

    /// Attempt to register a module before its parent.

    MissingParent,

}

/// Module metadata recorded inside the dependency graph.

export record ModuleEntry: Copy {

    /// Numeric identifier for the slot (index in the graph array).

    id: u16,

    /// Package identifier this module belongs to.

    packageId: u16,

    /// Parent module identifier, or `nil` for root modules.

    parent: ?u16,

    /// Absolute or workspace-relative path to the `.rad` source file.

    filePath: *[u8],

    /// Number of bytes covering the directory portion of `filePath`.

    dirLen: u32,

    /// Module name.

    name: *[u8],

    /// Logical path from the root module to this module.

    path: [*[u8]; MAX_MODULE_PATH_DEPTH],

    /// Number of segments inside `path`.

    pathDepth: u32,

    /// Mutable module state shared by all entry views.

    updates: *cell ModuleUpdates,

}

/// Copyable state stored in a module entry's cell.

export record ModuleUpdates: Copy {

    /// Current lifecycle state.

    state: ModuleState,

    /// Child module identifiers declared directly inside this module.

    children: [u16; MAX_MODULES],

    /// Number of entries stored in `children`.

    childrenLen: u32,

    /// Parsed AST root for this module when available.

    ast: ?*ast::Node,

    /// Source text for this module (for error reporting).

    source: ?*[u8],

}

/// Dense storage for all modules referenced by the compilation unit.

export record ModuleGraph {

    /// Entry identities indexed by module identifier.

    entries: *mut [?*ModuleEntry],

    /// Number of initialized entries.

    entriesLen: u32,

    /// Arena for AST nodes and stable entry allocations.

    arena: ?*unsafe mut ast::NodeArena,

}

/// Initialize an empty module graph backed by the provided storage.

/// The AST arena must outlive the graph and all retained entry views.

/// Entry allocation must occur outside speculative parser allocations.

export unsafe fn moduleGraph(

    storage: *mut [?*ModuleEntry],

    arena: &mut ast::NodeArena

) -> ModuleGraph {

    for i in 0..storage.len {

        set storage[i] = nil;

    }

    return ModuleGraph {

        entries: storage,

        entriesLen: 0,

        arena: arena as *unsafe mut ast::NodeArena,

    };

}

/// Register a root module residing at `path` for a package.

export unsafe fn registerRoot(graph: &mut ModuleGraph, pool: &mut strings::Pool, packageId: u16, filePath: *[u8]) -> u16 throws (ModuleError) {

    let name = try basenameSlice(filePath);

    return try registerRootWithName(graph, pool, packageId, name, filePath);

}

/// Register a root module with an explicit name and file path for a package.

export unsafe fn registerRootWithName(

    graph: &mut ModuleGraph, pool: &mut strings::Pool,

    packageId: u16,

    name: *[u8],

    filePath: *[u8]

) -> u16 throws (ModuleError) {

    let m = try allocModule(graph, pool, packageId, name, filePath);

    try appendPathSegment(m, name);

    let id = m.id;

    publish(graph, m);

    return id;

}

/// Register a child module.

/// Returns the module identifier.

export unsafe fn registerChild(

    graph: &mut ModuleGraph, pool: &mut strings::Pool,

    parentId: u16,

    name: *[u8],

    filePath: *[u8]

) -> u16 throws (ModuleError) {

    assert name.len > 0, "registerChild: name must not be empty";

    assert filePath.len > 0, "registerChild: file path must not be empty";

    let parent = get(graph, parentId)

        else throw ModuleError::NotFound(parentId);

    // If the child already exists under this parent, return it.

    if let child = findChild(graph, name, parentId) {

        return child.id;

    }

    // Inherit packageId from parent.

    let m = try allocModule(graph, pool, parent.packageId, name, filePath);

    set m.parent = parentId;

    // Inherit path prefix from parent.

    for p in moduleQualifiedPath(parent) {

        try appendPathSegment(m, p);

    }

    try appendPathSegment(m, name);

    let id = try addChild(parent, m.id);

    publish(graph, m);

    return id;

}

/// Fetch a read-only view of the module identified by `id`.

export fn get(graph: &ModuleGraph, id: u16) -> ?*ModuleEntry {

    if not isValidId(graph, id) {

        return nil;

    }

    return graph.entries[id as u32];

}

/// Return the identifier of the child stored at `index`.

export fn childAt(m: *ModuleEntry, index: u32) -> u16 {

    let updates = *m.updates;

    assert index < updates.childrenLen, "childAt: index must be valid";

    return updates.children[index];

}

/// Public accessor for a module's directory prefix.

export fn moduleDir(m: *ModuleEntry) -> *[u8] {

    return &m.filePath[..m.dirLen];

}

/// Public accessor to the logical module path segments.

export fn moduleQualifiedPath(m: *ModuleEntry) -> *[*[u8]] {

    assert m.pathDepth > 0, "moduleQualifiedPath: path must not be empty";

    return &m.path[..m.pathDepth];

}

/// Retrieve the lifecycle state for `id`.

export fn state(graph: &ModuleGraph, id: u16) -> ModuleState throws (ModuleError) {

    let m = get(graph, id) else {

        throw ModuleError::NotFound(id);

    };

    return (*m.updates).state;

}

/// Record the parsed AST root for `id`.

export fn setAst(graph: &mut ModuleGraph, id: u16, root: *ast::Node) throws (ModuleError) {

    let m = get(graph, id) else throw ModuleError::NotFound(id);

    let mut updates = *m.updates;

    set updates.ast = root;

    set updates.state = ModuleState::Parsed;

    set *m.updates = updates;

}

/// Set the source text for a module.

export fn setSource(graph: &mut ModuleGraph, id: u16, source: *[u8]) throws (ModuleError) {

    let m = get(graph, id) else throw ModuleError::NotFound(id);

    let mut updates = *m.updates;

    set updates.source = source;

    set *m.updates = updates;

}

/// Look up a child module by name under the given parent.

export fn findChild(graph: &ModuleGraph, name: *[u8], parentId: u16) -> ?*ModuleEntry {

    assert isValidId(graph, parentId), "findChild: parent identifier is valid";

    let parent = get(graph, parentId) else panic;

    let updates = *parent.updates;

    for i in 0..updates.childrenLen {

        let childId = updates.children[i];

        let child = get(graph, childId) else panic;

        if mem::eq(child.name, name) {

            return child;

        }

    }

    return nil;

}

/// Parse a file path into components by splitting on '/'.

/// Expects and removes the '.rad' extension from the last component.

/// Returns the number of components extracted, or `nil` if the path is invalid.

export fn parsePath(filePath: *[u8], components: &mut [*[u8]]) -> ?u32 {

    let mut count: u32 = 0;

    let mut last: u32 = 0;

    // Split on '/' to extract all but the last component.

    for i in 0..filePath.len {

        if filePath[i] == PATH_SEP {

            if i > last {

                assert count < components.len, "parsePath: output slice is large enough";

                set components[count] = &filePath[last..i];

                set count += 1;

            }

            set last = i + 1;

        }

    }

    if last >= filePath.len {

        return nil; // Path ends with separator or is empty.

    }

    // Handle the last component by removing extension.

    assert count < components.len, "parsePath: output slice is large enough";

    if let name = trimExtension(&filePath[last..]) {

        set components[count] = name;

    } else {

        return nil;

    };

    set count += 1;

    return count;

}

/// Register a module from a file path, creating the full hierarchy as needed.

/// The path is split into components and the module hierarchy is built accordingly.

/// If `rootId` is `nil`, registers a new root for the given package.

/// Returns the module ID of the last component.

export unsafe fn registerFromPath(graph: &mut ModuleGraph, pool: &mut strings::Pool, packageId: u16, rootId: ?u16, filePath: *[u8]) -> u16 throws (ModuleError) {

    let root = rootId else {

        return try registerRoot(graph, pool, packageId, filePath);

    };

    let rootEntry = get(graph, root) else {

        panic "registerFromPath: root is missing from storage";

    };

    // Strip the base directory from the file path.

    let baseDir = moduleDir(rootEntry);

    let pathSuffix = mem::stripPrefix(baseDir, filePath) else {

        throw ModuleError::InvalidPath;

    };

    // Parse the stripped path into components.

    let mut parts: [*[u8]; MAX_MODULE_PATH_DEPTH] = [""; MAX_MODULE_PATH_DEPTH];

    let partsLen = parsePath(pathSuffix, &mut parts[..]) else {

        throw ModuleError::InvalidPath;

    };

    if partsLen == 0 {

        throw ModuleError::InvalidPath;

    }

    // Strip the root's qualified path from the parsed components.

    let rootPath = moduleQualifiedPath(rootEntry);

    let prefixLen = stripPathPrefix(rootPath, &parts[..partsLen]) else {

        throw ModuleError::InvalidPath;

    };

    if prefixLen == partsLen {

        throw ModuleError::InvalidPath;

    }

    let childName = parts[partsLen - 1];

    // Navigate through all but the last segment to find the parent.

    let mut parentId = root;

    for part in &parts[prefixLen..partsLen - 1] {

        let child = findChild(graph, part, parentId) else {

            throw ModuleError::MissingParent;

        };

        set parentId = child.id;

    }

    return try registerChild(graph, pool, parentId, childName, filePath);

}

/// Allocate a fresh entry in the graph.

unsafe fn allocModule(graph: &mut ModuleGraph, pool: &mut strings::Pool, packageId: u16, name: *[u8], filePath: *[u8]) -> *mut ModuleEntry throws (ModuleError) {

    if graph.entriesLen >= graph.entries.len {

        throw ModuleError::CapacityExceeded;

    }

    let idx = graph.entriesLen;

    let arena = graph.arena else panic;

    let state = try! alloc::alloc(&mut arena.arena, @sizeOf(ModuleUpdates), @alignOf(ModuleUpdates)) as *mut ModuleUpdates;

    set *state = ModuleUpdates {

        state: ModuleState::Registered,

        children: [0; MAX_MODULES],

        childrenLen: 0,

        ast: nil,

        source: nil,

    };

    let updates = &cell *state;

    // TODO: This is a common pattern that needs better syntax.

    let m = try! alloc::alloc(&mut arena.arena, @sizeOf(ModuleEntry), @alignOf(ModuleEntry)) as *mut ModuleEntry;

    set *m = ModuleEntry {

        id: idx as u16,

        packageId,

        parent: nil,

        filePath,

        dirLen: dirLength(filePath),

        name: strings::intern(pool, name),

        path: [""; MAX_MODULE_PATH_DEPTH],

        pathDepth: 0,

        updates,

    };

    return m;

}

/// Append a logical path segment (module identifier) to the entry.

fn appendPathSegment(entry: &mut ModuleEntry, segment: *[u8]) throws (ModuleError) {

    if entry.pathDepth >= entry.path.len {

        throw ModuleError::PathTooDeep;

    }

    set entry.path[entry.pathDepth] = segment;

    set entry.pathDepth += 1;

}

/// Append a child identifier to the parent's child list.

fn addChild(parent: *ModuleEntry, childId: u16) -> u16 throws (ModuleError) {

    let mut updates = *parent.updates;

    if updates.childrenLen >= updates.children.len {

        throw ModuleError::CapacityExceeded;

    }

    set updates.children[updates.childrenLen] = childId;

    set updates.childrenLen += 1;

    set *parent.updates = updates;

    return childId;

}

/// Publish a fully initialized module entry in identifier order.

fn publish(graph: &mut ModuleGraph, entry: *ModuleEntry) {

    assert entry.id as u32 == graph.entriesLen;

    set graph.entries[graph.entriesLen] = entry;

    set graph.entriesLen += 1;

}

/// Return the number of registered children.

export fn childCount(entry: *ModuleEntry) -> u32 {

    return (*entry.updates).childrenLen;

}

/// Return the current parsed root for an entry.

export fn astFor(entry: *ModuleEntry) -> ?*ast::Node {

    return (*entry.updates).ast;

}

/// Return the current source text for an entry.

export fn sourceFor(entry: *ModuleEntry) -> ?*[u8] {

    return (*entry.updates).source;

}

/// Check if `id` points at an allocated entry.

fn isValidId(graph: &ModuleGraph, id: u16) -> bool {

    return (id as u32) < graph.entriesLen;

}

/// Return the length of the directory prefix for `path`.

/// Return zero if the path has no separator.

fn dirLength(path: *[u8]) -> u32 {

    let mut start: u32 = 0;

    for i in 0..path.len {

        if path[i] == PATH_SEP {

            set start = i + 1;

        }

    }

    return start;

}

/// Produce a subslice for the basename of `path` (without extension).

fn basenameSlice(path: *[u8]) -> *[u8] throws (ModuleError) {

    let start = dirLength(path);

    let withoutExt = trimExtension(path) else {

        throw ModuleError::InvalidPath;

    };

    return &withoutExt[start..];

}

/// Trim the `.rad` extension from `path` if present.

/// Returns the path slice without the extension.

export fn trimExtension(path: *[u8]) -> ?*[u8] {

    if path.len < SOURCE_EXT.len {

        return nil;

    }

    let extStart = path.len - SOURCE_EXT.len;

    for ext, i in SOURCE_EXT {

        if path[extStart + i] <> ext {

            return nil;

        }

    }

    return &path[..extStart];

}

/// Check a path prefix and return its segment count.

fn stripPathPrefix(prefix: &[*[u8]], path: &[*[u8]]) -> ?u32 {

    if prefix.len == 0 {

        return 0;

    }

    if prefix.len > path.len {

        return nil;

    }

    for segment, i in prefix {

        if not mem::eq(segment, path[i]) {

            return nil;

        }

    }

    return prefix.len;

}