Skip to content

development.md

Latest commit

 

History

History
133 lines (97 loc) · 7.15 KB

development.md

File metadata and controls

133 lines (97 loc) · 7.15 KB
Raw

Development notes

Dependency choices

  • tower-lsp: primary LSP transport/server framework. It already re-exports the lsp_types surface we need, so we avoid a separate direct lsp-types dependency unless version pinning becomes necessary.
  • tokio: async runtime for stdio LSP serving, background indexing, cancellation, and future task coordination.
  • serde + serde_json: config, protocol-adjacent JSON handling, fixtures, and test payloads.
  • tracing + tracing-subscriber: structured logs for editor/LSP debugging with env-configurable filtering.
  • clap: small, standard CLI layer for binary flags like explicit stdio mode and future debug/config commands.
  • ropey: efficient text storage plus line/offset mapping for LSP ranges, edits, and diagnostics.
  • parking_lot: chosen over dashmap for near-term shared state because current architecture needs predictable locks around document/workspace state more than a concurrent map API. Revisit dashmap only if profiling shows real contention on keyed state.
  • thiserror: typed internal errors for library boundaries and subsystem-specific failures.
  • anyhow: ergonomic top-level/application error aggregation at binary and task boundaries.
  • insta: snapshot coverage for diagnostics, formatting, and protocol payloads.
  • pretty_assertions: readable structural diffs in unit/integration tests.
  • tempfile: isolated workspace/file-fixture tests without polluting the repo.
  • proptest: parser/formatter invariants and edge-case generation where example-based tests are too narrow.
  • similar: text diff support for formatter and snapshot-adjacent assertions when we want explicit diff output beyond plain equality checks.

Deferred or special cases

  • lyma remains optional and feature-gated because v1 stays parse-only by default, with upstream integration behind the local syntax facade.
  • miette remains in the crate for rich human-facing diagnostics/CLI error presentation even though it was not part of the narrower preferred set.
  • We intentionally do not add a direct dashmap dependency yet; parking_lot covers the current root-bounded workspace/document-state plan with less API commitment.

Common commands

cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test
cargo test --all-features
cargo test --test lsp_harness
cargo bench --bench parse_index
cargo doc --workspace --all-features --no-deps
cargo deny check

Use UPDATE_GOLDENS=1 cargo test --test parser_tests only when intentionally refreshing parser golden fixtures.

VS Code extension workflow

The VS Code extension lives under editors/vscode and launches the repository's local lymals binary over stdio.

One-time setup

From the repo root:

cargo build

From editors/vscode:

npm install
npm run compile

Use npm run watch instead of repeated npm run compile during active extension work.

Launch and verify in under 10 minutes

  1. Open editors/vscode in VS Code.
  2. Set lymalsExtension.server.path to the local debug binary:
    • Windows: ../../target/debug/lymals.exe
    • macOS/Linux: ../../target/debug/lymals
    • If the binary lives under a path with spaces, enter the raw path value without extra quoting because the extension spawns it directly with command + argv (for example C:\Program Files\Lymals\lymals.exe or /opt/my apps/lymals).
  3. Press F5 to start the Extension Development Host.
  4. In the new window, open a sample .lyma file such as ../../tests/fixtures/diagnostics/syntax_error.lyma.
  5. Confirm Lyma diagnostics appear in Problems.
  6. Open Output > Lymals to inspect extension logs, startup messages, and optional protocol trace output.

Debugging tips

  • lymalsExtension.server.logFile adds --log-file to the server command.
  • Example log-file paths:
    • Windows: C:\Users\you\AppData\Local\Lymals\logs\server.log
    • macOS/Linux: /tmp/lymals/server.log
  • lymalsExtension.server.rustLog sets RUST_LOG for the spawned server process.
  • In Extension Development mode, leaving lymalsExtension.server.logFile empty uses a storage-backed default log file; the resolved path is announced in Output > Lymals.
  • lymalsExtension.server.trace.server is the quickest way to inspect raw LSP traffic.

The root Taskfile.yml also contains a vsix helper for local packaging experiments, but that .vsix remains a development-only artifact and must not be described or treated as publishable in v1.

Local packaging workflow (editors/vscode only)

Package the extension locally from editors/vscode:

npm run package

That workflow is intentionally limited to producing a local .vsix build artifact. It does not publish, upload, or release anything to the VS Code Marketplace, Open VSX, or GitHub Releases.

Before considering a .vsix shareable even for internal review, inspect the exact contents:

npm run package:contents

Equivalent direct command:

vsce ls --tree --no-dependencies

Review that listing and confirm it excludes tests, node_modules, Rust target output, logs, and any secrets or local-only files.

Packaging notes:

  • Default recommendation: do not bundle platform-specific lymals binaries in the first VS Code packaging PR.
  • Preferred development flow: point the extension at a user-configured binary path or a lymals binary already available on PATH.
  • If a future binary-bundling strategy is approved, run cargo build --release first and make any binary copy/embed step explicit, documented, and reviewable.
  • Keep editors/vscode/package.json's extension version aligned with the Rust crate version in Cargo.toml.

Marketplace/Open VSX prerequisites are intentionally out of scope here. Publisher ownership, versioning policy, licensing review, and release-artifact validation must be completed separately and approved by a maintainer before any future manual publish decision.

Contribution workflow

  • Keep changes aligned with the v1 contract: release only raw lymals binaries/checksums, keep editor integration docs-only, and do not add Lua execution paths to shipped features.
  • Run the validation commands above before opening a PR; at minimum, formatting, clippy, tests, docs, and cargo deny check should pass locally or in CI.
  • Update user/developer docs when behavior, flags, configuration, safety limits, or packaging scope changes.
  • Add or update focused tests with code changes; use snapshot/golden updates only when the behavior change is intentional.
  • Document externally visible changes in CHANGELOG.md under Unreleased.

Architecture notes

  • tower-lsp owns protocol dispatch in src/server.rs; feature-specific request logic lives under src/handlers/.
  • Feature engines consume local parser/tokenizer/syntax/semantic facades rather than raw upstream AST types.
  • Source-line or indentation heuristics are allowed only as supplements after syntax lookup (for example folding/selection/code-action edit extents), and should stay covered by focused tests.
  • src/imports.rs and src/workspace.rs enforce resolver containment and workspace limits.
  • src/eval.rs is a fail-closed placeholder; do not call it from shipped editor features for v1.