@dxos/deus 0.0.0-stage → 0.0.0
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/LICENSE +105 -0
- package/README.md +24 -2
- package/bin/deus.ts +42 -0
- package/dist/lib/chunk-blocks.mjs +151 -0
- package/dist/lib/chunk-blocks.mjs.map +1 -0
- package/dist/lib/chunk-check.mjs +452 -0
- package/dist/lib/chunk-check.mjs.map +1 -0
- package/dist/lib/chunk-completion.mjs +112 -0
- package/dist/lib/chunk-completion.mjs.map +1 -0
- package/dist/lib/chunk-extension.mjs +396 -0
- package/dist/lib/chunk-extension.mjs.map +1 -0
- package/dist/lib/chunk-parse.mjs +21 -0
- package/dist/lib/chunk-parse.mjs.map +1 -0
- package/dist/lib/cli.mjs +946 -0
- package/dist/lib/cli.mjs.map +1 -0
- package/dist/lib/extension.mjs +4 -0
- package/dist/lib/index.mjs +6 -0
- package/dist/lib/parse.mjs +4 -0
- package/dist/lib/review.mjs +260 -0
- package/dist/lib/review.mjs.map +1 -0
- package/dist/lib/spec-index.mjs +28 -0
- package/dist/lib/spec-index.mjs.map +1 -0
- package/dist/types/bin/deus.d.ts +3 -0
- package/dist/types/bin/deus.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts +7 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts +5 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/changelog.d.ts +25 -0
- package/dist/types/src/cli/changelog.d.ts.map +1 -0
- package/dist/types/src/cli/cli.test.d.ts +2 -0
- package/dist/types/src/cli/cli.test.d.ts.map +1 -0
- package/dist/types/src/cli/errors.d.ts +183 -0
- package/dist/types/src/cli/errors.d.ts.map +1 -0
- package/dist/types/src/cli/features.d.ts +58 -0
- package/dist/types/src/cli/features.d.ts.map +1 -0
- package/dist/types/src/cli/git.d.ts +8 -0
- package/dist/types/src/cli/git.d.ts.map +1 -0
- package/dist/types/src/cli/index.d.ts +12 -0
- package/dist/types/src/cli/index.d.ts.map +1 -0
- package/dist/types/src/cli/lint.d.ts +17 -0
- package/dist/types/src/cli/lint.d.ts.map +1 -0
- package/dist/types/src/cli/qa-lint.d.ts +40 -0
- package/dist/types/src/cli/qa-lint.d.ts.map +1 -0
- package/dist/types/src/cli/qa.d.ts +86 -0
- package/dist/types/src/cli/qa.d.ts.map +1 -0
- package/dist/types/src/cli/review.d.ts +38 -0
- package/dist/types/src/cli/review.d.ts.map +1 -0
- package/dist/types/src/cli/spec-index.d.ts +17 -0
- package/dist/types/src/cli/spec-index.d.ts.map +1 -0
- package/dist/types/src/extension/blocks.d.ts +65 -0
- package/dist/types/src/extension/blocks.d.ts.map +1 -0
- package/dist/types/src/extension/check.d.ts +99 -0
- package/dist/types/src/extension/check.d.ts.map +1 -0
- package/dist/types/src/extension/check.test.d.ts +2 -0
- package/dist/types/src/extension/check.test.d.ts.map +1 -0
- package/dist/types/src/extension/code.d.ts +7 -0
- package/dist/types/src/extension/code.d.ts.map +1 -0
- package/dist/types/src/extension/complete.d.ts +6 -0
- package/dist/types/src/extension/complete.d.ts.map +1 -0
- package/dist/types/src/extension/completion.d.ts +10 -0
- package/dist/types/src/extension/completion.d.ts.map +1 -0
- package/dist/types/src/extension/constants.d.ts +6 -0
- package/dist/types/src/extension/constants.d.ts.map +1 -0
- package/dist/types/src/extension/fences.d.ts +10 -0
- package/dist/types/src/extension/fences.d.ts.map +1 -0
- package/dist/types/src/extension/gen/mdl.d.ts +3 -0
- package/dist/types/src/extension/gen/mdl.d.ts.map +1 -0
- package/dist/types/src/extension/gen/mdl.terms.d.ts +2 -0
- package/dist/types/src/extension/gen/mdl.terms.d.ts.map +1 -0
- package/dist/types/src/extension/index.d.ts +8 -0
- package/dist/types/src/extension/index.d.ts.map +1 -0
- package/dist/types/src/extension/language.d.ts +20 -0
- package/dist/types/src/extension/language.d.ts.map +1 -0
- package/dist/types/src/extension/lint.d.ts +8 -0
- package/dist/types/src/extension/lint.d.ts.map +1 -0
- package/dist/types/src/extension/parse.d.ts +6 -0
- package/dist/types/src/extension/parse.d.ts.map +1 -0
- package/dist/types/src/extension/parser.test.d.ts +2 -0
- package/dist/types/src/extension/parser.test.d.ts.map +1 -0
- package/dist/types/src/extension/refs.d.ts +32 -0
- package/dist/types/src/extension/refs.d.ts.map +1 -0
- package/dist/types/src/extension/refs.test.d.ts +2 -0
- package/dist/types/src/extension/refs.test.d.ts.map +1 -0
- package/dist/types/src/extension/syntax.d.ts +12 -0
- package/dist/types/src/extension/syntax.d.ts.map +1 -0
- package/dist/types/src/index.d.ts +3 -0
- package/dist/types/src/index.d.ts.map +1 -0
- package/dist/types/src/review/fields.d.ts +9 -0
- package/dist/types/src/review/fields.d.ts.map +1 -0
- package/dist/types/src/review/index.d.ts +5 -0
- package/dist/types/src/review/index.d.ts.map +1 -0
- package/dist/types/src/review/review.d.ts +70 -0
- package/dist/types/src/review/review.d.ts.map +1 -0
- package/dist/types/src/review/review.test.d.ts +2 -0
- package/dist/types/src/review/review.test.d.ts.map +1 -0
- package/dist/types/src/review/source-key.d.ts +35 -0
- package/dist/types/src/review/source-key.d.ts.map +1 -0
- package/dist/types/src/review/symbol.d.ts +17 -0
- package/dist/types/src/review/symbol.d.ts.map +1 -0
- package/dist/types/src/review/symbol.test.d.ts +2 -0
- package/dist/types/src/review/symbol.test.d.ts.map +1 -0
- package/dist/types/src/spec-index/index.d.ts +3 -0
- package/dist/types/src/spec-index/index.d.ts.map +1 -0
- package/dist/types/src/spec-index/parse.d.ts +11 -0
- package/dist/types/src/spec-index/parse.d.ts.map +1 -0
- package/dist/types/src/spec-index/spec-index.d.ts +21 -0
- package/dist/types/src/spec-index/spec-index.d.ts.map +1 -0
- package/dist/types/src/spec-index/spec-index.test.d.ts +2 -0
- package/dist/types/src/spec-index/spec-index.test.d.ts.map +1 -0
- package/dist/types/tsconfig.tsbuildinfo +1 -0
- package/docs/DESIGN.md +561 -0
- package/docs/IDIOMS.md +265 -0
- package/lang/PLUGIN-.template.mdl +115 -0
- package/lang/app.mdl +200 -0
- package/lang/changelog.mdl +184 -0
- package/lang/core.mdl +203 -0
- package/lang/examples/chess-1.mdl +149 -0
- package/lang/examples/chess-2.mdl +203 -0
- package/lang/examples/chess-3.mdl +231 -0
- package/lang/features.mdl +92 -0
- package/lang/plugin.mdl +59 -0
- package/lang/qa.mdl +383 -0
- package/lang/review.mdl +103 -0
- package/lang/sql.mdl +72 -0
- package/package.json +74 -3
- package/src/cli/__fixtures__/bad-decision.mdl +13 -0
- package/src/cli/__fixtures__/features/CYCLE.mdl +25 -0
- package/src/cli/__fixtures__/features/FEATURES.mdl +47 -0
- package/src/cli/__fixtures__/features/SPEC.mdl +22 -0
- package/src/cli/__fixtures__/features/SPEC.review.mdl +32 -0
- package/src/cli/__fixtures__/features/TASKS.md +5 -0
- package/src/cli/__fixtures__/lint-refs/SPEC.mdl +7 -0
- package/src/cli/__fixtures__/lint-refs/SPEC.review.mdl +7 -0
- package/src/cli/__fixtures__/qa-lint/packages/plugins/plugin-risky/PLUGIN.mdl +29 -0
- package/src/cli/__fixtures__/qa-list/plugin-sample/spec/PLUGIN.mdl +51 -0
- package/src/cli/__fixtures__/review/SPEC.mdl +23 -0
- package/src/cli/__fixtures__/review/SPEC.review.mdl +26 -0
- package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.review.mdl +14 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.ts +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.ts +7 -0
- package/src/cli/changelog.ts +122 -0
- package/src/cli/cli.test.ts +359 -0
- package/src/cli/errors.ts +23 -0
- package/src/cli/features.ts +320 -0
- package/src/cli/git.ts +35 -0
- package/src/cli/index.ts +27 -0
- package/src/cli/lint.ts +75 -0
- package/src/cli/qa-lint.ts +206 -0
- package/src/cli/qa.ts +300 -0
- package/src/cli/review.ts +359 -0
- package/src/cli/spec-index.ts +54 -0
- package/src/extension/blocks.ts +169 -0
- package/src/extension/check.test.ts +629 -0
- package/src/extension/check.ts +552 -0
- package/src/extension/code.ts +99 -0
- package/src/extension/complete.ts +34 -0
- package/src/extension/completion.ts +64 -0
- package/src/extension/constants.ts +28 -0
- package/src/extension/fences.ts +270 -0
- package/src/extension/gen/mdl.terms.ts +16 -0
- package/src/extension/gen/mdl.ts +16 -0
- package/src/extension/index.ts +25 -0
- package/src/extension/language.ts +33 -0
- package/src/extension/lint.ts +19 -0
- package/src/extension/mdl.grammar +60 -0
- package/src/extension/parse.ts +31 -0
- package/src/extension/parser.test.ts +248 -0
- package/src/extension/refs.test.ts +95 -0
- package/src/extension/refs.ts +94 -0
- package/src/extension/syntax.ts +25 -0
- package/src/index.ts +6 -0
- package/src/review/fields.ts +31 -0
- package/src/review/index.ts +8 -0
- package/src/review/review.test.ts +111 -0
- package/src/review/review.ts +184 -0
- package/src/review/source-key.ts +63 -0
- package/src/review/symbol.test.ts +47 -0
- package/src/review/symbol.ts +96 -0
- package/src/spec-index/index.ts +6 -0
- package/src/spec-index/parse.ts +22 -0
- package/src/spec-index/spec-index.test.ts +56 -0
- package/src/spec-index/spec-index.ts +49 -0
package/lang/qa.mdl
ADDED
|
@@ -0,0 +1,383 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: org.dxos.spec.qa
|
|
3
|
+
name: DSL.QA
|
|
4
|
+
version: 1.1
|
|
5
|
+
extends:
|
|
6
|
+
- org.dxos.spec.core
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
The QA dialect. Adds the executable half of a specification, so a `.mdl` document doubles as a
|
|
10
|
+
test plan that a human tester and an agent tester execute from the same source.
|
|
11
|
+
|
|
12
|
+
The vocabulary is borrowed, not invented, and comes in two layers:
|
|
13
|
+
|
|
14
|
+
| Layer | Term | Meaning |
|
|
15
|
+
| --- | --- | --- |
|
|
16
|
+
| Gherkin — criteria, derivable | `feat` / `req` | a feature and its requirements |
|
|
17
|
+
| | `scenario T-n` | given / when / then; a criterion, not a script (Deus.Std) |
|
|
18
|
+
| xUnit — execution, runnable | `suite` | a named set of tests, selected by name or tag |
|
|
19
|
+
| | `test QA-n` | one executable case: `before` / `steps` / `after` |
|
|
20
|
+
| | `step` | one move: a human instruction and, usually, one operation |
|
|
21
|
+
|
|
22
|
+
A `test` is an ordered list of steps with a success criterion per step. Each step carries two
|
|
23
|
+
faces: a human instruction and, where the step maps to an invocable operation, an agent binding.
|
|
24
|
+
Neither face is a rendering of the other — a human clicks a navtree row, an agent invokes an
|
|
25
|
+
operation, and both are the truth about how that actor performs the step.
|
|
26
|
+
|
|
27
|
+
Tests live in a `## QA` section of a `PLUGIN.mdl`, or in `spec/APP.mdl` of an application for
|
|
28
|
+
journeys that cross plugins. Suites live beside the tests they group.
|
|
29
|
+
|
|
30
|
+
## Extensions
|
|
31
|
+
|
|
32
|
+
| Term | URI |
|
|
33
|
+
| ------- | -------------------------- |
|
|
34
|
+
| `test` | `org.dxos.mdl.test@1.0` |
|
|
35
|
+
| `step` | `org.dxos.mdl.step@1.0` |
|
|
36
|
+
| `suite` | `org.dxos.mdl.suite@1.0` |
|
|
37
|
+
| `op` | `org.dxos.mdl.op@1.1` |
|
|
38
|
+
|
|
39
|
+
`org.dxos.mdl.test@1.0` named the given/when/then block until 2026-09-08; that block is now
|
|
40
|
+
`scenario` (`org.dxos.mdl.scenario@1.0`) and `test` is the executable one. A document declaring
|
|
41
|
+
`test` in its Extensions table means this definition.
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Relationship to `scenario`
|
|
46
|
+
|
|
47
|
+
`scenario` and `test` are not competitors and must not be collapsed:
|
|
48
|
+
|
|
49
|
+
| | `scenario T-n` | `test QA-n` |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| Kind | derivable criterion | orchestrable script |
|
|
52
|
+
| Shape | given / when / then | N ordered steps in three stages |
|
|
53
|
+
| Target | vitest, storybook play | the running app |
|
|
54
|
+
| Asserted by | the test runner | the human, or an agent through the debug port |
|
|
55
|
+
|
|
56
|
+
A test's `covers:` names the `feat` / `req` / `scenario` identifiers it exercises, so coverage is
|
|
57
|
+
a question the linter can answer rather than a guess.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## The `test` Block
|
|
62
|
+
|
|
63
|
+
```mdl
|
|
64
|
+
ext test
|
|
65
|
+
uri: org.dxos.mdl.test@1.0
|
|
66
|
+
desc: |
|
|
67
|
+
An end-to-end case against the running application, executed by a human tester or an
|
|
68
|
+
agent. Three stages of ordered steps, each step with its own success criterion.
|
|
69
|
+
fields:
|
|
70
|
+
desc?: Prose
|
|
71
|
+
actors?: human | agent | both # default both; see the invoke rule below
|
|
72
|
+
covers?: RefList # feat / req / scenario ids this test exercises
|
|
73
|
+
status?: passing | failing | blocked | unverified # last known result, with a date in a comment
|
|
74
|
+
automated?: RefList # playwright specs that execute this test unattended (see below)
|
|
75
|
+
given?: GivenList # preconditions; `name: prose` binds `$given.name` (see below)
|
|
76
|
+
before?: StepList # fixture the test needs, but is not itself testing
|
|
77
|
+
steps: StepList # the test — the steps whose failure is a defect
|
|
78
|
+
after?: StepList # returning the app to its pre-test state
|
|
79
|
+
# all three are arrays of the same `step` shape
|
|
80
|
+
then?: ProseList # whole-test criteria, beyond the per-step ones
|
|
81
|
+
tags?: TagList
|
|
82
|
+
nesting: none
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
```mdl
|
|
86
|
+
ext step
|
|
87
|
+
uri: org.dxos.mdl.step@1.0
|
|
88
|
+
desc: |
|
|
89
|
+
One move in a test — an item of a stage list, not a block of its own. `do` and `expect`
|
|
90
|
+
are required: that is what keeps a test human-runnable, and a step no human can perform is a
|
|
91
|
+
design smell rather than a shortcut. A step invokes at most one operation.
|
|
92
|
+
fields:
|
|
93
|
+
name?: Prose # short title, for the report table
|
|
94
|
+
id?: Identifier # stable handle; see the numbering rule below
|
|
95
|
+
do: Prose # the human instruction (required)
|
|
96
|
+
expect: Prose # the success criterion BOTH actors judge (required)
|
|
97
|
+
invoke?: OpInvocation # operation key + input literal; one operation per step
|
|
98
|
+
space?: Expr # the space the invoker receives; default `$given.space`, else the default space
|
|
99
|
+
capture?: Identifier # names this step's result for later steps as `$<name>`
|
|
100
|
+
assert?: CodeBlock # deterministic check evaluated in the debug port; must return truthy
|
|
101
|
+
note?: Prose # a constraint the runner must respect (see Execution Rules)
|
|
102
|
+
blocked?: Prose # why this step cannot run at all, and what must change first
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Steps are items of a list, not repeated `step <n>:` keys. Core declares block bodies as
|
|
106
|
+
`key[?]: value`, with `key:` followed by an indented `-` list as the multi-line form — which
|
|
107
|
+
`given` already uses. A pseudo-key carrying a positional id is not core syntax, and
|
|
108
|
+
it forces every later step to be renumbered by hand when one is inserted.
|
|
109
|
+
|
|
110
|
+
### Field rules
|
|
111
|
+
|
|
112
|
+
1. **`do` and `expect` are required on every step.** A test whose steps only an agent can perform
|
|
113
|
+
is not a QA plan, it is a script.
|
|
114
|
+
2. **`invoke` is optional, and its absence is meaningful.** A step with no operation behind it —
|
|
115
|
+
a drag, a page reload, a judgement about flicker — is a first-class step. A test containing any
|
|
116
|
+
such step cannot declare `actors: agent`.
|
|
117
|
+
3. **`assert` is optional.** `expect` prose is always the criterion; `assert` only makes it
|
|
118
|
+
deterministic where that is cheap. Requiring it would make authoring a test a coding task.
|
|
119
|
+
4. **`capture` threads a result forward** as `$<name>`, referenced in a later step's `invoke`.
|
|
120
|
+
Within a step, `$result` is that step's own `invoke` result, for use in its `assert`, and
|
|
121
|
+
`$<name>.snapshot` is the snapshot taken after that step, for an operation that returns less
|
|
122
|
+
than the step produced. Only serializable values cross a snippet boundary — an id does, a live
|
|
123
|
+
ECHO object does not (Rule 2).
|
|
124
|
+
5. **`$snapshot` is the app's state after the step.** The runner takes one
|
|
125
|
+
`org.dxos.operation.debug.snapshot` after every step's `invoke` (or, for a step with none,
|
|
126
|
+
after the human reports it done) and binds it as `$snapshot` for the step's `assert`. It
|
|
127
|
+
carries `layout`, `planks`, `spaces`, `toasts`, `surfaces`, `attention`, `plugins`, and the
|
|
128
|
+
`errors` logged since the run started. A step judges the app by its snapshot or by a query
|
|
129
|
+
operation, never by the `invoke` return value (Rule 3). When a test needs something the snapshot
|
|
130
|
+
does not report, extend the snapshot operation rather than scripting the page.
|
|
131
|
+
Alongside it the runner binds **`$stepErrors`** — the entries of `$snapshot.errors` logged since
|
|
132
|
+
the previous step's snapshot, so this step's own errors and no one else's. `$snapshot.errors` is
|
|
133
|
+
cumulative by design (Rule 11) and therefore useless as a pass/fail clause: one background error
|
|
134
|
+
early in a run makes `$snapshot.errors.length === 0` false for every step after it. An `assert`
|
|
135
|
+
that judges errors uses `$stepErrors`; `$snapshot.errors` is for reporting.
|
|
136
|
+
6. **A `given` entry written `name: prose` binds `$given.name`.** A bare entry is a condition to
|
|
137
|
+
check; a named one is also a value the runner must resolve and hold for the steps to reference
|
|
138
|
+
(`$given.collection`). Without this, a step's `invoke` would name something the test never
|
|
139
|
+
defined.
|
|
140
|
+
7. **Steps are numbered by position**, from 1 within their stage, so `QA-1.3` is the third item
|
|
141
|
+
of `steps`. A step that needs a handle stable across insertions declares `id:`, and is then
|
|
142
|
+
referenced by it (`QA-1.open`) instead. Most steps do not need one; give an `id` to a step
|
|
143
|
+
whose failure is cited somewhere outside the document.
|
|
144
|
+
|
|
145
|
+
### `automated` — the unattended arm of a test
|
|
146
|
+
|
|
147
|
+
A `test QA-n` is the specification of a journey; a Playwright spec is one *execution* of it, run
|
|
148
|
+
unattended on every CI cell. `automated:` names those specs, each entry
|
|
149
|
+
`<package>:<file>#<full test title>`:
|
|
150
|
+
|
|
151
|
+
```mdl
|
|
152
|
+
automated:
|
|
153
|
+
- composer-e2e:basic.spec.ts#Basic tests › create document
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
The binding is declared on **both** sides and checked, rather than left as prose:
|
|
157
|
+
`packages/e2e/composer-e2e/scripts/check-qa-coverage.mjs` reads every `automated:` here and every
|
|
158
|
+
`@QA` tag in the specs, and fails when either side names something the other does not have. A
|
|
159
|
+
one-sided link rots silently — a renamed test keeps a green check while the flow it claimed to
|
|
160
|
+
cover stops being exercised.
|
|
161
|
+
|
|
162
|
+
1. **`automated` never replaces the steps.** The `do`/`expect` prose stays the contract, because a
|
|
163
|
+
spec asserts what it was written to assert and the flow is what a human re-runs when it breaks.
|
|
164
|
+
A test whose steps were deleted "because Playwright covers it" is no longer a QA flow.
|
|
165
|
+
2. **The spec is free to cover a subset**, and usually does: `after` is teardown the runner does
|
|
166
|
+
not need when every worker gets a fresh profile, and a step with no operation behind it (a drag,
|
|
167
|
+
a reload) may be the whole reason a flow is `actors: human`. Coverage is a claim about the
|
|
168
|
+
`steps`, not about every stage.
|
|
169
|
+
3. **A spec may name several flows** and a flow several specs; both sides are lists.
|
|
170
|
+
4. **The check is referential, not semantic.** It proves the two sides name each other and that the
|
|
171
|
+
named test runs; it cannot read a Playwright spec and decide whether it exercises these `steps`.
|
|
172
|
+
A test tagged `@QA-n` that asserts nothing still passes the check, so the claim that a spec
|
|
173
|
+
covers a flow is a reviewer's judgement, not a verified fact. What the flow's own `assert`s
|
|
174
|
+
verify is the `composer-qa` run, which executes these steps against the live app; nothing
|
|
175
|
+
cross-checks the two arms against each other.
|
|
176
|
+
|
|
177
|
+
### Input literals
|
|
178
|
+
|
|
179
|
+
An `invoke` is an operation key followed by a JSON-shaped input. Inside it:
|
|
180
|
+
|
|
181
|
+
| Form | Meaning | Snippet the runner emits |
|
|
182
|
+
| --- | --- | --- |
|
|
183
|
+
| `$name`, `$name.field`, `$name.snapshot.…` | a captured result or a `given` binding; any JS path over it | the held value |
|
|
184
|
+
| `$runId` | this run's id, so artifacts are attributable | the string |
|
|
185
|
+
| `Obj("echo://S/O")` | the live object at that URI | `dxos.spaces('S').db.getObjectById('O')` |
|
|
186
|
+
| `Ref("echo://S/O")` | a reference to it, for `Ref` inputs | `dxos.Ref.make(…getObjectById('O'))` |
|
|
187
|
+
| `Space("S")` | the live space, for `space` inputs | `dxos.spaces('S')` |
|
|
188
|
+
|
|
189
|
+
Placeholders may appear inside strings (`"QA: Basics $runId"`, `"root/$given.space.id/…"`). A
|
|
190
|
+
`create` operation returns a URI, not an object, precisely so that a later step can name the
|
|
191
|
+
object through `Obj(…)` after a snippet boundary. A held value that is an `echo://` URI also
|
|
192
|
+
exposes `.spaceId` and `.objectId`, parsed by the runner, so a navigation path is written
|
|
193
|
+
`"root/$space.id/content/collections/$doc.objectId"` without a step to split the URI.
|
|
194
|
+
|
|
195
|
+
### Operation references
|
|
196
|
+
|
|
197
|
+
Within the document, an operation declared here is referenced as `[op:<id>]`, which resolves via
|
|
198
|
+
that block's `key:` field (`op@1.1`).
|
|
199
|
+
|
|
200
|
+
An operation owned by **another** plugin is written as a full key literal. This is not only an
|
|
201
|
+
`APP.mdl` concern: a plugin-scoped test routinely drives `space.addObject` and `appToolkit.open`,
|
|
202
|
+
and neither is declared in the plugin's own spec.
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## The `suite` Block
|
|
207
|
+
|
|
208
|
+
```mdl
|
|
209
|
+
ext suite
|
|
210
|
+
uri: org.dxos.mdl.suite@1.0
|
|
211
|
+
desc: |
|
|
212
|
+
A named set of tests, run together and reported together. A container by reference: the
|
|
213
|
+
tests stay standalone blocks, and a suite lists them by id — `QA-1` for a test in the same
|
|
214
|
+
document, `markdown:QA-1` for another plugin's (`app:QA-1` for the application spec).
|
|
215
|
+
fields:
|
|
216
|
+
desc?: Prose
|
|
217
|
+
tags?: TagList # `run --tag nightly` selects every suite carrying the tag
|
|
218
|
+
tests: RefList # ordered for the report; execution is order-independent
|
|
219
|
+
nesting: none
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
1. **Suites are order-independent by construction.** Every test owns its fixture (`given` +
|
|
223
|
+
`before`) and its teardown (`after`), so any selection of tests is runnable in any order. There
|
|
224
|
+
is no suite-level `before`: anything every member needs — a plugin enabled, an identity — goes in
|
|
225
|
+
each test's `given`, which the runner establishes idempotently.
|
|
226
|
+
2. **Every document is an implicit suite** of its own tests, addressed by its short name
|
|
227
|
+
(`run markdown`), so a plugin needs no `suite` block to be runnable as a unit.
|
|
228
|
+
3. **Tags select suites, not tests.** `run --tag nightly` runs the union of the tests of every
|
|
229
|
+
suite tagged `nightly`, de-duplicated. A test's own `tags:` are descriptive and searchable but
|
|
230
|
+
do not put it in a run.
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## `op@1.1` — the `key` field
|
|
235
|
+
|
|
236
|
+
```mdl
|
|
237
|
+
ext op
|
|
238
|
+
uri: org.dxos.mdl.op@1.1
|
|
239
|
+
extends: op
|
|
240
|
+
adds-fields:
|
|
241
|
+
key?: NSID # runtime operation key — what the invoker receives
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Without `key`, a test cannot say which operation it means. The distinction is real and not
|
|
245
|
+
academic: `plugin-markdown` declares one `op create` but ships two runtime operations —
|
|
246
|
+
`org.dxos.operation.markdown.create` (agent-facing, `Database.Service`) and
|
|
247
|
+
`org.dxos.operation.markdown.createDraft` (the UI factory, `Capability.Service`). A test that
|
|
248
|
+
guesses picks the wrong one and fails at runtime.
|
|
249
|
+
|
|
250
|
+
The spec mirrors the code: one `op` block per runtime `Operation.make` key, with `key:` and
|
|
251
|
+
`requires:` copied from its `meta.key` and `services`. A design-level operation with no runtime
|
|
252
|
+
counterpart keeps its block without `key:` and says so in `status: unimplemented`, so a reader can
|
|
253
|
+
tell an intended operation from an existing one and a test never references it.
|
|
254
|
+
|
|
255
|
+
Populate the pre-existing `requires:` from the code's `services:` at the same time. It is
|
|
256
|
+
informational — see Execution Rule 1 — but it tells a reader why a step behaves as it does.
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
## Execution Rules
|
|
261
|
+
|
|
262
|
+
These are not style advice. Each was established by running a test against a live application;
|
|
263
|
+
a runner that ignores them produces false failures.
|
|
264
|
+
|
|
265
|
+
1. **Always invoke through the operation invoker with an explicit `spaceId`.** Do not branch on
|
|
266
|
+
`requires:`. An operation's own declaration cannot see the services its *downstream* calls
|
|
267
|
+
need, so `requires:` is necessary but not sufficient to predict whether a plain invoke will
|
|
268
|
+
work. Taking the invoker path unconditionally removes the question. The step's `space:` names
|
|
269
|
+
the space; absent, `$given.space`, else the default space.
|
|
270
|
+
|
|
271
|
+
2. **Coalesce adjacent steps that thread a live object.** The debug port serializes between
|
|
272
|
+
snippets, so an ECHO object captured in one step cannot be passed to the next. Human step
|
|
273
|
+
granularity and snippet granularity are different things, and reconciling them is the runner's
|
|
274
|
+
job, not the author's. Prefer captures that are strings (a URI, an id, a path) and `Obj(…)` in
|
|
275
|
+
the next step, which needs no coalescing at all.
|
|
276
|
+
|
|
277
|
+
3. **Verify the effect, never the return value.** A successful invocation frequently did less
|
|
278
|
+
than the step intended — a `create` operation is a factory and places nothing. Judge `expect`
|
|
279
|
+
against `$snapshot`, a query operation, or the DOM.
|
|
280
|
+
|
|
281
|
+
4. **Establish `given` or abort.** A test that runs against unmet preconditions reports failures
|
|
282
|
+
that belong to the fixture, not the application.
|
|
283
|
+
|
|
284
|
+
5. **Assertions must be falsifiable against a dirty fixture.** An existence-shaped check
|
|
285
|
+
(`some((o) => o.name === 'Notes')`) is already true when a previous run left its artifacts
|
|
286
|
+
behind, so the step reports pass having done nothing. Assert on the identity the test just
|
|
287
|
+
produced (`o.id === $created.object.id`), and name the test's own artifacts in `given` as
|
|
288
|
+
preconditions of their absence. Artifacts carry the `QA:` prefix and `$runId` in their name.
|
|
289
|
+
|
|
290
|
+
6. **Resolve an operation by its exact key, never by suffix.** `endsWith('create')` matches both
|
|
291
|
+
`org.dxos.operation.markdown.create` and `org.dxos.operation.markdown.createDraft` — the very
|
|
292
|
+
ambiguity `key:` exists to remove.
|
|
293
|
+
|
|
294
|
+
7. **Three stages, run in order: `before`, `steps`, `after` — each an array of the same `step`.**
|
|
295
|
+
Put a step in `before` only when it is fixture the test is not itself exercising. Creating the
|
|
296
|
+
subject usually IS the test: QA-2 tests that two documents can be made and linked, so the
|
|
297
|
+
creating belongs in `steps`, and `before` stays empty. `before` builds the fixture,
|
|
298
|
+
`steps` is the test, `after` undoes it. The split is what makes a partial run meaningful — and
|
|
299
|
+
what makes a failure legible, since a `before` failure is a broken fixture while a `steps`
|
|
300
|
+
failure is a defect in the application. Every stage is a step list; `after` in particular is
|
|
301
|
+
steps, not prose, and goes through operations like any other. A prose instruction ("delete the
|
|
302
|
+
document") leaves each actor to pick a mechanism, and they diverge: a human uses the navtree's
|
|
303
|
+
delete action, which routes through `space.removeObjects` and closes any open plank; a runner
|
|
304
|
+
reaching for `space.db.remove` strands a plank pointing at an object that no longer exists,
|
|
305
|
+
which the user cannot then close. `after` removes only what this run created, by identity.
|
|
306
|
+
|
|
307
|
+
8. **A partial run is the runner's option, not the test's.** A test always declares all three
|
|
308
|
+
stages; which of them to run is decided per invocation. Running `before` alone stands a fixture
|
|
309
|
+
up to look at; `after` alone tears one down; `steps` alone re-tests against a fixture already
|
|
310
|
+
standing. Whatever is skipped must be reported — what remains and how to remove it — since the
|
|
311
|
+
next full run's `given` will otherwise fail on its own leftovers (Rule 5).
|
|
312
|
+
|
|
313
|
+
9. **A step that cannot run says so in `blocked`, and the test's `status` becomes `blocked`.**
|
|
314
|
+
Not `failing` — nothing was tested — and not silence, which reads as untried. A duplicate
|
|
315
|
+
operation key, a missing capability or a removed operation all land here.
|
|
316
|
+
|
|
317
|
+
10. **Report by test and step number** — `QA-1.3`, or `QA-1.<id>` for a step declaring one — so a
|
|
318
|
+
failure is addressable without prose. Prefer the id where a step has one: it survives a step
|
|
319
|
+
being inserted ahead of it, a position does not.
|
|
320
|
+
|
|
321
|
+
11. **Snapshot after every step, and `errors` is always a finding.** The runner passes the run's
|
|
322
|
+
start time as `since`, so each snapshot reports every error logged so far; a non-empty
|
|
323
|
+
`errors` fails nothing by itself but is recorded against the step where it first appeared,
|
|
324
|
+
even when that step's own check passed. A step that means to fail on an error asserts on
|
|
325
|
+
`$stepErrors` (Field rule 5), never on `$snapshot.errors`: the cumulative array keeps one early
|
|
326
|
+
background error false for the rest of the run, which reads as every later step failing for
|
|
327
|
+
something none of them did. Both smoke runs of `app:QA-1` hit exactly that.
|
|
328
|
+
|
|
329
|
+
12. **A suite run continues past a failed test.** Each test is self-contained, so a failure in
|
|
330
|
+
one — including a failed `after` — is reported and the next test's `given` guards it. A run
|
|
331
|
+
stops early only when the app itself is gone: the port no longer answers, or the page has
|
|
332
|
+
crashed.
|
|
333
|
+
|
|
334
|
+
---
|
|
335
|
+
|
|
336
|
+
## Example
|
|
337
|
+
|
|
338
|
+
```mdl
|
|
339
|
+
test QA-1: Create a space and a document, then delete the document
|
|
340
|
+
actors: both
|
|
341
|
+
covers: [F-1.1, T-1]
|
|
342
|
+
tags: [smoke]
|
|
343
|
+
given:
|
|
344
|
+
- an identity exists and the default space is SPACE_READY
|
|
345
|
+
- no space whose name starts with "QA:" exists — ABORT rather than deleting one this test did not create
|
|
346
|
+
before:
|
|
347
|
+
- name: Create a space
|
|
348
|
+
do: Open the space list's +, name the space "QA: Basics $runId" and create it.
|
|
349
|
+
invoke: org.dxos.operation.space.create { name: "QA: Basics $runId" }
|
|
350
|
+
capture: space
|
|
351
|
+
expect: the navtree switches to the new space
|
|
352
|
+
assert: return $snapshot.spaces.some((s) => s.id === $space.id && s.state === 'SPACE_READY')
|
|
353
|
+
steps:
|
|
354
|
+
- name: Create a document
|
|
355
|
+
do: With the new space selected, click + and choose Document. Name it "QA: Doc 1".
|
|
356
|
+
invoke: org.dxos.operation.markdown.create { name: "QA: Doc 1", content: "# QA: Doc 1\n" }
|
|
357
|
+
space: $space.id
|
|
358
|
+
capture: doc
|
|
359
|
+
expect: "QA: Doc 1" appears as a row under the space
|
|
360
|
+
assert: |
|
|
361
|
+
const docs = await composer.invoke('org.dxos.operation.space.queryObjects',
|
|
362
|
+
{ typename: 'org.dxos.type.document' }, { spaceId: $space.id });
|
|
363
|
+
return docs.some((o) => o.id === $doc.id);
|
|
364
|
+
- name: Delete it
|
|
365
|
+
do: Open the row's ⋮ menu and choose Delete.
|
|
366
|
+
invoke: org.dxos.operation.space.removeObjects { objects: [Obj($doc.id)] }
|
|
367
|
+
space: $space.id
|
|
368
|
+
expect: a "Document deleted" toast with Undo appears and the row is gone
|
|
369
|
+
assert: return $snapshot.toasts.some((t) => t.title === 'Document deleted') && $stepErrors.length === 0
|
|
370
|
+
after:
|
|
371
|
+
- name: Delete the space
|
|
372
|
+
do: Open the space's settings and delete the space; pick the default space.
|
|
373
|
+
invoke: org.dxos.operation.space.delete { space: Space($space.id) }
|
|
374
|
+
expect: no "QA:" space remains and the workspace is the default space
|
|
375
|
+
assert: return !$snapshot.spaces.some((s) => s.name?.startsWith('QA:'))
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
```mdl
|
|
379
|
+
suite smoke: Boots, one space, one document
|
|
380
|
+
desc: The five-minute check a Routine runs on every merge to main.
|
|
381
|
+
tags: [smoke, nightly]
|
|
382
|
+
tests: [QA-1]
|
|
383
|
+
```
|
package/lang/review.mdl
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: org.dxos.spec.review
|
|
3
|
+
name: DSL.Review
|
|
4
|
+
version: 1.0
|
|
5
|
+
extends:
|
|
6
|
+
- org.dxos.spec.core
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
The review dialect. A review is a separate document that judges how far the code meets a spec, item
|
|
10
|
+
by item. It is written by an agent (the `spec-review` skill) or a person, and lives beside the spec
|
|
11
|
+
it judges: `PLUGIN.mdl` → `PLUGIN.review.mdl`. Each new review replaces the previous file; git keeps
|
|
12
|
+
the history. The spec viewer reads the latest review and marks each judged item with its status.
|
|
13
|
+
|
|
14
|
+
A review is evidence, not a decision: it never changes the spec, and it adds no changelog entry.
|
|
15
|
+
|
|
16
|
+
## Extensions
|
|
17
|
+
|
|
18
|
+
| Term | URI |
|
|
19
|
+
| --------- | --------------------------- |
|
|
20
|
+
| `verdict` | `org.dxos.mdl.verdict@1.0` |
|
|
21
|
+
|
|
22
|
+
## Document
|
|
23
|
+
|
|
24
|
+
Frontmatter names what was reviewed and against what:
|
|
25
|
+
|
|
26
|
+
```yaml
|
|
27
|
+
---
|
|
28
|
+
spec: github:dxos/dxos/packages/plugins/plugin-file-system/PLUGIN.mdl
|
|
29
|
+
commit: 64dcf3f44a541fdf0b3e55803f38d214e76a6279 # the code the review read
|
|
30
|
+
date: 2026-10-22
|
|
31
|
+
by: agent:claude-code # same actor forms as the changelog
|
|
32
|
+
---
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The body opens with a short summary, then one `verdict` per reviewed item.
|
|
36
|
+
|
|
37
|
+
## Statuses
|
|
38
|
+
|
|
39
|
+
| Status | Meaning |
|
|
40
|
+
| ---------- | ------------------------------------------------------------------------ |
|
|
41
|
+
| `done` | The code does what the item says. |
|
|
42
|
+
| `untested` | The code does it, but no test exercises it. |
|
|
43
|
+
| `partial` | Some of what the item says is done; the note says which part is not. |
|
|
44
|
+
| `diverged` | The code does something different from what the item says. |
|
|
45
|
+
| `missing` | Nothing in the code does it. |
|
|
46
|
+
|
|
47
|
+
The spec viewer shows beside each judged item whether code covers it (its `evidence:`, or "no code")
|
|
48
|
+
and whether tests exercise it: `tested` when the verdict names `tests:` or is `done`, `untested` for
|
|
49
|
+
any other status but `missing`, where there is no code to test.
|
|
50
|
+
|
|
51
|
+
## Tests and scenarios
|
|
52
|
+
|
|
53
|
+
A `scenario` or a `test` block describes behaviour to exercise, so it is judged on whether
|
|
54
|
+
automation exercises it, not on whether code implements it:
|
|
55
|
+
|
|
56
|
+
| Status | For a `scenario` or `test` |
|
|
57
|
+
| ---------- | --------------------------------------------------------------------------- |
|
|
58
|
+
| `done` | An automated test runs it end to end; `tests:` cites that test. |
|
|
59
|
+
| `partial` | A test covers some of its steps or `then:` clauses; the note says which. |
|
|
60
|
+
| `diverged` | A test runs something different from what it describes. |
|
|
61
|
+
| `missing` | Nothing runs it (a manual QA run is not automation). |
|
|
62
|
+
|
|
63
|
+
`untested` does not apply. `tests:` names the test files that exercise it and is required for
|
|
64
|
+
`done`, `partial` and `diverged`; `evidence:` may name the code it drives. The viewer shows
|
|
65
|
+
`tested`, `partly tested` or `not tested` beside it, with a chip per test file.
|
|
66
|
+
|
|
67
|
+
## Walkthrough
|
|
68
|
+
|
|
69
|
+
When an item is implemented in more than one place, the verdict carries a `walkthrough:`: 1 to 5
|
|
70
|
+
segments, in reading order, that say where each part is implemented. Each segment is one
|
|
71
|
+
sentence followed by the `github:` key of the code it describes; the viewer shows the sentence
|
|
72
|
+
above the declaration the key names, linked to its file. Keep each sentence to what the code
|
|
73
|
+
does for this item, not how it works line by line.
|
|
74
|
+
|
|
75
|
+
- A `type` needs none: its one declaration is the hover card of its code chip.
|
|
76
|
+
- An `op` walks its declaration (the schema), then each handler.
|
|
77
|
+
- A `feat` or `req` walks the pieces in the order a request passes through them.
|
|
78
|
+
|
|
79
|
+
An item with a single implementation gets no walkthrough.
|
|
80
|
+
|
|
81
|
+
A `feat` with nested `req` items is judged through its requirements; its status is the worst of
|
|
82
|
+
theirs. Judge a `feat` directly only when it has no requirements.
|
|
83
|
+
|
|
84
|
+
## Definitions
|
|
85
|
+
|
|
86
|
+
```mdl
|
|
87
|
+
ext verdict
|
|
88
|
+
uri: org.dxos.mdl.verdict@1.0
|
|
89
|
+
desc: |
|
|
90
|
+
How far the code meets one spec item. The identifier is the item's id in the reviewed spec
|
|
91
|
+
(`F-1.2`, `Scene`, `openDirectory`); the inline prose is the verdict in one line.
|
|
92
|
+
fields:
|
|
93
|
+
status: done | untested | partial | diverged | missing
|
|
94
|
+
evidence?: RefList # github: keys of the code that supports the verdict, with #Symbol
|
|
95
|
+
tests?: RefList # github: keys of the test files that exercise the item, without #
|
|
96
|
+
walkthrough?: ProseList # 1-5 items `- <one sentence>. github:<key>`, when there is more than one implementation
|
|
97
|
+
note?: Prose # what is missing or different; required unless status is done
|
|
98
|
+
syntax: |
|
|
99
|
+
verdict F-1.2: The picker opens on the action.
|
|
100
|
+
status: done
|
|
101
|
+
evidence: [github:dxos/dxos/packages/plugins/plugin-file-system/src/util.ts#openDirectoryPicker]
|
|
102
|
+
tests: [github:dxos/dxos/packages/plugins/plugin-file-system/src/util.test.ts]
|
|
103
|
+
```
|
package/lang/sql.mdl
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: org.dxos.spec.sql
|
|
3
|
+
name: DSL.Sql
|
|
4
|
+
version: 1.0
|
|
5
|
+
extends:
|
|
6
|
+
- org.dxos.spec.core
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
The SQL dialect: one `table` block that declares a SQL table a component owns — its columns, key,
|
|
10
|
+
indexes, and the migration set that creates it. Before this dialect a spec named its tables only in
|
|
11
|
+
prose ("a new migration adds the column"), so a reviewer could not see the schema a requirement
|
|
12
|
+
relies on, and a spec review could not judge it.
|
|
13
|
+
|
|
14
|
+
A `table` block states the schema as it is after the spec's changes, not the history: the history is
|
|
15
|
+
the numbered migrations in the code, and the reasons are in the changelog. Use `type` for an ECHO
|
|
16
|
+
schema; a `table` is a store-level SQL table that is not an ECHO object.
|
|
17
|
+
|
|
18
|
+
## Extensions
|
|
19
|
+
|
|
20
|
+
| Term | URI |
|
|
21
|
+
| ------- | ------------------------- |
|
|
22
|
+
| `table` | `org.dxos.mdl.table@1.0` |
|
|
23
|
+
|
|
24
|
+
## Model
|
|
25
|
+
|
|
26
|
+
- **The identifier is the table name**, exactly as in the DDL (`feeds`, `convergenceKeyIntents`).
|
|
27
|
+
The inline prose says what one row is.
|
|
28
|
+
- **`columns:`** has one line per column: `name: SQLTYPE [constraint …] # meaning`.
|
|
29
|
+
- `SQLTYPE` is a SQLite storage class: `INTEGER`, `REAL`, `TEXT` or `BLOB`. A column that holds
|
|
30
|
+
JSON is `TEXT` with `json` in its comment and the TypeScript type it decodes to.
|
|
31
|
+
- A trailing `?` on the name means `NULL` is allowed (`feedNamespace?: TEXT`); without it the
|
|
32
|
+
column is `NOT NULL`.
|
|
33
|
+
- Constraints are written as in SQL: `PRIMARY KEY`, `AUTOINCREMENT`, `UNIQUE`, `DEFAULT <value>`,
|
|
34
|
+
`REFERENCES <table>(<column>)`.
|
|
35
|
+
- **`key:`** names the primary key, and `unique:` any other unique keys, as column lists.
|
|
36
|
+
- **`indexes:`** has one line per secondary index: `name(columns)` and why a query needs it.
|
|
37
|
+
- **`store:`** names the database the table lives in and, in parentheses, its migration-history table
|
|
38
|
+
(`feed store (feed_migrations)`), so the reader knows which migrations change it. A spec names
|
|
39
|
+
components and specs, never file paths: the code moves, the names stay.
|
|
40
|
+
- **`new:`** marks a table or columns the spec adds: `table` for a new table, or the list of new
|
|
41
|
+
columns. A spec review checks that a migration adds each of them.
|
|
42
|
+
- A `table` is a spec item: a requirement cites it as `table:feeds` or a column as
|
|
43
|
+
`table:feeds.options`, a review can judge it (`verdict table:feeds`), and a `github:` key may
|
|
44
|
+
point at the migration that creates it.
|
|
45
|
+
|
|
46
|
+
## Definitions
|
|
47
|
+
|
|
48
|
+
```mdl
|
|
49
|
+
ext table
|
|
50
|
+
uri: org.dxos.mdl.table@1.0
|
|
51
|
+
desc: |
|
|
52
|
+
A SQL table a component owns. The identifier is the table name; the inline prose is what one row
|
|
53
|
+
is. Columns, keys and indexes are the schema after the spec's changes.
|
|
54
|
+
fields:
|
|
55
|
+
store: Prose # the database, and its migration-history table in parentheses
|
|
56
|
+
columns: FieldMap # `name[?]: SQLTYPE [constraint …] # meaning`; `?` allows NULL
|
|
57
|
+
key?: Prose # the primary key, as a column list
|
|
58
|
+
unique?: ProseList # other unique keys, as column lists
|
|
59
|
+
indexes?: ProseList # `name(columns): why a query needs it`
|
|
60
|
+
new?: Prose # `table`, or the columns this spec adds
|
|
61
|
+
inline-prose: true
|
|
62
|
+
syntax: |
|
|
63
|
+
table feeds: One feed of a space, by namespace.
|
|
64
|
+
store: feed store (feed_migrations)
|
|
65
|
+
columns:
|
|
66
|
+
feedPrivateId: INTEGER PRIMARY KEY AUTOINCREMENT # local row id; blocks reference it
|
|
67
|
+
spaceId: TEXT
|
|
68
|
+
feedId: TEXT # the Feed object's entity id
|
|
69
|
+
options?: TEXT # json FeedOptions; NULL = defaults
|
|
70
|
+
key: feedPrivateId
|
|
71
|
+
new: options
|
|
72
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,77 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dxos/deus",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"description": "Deus — pattern specification language for human-agent collaborative software development. Carries the .mdl grammar, CodeMirror extension, and core dialects.",
|
|
5
|
+
"homepage": "https://dxos.org",
|
|
6
|
+
"bugs": "https://github.com/dxos/dxos/issues",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "https://github.com/dxos/dxos"
|
|
10
|
+
},
|
|
11
|
+
"license": "FSL-1.1-Apache-2.0",
|
|
12
|
+
"author": "info@dxos.org",
|
|
13
|
+
"sideEffects": false,
|
|
14
|
+
"type": "module",
|
|
15
|
+
"exports": {
|
|
16
|
+
".": {
|
|
17
|
+
"source": "./src/index.ts",
|
|
18
|
+
"types": "./dist/types/src/index.d.ts",
|
|
19
|
+
"import": "./dist/lib/index.mjs"
|
|
20
|
+
},
|
|
21
|
+
"./extension": {
|
|
22
|
+
"source": "./src/extension/index.ts",
|
|
23
|
+
"types": "./dist/types/src/extension/index.d.ts",
|
|
24
|
+
"import": "./dist/lib/extension.mjs"
|
|
25
|
+
},
|
|
26
|
+
"./parse": {
|
|
27
|
+
"source": "./src/extension/parse.ts",
|
|
28
|
+
"types": "./dist/types/src/extension/parse.d.ts",
|
|
29
|
+
"import": "./dist/lib/parse.mjs"
|
|
30
|
+
},
|
|
31
|
+
"./review": {
|
|
32
|
+
"source": "./src/review/index.ts",
|
|
33
|
+
"types": "./dist/types/src/review/index.d.ts",
|
|
34
|
+
"import": "./dist/lib/review.mjs"
|
|
35
|
+
},
|
|
36
|
+
"./spec-index": {
|
|
37
|
+
"source": "./src/spec-index/index.ts",
|
|
38
|
+
"types": "./dist/types/src/spec-index/index.d.ts",
|
|
39
|
+
"import": "./dist/lib/spec-index.mjs"
|
|
40
|
+
},
|
|
41
|
+
"./cli": {
|
|
42
|
+
"source": "./src/cli/index.ts",
|
|
43
|
+
"types": "./dist/types/src/cli/index.d.ts",
|
|
44
|
+
"import": "./dist/lib/cli.mjs"
|
|
45
|
+
}
|
|
46
|
+
},
|
|
47
|
+
"bin": {
|
|
48
|
+
"deus": "./bin/deus.ts"
|
|
49
|
+
},
|
|
50
|
+
"files": [
|
|
51
|
+
"bin",
|
|
52
|
+
"dist",
|
|
53
|
+
"docs",
|
|
54
|
+
"lang",
|
|
55
|
+
"src"
|
|
56
|
+
],
|
|
57
|
+
"dependencies": {
|
|
58
|
+
"@codemirror/autocomplete": "^6.20.3",
|
|
59
|
+
"@codemirror/language": "^6.12.4",
|
|
60
|
+
"@codemirror/lint": "6.9.7",
|
|
61
|
+
"@codemirror/state": "^6.7.6",
|
|
62
|
+
"@codemirror/view": "^6.43.13",
|
|
63
|
+
"@effect/platform-node": "4.0.4",
|
|
64
|
+
"@lezer/highlight": "^1.2.3",
|
|
65
|
+
"@lezer/lr": "^1.4.10",
|
|
66
|
+
"effect": "4.0.4",
|
|
67
|
+
"@dxos/errors": "0.16.0"
|
|
68
|
+
},
|
|
69
|
+
"devDependencies": {
|
|
70
|
+
"@lezer/generator": "^1.8.0",
|
|
71
|
+
"typescript": "^7.0.2",
|
|
72
|
+
"vitest": "4.1.10"
|
|
73
|
+
},
|
|
74
|
+
"publishConfig": {
|
|
75
|
+
"access": "public"
|
|
76
|
+
}
|
|
6
77
|
}
|