openidea/wit/workspace.wit

package openidea:[email protected];

interface workspace {
    use types.{error, location};

    /// Requests File > Open in this command/event's window (or a new window),
    /// including the usual project trust prompt. Needs no capability.
    /// `path` is an absolute directory path on the UI machine.
    open-project: func(path: string, new-window: bool) -> result<_, error>;

    /// The open project containing an absolute document path, or `none`.
    /// Reading the returned project still requires `project.read`.
    project-of: func(path: string) -> option<project>;

    /// What a path inside a project is.
    enum file-kind {
        file,
        directory,
        symlink,
        other,
    }

    /// Metadata of a path inside a project, as `stat` reports it.
    record file-stat {
        kind: file-kind,
        /// Bytes, for a file.
        size: u64,
        /// Seconds since the Unix epoch; `none` when the file system does
        /// not track it.
        modified: option<u64>,
    }

    /// A symbol in the host's current in-memory project index (new in 1.3).
    record symbol-info {
        name: string,
        /// Host symbol kind, in camelCase (`class`, `method`, `enumMember`, …).
        kind: string,
        container: option<string>,
        location: location,
    }

    /// Fuzzy symbol search (CamelHump and container-qualified queries) over the
    /// current index only; never starts or waits for a language server. Results
    /// may be incomplete while indexing and ranges reflect the indexed text,
    /// not necessarily unsaved edits. Empty queries return no symbols. Queries
    /// over 256 UTF-8 bytes are invalid; limit is capped at 1000 (zero is empty).
    /// Only paths readable under this project's root are returned; external
    /// content roots are excluded. Cancellation returns cancelled; exceeding the
    /// current call's deadline fails. A closed project is not-found.
    /// Requires `project.read`. New in 1.3.
    symbols: func(project: borrow<project>, query: string, limit: u32) -> result<list<symbol-info>, error>;

    /// A project open in the IDE.
    resource project {
        /// Absolute path of the project root. Requires `project.read`.
        root: func() -> result<string, error>;
        /// Reads a UTF-8 text file inside the project (absolute, or relative
        /// to the root); paths leaving the root are refused. Unsaved editor
        /// contents win over the disk. A missing path is `not-found`.
        /// Requires `project.read`.
        read-file: func(path: string) -> result<string, error>;
        /// Replaces the text of a file inside the project (absolute, or
        /// relative to the root), or creates it with missing parent
        /// directories; paths leaving the root are refused. Written in one
        /// step (a reader never sees half of it), keeping the file's encoding
        /// and BOM; a new file is UTF-8. An editor holding unsaved changes for
        /// the file makes it `invalid` (save them first). Requires
        /// `project.write`.
        write-file: func(path: string, text: string) -> result<_, error>;
        /// Whether `path` (absolute, or relative to the root) names an
        /// existing file or directory — including hidden and ignored ones,
        /// without reading any content. Paths leaving the root are refused.
        /// Requires `project.read`.
        exists: func(path: string) -> result<bool, error>;
        /// Metadata of an existing path inside the project (absolute, or
        /// relative to the root); a missing path is `not-found` and paths
        /// leaving the root are refused. Requires `project.read`.
        stat: func(path: string) -> result<file-stat, error>;
        /// Project files whose root-relative path matches `glob` (`**/*Mapper.xml`),
        /// at most `limit`, as absolute paths. Ignored and excluded files are
        /// skipped. Requires `project.read`.
        find-files: func(glob: string, limit: u32) -> result<list<string>, error>;
    }

    /// Projects open in any window. Requires `project.read`.
    projects: func() -> result<list<project>, error>;
}

interface editor {
    use types.{error, range, text-edit};

    record document {
        /// Grows with every change; edits name the version they were made for.
        version: u64,
        text: string,
    }

    /// A file open in an editor.
    resource text-editor {
        /// Absolute path of the file.
        path: func() -> string;
        /// Language id (`rust`, `solidity`, …).
        language: func() -> string;
        /// Current version and text. Requires `editor.read`.
        document: func() -> result<document, error>;
        /// Selections when the command was invoked (a cursor is an empty
        /// range). Requires `editor.read`.
        selections: func() -> result<list<range>, error>;
        /// Applies `edits` as one undoable change, only if the document is
        /// still at `version` (else `stale`, and nothing changes). Ranges are
        /// in that version and must not overlap. Returns the new version.
        /// Requires `editor.write`.
        apply-edits: func(version: u64, edits: list<text-edit>) -> result<u64, error>;
    }
}

/// Where a command or event comes from.
interface invocation {
    use workspace.{project};
    use editor.{text-editor};

    resource invocation {
        /// The window's project.
        project: func() -> option<project>;
        /// The window's focused editor.
        editor: func() -> option<text-editor>;
        /// The files and folders the command was run on (a multi-selection in
        /// a file tree, for instance), as absolute paths.
        /// Empty when it was not run on any, or when the menu was for a tab
        /// without a file (a virtual document).
        selected-paths: func() -> list<string>;
    }
}

/// Git, for the repository containing a project.
interface vcs {
    use types.{error};
    use workspace.{project};

    record repository-status {
        /// Absolute path of the working tree root.
        root: string,
        /// `none` when HEAD is detached.
        branch: option<string>,
        commit: option<string>,
        upstream: option<string>,
        ahead: u32,
        behind: u32,
        /// Merge / rebase / cherry-pick in progress.
        operation: option<string>,
        /// Files with staged or unstaged changes.
        changed-files: u32,
    }

    /// `none` when the project is not in a repository. Requires `vcs.read`.
    status: func(project: borrow<project>) -> result<option<repository-status>, error>;
    /// Configured remotes (`name`, fetch `url`), in order. Requires `vcs.read`.
    remotes: func(project: borrow<project>) -> result<list<tuple<string, string>>, error>;
    /// Fetches all remotes (pruning deleted branches). Requires `vcs.write`.
    /// Long-running: call it inside a task.
    fetch: func(project: borrow<project>) -> result<_, error>;
}