Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-pkg

Source of release 0.6.2

0.6.2 / src / package.lucb

## Authored package definition in package.prisma; see docs/PACKAGE_PRISMA.md.
## Decoding uses Prism's own reader. Unknown elements and properties are errors.
import memory
from luce_prism import prism
import strings
from semver import parse, invalid

pub let max_size: usize = 65536
pub let max_dependencies: usize = 128
pub let max_public: usize = 64
pub let max_tasks: usize = 64
pub let max_task_depends: usize = 16
pub let max_development: usize = 16
## Development paths every package has: `luc install` leaves these out unless `--dev`.
pub let default_development: str[2] = ["tests", "dev"]

## `name` is the dependency's package name and the compiler's dependency key.
pub struct Requirement:
    pub var name: str
    pub var owner: str
    ## A caret requirement (`^1.2.0`) or an exact version; empty for the newest release.
    pub var version: str
    ## Empty, or a local checkout used instead of the registry release.
    pub var path: str

## How an application is bundled for the desktop: Name.app on macOS, an AppDir with a
## .desktop entry on Linux. `name` is the display name.
pub struct Application:
    pub var name: str
    ## Reverse-DNS identifier such as com.luciaos.luced.
    pub var identifier: str
    ## Empty, or a relative path to the icon (.icns on macOS, .png on Linux).
    pub var icon: str

## Native inputs the compiler builds and links with the package, as in its `[native]`.
pub struct Native:
    pub var sources: str[32]
    pub var source_count: usize
    pub var link_search: str[16]
    pub var link_search_count: usize
    pub var libraries: str[32]
    pub var library_count: usize
    pub var frameworks: str[32]
    pub var framework_count: usize
    pub var pkg_config: str[16]
    pub var pkg_config_count: usize

pub struct Task:
    pub var name: str
    pub var command: str
    pub var description: str
    pub var depends: str[16]
    pub var depend_count: usize

## Decoded definition. Strings borrow `storage`; callers close it once.
pub struct Definition:
    var storage: u8[]
    var dependencies: Requirement[]
    var tasks: Task[]
    pub var name: str
    pub var owner: str
    pub var version: str
    ## `package` (a library), `application` (a desktop program) or `tool` (a terminal program).
    pub var kind: str
    pub var language: str
    pub var source: str
    pub var description: str
    ## Empty, or the package's license as an SPDX expression: `MIT OR Apache-2.0`.
    pub var license: str
    pub var readme: str
    ## Empty for a library; the program entry path for an application.
    pub var entry: str
    ## Empty, or the post-compile install script of an application.
    pub var install: str
    pub var native: Native
    ## `application.name` is empty when the package declares no desktop bundle.
    pub var application: Application
    pub var dependency_count: usize
    pub var task_count: usize
    ## The modules other packages may import (`str[] public`), by their paths under the
    ## source root: `ui`, `widgets.button` (base.md ยง16.4).
    pub var public: str[64]
    pub var public_count: usize
    ## Development-only paths the package declares (`str[] development`), relative to its
    ## root, besides `tests` and `dev`. `luc install` leaves all of them out unless `--dev`.
    pub var development: str[16]
    pub var development_count: usize

    ## True for anything that builds a program: an application or a tool.
    pub func is_application() -> bool:
        return self.entry.length > 0

    pub func is_tool() -> bool:
        return self.kind == "tool"

    pub func is_package() -> bool:
        return self.kind == "package"

    pub func is_bundled() -> bool:
        return self.application.name.length > 0

    ## Borrowed dependency in lexical name order.
    pub func dependency_at(index: usize) -> Requirement!:
        if index >= self.dependency_count: error(invalid, "package dependency index out of bounds")
        return self.dependencies[index]

    ## Whether `path` (relative to the package root, `/`-separated) is development
    ## material: `tests`, `dev`, a declared development path, or anything inside one.
    pub func is_development(path: str) -> bool:
        for prefix in default_development:
            if under(path, prefix): return true
        for i in 0..<self.development_count:
            if under(path, self.development[i]): return true
        return false

    pub func task_at(index: usize) -> Task!:
        if index >= self.task_count: error(invalid, "package task index out of bounds")
        return self.tasks[index]

    pub func close():
        if self.dependencies.length > 0: free(self.dependencies) in memory.heap
        if self.tasks.length > 0: free(self.tasks) in memory.heap
        if self.storage.length > 0: free(self.storage) in memory.heap
        self = Definition()

