@microsoft/rayfin-semantic-model-pack 0.0.0-stage → 1.1.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/CHANGELOG ADDED
@@ -0,0 +1,14 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@microsoft/rayfin-semantic-model-pack` will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## 1.1.0 - 2026-11-05
9
+
10
+ - [Rayfin Packs] Update semantic-model and visuals packs with data-app template fixes
11
+
12
+ ## 1.0.0 - Initial release
13
+
14
+ - Add the `analytics` capability pack and the `dax-authoring`, `query-design`, and `schema-discovery` skills.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ Copyright (c) Microsoft Corporation.
2
+
3
+ MIT License
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,79 @@
1
- # Temporary Holding Version
1
+ # @microsoft/rayfin-semantic-model-pack
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Agent skills and starter code for Power BI semantic-model analytics in Rayfin apps.
4
+
5
+ ## Quick Reference
6
+
7
+ > **Package**: `@microsoft/rayfin-semantic-model-pack`
8
+ > **Purpose**: Capability pack that teaches a coding agent to query a Power BI semantic model from a Rayfin app: connect the model, discover its schema, write DAX, and shape queries for visuals.
9
+ > **Use when**: A Rayfin app template adds semantic-model analytics to an app.
10
+ > **Do NOT use when**: You need a runtime library (use `@microsoft/rayfin-connector-fabric-semanticmodel`), or charts and tables (use `@microsoft/rayfin-visuals-pack`).
11
+ > **Contents**: `skills/analytics`, `skills/dax-authoring`, `skills/query-design`, `skills/schema-discovery`, plus the `analytics` install layer: `pack.json` and `kit/`
12
+ > **Install**: `npm install @microsoft/rayfin-semantic-model-pack`
13
+
14
+ ## Contents
15
+
16
+ The package has no entry point. It has two layers:
17
+
18
+ - `skills/` is the agent content. Each folder is one skill and maps 1:1 to
19
+ `.agents/skills/<name>/` in an app. This is what both app templates share.
20
+ - `pack.json` and `kit/` at the package root are the Rayfin Universal App's
21
+ install layer for the `analytics` skill, the one named in `pack.json`.
22
+
23
+ | Skill | Contents |
24
+ | --- | --- |
25
+ | `analytics` | Reading a semantic model from the app. Installed by the root `pack.json`, whose `kit/` holds the semantic-model query hook and the schema scripts |
26
+ | `dax-authoring` | Writing and testing DAX queries |
27
+ | `query-design` | Splitting work between DAX and TypeScript, including multi-grain and cross-highlight queries |
28
+ | `schema-discovery` | Exploring a model's tables, columns, measures, and relationships |
29
+
30
+ `pack.json` tells a template how to apply the pack, such as which dependencies
31
+ to add and which kit files to copy where. Its `copy` sources are relative to
32
+ the package root. The Rayfin Universal App applies it with
33
+ `npm run pack:add -- analytics`, and the copy targets assume that template's
34
+ layout.
35
+
36
+ ## Usage
37
+
38
+ Resolve `@microsoft/rayfin-semantic-model-pack/package.json`, then copy each
39
+ `skills/<name>/` folder next to it into the app's `.agents/skills/<name>/`.
40
+
41
+ A template that applies packs with `npm run pack:add`, such as the Rayfin
42
+ Universal App, also copies `pack.json` and `kit/` into
43
+ `.agents/skills/<name>/`, where `<name>` is the `name` in `pack.json`. A
44
+ template without `pack:add` takes `skills/` and doesn't read `pack.json`.
45
+
46
+ ## Key Constraints & Gotchas
47
+
48
+ - Apply the template's `connectors` pack first. It installs the
49
+ `@/lib/rayfin-client` that the kit imports.
50
+ - The skills link to `visuals` from `@microsoft/rayfin-visuals-pack`, and to
51
+ `app-design` and `app-validation`, which the app template
52
+ provides.
53
+ - The schema scripts need Node.js 22.13 or later.
54
+ - A copier that takes only `skills/<name>/` folders leaves `analytics` without
55
+ its `pack.json`, so `npm run pack:add -- analytics` can't find it. The
56
+ Universal App's copier must also mount the root `pack.json` and `kit/`.
57
+
58
+ ## Trademarks
59
+
60
+ This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
61
+
62
+ ## Security
63
+
64
+ Microsoft takes the security of our software products and services seriously, which
65
+ includes all source code repositories in our GitHub organizations.
66
+
67
+ **Please do not report security vulnerabilities through public GitHub issues.**
68
+
69
+ For security reporting information, locations, contact information, and policies,
70
+ please review the latest guidance for Microsoft repositories at
71
+ [https://aka.ms/SECURITY.md](https://aka.ms/SECURITY.md).
72
+
73
+ ## Code of conduct
74
+
75
+ We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
76
+
77
+ We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
78
+
79
+ See full [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
@@ -0,0 +1,361 @@
1
+ //-----------------------------------------------------------------------
2
+ // <copyright company="Microsoft Corporation">
3
+ // Copyright (c) Microsoft Corporation. All rights reserved.
4
+ // Licensed under the MIT license. See LICENSE file in the project root for full license information.
5
+ // </copyright>
6
+ //-----------------------------------------------------------------------
7
+
8
+ // Runs once the pack has copied this kit into an app: the template's vitest
9
+ // `include` is `src/**/*.spec.ts`, and these imports resolve against the copied
10
+ // locations rather than the kit.
11
+ //
12
+ // Only the Rayfin client is mocked, so the connector's own `toQueryResult` runs
13
+ // for real against wire-shaped responses.
14
+
15
+ import { renderHook, act, waitFor } from '@testing-library/react';
16
+ import { describe, it, expect, vi, beforeEach } from 'vitest';
17
+
18
+ import { useSemanticModelQuery } from '@/hooks/use-semantic-model-query';
19
+
20
+ const executeQuery = vi.fn();
21
+ const connectors: Record<string, unknown> = {};
22
+
23
+ /**
24
+ * Stands in for the SDK's connectors proxy, which **throws**
25
+ * `ConnectorsError('UNKNOWN_CONNECTOR')` for an unconfigured name rather than
26
+ * returning `undefined`.
27
+ */
28
+ const connectorsProxy = new Proxy(connectors, {
29
+ get(target, key: string) {
30
+ if (!(key in target)) {
31
+ throw Object.assign(
32
+ new Error(`Connector "${key}" was accessed but has no configuration.`),
33
+ { code: 'UNKNOWN_CONNECTOR' }
34
+ );
35
+ }
36
+ return target[key];
37
+ },
38
+ });
39
+
40
+ let clientHasConnectors = true;
41
+
42
+ vi.mock('@/lib/rayfin-client', () => ({
43
+ // Async, matching this template's client: the hook has to await it rather
44
+ // than index a synchronous singleton.
45
+ getRayfinClient: () =>
46
+ Promise.resolve(clientHasConnectors ? { connectors: connectorsProxy } : {}),
47
+ }));
48
+
49
+ /** A wire-shaped success, as the FuncSet adapter returns it. */
50
+ const wireSuccess = (total: number) => ({
51
+ status: 'Succeeded',
52
+ output: {
53
+ tables: [{ rows: [{ 'Sales[Total]': total }] }],
54
+ requestId: 'r1',
55
+ },
56
+ errors: [],
57
+ });
58
+
59
+ describe('useSemanticModelQuery', () => {
60
+ beforeEach(() => {
61
+ vi.clearAllMocks();
62
+ for (const key of Object.keys(connectors)) delete connectors[key];
63
+ connectors.model = { executeQuery };
64
+ clientHasConnectors = true;
65
+ });
66
+
67
+ const render = (connection = 'model', query = 'EVALUATE ROW()') =>
68
+ renderHook(() => useSemanticModelQuery({ connection, query }));
69
+
70
+ it('starts in the loading state', () => {
71
+ executeQuery.mockReturnValue(new Promise(() => {}));
72
+
73
+ const { result } = render();
74
+
75
+ expect(result.current.isLoading).toBe(true);
76
+ expect(result.current.data).toBeUndefined();
77
+ expect(result.current.error).toBeUndefined();
78
+ });
79
+
80
+ it('normalises a successful response into column-aligned rows', async () => {
81
+ executeQuery.mockResolvedValue(wireSuccess(42));
82
+
83
+ const { result } = render();
84
+
85
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
86
+ expect(result.current.data).toEqual({
87
+ status: 'success',
88
+ table: {
89
+ columns: [{ name: 'Sales[Total]', dataType: 'unknown' }],
90
+ rows: [[42]],
91
+ },
92
+ requestId: 'r1',
93
+ });
94
+ expect(result.current.error).toBeUndefined();
95
+ });
96
+
97
+ it('publishes an already-normalised result unchanged', async () => {
98
+ // A registered runtime normalises internally, so this arrives as the union
99
+ // rather than the wire shape. A connector missing from `connectorRuntimes`
100
+ // falls through to raw JSON and does arrive in the wire shape, so this
101
+ // pins that both paths agree.
102
+ executeQuery.mockResolvedValue({
103
+ status: 'success',
104
+ table: {
105
+ columns: [{ name: 'Sales[Total]', dataType: 'unknown' }],
106
+ rows: [[7]],
107
+ },
108
+ requestId: 'r9',
109
+ });
110
+
111
+ const { result } = render();
112
+
113
+ await waitFor(() => expect(result.current.data).toBeDefined());
114
+ expect(result.current.data).toEqual({
115
+ status: 'success',
116
+ table: {
117
+ columns: [{ name: 'Sales[Total]', dataType: 'unknown' }],
118
+ rows: [[7]],
119
+ },
120
+ requestId: 'r9',
121
+ });
122
+ expect(result.current.error).toBeUndefined();
123
+ });
124
+
125
+ it('reports a failure Power BI returned on the data channel only', async () => {
126
+ executeQuery.mockResolvedValue({
127
+ status: 'Succeeded',
128
+ output: { tables: [], queryError: { message: 'bad DAX' } },
129
+ errors: [],
130
+ });
131
+
132
+ const { result } = render();
133
+
134
+ await waitFor(() => expect(result.current.data).toBeDefined());
135
+ expect(result.current.data?.status).toBe('error');
136
+ // Categorised by the connector, not invented here.
137
+ expect(
138
+ result.current.data?.status === 'error' && result.current.data.error
139
+ ).toMatchObject({ category: 'query', message: 'bad DAX' });
140
+ // `error` must stay clear, or a caller checking it first never reaches the
141
+ // structured branch and the category is unreachable.
142
+ expect(result.current.error).toBeUndefined();
143
+ });
144
+
145
+ it('surfaces the thrown error itself, not a copy of its message', async () => {
146
+ // Re-wrapping into a fresh Error keeps only the message and drops the
147
+ // status and service code — exactly what separates an auth failure from a
148
+ // malformed query.
149
+ const thrown = Object.assign(new Error('401 Unauthorized'), {
150
+ status: 401,
151
+ });
152
+ executeQuery.mockRejectedValue(thrown);
153
+
154
+ const { result } = render();
155
+
156
+ await waitFor(() => expect(result.current.error).toBeDefined());
157
+ expect(result.current.error).toBe(thrown);
158
+ expect((result.current.error as { status?: number }).status).toBe(401);
159
+ });
160
+
161
+ it('clears a stale result when a later query throws', async () => {
162
+ // Prevents rows staying on screen under an error banner. Asserting this on
163
+ // the first query would pass either way - there has to be a result to lose.
164
+ executeQuery.mockResolvedValueOnce(wireSuccess(42));
165
+ const { result, rerender } = renderHook(
166
+ ({ query }) => useSemanticModelQuery({ connection: 'model', query }),
167
+ { initialProps: { query: 'EVALUATE ROW()' } }
168
+ );
169
+ await waitFor(() => expect(result.current.data).toBeDefined());
170
+
171
+ executeQuery.mockRejectedValueOnce(new Error('401 Unauthorized'));
172
+ rerender({ query: 'EVALUATE ROW(2)' });
173
+
174
+ await waitFor(() => expect(result.current.error).toBeDefined());
175
+ // A throw is not something Power BI returned, so it must not be dressed up
176
+ // as a result either.
177
+ expect(result.current.data).toBeUndefined();
178
+ });
179
+
180
+ it('directs an unknown connector to the CLI registration flow', async () => {
181
+ // The proxy throws for a name with no config. Left untranslated that
182
+ // surfaces as a generic transport failure, sending the builder to look at
183
+ // Fabric instead of at their own registration.
184
+ delete connectors.model;
185
+
186
+ const { result } = render();
187
+
188
+ await waitFor(() => expect(result.current.error).toBeDefined());
189
+ expect(result.current.error?.message).toBe(
190
+ `No connector named "model". Check that the name matches rayfin/rayfin.yml, ` +
191
+ `or add it with \`npx rayfin connector add\`.`
192
+ );
193
+ // The original is kept so the SDK's own code is still recoverable.
194
+ expect((result.current.error?.cause as { code?: string })?.code).toBe(
195
+ 'UNKNOWN_CONNECTOR'
196
+ );
197
+ expect(executeQuery).not.toHaveBeenCalled();
198
+ });
199
+
200
+ it('gives the same CLI guidance when a connector lookup returns undefined', async () => {
201
+ connectors.model = undefined;
202
+
203
+ const { result } = render();
204
+
205
+ await waitFor(() => expect(result.current.error).toBeDefined());
206
+ expect(result.current.error?.message).toBe(
207
+ `No connector named "model". Check that the name matches rayfin/rayfin.yml, ` +
208
+ `or add it with \`npx rayfin connector add\`.`
209
+ );
210
+ expect(result.current.error?.cause).toBeUndefined();
211
+ expect(result.current.data).toBeUndefined();
212
+ expect(result.current.isLoading).toBe(false);
213
+ expect(executeQuery).not.toHaveBeenCalled();
214
+ });
215
+
216
+ it('says so when the app never wired ConnectorsRayfinClient', async () => {
217
+ // The base template builds a plain RayfinClient with no `connectors`, and no
218
+ // pack rewrites that file. Without this the first symptom is an unrelated
219
+ // TypeError deep in the hook.
220
+ clientHasConnectors = false;
221
+
222
+ const { result } = render();
223
+
224
+ await waitFor(() => expect(result.current.error).toBeDefined());
225
+ expect(result.current.error?.message).toContain('ConnectorsRayfinClient');
226
+ expect(executeQuery).not.toHaveBeenCalled();
227
+ });
228
+
229
+ it('does not let a slow earlier query overwrite a newer result', async () => {
230
+ let resolveSlow: (value: unknown) => void = () => {};
231
+ executeQuery.mockReturnValueOnce(
232
+ new Promise((resolve) => {
233
+ resolveSlow = resolve;
234
+ })
235
+ );
236
+
237
+ const { result, rerender } = renderHook(
238
+ ({ query }) => useSemanticModelQuery({ connection: 'model', query }),
239
+ { initialProps: { query: 'EVALUATE ROW()' } }
240
+ );
241
+
242
+ executeQuery.mockResolvedValueOnce(wireSuccess(2));
243
+ rerender({ query: 'EVALUATE ROW(2)' });
244
+ await waitFor(() =>
245
+ expect(result.current.data?.status === 'success').toBe(true)
246
+ );
247
+
248
+ // The first query lands last and must not publish. A microtask is not
249
+ // enough to prove that: a stale publish needs several turns plus a React
250
+ // flush to become visible, so asserting too early passes either way.
251
+ await act(async () => {
252
+ resolveSlow(wireSuccess(999));
253
+ await new Promise((resolve) => setTimeout(resolve, 20));
254
+ });
255
+
256
+ expect(
257
+ result.current.data?.status === 'success' &&
258
+ result.current.data.table.rows
259
+ ).toEqual([[2]]);
260
+ });
261
+
262
+ it('clears a previous result when it goes idle', async () => {
263
+ executeQuery.mockResolvedValue(wireSuccess(1));
264
+
265
+ const { result, rerender } = renderHook(
266
+ ({ query }) => useSemanticModelQuery({ connection: 'model', query }),
267
+ { initialProps: { query: 'EVALUATE ROW()' } }
268
+ );
269
+ await waitFor(() => expect(result.current.data).toBeDefined());
270
+
271
+ // Leaving the rows in place renders data for a query that no longer
272
+ // applies.
273
+ rerender({ query: '' });
274
+
275
+ await waitFor(() => expect(result.current.data).toBeUndefined());
276
+ expect(result.current.isLoading).toBe(false);
277
+ });
278
+
279
+ it('keeps the previous result while an explicit refetch is loading', async () => {
280
+ executeQuery.mockResolvedValueOnce(wireSuccess(1));
281
+ const { result } = render();
282
+ await waitFor(() => expect(result.current.data).toBeDefined());
283
+
284
+ let resolveNext!: (value: unknown) => void;
285
+ executeQuery.mockReturnValueOnce(
286
+ new Promise((resolve) => {
287
+ resolveNext = resolve;
288
+ })
289
+ );
290
+ let pending: Promise<void>;
291
+ act(() => {
292
+ pending = result.current.refetch();
293
+ });
294
+ expect(result.current.isLoading).toBe(true);
295
+ expect(
296
+ result.current.data?.status === 'success' &&
297
+ result.current.data.table.rows
298
+ ).toEqual([[1]]);
299
+
300
+ await act(async () => {
301
+ resolveNext(wireSuccess(2));
302
+ await pending;
303
+ });
304
+ expect(result.current.isLoading).toBe(false);
305
+ expect(
306
+ result.current.data?.status === 'success' &&
307
+ result.current.data.table.rows
308
+ ).toEqual([[2]]);
309
+ });
310
+
311
+ it('does not publish an in-flight result after the query goes idle', async () => {
312
+ let resolveQuery!: (value: unknown) => void;
313
+ executeQuery.mockReturnValueOnce(
314
+ new Promise((resolve) => {
315
+ resolveQuery = resolve;
316
+ })
317
+ );
318
+ const { result, rerender } = renderHook(
319
+ ({ query }) => useSemanticModelQuery({ connection: 'model', query }),
320
+ { initialProps: { query: 'EVALUATE ROW()' } }
321
+ );
322
+ rerender({ query: '' });
323
+ await act(async () => {
324
+ resolveQuery(wireSuccess(9));
325
+ await new Promise((resolve) => setTimeout(resolve, 20));
326
+ });
327
+ expect(result.current.data).toBeUndefined();
328
+ expect(result.current.error).toBeUndefined();
329
+ expect(result.current.isLoading).toBe(false);
330
+ });
331
+
332
+ it('starts loading again when revisiting a previously completed query', async () => {
333
+ executeQuery.mockResolvedValueOnce(wireSuccess(1));
334
+ const { result, rerender } = renderHook(
335
+ ({ query }) => useSemanticModelQuery({ connection: 'model', query }),
336
+ { initialProps: { query: 'EVALUATE ROW(1)' } }
337
+ );
338
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
339
+
340
+ executeQuery.mockReturnValueOnce(new Promise(() => {}));
341
+ rerender({ query: 'EVALUATE ROW(2)' });
342
+ expect(result.current.isLoading).toBe(true);
343
+
344
+ let resolveRevisited!: (value: unknown) => void;
345
+ executeQuery.mockReturnValueOnce(
346
+ new Promise((resolve) => {
347
+ resolveRevisited = resolve;
348
+ })
349
+ );
350
+ rerender({ query: 'EVALUATE ROW(1)' });
351
+ expect(result.current.isLoading).toBe(true);
352
+ await act(async () => {
353
+ resolveRevisited(wireSuccess(3));
354
+ });
355
+ expect(result.current.isLoading).toBe(false);
356
+ expect(
357
+ result.current.data?.status === 'success' &&
358
+ result.current.data.table.rows
359
+ ).toEqual([[3]]);
360
+ });
361
+ });