@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.
Files changed (201) hide show
  1. package/LICENSE +105 -0
  2. package/README.md +24 -2
  3. package/bin/deus.ts +42 -0
  4. package/dist/lib/chunk-blocks.mjs +151 -0
  5. package/dist/lib/chunk-blocks.mjs.map +1 -0
  6. package/dist/lib/chunk-check.mjs +452 -0
  7. package/dist/lib/chunk-check.mjs.map +1 -0
  8. package/dist/lib/chunk-completion.mjs +112 -0
  9. package/dist/lib/chunk-completion.mjs.map +1 -0
  10. package/dist/lib/chunk-extension.mjs +396 -0
  11. package/dist/lib/chunk-extension.mjs.map +1 -0
  12. package/dist/lib/chunk-parse.mjs +21 -0
  13. package/dist/lib/chunk-parse.mjs.map +1 -0
  14. package/dist/lib/cli.mjs +946 -0
  15. package/dist/lib/cli.mjs.map +1 -0
  16. package/dist/lib/extension.mjs +4 -0
  17. package/dist/lib/index.mjs +6 -0
  18. package/dist/lib/parse.mjs +4 -0
  19. package/dist/lib/review.mjs +260 -0
  20. package/dist/lib/review.mjs.map +1 -0
  21. package/dist/lib/spec-index.mjs +28 -0
  22. package/dist/lib/spec-index.mjs.map +1 -0
  23. package/dist/types/bin/deus.d.ts +3 -0
  24. package/dist/types/bin/deus.d.ts.map +1 -0
  25. package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts +8 -0
  26. package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts.map +1 -0
  27. package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts +8 -0
  28. package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts.map +1 -0
  29. package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts +7 -0
  30. package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts.map +1 -0
  31. package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts +8 -0
  32. package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts.map +1 -0
  33. package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts +5 -0
  34. package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts.map +1 -0
  35. package/dist/types/src/cli/changelog.d.ts +25 -0
  36. package/dist/types/src/cli/changelog.d.ts.map +1 -0
  37. package/dist/types/src/cli/cli.test.d.ts +2 -0
  38. package/dist/types/src/cli/cli.test.d.ts.map +1 -0
  39. package/dist/types/src/cli/errors.d.ts +183 -0
  40. package/dist/types/src/cli/errors.d.ts.map +1 -0
  41. package/dist/types/src/cli/features.d.ts +58 -0
  42. package/dist/types/src/cli/features.d.ts.map +1 -0
  43. package/dist/types/src/cli/git.d.ts +8 -0
  44. package/dist/types/src/cli/git.d.ts.map +1 -0
  45. package/dist/types/src/cli/index.d.ts +12 -0
  46. package/dist/types/src/cli/index.d.ts.map +1 -0
  47. package/dist/types/src/cli/lint.d.ts +17 -0
  48. package/dist/types/src/cli/lint.d.ts.map +1 -0
  49. package/dist/types/src/cli/qa-lint.d.ts +40 -0
  50. package/dist/types/src/cli/qa-lint.d.ts.map +1 -0
  51. package/dist/types/src/cli/qa.d.ts +86 -0
  52. package/dist/types/src/cli/qa.d.ts.map +1 -0
  53. package/dist/types/src/cli/review.d.ts +38 -0
  54. package/dist/types/src/cli/review.d.ts.map +1 -0
  55. package/dist/types/src/cli/spec-index.d.ts +17 -0
  56. package/dist/types/src/cli/spec-index.d.ts.map +1 -0
  57. package/dist/types/src/extension/blocks.d.ts +65 -0
  58. package/dist/types/src/extension/blocks.d.ts.map +1 -0
  59. package/dist/types/src/extension/check.d.ts +99 -0
  60. package/dist/types/src/extension/check.d.ts.map +1 -0
  61. package/dist/types/src/extension/check.test.d.ts +2 -0
  62. package/dist/types/src/extension/check.test.d.ts.map +1 -0
  63. package/dist/types/src/extension/code.d.ts +7 -0
  64. package/dist/types/src/extension/code.d.ts.map +1 -0
  65. package/dist/types/src/extension/complete.d.ts +6 -0
  66. package/dist/types/src/extension/complete.d.ts.map +1 -0
  67. package/dist/types/src/extension/completion.d.ts +10 -0
  68. package/dist/types/src/extension/completion.d.ts.map +1 -0
  69. package/dist/types/src/extension/constants.d.ts +6 -0
  70. package/dist/types/src/extension/constants.d.ts.map +1 -0
  71. package/dist/types/src/extension/fences.d.ts +10 -0
  72. package/dist/types/src/extension/fences.d.ts.map +1 -0
  73. package/dist/types/src/extension/gen/mdl.d.ts +3 -0
  74. package/dist/types/src/extension/gen/mdl.d.ts.map +1 -0
  75. package/dist/types/src/extension/gen/mdl.terms.d.ts +2 -0
  76. package/dist/types/src/extension/gen/mdl.terms.d.ts.map +1 -0
  77. package/dist/types/src/extension/index.d.ts +8 -0
  78. package/dist/types/src/extension/index.d.ts.map +1 -0
  79. package/dist/types/src/extension/language.d.ts +20 -0
  80. package/dist/types/src/extension/language.d.ts.map +1 -0
  81. package/dist/types/src/extension/lint.d.ts +8 -0
  82. package/dist/types/src/extension/lint.d.ts.map +1 -0
  83. package/dist/types/src/extension/parse.d.ts +6 -0
  84. package/dist/types/src/extension/parse.d.ts.map +1 -0
  85. package/dist/types/src/extension/parser.test.d.ts +2 -0
  86. package/dist/types/src/extension/parser.test.d.ts.map +1 -0
  87. package/dist/types/src/extension/refs.d.ts +32 -0
  88. package/dist/types/src/extension/refs.d.ts.map +1 -0
  89. package/dist/types/src/extension/refs.test.d.ts +2 -0
  90. package/dist/types/src/extension/refs.test.d.ts.map +1 -0
  91. package/dist/types/src/extension/syntax.d.ts +12 -0
  92. package/dist/types/src/extension/syntax.d.ts.map +1 -0
  93. package/dist/types/src/index.d.ts +3 -0
  94. package/dist/types/src/index.d.ts.map +1 -0
  95. package/dist/types/src/review/fields.d.ts +9 -0
  96. package/dist/types/src/review/fields.d.ts.map +1 -0
  97. package/dist/types/src/review/index.d.ts +5 -0
  98. package/dist/types/src/review/index.d.ts.map +1 -0
  99. package/dist/types/src/review/review.d.ts +70 -0
  100. package/dist/types/src/review/review.d.ts.map +1 -0
  101. package/dist/types/src/review/review.test.d.ts +2 -0
  102. package/dist/types/src/review/review.test.d.ts.map +1 -0
  103. package/dist/types/src/review/source-key.d.ts +35 -0
  104. package/dist/types/src/review/source-key.d.ts.map +1 -0
  105. package/dist/types/src/review/symbol.d.ts +17 -0
  106. package/dist/types/src/review/symbol.d.ts.map +1 -0
  107. package/dist/types/src/review/symbol.test.d.ts +2 -0
  108. package/dist/types/src/review/symbol.test.d.ts.map +1 -0
  109. package/dist/types/src/spec-index/index.d.ts +3 -0
  110. package/dist/types/src/spec-index/index.d.ts.map +1 -0
  111. package/dist/types/src/spec-index/parse.d.ts +11 -0
  112. package/dist/types/src/spec-index/parse.d.ts.map +1 -0
  113. package/dist/types/src/spec-index/spec-index.d.ts +21 -0
  114. package/dist/types/src/spec-index/spec-index.d.ts.map +1 -0
  115. package/dist/types/src/spec-index/spec-index.test.d.ts +2 -0
  116. package/dist/types/src/spec-index/spec-index.test.d.ts.map +1 -0
  117. package/dist/types/tsconfig.tsbuildinfo +1 -0
  118. package/docs/DESIGN.md +561 -0
  119. package/docs/IDIOMS.md +265 -0
  120. package/lang/PLUGIN-.template.mdl +115 -0
  121. package/lang/app.mdl +200 -0
  122. package/lang/changelog.mdl +184 -0
  123. package/lang/core.mdl +203 -0
  124. package/lang/examples/chess-1.mdl +149 -0
  125. package/lang/examples/chess-2.mdl +203 -0
  126. package/lang/examples/chess-3.mdl +231 -0
  127. package/lang/features.mdl +92 -0
  128. package/lang/plugin.mdl +59 -0
  129. package/lang/qa.mdl +383 -0
  130. package/lang/review.mdl +103 -0
  131. package/lang/sql.mdl +72 -0
  132. package/package.json +74 -3
  133. package/src/cli/__fixtures__/bad-decision.mdl +13 -0
  134. package/src/cli/__fixtures__/features/CYCLE.mdl +25 -0
  135. package/src/cli/__fixtures__/features/FEATURES.mdl +47 -0
  136. package/src/cli/__fixtures__/features/SPEC.mdl +22 -0
  137. package/src/cli/__fixtures__/features/SPEC.review.mdl +32 -0
  138. package/src/cli/__fixtures__/features/TASKS.md +5 -0
  139. package/src/cli/__fixtures__/lint-refs/SPEC.mdl +7 -0
  140. package/src/cli/__fixtures__/lint-refs/SPEC.review.mdl +7 -0
  141. package/src/cli/__fixtures__/qa-lint/packages/plugins/plugin-risky/PLUGIN.mdl +29 -0
  142. package/src/cli/__fixtures__/qa-list/plugin-sample/spec/PLUGIN.mdl +51 -0
  143. package/src/cli/__fixtures__/review/SPEC.mdl +23 -0
  144. package/src/cli/__fixtures__/review/SPEC.review.mdl +26 -0
  145. package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.mdl +9 -0
  146. package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.review.mdl +13 -0
  147. package/src/cli/__fixtures__/review/plugin-deps/dx.config.ts +10 -0
  148. package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.mdl +9 -0
  149. package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.review.mdl +14 -0
  150. package/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.ts +10 -0
  151. package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.mdl +9 -0
  152. package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.review.mdl +13 -0
  153. package/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.ts +9 -0
  154. package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.mdl +9 -0
  155. package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.review.mdl +13 -0
  156. package/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.ts +10 -0
  157. package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.mdl +9 -0
  158. package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.review.mdl +13 -0
  159. package/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.ts +7 -0
  160. package/src/cli/changelog.ts +122 -0
  161. package/src/cli/cli.test.ts +359 -0
  162. package/src/cli/errors.ts +23 -0
  163. package/src/cli/features.ts +320 -0
  164. package/src/cli/git.ts +35 -0
  165. package/src/cli/index.ts +27 -0
  166. package/src/cli/lint.ts +75 -0
  167. package/src/cli/qa-lint.ts +206 -0
  168. package/src/cli/qa.ts +300 -0
  169. package/src/cli/review.ts +359 -0
  170. package/src/cli/spec-index.ts +54 -0
  171. package/src/extension/blocks.ts +169 -0
  172. package/src/extension/check.test.ts +629 -0
  173. package/src/extension/check.ts +552 -0
  174. package/src/extension/code.ts +99 -0
  175. package/src/extension/complete.ts +34 -0
  176. package/src/extension/completion.ts +64 -0
  177. package/src/extension/constants.ts +28 -0
  178. package/src/extension/fences.ts +270 -0
  179. package/src/extension/gen/mdl.terms.ts +16 -0
  180. package/src/extension/gen/mdl.ts +16 -0
  181. package/src/extension/index.ts +25 -0
  182. package/src/extension/language.ts +33 -0
  183. package/src/extension/lint.ts +19 -0
  184. package/src/extension/mdl.grammar +60 -0
  185. package/src/extension/parse.ts +31 -0
  186. package/src/extension/parser.test.ts +248 -0
  187. package/src/extension/refs.test.ts +95 -0
  188. package/src/extension/refs.ts +94 -0
  189. package/src/extension/syntax.ts +25 -0
  190. package/src/index.ts +6 -0
  191. package/src/review/fields.ts +31 -0
  192. package/src/review/index.ts +8 -0
  193. package/src/review/review.test.ts +111 -0
  194. package/src/review/review.ts +184 -0
  195. package/src/review/source-key.ts +63 -0
  196. package/src/review/symbol.test.ts +47 -0
  197. package/src/review/symbol.ts +96 -0
  198. package/src/spec-index/index.ts +6 -0
  199. package/src/spec-index/parse.ts +22 -0
  200. package/src/spec-index/spec-index.test.ts +56 -0
  201. package/src/spec-index/spec-index.ts +49 -0
