coc-tinymist 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 SeniorMars
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# coc-tinymist
+
+Typst language support for coc.nvim powered by [Tinymist](https://github.com/Myriad-Dreamin/tinymist).
+
+## Install
+
+```vim
+:CocInstall coc-tinymist
+```
+
+Open a `typst` buffer. If `tinymist` is not available from `tinymist.serverPath`, the extension's managed storage, or `$PATH`, coc-tinymist can download the latest Tinymist release from GitHub.
+
+## Configuration
+
+Common settings in `coc-settings.json`:
+
+```jsonc
+{
+  "semanticTokens.enable": false,
+  "[typst]": {
+    "semanticTokens.enable": true
+  },
+  "tinymist.enable": true,
+  "tinymist.serverPath": null,
+  "tinymist.serverArgs": ["lsp"],
+  "tinymist.updates.mode": "prompt",
+  "tinymist.rootPath": null,
+  "tinymist.outputPath": "",
+  "tinymist.exportTarget": "paged",
+  "tinymist.formatterMode": "typstyle",
+  "tinymist.formatterPrintWidth": 120,
+  "tinymist.fontPaths": null,
+  "tinymist.systemFonts": true,
+  "tinymist.exportPdf": "never",
+  "tinymist.exportOnSave": [],
+  "tinymist.exportOnType": [],
+  "tinymist.exportOnIdle": [],
+  "tinymist.exportOpenAfterSave": false,
+  "tinymist.exportOutputDirectory": null,
+  "tinymist.exportShowIn": "message",
+  "tinymist.lint.enabled": false,
+  "tinymist.lint.when": "onSave",
+  "tinymist.semanticTokens": "enable",
+  "tinymist.inlayHints.packageVersionStatus": true,
+  "tinymist.cocFallbackDocumentHighlight": true,
+  "tinymist.cocFallbackInlayHints": false,
+  "tinymist.fallback.maxFileBytes": 524288,
+  "tinymist.fallback.maxHighlights": 500,
+  "tinymist.fallback.maxInlayHints": 500,
+  "tinymist.onEnterEvent": false,
+  "tinymist.compileStatus": "disable",
+  "tinymist.statusBarFormat": "{compileStatusIcon} {wordCount} [{fileName}]",
+  "tinymist.mainFile.store": "workspaceState",
+  "tinymist.tasks.workspaceFileLimit": 100,
+  "tinymist.tasks.workspaceTimeoutMs": 120000,
+  "tinymist.tasks.fileTimeoutMs": 30000,
+  "tinymist.tasks.maxOutputBytes": 1048576,
+  "tinymist.tasks.progressIntervalMs": 2000,
+  "tinymist.commands.exportTimeoutMs": 120000,
+  "tinymist.commands.profileTimeoutMs": 120000,
+  "tinymist.commands.templateTimeoutMs": 60000,
+  "tinymist.markdown.isTrusted": false,
+  "tinymist.markdown.supportHtml": false
+}
+```
+
+Set `"tinymist.updates.mode": "never"` to disable managed downloads and only use a configured or system Tinymist executable. Use `"manual"` to install/update only when running `tinymist.install` or `tinymist.update`, `"prompt"` to ask first, or `"auto"` to download without prompting.
+
+Managed Tinymist downloads currently support macOS arm64/x64, Linux x64 GNU/musl, Linux arm64 GNU, Linux armv7 GNU, and Windows x64/arm64. On other platforms, install Tinymist yourself and point `tinymist.serverPath` at that executable.
+
+Set `"tinymist.compileStatus": "enable"` to opt into the status bar item for compile state, word count, and current file. Set `"tinymist.statusBarFormat": ""` to keep notifications enabled while hiding the item.
+
+Set `"semanticTokens.enable": true` under the `[typst]` language override to let Coc render semantic token highlights for Typst without enabling them globally. `tinymist.semanticTokens` controls whether Tinymist provides semantic token data to Coc; it does not override Coc's semantic highlighting gate. Use `:CocCommand semanticTokens.checkCurrent` to inspect whether Coc is applying semantic highlights in the current buffer, and `:CocCommand semanticTokens.refreshCurrent` after changing highlight groups.
+
+Set `"tinymist.onEnterEvent": true` to opt into coc-tinymist's insert-mode Enter handler for comment and equation continuation. Document-highlight fallback only runs when Tinymist returns no highlights. Inlay fallback is off by default because it is additive to Tinymist's own hints; enable it with `tinymist.cocFallbackInlayHints`. Fallback parsing is cached per document version and skipped above `tinymist.fallback.maxFileBytes`; per-request result caps are controlled by `tinymist.fallback.maxHighlights` and `tinymist.fallback.maxInlayHints`.
+
+The schema also includes Tinymist project resolution, syntax-only mode, formatter indent/prose wrapping, `typstExtraArgs`, and `typingContinueCommentsOnNewline`. VS Code-only settings such as webview preview, drag/drop, and paste handling are intentionally omitted.
+
+Markdown returned by Tinymist is untrusted and raw HTML rendering is disabled by default. Set `"tinymist.markdown.isTrusted": true` only if you want command links in server-provided Markdown to be executable. Set `"tinymist.markdown.supportHtml": true` only if you trust documentation generated from the current project and installed packages.
+
+`tinymist.exportTo` now attempts to pass a literal `outputPath` option through Tinymist's `workspace/executeCommand` export call. If the server ignores or rejects that option, coc-tinymist finalizes the result itself. Path artifacts are copied through temporary sibling files and atomically renamed into place where the platform allows it; inline `data` artifacts are written the same way. If a multi-file export targets `slides.png`, coc-tinymist writes `slides.png`, `slides-2.png`, `slides-3.png`, and so on. If the target has no extension, it is treated as a directory and Tinymist-generated basenames are preserved when available.
+
+Export target paths may use `{name}`, `{ext}`, `{kind}`, `{index}`, `{page}`, `{hash}`, and `{relativeDir}` placeholders. For example, `build/{relativeDir}/{name}-{hash}-{page}.{ext}` keeps artifacts from different source folders from colliding.
+
+For extension-side automatic exports, set `tinymist.exportOnSave`, `tinymist.exportOnType`, or `tinymist.exportOnIdle` to `true` for PDF, a single format such as `"Pdf"`, or an array such as `["Pdf", "Html"]`. Use `tinymist.exportOutputDirectory` to relocate automatic export artifacts, `tinymist.exportOpenAfterSave` to open save-triggered artifacts, and `tinymist.exportShowIn` to choose `none`, `message`, `output`, `quickfix`, or `open`.
+
+Automatic exports are serialized per source file, output format, and target path. If another save/type/idle event arrives while an export is running, coc-tinymist reruns once after the active export finishes so the final document state is not dropped.
+
+Pinned main documents are stored per workspace by default with `tinymist.mainFile.store: "workspaceState"` and restored after server startup/restart. Set it to `"none"` for in-memory-only pinning. `tinymist.detectMain` ranks obvious candidates such as `main.typ`, `thesis.typ`, `paper.typ`, Typst manifest entry points, and files with document setup rules.
+
+File-sensitive commands such as export, test, profile, template insertion, and pin-current-main require a file-backed Typst buffer. Coverage task results only attach `target/coverage.json` when the report was written during the current coverage run.
+
+CLI-backed tasks respect `tinymist.tasks.workspaceFileLimit`, `tinymist.tasks.workspaceTimeoutMs`, `tinymist.tasks.fileTimeoutMs`, `tinymist.tasks.maxOutputBytes`, and `tinymist.tasks.progressIntervalMs`. Use `tinymist.taskCancelRunning` to abort running CLI-backed task subprocesses. LSP command-backed export/profile/template actions use `tinymist.commands.exportTimeoutMs`, `tinymist.commands.profileTimeoutMs`, and `tinymist.commands.templateTimeoutMs`.
+
+Server source commands such as `tinymist.useManagedServer`, `tinymist.useSystemServer`, and `tinymist.useCustomServer` prompt for the configuration scope before writing `tinymist.serverPath`: Global, Workspace, or Workspace Folder.
+
+## Commands
+
+Use these with `:CocCommand`:
+
+| Command | Description |
+| --- | --- |
+| `tinymist.restartServer` | Restart the Tinymist language server |
+| `tinymist.install` | Install Tinymist from the latest GitHub release |
+| `tinymist.update` | Check for and install the latest managed Tinymist release |
+| `tinymist.serverVersion` | Show the active Tinymist version |
+| `tinymist.doctor` | Open a diagnostic report for server, config, workspace, and status |
+| `tinymist.doctorCopyIssueTemplate` | Copy a sanitized markdown issue report to the clipboard |
+| `tinymist.doctorSaveReport` | Save a sanitized markdown doctor report to a temp file |
+| `tinymist.checkDuplicateServer` | Check for a duplicate manual `languageserver.tinymist` config |
+| `tinymist.openConfig` | Open the user `coc-settings.json` file |
+| `tinymist.openWorkspaceConfig` | Open or create `.vim/coc-settings.json` under the current workspace |
+| `tinymist.explainConfig` | Show resolved Tinymist server config, client flags, and Coc-only settings |
+| `tinymist.migrateConfig` | Copy legacy Tinymist config keys to current coc-tinymist keys |
+| `tinymist.resetManagedServer` | Remove the managed Tinymist binary and release metadata |
+| `tinymist.useSystemServer` | Point `tinymist.serverPath` at the Tinymist executable found on `$PATH` |
+| `tinymist.useManagedServer` | Clear `tinymist.serverPath` and use the managed Tinymist binary |
+| `tinymist.useCustomServer` | Prompt for a custom Tinymist executable path |
+| `tinymist.actions` | Pick from grouped Tinymist actions for export, tasks, main files, templates, diagnostics, server, and config |
+| `tinymist.showStatus` | Show the latest Tinymist status details |
+| `tinymist.showLog` | Show the Tinymist language server log |
+| `tinymist.showTemplateGallery` | Open `CocList tinymistTemplates` |
+| `tinymist.refreshTemplates` | Refresh the Typst Universe template cache |
+| `tinymist.initTemplate` | Initialize a Typst project from a template package spec |
+| `tinymist.initTemplateVersion` | Pick a template and initialize a specific version |
+| `tinymist.initTemplateInPlace` | Insert a template entry file at the cursor |
+| `tinymist.export` | Pick an export format for the current Typst document |
+| `tinymist.exportTo` | Pick an export format and relocate the generated artifact to an output path |
+| `tinymist.exportAndOpen` | Pick an export format and open the generated artifact |
+| `tinymist.exportRepeat` | Repeat the last Tinymist export with the same format and options |
+| `tinymist.exportCopyPath` | Copy the first path from the last Tinymist export result |
+| `tinymist.exportCurrentPdf` | Export the current Typst document as PDF |
+| `tinymist.exportCurrentSvg` | Export the current Typst document as SVG |
+| `tinymist.exportCurrentPng` | Export the current Typst document as PNG |
+| `tinymist.exportCurrentHtml` | Export the current Typst document as HTML |
+| `tinymist.exportCurrentMarkdown` | Export the current Typst document as Markdown |
+| `tinymist.exportCurrentText` | Export the current Typst document as text |
+| `tinymist.profileCurrentFile` | Write current document trace data to a temp JSON file and the Tinymist Commands output channel |
+| `tinymist.pinCurrentAsMain` | Pin the current Typst document as main |
+| `tinymist.selectMain` | Pick a Typst file to pin as main |
+| `tinymist.showMain` | Show the currently pinned main file tracked by coc-tinymist |
+| `tinymist.clearMain` | Clear the pinned Tinymist main file |
+| `tinymist.detectMain` | Detect likely main Typst files and pin the selected candidate |
+| `tinymist.testCurrent` | Run `tinymist test` for the current file and record the task result |
+| `tinymist.testWorkspace` | Run `tinymist test` for Typst files under the workspace, capped at 100 files |
+| `tinymist.coverageCurrent` | Run `tinymist test --coverage` for the current file and record the task result plus `target/coverage.json` when produced |
+| `tinymist.tasks` | Open the Tinymist task history list |
+| `tinymist.taskRerunLast` | Rerun the most recent rerunnable Tinymist task |
+| `tinymist.taskOpenLastOutput` | Open the output view for the most recent Tinymist task |
+| `tinymist.taskClearHistory` | Clear structured Tinymist task history |
+| `tinymist.taskCancelRunning` | Cancel running CLI-backed Tinymist tasks |
+| `tinymist.lintToLocationList` | Populate the location list from current Typst/Tinymist diagnostics |
+| `tinymist.coverageOpenReport` | Open the latest Tinymist coverage report artifact |
+| `tinymist.onEnter` | Run Tinymist's experimental on-enter edit for comments/equations |
+
+## Lists
+
+Use these with `:CocList`:
+
+| List | Description |
+| --- | --- |
+| `tinymistTemplates` | Browse Typst Universe templates and initialize or insert one |
+| `tinymistTasks` | Inspect task history, rerun tasks, open artifacts, copy commands, and populate the location list |
+| `tinymistExports` | Inspect export history, open artifacts, copy paths, repeat exports, or relocate an export |
+
+The template list fetches `https://packages.typst.org/preview/index.json` and filters packages with template metadata. The latest successful gallery response is cached in Coc global state for offline browsing. If the network is unavailable and no cache exists, `tinymist.initTemplate` and `tinymist.initTemplateInPlace` still accept a manually entered package spec. The list actions include `init`, `in-place`, `details`, `version`, and `refresh`.
+
+Task runs are stored in memory as structured records with command, target, timestamps, status, raw result, message, and artifact paths. The task list actions are `open-output`, `rerun`, `copy-command`, `clear`, `open-artifact`, and `populate-location-list`; long CLI-backed tasks can be cancelled with `tinymist.taskCancelRunning`. `tinymist.lintToLocationList` uses the current Coc diagnostics because Tinymist lint feedback is delivered through LSP diagnostics rather than a separate one-shot command. The export list actions are `open`, `reveal/copy-path`, `repeat`, and `export-to`.
+
+## Troubleshooting
+
+Run `:CocCommand tinymist.doctor` first. For issue reports, prefer `:CocCommand tinymist.doctorCopyIssueTemplate`; it redacts proxy credentials, token-like environment keys and values, and configured paths where possible.
+
+If `tinymist.serverPath` is wrong or stale, coc-tinymist keeps the extension loaded and reports the invalid path. Run `:CocCommand tinymist.useManagedServer`, `:CocCommand tinymist.useSystemServer`, or `:CocCommand tinymist.useCustomServer` to repair the server source, then run `:CocCommand tinymist.restartServer`.
+
+If managed install says your platform is unsupported, install Tinymist manually and set `tinymist.serverPath`. Managed downloads currently cover the platforms listed above, not every target that Tinymist may publish.
+
+If you are behind a corporate proxy, configure Coc's `http.proxy` and `http.proxyStrictSSL` settings. Managed release metadata, checksums, binary downloads, and the Typst Universe template gallery all use those proxy settings.
+
+If Tinymist appears to start twice or diagnostics/actions duplicate, run `:CocCommand tinymist.checkDuplicateServer` and remove any manual `languageserver.tinymist` entry from `coc-settings.json`.
+
+If commands say Tinymist is not running, run `:CocCommand tinymist.showLog`, `:CocCommand tinymist.showStatus`, and `:CocCommand tinymist.doctor`. Then try `:CocCommand tinymist.restartServer`.
+
+If an export succeeds but reports no artifact path, open the `Tinymist Commands` output channel. Some server responses may return inline data or no path; `tinymist.exportTo` is the most predictable command when you need a specific artifact path.
+
+If `tinymist.coverageOpenReport` finds no report, rerun `:CocCommand tinymist.coverageCurrent`. coc-tinymist intentionally ignores stale `target/coverage.json` files that were not produced by the current coverage run.
+
+The on-enter keymap is disabled by default. Set `"tinymist.onEnterEvent": true` to enable it.
+
+## Development QA
+
+Run these before publishing:
+
+```sh
+npm run typecheck
+npm test
+npm run qa:commands
+npm run qa:coc
+npm run qa:lsp
+npm pack --dry-run
+```
+
+`npm test` builds the extension and runs unit tests, lifecycle integration tests, mocked Coc-host tests, downloader/archive tests, export tests, activation tests, and a fake Tinymist LSP smoke test. `npm run qa:coc` runs a headless Neovim/Coc smoke test that loads this extension, checks contributed commands/lists, and runs core commands. `npm run qa:lsp` runs the real Tinymist LSP smoke test when `tinymist` is available on `$PATH` or `TINYMIST_BIN` is set.
+
+For a manual release smoke, open `fixtures/sample.typ` in Neovim with Coc enabled and verify:
+
+- `:CocCommand tinymist.serverVersion`
+- `:CocCommand tinymist.doctor`
+- `:CocCommand tinymist.exportCurrentPdf`
+- `:CocCommand tinymist.showStatus`
+- `:CocList tinymistExports`
+- `:CocList tinymistTasks`
+- `:CocList tinymistTemplates`
+- standard Coc LSP actions such as hover, definition, references, rename, formatting, code actions, diagnostics, document symbols, and semantic tokens
+
+## License
+
+MIT
+
+---
+
+This extension is built with [create-coc-extension](https://github.com/fannheyward/create-coc-extension) and follows patterns from [coc-texlab](https://github.com/fannheyward/coc-texlab) and [coc-rust-analyzer](https://github.com/fannheyward/coc-rust-analyzer).