MatchaDB for VSCode

Language support for MatchaDB .matcha import files — a JSON5-based format whose keys map onto your JPA @Entity classes.

See MatchaDB for the library itself.

Features

Syntax highlighting for the JSON5 grammar plus MatchaDB semantics — reserved @-keys, #Entity:field references, entity keys distinguished from field keys.
Editor behaviors — auto-closing and surrounding pairs, brace matching, comment toggling, bracket-aware indentation.
Formatting that preserves comments and removes trailing commas.
Diagnostics for syntax errors and MatchaDB rules: keys used in the wrong place, unknown @-keys, duplicate or dangling @import_key / @fk_…, and more.
Schema-aware diagnostics, checked against your Java entities: unknown entity or field names, values whose type doesn't match the Java field, relationship values of the wrong shape, and fields the nesting already sets.
Completion of entity names, the contextual entity's field names, and concrete @fk_<field> / #<Entity>:<field> keys — never suggesting something already set.
Inlay hints labelling each row with the @Entity it maps to.
Go to definition from a key to its Java field or @Entity class.
Java @matchadb: links — an "@matchadb:<path>" argument in a Java file is highlighted (the marker like a reserved MatchaDB key, the path like a field), Ctrl/Cmd-clickable to open the import file, completes the path from the workspace's .matcha files, and is flagged when the path resolves to nothing.
Java import keys — an ImportReport key passed to get(…) / getId(…) navigates to its @import_key, completes from the loaded files, and is flagged when none of them declares it. The report is followed back to its loadAndReturn, whether called directly or held in a variable or field.

Requirements

None to edit .matcha files. The schema-aware features additionally need your JPA @Entity classes in the workspace — they are read straight from the .java sources, so no build step is required, and they stay silent when nothing is found.

@MatchaDbConfiguration (or matchadb.* properties) is picked up for the generation prefix and entity packages.

Known limitations

The Java sources are scanned syntactically, so a type hidden behind a constant or an unresolved cross-file generic is not resolved; the affected features stay silent rather than guess.

Import keys are resolved by following the report within its own file, so a report bound in another file — a base class, say — is not resolved; those calls are left alone rather than flagged.

Import keys are not syntax-highlighted in Java. A TextMate grammar cannot tell which receiver is an ImportReport, so colouring them would also colour every unrelated get(…) / getId(…) call. Navigation, completion and diagnostics do resolve the report properly, and stay silent on unrelated calls.

Architecture

├─ package.json                     # manifest + build scripts
├─ icons/                           # .matcha file icon (light + dark) + marketplace icon
├─ language-configuration.json      # editor behaviors
├─ syntaxes/matcha.tmLanguage.json  # TextMate grammar (highlighting)
├─ client/src/extension.ts          # LSP client (extension entry point)
└─ server/src/
   ├─ server.ts                     # LSP server: connection + capabilities
   ├─ parser/                       # lexer, AST, recursive-descent parser
   ├─ features/                     # diagnostics, completion, formatting, hints, definition
   ├─ schema/                       # Java scanning -> the @Entity model
   └─ test/                         # unit tests (node:test)

The language server is a local Node process — no network involved.

Develop

npm install
npm run compile     # or: npm run watch
npm test            # unit tests
npm run package     # build a .vsix

Press F5 to launch an Extension Development Host. It reopens whatever folder it had last, so open a MatchaDB project there once; or use the "Run Extension (demo project)" launch config for the self-contained samples/demo-project/.

The Output panel → MatchaDB Language Server logs the resolved schema on startup.

License

Apache-2.0

MatchaDB

CaRool