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

}

/// Zero-state owner for authority over one module graph's mutable state.

export record Permission {}

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

}

/// Copyable state stored in a module graph update 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 opaque record ModuleGraph: 'permission {

    /// Entry identities indexed by module identifier.

    entries: *mut [?*ModuleEntry],

    /// Permission-associated updates indexed by module identifier.

    updates: [?*cell 'permission ModuleUpdates; MAX_MODULES],

    /// External authority for the update cells in this graph.

    permission: &'permission mut Permission,

    /// 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 'permission (

    storage: *mut [?*ModuleEntry],

    arena: &mut ast::NodeArena,

    permission: &'permission mut Permission

) -> ModuleGraph 'permission {

    for i in 0..storage.len {

        set storage[i] = nil;

    }

    return ModuleGraph 'permission {

        entries: storage,

        updates: [nil; MAX_MODULES],

        permission,

        entriesLen: 0,

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

    };

}

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

export unsafe fn registerRoot 'permission (graph: &mut ModuleGraph 'permission, 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 'permission (

    graph: &mut ModuleGraph 'permission, 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 'permission (

    graph: &mut ModuleGraph 'permission, 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(graph, parent, m.id);

    publish(graph, m);

    return id;

}

/// Return the number of registered module identities.

export fn entryCount 'permission (graph: &ModuleGraph 'permission) -> u32 {

    return graph.entriesLen;

}

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

export fn get 'permission (graph: &ModuleGraph 'permission, 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 'permission (graph: &ModuleGraph 'permission, m: *ModuleEntry, index: u32) -> u16 {

    let cell = updatesFor(graph, m.id);

    let authority: 'loan = &*graph.permission, updates = &*cell in {

        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 'permission (graph: &ModuleGraph 'permission, id: u16) -> ModuleState throws (ModuleError) {

    let m = get(graph, id) else {

        throw ModuleError::NotFound(id);

    };

    let cell = updatesFor(graph, m.id);

    let authority: 'loan = &*graph.permission, updates = &*cell in {

        return updates.state;

    }

}

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

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

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

    let cell = updatesFor(graph, m.id);

    let authority: 'loan = &mut *graph.permission, updates = &mut *cell in {

        set updates.ast = root;

        set updates.state = ModuleState::Parsed;

    }

}

/// Set the source text for a module.

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

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

    let cell = updatesFor(graph, m.id);

    let authority: 'loan = &mut *graph.permission, updates = &mut *cell in {

        set updates.source = source;

    }

}

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

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

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

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

    let cell = updatesFor(graph, parent.id);

    let authority: 'loan = &*graph.permission, updates = &*cell in {

        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 'permission (graph: &mut ModuleGraph 'permission, 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 'permission (graph: &mut ModuleGraph 'permission, 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;

    let updates: *cell 'permission ModuleUpdates = &cell 'permission *state;

    let authority: 'loan = &mut *graph.permission, value = &mut *updates in {

        set *value = ModuleUpdates {

            state: ModuleState::Registered,

            children: [0; MAX_MODULES],

            childrenLen: 0,

            ast: nil,

            source: nil,

        };

    }

    set graph.updates[idx] = updates;

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

    };

    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 'permission (graph: &mut ModuleGraph 'permission, parent: *ModuleEntry, childId: u16) -> u16 throws (ModuleError) {

    let cell = updatesFor(graph, parent.id);

    let authority: 'loan = &mut *graph.permission, updates = &mut *cell in {

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

            throw ModuleError::CapacityExceeded;

        }

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

        set updates.childrenLen += 1;

    }

    return childId;

}

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

fn publish 'permission (graph: &mut ModuleGraph 'permission, 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 'permission (graph: &ModuleGraph 'permission, entry: *ModuleEntry) -> u32 {

    let cell = updatesFor(graph, entry.id);

    let authority: 'loan = &*graph.permission, updates = &*cell in {

        return updates.childrenLen;

    }

}

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

export fn astFor 'permission (graph: &ModuleGraph 'permission, entry: *ModuleEntry) -> ?*ast::Node {

    let cell = updatesFor(graph, entry.id);

    let authority: 'loan = &*graph.permission, updates = &*cell in {

        return updates.ast;

    }

}

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

export fn sourceFor 'permission (graph: &ModuleGraph 'permission, entry: *ModuleEntry) -> ?*[u8] {

    let cell = updatesFor(graph, entry.id);

    let authority: 'loan = &*graph.permission, updates = &*cell in {

        return updates.source;

    }

}

/// Return the permission-associated update cell for `id`.

fn updatesFor 'permission (graph: &ModuleGraph 'permission, id: u16) -> *cell 'permission ModuleUpdates {

    assert isValidId(graph, id), "updatesFor: module identifier is valid";

    let cell = graph.updates[id as u32] else {

        panic "updatesFor: missing update cell";

    };

    return cell;

}

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

fn isValidId 'permission (graph: &ModuleGraph 'permission, 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;

}