@dxos/deus 0.0.0-stage → 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +105 -0
- package/README.md +24 -2
- package/bin/deus.ts +42 -0
- package/dist/lib/chunk-blocks.mjs +151 -0
- package/dist/lib/chunk-blocks.mjs.map +1 -0
- package/dist/lib/chunk-check.mjs +452 -0
- package/dist/lib/chunk-check.mjs.map +1 -0
- package/dist/lib/chunk-completion.mjs +112 -0
- package/dist/lib/chunk-completion.mjs.map +1 -0
- package/dist/lib/chunk-extension.mjs +396 -0
- package/dist/lib/chunk-extension.mjs.map +1 -0
- package/dist/lib/chunk-parse.mjs +21 -0
- package/dist/lib/chunk-parse.mjs.map +1 -0
- package/dist/lib/cli.mjs +946 -0
- package/dist/lib/cli.mjs.map +1 -0
- package/dist/lib/extension.mjs +4 -0
- package/dist/lib/index.mjs +6 -0
- package/dist/lib/parse.mjs +4 -0
- package/dist/lib/review.mjs +260 -0
- package/dist/lib/review.mjs.map +1 -0
- package/dist/lib/spec-index.mjs +28 -0
- package/dist/lib/spec-index.mjs.map +1 -0
- package/dist/types/bin/deus.d.ts +3 -0
- package/dist/types/bin/deus.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts +7 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts +5 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/changelog.d.ts +25 -0
- package/dist/types/src/cli/changelog.d.ts.map +1 -0
- package/dist/types/src/cli/cli.test.d.ts +2 -0
- package/dist/types/src/cli/cli.test.d.ts.map +1 -0
- package/dist/types/src/cli/errors.d.ts +183 -0
- package/dist/types/src/cli/errors.d.ts.map +1 -0
- package/dist/types/src/cli/features.d.ts +58 -0
- package/dist/types/src/cli/features.d.ts.map +1 -0
- package/dist/types/src/cli/git.d.ts +8 -0
- package/dist/types/src/cli/git.d.ts.map +1 -0
- package/dist/types/src/cli/index.d.ts +12 -0
- package/dist/types/src/cli/index.d.ts.map +1 -0
- package/dist/types/src/cli/lint.d.ts +17 -0
- package/dist/types/src/cli/lint.d.ts.map +1 -0
- package/dist/types/src/cli/qa-lint.d.ts +40 -0
- package/dist/types/src/cli/qa-lint.d.ts.map +1 -0
- package/dist/types/src/cli/qa.d.ts +86 -0
- package/dist/types/src/cli/qa.d.ts.map +1 -0
- package/dist/types/src/cli/review.d.ts +38 -0
- package/dist/types/src/cli/review.d.ts.map +1 -0
- package/dist/types/src/cli/spec-index.d.ts +17 -0
- package/dist/types/src/cli/spec-index.d.ts.map +1 -0
- package/dist/types/src/extension/blocks.d.ts +65 -0
- package/dist/types/src/extension/blocks.d.ts.map +1 -0
- package/dist/types/src/extension/check.d.ts +99 -0
- package/dist/types/src/extension/check.d.ts.map +1 -0
- package/dist/types/src/extension/check.test.d.ts +2 -0
- package/dist/types/src/extension/check.test.d.ts.map +1 -0
- package/dist/types/src/extension/code.d.ts +7 -0
- package/dist/types/src/extension/code.d.ts.map +1 -0
- package/dist/types/src/extension/complete.d.ts +6 -0
- package/dist/types/src/extension/complete.d.ts.map +1 -0
- package/dist/types/src/extension/completion.d.ts +10 -0
- package/dist/types/src/extension/completion.d.ts.map +1 -0
- package/dist/types/src/extension/constants.d.ts +6 -0
- package/dist/types/src/extension/constants.d.ts.map +1 -0
- package/dist/types/src/extension/fences.d.ts +10 -0
- package/dist/types/src/extension/fences.d.ts.map +1 -0
- package/dist/types/src/extension/gen/mdl.d.ts +3 -0
- package/dist/types/src/extension/gen/mdl.d.ts.map +1 -0
- package/dist/types/src/extension/gen/mdl.terms.d.ts +2 -0
- package/dist/types/src/extension/gen/mdl.terms.d.ts.map +1 -0
- package/dist/types/src/extension/index.d.ts +8 -0
- package/dist/types/src/extension/index.d.ts.map +1 -0
- package/dist/types/src/extension/language.d.ts +20 -0
- package/dist/types/src/extension/language.d.ts.map +1 -0
- package/dist/types/src/extension/lint.d.ts +8 -0
- package/dist/types/src/extension/lint.d.ts.map +1 -0
- package/dist/types/src/extension/parse.d.ts +6 -0
- package/dist/types/src/extension/parse.d.ts.map +1 -0
- package/dist/types/src/extension/parser.test.d.ts +2 -0
- package/dist/types/src/extension/parser.test.d.ts.map +1 -0
- package/dist/types/src/extension/refs.d.ts +32 -0
- package/dist/types/src/extension/refs.d.ts.map +1 -0
- package/dist/types/src/extension/refs.test.d.ts +2 -0
- package/dist/types/src/extension/refs.test.d.ts.map +1 -0
- package/dist/types/src/extension/syntax.d.ts +12 -0
- package/dist/types/src/extension/syntax.d.ts.map +1 -0
- package/dist/types/src/index.d.ts +3 -0
- package/dist/types/src/index.d.ts.map +1 -0
- package/dist/types/src/review/fields.d.ts +9 -0
- package/dist/types/src/review/fields.d.ts.map +1 -0
- package/dist/types/src/review/index.d.ts +5 -0
- package/dist/types/src/review/index.d.ts.map +1 -0
- package/dist/types/src/review/review.d.ts +70 -0
- package/dist/types/src/review/review.d.ts.map +1 -0
- package/dist/types/src/review/review.test.d.ts +2 -0
- package/dist/types/src/review/review.test.d.ts.map +1 -0
- package/dist/types/src/review/source-key.d.ts +35 -0
- package/dist/types/src/review/source-key.d.ts.map +1 -0
- package/dist/types/src/review/symbol.d.ts +17 -0
- package/dist/types/src/review/symbol.d.ts.map +1 -0
- package/dist/types/src/review/symbol.test.d.ts +2 -0
- package/dist/types/src/review/symbol.test.d.ts.map +1 -0
- package/dist/types/src/spec-index/index.d.ts +3 -0
- package/dist/types/src/spec-index/index.d.ts.map +1 -0
- package/dist/types/src/spec-index/parse.d.ts +11 -0
- package/dist/types/src/spec-index/parse.d.ts.map +1 -0
- package/dist/types/src/spec-index/spec-index.d.ts +21 -0
- package/dist/types/src/spec-index/spec-index.d.ts.map +1 -0
- package/dist/types/src/spec-index/spec-index.test.d.ts +2 -0
- package/dist/types/src/spec-index/spec-index.test.d.ts.map +1 -0
- package/dist/types/tsconfig.tsbuildinfo +1 -0
- package/docs/DESIGN.md +561 -0
- package/docs/IDIOMS.md +265 -0
- package/lang/PLUGIN-.template.mdl +115 -0
- package/lang/app.mdl +200 -0
- package/lang/changelog.mdl +184 -0
- package/lang/core.mdl +203 -0
- package/lang/examples/chess-1.mdl +149 -0
- package/lang/examples/chess-2.mdl +203 -0
- package/lang/examples/chess-3.mdl +231 -0
- package/lang/features.mdl +92 -0
- package/lang/plugin.mdl +59 -0
- package/lang/qa.mdl +383 -0
- package/lang/review.mdl +103 -0
- package/lang/sql.mdl +72 -0
- package/package.json +74 -3
- package/src/cli/__fixtures__/bad-decision.mdl +13 -0
- package/src/cli/__fixtures__/features/CYCLE.mdl +25 -0
- package/src/cli/__fixtures__/features/FEATURES.mdl +47 -0
- package/src/cli/__fixtures__/features/SPEC.mdl +22 -0
- package/src/cli/__fixtures__/features/SPEC.review.mdl +32 -0
- package/src/cli/__fixtures__/features/TASKS.md +5 -0
- package/src/cli/__fixtures__/lint-refs/SPEC.mdl +7 -0
- package/src/cli/__fixtures__/lint-refs/SPEC.review.mdl +7 -0
- package/src/cli/__fixtures__/qa-lint/packages/plugins/plugin-risky/PLUGIN.mdl +29 -0
- package/src/cli/__fixtures__/qa-list/plugin-sample/spec/PLUGIN.mdl +51 -0
- package/src/cli/__fixtures__/review/SPEC.mdl +23 -0
- package/src/cli/__fixtures__/review/SPEC.review.mdl +26 -0
- package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.review.mdl +14 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.ts +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.ts +7 -0
- package/src/cli/changelog.ts +122 -0
- package/src/cli/cli.test.ts +359 -0
- package/src/cli/errors.ts +23 -0
- package/src/cli/features.ts +320 -0
- package/src/cli/git.ts +35 -0
- package/src/cli/index.ts +27 -0
- package/src/cli/lint.ts +75 -0
- package/src/cli/qa-lint.ts +206 -0
- package/src/cli/qa.ts +300 -0
- package/src/cli/review.ts +359 -0
- package/src/cli/spec-index.ts +54 -0
- package/src/extension/blocks.ts +169 -0
- package/src/extension/check.test.ts +629 -0
- package/src/extension/check.ts +552 -0
- package/src/extension/code.ts +99 -0
- package/src/extension/complete.ts +34 -0
- package/src/extension/completion.ts +64 -0
- package/src/extension/constants.ts +28 -0
- package/src/extension/fences.ts +270 -0
- package/src/extension/gen/mdl.terms.ts +16 -0
- package/src/extension/gen/mdl.ts +16 -0
- package/src/extension/index.ts +25 -0
- package/src/extension/language.ts +33 -0
- package/src/extension/lint.ts +19 -0
- package/src/extension/mdl.grammar +60 -0
- package/src/extension/parse.ts +31 -0
- package/src/extension/parser.test.ts +248 -0
- package/src/extension/refs.test.ts +95 -0
- package/src/extension/refs.ts +94 -0
- package/src/extension/syntax.ts +25 -0
- package/src/index.ts +6 -0
- package/src/review/fields.ts +31 -0
- package/src/review/index.ts +8 -0
- package/src/review/review.test.ts +111 -0
- package/src/review/review.ts +184 -0
- package/src/review/source-key.ts +63 -0
- package/src/review/symbol.test.ts +47 -0
- package/src/review/symbol.ts +96 -0
- package/src/spec-index/index.ts +6 -0
- package/src/spec-index/parse.ts +22 -0
- package/src/spec-index/spec-index.test.ts +56 -0
- package/src/spec-index/spec-index.ts +49 -0
package/docs/IDIOMS.md
ADDED
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
# Idioms
|
|
2
|
+
|
|
3
|
+
> A named, canonical way of doing one thing in DXOS, demonstrated by real code
|
|
4
|
+
> that the build system compiles and tests.
|
|
5
|
+
|
|
6
|
+
## What an idiom is
|
|
7
|
+
|
|
8
|
+
An **idiom** is a recurring solution to a problem in the DXOS codebase, given a
|
|
9
|
+
short slug and pinned to a single concrete artifact — a storybook story, a
|
|
10
|
+
test, a hook, a function, or a type. The artifact _is_ the canonical example;
|
|
11
|
+
the idiom is just metadata that names it, explains when to use it, and links it
|
|
12
|
+
to related symbols.
|
|
13
|
+
|
|
14
|
+
Idioms exist because:
|
|
15
|
+
|
|
16
|
+
- Agents need to find the right pattern by name before reading code.
|
|
17
|
+
- Humans need a single place to point to when reviewing a PR ("use the
|
|
18
|
+
`org.dxos.react-ui-menu.toolbarMenu` idiom").
|
|
19
|
+
- The codebase needs guard rails against drift — when the canonical artifact
|
|
20
|
+
breaks, the idiom breaks, and CI surfaces it.
|
|
21
|
+
|
|
22
|
+
### Principles
|
|
23
|
+
|
|
24
|
+
**Code is ground truth.** An idiom cannot exist without a compiling, exported
|
|
25
|
+
artifact that demonstrates it. No prose-only idioms, no aspirational idioms.
|
|
26
|
+
|
|
27
|
+
**Nothing is an idiom by default.** A storybook story is just a story; a test
|
|
28
|
+
is just a test. Only an explicit `@idiom <slug>` tag promotes it.
|
|
29
|
+
|
|
30
|
+
**JSDoc carries the metadata.** Idioms travel with the code they describe.
|
|
31
|
+
No sidecar files, no central registry to keep in sync.
|
|
32
|
+
|
|
33
|
+
**Distributed authoring, central discovery.** Any package can declare idioms.
|
|
34
|
+
A build-time scanner (`moon run introspect:idioms`) harvests them into a single
|
|
35
|
+
catalog.
|
|
36
|
+
|
|
37
|
+
**Slugs are NSIDs.** Every idiom slug must be a well-formed AT Protocol NSID
|
|
38
|
+
(see [`@dxos/util.id`](../../../common/util/src/id.ts) and
|
|
39
|
+
<https://atproto.com/specs/nsid>). Authority segments are reverse-domain dotted
|
|
40
|
+
(`org.dxos.<package>`), the name segment is camelCase. One namespace across
|
|
41
|
+
the monorepo.
|
|
42
|
+
|
|
43
|
+
Examples:
|
|
44
|
+
`org.dxos.react-ui-menu.toolbarMenu`,
|
|
45
|
+
`org.dxos.echo-react.reactiveQuery`,
|
|
46
|
+
`org.dxos.app-framework.capabilityProvider`.
|
|
47
|
+
|
|
48
|
+
## Tagging
|
|
49
|
+
|
|
50
|
+
An idiom is declared by adding an `@idiom` JSDoc tag to an exported symbol or a
|
|
51
|
+
top-level `test(...)` call.
|
|
52
|
+
|
|
53
|
+
### Tag shape
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
/**
|
|
57
|
+
* <Leading prose — becomes the idiom summary.>
|
|
58
|
+
*
|
|
59
|
+
* @idiom <slug>
|
|
60
|
+
* applies: <when this pattern fits>
|
|
61
|
+
* instead-of: <what this replaces> [{@link AntiSymbol}]
|
|
62
|
+
* uses: {@link SymbolA}, {@link SymbolB}
|
|
63
|
+
* related: <slug>, <slug>
|
|
64
|
+
*/
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
| Field | Required | Meaning |
|
|
68
|
+
| ------------ | -------- | ---------------------------------------------------------- |
|
|
69
|
+
| `<slug>` | yes | Globally unique [NSID](https://atproto.com/specs/nsid). |
|
|
70
|
+
| `applies` | yes | One-line applicability — when to reach for this. |
|
|
71
|
+
| `instead-of` | no | Anti-pattern this replaces. Prose plus optional `{@link}`. |
|
|
72
|
+
| `uses` | no | Comma-separated `{@link}` references to the key symbols. |
|
|
73
|
+
| `related` | no | NSID slugs of related idioms. |
|
|
74
|
+
|
|
75
|
+
The leading JSDoc paragraph (above the `@idiom` line) is the **summary**: a
|
|
76
|
+
two-to-four sentence rationale. If the host symbol's own JSDoc already explains
|
|
77
|
+
the pattern well, the leading prose may be empty — the agent will read the
|
|
78
|
+
source.
|
|
79
|
+
|
|
80
|
+
`{@link}` references are standard JSDoc and resolve against the introspect
|
|
81
|
+
symbol graph.
|
|
82
|
+
|
|
83
|
+
### Hosts
|
|
84
|
+
|
|
85
|
+
The `@idiom` tag is recognized on:
|
|
86
|
+
|
|
87
|
+
- **Storybook story exports** — `export const X: Story = { … }` in any
|
|
88
|
+
`*.stories.tsx` file. Best for UI patterns.
|
|
89
|
+
- **Tests** — top-level `test('…', …)` calls in any `*.test.ts`. Best for
|
|
90
|
+
behavioral patterns (ECHO queries, effect flows, capability wiring). The tag
|
|
91
|
+
goes on a JSDoc immediately preceding the `test(...)` call.
|
|
92
|
+
- **Exported symbols** — any `export` declaration: function, class, hook, type,
|
|
93
|
+
schema, constant.
|
|
94
|
+
|
|
95
|
+
A test or story is _not_ an idiom by default — only the `@idiom` tag makes it
|
|
96
|
+
one. There is no implicit promotion based on naming, location, or other
|
|
97
|
+
heuristics.
|
|
98
|
+
|
|
99
|
+
If multiple artifacts demonstrate the same pattern, only one carries the tag —
|
|
100
|
+
the most representative. Others should link back via `related:` if useful.
|
|
101
|
+
|
|
102
|
+
## Examples
|
|
103
|
+
|
|
104
|
+
### UI pattern (story host)
|
|
105
|
+
|
|
106
|
+
```tsx
|
|
107
|
+
// packages/ui/react-ui-menu/src/Menu.stories.tsx
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Reactive toolbar driven by an atom-backed actions hook.
|
|
111
|
+
*
|
|
112
|
+
* Defining actions inside a hook lets them subscribe to reactive state
|
|
113
|
+
* (echo, atoms, settings) without re-rendering the toolbar shell. The
|
|
114
|
+
* menu structure is data, not JSX.
|
|
115
|
+
*
|
|
116
|
+
* @idiom org.dxos.react-ui-menu.toolbarMenu
|
|
117
|
+
* applies: Toolbars whose entries depend on reactive state
|
|
118
|
+
* instead-of: {@link Toolbar.Root} with hand-wired children
|
|
119
|
+
* uses: {@link useMenuActions}, {@link Menu.Root}
|
|
120
|
+
* related: org.dxos.react-ui-menu.menuActions, org.dxos.app-framework.actionGraph
|
|
121
|
+
*/
|
|
122
|
+
export const ReactiveToolbar: Story = {
|
|
123
|
+
render: () => {
|
|
124
|
+
const actions = useMenuActions(/* ... */);
|
|
125
|
+
return <Menu.Root actions={actions} />;
|
|
126
|
+
},
|
|
127
|
+
};
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### Behavioral pattern (test host)
|
|
131
|
+
|
|
132
|
+
```ts
|
|
133
|
+
// packages/sdk/echo-react/src/use-query.test.tsx
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Live ECHO query that re-renders the component on insert/update/delete.
|
|
137
|
+
*
|
|
138
|
+
* @idiom org.dxos.echo-react.reactiveQuery
|
|
139
|
+
* applies: Subscribing to a live ECHO collection from a React component
|
|
140
|
+
* instead-of: imperatively re-reading the space inside an effect
|
|
141
|
+
* uses: {@link Query}, {@link useQuery}
|
|
142
|
+
*/
|
|
143
|
+
test('reactive query updates on insert', ({ expect }) => {
|
|
144
|
+
const tasks = useQuery(space, Query.type(Task));
|
|
145
|
+
// ...assertions that the query reacts...
|
|
146
|
+
});
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Pure-API pattern (symbol host)
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
// packages/sdk/app-framework/src/define-capability.ts
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* @idiom org.dxos.app-framework.capabilityProvider
|
|
156
|
+
* applies: Exposing a service resolvable by id from elsewhere in the app
|
|
157
|
+
* uses: {@link contributes}, {@link Capability}
|
|
158
|
+
* related: org.dxos.app-framework.operationHandler, org.dxos.app-framework.pluginScaffold
|
|
159
|
+
*/
|
|
160
|
+
export const defineCapability = /* ... */;
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Discovery
|
|
164
|
+
|
|
165
|
+
Idioms are harvested by a scanner exposed as `scanIdioms()` from
|
|
166
|
+
`@dxos/introspect/idioms`, and invoked by the `dx reflect idiom list` CLI command.
|
|
167
|
+
|
|
168
|
+
### POC behavior (this PR)
|
|
169
|
+
|
|
170
|
+
The current POC is regex-based — it does **not** use the ts-morph indexer:
|
|
171
|
+
|
|
172
|
+
1. Walks `packages/**/src/**/*.{ts,tsx}` via `glob`.
|
|
173
|
+
2. Locates JSDoc blocks containing `@idiom <nsid>` on stories, tests, and
|
|
174
|
+
exported symbols.
|
|
175
|
+
3. Parses the indented key:value body.
|
|
176
|
+
4. Captures source location, a best-effort symbol/test name, and a host kind
|
|
177
|
+
(`story` / `test` / `symbol`).
|
|
178
|
+
5. Throws if the slug fails NSID validation or if `applies:` is missing.
|
|
179
|
+
|
|
180
|
+
`{@link}` and `uses:` references are captured verbatim — they are not yet
|
|
181
|
+
resolved against the symbol graph.
|
|
182
|
+
|
|
183
|
+
### Planned (not yet implemented)
|
|
184
|
+
|
|
185
|
+
The follow-on, ts-morph-based implementation will additionally:
|
|
186
|
+
|
|
187
|
+
- Resolve `{@link}` / `uses:` / `instead-of:` refs against the introspect
|
|
188
|
+
symbol graph.
|
|
189
|
+
- Emit `packages/reflect/introspect/dist/idioms.json` for downstream
|
|
190
|
+
consumers and the MCP server.
|
|
191
|
+
- Add a CI gate that fails on duplicate slugs, unresolved refs, or host
|
|
192
|
+
artifacts that do not compile.
|
|
193
|
+
- Emit warnings for idioms with no `uses:` / `instead-of:` references, or
|
|
194
|
+
whose summary is empty _and_ whose host has no JSDoc body.
|
|
195
|
+
|
|
196
|
+
## MCP surface
|
|
197
|
+
|
|
198
|
+
The `@dxos/introspect-mcp` server exposes:
|
|
199
|
+
|
|
200
|
+
```ts
|
|
201
|
+
list_idioms(filter?: { tag?: string })
|
|
202
|
+
→ { slug, summary, host: 'story' | 'test' | 'symbol', canonicalSource }[]
|
|
203
|
+
|
|
204
|
+
get_idiom(slug)
|
|
205
|
+
→ {
|
|
206
|
+
slug,
|
|
207
|
+
summary,
|
|
208
|
+
applies,
|
|
209
|
+
insteadOf?,
|
|
210
|
+
uses: SymbolRef[],
|
|
211
|
+
related: string[],
|
|
212
|
+
canonicalSource: {
|
|
213
|
+
kind: 'story' | 'test' | 'symbol',
|
|
214
|
+
file: string,
|
|
215
|
+
line: number,
|
|
216
|
+
excerpt: string,
|
|
217
|
+
storybookUrl?: string, // when host is a story
|
|
218
|
+
},
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
find_idioms_by_symbol(ref: SymbolRef)
|
|
222
|
+
→ IdiomSummary[] // idioms that `uses:` this symbol
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
`storybookUrl` is derived from the host file path + export name when the host
|
|
226
|
+
is a story; for tests and symbols it is omitted.
|
|
227
|
+
|
|
228
|
+
## Deus integration
|
|
229
|
+
|
|
230
|
+
Deus does not own idioms. The language only needs a one-line ext in `Deus.DXOS`
|
|
231
|
+
so a `.mdl` document can _reference_ an idiom by slug:
|
|
232
|
+
|
|
233
|
+
```mdl
|
|
234
|
+
ext idiom-ref
|
|
235
|
+
uri: org.dxos.mdl.idiom-ref@1.0
|
|
236
|
+
desc: Reference to an idiom by slug. Resolved via introspect.
|
|
237
|
+
fields:
|
|
238
|
+
slug: Identifier
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
A `PLUGIN.mdl` may then list
|
|
242
|
+
`uses-idioms: [org.dxos.react-ui-menu.toolbarMenu, org.dxos.app-framework.capabilityProvider]`
|
|
243
|
+
to declare which patterns the plugin builds on. The introspect linter resolves
|
|
244
|
+
the slug against the idiom catalog.
|
|
245
|
+
|
|
246
|
+
## Non-goals
|
|
247
|
+
|
|
248
|
+
- **Prose-only idioms.** Every idiom binds to a compiling artifact.
|
|
249
|
+
- **Idiom versioning.** Idioms move with their host code; semver is not
|
|
250
|
+
introduced. A breaking change to a host is a breaking change to the idiom.
|
|
251
|
+
- **Cross-repo idioms.** Idioms only describe patterns in this monorepo.
|
|
252
|
+
- **Auto-generation.** No tool will write `@idiom` tags for you. Tagging is an
|
|
253
|
+
explicit editorial act.
|
|
254
|
+
|
|
255
|
+
## Open questions
|
|
256
|
+
|
|
257
|
+
- **Idiom deprecation.** When a pattern is superseded, do we keep the old
|
|
258
|
+
`@idiom` and add `@deprecated <reason> {@link new-slug}`, or remove it
|
|
259
|
+
entirely? Leaning: keep + deprecate, so agents reading old code can still
|
|
260
|
+
find the modern replacement.
|
|
261
|
+
- **Anti-idiom artifacts.** Should we support a `@anti-idiom <slug>` tag on a
|
|
262
|
+
story or test that demonstrates the broken version side-by-side? Useful for
|
|
263
|
+
rich storybook pages, but adds a second concept. Deferred to v2.
|
|
264
|
+
- **Authoring lint rules.** Should we enforce that every public package
|
|
265
|
+
exposes at least one idiom? Probably not — discovery should be organic.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: org.dxos.plugin.<name>
|
|
3
|
+
name: <Name>Plugin
|
|
4
|
+
version: 0.1.0
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<description>
|
|
8
|
+
|
|
9
|
+
## Extensions
|
|
10
|
+
|
|
11
|
+
The following extension dialects are used in this document.
|
|
12
|
+
Each extension is defined in the Appendix or resolved via its URI.
|
|
13
|
+
|
|
14
|
+
| Term | URI |
|
|
15
|
+
|-------------|--------------------------------|
|
|
16
|
+
| `type` | `org.dxos.mdl.type@1.0` |
|
|
17
|
+
| `feat` | `org.dxos.mdl.feat@1.0` |
|
|
18
|
+
| `scenario` | `org.dxos.mdl.scenario@1.0` |
|
|
19
|
+
| `component` | `org.dxos.mdl.component@1.0` |
|
|
20
|
+
| `decision` | `org.dxos.mdl.decision@1.0` |
|
|
21
|
+
|
|
22
|
+
## Types
|
|
23
|
+
|
|
24
|
+
```mdl
|
|
25
|
+
type <name>
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Components
|
|
29
|
+
|
|
30
|
+
```mdl
|
|
31
|
+
component <name>
|
|
32
|
+
desc: <description>
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Features
|
|
36
|
+
|
|
37
|
+
```mdl
|
|
38
|
+
feat F-1: <feature>
|
|
39
|
+
|
|
40
|
+
req F-1.1: <requirement>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Acceptance
|
|
44
|
+
|
|
45
|
+
```mdl
|
|
46
|
+
scenario T-1:
|
|
47
|
+
given:
|
|
48
|
+
then:
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Changelog
|
|
52
|
+
|
|
53
|
+
Every change to this spec adds a decision, newest last. See `lang/changelog.mdl` for the attribution rules.
|
|
54
|
+
|
|
55
|
+
```mdl
|
|
56
|
+
decision D-1: <what is now true>
|
|
57
|
+
date: <YYYY-MM-DD>
|
|
58
|
+
by: user:<handle>
|
|
59
|
+
why: <the constraint that forced it>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Appendix: Extension Definitions
|
|
65
|
+
|
|
66
|
+
Extension block types used in this document are defined below using
|
|
67
|
+
the core `ext` primitive — the only construct the base language provides.
|
|
68
|
+
|
|
69
|
+
```mdl
|
|
70
|
+
ext type
|
|
71
|
+
uri: org.dxos.mdl.type@1.0
|
|
72
|
+
desc: A named data structure with typed fields and optional literals.
|
|
73
|
+
fields:
|
|
74
|
+
desc?: Prose
|
|
75
|
+
fields?: FieldMap # name[?]: TypeExpr (# inline comment)
|
|
76
|
+
literals?: UnionList # a | b | c
|
|
77
|
+
extends?: TypeRef[]
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```mdl
|
|
81
|
+
ext feat
|
|
82
|
+
uri: org.dxos.mdl.feat@1.0
|
|
83
|
+
desc: A named feature grouping one or more requirements.
|
|
84
|
+
fields:
|
|
85
|
+
desc?: Prose
|
|
86
|
+
req: RequirementList
|
|
87
|
+
nesting: self # feat blocks may contain feat blocks
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
```mdl
|
|
91
|
+
ext scenario
|
|
92
|
+
uri: org.dxos.mdl.scenario@1.0
|
|
93
|
+
desc: An acceptance scenario expressed as given / when / then steps.
|
|
94
|
+
fields:
|
|
95
|
+
given?: Step | Step[]
|
|
96
|
+
when?: Step | Step[]
|
|
97
|
+
then: Step | Step[]
|
|
98
|
+
tags?: TagList
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
```mdl
|
|
102
|
+
ext component
|
|
103
|
+
uri: org.dxos.mdl.component@1.0
|
|
104
|
+
desc: A UI component with props, internal state, slots, actions, and events.
|
|
105
|
+
fields:
|
|
106
|
+
desc?: Prose
|
|
107
|
+
props?: FieldMap # external inputs (immutable inside component)
|
|
108
|
+
state?: FieldMap # internal reactive state
|
|
109
|
+
slots?: FieldMap # named ReactNode injection points
|
|
110
|
+
actions?: ActionMap # methods the component exposes or handles
|
|
111
|
+
emits?: EventMap # events the component raises to its parent
|
|
112
|
+
layout?: CodeBlock # ASCII sketch of visual structure (non-normative)
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
`decision` is defined in [`changelog.mdl`](./changelog.mdl).
|
package/lang/app.mdl
ADDED
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: org.dxos.spec.app
|
|
3
|
+
name: DSL.App
|
|
4
|
+
version: 1.0
|
|
5
|
+
extends:
|
|
6
|
+
- org.dxos.spec.core
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
The app dialect: vocabulary for describing a Composer application's
|
|
10
|
+
**navigation and presentation structure** — app-graph nodes, deck level
|
|
11
|
+
chains, planks, companions, surface contributions, and menus. It complements
|
|
12
|
+
the standard dialect (`type`, `op`, `component`, `service`, `feat`, `test`),
|
|
13
|
+
which describes data and behavior; this dialect describes *where things
|
|
14
|
+
appear and how the user reaches them*.
|
|
15
|
+
|
|
16
|
+
Consumers list the terms they use in their Extensions table (each resolves to
|
|
17
|
+
a URI defined here), or extend this document wholesale via frontmatter
|
|
18
|
+
`extends`. See `packages/plugins/plugin-inbox/PLUGIN.mdl` for a full
|
|
19
|
+
real-world usage.
|
|
20
|
+
|
|
21
|
+
## Model
|
|
22
|
+
|
|
23
|
+
The vocabulary mirrors the runtime exactly:
|
|
24
|
+
|
|
25
|
+
- The **app-graph** is a reactive graph of nodes contributed by plugins.
|
|
26
|
+
A `node` block declares a node (or family of nodes) — its subject, its
|
|
27
|
+
children (e.g. folders), and the actions that hang off it.
|
|
28
|
+
- The **deck** renders planks; a plank is *just a graph-node id* whose content
|
|
29
|
+
resolves through an `article` Surface dispatch. A `deck` block declares a
|
|
30
|
+
**level chain** (`Mailbox > Message > Attachment`): opening at a level
|
|
31
|
+
reuses that level's plank and closes levels below.
|
|
32
|
+
- A **companion** is a child node (`~variant` linked segment) rendered as a
|
|
33
|
+
plank attached to its context plank.
|
|
34
|
+
- A **surface** contribution maps `(role, subject type)` to a component — the
|
|
35
|
+
single dispatch mechanism by which anything renders anywhere.
|
|
36
|
+
- A **menu** declares toolbar/context-menu content as references to
|
|
37
|
+
operations (`op:` blocks) and graph-node actions — never inline behavior.
|
|
38
|
+
|
|
39
|
+
### Reference forms
|
|
40
|
+
|
|
41
|
+
Cross-references follow the core rules (`[id]`, `op:Name`, `component:Name`)
|
|
42
|
+
with these additional prefixes: `node:Name`, `surface:Name`, `type:Name`.
|
|
43
|
+
Subjects reference ECHO types declared in `type` blocks (or external types
|
|
44
|
+
listed in prose).
|
|
45
|
+
|
|
46
|
+
## Extensions
|
|
47
|
+
|
|
48
|
+
| Term | URI |
|
|
49
|
+
| ----------- | ----------------------------- |
|
|
50
|
+
| `node` | `org.dxos.mdl.node@1.0` |
|
|
51
|
+
| `deck` | `org.dxos.mdl.deck@1.0` |
|
|
52
|
+
| `plank` | `org.dxos.mdl.plank@1.0` |
|
|
53
|
+
| `companion` | `org.dxos.mdl.companion@1.0` |
|
|
54
|
+
| `surface` | `org.dxos.mdl.surface@1.0` |
|
|
55
|
+
| `menu` | `org.dxos.mdl.menu@1.0` |
|
|
56
|
+
|
|
57
|
+
## Definitions
|
|
58
|
+
|
|
59
|
+
```mdl
|
|
60
|
+
ext node
|
|
61
|
+
uri: org.dxos.mdl.node@1.0
|
|
62
|
+
desc: |
|
|
63
|
+
An app-graph node contribution: a node (or per-object family of nodes)
|
|
64
|
+
the plugin adds to the graph. `source` names the parent — a well-known
|
|
65
|
+
node id (e.g. the space root) or a type whose instances the connector
|
|
66
|
+
expands. Children declared inline become child nodes (e.g. folders).
|
|
67
|
+
Actions reference `op:` blocks and surface as menu/toolbar items wherever
|
|
68
|
+
the node appears.
|
|
69
|
+
fields:
|
|
70
|
+
desc?: Prose
|
|
71
|
+
source?: NodeRef | TypeRef # parent node or the type this connector expands
|
|
72
|
+
subject?: TypeRef | Literal # the node's data (an ECHO object or a constant)
|
|
73
|
+
properties?: FieldMap # label, icon, disposition, position, ...
|
|
74
|
+
children?: NodeList # inline child node declarations (folders etc.)
|
|
75
|
+
actions?: OpRefList # operations contributed to this node
|
|
76
|
+
article?: SurfaceRef | ComponentRef # what an article surface renders for it
|
|
77
|
+
nesting: self
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```mdl
|
|
81
|
+
ext deck
|
|
82
|
+
uri: org.dxos.mdl.deck@1.0
|
|
83
|
+
desc: |
|
|
84
|
+
A declared level chain: how reading down a hierarchy maps onto planks.
|
|
85
|
+
Each level names the plank that opens at that depth; opening at a level
|
|
86
|
+
reuses that level's plank and closes deeper ones. Modifier gestures
|
|
87
|
+
(meta/ctrl) opt out and open a free plank instead.
|
|
88
|
+
fields:
|
|
89
|
+
desc?: Prose
|
|
90
|
+
chain: PlankRefList # ordered, e.g. Mailbox > Message > Attachment
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
```mdl
|
|
94
|
+
ext plank
|
|
95
|
+
uri: org.dxos.mdl.plank@1.0
|
|
96
|
+
desc: |
|
|
97
|
+
One deck plank kind: which subject it presents and through which article.
|
|
98
|
+
`parent` places it in a level chain (equivalently declared via `deck`);
|
|
99
|
+
`companions` lists the companion variants available on it.
|
|
100
|
+
fields:
|
|
101
|
+
desc?: Prose
|
|
102
|
+
subject: TypeRef # the graph node data this plank presents
|
|
103
|
+
article: SurfaceRef | ComponentRef
|
|
104
|
+
parent?: PlankRef # the level above in the chain
|
|
105
|
+
companions?: CompanionRefList
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
```mdl
|
|
109
|
+
ext companion
|
|
110
|
+
uri: org.dxos.mdl.companion@1.0
|
|
111
|
+
desc: |
|
|
112
|
+
A plank companion: a child node (`~variant` linked segment) rendered as a
|
|
113
|
+
plank attached to its context plank, sharing its attention context.
|
|
114
|
+
fields:
|
|
115
|
+
desc?: Prose
|
|
116
|
+
of: TypeRef | NodeRef # the context plank's subject
|
|
117
|
+
variant: Identifier # the `~variant` segment / tab id
|
|
118
|
+
component?: ComponentRef | SurfaceRef
|
|
119
|
+
properties?: FieldMap # label, icon, position, ...
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
```mdl
|
|
123
|
+
ext surface
|
|
124
|
+
uri: org.dxos.mdl.surface@1.0
|
|
125
|
+
desc: |
|
|
126
|
+
A Surface contribution: maps a role token plus a subject-type filter to a
|
|
127
|
+
component. This is the app's single presentation dispatch — articles,
|
|
128
|
+
sections, cards, dialogs, and companions all resolve through it.
|
|
129
|
+
|
|
130
|
+
Resolution is not most-specific-wins: every contribution whose role and
|
|
131
|
+
filter match is a candidate, and `position` orders them (`first` /
|
|
132
|
+
`last` are the sentinels; equal positions keep registration order). A
|
|
133
|
+
role-only contribution therefore competes with a subject-specific one,
|
|
134
|
+
and the subject-specific one must claim an earlier position to win.
|
|
135
|
+
fields:
|
|
136
|
+
desc?: Prose
|
|
137
|
+
role: Identifier # role token (article | section | card | dialog | ...)
|
|
138
|
+
subject?: TypeRef # type filter; omitted = role-only match
|
|
139
|
+
component: ComponentRef
|
|
140
|
+
variant?: Identifier
|
|
141
|
+
position?: number | first | last # tie-break among all matching contributions
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
```mdl
|
|
145
|
+
ext menu
|
|
146
|
+
uri: org.dxos.mdl.menu@1.0
|
|
147
|
+
desc: |
|
|
148
|
+
Toolbar / context-menu content for a node or type: ordered references to
|
|
149
|
+
operations and action groups. Menus carry no behavior of their own —
|
|
150
|
+
every item resolves to an `op:` (directly or through a graph-node
|
|
151
|
+
action).
|
|
152
|
+
fields:
|
|
153
|
+
desc?: Prose
|
|
154
|
+
of: TypeRef | NodeRef # what the menu attaches to
|
|
155
|
+
disposition?: toolbar | context | list-item
|
|
156
|
+
items: OpRefList # ordered; groups as nested lists
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## Example
|
|
160
|
+
|
|
161
|
+
A mailbox with system folders, a two-level reading chain, and a companion:
|
|
162
|
+
|
|
163
|
+
```mdl
|
|
164
|
+
node MailboxNode
|
|
165
|
+
source: type:Mailbox
|
|
166
|
+
subject: type:Mailbox
|
|
167
|
+
properties:
|
|
168
|
+
icon: ph--tray--regular
|
|
169
|
+
children:
|
|
170
|
+
- Inbox # folder: system-tag filtered view of the mailbox
|
|
171
|
+
- Sent
|
|
172
|
+
- Drafts
|
|
173
|
+
actions: [op:SyncMailbox, op:DraftEmail]
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
```mdl
|
|
177
|
+
plank MailboxPlank
|
|
178
|
+
subject: type:Mailbox
|
|
179
|
+
article: component:MailboxArticle
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
```mdl
|
|
183
|
+
plank MessagePlank
|
|
184
|
+
subject: type:Message
|
|
185
|
+
article: component:MessageArticle
|
|
186
|
+
parent: MailboxPlank
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
```mdl
|
|
190
|
+
deck MailboxDeck
|
|
191
|
+
desc: Reading down the mailbox reuses one plank per level (two levels shown; the attachment level is elided).
|
|
192
|
+
chain: MailboxPlank > MessagePlank
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
```mdl
|
|
196
|
+
companion RelatedContacts
|
|
197
|
+
of: type:Message
|
|
198
|
+
variant: contacts
|
|
199
|
+
component: component:RelatedContacts
|
|
200
|
+
```
|