func name_valid(value: str) -> bool:
    if value.length == 0 or value.length > 64: return false
    for i in 0..<value.length:
        let byte = value.bytes[i]
        let alnum = (byte >= 'a' and byte <= 'z') or (byte >= '0' and byte <= '9')
        if not alnum and (i == 0 or (byte != '_' and byte != '-')): return false
    return true

## Display names become directory names, so they stay plain: letters, digits, spaces, `-`, `_`, `.`.
func display_valid(value: str) -> bool:
    if value.length == 0 or value.length > 64 or value.bytes[0] == ' ' or value.bytes[0] == '.' or value.bytes[value.length - 1] == ' ': return false
    for byte in value.bytes:
        let alnum = (byte >= 'a' and byte <= 'z') or (byte >= 'A' and byte <= 'Z') or (byte >= '0' and byte <= '9')
        if not alnum and byte != ' ' and byte != '-' and byte != '_' and byte != '.': return false
    return true

## Reverse-DNS: at least two dot-separated labels of letters, digits and hyphens.
func identifier_valid(value: str) -> bool:
    if value.length == 0 or value.length > 128: return false
    var labels: usize
    var start: usize
    for end in 0..<value.length + 1:
        if end != value.length and value.bytes[end] != '.': continue
        if end == start: return false
        for byte in value.bytes[start..<end]:
            let alnum = (byte >= 'a' and byte <= 'z') or (byte >= 'A' and byte <= 'Z') or (byte >= '0' and byte <= '9')
            if not alnum and byte != '-': return false
        labels += 1
        start = end + 1
    return labels >= 2

## A library, framework or pkg-config name: never a path or an option.
func token_valid(value: str) -> bool:
    if value.length == 0 or value.length > 128 or value.bytes[0] == '-': return false
    for byte in value.bytes:
        let alnum = (byte >= 'a' and byte <= 'z') or (byte >= 'A' and byte <= 'Z') or (byte >= '0' and byte <= '9')
        if not alnum and byte != '_' and byte != '-' and byte != '.' and byte != '+': return false
    return true

## Dotted module name such as `luce_ui.ui`.
func module_valid(value: str) -> bool:
    if value.length == 0 or value.length > 256: return false
    var start: usize
    for end in 0..<value.length + 1:
        if end != value.length and value.bytes[end] != '.': continue
        if end == start: return false
        for byte in value.bytes[start..<end]:
            let alnum = (byte >= 'a' and byte <= 'z') or (byte >= 'A' and byte <= 'Z') or (byte >= '0' and byte <= '9')
            if not alnum and byte != '_': return false
        start = end + 1
    return true

## `inputs` or `all` for every target, an operating system (`macos`, `linux`, `windows`),
## or one exact target (`arm64-macos`, `x86_64-linux`, `x86_64-windows`).
func native_element_valid(name: str) -> bool:
    if name == "inputs" or name == "all": return true
    for known in ["macos", "linux", "windows", "arm64-macos", "x86_64-linux", "x86_64-windows"]:
        if name == known: return true
    return false

## Relative, `/`-separated, no empty, `.` or `..` segment, backslash, colon or control byte.
func path_valid(value: str) -> bool:
    if value.length == 0 or value.length > 1024: return false
    var start: usize
    for end in 0..<value.length + 1:
        if end != value.length:
            let byte = value.bytes[end]
            if byte < 0x20 or byte == 0x7f or byte == '\\' or byte == ':': return false
            if byte != '/': continue
        let part = (str)value.bytes[start..<end]
        if part.length == 0 or part == "." or part == "..": return false
        start = end + 1
    return true

## Whether public `module` (`widgets.button`) would sit in a development path of
## `definition`: its file `<source>/widgets/button.lucb` or its directory.
func public_development(definition: const Definition*, module: str) -> bool:
    var buffer: u8[1200]
    if definition.source.length + 1 + module.length + 5 > buffer.length: return false
    var used: usize = 0
    for byte in definition.source.bytes:
        buffer[used] = byte
        used += 1
    buffer[used] = '/'
    used += 1
    for byte in module.bytes:
        buffer[used] = '/' if byte == '.' else byte
        used += 1
    if definition.is_development((str)buffer[..<used]): return true
    for suffix in [".lucb", ".luc"]:
        for i in 0..<suffix.length: buffer[used + i] = suffix.bytes[i]
        if definition.is_development((str)buffer[..<used + suffix.length]): return true
    return false

## Whether `path` is `prefix` or lies inside it.
func under(path: str, prefix: str) -> bool:
    if not strings.starts_with(path, prefix): return false
    return path.length == prefix.length or path.bytes[prefix.length] == '/'

