@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
@@ -0,0 +1,320 @@
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 Console from 'effect/Console';
9
+ import * as Effect from 'effect/Effect';
10
+ import * as FileSystem from 'effect/FileSystem';
11
+ import * as Option from 'effect/Option';
12
+ import * as Path from 'effect/Path';
13
+
14
+ import { parseMdlBlocks } from '../extension/blocks.ts';
15
+ import { frontmatter } from '../spec-index/parse.ts';
16
+ import { FeatureCheckError } from './errors.ts';
17
+ import { git } from './git.ts';
18
+ import { type ReviewItem, blockField, itemsUnder, keyList, reviewItems, reviewVerdicts } from './review.ts';
19
+
20
+ /** The authored statuses of `lang/features.mdl`, in the order a feature normally moves through them. */
21
+ export const FEATURE_STATUSES = ['planned', 'in-progress', 'prototype', 'operational', 'failing'] as const;
22
+
23
+ export type FeatureStatus = (typeof FEATURE_STATUSES)[number];
24
+
25
+ /** What the reviews of a feature's spec items say, or `unreviewed` when an item has no verdict. */
26
+ export type DerivedStatus = Exclude<FeatureStatus, 'failing'> | 'unreviewed';
27
+
28
+ export type Feature = {
29
+ id: string;
30
+ title: string;
31
+ line: number;
32
+ status?: string;
33
+ /** Repo-relative spec paths, each optionally `#<item id>`. */
34
+ specs: string[];
35
+ depends: string[];
36
+ };
37
+
38
+ /** Every `feature` block of a feature map. */
39
+ export const parseFeatureMap = (text: string): Feature[] =>
40
+ parseMdlBlocks(text)
41
+ .filter(({ type }) => type === 'feature')
42
+ .map(({ id, title, body, from }) => ({
43
+ id: id ?? '',
44
+ title: title ?? '',
45
+ line: text.slice(0, from).split('\n').length,
46
+ status: blockField(body, 'status'),
47
+ specs: keyList(blockField(body, 'specs')),
48
+ depends: keyList(blockField(body, 'depends')),
49
+ }));
50
+
51
+ /**
52
+ * The status the reviews support: every item done is operational, done or untested is a prototype, every item
53
+ * missing is planned, and anything between is in progress.
54
+ */
55
+ export const deriveStatus = (statuses: ReadonlyArray<string | undefined>): DerivedStatus => {
56
+ if (statuses.length === 0 || statuses.some((status) => status === undefined)) {
57
+ return 'unreviewed';
58
+ }
59
+ if (statuses.every((status) => status === 'done')) {
60
+ return 'operational';
61
+ }
62
+ if (statuses.every((status) => status === 'done' || status === 'untested')) {
63
+ return 'prototype';
64
+ }
65
+ if (statuses.every((status) => status === 'missing')) {
66
+ return 'planned';
67
+ }
68
+ return 'in-progress';
69
+ };
70
+
71
+ /** One spec item a feature cites, with the verdict its review gives it. */
72
+ export type FeatureItem = ReviewItem & { spec: string; status?: string; note?: string };
73
+
74
+ export type FeatureReport = {
75
+ feature: Feature;
76
+ derived: DerivedStatus;
77
+ items: FeatureItem[];
78
+ };
79
+
80
+ export type FeatureMapReport = {
81
+ reports: FeatureReport[];
82
+ errors: string[];
83
+ warnings: string[];
84
+ };
85
+
86
+ const REVIEW_SUFFIX = '.review.mdl';
87
+
88
+ /** Finds the first dependency cycle as the ids along it, closing on the id it started from. */
89
+ const findCycle = (features: ReadonlyArray<Feature>): string[] | undefined => {
90
+ const depends = new Map(features.map(({ id, depends }) => [id, depends]));
91
+ const done = new Set<string>();
92
+ const visit = (id: string, trail: string[]): string[] | undefined => {
93
+ if (trail.includes(id)) {
94
+ return [...trail.slice(trail.indexOf(id)), id];
95
+ }
96
+ if (done.has(id)) {
97
+ return undefined;
98
+ }
99
+ for (const next of depends.get(id) ?? []) {
100
+ const cycle = visit(next, [...trail, id]);
101
+ if (cycle) {
102
+ return cycle;
103
+ }
104
+ }
105
+ done.add(id);
106
+ return undefined;
107
+ };
108
+ for (const { id } of features) {
109
+ const cycle = visit(id, []);
110
+ if (cycle) {
111
+ return cycle;
112
+ }
113
+ }
114
+ return undefined;
115
+ };
116
+
117
+ /**
118
+ * Resolves every spec reference of a feature map against the checkout and its reviews, derives each feature's status,
119
+ * and collects what is wrong (errors) or out of step (warnings).
120
+ */
121
+ export const analyzeFeatureMap = Effect.fnUntraced(function* (mapPath: string) {
122
+ const fs = yield* FileSystem.FileSystem;
123
+ const path = yield* Path.Path;
124
+ const root = yield* git(path.dirname(path.resolve(mapPath)), 'rev-parse', '--show-toplevel');
125
+ const features = parseFeatureMap(yield* fs.readFileString(mapPath));
126
+ const errors: string[] = [];
127
+ const warnings: string[] = [];
128
+ const exists = (file: string) => fs.exists(file).pipe(Effect.orElseSucceed(() => false));
129
+ const readIfExists = Effect.fnUntraced(function* (file: string) {
130
+ return (yield* exists(file)) ? yield* fs.readFileString(file) : undefined;
131
+ });
132
+
133
+ const byId = new Map<string, Feature>();
134
+ for (const feature of features) {
135
+ const at = `${mapPath}:${feature.line}: ${feature.id}`;
136
+ if (byId.has(feature.id)) {
137
+ errors.push(`${at}: second feature with this id`);
138
+ }
139
+ byId.set(feature.id, feature);
140
+ if (!feature.status || !(FEATURE_STATUSES as readonly string[]).includes(feature.status)) {
141
+ errors.push(`${at}: status \`${feature.status ?? ''}\`; use one of ${FEATURE_STATUSES.join(', ')}`);
142
+ }
143
+ if (feature.specs.length === 0) {
144
+ errors.push(`${at}: cites no spec; a feature names the spec items that state it`);
145
+ }
146
+ }
147
+ for (const feature of features) {
148
+ for (const dependency of feature.depends) {
149
+ if (!byId.has(dependency)) {
150
+ errors.push(`${mapPath}:${feature.line}: ${feature.id}: depends on unknown feature ${dependency}`);
151
+ }
152
+ }
153
+ }
154
+ const cycle = findCycle(features);
155
+ if (cycle) {
156
+ errors.push(`${mapPath}: dependency cycle: ${cycle.join(' -> ')}`);
157
+ }
158
+
159
+ // A spec is read, and its review's staleness checked, once however many features cite it.
160
+ const specs = new Map<string, { text?: string; verdicts: Map<string, { status?: string; note?: string }> }>();
161
+ const loadSpec = Effect.fnUntraced(function* (spec: string, at: string) {
162
+ const cached = specs.get(spec);
163
+ if (cached) {
164
+ return cached;
165
+ }
166
+ const file = path.resolve(root, spec);
167
+ const text = yield* readIfExists(file);
168
+ const reviewFile = file.replace(/\.mdl$/, REVIEW_SUFFIX);
169
+ const review = text ? yield* readIfExists(reviewFile) : undefined;
170
+ if (!text) {
171
+ errors.push(`${at}: spec not found: ${spec}`);
172
+ } else if (!review) {
173
+ warnings.push(`${at}: ${spec} has no review; run the spec-review skill`);
174
+ } else {
175
+ const commit = frontmatter(review).commit;
176
+ const changed = commit
177
+ ? yield* git(root, 'rev-list', `${commit}..HEAD`, '--', spec).pipe(Effect.option)
178
+ : Option.none<string>();
179
+ const dirty = yield* git(root, 'status', '--porcelain', '--', spec).pipe(Effect.orElseSucceed(() => ''));
180
+ if (Option.isNone(changed)) {
181
+ warnings.push(`${at}: the review of ${spec} names a commit not in this clone`);
182
+ } else if (changed.value !== '' || dirty !== '') {
183
+ warnings.push(`${at}: ${spec} changed after its review (${commit?.slice(0, 8)}); re-review it`);
184
+ }
185
+ }
186
+ const entry = { text, verdicts: review ? reviewVerdicts(review) : new Map() };
187
+ specs.set(spec, entry);
188
+ return entry;
189
+ });
190
+
191
+ const reports: FeatureReport[] = [];
192
+ for (const feature of features) {
193
+ const at = `${mapPath}:${feature.line}: ${feature.id}`;
194
+ const items: FeatureItem[] = [];
195
+ for (const ref of feature.specs) {
196
+ const [spec, id] = ref.split('#');
197
+ const { text, verdicts } = yield* loadSpec(spec, at);
198
+ if (!text) {
199
+ continue;
200
+ }
201
+ const cited = id ? itemsUnder(text, id) : reviewItems(text);
202
+ if (cited.length === 0) {
203
+ errors.push(`${at}: ${ref} names no reviewable item of the spec`);
204
+ }
205
+ items.push(...cited.map((item) => ({ ...item, spec, ...verdicts.get(item.id) })));
206
+ }
207
+ const derived = deriveStatus(items.map(({ status }) => status));
208
+ const unjudged = items.filter(({ status }) => status === undefined).map(({ id }) => id);
209
+ if (unjudged.length > 0 && unjudged.length < items.length) {
210
+ warnings.push(`${at}: no verdict yet for ${unjudged.join(', ')}`);
211
+ }
212
+ if (feature.status && feature.status !== 'failing' && derived !== 'unreviewed' && feature.status !== derived) {
213
+ warnings.push(`${at}: marked ${feature.status} but its reviews say ${derived}`);
214
+ }
215
+ for (const dependency of feature.depends) {
216
+ const status = byId.get(dependency)?.status;
217
+ if (feature.status !== 'planned' && (status === 'planned' || status === 'failing')) {
218
+ warnings.push(`${at}: blocked: depends on ${dependency}, which is ${status}`);
219
+ } else if (feature.status === 'operational' && status !== 'operational') {
220
+ warnings.push(`${at}: operational ahead of its dependency ${dependency} (${status})`);
221
+ }
222
+ }
223
+ if (feature.status === 'in-progress') {
224
+ const dirs = new Set(
225
+ items.flatMap(({ spec }) => {
226
+ const dir = path.dirname(path.resolve(root, spec));
227
+ return ['spec', 'docs'].includes(path.basename(dir)) ? [dir, path.dirname(dir)] : [dir];
228
+ }),
229
+ );
230
+ let planned = false;
231
+ for (const dir of dirs) {
232
+ const tasks = yield* readIfExists(path.join(dir, 'TASKS.md'));
233
+ planned ||=
234
+ tasks !== undefined && new RegExp(`^#{2,3} .*\\b${feature.id.replace(/\./g, '\\.')}\\b`, 'm').test(tasks);
235
+ }
236
+ if (!planned) {
237
+ warnings.push(
238
+ `${at}: partly built with no work planned: no TASKS.md beside its spec has a \`## ${feature.id}\` section`,
239
+ );
240
+ }
241
+ }
242
+ reports.push({ feature, derived, items });
243
+ }
244
+
245
+ return { reports, errors, warnings } satisfies FeatureMapReport;
246
+ });
247
+
248
+ const DEFAULT_MAP = 'FEATURES.mdl';
249
+
250
+ const resolveMap = Effect.fnUntraced(function* (map: Option.Option<string>) {
251
+ if (Option.isSome(map)) {
252
+ return map.value;
253
+ }
254
+ const path = yield* Path.Path;
255
+ return path.join(yield* git(process.cwd(), 'rev-parse', '--show-toplevel'), DEFAULT_MAP);
256
+ });
257
+
258
+ const mapFlag = Flag.String('map').pipe(
259
+ Flag.withDescription(`The feature map; defaults to ${DEFAULT_MAP} at the repository root.`),
260
+ Flag.optional,
261
+ );
262
+
263
+ /** Prints one row per feature, then every warning and error; fails when there is an error. */
264
+ export const checkFeatures = Effect.fnUntraced(function* (mapPath: string) {
265
+ const { reports, errors, warnings } = yield* analyzeFeatureMap(mapPath);
266
+ for (const { feature, derived, items } of reports) {
267
+ const done = items.filter(({ status }) => status === 'done').length;
268
+ yield* Console.log(`${feature.id}\t${feature.status ?? ''}\t${derived}\t${done}/${items.length} done`);
269
+ }
270
+ for (const warning of warnings) {
271
+ yield* Console.log(`warning: ${warning}`);
272
+ }
273
+ for (const error of errors) {
274
+ yield* Console.log(`error: ${error}`);
275
+ }
276
+ yield* Console.log(`${reports.length} features; ${errors.length} errors, ${warnings.length} warnings.`);
277
+ if (errors.length > 0) {
278
+ return yield* Effect.fail(new FeatureCheckError({ context: { errors: errors.length } }));
279
+ }
280
+ });
281
+
282
+ /** The first sentence of a verdict note, so a task line stays one line. */
283
+ const firstSentence = (note: string | undefined): string =>
284
+ (note ?? '').replace(/\s+/g, ' ').match(/^.*?[.!?](?=\s|$)/)?.[0] ?? (note ?? '').trim();
285
+
286
+ /** Prints the open work of one feature as a TASKS.md section: one task per spec item not yet done. */
287
+ export const featureTasks = Effect.fnUntraced(function* (mapPath: string, id: string) {
288
+ const { reports } = yield* analyzeFeatureMap(mapPath);
289
+ const report = reports.find(({ feature }) => feature.id === id);
290
+ if (!report) {
291
+ return yield* Effect.fail(new FeatureCheckError({ context: { feature: id, reason: 'not on the map' } }));
292
+ }
293
+ yield* Console.log(`## ${report.feature.id}: ${report.feature.title}\n`);
294
+ let spec: string | undefined;
295
+ for (const item of report.items.filter(({ status }) => status !== 'done')) {
296
+ if (item.spec !== spec) {
297
+ spec = item.spec;
298
+ yield* Console.log(`Spec: \`${spec}\`\n`);
299
+ }
300
+ const why = item.status ? `${item.status}${item.note ? `: ${firstSentence(item.note)}` : ''}` : 'unreviewed';
301
+ yield* Console.log(`- [ ] ${item.id}: ${item.title} (${why})`);
302
+ }
303
+ });
304
+
305
+ const check = Command.make('check', { map: mapFlag }, ({ map }) => Effect.flatMap(resolveMap(map), checkFeatures)).pipe(
306
+ Command.withDescription(
307
+ 'Check the feature map against the specs and their reviews: `<id>\\t<status>\\t<derived>\\t<done>/<items> done`.',
308
+ ),
309
+ );
310
+
311
+ const tasks = Command.make(
312
+ 'tasks',
313
+ { map: mapFlag, feature: Argument.String('feature').pipe(Argument.withDescription('The feature id.')) },
314
+ ({ map, feature }) => Effect.flatMap(resolveMap(map), (mapPath) => featureTasks(mapPath, feature)),
315
+ ).pipe(Command.withDescription('Print the open spec items of one feature as a TASKS.md section.'));
316
+
317
+ export const features = Command.make('features').pipe(
318
+ Command.withDescription('Feature map tools: the top of feature map > specs > tasks > code > result.'),
319
+ Command.withSubcommands([check, tasks]),
320
+ );
package/src/cli/git.ts ADDED
@@ -0,0 +1,35 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import * as Effect from 'effect/Effect';
6
+ import * as ChildProcess from 'effect/process/ChildProcess';
7
+ import * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
8
+ import * as Stream from 'effect/Stream';
9
+
10
+ import { GitError } from './errors.ts';
11
+
12
+ /** Runs `git <args>` in `cwd` and returns trimmed stdout; a non-zero exit fails with {@link GitError}. */
13
+ export const git = Effect.fnUntraced(function* (cwd: string, ...args: string[]) {
14
+ const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
15
+ return yield* Effect.scoped(
16
+ Effect.gen(function* () {
17
+ const handle = yield* spawner.spawn(ChildProcess.make('git', args, { cwd }));
18
+ const [stdout, stderr, exitCode] = yield* Effect.all(
19
+ [
20
+ Stream.mkString(Stream.decodeText(handle.stdout)),
21
+ Stream.mkString(Stream.decodeText(handle.stderr)),
22
+ handle.exitCode,
23
+ ],
24
+ { concurrency: 'unbounded' },
25
+ );
26
+ if (exitCode !== 0) {
27
+ return yield* Effect.fail(new GitError({ context: { args, exitCode, stderr: stderr.trim() } }));
28
+ }
29
+ return stdout.trim();
30
+ }),
31
+ ).pipe(Effect.catchTag('PlatformError', (error) => Effect.fail(new GitError({ cause: error, context: { args } }))));
32
+ });
33
+
34
+ /** Splits command output into its non-empty lines. */
35
+ export const lines = (text: string): string[] => text.split('\n').filter(Boolean);
@@ -0,0 +1,27 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import * as Command from 'effect/cli/Command';
6
+
7
+ import { changelog } from './changelog.ts';
8
+ import { features } from './features.ts';
9
+ import { lint } from './lint.ts';
10
+ import { qa } from './qa.ts';
11
+ import { review } from './review.ts';
12
+ import { index } from './spec-index.ts';
13
+
14
+ export * from './changelog.ts';
15
+ export * from './errors.ts';
16
+ export * from './features.ts';
17
+ export * from './lint.ts';
18
+ export * from './qa.ts';
19
+ export * from './qa-lint.ts';
20
+ export * from './review.ts';
21
+ export * from './spec-index.ts';
22
+
23
+ /** The `deus` command tree: run standalone by `bin/deus.ts` and mounted by the `dx` CLI as `dx deus`. */
24
+ export const deus = Command.make('deus').pipe(
25
+ Command.withDescription('Tools for Deus `.mdl` specs.'),
26
+ Command.withSubcommands([changelog, features, index, lint, qa, review]),
27
+ );
@@ -0,0 +1,75 @@
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 Console from 'effect/Console';
9
+ import * as Effect from 'effect/Effect';
10
+ import * as FileSystem from 'effect/FileSystem';
11
+ import * as Option from 'effect/Option';
12
+
13
+ import { lintMdl } from '../extension/check.ts';
14
+ import { LintError } from './errors.ts';
15
+ import { git } from './git.ts';
16
+ import { buildSpecIndex } from './spec-index.ts';
17
+
18
+ const INDEXED_CHECKS = ['mdl/ref', 'mdl/uses'];
19
+
20
+ export type LintOptions = {
21
+ files: readonly string[];
22
+ /** Keep one check, e.g. `mdl/decision`; the block-type check still knows only the built-in types. */
23
+ only: Option.Option<string>;
24
+ };
25
+
26
+ /** Lints .mdl files with the checks the editor runs; fails when any diagnostic is an error. */
27
+ export const lintFiles = Effect.fnUntraced(function* ({ files, only }: LintOptions) {
28
+ const fs = yield* FileSystem.FileSystem;
29
+ const needsIndex = Option.isNone(only) || INDEXED_CHECKS.includes(only.value);
30
+ const root = needsIndex
31
+ ? yield* git(process.cwd(), 'rev-parse', '--show-toplevel').pipe(
32
+ // Outside a checkout there is nothing to resolve references against; any other git failure must fail the run.
33
+ Effect.catch((error) =>
34
+ String(error.context?.stderr).includes('not a git repository')
35
+ ? Effect.succeed(undefined)
36
+ : Effect.fail(error),
37
+ ),
38
+ )
39
+ : undefined;
40
+ if (needsIndex && root === undefined) {
41
+ yield* Console.log('warning: not inside a git checkout; the mdl/ref and mdl/uses checks were skipped.');
42
+ }
43
+ const index = root === undefined ? undefined : yield* buildSpecIndex(root);
44
+ let errors = 0;
45
+ for (const file of files) {
46
+ const text = yield* fs.readFileString(file);
47
+ for (const { from, severity, source, message } of lintMdl(text, {
48
+ index: file.endsWith('.review.mdl') ? undefined : index,
49
+ })) {
50
+ if (Option.isSome(only) && source !== only.value) {
51
+ continue;
52
+ }
53
+ const line = text.slice(0, from).split('\n').length;
54
+ yield* Console.log(`${file}:${line}: ${severity} [${source}]: ${message}`);
55
+ if (severity === 'error') {
56
+ errors++;
57
+ }
58
+ }
59
+ }
60
+ if (errors > 0) {
61
+ return yield* Effect.fail(new LintError({ context: { errors } }));
62
+ }
63
+ });
64
+
65
+ export const lint = Command.make(
66
+ 'lint',
67
+ {
68
+ only: Flag.String('only').pipe(Flag.withDescription('Report one check only, e.g. `mdl/decision`.'), Flag.optional),
69
+ files: Argument.String('files').pipe(
70
+ Argument.withDescription('The .mdl files to lint.'),
71
+ Argument.variadic({ min: 1 }),
72
+ ),
73
+ },
74
+ lintFiles,
75
+ ).pipe(Command.withDescription('Lint .mdl files with the checks the editor runs.'));
@@ -0,0 +1,206 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import * as Command from 'effect/cli/Command';
6
+ import * as Flag from 'effect/cli/Flag';
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 { QaLintError } from './errors.ts';
14
+
15
+ /** Names the runner binds itself (qa.mdl Field rule 5 and Input literals), so no test declares them. */
16
+ const RUNNER_BOUND = new Set(['given', 'result', 'error', 'spaceId', 'snapshot', 'stepErrors', 'runId']);
17
+
18
+ export type UnboundReport = { file: string; test: string; unbound: [name: string, line: number][] };
19
+
20
+ /** `test QA-n` blocks whose steps reference a `$given.x` or `$x` the test never binds. */
21
+ export const findUnboundReferences = (file: string, text: string): UnboundReport[] => {
22
+ const lines = text.split('\n');
23
+ // Slice each `test QA-n:` block: starts at the header, ends at the closing fence.
24
+ const tests: { name: string; body: { line: number; text: string }[] }[] = [];
25
+ let current: (typeof tests)[number] | undefined;
26
+ lines.forEach((line, index) => {
27
+ const header = line.match(/^test (QA-\d+):/);
28
+ if (header) {
29
+ current = { name: header[1], body: [] };
30
+ tests.push(current);
31
+ } else if (current && line.startsWith('```')) {
32
+ current = undefined;
33
+ } else if (current) {
34
+ current.body.push({ line: index + 1, text: line });
35
+ }
36
+ });
37
+
38
+ return tests.flatMap((test) => {
39
+ const text = test.body.map(({ text }) => text).join('\n');
40
+ // Bound names: `given:` entries written `- name: prose`, and every `capture:`.
41
+ const givens = new Set<string>();
42
+ let inGiven = false;
43
+ for (const { text: line } of test.body) {
44
+ if (/^\s{2}given:/.test(line)) {
45
+ inGiven = true;
46
+ continue;
47
+ }
48
+ if (/^\s{2}\w+[?]?:/.test(line)) {
49
+ inGiven = false;
50
+ }
51
+ const entry = inGiven ? line.match(/^\s*-\s+([A-Za-z_][A-Za-z0-9_]*):\s/) : null;
52
+ if (entry) {
53
+ givens.add(entry[1]);
54
+ }
55
+ }
56
+ const captures = new Set([...text.matchAll(/^\s*capture:\s*([A-Za-z_][A-Za-z0-9_]*)/gm)].map((match) => match[1]));
57
+
58
+ const unbound = new Map<string, number>();
59
+ for (const { line, text: content } of test.body) {
60
+ for (const match of content.matchAll(/\$given\.([A-Za-z_][A-Za-z0-9_]*)/g)) {
61
+ if (!givens.has(match[1])) {
62
+ unbound.set(`$given.${match[1]}`, line);
63
+ }
64
+ }
65
+ for (const match of content.matchAll(/\$([A-Za-z_][A-Za-z0-9_]*)/g)) {
66
+ if (!RUNNER_BOUND.has(match[1]) && !captures.has(match[1])) {
67
+ unbound.set(`$${match[1]}`, line);
68
+ }
69
+ }
70
+ }
71
+ return unbound.size > 0 ? [{ file, test: test.name, unbound: [...unbound.entries()] }] : [];
72
+ });
73
+ };
74
+
75
+ export type TeardownReport = { file: string; test: string; line: number; reason: string };
76
+
77
+ /**
78
+ * `after:` steps that could remove an object the run did not create.
79
+ *
80
+ * A teardown is safe when it removes something the test bound itself (a `capture:` or a named `given:`), or resolves
81
+ * by a name the test's `given` guarantees is absent — constrained to the subject's own type, and throwing when nothing
82
+ * matches. Resolving by type-and-index deletes whatever the space happens to hold first; resolving by name across
83
+ * `Filter.everything()` deletes any object carrying that name, which the `given` precondition does not exclude.
84
+ */
85
+ export const findUnsafeTeardowns = (file: string, text: string): TeardownReport[] => {
86
+ const lines = text.split('\n');
87
+ const reports: TeardownReport[] = [];
88
+ let inAfter = false;
89
+ let test = '';
90
+ lines.forEach((line, index) => {
91
+ const header = line.match(/^test (QA-\d+):/);
92
+ if (header) {
93
+ test = header[1];
94
+ inAfter = false;
95
+ }
96
+ if (/^ {2}after:/.test(line)) {
97
+ inAfter = true;
98
+ return;
99
+ }
100
+ if (/^ {2}(steps|before|given):/.test(line) || line.startsWith('```')) {
101
+ inAfter = false;
102
+ }
103
+ if (!inAfter || !/removeObjects/.test(line)) {
104
+ return;
105
+ }
106
+ // Only the invoke's own continuation lines — an `assert:` verifying removal legitimately queries the database and
107
+ // must not be mistaken for victim selection.
108
+ const step: string[] = [];
109
+ for (let next = index; next < lines.length; next++) {
110
+ if (next > index && /^\s+(assert|expect|note|do|name|capture):/.test(lines[next])) {
111
+ break;
112
+ }
113
+ step.push(lines[next]);
114
+ }
115
+ const body = step.join('\n');
116
+ if (!/db\.query/.test(body)) {
117
+ return; // Removes a bound value.
118
+ }
119
+ const byIndex = /\.objects\[\d+\]/.test(body);
120
+ const guarded = /throw new Error/.test(body);
121
+ // A name match over every object in the space is not narrowed by a `given` that only promises no *typed* subject
122
+ // carries the name.
123
+ const untyped = /Filter\.everything\(\)/.test(body) && /\.name ===/.test(body);
124
+ // Selecting on an id the test itself produced discriminates even on a dirty fixture, so it needs no name guard
125
+ // (Execution Rule 5).
126
+ const byIdentity = /\.id ===/.test(body);
127
+ if (byIndex || untyped || (!guarded && !byIdentity)) {
128
+ const reason = byIndex ? 'resolves by index' : untyped ? 'name match across every type' : 'unguarded query';
129
+ reports.push({ file, test, line: index + 1, reason });
130
+ }
131
+ });
132
+ return reports;
133
+ };
134
+
135
+ /** The plugin specs the QA lints cover: `packages/plugins/<plugin>/PLUGIN.mdl`, sorted, relative to `root`. */
136
+ const pluginSpecs = Effect.fnUntraced(function* (root: string) {
137
+ const fs = yield* FileSystem.FileSystem;
138
+ const path = yield* Path.Path;
139
+ const plugins = (yield* fs.readDirectory(path.join(root, 'packages/plugins'))).sort();
140
+ const specs: { file: string; text: string }[] = [];
141
+ for (const plugin of plugins) {
142
+ const file = `packages/plugins/${plugin}/PLUGIN.mdl`;
143
+ const text = yield* fs.readFileString(path.join(root, file)).pipe(Effect.option);
144
+ if (Option.isSome(text)) {
145
+ specs.push({ file, text: text.value });
146
+ }
147
+ }
148
+ return specs;
149
+ });
150
+
151
+ export type QaCheck = 'unbound' | 'teardown';
152
+
153
+ export const QA_CHECKS: readonly QaCheck[] = ['unbound', 'teardown'];
154
+
155
+ /** Runs the QA lints over every plugin spec under `root`; fails when any reports a finding. */
156
+ export const lintQa = Effect.fnUntraced(function* ({ root, checks }: { root: string; checks: readonly QaCheck[] }) {
157
+ const specs = yield* pluginSpecs(root);
158
+ let findings = 0;
159
+
160
+ if (checks.includes('unbound')) {
161
+ const reports = specs.flatMap(({ file, text }) => findUnboundReferences(file, text));
162
+ let total = 0;
163
+ for (const report of reports) {
164
+ yield* Console.log(`${report.file} ${report.test}`);
165
+ for (const [name, line] of report.unbound) {
166
+ yield* Console.log(` L${line} ${name}`);
167
+ total++;
168
+ }
169
+ }
170
+ yield* Console.log(`\n${reports.length} tests with unbound references; ${total} references total`);
171
+ findings += total;
172
+ }
173
+
174
+ if (checks.includes('teardown')) {
175
+ const reports = specs.flatMap(({ file, text }) => findUnsafeTeardowns(file, text));
176
+ for (const { file, test, line, reason } of reports) {
177
+ yield* Console.log(`${file} ${test} L${line} ${reason}`);
178
+ }
179
+ yield* Console.log(`\n${reports.length} teardown step(s) that could remove an object the run did not create`);
180
+ findings += reports.length;
181
+ }
182
+
183
+ if (findings > 0) {
184
+ return yield* Effect.fail(new QaLintError({ context: { findings } }));
185
+ }
186
+ });
187
+
188
+ export const qaLint = Command.make(
189
+ 'lint',
190
+ {
191
+ check: Flag.Literals('check', QA_CHECKS).pipe(
192
+ Flag.withDescription(
193
+ 'Run one check: `unbound` ($references a test never binds) or `teardown` (unsafe `after:` removals).',
194
+ ),
195
+ Flag.optional,
196
+ ),
197
+ root: Flag.String('root').pipe(
198
+ Flag.withDescription('Repository root holding `packages/plugins` (default the working directory).'),
199
+ Flag.withDefault(process.cwd()),
200
+ ),
201
+ },
202
+ ({ check, root }) =>
203
+ lintQa({ root, checks: Option.match(check, { onNone: () => QA_CHECKS, onSome: (one) => [one] }) }),
204
+ ).pipe(
205
+ Command.withDescription('Lint the `test` blocks of every plugin spec for unbound references and unsafe teardowns.'),
206
+ );