@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,184 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { parseMdlBlocks } from '../extension/blocks.ts';
6
+ import { parseFields } from './fields.ts';
7
+ import { type SourceKey, formatSourceKey, parseSourceKey } from './source-key.ts';
8
+
9
+ /**
10
+ * How far the code meets one spec item, least severe first: `done` as specified, `untested` present but with no test
11
+ * that covers it, `partial` in part, `diverged` implemented differently from what the spec says, `missing` not at all.
12
+ */
13
+ export const VERDICT_STATUSES = ['done', 'untested', 'partial', 'diverged', 'missing'] as const;
14
+
15
+ export type VerdictStatus = (typeof VERDICT_STATUSES)[number];
16
+
17
+ export type Verdict = {
18
+ /** The spec item judged: a block id (`Scene`, `F-1`) or a nested requirement (`F-1.2`). */
19
+ id: string;
20
+ status: VerdictStatus;
21
+ summary?: string;
22
+ /** `github:` keys of the code that supports the verdict. */
23
+ evidence: string[];
24
+ /** `github:` keys of the tests that exercise the item; empty when the review names none. */
25
+ tests: string[];
26
+ /** Where each part of the item is implemented, in reading order; empty when the review gives none. */
27
+ walkthrough: WalkthroughStep[];
28
+ note?: string;
29
+ };
30
+
31
+ /** One segment of a walkthrough: a sentence and the `github:` key of the code it describes. */
32
+ export type WalkthroughStep = { text: string; key: string };
33
+
34
+ /** At most this many segments: a walkthrough says where things are, it does not retell the code. */
35
+ export const MAX_WALKTHROUGH = 5;
36
+
37
+ /** `- a` items, a line without the dash continuing the item above it. */
38
+ const listItems = (lines: readonly string[]): string[] =>
39
+ lines.reduce<string[]>(
40
+ (items, line) =>
41
+ line.startsWith('-')
42
+ ? [...items, line.replace(/^-\s*/, '')]
43
+ : items.length > 0
44
+ ? [...items.slice(0, -1), `${items[items.length - 1]} ${line}`]
45
+ : items,
46
+ [],
47
+ );
48
+
49
+ /** `- <sentence>. github:<key>`, the key last; a step with no key is dropped. */
50
+ const parseStep = (item: string): WalkthroughStep[] => {
51
+ const match = item.match(/^(.*?)\s*(github:\S+)\s*$/);
52
+ return match ? [{ text: match[1].replace(/[\s.:—-]+$/, '').trim(), key: match[2] }] : [];
53
+ };
54
+
55
+ /**
56
+ * The walkthrough shown for a verdict: the reviewer's, or one segment per evidence key when the item is implemented
57
+ * in more than one place. Undefined for a single implementation, whose code chip already shows its declaration.
58
+ */
59
+ export const walkthroughOf = (verdict: Verdict): WalkthroughStep[] | undefined => {
60
+ if (verdict.walkthrough.length > 0) {
61
+ return verdict.walkthrough.slice(0, MAX_WALKTHROUGH);
62
+ }
63
+ return verdict.evidence.length > 1
64
+ ? verdict.evidence.slice(0, MAX_WALKTHROUGH).map((key) => ({ text: '', key }))
65
+ : undefined;
66
+ };
67
+
68
+ export type ReviewModel = {
69
+ /** Frontmatter: the reviewed spec's key, the commit the code was read at, when, and by whom. */
70
+ spec?: string;
71
+ commit?: string;
72
+ date?: string;
73
+ by?: string;
74
+ verdicts: Verdict[];
75
+ };
76
+
77
+ const severity = (status: VerdictStatus): number => VERDICT_STATUSES.indexOf(status);
78
+
79
+ const isStatus = (value?: string): value is VerdictStatus =>
80
+ value !== undefined && (VERDICT_STATUSES as readonly string[]).includes(value);
81
+
82
+ const parseFrontmatter = (text: string): Record<string, string> => {
83
+ const body = text.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? '';
84
+ return Object.fromEntries(
85
+ body.split('\n').flatMap((line) => {
86
+ const match = line.match(/^([\w-]+):\s*(.*?)\s*$/);
87
+ return match ? [[match[1], match[2]]] : [];
88
+ }),
89
+ );
90
+ };
91
+
92
+ /** The `verdict` blocks of a review document; a verdict with no known status is dropped. */
93
+ export const parseReview = (text: string): ReviewModel => {
94
+ const { spec, commit, date, by } = parseFrontmatter(text);
95
+ const verdicts = parseMdlBlocks(text)
96
+ .filter(({ type, id }) => type === 'verdict' && id)
97
+ .flatMap(({ id, title, body }): Verdict[] => {
98
+ const fields = parseFields(body);
99
+ const status = fields.get('status')?.inline;
100
+ if (!isStatus(status)) {
101
+ return [];
102
+ }
103
+ // A list may be inline (`[a, b]`), wrapped over several lines, or written as `- a` items.
104
+ const list = (name: string) =>
105
+ [fields.get(name)?.inline, ...(fields.get(name)?.lines ?? [])]
106
+ .join(',')
107
+ .split(',')
108
+ .map((value) => value.replace(/^[\s[-]+|[\s\]]+$/g, ''))
109
+ .filter(Boolean);
110
+ const note = [fields.get('note')?.inline, ...(fields.get('note')?.lines ?? [])].filter(Boolean).join(' ');
111
+ return [
112
+ {
113
+ id,
114
+ status,
115
+ ...(title && { summary: title }),
116
+ evidence: list('evidence'),
117
+ tests: list('tests'),
118
+ walkthrough: listItems(fields.get('walkthrough')?.lines ?? []).flatMap(parseStep),
119
+ ...(note && { note }),
120
+ },
121
+ ];
122
+ });
123
+ return { spec, commit, date, by, verdicts };
124
+ };
125
+
126
+ /**
127
+ * The status shown for a spec item: its own verdict, else the worst verdict of the items nested under it
128
+ * (`F-1` from `F-1.1`, `F-1.2`), so a feature reads as missing when any of its requirements is.
129
+ */
130
+ export const statusOf = (review: ReviewModel | undefined, id: string): VerdictStatus | undefined => {
131
+ if (!review) {
132
+ return undefined;
133
+ }
134
+ const own = review.verdicts.find((verdict) => verdict.id === id);
135
+ if (own) {
136
+ return own.status;
137
+ }
138
+ const nested = review.verdicts.filter((verdict) => verdict.id.startsWith(`${id}.`));
139
+ return nested.length > 0
140
+ ? nested.reduce((worst, { status }) => (severity(status) > severity(worst) ? status : worst), nested[0].status)
141
+ : undefined;
142
+ };
143
+
144
+ /** Verdict counts per status, in display order. */
145
+ export const summarizeReview = (review: ReviewModel): { status: VerdictStatus; count: number }[] =>
146
+ VERDICT_STATUSES.map((status) => ({
147
+ status,
148
+ count: review.verdicts.filter((verdict) => verdict.status === status).length,
149
+ })).filter(({ count }) => count > 0);
150
+
151
+ /** The files a review cites (evidence, tests and walkthrough steps), without fragments and in a stable order. */
152
+ export const citedFiles = (review: ReviewModel): string[] =>
153
+ [
154
+ ...new Set(
155
+ review.verdicts
156
+ .flatMap(({ evidence, tests, walkthrough }) => [...evidence, ...tests, ...walkthrough.map(({ key }) => key)])
157
+ .map(parseSourceKey)
158
+ .filter((key) => key !== undefined)
159
+ .map((key) => formatSourceKey(key, false)),
160
+ ),
161
+ ].sort();
162
+
163
+ /** Keys attached to a spec item from outside its text, e.g. a review's evidence; `id` may name a nested req (`F-1.2`). */
164
+ export type Annotation = {
165
+ id: string;
166
+ /** The code that implements the item. */
167
+ keys: readonly SourceKey[];
168
+ /** Whether a review found tests for the item; absent when it does not say. */
169
+ testing?: 'tested' | 'untested';
170
+ /** The tests that exercise the item. */
171
+ tests?: readonly SourceKey[];
172
+ };
173
+
174
+ /**
175
+ * A review's verdicts as annotations: the code that implements each item and the tests that exercise it. `done` means
176
+ * tested by definition (see `VERDICT_STATUSES`); nothing is said about testing code that does not exist.
177
+ */
178
+ export const reviewAnnotations = (review: ReviewModel | undefined): Annotation[] =>
179
+ (review?.verdicts ?? []).map(({ id, status, evidence, tests }): Annotation => {
180
+ const keys = evidence.map(parseSourceKey).filter((key) => key !== undefined);
181
+ const testKeys = tests.map(parseSourceKey).filter((key) => key !== undefined);
182
+ const testing = testKeys.length > 0 || status === 'done' ? 'tested' : status === 'missing' ? undefined : 'untested';
183
+ return { id, keys, ...(testing && { testing }), ...(testKeys.length > 0 && { tests: testKeys }) };
184
+ });
@@ -0,0 +1,63 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ /** The prefix of a key written in text: `github:owner/repo/path`. */
6
+ export const GITHUB_SOURCE = 'github';
7
+
8
+ /**
9
+ * A location in a GitHub repository: `github:owner/repo/path/to/file[#fragment]`.
10
+ * The fragment names a spec block (`#F-1`, `#Scene`) or a code symbol (`#MyClass`).
11
+ */
12
+ export type SourceKey = {
13
+ owner: string;
14
+ repo: string;
15
+ /** POSIX path relative to the repository root. */
16
+ path: string;
17
+ fragment?: string;
18
+ };
19
+
20
+ /** Matches a key in running text; a trailing `.` is sentence punctuation and is trimmed by {@link findSourceKeys}. */
21
+ export const SOURCE_KEY_PATTERN = /github:[\w.-]+\/[\w.-]+\/[\w./@+-]+(?:#[\w$.-]+)?/g;
22
+
23
+ /** Parses `github:owner/repo/path[#fragment]`; undefined when the text is not a key. */
24
+ export const parseSourceKey = (text: string): SourceKey | undefined => {
25
+ const match = text.trim().match(/^github:([\w.-]+)\/([\w.-]+)\/([^#\s]+)(?:#([\w$.-]+))?$/);
26
+ if (!match) {
27
+ return undefined;
28
+ }
29
+ const [, owner, repo, path, fragment] = match;
30
+ return { owner, repo, path, ...(fragment && { fragment }) };
31
+ };
32
+
33
+ /** Formats a key; the fragment is included only when asked for. */
34
+ export const formatSourceKey = ({ owner, repo, path, fragment }: SourceKey, withFragment = true): string =>
35
+ `${GITHUB_SOURCE}:${owner}/${repo}/${path}${withFragment && fragment ? `#${fragment}` : ''}`;
36
+
37
+ /** `owner/repo`, the identity a local checkout is matched by. */
38
+ export const repoId = ({ owner, repo }: Pick<SourceKey, 'owner' | 'repo'>): string => `${owner}/${repo}`;
39
+
40
+ /** `owner/repo` from a GitHub remote URL (`git@github.com:o/r.git`, `https://github.com/o/r`). */
41
+ export const parseGitHubRemote = (url: string): string | undefined =>
42
+ url
43
+ .match(/github\.com[:/]([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/)
44
+ ?.slice(1, 3)
45
+ .join('/');
46
+
47
+ /** Whether the key points at a spec document rather than at code. */
48
+ export const isSpecKey = (key: SourceKey): boolean => key.path.endsWith('.mdl');
49
+
50
+ /** The review written beside a spec: `SPEC.mdl` → `SPEC.review.mdl`. */
51
+ export const reviewKeyOf = (key: SourceKey): SourceKey => ({
52
+ owner: key.owner,
53
+ repo: key.repo,
54
+ path: key.path.replace(/\.mdl$/, '.review.mdl'),
55
+ });
56
+
57
+ /** Every key mentioned in a text, with its offsets. */
58
+ export const findSourceKeys = (text: string): { from: number; to: number; key: SourceKey; raw: string }[] =>
59
+ [...text.matchAll(SOURCE_KEY_PATTERN)].flatMap((match) => {
60
+ const raw = match[0].replace(/\.+$/, '');
61
+ const key = parseSourceKey(raw);
62
+ return key ? [{ from: match.index, to: match.index + raw.length, key, raw }] : [];
63
+ });
@@ -0,0 +1,47 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { describe, test } from 'vitest';
6
+
7
+ import { declarationSnippet, findSymbolLine } from './symbol.ts';
8
+
9
+ describe('symbol lookup', () => {
10
+ const source = [
11
+ 'import x from "y";',
12
+ '',
13
+ 'export class Spec {',
14
+ ' static make(): Spec {',
15
+ ' return new Spec();',
16
+ ' }',
17
+ '}',
18
+ '',
19
+ 'export const make = () => Spec.make();',
20
+ ].join('\n');
21
+
22
+ test('finds declarations before mentions, and members after their owner', ({ expect }) => {
23
+ expect(findSymbolLine(source, 'Spec')).toBe(3);
24
+ expect(findSymbolLine(source, 'make')).toBe(9);
25
+ expect(findSymbolLine(source, 'Spec.make')).toBe(4);
26
+ expect(findSymbolLine(source, 'Missing')).toBeUndefined();
27
+ });
28
+
29
+ test('a snippet runs from the declaration to where its brackets close', ({ expect }) => {
30
+ expect(declarationSnippet(source, 'Spec.make')).toEqual({
31
+ line: 4,
32
+ lines: [' static make(): Spec {', ' return new Spec();', ' }'],
33
+ truncated: false,
34
+ });
35
+ expect(declarationSnippet(source, 'make')).toEqual({
36
+ line: 9,
37
+ lines: ['export const make = () => Spec.make();'],
38
+ truncated: false,
39
+ });
40
+ expect(declarationSnippet(source, 'Missing')).toBeUndefined();
41
+ // No symbol: the file's opening lines, after the copyright header.
42
+ expect(declarationSnippet(['//', '// Copyright', '//', '', 'import a;', 'a();'].join('\n'))).toMatchObject({
43
+ line: 5,
44
+ lines: ['import a;', 'a();'],
45
+ });
46
+ });
47
+ });
@@ -0,0 +1,96 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ const escape = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
6
+
7
+ /** Declarations, most specific first: a top-level declaration beats a member, which beats a bare mention. */
8
+ const declarationPatterns = (name: string): RegExp[] => {
9
+ const id = escape(name);
10
+ return [
11
+ new RegExp(
12
+ `^\\s*(?:export\\s+)?(?:default\\s+)?(?:declare\\s+)?(?:abstract\\s+)?(?:async\\s+)?(?:class|interface|type|enum|function\\*?|const|let|var|namespace)\\s+${id}\\b`,
13
+ ),
14
+ new RegExp(
15
+ `^\\s*(?:(?:public|private|protected|static|readonly|override|async|get|set|#)\\s*)*${id}\\s*(?:\\??[:(<=])`,
16
+ ),
17
+ new RegExp(`\\b${id}\\b`),
18
+ ];
19
+ };
20
+
21
+ /**
22
+ * The 1-based line that declares a symbol in a source file, or undefined when it is not there. A dotted name
23
+ * (`Spec.make`, `Class.method`) finds the outer declaration first and then the member after it.
24
+ */
25
+ export const findSymbolLine = (content: string, symbol: string): number | undefined => {
26
+ const lines = content.split('\n');
27
+ let start = 0;
28
+ let found: number | undefined;
29
+ for (const [index, part] of symbol.split('.').entries()) {
30
+ found = undefined;
31
+ const [declaration, member, mention] = declarationPatterns(part);
32
+ // After the owner, a member is what the dotted name means; a later top-level namesake is not.
33
+ for (const pattern of index === 0 ? [declaration, member, mention] : [member, declaration, mention]) {
34
+ const index = lines.findIndex((line, number) => number >= start && pattern.test(line));
35
+ if (index >= 0) {
36
+ found = index;
37
+ break;
38
+ }
39
+ }
40
+ if (found === undefined) {
41
+ return undefined;
42
+ }
43
+ start = found + 1;
44
+ }
45
+ return found === undefined ? undefined : found + 1;
46
+ };
47
+
48
+ /** The longest declaration a snippet shows; a longer one ends with an ellipsis line. */
49
+ const MAX_SNIPPET_LINES = 16;
50
+
51
+ /** A short excerpt of a source file: its first line number (1-based) and its lines. */
52
+ export type Snippet = { line: number; lines: string[]; truncated: boolean };
53
+
54
+ const depthChange = (line: string): number => {
55
+ // Quoted text and line comments do not open or close a block.
56
+ const code = line.replace(/(["'`])(?:\\.|(?!\1).)*\1/g, '').replace(/\/\/.*$/, '');
57
+ return (code.match(/[{([]/g)?.length ?? 0) - (code.match(/[})\]]/g)?.length ?? 0);
58
+ };
59
+
60
+ /**
61
+ * The declaration a key names, as shown on hover: from the declaring line to where its brackets close, or the
62
+ * file's opening lines (after the copyright header) when there is no symbol. Undefined when the symbol is not there.
63
+ */
64
+ export const declarationSnippet = (content: string, symbol?: string): Snippet | undefined => {
65
+ const lines = content.split('\n');
66
+ let start: number;
67
+ if (symbol) {
68
+ const found = findSymbolLine(content, symbol);
69
+ if (found === undefined) {
70
+ return undefined;
71
+ }
72
+ start = found - 1;
73
+ } else {
74
+ start = 0;
75
+ while (start < lines.length && (lines[start].startsWith('//') || lines[start].trim() === '')) {
76
+ start++;
77
+ }
78
+ }
79
+
80
+ let end = start;
81
+ let depth = depthChange(lines[start] ?? '');
82
+ // A declaration continues while a bracket it opened is still open.
83
+ while (symbol && depth > 0 && end + 1 < lines.length) {
84
+ end++;
85
+ depth += depthChange(lines[end]);
86
+ }
87
+ if (!symbol) {
88
+ end = Math.min(lines.length - 1, start + MAX_SNIPPET_LINES - 1);
89
+ }
90
+ const truncated = end - start + 1 > MAX_SNIPPET_LINES;
91
+ return {
92
+ line: start + 1,
93
+ lines: lines.slice(start, truncated ? start + MAX_SNIPPET_LINES : end + 1),
94
+ truncated: truncated || (!symbol && end < lines.length - 1),
95
+ };
96
+ };
@@ -0,0 +1,6 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ export * from './spec-index.ts';
6
+ export * from './parse.ts';
@@ -0,0 +1,22 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ /** The flat `key: value` pairs of a document's YAML frontmatter. */
6
+ export const frontmatter = (text: string): Record<string, string> =>
7
+ Object.fromEntries(
8
+ (text.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? '').split('\n').flatMap((line) => {
9
+ const match = line.match(/^([\w-]+):\s*(.*?)\s*(?:#.*)?$/);
10
+ return match ? [[match[1], match[2]]] : [];
11
+ }),
12
+ );
13
+
14
+ /** The `req` lines nested in a block body, with each one's line offset within the body. */
15
+ export const reqs = (body: string): { id: string; title: string; offset: number }[] =>
16
+ body.split('\n').flatMap((text, offset) => {
17
+ const req = text.match(/^\s+req\s+([A-Za-z][\w.-]*)\s*:\s*(.*)$/);
18
+ return req ? [{ id: req[1], title: req[2], offset }] : [];
19
+ });
20
+
21
+ /** The ids of the `req` lines nested in a block body. */
22
+ export const reqIds = (body: string): string[] => reqs(body).map(({ id }) => id);
@@ -0,0 +1,56 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { describe, test } from 'vitest';
6
+
7
+ import { indexSpecs, isIndexedSpec } from './spec-index.ts';
8
+
9
+ const spec = (id: string | undefined) =>
10
+ [
11
+ ...(id ? ['---', `id: ${id}`, '---', ''] : []),
12
+ '# Spec',
13
+ '',
14
+ '```mdl',
15
+ 'type Foo',
16
+ '```',
17
+ '',
18
+ '```mdl',
19
+ 'feat F-1: A feature',
20
+ ' req F-1.1: First requirement.',
21
+ '```',
22
+ '',
23
+ ].join('\n');
24
+
25
+ describe('indexSpecs', () => {
26
+ test('indexes a spec by its frontmatter id with its block and req ids', ({ expect }) => {
27
+ const index = indexSpecs([{ path: 'a/SPEC.mdl', text: spec('org.example.a') }]);
28
+ expect(index.specs['org.example.a'].path).toBe('a/SPEC.mdl');
29
+ expect(index.specs['org.example.a'].items).toEqual(expect.arrayContaining(['Foo', 'F-1', 'F-1.1']));
30
+ expect(index.duplicates).toEqual({});
31
+ });
32
+
33
+ test('reports a duplicated id on every path and does not resolve it', ({ expect }) => {
34
+ const index = indexSpecs([
35
+ { path: 'a/SPEC.mdl', text: spec('org.example.a') },
36
+ { path: 'b/SPEC.mdl', text: spec('org.example.a') },
37
+ ]);
38
+ expect(index.specs['org.example.a']).toBeUndefined();
39
+ expect(index.duplicates['org.example.a']).toEqual(['a/SPEC.mdl', 'b/SPEC.mdl']);
40
+ });
41
+
42
+ test('skips a file with no frontmatter id', ({ expect }) => {
43
+ const index = indexSpecs([{ path: 'a/SPEC.mdl', text: spec(undefined) }]);
44
+ expect(index).toEqual({ specs: {}, duplicates: {} });
45
+ });
46
+ });
47
+
48
+ describe('isIndexedSpec', () => {
49
+ test('keeps specs and dialects, leaves out reviews, fixtures and lang examples', ({ expect }) => {
50
+ expect(isIndexedSpec('packages/plugins/plugin-code/PLUGIN.mdl')).toBe(true);
51
+ expect(isIndexedSpec('packages/reflect/deus/lang/core.mdl')).toBe(true);
52
+ expect(isIndexedSpec('packages/plugins/plugin-code/PLUGIN.review.mdl')).toBe(false);
53
+ expect(isIndexedSpec('packages/reflect/deus/src/cli/__fixtures__/SPEC.mdl')).toBe(false);
54
+ expect(isIndexedSpec('packages/reflect/deus/lang/examples/chess-1.mdl')).toBe(false);
55
+ });
56
+ });
@@ -0,0 +1,49 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { parseMdlBlocks } from '../extension/blocks.ts';
6
+ import { frontmatter, reqIds } from './parse.ts';
7
+
8
+ /** One spec in the index: where it lives and every id a reference into it can name. */
9
+ export type SpecEntry = {
10
+ /** POSIX, repo-relative. */
11
+ path: string;
12
+ /** Every block id and `req` id of the spec. */
13
+ items: string[];
14
+ };
15
+
16
+ export type SpecIndex = {
17
+ /** Specs by frontmatter id; a duplicated id is absent. */
18
+ specs: Record<string, SpecEntry>;
19
+ /** Each duplicated id with every path that claims it. */
20
+ duplicates: Record<string, string[]>;
21
+ };
22
+
23
+ /** Whether the index holds a tracked `.mdl` path; `lang/examples/` is excluded because its files share one id. */
24
+ export const isIndexedSpec = (path: string): boolean =>
25
+ !path.endsWith('.review.mdl') && !path.includes('__fixtures__') && !path.includes('/deus/lang/examples/');
26
+
27
+ const specItems = (text: string): string[] => [
28
+ ...new Set(parseMdlBlocks(text).flatMap(({ id, body }) => [...(id ? [id] : []), ...reqIds(body)])),
29
+ ];
30
+
31
+ /** Indexes spec texts by frontmatter id; a file with no id is skipped. */
32
+ export const indexSpecs = (files: { path: string; text: string }[]): SpecIndex => {
33
+ const claims = new Map<string, { path: string; items: string[] }[]>();
34
+ for (const { path, text } of files) {
35
+ const id = frontmatter(text).id;
36
+ if (id) {
37
+ claims.set(id, [...(claims.get(id) ?? []), { path, items: specItems(text) }]);
38
+ }
39
+ }
40
+ const index: SpecIndex = { specs: {}, duplicates: {} };
41
+ for (const [id, entries] of claims) {
42
+ if (entries.length === 1) {
43
+ index.specs[id] = entries[0];
44
+ } else {
45
+ index.duplicates[id] = entries.map((entry) => entry.path);
46
+ }
47
+ }
48
+ return index;
49
+ };