openidea/wit/workspace.wit

package openidea:plugin@1.8.0;

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

    /// Text search options. Include/exclude are project-relative globs, as in Find in Files.
    record text-query {
        pattern: string,
        regex: bool,
        case-sensitive: bool,
        whole-word: bool,
        %include: list<string>,
        exclude: list<string>,
    }
    /// A match with zero-based lines and UTF-16 columns, and its displayed line.
    record text-match { location: location, line: string }
    /// Bounded search results; limit-hit says there may be more matches.
    record text-search { matches: list<text-match>, limit-hit: bool }

    /// A project open in the IDE.
    resource project {
        /// Absolute path of the project root. Requires `project.read`.
        root: func() -> result<string, error>;
        /// Find in Files with unsaved documents and project excludes. Requires project.read.
        /// Cancellable, at most 10,000 matches. Zero limit returns no matches.
        /// Line previews are capped at 4096 UTF-8 bytes, results at 4 MiB (limit-hit).
        search-text: func(query: text-query, limit: u32) -> result<text-search, 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>;
        /// Reads the bytes of a file inside the project (absolute, or
        /// relative to the root) — images, archives, fonts — at most 16 MiB,
        /// as `fs.read-bytes` allows; paths leaving the root are refused and
        /// a missing path is `not-found`. The file on disk: unsaved editor
        /// contents don't apply. Requires `project.read`.
        read-bytes: func(path: string) -> result<list<u8>, 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>;
        /// 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 the 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`.
        symbols: func(query: string, limit: u32) -> result<list<symbol-info>, error>;
    }

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

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

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

    /// An editor in the invoking window.
    record open-editor { path: string, language: string, dirty: bool, active: bool }
    /// Only from commands/events of a window. Requires editor.read.
    open-editors: func() -> result<list<open-editor>, error>;
    /// Open a project file (project.read) or a file in plugin-dir, selecting a range.
    /// Only from commands/events of a window. Paths follow views.open-location.
    open: func(path: string, selection: option<range>) -> result<_, error>;

    /// Current version and text of an open project document. Unlike
    /// `text-editor.document`, this is available to background events.
    /// The path is project-relative and requires `project.read` and
    /// `editor.read`.
    document-at: func(project: borrow<project>, path: string) -> result<document, error>;

    /// Applies versioned edits to an open project document from a background
    /// event. The path is project-relative and requires `project.read` and
    /// `editor.write`. The host refuses VCS/IDE control directories and every
    /// symlink, junction or reparse-point component before it finds the open
    /// document. Stale versions are rejected without changing text.
    /// These background edits are non-undoable and are not re-emitted as
    /// `document-changed` events.
    apply-edits-at: func(project: borrow<project>, path: string, version: u64, edits: list<text-edit>) -> result<u64, error>;

    /// A file open in an editor.
    resource text-editor {
        /// Absolute path of the file.
        path: func() -> string;
        /// Replace selections in this window's editor. No capability; commands/events only.
        set-selections: func(selections: list<range>) -> result<_, error>;
        /// Scroll a range into view in this window's editor. No capability; commands/events only.
        reveal: func(range: range) -> result<_, error>;
        /// 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,
    }

    /// A commit in repository history; date is Unix seconds.
    record commit-info {
        id: string, short-id: string, author: string, author-email: string,
        date: s64, subject: string, body: string, parents: list<string>,
    }
    /// One zero-based document line's attribution; date is Unix seconds.
    record blame-line { line: u32, commit: string, author: string, date: s64, summary: string }
    /// Newest commits first, at most 1000. Trusted projects only; requires vcs.read.
    log: func(project: borrow<project>, path: option<string>, limit: u32) -> result<list<commit-info>, error>;
    /// Includes unsaved text, with changed lines attributed to uncommitted changes.
    /// Trusted projects only; requires vcs.read. Paths must be inside the project.
    blame: func(project: borrow<project>, path: string) -> result<list<blame-line>, error>;
    /// Working tree versus HEAD or against. None outside a repository. Disk text only.
    /// Fails above 4 MiB. Trusted projects only; requires vcs.read.
    diff: func(project: borrow<project>, path: option<string>, against: option<string>) -> result<option<string>, error>;

    /// `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>;
}