# Pulsar Tree-sitter Migration Notes

The current Pulsar package uses:

```text
pulsaredit-language-zuzu/language-zuzu/grammars/zuzu.cson
```

That grammar should not be removed until `tree-sitter-zuzu` is proven in a real
Pulsar package.

## Local Spike Result

Checked against local Pulsar:

```text
Pulsar  : 1.114.0
Electron: 12.2.3
Chrome  : 89.0.4389.128
Node    : 14.16.0
```

The existing `pulsaredit-language-zuzu/language-zuzu/package.json` contributes
only `./grammars/zuzu.cson`, and `lib/main.js` has empty activation hooks. Its
current package tests pass under `pulsar --package test`:

```text
5 tests, 96 assertions, 0 failures, 0 skipped
```

Decision for now: use option 3, audit-only. Keep the CSON grammar as the
shipped Pulsar grammar and use `tree-sitter-zuzu` as an audit and future
migration source until a dedicated Pulsar package spike proves that current
Pulsar can register this parser, load the shared query files or documented
Pulsar-specific variants, and preserve existing package behaviour.

## Feasibility Questions

- Can current Pulsar register and load a third-party Tree-sitter grammar from a
  package without patching Pulsar itself?
- Does the package need generated parser artefacts checked in, or can it build
  during package installation?
- Can existing settings and activation code remain unchanged?
- Are the shared `queries/*.scm` captures sufficient for Pulsar themes?
- Is a TextMate fallback needed for older Pulsar installations?

## Migration Options

1. Full migration: Pulsar uses `tree-sitter-zuzu` as the primary grammar and
   drops the CSON grammar after one deprecation release.
2. Hybrid migration: Pulsar uses Tree-sitter where supported and retains the
   CSON grammar as fallback.
3. Audit-only: the CSON grammar remains, but Tree-sitter tests become the
   reference for future highlighting fixes.

## Acceptance Criteria

- Install the package in current Pulsar.
- Open `.zzs` and `.zzm` files.
- Confirm highlighting, comments, POD blocks, strings, Unicode operators, and
  folding.
- Run the package's existing specs.
- Document any Pulsar-specific query deviations.
