@redush/sysconst-validator 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +117 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# @redush/sysconst-validator
|
|
2
|
+
|
|
3
|
+
**Validation library for System Constitution**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@redush/sysconst-validator)
|
|
6
|
+
[](https://github.com/nicholasoxford/system-constitution/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
Part of [System Constitution](https://github.com/nicholasoxford/system-constitution) — an architectural governance layer for autonomous software evolution.
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npm install @redush/sysconst-validator
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Usage
|
|
17
|
+
|
|
18
|
+
```typescript
|
|
19
|
+
import { validate, validateFile } from '@redush/sysconst-validator';
|
|
20
|
+
|
|
21
|
+
// Validate YAML string
|
|
22
|
+
const result = validate(`
|
|
23
|
+
spec: sysconst/v1
|
|
24
|
+
project:
|
|
25
|
+
id: myapp
|
|
26
|
+
versioning:
|
|
27
|
+
strategy: semver
|
|
28
|
+
current: "1.0.0"
|
|
29
|
+
domain:
|
|
30
|
+
nodes:
|
|
31
|
+
- kind: System
|
|
32
|
+
id: system.root
|
|
33
|
+
spec:
|
|
34
|
+
goals: ["My application"]
|
|
35
|
+
`);
|
|
36
|
+
|
|
37
|
+
if (result.valid) {
|
|
38
|
+
console.log('Constitution is valid!');
|
|
39
|
+
} else {
|
|
40
|
+
console.log('Errors:', result.errors);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
// Validate from file
|
|
44
|
+
const fileResult = await validateFile('./myapp.sysconst.yaml');
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Validation Phases
|
|
48
|
+
|
|
49
|
+
The validator runs 6 phases in sequence:
|
|
50
|
+
|
|
51
|
+
| Phase | Description |
|
|
52
|
+
|-------|-------------|
|
|
53
|
+
| **1. Structural** | Syntax, required fields, JSON Schema compliance |
|
|
54
|
+
| **2. Referential** | NodeRef resolution, unique IDs, no dangling references |
|
|
55
|
+
| **3. Semantic** | Kind-specific rules (Entity fields, Command params, etc.) |
|
|
56
|
+
| **4. Evolution** | Version history, migration compatibility |
|
|
57
|
+
| **5. Generation** | Zone safety, hook anchor validation |
|
|
58
|
+
| **6. Verifiability** | Scenario coverage, pipeline definitions |
|
|
59
|
+
|
|
60
|
+
## API
|
|
61
|
+
|
|
62
|
+
### `validate(yaml: string): ValidationResult`
|
|
63
|
+
|
|
64
|
+
Validates a YAML string containing a System Constitution.
|
|
65
|
+
|
|
66
|
+
### `validateFile(path: string): Promise<ValidationResult>`
|
|
67
|
+
|
|
68
|
+
Validates a constitution file from disk.
|
|
69
|
+
|
|
70
|
+
### `ValidationResult`
|
|
71
|
+
|
|
72
|
+
```typescript
|
|
73
|
+
interface ValidationResult {
|
|
74
|
+
valid: boolean;
|
|
75
|
+
errors: ValidationError[];
|
|
76
|
+
warnings: ValidationWarning[];
|
|
77
|
+
phases: PhaseResult[];
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
interface ValidationError {
|
|
81
|
+
code: string; // e.g., "INVALID_NODE_REF"
|
|
82
|
+
message: string;
|
|
83
|
+
path?: string; // JSON path to error location
|
|
84
|
+
phase: number;
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Error Codes
|
|
89
|
+
|
|
90
|
+
| Code | Phase | Description |
|
|
91
|
+
|------|-------|-------------|
|
|
92
|
+
| `INVALID_YAML` | 1 | YAML parsing failed |
|
|
93
|
+
| `INVALID_SPEC_VERSION` | 1 | Unknown spec version |
|
|
94
|
+
| `SCHEMA_VIOLATION` | 1 | JSON Schema validation failed |
|
|
95
|
+
| `DUPLICATE_ID` | 2 | Node ID used more than once |
|
|
96
|
+
| `INVALID_NODE_REF` | 2 | NodeRef points to non-existent node |
|
|
97
|
+
| `INVALID_FIELD_TYPE` | 3 | Unknown field type in Entity |
|
|
98
|
+
| `MISSING_REQUIRED_FIELD` | 3 | Required field not defined |
|
|
99
|
+
| `INVALID_EVOLUTION` | 4 | Breaking change without migration |
|
|
100
|
+
| `INVALID_ZONE` | 5 | Unknown generation zone |
|
|
101
|
+
| `UNCOVERED_SCENARIO` | 6 | Node not covered by any scenario |
|
|
102
|
+
|
|
103
|
+
See [full error reference](https://github.com/nicholasoxford/system-constitution/blob/main/docs/v1/reference/error-codes.md).
|
|
104
|
+
|
|
105
|
+
## Related Packages
|
|
106
|
+
|
|
107
|
+
- [`@redush/sysconst`](https://www.npmjs.com/package/@redush/sysconst) — CLI tool
|
|
108
|
+
|
|
109
|
+
## Links
|
|
110
|
+
|
|
111
|
+
- [Documentation](https://redush.com)
|
|
112
|
+
- [GitHub](https://github.com/nicholasoxford/system-constitution)
|
|
113
|
+
- [Full Specification](https://github.com/nicholasoxford/system-constitution/blob/main/docs/v1/spec/01-introduction.md)
|
|
114
|
+
|
|
115
|
+
## License
|
|
116
|
+
|
|
117
|
+
MIT
|
package/package.json
CHANGED