## A dependency checkout may sit outside the package, so `..` is allowed here.
func local_path_valid(value: str) -> bool:
    if value.length == 0 or value.length > 1024: return false
    for byte in value.bytes:
        if byte < 0x20 or byte == 0x7f or byte == '\\': return false
    return true

func requirement_valid(value: str) -> bool:
    let exact = (str)value.bytes[1..] if value.length > 1 and value.bytes[0] == '^' else value
    _ = parse(exact) catch: return false
    return true

## An SPDX license expression: identifiers (`MIT`, `Apache-2.0`, `GPL-2.0+`,
## `LicenseRef-x`, `DocumentRef-a:LicenseRef-b`) joined by `AND`, `OR` and `WITH`, with
## parentheses, on one line. Which identifiers SPDX lists is not checked.
func license_valid(value: str) -> bool:
    if value.length == 0 or not line_valid(value): return false
    var open: usize
    # whether the next word is an identifier (true) or an operator (false)
    var operand = true
    var i: usize
    while i < value.length:
        let byte = value.bytes[i]
        if byte == ' ':
            i += 1
        elif byte == '(':
            if not operand: return false
            open += 1
            i += 1
        elif byte == ')':
            if operand or open == 0: return false
            open -= 1
            i += 1
        else:
            var end = i
            while end < value.length and value.bytes[end] != ' ' and value.bytes[end] != '(' and value.bytes[end] != ')':
                end += 1
            let word = (str)value.bytes[i..<end]
            if word == "AND" or word == "OR" or word == "WITH":
                if operand: return false
            elif not operand or not license_identifier(word):
                return false
            operand = not operand
            i = end
    return not operand and open == 0

func license_identifier(word: str) -> bool:
    for i in 0..<word.length:
        let byte = word.bytes[i]
        let plain = (byte >= 'a' and byte <= 'z') or (byte >= 'A' and byte <= 'Z') or (byte >= '0' and byte <= '9') or byte == '.' or byte == '-' or byte == ':'
        # `+` means "or later" and ends an identifier
        if not plain and not (byte == '+' and i == word.length - 1 and i > 0): return false
    return true

func line_valid(value: str) -> bool:
    if value.length > 256: return false
    for byte in value.bytes:
        if byte < 0x20 or byte == 0x7f: return false
    return true

## Copies decoded text into the arena owned by the Definition.
struct Arena:
    var bytes: u8[]
    var used: usize

    func copy(text: str) -> str!:
        if self.used + text.length > self.bytes.length: error(invalid, "package definition exceeds its bound")
        let start = self.used
        for i in 0..<text.length: self.bytes[start + i] = text.bytes[i]
        self.used += text.length
        return (str)self.bytes[start..<self.used]

    func text(doc: prism.Document*, path: str, name: str) -> str!:
        let value = try doc.get(path, name)
        defer value.release()
        if value.value().dtype() != prism.DType.string or value.value().rank() != 0:
            error(invalid, "package property must be a single str")
        return try self.copy(try value.value().text_at())

    func list(doc: prism.Document*, path: str, name: str, output: str[], count: usize*) -> !:
        let value = try doc.get(path, name)
        defer value.release()
        if value.value().dtype() != prism.DType.string or value.value().rank() != 1:
            error(invalid, "package property must be a str array")
        if *count + value.value().count() > output.length: error(invalid, "package str array is too long")
        for i in 0..<value.value().count():
            output[*count + i] = try self.copy(try value.value().text_at(i))
        *count += value.value().count()

func sort(values: Requirement[], count: usize):
    for i in 1..<count:
        let current = values[i]
        var at = i
        while at > 0 and values[at - 1].name > current.name:
            values[at] = values[at - 1]
            at -= 1
        values[at] = current

## Where the last refused package.prisma of this thread went wrong, and why.
local var diagnosis: u8[320]

## Prism's refusal of package.prisma, as `package.prisma:line:column: why`. The text
## lives in this thread's `diagnosis` until the next refusal.
func located(result: prism.DecodeResult*) -> str!:
    let why = result.error_message()
    let shown = (str)why.bytes[..<why.length if why.length < 240 else 240]
    return try strings.format(diagnosis, f"package.prisma:{result.line()}:{result.column()}: {shown}")

