intentumdiff-plugin-repo
The RULES a standalone IntentumDiff plugin repo must follow — every intentumdiff-<lang>-parser (and any third-party plugin, e.g. intentumdiff-dbt). Use this whenever you create, scaffold, review, or w
SKILL.mdskills/intentumdiff-plugin-repo/SKILL.md
GitHubIntentumDiff — Plugin repo rules
This skill is mastered by
intentumdiff-plugin-sdkand copied onto each plugin repo. Do NOT edit the copy in a parser repo — change the SDK master and let thesync-skillsjob fan it out.
A plugin repo is one self-contained WebAssembly component (a parser is the common case) plus its
build, tests, docs, and registry metadata. intentumdiff-<lang>-parser x69 are first-party;
third-party plugins (intentumdiff-dbt, …) follow the same rules and the same loading path — there
is no privileged first-party route.
The rules (a plugin repo MUST…)
- Implement the WIT contract, and only the WIT contract.
plugin.wit(from the SDK) is the single source of truth for the boundary — there is no Python ABC, no host-side interface. A parser implements theparser-pluginworld. - Depend on
intentumdiff-plugin-sdk; never copy-paste conversion code. Shared behavior (CST→ SemanticNode conversion, text/literal capture, generic labeling, position conventions, trivia, structural hashing) lives in the SDK'sTreeSitterConverter. The repo supplies ONLY data (semantic-type lists) and genuine language overrides (label_overridehooks). Maintainer ruling (2026-07-06): do not copy the conversion template between crates — the 28 duplicated templates drifted and forced per-crate sweeps. A conversion bug fix belongs in the SDK unless provably language-specific. - Be
ParserMode::FullParse(first-party) — the plugin owns grammar AND CST→semantic mapping. Host-sideinterpret-cstis rejected on first-party paths. - Export the full set:
preprocess-source,process(the full parse),detect-language(cheap, deterministic, conservative),example,language-ids/language-info,trivia-node-types. - Emit a valid tree: globally-unique
ids (or the host rejects it), meaningfulnode_type(grammar role) +label(identity token),parent_typefor methods, and privacy-safeNodeFactson definition nodes. 0-based rows are mandatory (issue #52). VALUE/literal nodes must be semantic or value edits vanish. Use the grammar's ACTUAL node-kind names — dump a parse, never guess. - Meet the shipped-example contract: every advertised language ID parses its
examplewith NO fallback and NO parse errors, producing a structured diff. Dormant grammars stay disabled until they meet it. - Ship + pass its Tier-B CI: builds the
.wasm, runs the #87 parity/fuzz suite (parses its own WIT example; survives truncated/binary/NUL/bracket-noise input with only valid outcomes — a tree, an in-band{error}envelope, or a typed plugin exception, never a host crash), and per-cratecargo test. The SDK provides the reusable CI workflow. - Earn trust through the registry, not its repo. "Official/safe" = listed in
intentumdiff-registrywith a verified checksum, a clean capability scan, and a matching provenance manifest — enforced by the registry PR gate, NOT by which org owns the repo. Ship a provenance manifest (SHA-256 of the staged.wasm+ source manifest) and declaretrust_tier/abi_target. - Run sandboxed with zero host capabilities. Parsers execute in wasmtime with empty WASI (no
fs/net/env), memory-isolated and fuel-metered; the only host imports are
strip-trivia,structural-hash,log. Do not assume any ambient capability. - Pin the ABI/contract version. The repo builds against a specific SDK WIT/host-utils version; the host enforces the version at load. Bump deliberately.
What a plugin repo contains
intentumdiff-<lang>-parser/
Cargo.toml # standalone; depends on the intentumdiff SDK crate (not a workspace)
src/ # the parser crate (grammar dep + semantic-type data + overrides)
wit/ # the pinned plugin.wit (from the SDK)
tests/ # per-crate cargo tests + Tier-B parity/fuzz fixtures
.github/workflows/ # the SDK-provided reusable CI (build .wasm + parity/fuzz + register)
provenance.json # SHA-256 + source manifest for the built .wasm
.claude/skills/ # this skill (SDK-mastered copy) + intentumdiff-parsers
README.md
Adding / fixing a language
Follow intentumdiff-parsers for the mechanics (scaffold from the SDK template, implement the
exports, map the CST, the hard-won conversion rules). The repo-level difference from the monorepo:
the five registration ledgers become the registry entry + the ABI target — a plugin repo does
not edit the core's pyproject/registry.py; it registers itself in intentumdiff-registry.
Migration acceptance (files-only extraction)
A pure extraction leaves the corpus ratchet manifests byte-identical on regeneration
(tests/fixtures/corpus is the contract). No history is imported — one clean initial commit.