@microsoft/rayfin-semantic-model-pack 0.0.0-stage → 1.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 (29) hide show
  1. package/CHANGELOG +10 -0
  2. package/LICENSE +21 -0
  3. package/README.md +65 -2
  4. package/package.json +10 -3
  5. package/skills/analytics/SKILL.md +460 -0
  6. package/skills/analytics/kit/hooks/use-semantic-model-query.spec.ts +342 -0
  7. package/skills/analytics/kit/hooks/use-semantic-model-query.ts +229 -0
  8. package/skills/analytics/kit/lib/connectors.ts +94 -0
  9. package/skills/analytics/kit/scripts/rayfin-connector.mjs +265 -0
  10. package/skills/analytics/kit/scripts/rayfin-connector.test.mjs +243 -0
  11. package/skills/analytics/kit/scripts/schema-sql-batch.test.mjs +2097 -0
  12. package/skills/analytics/kit/scripts/schema-sql-cli.test.mjs +488 -0
  13. package/skills/analytics/kit/scripts/schema-sql.mjs +2650 -0
  14. package/skills/analytics/kit/scripts/schema-sql.test.mjs +1387 -0
  15. package/skills/analytics/kit/scripts/schema.mjs +166 -0
  16. package/skills/analytics/kit/scripts/schema.test.mjs +271 -0
  17. package/skills/analytics/pack.json +49 -0
  18. package/skills/dax-authoring/SKILL.md +172 -0
  19. package/skills/dax-authoring/references/dax-core-reference.md +862 -0
  20. package/skills/dax-authoring/references/dax-query-patterns.md +396 -0
  21. package/skills/dax-authoring/references/dax-time-intelligence.md +347 -0
  22. package/skills/query-design/SKILL.md +114 -0
  23. package/skills/query-design/references/anti-patterns.md +285 -0
  24. package/skills/query-design/references/filter-strategy.md +68 -0
  25. package/skills/query-design/references/format-strings.md +62 -0
  26. package/skills/query-design/references/highlight-queries.md +122 -0
  27. package/skills/query-design/references/multi-grain-patterns.md +159 -0
  28. package/skills/schema-discovery/SKILL.md +382 -0
  29. package/skills/schema-discovery/references/discovery-queries.md +153 -0
