Skip to content

AGENTS.md

Latest commit

 

History

History
96 lines (72 loc) · 6.4 KB

AGENTS.md

File metadata and controls

96 lines (72 loc) · 6.4 KB
Raw

AGENTS.md

This is the tinymist language service, integrated with editor frontends and other tools to provide features like code intelligence, linting, debugging, and preview rendering for Typst projects.

Quick Start

  1. Read the nearest relevant docs before editing. Start with docs/dev-guide.md, then inspect the affected crate or editor directory.
  2. For any non-trivial behavior change, check OpenSpec first: accepted specs live in openspec/specs/ and active work lives in openspec/changes/.
  3. Keep changes scoped to the task, prefer source-of-truth files over generated outputs, and follow existing crate and feature boundaries.
  4. Before finishing, run the smallest meaningful validation for the area you touched and summarize what you verified.

Must-Follow Rules

  • Use the OpenSpec workflow for new features, behavior changes, multi-step fixes, and refactors. Small local edits can skip it when a formal change would add more overhead than value.
  • Do not hand-edit generated Markdown files. README.md, MAINTAINERS.md, crates/typlite/README.md, and many docs under editors/ are generated by node scripts/link-docs.mjs.
  • Treat tinymist.lock files and similar generated outputs as artifacts. If a change requires them to differ, regenerate them instead of patching them manually.
  • Keep warnings at zero. CI runs with RUSTFLAGS='-Dwarnings', and cargo clippy, cargo fmt, docs, and tests are part of the normal quality bar.
  • Prefer the smallest test command that covers your change, but widen validation when work spans Rust, editor tooling, generated docs, or feature flags.
  • Preserve unrelated user changes. The worktree may already be dirty.
  • Avoid editing dependency pins, version metadata, or release files unless the task actually requires it.
  • Use Conventional Commits for commit messages, for example fix(renderer-diff): keep sidebar scrollable.

OpenSpec Workflow

  • Start by reading openspec/config.yaml, the relevant accepted spec in openspec/specs/, and any matching active change under openspec/changes/.
  • If the work fits an existing active change, continue in that change instead of creating parallel artifacts.
  • Keep proposal.md, design.md, tasks.md, and spec deltas aligned with implementation when you work inside an OpenSpec change.
  • Use archived changes in openspec/changes/archive/ as prior art, not as the source of current requirements.

Repo Map

  • crates/tinymist-cli/: the tinymist binary entrypoint and top-level CLI commands.
  • crates/tinymist/: shared runtime and service logic used by system and web builds.
  • crates/tinymist-query/: analyzer engine behind most language-intelligence features. Snapshot tests are especially important here.
  • crates/tinymist-analysis/: lower-level analysis utilities and supporting logic.
  • crates/tinymist-world/ and crates/tinymist-project/: Typst world, project model, config loading, package handling, and filesystem-facing state.
  • crates/tinymist-render/, crates/typst-preview/, crates/tinymist-assets/, and tools/typst-preview-frontend/: preview and rendering pipeline, plus bundled frontend assets.
  • crates/tinymist-lint/, crates/tinymist-debug/, crates/tinymist-dap/, and crates/sync-lsp/: linting, debugging, DAP, and protocol plumbing.
  • editors/vscode/: the main editor frontend and most JavaScript and TypeScript tooling.
  • editors/: other editor integrations. Many of their docs are generated, so check the source before editing Markdown directly.
  • tests/: end-to-end coverage, command fixtures, and sample workspaces.
  • docs/: developer and user documentation. docs/dev-guide.md is the best high-level entry point.
  • scripts/: build, generation, validation, and release helpers.

Workflow

1. Clarify the task

  • Identify which crate, editor frontend, docs source, or generated asset is actually responsible for the behavior.
  • Read nearby docs and tests before changing code. For analyzer work, inspect existing fixtures and snapshots first.
  • Decide whether the task is a small local edit or needs OpenSpec artifacts.

2. Make the change

  • Fix the root cause in the primary source file whenever possible, instead of layering workarounds onto generated outputs or secondary wrappers.
  • Follow the repo's existing feature-flag structure. If you touch feature combinations, plan to run scripts/feature-testing.sh.
  • When documentation is generated, edit the underlying Typst or source docs and then regenerate with node scripts/link-docs.mjs.

3. Validate

  • Rust changes in one crate: cargo test -p <crate>
  • Broad Rust changes: cargo test --workspace -- --skip=e2e
  • Formatting: cargo fmt --check --all
  • Lints: cargo clippy --workspace --all-targets
  • Feature-flag coverage: scripts/feature-testing.sh
  • Analyzer snapshots: cargo insta test -p tinymist-query --accept
  • CLI or end-to-end behavior: ./scripts/e2e.sh
  • VS Code frontend: yarn lint and yarn test:vsc
  • Preview or localization assets: yarn build:preview and yarn build:l10n
  • Generated docs: node scripts/link-docs.mjs --check
  • Grammar changes: yarn test:grammar

4. Summarize

  • Report the behavior change in user-facing terms.
  • List the validation you ran.
  • Call out anything you could not verify locally.

Commit and PR Conventions

  • Write commit messages in Conventional Commits format, such as fix(query): handle missing labels.
  • Keep PR content limited to a list of modified features and issue operations, such as Close #123.
  • Do not include validation logs, command transcripts, or detailed execution notes in PR content.

Rust Conventions

  • Follow workspace lints in Cargo.toml. missing_docs, missing_safety_doc, and undocumented_unsafe_blocks are all watched in this repo.
  • Keep code warning-free under the workspace toolchain and CI settings.
  • Prefer targeted tests first, then widen to workspace checks if the change crosses crate boundaries or affects shared infrastructure.
  • Inspect snapshot diffs before accepting them. Snapshot churn is expected in analyzer and e2e tests, but it should always be intentional.

Docs Conventions

  • Generated files are marked at the top with Do not edit manually. Respect that marker.
  • If you change docs that are mirrored into generated Markdown, rerun node scripts/link-docs.mjs rather than editing the generated copies.
  • Keep documentation changes close to the code or feature they describe, and update OpenSpec artifacts when behavior-level guidance changes.