holocron 0.3.0

Declarative schema & query compiler — one YAML as the source of truth for SQL schema and a type-checked query catalog.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# Holocron

[![CI](https://github.com/extinctCoder/holocron/actions/workflows/ci.yml/badge.svg)](https://github.com/extinctCoder/holocron/actions/workflows/ci.yml)
[![Security Audit](https://github.com/extinctCoder/holocron/actions/workflows/audit.yml/badge.svg)](https://github.com/extinctCoder/holocron/actions/workflows/audit.yml)
[![dependency status](https://deps.rs/repo/github/extinctCoder/holocron/status.svg)](https://deps.rs/repo/github/extinctCoder/holocron)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/extinctCoder/holocron/badge)](https://securityscorecards.dev/viewer/?uri=github.com/extinctCoder/holocron)
[![crates.io](https://img.shields.io/crates/v/holocron.svg)](https://crates.io/crates/holocron)
[![downloads](https://img.shields.io/crates/d/holocron.svg)](https://crates.io/crates/holocron)
[![docs.rs](https://img.shields.io/docsrs/holocron)](https://docs.rs/holocron)
[![license](https://img.shields.io/crates/l/holocron.svg)](#license)

> A declarative schema & query compiler — one YAML file as the single source of truth
> for your SQL schema **and** a type-checked query catalog.

## What is this?

Holocron is a **compiler whose target language is SQL**. You write one declarative
**YAML** file that defines both:

1. your **database schema** (tables, views, indexes), and
2. a **semantic rulebook** — which columns are filterable/searchable/sortable, what
   the aggregates and entities are, who owns a row, which view is the default list.

From that single file it produces the physical schema **and** an in-memory **catalog**.
Any query — written in **RSQL** (compact, URL-friendly) or **YAML** (full specs) — is
**type-checked against the catalog before it runs**: unknown field, not-filterable,
wrong-operator-for-type are caught at build time, **with no database connection needed**,
because the YAML *is* the schema.

## Why

ORMs are code-first and language-bound, and migration tools know nothing about how the
app is *allowed* to use the data. Holocron's novel piece is the **bridge**: one
declarative source that is simultaneously the physical schema *and* the application's
query/authz/read contract, consumable from any language.

> **The guarantee:** *any query that compiles is well-formed against the declared schema
> — every field exists, is allowed, and is used with a valid operator for its type — and
> produces runnable SQL.*

## Status

🚧 **Active development.** The compiler pipeline parses, builds a catalog, resolves
views, type-checks queries, and emits PostgreSQL DDL end-to-end — with rich,
rustc-style diagnostics that underline the exact YAML token at fault. The LSP server
gives live in-editor squiggles. Still in flight: error-collection (currently bail-on-first),
DML emit, and the RSQL parser. Full roadmap in
[`holocron-seed/DESIGN.md`](holocron-seed/DESIGN.md).

## Install

```sh
cargo install holocron
```

Installs two binaries:

- **`holocron`** — the CLI compiler
- **`holocron-lsp`** — the editor LSP server

Or download pre-built archives for macOS / Linux / Windows from the
[latest GitHub Release](https://github.com/extinctCoder/holocron/releases/latest)
(each archive contains both binaries).

To use the compiler as a Rust library:

```sh
cargo add holocron
```

## Usage

Schema files conventionally use the `.holocron.yaml` extension — the editor LSP picks
that up automatically. See [`samples/`](samples/) for a dozen-plus working examples
plus error samples demonstrating every diagnostic.

```sh
holocron samples/blog.holocron.yaml     # YAML → PostgreSQL DDL on stdout
cat schema.holocron.yaml | holocron     # or pipe from stdin
holocron --help
```

## Editor integration

`holocron-lsp` speaks standard [LSP](https://microsoft.github.io/language-server-protocol/).
Open a `.holocron.yaml` file in your editor and unknown columns, duplicate aliases,
type mismatches, etc. underline in real time with the same diagnostics you'd see at
the CLI.

### Zed (project `.zed/settings.json`)

```json
{
  "lsp": {
    "holocron": {
      "binary": {
        "path": "/path/to/holocron-lsp",
        "arguments": []
      }
    }
  },
  "languages": {
    "YAML": { "language_servers": ["holocron"] }
  }
}
```

Make sure the project is **trusted** in Zed; otherwise project-level settings (including
this one) are ignored.

### JetBrains (RustRover, IntelliJ, …) via LSP4IJ

1. Install the **LSP4IJ** plugin from the Marketplace.
2. `Settings → Languages & Frameworks → Language Servers → +` (New Language Server).
3. **Command:** the path to `holocron-lsp`.
4. **Mappings tab → File name patterns:** `*.holocron.yaml`.
5. **Language Id:** leave empty.

### Other editors

`holocron-lsp` is a stdio LSP server. Any LSP client works — point it at the binary
and associate `*.holocron.yaml`.

## Development

This project uses [Conventional Commits](https://www.conventionalcommits.org). Releases
are fully automated: merging to `main` bumps the version, updates the changelog, tags,
publishes to crates.io, and creates a GitHub Release with binary archives for every
supported platform.

```sh
cargo build      # build
cargo test       # run tests
cargo doc --open # build & view the docs
```

[pre-commit](https://pre-commit.com) hooks mirror CI (formatting, clippy, tests, commit
linting):

```sh
pre-commit install --install-hooks --hook-type commit-msg
```

## License

Licensed under the [Mozilla Public License 2.0](LICENSE).