rototo 0.1.0-alpha.3

Control plane for runtime configuration of your application.
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

# Diagnostics Reference

Diagnostics are the contract between rototo, humans, CI, editor integrations,
and agents. A diagnostic tells you which rule failed, where it failed, how
serious it is, and what to change.

## Diagnostic Shape

JSON diagnostics use this shape:

```json
{
  "rule": "rototo/variable-unknown-value",
  "severity": "error",
  "stage": "reference",
  "entity": {
    "kind": "rule",
    "variable": "account-limits",
    "index": 0
  },
  "message": "rule references unknown value: enterprise",
  "help": "Create the referenced value or update the resolve reference.",
  "location": {
    "path": "variables/account-limits.toml",
    "range": {
      "start": { "line": 12, "character": 8 },
      "end": { "line": 12, "character": 20 }
    }
  },
  "related": []
}
```

## Rule Ids

Built-in rules use the `rototo` authority:

```text
rototo/<rule-id>
```

Examples:

```text
rototo/workspace-manifest-missing
rototo/qualifier-predicate-unknown-op
rototo/variable-unknown-value
rototo/resource-object-schema-mismatch
```

Custom rules use:

```text
<authority>/<rule-id>
```

The `rototo` authority is reserved. Each rule-id part must contain lowercase
ASCII letters, digits, or hyphens.

## Severity

Severity values are:

```text
error
warning
```

`rototo lint` exits with failure when selected diagnostics include any error.
Warnings are still reported because they often point at confusing or risky
workspace behavior.

## Entity Kinds

Diagnostics can target:

```text
workspace
manifest
qualifier
predicate
variable
resource
resource_object
value
rule
custom_lint
schema
```

The entity gives tools a stable object to group by. The location gives humans
the file and range to edit.

## Catalog

The diagnostic catalog describes available rules:

```sh
rototo show --lint-rules
rototo show examples/basic --lint-rules
rototo show examples/basic --lint-authority rototo
```

The global catalog contains built-in rototo rules. A workspace-scoped catalog
also includes custom rules registered by `lint/*.lua`.

Catalog entries contain:

```json
{
  "rule": "rototo/variable-unknown-value",
  "severity": "error",
  "entity": "variable",
  "title": "Variable references an unknown value",
  "help": "Create the referenced value or update the resolve reference."
}
```

## Stability

Treat rule ids as stable automation inputs. CI filters, editor integrations,
and agents should use `rule`, `severity`, `stage`, and `entity` rather than
matching diagnostic message text.

Messages are written for humans and may become more specific over time.