//! 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.

pub 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.

pub const MAX_MODULES: u32 = 128;

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

const MAX_MODULE_NAME_LEN: u32 = 64;

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

const MAX_PATH_LEN: u32 = 256;

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

const MAX_MODULE_PATH_DEPTH: u32 = 16;

/// Filesystem separator used when constructing child paths.

const PATH_SEP: u8 = '/';

/// Source file extension handled by the loader.

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

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

pub union ModuleState {

    /// 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.

pub union ModuleError {

    /// Module not found.

    NotFound(u16),

    /// Module path not found.

    PathNotFound(*[u8]),

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

    CapacityExceeded,

    /// Requested parent identifier is invalid.

    InvalidParent,

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

    InvalidPath,

    /// Attempted to register a module whose name already exists in the same namespace.

    DuplicateModule,

    /// Attempt to register a root module when there already is one.

    DuplicateRoot,

    /// Fully qualified file path exceeds the fixed storage.

    PathTooLong,

    /// Module name exceeds the fixed storage.

    NameTooLong,

    /// 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.

pub record ModuleEntry {

    /// 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,

    /// 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: ?*mut ast::Node,

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

    source: ?*[u8],

}

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

pub record ModuleGraph {

    entries: *mut [ModuleEntry],

    entriesLen: u32,

    pool: *mut strings::Pool,

    /// Arena used for all AST node allocations.

    arena: ?*ast::NodeArena,

}

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

pub fn moduleGraph(

    storage: *mut [ModuleEntry],

    pool: *mut strings::Pool,

    arena: *mut ast::NodeArena

) -> ModuleGraph {

    return ModuleGraph {

        entries: storage,

        entriesLen: 0,

        pool,

        arena,

    };

}

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

pub fn registerRoot(graph: *mut ModuleGraph, packageId: u16, filePath: *[u8]) -> u16 throws (ModuleError) {

    let name = try basenameSlice(filePath);

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

}

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

pub fn registerRootWithName(

    graph: *mut ModuleGraph,

    packageId: u16,

    name: *[u8],

    filePath: *[u8]

) -> u16 throws (ModuleError) {

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

    try appendPathSegment(m, m.name);

    m.state = ModuleState::Registered;

    return m.id;

}

/// Register a child module.

/// Returns the module identifier.

pub fn registerChild(

    graph: *mut ModuleGraph,

    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 = getMut(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, parent.packageId, name, filePath);

    m.dirLen = dirLength(m.filePath);

    m.state = ModuleState::Registered;

    m.parent = parentId;

    // Inherit path prefix from parent.

    for p in moduleQualifiedPath(parent) {

        try appendPathSegment(m, p);

    }

    try appendPathSegment(m, m.name);

    return try addChild(parent, m.id);

}

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

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

    if not isValidId(graph, id) {

        return nil;

    }

    return &graph.entries[id as u32];

}

/// Access a mutable entry by identifier.

fn getMut(graph: *mut ModuleGraph, id: u16) -> ?*mut ModuleEntry {

    if not isValidId(graph, id) {

        return nil;

    }

    return &mut graph.entries[id as u32];

}

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

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

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

    return m.children[index];

}

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

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

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

}

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

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

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

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

}

/// Update the recorded lifecycle state for `id`.

pub fn setState(graph: *mut ModuleGraph, id: u16, state: ModuleState) throws (ModuleError) {

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

    m.state = state;

}

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

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

    let m = get(graph, id) else {

        throw ModuleError::NotFound(id);

    };

    return m.state;

}

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

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

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

    m.ast = root;

    m.state = ModuleState::Parsed;

}

/// Set the source text for a module.

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

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

    m.source = source;

}

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

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

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

    let parent = &graph.entries[parentId as u32];

    for i in 0..parent.childrenLen {

        let childId = parent.children[i];

        let child = &graph.entries[childId as u32];

        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.

pub 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";

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

                count += 1;

            }

            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..]) {

        components[count] = name;

    } else {

        return nil;

    };

    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.

pub fn registerFromPath(graph: *mut ModuleGraph, packageId: u16, rootId: ?u16, filePath: *[u8]) -> u16 throws (ModuleError) {

    let root = rootId else {

        return try registerRoot(graph, 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] = undefined;

    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 childPath = stripPathPrefix(rootPath, &parts[..partsLen]) else {

        throw ModuleError::InvalidPath;

    };

    if childPath.len == 0 {

        throw ModuleError::InvalidPath;

    }

    let childName = childPath[childPath.len - 1];

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

    let mut parentId = root;

    for part in &childPath[..(childPath.len - 1)] {

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

            throw ModuleError::MissingParent;

        };

        parentId = child.id;

    }

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

}

/// Allocate a fresh entry in the graph.

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

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

        throw ModuleError::CapacityExceeded;

    }

    let idx = graph.entriesLen;

    graph.entriesLen += 1;

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

    let m = &mut graph.entries[idx];

    *m = ModuleEntry {

        id: idx as u16,

        packageId,

        parent: nil,

        filePath,

        dirLen: 0,

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

        path: undefined,

        pathDepth: 0,

        state: ModuleState::Vacant,

        children: undefined,

        childrenLen: 0,

        ast: nil,

        source: nil,

    };

    m.dirLen = dirLength(m.filePath);

    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;

    }

    entry.path[entry.pathDepth] = segment;

    entry.pathDepth += 1;

}

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

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

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

        throw ModuleError::CapacityExceeded;

    }

    parent.children[parent.childrenLen] = childId;

    parent.childrenLen += 1;

    return childId;

}

/// 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`.

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

    if path.len == 0 {

        return 0;

    }

    let mut last: i32 = -1;

    for i in 0..path.len {

        if path[i] == PATH_SEP {

            last = i as i32;

        }

    }

    if last < 0 {

        return 0;

    }

    return (last as u32) + 1;

}

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

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

    let start = basenameStart(path);

    let withoutExt = trimExtension(path) else {

        throw ModuleError::InvalidPath;

    };

    return &withoutExt[start..];

}

/// Find the byte offset immediately following the last separator.

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

    let mut start: u32 = 0;

    for i in 0..path.len {

        if path[i] == PATH_SEP {

            start = i + 1;

        }

    }

    return start;

}

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

/// Returns the path slice without the extension.

pub 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];

}

/// Strip prefix from path, and return the suffix.

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

    if prefix.len == 0 {

        return path;

    }

    if prefix.len > path.len {

        return nil;

    }

    for segment, i in prefix {

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

            return nil;

        }

    }

    return &path[prefix.len..];

}