pub func decode(text: const u8[]) -> Definition!:
    if text.length == 0 or text.length > max_size: error(invalid, "package definition size outside bounds")
    let diagnosed = try prism.decode_diagnosed(text, prism.Codec.prisma)
    defer diagnosed.release()
    if not diagnosed.value().ok(): error(invalid, try located(diagnosed.value()))
    let reference = try diagnosed.value().document()
    defer reference.release()
    let doc = reference.value()
    if doc.connection_count() != 0: error(invalid, "package.prisma may not contain connections")

    var result: Definition
    errdefer result.close()
    result.storage = try new u8[text.length] --- in memory.heap
    var arena = Arena(bytes = result.storage)
    var found: Requirement[128]
    var declared = try new Task[max_tasks] --- in memory.heap
    defer free(declared) in memory.heap
    var root = ""
    var seen_application = false

    for index in 0..<doc.element_count():
        let path = try doc.path_at(index)
        let kind = try doc.type_at(path)
        var depth: usize
        var last: usize
        for i in 0..<path.length:
            if path.bytes[i] == '/':
                depth += 1
                last = i
        let name = (str)path.bytes[last + 1..]
        if depth == 1:
            if kind != "package" or root.length > 0: error(invalid, "package.prisma needs exactly one root package element")
            if not name_valid(name): error(invalid, "invalid package name")
            root = path
            for i in 0..<try doc.property_count(path):
                let key = try doc.property_name(path, i)
                if key == "development":
                    try arena.list(doc, path, key, result.development[0..], &result.development_count)
                    continue
                if key == "public":
                    try arena.list(doc, path, key, result.public[0..], &result.public_count)
                    continue
                let value = try arena.text(doc, path, key)
                if key == "owner": result.owner = value
                elif key == "version": result.version = value
                elif key == "kind": result.kind = value
                elif key == "language": result.language = value
                elif key == "source": result.source = value
                elif key == "description": result.description = value
                elif key == "license": result.license = value
                elif key == "readme": result.readme = value
                elif key == "entry": result.entry = value
                elif key == "install": result.install = value
                else: error(invalid, "unknown package property")
            result.name = try arena.copy(name)
        elif depth == 2 and kind == "dependency":
            if result.dependency_count >= max_dependencies: error(invalid, "too many package dependencies")
            if not name_valid(name): error(invalid, "invalid dependency name")
            var entry = Requirement(name = try arena.copy(name))
            for i in 0..<try doc.property_count(path):
                let key = try doc.property_name(path, i)
                let value = try arena.text(doc, path, key)
                if key == "owner": entry.owner = value
                elif key == "version": entry.version = value
                elif key == "path": entry.path = value
                else: error(invalid, "unknown dependency property")
            if not name_valid(entry.owner): error(invalid, "dependency owner is missing or invalid")
            # no version asks for the newest release; luc.lock records the one chosen
            if entry.version.length > 0 and not requirement_valid(entry.version): error(invalid, "dependency version is invalid")
            if entry.path.length > 0 and not local_path_valid(entry.path): error(invalid, "invalid dependency path")
            for i in 0..<result.dependency_count:
                if found[i].name == entry.name: error(invalid, "duplicate package dependency")
            found[result.dependency_count] = entry
            result.dependency_count += 1
        elif depth == 2 and kind == "application":
            if seen_application: error(invalid, "a package declares at most one application")
            seen_application = true
            for i in 0..<try doc.property_count(path):
                let key = try doc.property_name(path, i)
                if key == "name": result.application.name = try arena.text(doc, path, key)
                elif key == "identifier": result.application.identifier = try arena.text(doc, path, key)
                elif key == "icon": result.application.icon = try arena.text(doc, path, key)
                else: error(invalid, "unknown application property")
            if not display_valid(result.application.name): error(invalid, "application name is missing or not a plain display name")
            if not identifier_valid(result.application.identifier): error(invalid, "application identifier must be reverse-DNS, such as com.example.app")
            if result.application.icon.length > 0 and not path_valid(result.application.icon): error(invalid, "invalid application icon path")
        elif depth == 2 and kind == "native":
            # one element per target it applies to, their inputs taken together here
            if not native_element_valid(name): error(invalid, "a native element is named inputs, all, an operating system or a target")
            for i in 0..<try doc.property_count(path):
                let key = try doc.property_name(path, i)
                if key == "sources": try arena.list(doc, path, key, result.native.sources[0..], &result.native.source_count)
                elif key == "link_search": try arena.list(doc, path, key, result.native.link_search[0..], &result.native.link_search_count)
                elif key == "libraries": try arena.list(doc, path, key, result.native.libraries[0..], &result.native.library_count)
                elif key == "frameworks": try arena.list(doc, path, key, result.native.frameworks[0..], &result.native.framework_count)
                elif key == "pkg_config": try arena.list(doc, path, key, result.native.pkg_config[0..], &result.native.pkg_config_count)
                else: error(invalid, "unknown native property")
            for i in 0..<result.native.source_count:
                if not path_valid(result.native.sources[i]): error(invalid, "invalid native source path")
            for i in 0..<result.native.link_search_count:
                if not path_valid(result.native.link_search[i]): error(invalid, "invalid native link search path")
            for i in 0..<result.native.library_count:
                if not token_valid(result.native.libraries[i]): error(invalid, "invalid native library name")
            for i in 0..<result.native.framework_count:
                if not token_valid(result.native.frameworks[i]): error(invalid, "invalid native framework name")
            for i in 0..<result.native.pkg_config_count:
                if not token_valid(result.native.pkg_config[i]): error(invalid, "invalid pkg-config name")
        elif depth == 2 and kind == "export":
            error(invalid, "a package names its public modules in `str[] public = [...]`; `def export` is gone")
        elif depth == 2 and kind == "task":
            if result.task_count >= max_tasks: error(invalid, "too many package tasks")
            if not name_valid(name): error(invalid, "invalid task name")
            var entry = Task(name = try arena.copy(name))
            for i in 0..<try doc.property_count(path):
                let key = try doc.property_name(path, i)
                if key == "cmd": entry.command = try arena.text(doc, path, key)
                elif key == "description": entry.description = try arena.text(doc, path, key)
                elif key == "depends": try arena.list(doc, path, key, entry.depends[0..], &entry.depend_count)
                else: error(invalid, "unknown task property")
            if entry.command.length == 0 and entry.depend_count == 0: error(invalid, "task needs a cmd or depends")
            if not line_valid(entry.description): error(invalid, "task description must be one line")
            declared[result.task_count] = entry
            result.task_count += 1
        else:
            error(invalid, "unknown element in package.prisma")

    if root.length == 0: error(invalid, "package.prisma needs exactly one root package element")
    if not name_valid(result.owner): error(invalid, "package owner is missing or invalid")
    _ = parse(result.version) catch: error(invalid, "package version is missing or invalid")
    if result.language != "luce" and result.language != "luce-base": error(invalid, "package language must be luce or luce-base")
    if result.source.length == 0: result.source = "src"
    if not path_valid(result.source): error(invalid, "invalid package source path")
    if not line_valid(result.description): error(invalid, "package description must be one line of at most 256 bytes")
    if result.license.length > 0 and not license_valid(result.license): error(invalid, "package license must be an SPDX expression, such as MIT OR Apache-2.0")
    if result.readme.length > 0 and not path_valid(result.readme): error(invalid, "invalid package readme path")
    if result.entry.length > 0 and not path_valid(result.entry): error(invalid, "invalid package entry path")
    # The kind decides what else the definition must and must not say.
    if result.kind == "package":
        if result.entry.length > 0 or result.application.name.length > 0 or result.install.length > 0:
            error(invalid, "a package is a library: it has no entry, application or install script")
    elif result.kind == "tool":
        if result.entry.length == 0: error(invalid, "a tool needs an entry")
        if result.application.name.length > 0: error(invalid, "a tool runs in a terminal; declare kind application for a desktop program")
    elif result.kind == "application":
        if result.entry.length == 0 or result.application.name.length == 0:
            error(invalid, "an application needs an entry and an application element with its name and identifier")
    else:
        error(invalid, "kind must be package, application or tool")
    if result.install.length > 0:
        if result.entry.length == 0: error(invalid, "only an application may declare an install script")
        if not path_valid(result.install): error(invalid, "invalid package install path")
    # What an install builds must not be development material, or it would be left out.
    for i in 0..<result.development_count:
        if not path_valid(result.development[i]): error(invalid, "invalid development path")
    if result.entry.length > 0 and result.is_development(result.entry):
        error(invalid, "the entry lies in a development path, which luc install leaves out")
    if result.install.length > 0 and result.is_development(result.install):
        error(invalid, "the install script lies in a development path, which luc install leaves out")
    if result.is_development(result.source):
        error(invalid, "the source root lies in a development path, which luc install leaves out")
    for i in 0..<result.public_count:
        if not module_valid(result.public[i]): error(invalid, "a public module is a dotted path under the source root")
        if public_development(&result, result.public[i]):
            error(invalid, "a public module lies in a development path, which luc install leaves out")

    sort(found, result.dependency_count)
    if result.dependency_count > 0:
        result.dependencies = try new Requirement[result.dependency_count] --- in memory.heap
        for i in 0..<result.dependency_count: result.dependencies[i] = found[i]
    if result.task_count > 0:
        result.tasks = try new Task[result.task_count] --- in memory.heap
        for i in 0..<result.task_count: result.tasks[i] = declared[i]
    return result