package/src/cli/qa.ts ADDED
@@ -0,0 +1,300 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import * as Argument from 'effect/cli/Argument';
6
+ import * as Command from 'effect/cli/Command';
7
+ import * as Flag from 'effect/cli/Flag';
8
+ import * as Config from 'effect/Config';
9
+ import * as Console from 'effect/Console';
10
+ import * as Context from 'effect/Context';
11
+ import * as Effect from 'effect/Effect';
12
+ import * as FileSystem from 'effect/FileSystem';
13
+ import * as Option from 'effect/Option';
14
+ import * as Path from 'effect/Path';
15
+
16
+ import { qaLint } from './qa-lint.ts';
17
+
18
+ /**
19
+ * Whether a host CLI asked for JSON output. `dx` declares `--json` as a shared root flag, which consumes it before
20
+ * `dx deus qa list` sees its own, so `dx` provides this instead.
21
+ */
22
+ export const JsonOutput: Context.Reference<boolean> = Context.Reference<boolean>('@dxos/deus/JsonOutput', {
23
+ defaultValue: () => false,
24
+ });
25
+
26
+ // Enumerates the executable `test QA-n` blocks and the `suite` blocks that group them across the repo's `.mdl` specs
27
+ // (the Deus.QA dialect, `lang/qa.mdl`). Deliberately regex-based rather than a real parser: the block grammar is still
28
+ // settling, and a listing that breaks on an unparsed field is worse than one that reports what it found.
29
+
30
+ /** Directories never searched; `__fixtures__` hold test inputs, not runnable plans. */
31
+ const SKIP = new Set(['node_modules', 'dist', '.git', '.moon', 'out', 'temp', '.cache', '__fixtures__']);
32
+
33
+ const STAGES = ['before', 'steps', 'after'] as const;
34
+
35
+ type Stage = (typeof STAGES)[number];
36
+
37
+ export type StageCounts = Record<Stage, number>;
38
+
39
+ export type QaTest = {
40
+ file: string;
41
+ plugin: string;
42
+ id: string;
43
+ title: string;
44
+ status: string;
45
+ actors: string;
46
+ /** Per stage, so a partial run's size is visible; `steps` is the test, the other two are fixture. */
47
+ stages: StageCounts;
48
+ covers: string;
49
+ tags: string[];
50
+ };
51
+
52
+ export type TestRef = { plugin: string; id: string };
53
+
54
+ export type QaSuite = {
55
+ file: string;
56
+ plugin: string;
57
+ id: string;
58
+ title: string;
59
+ tags: string[];
60
+ tests: TestRef[];
61
+ };
62
+
63
+ export type QaDocument = { file: string; text: string };
64
+
65
+ type Block = { file: string; plugin: string; id: string; title: string; body: string };
66
+
67
+ /** Steps per stage. A stage header sits at two spaces; its steps are `- name:`/`- do:` at four. */
68
+ const countStages = (body: string): StageCounts => {
69
+ const counts: StageCounts = { before: 0, steps: 0, after: 0 };
70
+ let stage: Stage | undefined;
71
+ for (const line of body.split('\n')) {
72
+ const header = line.match(/^ {2}(\w+):\s*$/);
73
+ if (header) {
74
+ stage = STAGES.find((candidate) => candidate === header[1]);
75
+ continue;
76
+ }
77
+ if (stage && /^ {4}- +(?:name|do):/.test(line)) {
78
+ counts[stage]++;
79
+ }
80
+ }
81
+ return counts;
82
+ };
83
+
84
+ /** The short name a test or suite is addressed by: `markdown` for plugin-markdown, `app` for APP.mdl. */
85
+ export const shortName = (file: string): string =>
86
+ file.match(/plugin-([\w-]+)\//)?.[1] ?? (file.endsWith('APP.mdl') ? 'app' : file.replace(/\.mdl$/, ''));
87
+
88
+ const parseList = (value: string | undefined): string[] =>
89
+ (value ?? '')
90
+ .split(',')
91
+ .map((item) => item.trim())
92
+ .filter(Boolean);
93
+
94
+ /** Blocks of one kind in a document. Several blocks may share one fence, so headers are matched per line. */
95
+ const parseBlocks = (text: string, file: string, kind: string): Block[] =>
96
+ [...text.matchAll(/```mdl\n([\s\S]*?)```/g)].flatMap(([, fence]) => {
97
+ const headers = [...fence.matchAll(new RegExp(`^${kind}\\s+([\\w.-]+)\\s*(?::\\s*(.*))?$`, 'gm'))];
98
+ return headers.map((header, index) => ({
99
+ file,
100
+ plugin: shortName(file),
101
+ id: header[1],
102
+ title: (header[2] ?? '').trim(),
103
+ body: fence.slice(header.index, headers[index + 1]?.index ?? fence.length),
104
+ }));
105
+ });
106
+
107
+ export const parseTests = (text: string, file: string): QaTest[] =>
108
+ parseBlocks(text, file, 'test').map(({ body, ...block }) => ({
109
+ ...block,
110
+ status: body.match(/^\s*status:\s*(\w+)/m)?.[1] ?? 'unverified',
111
+ actors: body.match(/^\s*actors:\s*([\w|\s]+?)\s*$/m)?.[1]?.trim() ?? 'both',
112
+ stages: countStages(body),
113
+ covers: body.match(/^\s*covers:\s*\[(.*?)\]/m)?.[1] ?? '',
114
+ tags: parseList(body.match(/^\s*tags:\s*\[(.*?)\]/m)?.[1]),
115
+ }));
116
+
117
+ export const parseSuites = (text: string, file: string): QaSuite[] =>
118
+ parseBlocks(text, file, 'suite').map(({ body, ...block }) => ({
119
+ ...block,
120
+ tags: parseList(body.match(/^\s*tags:\s*\[(.*?)\]/m)?.[1]),
121
+ // A bare `QA-1` is this document's test; `markdown:QA-1` names another plugin's.
122
+ tests: parseList(body.match(/^\s*tests:\s*\[(.*?)\]/m)?.[1]).map((ref) => {
123
+ const [plugin, id] = ref.includes(':') ? ref.split(':') : [block.plugin, ref];
124
+ return { plugin, id };
125
+ }),
126
+ }));
127
+
128
+ /**
129
+ * A dialect definition (`org.dxos.spec.*`) carries example tests to document its own syntax; those are illustrations,
130
+ * not plans, and listing them as runnable is a trap.
131
+ */
132
+ export const isDialect = (text: string): boolean => /^id:\s*org\.dxos\.spec\./m.test(text.split('---')[1] ?? '');
133
+
134
+ export type QaQuery = {
135
+ /** `[<plugin> <testId>]` resolves exactly; a single value is a substring filter over path, id and title. */
136
+ query: readonly string[];
137
+ tag: Option.Option<string>;
138
+ suite: Option.Option<string>;
139
+ suites: boolean;
140
+ };
141
+
142
+ export type QaSelection = { kind: 'tests'; rows: QaTest[] } | { kind: 'suites'; rows: QaSuite[] };
143
+
144
+ /** The tests a suite names, in its order; a ref that resolves to nothing is reported as `missing`, not dropped. */
145
+ const resolveSuite = (tests: QaTest[], suite: QaSuite): QaTest[] =>
146
+ suite.tests.map(
147
+ (ref) =>
148
+ tests.find((candidate) => candidate.plugin === ref.plugin && candidate.id === ref.id) ?? {
149
+ file: suite.file,
150
+ plugin: ref.plugin,
151
+ id: ref.id,
152
+ title: '(unresolved)',
153
+ status: 'missing',
154
+ actors: 'both',
155
+ stages: { before: 0, steps: 0, after: 0 },
156
+ covers: '',
157
+ tags: [],
158
+ },
159
+ );
160
+
161
+ /** Selects the tests (or suites) a query names from the parsed documents. */
162
+ export const selectQa = (documents: readonly QaDocument[], { query, tag, suite, suites: listSuites }: QaQuery) => {
163
+ const specs = documents.filter(({ text }) => !isDialect(text));
164
+ const tests = specs.flatMap(({ file, text }) => parseTests(text, file));
165
+ const suites = specs.flatMap(({ file, text }) => parseSuites(text, file));
166
+
167
+ // Two positionals resolve exactly — `<plugin> <testId>`. One is the loose substring filter, and a test id alone is
168
+ // genuinely ambiguous: QA-1 exists in more than one plugin.
169
+ const [plugin, testId] = query.length >= 2 ? query : [undefined, undefined];
170
+ const filter = query.length >= 2 ? undefined : query[0];
171
+ const matchesPlugin = (item: { plugin: string }) => !plugin || item.plugin === plugin.replace(/^plugin-/, '');
172
+ const matchesFilter = (item: { file: string; id: string; title: string }) =>
173
+ !filter || `${item.file} ${item.id} ${item.title}`.toLowerCase().includes(filter.toLowerCase());
174
+
175
+ let selectedSuites = suites.filter(matchesPlugin).filter(matchesFilter);
176
+ if (Option.isSome(tag)) {
177
+ selectedSuites = suites.filter((candidate) => candidate.tags.includes(tag.value));
178
+ }
179
+ if (Option.isSome(suite)) {
180
+ selectedSuites = suites.filter((candidate) => candidate.id === suite.value);
181
+ }
182
+
183
+ const description = plugin
184
+ ? `${plugin} ${testId}`
185
+ : (filter ?? Option.getOrUndefined(tag) ?? Option.getOrUndefined(suite));
186
+ if (listSuites) {
187
+ return { selection: { kind: 'suites', rows: selectedSuites } satisfies QaSelection, description };
188
+ }
189
+ if (Option.isSome(tag) || Option.isSome(suite)) {
190
+ // Suites are order-independent by construction (each test owns its fixture), so a tag's union is simply every
191
+ // member test, de-duplicated, in suite order.
192
+ const seen = new Set<string>();
193
+ const rows = selectedSuites
194
+ .flatMap((candidate) => resolveSuite(tests, candidate))
195
+ .filter((test) => {
196
+ const key = `${test.plugin}:${test.id}`;
197
+ return seen.has(key) ? false : (seen.add(key), true);
198
+ });
199
+ return { selection: { kind: 'tests', rows } satisfies QaSelection, description };
200
+ }
201
+ const rows = tests
202
+ .filter(matchesPlugin)
203
+ .filter(matchesFilter)
204
+ .filter((test) => !testId || test.id.toLowerCase() === testId.toLowerCase());
205
+ return { selection: { kind: 'tests', rows } satisfies QaSelection, description };
206
+ };
207
+
208
+ /** The numbered table `/dxos:qa` renders; row numbers are the addressing scheme. */
209
+ export const formatSelection = (selection: QaSelection, description: string | undefined): string[] => {
210
+ const noun = selection.kind;
211
+ if (selection.rows.length === 0) {
212
+ return [description ? `No ${noun} matching "${description}".` : `No ${noun} found.`];
213
+ }
214
+ if (selection.kind === 'suites') {
215
+ const width = Math.max(...selection.rows.map((suite) => suite.id.length));
216
+ return selection.rows.flatMap((suite, index) => [
217
+ `${String(index + 1).padStart(2)}. ${suite.id.padEnd(width)} ${String(suite.tests.length).padStart(2)} tests ${suite.title}`,
218
+ ` ${suite.file}${suite.tags.length ? ` tags: ${suite.tags.join(', ')}` : ''}`,
219
+ ]);
220
+ }
221
+ const idWidth = Math.max(...selection.rows.map((test) => test.id.length));
222
+ const statusWidth = Math.max(...selection.rows.map((test) => test.status.length));
223
+ return selection.rows.flatMap((test, index) => {
224
+ const { before, steps, after } = test.stages;
225
+ return [
226
+ `${String(index + 1).padStart(2)}. ${test.plugin}:${test.id.padEnd(idWidth)} ${test.status.padEnd(statusWidth)} ` +
227
+ `${String(steps).padStart(2)} steps (${before} before, ${after} after) ${test.title}`,
228
+ ` ${test.file}${test.covers ? ` covers: ${test.covers}` : ''}`,
229
+ ];
230
+ });
231
+ };
232
+
233
+ /** Every `.mdl` file under `root`, sorted, with paths relative to it; broken symlinks are skipped. */
234
+ export const readDocuments = Effect.fnUntraced(function* (root: string) {
235
+ const fs = yield* FileSystem.FileSystem;
236
+ const path = yield* Path.Path;
237
+ const walk = (dir: string): Effect.Effect<string[]> =>
238
+ Effect.gen(function* () {
239
+ // Sorted: the row numbers are the addressing scheme, and readdir order is filesystem-defined.
240
+ const entries = (yield* fs.readDirectory(dir).pipe(Effect.orElseSucceed((): string[] => []))).sort();
241
+ const files: string[] = [];
242
+ for (const entry of entries) {
243
+ if (SKIP.has(entry)) {
244
+ continue;
245
+ }
246
+ const full = path.join(dir, entry);
247
+ const info = yield* fs.stat(full).pipe(Effect.option);
248
+ if (Option.isNone(info)) {
249
+ continue;
250
+ }
251
+ if (info.value.type === 'Directory') {
252
+ files.push(...(yield* walk(full)));
253
+ } else if (entry.endsWith('.mdl')) {
254
+ files.push(full);
255
+ }
256
+ }
257
+ return files;
258
+ });
259
+
260
+ const files = yield* walk(root);
261
+ return yield* Effect.forEach(files, (file) =>
262
+ fs.readFileString(file).pipe(Effect.map((text): QaDocument => ({ file: path.relative(root, file), text }))),
263
+ );
264
+ });
265
+
266
+ const list = Command.make(
267
+ 'list',
268
+ {
269
+ query: Argument.String('query').pipe(
270
+ Argument.withDescription(
271
+ '`<plugin> <testId>` for exactly one test (`markdown QA-1`, `app QA-1`), or a substring filter.',
272
+ ),
273
+ Argument.variadic({ max: 2 }),
274
+ ),
275
+ tag: Flag.String('tag').pipe(Flag.withDescription('The tests of every suite carrying this tag.'), Flag.optional),
276
+ suite: Flag.String('suite').pipe(Flag.withDescription('The tests of one suite, in its order.'), Flag.optional),
277
+ suites: Flag.Boolean('suites').pipe(Flag.withDescription('List suites instead of tests.'), Flag.withDefault(false)),
278
+ json: Flag.Boolean('json').pipe(Flag.withDescription('Print the rows as JSON.'), Flag.withDefault(false)),
279
+ root: Flag.String('root').pipe(
280
+ Flag.withDescription('Directory to search (env DX_REPO_ROOT; default the working directory).'),
281
+ Flag.withFallbackConfig(Config.String('DX_REPO_ROOT')),
282
+ Flag.withDefault(process.cwd()),
283
+ ),
284
+ },
285
+ Effect.fnUntraced(function* ({ json, root, ...query }) {
286
+ const { selection, description } = selectQa(yield* readDocuments(root), query);
287
+ if (json || (yield* JsonOutput)) {
288
+ yield* Console.log(JSON.stringify(selection.rows, null, 2));
289
+ return;
290
+ }
291
+ for (const line of formatSelection(selection, description)) {
292
+ yield* Console.log(line);
293
+ }
294
+ }),
295
+ ).pipe(Command.withDescription('List the executable `test` and `suite` blocks across the .mdl specs, numbered.'));
296
+
297
+ export const qa = Command.make('qa').pipe(
298
+ Command.withDescription('Deus.QA tools.'),
299
+ Command.withSubcommands([list, qaLint]),
300
+ );
@@ -0,0 +1,359 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import * as Argument from 'effect/cli/Argument';
6
+ import * as Command from 'effect/cli/Command';
7
+ import * as Console from 'effect/Console';
8
+ import * as Effect from 'effect/Effect';
9
+ import * as FileSystem from 'effect/FileSystem';
10
+ import * as Option from 'effect/Option';
11
+ import * as Path from 'effect/Path';
12
+
13
+ import { parseMdlBlocks } from '../extension/blocks.ts';
14
+ import { specDependencies } from '../extension/refs.ts';
15
+ import { frontmatter, reqs } from '../spec-index/parse.ts';
16
+ import { ReviewCheckError } from './errors.ts';
17
+ import { git } from './git.ts';
18
+
19
+ const STATUSES = new Set(['done', 'untested', 'partial', 'diverged', 'missing']);
20
+
21
+ /** Kinds a review judges. Acceptance blocks (scenarios, QA tests) are run, not reviewed; history is not code. */
22
+ const REVIEWED_KINDS = new Set([
23
+ 'plugin',
24
+ 'feat',
25
+ 'req',
26
+ 'type',
27
+ 'op',
28
+ 'component',
29
+ 'service',
30
+ 'capability',
31
+ 'module',
32
+ 'db',
33
+ 'scenario',
34
+ 'test',
35
+ ]);
36
+
37
+ /** A walkthrough says where things are; more steps than this retells the code. */
38
+ const MAX_WALKTHROUGH = 5;
39
+
40
+ /** Kinds judged on whether automation exercises them rather than on whether code implements them. */
41
+ const EXERCISE_KINDS = new Set(['scenario', 'test']);
42
+
43
+ /** A key list written inline (`[a, b]`), wrapped over lines, or as `- a` items, as `parseReview` reads it. */
44
+ export const keyList = (value: string | undefined): string[] =>
45
+ (value ?? '')
46
+ .split(/[,\n]/)
47
+ .map((item) => item.replace(/^[\s[-]+|[\s\]]+$/g, ''))
48
+ .filter(Boolean);
49
+
50
+ export type ReviewItem = { id: string; kind: string; line: number; title: string };
51
+
52
+ const blocks = (text: string): { body: string; line: number }[] =>
53
+ [...text.matchAll(/^```mdl\s*\n([\s\S]*?)^```/gm)].map((match) => ({
54
+ body: match[1],
55
+ line: text.slice(0, match.index).split('\n').length + 1,
56
+ }));
57
+
58
+ /** Top-level blocks, plus `req` items nested in a `feat`; a feat with reqs is judged through them. */
59
+ export const reviewItems = (text: string): ReviewItem[] =>
60
+ blocks(text).flatMap(({ body, line }) => {
61
+ const lines = body.split('\n');
62
+ const header = lines[0].match(/^(\w+)\s+([A-Za-z][\w.-]*)\s*(?::\s*(.*))?$/);
63
+ if (!header || !REVIEWED_KINDS.has(header[1])) {
64
+ return [];
65
+ }
66
+ const nested = reqs(body).map(({ id, title, offset }) => ({ id, kind: 'req', line: line + offset, title }));
67
+ return nested.length > 0 ? nested : [{ id: header[2], kind: header[1], line, title: header[3] ?? '' }];
68
+ });
69
+
70
+ /** A block field at two spaces of indent; a `|` value continues on lines indented four or more. */
71
+ export const blockField = (body: string, name: string): string | undefined => {
72
+ const match = body.match(new RegExp(`^ ${name}:[ \\t]*(.*)$((?:\\n {4,}.*)*)`, 'm'));
73
+ return match ? `${match[1]} ${match[2]}`.replace(/^\|/, '').trim() : undefined;
74
+ };
75
+
76
+ /**
77
+ * The items a reference to `id` covers: a block's reqs (or the block itself when it has none), or one nested req.
78
+ */
79
+ export const itemsUnder = (text: string, id: string): ReviewItem[] => {
80
+ const block = blocks(text).find(({ body }) => body.split('\n')[0].match(/^\w+\s+([A-Za-z][\w.-]*)/)?.[1] === id);
81
+ if (block) {
82
+ const end = block.line + block.body.split('\n').length;
83
+ return reviewItems(text).filter(({ line }) => line >= block.line && line < end);
84
+ }
85
+ return reviewItems(text).filter((item) => item.id === id);
86
+ };
87
+
88
+ /** Each verdict's status and note, by item id. */
89
+ export const reviewVerdicts = (text: string): Map<string, { status?: string; note?: string }> =>
90
+ new Map(
91
+ blocks(text).flatMap(({ body }) => {
92
+ const id = body.split('\n')[0].match(/^verdict\s+([A-Za-z][\w.-]*)/)?.[1];
93
+ return id ? [[id, { status: blockField(body, 'status'), note: blockField(body, 'note') }] as const] : [];
94
+ }),
95
+ );
96
+
97
+ /**
98
+ * The `dependsOn` array of the `plugin` object in a `dx.config.ts`, empty when the object has none; undefined when
99
+ * there is no `plugin` object or `dependsOn` is not a literal array of strings. Comments are stripped first so a commented-out entry does not count.
100
+ */
101
+ export const configDependsOn = (configText: string): string[] | undefined => {
102
+ const code = configText.replace(/(['"`])(?:\\.|(?!\1)[^\\])*\1|\/\/.*|\/\*[\s\S]*?\*\//g, (match) =>
103
+ match.startsWith('/') ? ' ' : match,
104
+ );
105
+ const start = /\bplugin\s*:\s*\{/.exec(code);
106
+ if (start?.index === undefined) {
107
+ return undefined;
108
+ }
109
+ let depth = 0;
110
+ let end = code.length;
111
+ for (let index = start.index + start[0].length - 1; index < code.length; index++) {
112
+ depth += code[index] === '{' ? 1 : code[index] === '}' ? -1 : 0;
113
+ if (depth === 0) {
114
+ end = index;
115
+ break;
116
+ }
117
+ }
118
+ const plugin = code.slice(start.index, end);
119
+ if (!/\bdependsOn\s*:/.test(plugin)) {
120
+ return [];
121
+ }
122
+ const literal = plugin.match(/\bdependsOn\s*:\s*\[([^\]]*)\]/)?.[1];
123
+ if (literal === undefined) {
124
+ return undefined;
125
+ }
126
+ const items = literal
127
+ .split(',')
128
+ .map((item) => item.trim())
129
+ .filter((item) => item !== '');
130
+ const strings = items.map((item) => item.match(/^(['"`])([^'"`$\\]*)\1$/)?.[2]);
131
+ return strings.every((value) => value !== undefined) ? strings.filter((value) => value !== undefined) : undefined;
132
+ };
133
+
134
+ /** Whether the source declares the name: a top-level declaration, a member, or an export list entry. */
135
+ const declares = (source: string, name: string): boolean => {
136
+ const id = name.replace(/[$]/g, '\\$');
137
+ return [
138
+ new RegExp(`(?:class|interface|type|enum|function\\*?|const|let|var|namespace)\\s+${id}\\b`),
139
+ new RegExp(
140
+ `^\\s*(?:(?:public|private|protected|static|readonly|override|async|get|set|#)\\s*)*${id}\\s*\\??[:(<=]`,
141
+ 'm',
142
+ ),
143
+ new RegExp(`export\\s*\\{[^}]*\\b${id}\\b`),
144
+ ].some((pattern) => pattern.test(source));
145
+ };
146
+
147
+ type ResolvedKey = { file?: string; symbol?: string; error?: string };
148
+
149
+ /**
150
+ * Validates a `.review.mdl` against its spec and the checkout: frontmatter, statuses, notes, coverage of every item,
151
+ * and that each evidence key names an existing file and symbol.
152
+ */
153
+ export const checkReview = Effect.fnUntraced(function* (reviewPath: string) {
154
+ const fs = yield* FileSystem.FileSystem;
155
+ const path = yield* Path.Path;
156
+ const errors: string[] = [];
157
+ const warnings: string[] = [];
158
+ const text = yield* fs.readFileString(reviewPath);
159
+ const meta = frontmatter(text);
160
+ for (const key of ['spec', 'commit', 'date', 'by']) {
161
+ if (!meta[key]) {
162
+ errors.push(`frontmatter: missing \`${key}\``);
163
+ }
164
+ }
165
+ if (meta.date && !/^\d{4}-\d{2}-\d{2}$/.test(meta.date)) {
166
+ errors.push('frontmatter: `date` must be YYYY-MM-DD');
167
+ }
168
+ if (meta.by && !/^(user|agent):\S+$/.test(meta.by)) {
169
+ errors.push('frontmatter: `by` must be `user:<handle>` or `agent:<name>`');
170
+ }
171
+
172
+ const root = yield* git(path.dirname(path.resolve(reviewPath)), 'rev-parse', '--show-toplevel');
173
+ const realRoot = yield* fs.realPath(root);
174
+ const repo = Option.getOrUndefined(
175
+ yield* git(root, 'remote', 'get-url', 'origin').pipe(
176
+ Effect.option,
177
+ Effect.map(Option.flatMapNullishOr((url) => url.match(/github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/)?.[1])),
178
+ ),
179
+ );
180
+ if (meta.commit && Option.isNone(yield* git(root, 'cat-file', '-e', `${meta.commit}^{commit}`).pipe(Effect.option))) {
181
+ warnings.push(`frontmatter: commit ${meta.commit} is not in this clone (shallow, or not fetched)`);
182
+ }
183
+
184
+ const exists = (file: string) => fs.exists(file).pipe(Effect.orElseSucceed(() => false));
185
+ const resolveKey = Effect.fnUntraced(function* (key: string) {
186
+ const match = key.match(/^github:([\w.-]+\/[\w.-]+)\/([^#\s]+)(?:#([\w$.-]+))?$/);
187
+ if (!match) {
188
+ return { error: `not a github: key: ${key}` } satisfies ResolvedKey;
189
+ }
190
+ if (repo && match[1].toLowerCase() !== repo.toLowerCase()) {
191
+ return {} satisfies ResolvedKey;
192
+ }
193
+ const file = path.resolve(root, match[2]);
194
+ // A key names a file inside the checkout; neither `..` nor a symlink may reach outside it.
195
+ const real = (yield* exists(file)) ? yield* fs.realPath(file) : file;
196
+ if (match[2].split('/').includes('..') || !real.startsWith(`${realRoot}${path.sep}`)) {
197
+ return { error: `key leaves the checkout: ${key}` } satisfies ResolvedKey;
198
+ }
199
+ return { file, symbol: match[3] } satisfies ResolvedKey;
200
+ });
201
+
202
+ const specFile = meta.spec ? (yield* resolveKey(meta.spec)).file : undefined;
203
+ const specText = specFile && (yield* exists(specFile)) ? yield* fs.readFileString(specFile) : undefined;
204
+ if (meta.spec && !specText) {
205
+ errors.push(`frontmatter: spec not found in this checkout: ${meta.spec}`);
206
+ }
207
+ const items = specText ? reviewItems(specText) : [];
208
+ const itemIds = new Set(items.map(({ id }) => id));
209
+ const kindOf = new Map(items.map(({ id, kind }) => [id, kind]));
210
+
211
+ const verdicts = blocks(text).flatMap(({ body, line }) => {
212
+ const header = body.split('\n')[0].match(/^verdict\s+([A-Za-z][\w.-]*)\s*(?::\s*(.*))?$/);
213
+ return header ? [{ id: header[1], line, body }] : [];
214
+ });
215
+ const seen = new Set<string>();
216
+ for (const { id, line, body } of verdicts) {
217
+ const at = `${reviewPath}:${line}`;
218
+ if (seen.has(id)) {
219
+ errors.push(`${at}: second verdict for ${id}`);
220
+ }
221
+ seen.add(id);
222
+ if (specText && !itemIds.has(id)) {
223
+ errors.push(`${at}: ${id} is not a reviewable item of the spec (run \`items\` for the list)`);
224
+ }
225
+ const status = blockField(body, 'status');
226
+ if (!status || !STATUSES.has(status)) {
227
+ errors.push(`${at}: ${id} has status \`${status ?? ''}\`; use one of ${[...STATUSES].join(', ')}`);
228
+ }
229
+ if (status && status !== 'done' && !blockField(body, 'note')) {
230
+ errors.push(`${at}: ${id} is ${status} but has no note saying what is missing or different`);
231
+ }
232
+ const exercise = EXERCISE_KINDS.has(kindOf.get(id) ?? '');
233
+ const evidence = keyList(blockField(body, 'evidence'));
234
+ if (!exercise && (status === 'done' || status === 'untested' || status === 'partial') && evidence.length === 0) {
235
+ warnings.push(`${at}: ${id} is ${status} with no evidence`);
236
+ }
237
+ for (const key of evidence) {
238
+ const { file, symbol, error } = yield* resolveKey(key);
239
+ if (error) {
240
+ errors.push(`${at}: ${error}`);
241
+ } else if (file && !(yield* exists(file))) {
242
+ errors.push(`${at}: evidence file not found: ${key}`);
243
+ } else if (file && symbol) {
244
+ if (!declares(yield* fs.readFileString(file), symbol.split('.').pop() ?? symbol)) {
245
+ errors.push(`${at}: no declaration of ${symbol} in ${key.split('#')[0]} (a mention is not evidence)`);
246
+ }
247
+ }
248
+ }
249
+ const tests = keyList(blockField(body, 'tests'));
250
+ if (exercise && status === 'untested') {
251
+ errors.push(`${at}: ${id} is a ${kindOf.get(id)}; use done, partial, diverged or missing (see lang/review.mdl)`);
252
+ }
253
+ if (exercise && status !== 'missing' && tests.length === 0) {
254
+ errors.push(`${at}: ${id} is a ${kindOf.get(id)} judged ${status} but cites no tests`);
255
+ }
256
+ if (status === 'untested' && tests.length > 0) {
257
+ errors.push(`${at}: ${id} is untested but cites tests; make it done or drop the tests`);
258
+ }
259
+ if (!exercise && status === 'done' && tests.length === 0) {
260
+ warnings.push(`${at}: ${id} is done with no tests; cite them or make it untested`);
261
+ }
262
+ for (const key of tests) {
263
+ const { file, symbol, error } = yield* resolveKey(key);
264
+ if (error) {
265
+ errors.push(`${at}: ${error}`);
266
+ } else if (symbol) {
267
+ errors.push(`${at}: a test key names the test file only, without #: ${key}`);
268
+ } else if (file && !(yield* exists(file))) {
269
+ errors.push(`${at}: test file not found: ${key}`);
270
+ }
271
+ }
272
+ // Each step is `- <sentence>. github:<key>`; the joined field holds them as `- ` separated items.
273
+ const steps = (blockField(body, 'walkthrough') ?? '')
274
+ .split(/(?:^|\s)-\s+/)
275
+ .map((step) => step.trim())
276
+ .filter(Boolean);
277
+ if (steps.length > MAX_WALKTHROUGH) {
278
+ errors.push(`${at}: ${id} has ${steps.length} walkthrough steps; keep it to ${MAX_WALKTHROUGH}`);
279
+ }
280
+ if (steps.length > 0 && evidence.length < 2) {
281
+ warnings.push(`${at}: ${id} has one implementation; its code chip already shows it, so drop the walkthrough`);
282
+ }
283
+ for (const step of steps) {
284
+ const key = step.match(/(github:\S+)\s*$/)?.[1];
285
+ if (!key) {
286
+ errors.push(`${at}: walkthrough step does not end with a github: key: ${step}`);
287
+ continue;
288
+ }
289
+ const { file, symbol, error } = yield* resolveKey(key);
290
+ if (error) {
291
+ errors.push(`${at}: ${error}`);
292
+ } else if (file && !(yield* exists(file))) {
293
+ errors.push(`${at}: walkthrough file not found: ${key}`);
294
+ } else if (file && symbol) {
295
+ if (!declares(yield* fs.readFileString(file), symbol.split('.').pop() ?? symbol)) {
296
+ errors.push(`${at}: no declaration of ${symbol} in ${key.split('#')[0]} (walkthrough)`);
297
+ }
298
+ }
299
+ }
300
+ }
301
+ // dx.config.ts is what the app loads, so a spec that lists other dependencies has diverged from the code.
302
+ const pluginBlock = specText ? parseMdlBlocks(specText).find(({ type }) => type === 'plugin') : undefined;
303
+ const configFile = specFile ? path.join(path.dirname(specFile), 'dx.config.ts') : undefined;
304
+ if (specText && pluginBlock && configFile && (yield* exists(configFile))) {
305
+ const config = configDependsOn(yield* fs.readFileString(configFile));
306
+ const declared = specDependencies(specText)
307
+ .filter(({ via }) => via === 'dependsOn')
308
+ .map(({ id }) => id);
309
+ const verdict = verdicts.find(({ id }) => id === pluginBlock.id);
310
+ if (config && verdict && blockField(verdict.body, 'status') !== 'diverged') {
311
+ const same = new Set(declared).size === new Set(config).size && declared.every((id) => config.includes(id));
312
+ if (!same) {
313
+ errors.push(
314
+ `${reviewPath}:${verdict.line}: ${pluginBlock.id} dependsOn [${declared.join(', ')}] differs from dx.config.ts [${config.join(', ')}]; judge it diverged`,
315
+ );
316
+ }
317
+ }
318
+ }
319
+ for (const { id, line } of items) {
320
+ if (!seen.has(id)) {
321
+ errors.push(`${specFile}:${line}: ${id} has no verdict`);
322
+ }
323
+ }
324
+
325
+ for (const warning of warnings) {
326
+ yield* Console.log(`warning: ${warning}`);
327
+ }
328
+ for (const error of errors) {
329
+ yield* Console.log(`error: ${error}`);
330
+ }
331
+ yield* Console.log(
332
+ `${verdicts.length} verdicts for ${items.length} items; ${errors.length} errors, ${warnings.length} warnings.`,
333
+ );
334
+ if (errors.length > 0) {
335
+ return yield* Effect.fail(new ReviewCheckError({ context: { errors: errors.length } }));
336
+ }
337
+ });
338
+
339
+ const items = Command.make(
340
+ 'items',
341
+ { spec: Argument.String('spec').pipe(Argument.withDescription('The spec (.mdl) to list.')) },
342
+ Effect.fnUntraced(function* ({ spec }) {
343
+ const fs = yield* FileSystem.FileSystem;
344
+ for (const { id, kind, line, title } of reviewItems(yield* fs.readFileString(spec))) {
345
+ yield* Console.log(`${id}\t${kind}\t${line}\t${title}`);
346
+ }
347
+ }),
348
+ ).pipe(Command.withDescription('List every item a spec review must judge: `<id>\\t<kind>\\t<line>\\t<title>`.'));
349
+
350
+ const check = Command.make(
351
+ 'check',
352
+ { review: Argument.String('review').pipe(Argument.withDescription('The review (.review.mdl) to validate.')) },
353
+ ({ review }) => checkReview(review),
354
+ ).pipe(Command.withDescription('Validate a spec review against its spec and the checkout.'));
355
+
356
+ export const review = Command.make('review').pipe(
357
+ Command.withDescription('Spec review tools.'),
358
+ Command.withSubcommands([items, check]),
359
+ );