cratestack-parser 0.3.2

Rust-native schema-first framework for typed HTTP APIs, generated clients, and backend services.
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

# cratestack-parser

Parser and semantic checker for `.cstack` schema files.

## Overview

`cratestack-parser` turns `.cstack` source text into a `cratestack_core::Schema` AST and runs semantic validation. The `include_schema!` proc-macro calls this crate at compile time; the LSP and CLI call it at runtime.

## Installation

```toml
[dependencies]
cratestack-parser = "0.2.2"
```

## Usage

### Parse from a string

```rust
use cratestack_parser::parse_schema;

let source = r#"
auth Principal {
  id String
  role String?
}

model Post {
  id String @id
  title String
  published Boolean @default(false)
  authorId String

  @@allow("read", auth() != null)
}
"#;

let schema = parse_schema(source)?;
```

### Parse from a file

```rust
use cratestack_parser::parse_schema_file;

let schema = parse_schema_file("schema.cstack")?;
```

### Named source for diagnostics

```rust
use cratestack_parser::parse_schema_named;

let schema = parse_schema_named("my-app/schema.cstack", source)?;
```

## Errors

`SchemaError` carries a source span and a line number plus an ariadne-rendered report:

```rust
use cratestack_parser::{SchemaError, parse_schema};

match parse_schema(source) {
    Ok(schema) => { /* ... */ }
    Err(error) => {
        eprintln!("{}", error.message());
        eprintln!("line {}", error.line());
        let span = error.span();
        eprintln!("bytes {}..{}", span.start, span.end);
        eprintln!("{}", error.render("schema.cstack", source));
    }
}
```

## Supported Constructs

| Construct       | Description                                                |
|-----------------|------------------------------------------------------------|
| `datasource`    | Database config (`provider = "postgresql"` or `"sqlite"`)  |
| `auth`          | Single auth block declaring principal fields               |
| `mixin`         | Reusable field set, applied via `@use(...)` on a model     |
| `model`         | Entity with fields, relations, and policy attributes       |
| `type`          | Named record type (`@custom` fields supported)             |
| `enum`          | Untyped identifier variants                                |
| `procedure`     | `procedure` / `mutation procedure` with typed args/return  |
| `mcp`           | Parsed as a config block                                   |

See the root README for the canonical capability matrix.

## Field and Model Attributes

See [Field Attributes](https://cratestack.dev/reference/field-attributes) for the full list. Common attributes:

- `@id`, `@unique`, `@relation(...)`, `@default(...)`
- `@readonly`, `@server_only`, `@pii`, `@sensitive`
- `@version` (optimistic locking)
- `@length`, `@range`, `@email`, `@regex`, `@uri`, `@iso4217` (validators)
- `@@allow(action, expr)`, `@@deny(action, expr)`
- `@@audit`, `@@soft_delete`
- `@@emit(created, updated, deleted)`

## See Also

- [Mixins reference](https://cratestack.dev/reference/mixins)
- [Field Attributes](https://cratestack.dev/reference/field-attributes)
- [Validators guide](https://cratestack.dev/guides/validators)
- `cratestack-macros` — the proc-macro that drives this parser at compile time
- `cratestack-lsp` — LSP frontend over the same parser

## License

MIT