@@ -0,0 +1,265 @@
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
+ import { spawn } from 'node:child_process';
9
+ import { createRequire } from 'node:module';
10
+ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
11
+ import { dirname, join, resolve } from 'node:path';
12
+ import { StringDecoder } from 'node:string_decoder';
13
+
14
+ function parseJson(text) {
15
+ try {
16
+ return JSON.parse(String(text).trim());
17
+ } catch {
18
+ return null;
19
+ }
20
+ }
21
+
22
+ function samePath(left, right) {
23
+ const normalize = (value) => {
24
+ const path = resolve(String(value));
25
+ return process.platform === 'win32' ? path.toLocaleLowerCase() : path;
26
+ };
27
+ return normalize(left) === normalize(right);
28
+ }
29
+
30
+ export function rayfinErrorMessage(value) {
31
+ if (value?.status === 'error') {
32
+ return String(
33
+ value.error?.message ??
34
+ value.error ??
35
+ 'Rayfin connector invocation failed.'
36
+ );
37
+ }
38
+ return null;
39
+ }
40
+
41
+ export function resolveRayfinCliEntry({
42
+ moduleUrl = import.meta.url,
43
+ createRequireImpl = createRequire,
44
+ readFileSyncImpl = readFileSync,
45
+ } = {}) {
46
+ const require = createRequireImpl(moduleUrl);
47
+ const packagePath = require.resolve('@microsoft/rayfin-cli/package.json');
48
+ const packageJson = JSON.parse(readFileSyncImpl(packagePath, 'utf8'));
49
+ const relativeEntry =
50
+ typeof packageJson.bin === 'string'
51
+ ? packageJson.bin
52
+ : packageJson.bin?.rayfin;
53
+ if (typeof relativeEntry !== 'string' || relativeEntry.length === 0) {
54
+ throw new Error(
55
+ '@microsoft/rayfin-cli does not declare a rayfin executable.'
56
+ );
57
+ }
58
+ return join(dirname(packagePath), relativeEntry);
59
+ }
60
+
61
+ function launchError(error) {
62
+ const code = error?.code ? ` (${error.code})` : '';
63
+ return (
64
+ `Could not run the Rayfin CLI${code}. ` +
65
+ 'Install the app dependencies, then retry. ' +
66
+ `Details: ${error?.message ?? String(error)}`
67
+ );
68
+ }
69
+
70
+ export function runRayfinCli({
71
+ args,
72
+ cwd = process.cwd(),
73
+ cliEntry,
74
+ spawnImpl = spawn,
75
+ environment = process.env,
76
+ }) {
77
+ return new Promise((resolveResult) => {
78
+ let commandEntry;
79
+ try {
80
+ commandEntry = cliEntry ?? resolveRayfinCliEntry();
81
+ } catch (error) {
82
+ resolveResult({ ok: false, error: launchError(error) });
83
+ return;
84
+ }
85
+
86
+ let child;
87
+ try {
88
+ child = spawnImpl(process.execPath, [commandEntry, ...args], {
89
+ cwd,
90
+ env: environment,
91
+ windowsHide: true,
92
+ shell: false,
93
+ });
94
+ } catch (error) {
95
+ resolveResult({ ok: false, error: launchError(error) });
96
+ return;
97
+ }
98
+
99
+ let stdout = '';
100
+ let stderr = '';
101
+ let settled = false;
102
+ // Pipe chunks do not respect character boundaries, so a multi-byte
103
+ // character split across two reads decodes as U+FFFD under a per-chunk
104
+ // toString(). StringDecoder holds the partial sequence back until the rest
105
+ // arrives.
106
+ const outDecoder = new StringDecoder('utf8');
107
+ const errDecoder = new StringDecoder('utf8');
108
+ const finish = (value) => {
109
+ if (settled) return;
110
+ settled = true;
111
+ resolveResult(value);
112
+ };
113
+ child.stdout?.on('data', (chunk) => {
114
+ stdout += outDecoder.write(chunk);
115
+ });
116
+ child.stderr?.on('data', (chunk) => {
117
+ stderr += errDecoder.write(chunk);
118
+ });
119
+ child.on('error', (error) => {
120
+ finish({
121
+ ok: false,
122
+ error: launchError(error),
123
+ stdout,
124
+ stderr,
125
+ });
126
+ });
127
+ child.on('close', (code, signal) => {
128
+ stdout += outDecoder.end();
129
+ stderr += errDecoder.end();
130
+ const parsed = parseJson(stdout);
131
+ if (code === 0 && signal == null) {
132
+ finish({ ok: true, value: parsed, stdout, stderr });
133
+ return;
134
+ }
135
+ const rayfinError = parsed ? rayfinErrorMessage(parsed) : null;
136
+ const message = rayfinError || stderr.trim() || stdout.trim();
137
+ const status = signal
138
+ ? `Rayfin terminated by signal ${signal}`
139
+ : `Rayfin exited with code ${code ?? 'unknown'}`;
140
+ finish({
141
+ ok: false,
142
+ error: message ? `${status}: ${message}` : `${status}.`,
143
+ stdout,
144
+ stderr,
145
+ exitCode: code,
146
+ signal,
147
+ });
148
+ });
149
+ });
150
+ }
151
+
152
+ export async function listConfiguredConnectors(options = {}) {
153
+ const result = await runRayfinCli({
154
+ ...options,
155
+ args: ['connector', 'list', '--json'],
156
+ });
157
+ if (!result.ok) {
158
+ return result;
159
+ }
160
+ if (!Array.isArray(result.value)) {
161
+ return {
162
+ ok: false,
163
+ error:
164
+ 'Could not resolve connectors because `rayfin connector list --json` ' +
165
+ 'did not return a JSON array. Run this command from the app root.',
166
+ stdout: result.stdout,
167
+ stderr: result.stderr,
168
+ };
169
+ }
170
+ return {
171
+ ok: true,
172
+ connectors: result.value,
173
+ stdout: result.stdout,
174
+ stderr: result.stderr,
175
+ };
176
+ }
177
+
178
+ export async function invokeConnector({
179
+ connector,
180
+ query,
181
+ limit,
182
+ cwd = process.cwd(),
183
+ cliEntry,
184
+ spawnImpl = spawn,
185
+ }) {
186
+ // Rayfin rejects --file paths outside the project root. Keep both the
187
+ // request and the explicit full-result file inside the app.
188
+ const temporaryDirectory = mkdtempSync(join(cwd, '.rayfin-schema-query-'));
189
+ const payloadPath = join(temporaryDirectory, 'query.json');
190
+ const outputPath = join(temporaryDirectory, 'result.json');
191
+ const payload = {
192
+ query,
193
+ ...(limit ? { resultSetRowCountLimit: Number(limit) } : {}),
194
+ };
195
+
196
+ try {
197
+ writeFileSync(payloadPath, JSON.stringify(payload), 'utf8');
198
+ const result = await runRayfinCli({
199
+ args: [
200
+ 'connector',
201
+ 'invoke',
202
+ connector,
203
+ 'executeQuery',
204
+ '--file',
205
+ payloadPath,
206
+ '--output-file',
207
+ outputPath,
208
+ '--json',
209
+ ],
210
+ cwd,
211
+ cliEntry,
212
+ spawnImpl,
213
+ });
214
+ if (!result.ok) {
215
+ return result;
216
+ }
217
+
218
+ const envelope = result.value;
219
+ if (!envelope || envelope.status !== 'ok') {
220
+ return {
221
+ ok: false,
222
+ error:
223
+ rayfinErrorMessage(envelope) ??
224
+ 'Rayfin connector invoke returned an invalid JSON envelope.',
225
+ stdout: result.stdout,
226
+ stderr: result.stderr,
227
+ };
228
+ }
229
+ if (
230
+ typeof envelope.outputFile !== 'string' ||
231
+ !samePath(envelope.outputFile, outputPath)
232
+ ) {
233
+ return {
234
+ ok: false,
235
+ error:
236
+ 'Rayfin did not write the connector result to the requested ' +
237
+ 'output file. Refusing to trust the inline preview.',
238
+ stdout: result.stdout,
239
+ stderr: result.stderr,
240
+ };
241
+ }
242
+
243
+ const output = parseJson(readFileSync(outputPath, 'utf8'));
244
+ if (output === null) {
245
+ return {
246
+ ok: false,
247
+ error: 'Rayfin wrote a connector result that was not valid JSON.',
248
+ stdout: result.stdout,
249
+ stderr: result.stderr,
250
+ };
251
+ }
252
+
253
+ return {
254
+ ok: true,
255
+ output,
256
+ outputFile: envelope.outputFile,
257
+ outputBytes: envelope.outputBytes,
258
+ outputTruncated: envelope.outputTruncated === true,
259
+ stdout: result.stdout,
260
+ stderr: result.stderr,
261
+ };
262
+ } finally {
263
+ rmSync(temporaryDirectory, { recursive: true, force: true });
264
+ }
265
+ }
@@ -0,0 +1,243 @@
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
+ import assert from 'node:assert/strict';
9
+ import { EventEmitter } from 'node:events';
10
+ import {
11
+ existsSync,
12
+ mkdtempSync,
13
+ readdirSync,
14
+ readFileSync,
15
+ rmSync,
16
+ writeFileSync,
17
+ } from 'node:fs';
18
+ import { tmpdir } from 'node:os';
19
+ import { join, relative } from 'node:path';
20
+ import test from 'node:test';
21
+
22
+ import {
23
+ invokeConnector,
24
+ listConfiguredConnectors,
25
+ rayfinErrorMessage,
26
+ resolveRayfinCliEntry,
27
+ } from './rayfin-connector.mjs';
28
+
29
+ function fakeChild(onStart) {
30
+ const child = new EventEmitter();
31
+ child.stdout = new EventEmitter();
32
+ child.stderr = new EventEmitter();
33
+ queueMicrotask(() => onStart(child));
34
+ return child;
35
+ }
36
+
37
+ test('rayfinErrorMessage extracts only error envelopes', () => {
38
+ assert.equal(
39
+ rayfinErrorMessage({
40
+ status: 'error',
41
+ error: { message: 'Access denied' },
42
+ }),
43
+ 'Access denied'
44
+ );
45
+ assert.equal(
46
+ rayfinErrorMessage({ status: 'ok', output: { ignored: true } }),
47
+ null
48
+ );
49
+ });
50
+
51
+ test('resolveRayfinCliEntry reads the extensionless package bin', () => {
52
+ const packagePath = join(
53
+ 'C:',
54
+ 'app',
55
+ 'node_modules',
56
+ '@microsoft',
57
+ 'rayfin-cli',
58
+ 'package.json'
59
+ );
60
+ const createRequireImpl = () => ({
61
+ resolve(specifier) {
62
+ assert.equal(specifier, '@microsoft/rayfin-cli/package.json');
63
+ return packagePath;
64
+ },
65
+ });
66
+ const entry = resolveRayfinCliEntry({
67
+ createRequireImpl,
68
+ readFileSyncImpl: () => JSON.stringify({ bin: { rayfin: 'scripts/main' } }),
69
+ });
70
+ assert.equal(
71
+ entry,
72
+ join(
73
+ 'C:',
74
+ 'app',
75
+ 'node_modules',
76
+ '@microsoft',
77
+ 'rayfin-cli',
78
+ 'scripts',
79
+ 'main'
80
+ )
81
+ );
82
+ });
83
+
84
+ test('connector list treats empty stdout as a resolution error', async () => {
85
+ const result = await listConfiguredConnectors({
86
+ cliEntry: 'rayfin-entry',
87
+ spawnImpl: (_command, args) =>
88
+ fakeChild((child) => {
89
+ assert.deepEqual(args.slice(1), ['connector', 'list', '--json']);
90
+ child.emit('close', 0, null);
91
+ }),
92
+ });
93
+ assert.equal(result.ok, false);
94
+ assert.match(result.error, /did not return a JSON array/i);
95
+ assert.match(result.error, /app root/i);
96
+ });
97
+
98
+ test('connector list accepts a valid project with no connectors', async () => {
99
+ const result = await listConfiguredConnectors({
100
+ cliEntry: 'rayfin-entry',
101
+ spawnImpl: () =>
102
+ fakeChild((child) => {
103
+ child.stdout.emit('data', '[]\n');
104
+ child.emit('close', 0, null);
105
+ }),
106
+ });
107
+ assert.deepEqual(result.connectors, []);
108
+ });
109
+
110
+ test('invokeConnector spawns Node directly and reads the full spilled result', async () => {
111
+ const cwd = mkdtempSync(join(tmpdir(), 'rayfin-project-'));
112
+ const fullRows = Array.from({ length: 120 }, (_, index) => [
113
+ index,
114
+ 'x'.repeat(100),
115
+ ]);
116
+ const fullOutput = {
117
+ status: 'success',
118
+ table: {
119
+ columns: [{ name: '[Id]' }, { name: '[Value]' }],
120
+ rows: fullRows,
121
+ },
122
+ };
123
+ assert.ok(
124
+ Buffer.byteLength(JSON.stringify(fullOutput), 'utf8') > 8 * 1024,
125
+ "the fixture must exceed Rayfin's default inline threshold"
126
+ );
127
+
128
+ let payloadPath;
129
+ let outputPath;
130
+ let command;
131
+ let payload;
132
+ const spawnImpl = (receivedCommand, args, options) => {
133
+ command = receivedCommand;
134
+ assert.equal(options.cwd, cwd);
135
+ assert.equal(options.shell, false);
136
+ assert.equal(args[0], 'rayfin-entry');
137
+ payloadPath = args[args.indexOf('--file') + 1];
138
+ outputPath = args[args.indexOf('--output-file') + 1];
139
+ assert.ok(!relative(cwd, payloadPath).startsWith('..'));
140
+ assert.ok(!relative(cwd, outputPath).startsWith('..'));
141
+ payload = JSON.parse(readFileSync(payloadPath, 'utf8'));
142
+
143
+ return fakeChild((child) => {
144
+ writeFileSync(outputPath, JSON.stringify(fullOutput), 'utf8');
145
+ child.stdout.emit(
146
+ 'data',
147
+ JSON.stringify({
148
+ status: 'ok',
149
+ output: {
150
+ ...fullOutput,
151
+ table: {
152
+ ...fullOutput.table,
153
+ rows: fullRows.slice(0, 20),
154
+ },
155
+ },
156
+ outputFile: outputPath,
157
+ outputBytes: Buffer.byteLength(JSON.stringify(fullOutput)),
158
+ outputTruncated: true,
159
+ previewItems: 20,
160
+ })
161
+ );
162
+ child.emit('close', 0, null);
163
+ });
164
+ };
165
+
166
+ try {
167
+ const result = await invokeConnector({
168
+ connector: 'sales',
169
+ query: 'EVALUATE INFO.VIEW.COLUMNS()',
170
+ cwd,
171
+ cliEntry: 'rayfin-entry',
172
+ spawnImpl,
173
+ });
174
+ assert.equal(command, process.execPath);
175
+ assert.equal(result.ok, true);
176
+ assert.equal(result.outputTruncated, true);
177
+ assert.equal(result.output.table.rows.length, 120);
178
+ assert.equal(
179
+ result.output.table.rows[119][0],
180
+ 119,
181
+ 'the full file must win over the 20-row stdout preview'
182
+ );
183
+ assert.deepEqual(payload, {
184
+ query: 'EVALUATE INFO.VIEW.COLUMNS()',
185
+ });
186
+ assert.equal(existsSync(payloadPath), false);
187
+ assert.equal(existsSync(outputPath), false);
188
+ } finally {
189
+ rmSync(cwd, { recursive: true, force: true });
190
+ }
191
+ });
192
+
193
+ test('invokeConnector refuses an unverified output file', async () => {
194
+ const cwd = mkdtempSync(join(tmpdir(), 'rayfin-project-'));
195
+ try {
196
+ const result = await invokeConnector({
197
+ connector: 'sales',
198
+ query: 'EVALUATE INFO.VIEW.TABLES()',
199
+ cwd,
200
+ cliEntry: 'rayfin-entry',
201
+ spawnImpl: () =>
202
+ fakeChild((child) => {
203
+ child.stdout.emit(
204
+ 'data',
205
+ JSON.stringify({
206
+ status: 'ok',
207
+ output: { preview: true },
208
+ outputFile: join(cwd, 'wrong.json'),
209
+ outputTruncated: true,
210
+ })
211
+ );
212
+ child.emit('close', 0, null);
213
+ }),
214
+ });
215
+ assert.equal(result.ok, false);
216
+ assert.match(result.error, /Refusing to trust/i);
217
+ } finally {
218
+ rmSync(cwd, { recursive: true, force: true });
219
+ }
220
+ });
221
+
222
+ test('invokeConnector cleans its directory when payload serialization fails', async () => {
223
+ const cwd = mkdtempSync(join(tmpdir(), 'rayfin-project-'));
224
+ try {
225
+ await assert.rejects(
226
+ invokeConnector({
227
+ connector: 'sales',
228
+ query: 1n,
229
+ cwd,
230
+ cliEntry: 'rayfin-entry',
231
+ }),
232
+ /BigInt/
233
+ );
234
+ assert.deepEqual(
235
+ readdirSync(cwd).filter((name) =>
236
+ name.startsWith('.rayfin-schema-query-')
237
+ ),
238
+ []
239
+ );
240
+ } finally {
241
+ rmSync(cwd, { recursive: true, force: true });
242
+ }
243
+ });