@malloy-publisher/server 0.0.231 → 0.0.233
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/README.docker.md +4 -0
- package/dist/app/api-doc.yaml +135 -13
- package/dist/app/assets/{EnvironmentPage-wa_EPkwK.js → EnvironmentPage-DutP7T8h.js} +1 -1
- package/dist/app/assets/{HomePage-jnCrupQp.js → HomePage-BcxDrBfl.js} +1 -1
- package/dist/app/assets/{LightMode-DYbwNULZ.js → LightMode-BJukGxgz.js} +1 -1
- package/dist/app/assets/{MainPage-CuJLrPNI.js → MainPage-DXbwlMeF.js} +2 -2
- package/dist/app/assets/{MaterializationsPage-D_67x2ee.js → MaterializationsPage-BBQksmTU.js} +1 -1
- package/dist/app/assets/{ModelPage-D5JtAWqR.js → ModelPage-C6tK51uU.js} +1 -1
- package/dist/app/assets/{PackagePage-BRwtqUSG.js → PackagePage-Bo3cwwZE.js} +1 -1
- package/dist/app/assets/{RouteError-CBNNrnSD.js → RouteError-BufkcAKE.js} +1 -1
- package/dist/app/assets/{ThemeEditorPage-CTCeBneA.js → ThemeEditorPage-DICvvKpa.js} +1 -1
- package/dist/app/assets/{WorkbookPage-SN6f1RBm.js → WorkbookPage-Dkwt75Nj.js} +1 -1
- package/dist/app/assets/{core-Dp3q5Ieu.es-CD5FvM2s.js → core-C0nunIQT.es-DlMLKZBK.js} +1 -1
- package/dist/app/assets/{index-DU4r7GdU.js → index-BabP-V-S.js} +346 -321
- package/dist/app/assets/{index-BLCx1EdC.js → index-BusxL5Pt.js} +1 -1
- package/dist/app/assets/{index-C_tJstcx.js → index-CmEVVe-8.js} +15 -15
- package/dist/app/assets/{index-CfmBVB6M.js → index-Cs4WVm2z.js} +1 -1
- package/dist/app/assets/{index-B3Nn8Vm2.js → index-qnhU9CGo.js} +266 -265
- package/dist/app/index.html +1 -1
- package/dist/instrumentation.mjs +2 -0
- package/dist/package_load_worker.mjs +11 -1
- package/dist/server.mjs +22627 -1260
- package/package.json +12 -12
- package/scripts/bake-duckdb-extensions.js +4 -1
- package/src/config.spec.ts +39 -0
- package/src/config.ts +135 -0
- package/src/controller/materialization.controller.spec.ts +62 -0
- package/src/controller/materialization.controller.ts +15 -0
- package/src/controller/package.controller.spec.ts +6 -0
- package/src/controller/package.controller.ts +7 -2
- package/src/controller/query.controller.ts +26 -21
- package/src/errors.ts +19 -0
- package/src/json_utils.spec.ts +51 -0
- package/src/json_utils.ts +33 -0
- package/src/logger.spec.ts +18 -1
- package/src/logger.ts +3 -1
- package/src/materialization_metrics.spec.ts +89 -4
- package/src/materialization_metrics.ts +155 -5
- package/src/mcp/query_envelope.spec.ts +229 -0
- package/src/mcp/query_envelope.ts +230 -0
- package/src/mcp/server.protocol.spec.ts +128 -16
- package/src/mcp/skills/build_skills_bundle.ts +94 -4
- package/src/mcp/skills/skills_bundle.json +1 -1
- package/src/mcp/skills/skills_bundle.spec.ts +113 -4
- package/src/mcp/tool_response.spec.ts +108 -0
- package/src/mcp/tool_response.ts +138 -0
- package/src/mcp/tools/compile_tool.spec.ts +112 -4
- package/src/mcp/tools/compile_tool.ts +61 -30
- package/src/mcp/tools/docs_search_tool.ts +6 -16
- package/src/mcp/tools/embedding_index.spec.ts +1236 -0
- package/src/mcp/tools/embedding_index.ts +808 -0
- package/src/mcp/tools/execute_query_tool.spec.ts +23 -3
- package/src/mcp/tools/execute_query_tool.ts +90 -151
- package/src/mcp/tools/get_context_eval.ts +194 -45
- package/src/mcp/tools/get_context_tool.spec.ts +358 -5
- package/src/mcp/tools/get_context_tool.ts +202 -56
- package/src/mcp/tools/reload_package_tool.ts +3 -29
- package/src/pg_helpers.spec.ts +201 -0
- package/src/pg_helpers.ts +44 -5
- package/src/server.ts +24 -0
- package/src/service/build_plan.spec.ts +128 -2
- package/src/service/build_plan.ts +239 -17
- package/src/service/compile_fragment_techniques.spec.ts +156 -0
- package/src/service/connection.spec.ts +371 -1
- package/src/service/connection.ts +339 -20
- package/src/service/connection_config.spec.ts +108 -0
- package/src/service/connection_config.ts +47 -8
- package/src/service/connection_federation.spec.ts +184 -0
- package/src/service/duckdb_instance_isolation.spec.ts +137 -0
- package/src/service/embedding_provider.spec.ts +329 -0
- package/src/service/embedding_provider.ts +236 -0
- package/src/service/environment.ts +274 -12
- package/src/service/environment_store.spec.ts +678 -3
- package/src/service/environment_store.ts +449 -33
- package/src/service/environment_store_clone.spec.ts +350 -0
- package/src/service/manifest_loader.spec.ts +68 -13
- package/src/service/manifest_loader.ts +67 -19
- package/src/service/materialization_build_session.spec.ts +435 -0
- package/src/service/materialization_build_session.ts +681 -0
- package/src/service/materialization_eligibility.spec.ts +158 -0
- package/src/service/materialization_eligibility.ts +305 -0
- package/src/service/materialization_serve_transform.spec.ts +1003 -0
- package/src/service/materialization_serve_transform.ts +779 -0
- package/src/service/materialization_service.spec.ts +774 -7
- package/src/service/materialization_service.ts +1107 -42
- package/src/service/materialization_test_fixtures.ts +7 -0
- package/src/service/model.spec.ts +207 -0
- package/src/service/model.ts +569 -59
- package/src/service/model_limits.spec.ts +28 -0
- package/src/service/model_limits.ts +21 -0
- package/src/service/model_storage_serve.spec.ts +193 -0
- package/src/service/model_storage_serve_joins.spec.ts +193 -0
- package/src/service/package.spec.ts +196 -0
- package/src/service/package.ts +385 -17
- package/src/service/persistence_policy.spec.ts +109 -0
- package/src/storage/duckdb/schema.ts +37 -0
- package/tests/fixtures/xlsx/database.xlsx +0 -0
- package/tests/integration/first_boot/readiness_line.integration.spec.ts +177 -0
- package/tests/integration/materialization/manifest_binding.integration.spec.ts +104 -0
- package/tests/integration/mcp/mcp_execute_query_tool.integration.spec.ts +37 -12
- package/tests/integration/mcp/mcp_get_context_semantic.integration.spec.ts +235 -0
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
import { describe, expect, it } from "bun:test";
|
|
2
|
+
import * as fs from "node:fs";
|
|
2
3
|
import * as path from "node:path";
|
|
3
|
-
import {
|
|
4
|
+
import {
|
|
5
|
+
buildSkills,
|
|
6
|
+
isCredible,
|
|
7
|
+
type SkillEntry,
|
|
8
|
+
} from "./build_skills_bundle";
|
|
4
9
|
import bundle from "./skills_bundle.json";
|
|
5
10
|
|
|
6
11
|
const skills = (
|
|
@@ -54,9 +59,113 @@ describe("skills_bundle.json (generated dual-channel asset)", () => {
|
|
|
54
59
|
expect(new Set(names).size).toBe(names.length);
|
|
55
60
|
});
|
|
56
61
|
|
|
62
|
+
/**
|
|
63
|
+
* A skill's reference/ files are its on-demand detail, and this channel is
|
|
64
|
+
* the only way a host without the skills on disk can reach them. Before they
|
|
65
|
+
* were bundled, malloy-review told an agent to load rubrics that, over MCP,
|
|
66
|
+
* did not exist.
|
|
67
|
+
*/
|
|
68
|
+
describe("reference files", () => {
|
|
69
|
+
const isReference = (s: SkillEntry) => s.name.includes("/");
|
|
70
|
+
const referenceEntries = skills.filter(isReference);
|
|
71
|
+
|
|
72
|
+
it("bundles every reference/*.md in the tree", () => {
|
|
73
|
+
// Mirror the builder's own exclusion. A stray credible-* skill with a
|
|
74
|
+
// reference/ dir is never bundled, so walking without this filter
|
|
75
|
+
// fails on a correct bundle.
|
|
76
|
+
const onDisk = fs
|
|
77
|
+
.readdirSync(sourceDir, { withFileTypes: true })
|
|
78
|
+
.filter((d) => d.isDirectory() && !isCredible(d.name))
|
|
79
|
+
.flatMap((d) => {
|
|
80
|
+
const dir = path.join(sourceDir, d.name, "reference");
|
|
81
|
+
return fs.existsSync(dir)
|
|
82
|
+
? fs
|
|
83
|
+
.readdirSync(dir)
|
|
84
|
+
.filter((f) => f.endsWith(".md"))
|
|
85
|
+
.map((f) => `${d.name}/${path.basename(f, ".md")}`)
|
|
86
|
+
: [];
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
expect(onDisk.length).toBeGreaterThan(0);
|
|
90
|
+
expect(referenceEntries.map((s) => s.name).sort()).toEqual(
|
|
91
|
+
onDisk.sort(),
|
|
92
|
+
);
|
|
93
|
+
});
|
|
94
|
+
|
|
95
|
+
it("names each one under its parent skill", () => {
|
|
96
|
+
const skillNames = new Set(
|
|
97
|
+
skills.filter((s) => !isReference(s)).map((s) => s.name),
|
|
98
|
+
);
|
|
99
|
+
for (const entry of referenceEntries) {
|
|
100
|
+
expect(skillNames.has(entry.name.split("/")[0])).toBe(true);
|
|
101
|
+
}
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
it("gives each one a description drawn from its heading", () => {
|
|
105
|
+
// Reference files carry no frontmatter, so a listing would otherwise
|
|
106
|
+
// show them nameless. Every file in the tree has an H1 to use.
|
|
107
|
+
//
|
|
108
|
+
// Assert against the no-heading fallback rather than a length floor:
|
|
109
|
+
// the fallback is itself long enough to clear any such floor, so a
|
|
110
|
+
// length check alone stays green even if heading extraction breaks
|
|
111
|
+
// entirely and all of a skill's entries collapse to one string.
|
|
112
|
+
for (const entry of referenceEntries) {
|
|
113
|
+
const parent = entry.name.split("/")[0];
|
|
114
|
+
expect(entry.description).toContain("Reference detail for");
|
|
115
|
+
expect(entry.description).not.toBe(
|
|
116
|
+
`Reference detail for the ${parent} skill.`,
|
|
117
|
+
);
|
|
118
|
+
}
|
|
119
|
+
});
|
|
120
|
+
|
|
121
|
+
it("tells the parent skill where its reference files went", () => {
|
|
122
|
+
// The parent body points at them by relative path, which resolves for
|
|
123
|
+
// a host reading files off disk and not for one given this as a prompt.
|
|
124
|
+
const parents = new Set(
|
|
125
|
+
referenceEntries.map((s) => s.name.split("/")[0]),
|
|
126
|
+
);
|
|
127
|
+
for (const name of parents) {
|
|
128
|
+
const parent = skills.find((s) => s.name === name);
|
|
129
|
+
expect(parent?.body).toContain("Reference files over MCP");
|
|
130
|
+
expect(parent?.body).toContain(`get the prompt named \`${name}/`);
|
|
131
|
+
}
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
it("leaves skills without a reference/ directory untouched", () => {
|
|
135
|
+
const plain = skills.find((s) => s.name === "malloy-getting-started");
|
|
136
|
+
expect(plain?.body).not.toContain("Reference files over MCP");
|
|
137
|
+
});
|
|
138
|
+
});
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* Pre-existing drift, bounded rather than exempted. Every SKILL.md honours
|
|
142
|
+
* the house style; these three reference files never did, because nothing
|
|
143
|
+
* checked them until they entered the bundle. Fixing 23 prose em-dashes in
|
|
144
|
+
* three SHARED skills is an upstream-first change of its own, not something
|
|
145
|
+
* to bundle into the build-time asset that surfaced it.
|
|
146
|
+
*
|
|
147
|
+
* Listed by name so a NEW violation still fails: shrink this list as the
|
|
148
|
+
* files are fixed, and delete it when it is empty.
|
|
149
|
+
*/
|
|
150
|
+
const EM_DASH_DRIFT = new Set([
|
|
151
|
+
"malloy-html-data-apps/lazy-load",
|
|
152
|
+
"malloy-html-data-apps/verification-harness",
|
|
153
|
+
"malloy-lookml-review/build-derived-tables",
|
|
154
|
+
]);
|
|
155
|
+
|
|
57
156
|
it("carries no em-dashes (house style)", () => {
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
157
|
+
const offenders = skills
|
|
158
|
+
.filter((s) => !EM_DASH_DRIFT.has(s.name) && s.body.includes("—"))
|
|
159
|
+
.map((s) => s.name);
|
|
160
|
+
expect(offenders).toEqual([]);
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
it("the em-dash allowlist names only entries that still need fixing", () => {
|
|
164
|
+
// Stops the list outliving the drift: an entry that has been cleaned up,
|
|
165
|
+
// or renamed away, has to leave the list.
|
|
166
|
+
const stillDrifting = skills
|
|
167
|
+
.filter((s) => EM_DASH_DRIFT.has(s.name) && s.body.includes("—"))
|
|
168
|
+
.map((s) => s.name);
|
|
169
|
+
expect([...EM_DASH_DRIFT].sort()).toEqual(stillDrifting.sort());
|
|
61
170
|
});
|
|
62
171
|
});
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
import { describe, expect, it } from "bun:test";
|
|
2
|
+
import { formatErrorText, jsonResource, jsonToolError } from "./tool_response";
|
|
3
|
+
|
|
4
|
+
// Pins the wire shape every malloy_* tool returns. Two properties here are
|
|
5
|
+
// regressions waiting to happen, so they are asserted explicitly rather than
|
|
6
|
+
// left to the tools' own specs:
|
|
7
|
+
//
|
|
8
|
+
// - the resource carries `mimeType`, not `type`. `type` is not in the MCP
|
|
9
|
+
// ResourceContents schema; it was accepted by .passthrough() and ignored.
|
|
10
|
+
// - an error result carries a text block. The structured payload alone is
|
|
11
|
+
// invisible to a client that renders only text for isError results.
|
|
12
|
+
|
|
13
|
+
describe("jsonResource", () => {
|
|
14
|
+
it("puts the resource block first and types it with mimeType", () => {
|
|
15
|
+
const r = jsonResource("malloy:/x", { a: 1 });
|
|
16
|
+
|
|
17
|
+
expect(r.isError).toBe(false);
|
|
18
|
+
expect(r.content).toHaveLength(1);
|
|
19
|
+
expect(r.content[0].type).toBe("resource");
|
|
20
|
+
|
|
21
|
+
const resource = (r.content[0] as { resource: Record<string, unknown> })
|
|
22
|
+
.resource;
|
|
23
|
+
expect(resource.mimeType).toBe("application/json");
|
|
24
|
+
expect(resource.uri).toBe("malloy:/x");
|
|
25
|
+
// The pre-fix spelling must not come back.
|
|
26
|
+
expect(resource.type).toBeUndefined();
|
|
27
|
+
expect(JSON.parse(resource.text as string)).toEqual({ a: 1 });
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
it("appends an optional text block after the resource", () => {
|
|
31
|
+
const r = jsonResource("malloy:/x", { a: 1 }, { text: "heads up" });
|
|
32
|
+
|
|
33
|
+
expect(r.content).toHaveLength(2);
|
|
34
|
+
expect(r.content[0].type).toBe("resource");
|
|
35
|
+
expect(r.content[1]).toEqual({ type: "text", text: "heads up" });
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
it("omits the text block when no text is supplied", () => {
|
|
39
|
+
expect(jsonResource("malloy:/x", {}).content).toHaveLength(1);
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
it("honours the space option without changing the parsed payload", () => {
|
|
43
|
+
const compact = jsonResource("malloy:/x", { a: 1 });
|
|
44
|
+
const pretty = jsonResource("malloy:/x", { a: 1 }, { space: 2 });
|
|
45
|
+
|
|
46
|
+
const text = (r: typeof compact) =>
|
|
47
|
+
(r.content[0] as { resource: { text: string } }).resource.text;
|
|
48
|
+
|
|
49
|
+
expect(text(pretty)).toContain("\n");
|
|
50
|
+
expect(text(compact)).not.toContain("\n");
|
|
51
|
+
expect(JSON.parse(text(pretty))).toEqual(JSON.parse(text(compact)));
|
|
52
|
+
});
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
describe("formatErrorText", () => {
|
|
56
|
+
it("renders the message and every suggestion", () => {
|
|
57
|
+
const text = formatErrorText({
|
|
58
|
+
message: "Resource not found: env/pkg",
|
|
59
|
+
suggestions: ["Check the spelling.", "Call malloy_getContext."],
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
expect(text).toContain("Resource not found: env/pkg");
|
|
63
|
+
expect(text).toContain("- Check the spelling.");
|
|
64
|
+
expect(text).toContain("- Call malloy_getContext.");
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
it("returns the bare message when there are no suggestions", () => {
|
|
68
|
+
expect(formatErrorText({ message: "boom", suggestions: [] })).toBe(
|
|
69
|
+
"boom",
|
|
70
|
+
);
|
|
71
|
+
});
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
describe("jsonToolError", () => {
|
|
75
|
+
const details = {
|
|
76
|
+
message: "Cannot redefine 'overview'",
|
|
77
|
+
suggestions: ["Rename the view."],
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
it("sets isError and carries the message in BOTH blocks", () => {
|
|
81
|
+
const r = jsonToolError("error://compile", details);
|
|
82
|
+
|
|
83
|
+
expect(r.isError).toBe(true);
|
|
84
|
+
expect(r.content).toHaveLength(2);
|
|
85
|
+
|
|
86
|
+
const payload = JSON.parse(
|
|
87
|
+
(r.content[0] as { resource: { text: string } }).resource.text,
|
|
88
|
+
);
|
|
89
|
+
expect(payload.error).toBe("Cannot redefine 'overview'");
|
|
90
|
+
expect(payload.suggestions).toEqual(["Rename the view."]);
|
|
91
|
+
|
|
92
|
+
// The whole point of the change: a text-only client still sees it.
|
|
93
|
+
const textBlock = r.content[1] as { type: string; text: string };
|
|
94
|
+
expect(textBlock.type).toBe("text");
|
|
95
|
+
expect(textBlock.text).toContain("Cannot redefine 'overview'");
|
|
96
|
+
expect(textBlock.text).toContain("- Rename the view.");
|
|
97
|
+
});
|
|
98
|
+
|
|
99
|
+
it("merges extraPayload so getContext keeps its results key", () => {
|
|
100
|
+
const r = jsonToolError("error://ctx", details, { results: [] });
|
|
101
|
+
|
|
102
|
+
const payload = JSON.parse(
|
|
103
|
+
(r.content[0] as { resource: { text: string } }).resource.text,
|
|
104
|
+
);
|
|
105
|
+
expect(payload.results).toEqual([]);
|
|
106
|
+
expect(payload.error).toBe("Cannot redefine 'overview'");
|
|
107
|
+
});
|
|
108
|
+
});
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
import type { ErrorDetails } from "./error_messages";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Shared construction of the MCP content blocks every malloy_* tool returns.
|
|
5
|
+
*
|
|
6
|
+
* Two things here are load-bearing and were previously wrong at every call site:
|
|
7
|
+
*
|
|
8
|
+
* 1. The resource block carries `mimeType`, not `type`. The MCP
|
|
9
|
+
* ResourceContents schema is `z.object({uri, mimeType?, _meta?}).passthrough()`,
|
|
10
|
+
* so a `type: "application/json"` field was accepted by passthrough and then
|
|
11
|
+
* ignored by every client, leaving the payload untyped on the wire.
|
|
12
|
+
*
|
|
13
|
+
* 2. An error result also emits a plain text block. A client that renders only
|
|
14
|
+
* text blocks when `isError` is set sees nothing at all in an embedded
|
|
15
|
+
* resource, and reports a bare "Unknown error" while the server's real
|
|
16
|
+
* message and suggestions sit unread in the resource. The text block is what
|
|
17
|
+
* makes a diagnostic legible; the resource block is what keeps it parseable.
|
|
18
|
+
*
|
|
19
|
+
* Ordering matters: the resource block stays at index 0 so callers (and specs)
|
|
20
|
+
* can keep reading `content[0].resource.text` for the structured payload.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
const JSON_MIME_TYPE = "application/json";
|
|
24
|
+
|
|
25
|
+
// The index signatures mirror the MCP SDK's CallToolResult types, which declare
|
|
26
|
+
// `[x: string]: unknown` on the result and on every content block. Without them
|
|
27
|
+
// these are not assignable to the SDK's tool-callback return type.
|
|
28
|
+
type ResourceBlock = {
|
|
29
|
+
[x: string]: unknown;
|
|
30
|
+
type: "resource";
|
|
31
|
+
resource: {
|
|
32
|
+
[x: string]: unknown;
|
|
33
|
+
uri: string;
|
|
34
|
+
mimeType: string;
|
|
35
|
+
text: string;
|
|
36
|
+
};
|
|
37
|
+
};
|
|
38
|
+
|
|
39
|
+
type TextBlock = { [x: string]: unknown; type: "text"; text: string };
|
|
40
|
+
|
|
41
|
+
export type ToolContent = ResourceBlock | TextBlock;
|
|
42
|
+
|
|
43
|
+
export interface ToolResult {
|
|
44
|
+
[x: string]: unknown;
|
|
45
|
+
isError: boolean;
|
|
46
|
+
content: ToolContent[];
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function resourceBlock(
|
|
50
|
+
uri: string,
|
|
51
|
+
payload: unknown,
|
|
52
|
+
space?: number,
|
|
53
|
+
replacer?: (key: string, value: unknown) => unknown,
|
|
54
|
+
): ResourceBlock {
|
|
55
|
+
return {
|
|
56
|
+
type: "resource" as const,
|
|
57
|
+
resource: {
|
|
58
|
+
uri,
|
|
59
|
+
mimeType: JSON_MIME_TYPE,
|
|
60
|
+
text: JSON.stringify(payload, replacer, space),
|
|
61
|
+
},
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Renders ErrorDetails as the prose a client will actually show the agent.
|
|
67
|
+
*
|
|
68
|
+
* The suggestions are included, not just the message: they carry the part that
|
|
69
|
+
* makes an error actionable (which source was denied, which view to look for,
|
|
70
|
+
* that a reload is needed), and a client that cannot read the resource block
|
|
71
|
+
* has no other way to reach them. They are a short, bounded list by
|
|
72
|
+
* construction in error_messages.ts.
|
|
73
|
+
*
|
|
74
|
+
* Exported so a spec can pin the rendering rather than merely its presence.
|
|
75
|
+
*/
|
|
76
|
+
export function formatErrorText(details: ErrorDetails): string {
|
|
77
|
+
if (details.suggestions.length === 0) {
|
|
78
|
+
return details.message;
|
|
79
|
+
}
|
|
80
|
+
const suggestions = details.suggestions.map((s) => `- ${s}`).join("\n");
|
|
81
|
+
return `${details.message}\n\nSuggestions:\n${suggestions}`;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Wraps a JSON payload in the resource-content shape, optionally adding a text
|
|
86
|
+
* block alongside it.
|
|
87
|
+
*
|
|
88
|
+
* `text` is deliberately opt-in rather than automatic on success: a query result
|
|
89
|
+
* is already size-capped (assertWithinModelResponseLimits), and duplicating it
|
|
90
|
+
* as prose would double the payload for no gain. Success paths that have
|
|
91
|
+
* something short and useful to say (render-tag warnings) pass it explicitly.
|
|
92
|
+
*
|
|
93
|
+
* @param space JSON.stringify indentation. Left undefined (compact) except for
|
|
94
|
+
* query results, which have always been pretty-printed for readability.
|
|
95
|
+
*/
|
|
96
|
+
export function jsonResource(
|
|
97
|
+
uri: string,
|
|
98
|
+
payload: unknown,
|
|
99
|
+
options?: {
|
|
100
|
+
isError?: boolean;
|
|
101
|
+
text?: string;
|
|
102
|
+
space?: number;
|
|
103
|
+
/** Needed when the payload can carry BigInt: see json_utils.bigIntReplacer. */
|
|
104
|
+
replacer?: (key: string, value: unknown) => unknown;
|
|
105
|
+
},
|
|
106
|
+
): ToolResult {
|
|
107
|
+
const content: ToolContent[] = [
|
|
108
|
+
resourceBlock(uri, payload, options?.space, options?.replacer),
|
|
109
|
+
];
|
|
110
|
+
if (options?.text !== undefined) {
|
|
111
|
+
content.push({ type: "text" as const, text: options.text });
|
|
112
|
+
}
|
|
113
|
+
return { isError: options?.isError ?? false, content };
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Builds the standard error result: the {error, suggestions} JSON a parsing
|
|
118
|
+
* client wants, plus the same information as text so every client can read it.
|
|
119
|
+
*
|
|
120
|
+
* @param extraPayload Merged into the JSON payload. malloy_getContext uses it
|
|
121
|
+
* to keep its `results: []` contract on the error path, which its callers
|
|
122
|
+
* (and specs) rely on to treat every tier's response shape uniformly.
|
|
123
|
+
*/
|
|
124
|
+
export function jsonToolError(
|
|
125
|
+
uri: string,
|
|
126
|
+
details: ErrorDetails,
|
|
127
|
+
extraPayload?: Record<string, unknown>,
|
|
128
|
+
): ToolResult {
|
|
129
|
+
return jsonResource(
|
|
130
|
+
uri,
|
|
131
|
+
{
|
|
132
|
+
error: details.message,
|
|
133
|
+
suggestions: details.suggestions,
|
|
134
|
+
...extraPayload,
|
|
135
|
+
},
|
|
136
|
+
{ isError: true, text: formatErrorText(details) },
|
|
137
|
+
);
|
|
138
|
+
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { describe, expect, it } from "bun:test";
|
|
2
|
-
import { registerCompileTool } from "./compile_tool";
|
|
2
|
+
import { formatDiagnosticsText, registerCompileTool } from "./compile_tool";
|
|
3
3
|
import type { EnvironmentStore } from "../../service/environment_store";
|
|
4
4
|
import { PackageNotFoundError, ServiceUnavailableError } from "../../errors";
|
|
5
5
|
|
|
@@ -7,9 +7,15 @@ import { PackageNotFoundError, ServiceUnavailableError } from "../../errors";
|
|
|
7
7
|
// be exercised against a mocked EnvironmentStore. The tool builds a
|
|
8
8
|
// CompileController internally, which calls environment.compileSource, so the
|
|
9
9
|
// mock only needs getEnvironment -> { compileSource }.
|
|
10
|
+
type Content = Array<{
|
|
11
|
+
type?: string;
|
|
12
|
+
text?: string;
|
|
13
|
+
resource?: { text: string };
|
|
14
|
+
}>;
|
|
15
|
+
|
|
10
16
|
type Handler = (params: Record<string, unknown>) => Promise<{
|
|
11
17
|
isError?: boolean;
|
|
12
|
-
content:
|
|
18
|
+
content: Content;
|
|
13
19
|
}>;
|
|
14
20
|
|
|
15
21
|
function captureHandler(store: Partial<EnvironmentStore>): Handler {
|
|
@@ -24,8 +30,12 @@ function captureHandler(store: Partial<EnvironmentStore>): Handler {
|
|
|
24
30
|
return handler;
|
|
25
31
|
}
|
|
26
32
|
|
|
27
|
-
function parse(result: { content:
|
|
28
|
-
return JSON.parse(result.content[0].resource
|
|
33
|
+
function parse(result: { content: Content }) {
|
|
34
|
+
return JSON.parse(result.content[0].resource!.text);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function textBlock(result: { content: Content }) {
|
|
38
|
+
return result.content.find((b) => b.type === "text")?.text;
|
|
29
39
|
}
|
|
30
40
|
|
|
31
41
|
function storeReturning(
|
|
@@ -89,6 +99,40 @@ describe("malloy_compile tool", () => {
|
|
|
89
99
|
]);
|
|
90
100
|
});
|
|
91
101
|
|
|
102
|
+
it("also states the diagnostics in a text block", async () => {
|
|
103
|
+
// The regression pin for the isError path that matters most: a bad Malloy
|
|
104
|
+
// snippet. A client that renders only text blocks on isError sees nothing
|
|
105
|
+
// without this, and reports a bare "Unknown error" while the diagnostics
|
|
106
|
+
// sit unread in the resource block.
|
|
107
|
+
const handler = captureHandler(
|
|
108
|
+
storeReturning([
|
|
109
|
+
{
|
|
110
|
+
severity: "error",
|
|
111
|
+
message: "'nope' is not defined",
|
|
112
|
+
code: "field-not-found",
|
|
113
|
+
at: {
|
|
114
|
+
range: {
|
|
115
|
+
start: { line: 2, character: 3 },
|
|
116
|
+
end: { line: 2, character: 7 },
|
|
117
|
+
},
|
|
118
|
+
},
|
|
119
|
+
},
|
|
120
|
+
]),
|
|
121
|
+
);
|
|
122
|
+
const result = await handler(args);
|
|
123
|
+
expect(textBlock(result)).toBe(
|
|
124
|
+
"Compile failed with 1 error (positions are 0-based):\n\n" +
|
|
125
|
+
"- 'nope' is not defined (line 2, character 3) [field-not-found]",
|
|
126
|
+
);
|
|
127
|
+
});
|
|
128
|
+
|
|
129
|
+
it("adds no text block to a clean compile", async () => {
|
|
130
|
+
// Success stays resource-only: the payload is the answer, and duplicating
|
|
131
|
+
// it as prose would double every response for no gain.
|
|
132
|
+
const handler = captureHandler(storeReturning([]));
|
|
133
|
+
expect(textBlock(await handler(args))).toBeUndefined();
|
|
134
|
+
});
|
|
135
|
+
|
|
92
136
|
it("treats a warning as a clean compile (status success, isError false)", async () => {
|
|
93
137
|
const handler = captureHandler(
|
|
94
138
|
storeReturning([
|
|
@@ -184,6 +228,70 @@ describe("malloy_compile tool", () => {
|
|
|
184
228
|
});
|
|
185
229
|
});
|
|
186
230
|
|
|
231
|
+
describe("formatDiagnosticsText", () => {
|
|
232
|
+
it("renders only the error-severity diagnostics", () => {
|
|
233
|
+
const text = formatDiagnosticsText([
|
|
234
|
+
{ severity: "warn", message: "deprecated syntax", code: "dep" },
|
|
235
|
+
{ severity: "error", message: "first", line: 1, character: 0 },
|
|
236
|
+
{ severity: "error", message: "second", line: 4, character: 2 },
|
|
237
|
+
]);
|
|
238
|
+
expect(text).toBe(
|
|
239
|
+
"Compile failed with 2 errors (positions are 0-based):\n\n" +
|
|
240
|
+
"- first (line 1, character 0)\n" +
|
|
241
|
+
"- second (line 4, character 2)",
|
|
242
|
+
);
|
|
243
|
+
expect(text).not.toContain("deprecated syntax");
|
|
244
|
+
});
|
|
245
|
+
|
|
246
|
+
it("omits the position when a diagnostic has no location", () => {
|
|
247
|
+
expect(
|
|
248
|
+
formatDiagnosticsText([
|
|
249
|
+
{ severity: "error", message: "no location", code: "syntax" },
|
|
250
|
+
]),
|
|
251
|
+
).toBe(
|
|
252
|
+
"Compile failed with 1 error (positions are 0-based):\n\n" +
|
|
253
|
+
"- no location [syntax]",
|
|
254
|
+
);
|
|
255
|
+
});
|
|
256
|
+
|
|
257
|
+
it("renders line 0 / character 0 rather than dropping them", () => {
|
|
258
|
+
// 0 is a real position, not a missing one; a falsy check here would
|
|
259
|
+
// silently swallow the first line of the file.
|
|
260
|
+
expect(
|
|
261
|
+
formatDiagnosticsText([
|
|
262
|
+
{
|
|
263
|
+
severity: "error",
|
|
264
|
+
message: "at the top",
|
|
265
|
+
line: 0,
|
|
266
|
+
character: 0,
|
|
267
|
+
},
|
|
268
|
+
]),
|
|
269
|
+
).toContain("- at the top (line 0, character 0)");
|
|
270
|
+
});
|
|
271
|
+
|
|
272
|
+
it("defaults character to 0 when only the line is known", () => {
|
|
273
|
+
expect(
|
|
274
|
+
formatDiagnosticsText([
|
|
275
|
+
{ severity: "error", message: "line only", line: 7 },
|
|
276
|
+
]),
|
|
277
|
+
).toContain("- line only (line 7, character 0)");
|
|
278
|
+
});
|
|
279
|
+
|
|
280
|
+
it("falls back to every diagnostic when none has error severity", () => {
|
|
281
|
+
// Defensive: status is "error" only when an error-severity diagnostic
|
|
282
|
+
// exists, so this should be unreachable. It must not render an empty
|
|
283
|
+
// list if that ever changes.
|
|
284
|
+
expect(
|
|
285
|
+
formatDiagnosticsText([
|
|
286
|
+
{ severity: "warn", message: "only a warn" },
|
|
287
|
+
]),
|
|
288
|
+
).toBe(
|
|
289
|
+
"Compile failed with 1 error (positions are 0-based):\n\n" +
|
|
290
|
+
"- only a warn",
|
|
291
|
+
);
|
|
292
|
+
});
|
|
293
|
+
});
|
|
294
|
+
|
|
187
295
|
it("forwards givens to compileSource", async () => {
|
|
188
296
|
let captured: unknown;
|
|
189
297
|
const handler = captureHandler({
|
|
@@ -6,6 +6,7 @@ import { EnvironmentStore } from "../../service/environment_store";
|
|
|
6
6
|
import { CompileController } from "../../controller/compile.controller";
|
|
7
7
|
import { type ErrorDetails } from "../error_messages";
|
|
8
8
|
import { buildMalloyUri, classifyToolError } from "../handler_utils";
|
|
9
|
+
import { jsonResource, jsonToolError } from "../tool_response";
|
|
9
10
|
|
|
10
11
|
// Zod shape for malloy_compile. environmentName/packageName mirror the other
|
|
11
12
|
// tools and point the agent at malloy_getContext for name discovery.
|
|
@@ -51,8 +52,53 @@ const COMPILE_DESCRIPTION = `Compile-check Malloy source against a model and ret
|
|
|
51
52
|
- source (required): the Malloy text to validate.
|
|
52
53
|
- includeSql (optional): also return the generated SQL when the source ends in a runnable query. The query is still not executed and no data is scanned.
|
|
53
54
|
|
|
55
|
+
## Checking part of a source
|
|
56
|
+
Your source is APPENDED, so it must stand alone as top-level Malloy: a bare \`view:\`, \`dimension:\` or \`measure:\` does not compile on its own, and resubmitting a source the model already declares reports "Cannot redefine". docs/ai-agents.md gives the two forms that work.
|
|
57
|
+
|
|
54
58
|
## Response
|
|
55
|
-
A JSON object with status ("success" or "error") and diagnostics: an array of { severity ("error" / "warn" / "debug"), message, code, line, character, endLine, endCharacter, replacement }. Positions are 0-based (line and character start at 0) and relative to the model file with your source appended to it, so a diagnostic in your submitted source lands after the model's own line count, and a diagnostic may point at pre-existing content in the model rather than at your source. A clean compile can still return warnings; status is "error" only when at least one diagnostic has error severity.`;
|
|
59
|
+
A JSON object with status ("success" or "error") and diagnostics: an array of { severity ("error" / "warn" / "debug"), message, code, line, character, endLine, endCharacter, replacement }. Positions are 0-based (line and character start at 0) and relative to the model file with your source appended to it, so a diagnostic in your submitted source lands after the model's own line count, and a diagnostic may point at pre-existing content in the model rather than at your source. Any wrapper you add counts toward that offset too. A clean compile can still return warnings; status is "error" only when at least one diagnostic has error severity. When status is "error" the response also states the error diagnostics in a plain text block alongside the JSON, so the failure is legible without parsing the payload.`;
|
|
60
|
+
|
|
61
|
+
/** The flattened diagnostic shape this tool returns. */
|
|
62
|
+
type CompileDiagnostic = {
|
|
63
|
+
severity: string;
|
|
64
|
+
message: string;
|
|
65
|
+
code?: string;
|
|
66
|
+
line?: number;
|
|
67
|
+
character?: number;
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Renders error diagnostics as the prose a text-only client will show.
|
|
72
|
+
*
|
|
73
|
+
* A failed compile is an isError result whose diagnostics live in the resource
|
|
74
|
+
* block, so a client that renders only text blocks on isError sees nothing —
|
|
75
|
+
* which is how a real compile error gets reported as a bare "Unknown error".
|
|
76
|
+
* The resource block stays the parseable channel; this is the legible one.
|
|
77
|
+
* Positions are labelled 0-based to match the payload rather than introduce a
|
|
78
|
+
* second convention for the same numbers.
|
|
79
|
+
*
|
|
80
|
+
* Only error-severity diagnostics are rendered: status is "error" because of
|
|
81
|
+
* those, and they are what the caller has to fix. Falling back to every
|
|
82
|
+
* diagnostic keeps the text non-empty if that invariant ever breaks.
|
|
83
|
+
*
|
|
84
|
+
* Exported so a spec can pin the rendering rather than merely its presence.
|
|
85
|
+
*/
|
|
86
|
+
export function formatDiagnosticsText(
|
|
87
|
+
diagnostics: CompileDiagnostic[],
|
|
88
|
+
): string {
|
|
89
|
+
const errors = diagnostics.filter((d) => d.severity === "error");
|
|
90
|
+
const shown = errors.length > 0 ? errors : diagnostics;
|
|
91
|
+
const lines = shown.map((d) => {
|
|
92
|
+
const at =
|
|
93
|
+
d.line !== undefined
|
|
94
|
+
? ` (line ${d.line}, character ${d.character ?? 0})`
|
|
95
|
+
: "";
|
|
96
|
+
const code = d.code ? ` [${d.code}]` : "";
|
|
97
|
+
return `- ${d.message}${at}${code}`;
|
|
98
|
+
});
|
|
99
|
+
const noun = shown.length === 1 ? "error" : "errors";
|
|
100
|
+
return `Compile failed with ${shown.length} ${noun} (positions are 0-based):\n\n${lines.join("\n")}`;
|
|
101
|
+
}
|
|
56
102
|
|
|
57
103
|
/**
|
|
58
104
|
* Registers the malloy_compile MCP tool: validates Malloy source against a model
|
|
@@ -125,19 +171,19 @@ export function registerCompileTool(
|
|
|
125
171
|
...(result.sql !== undefined && { sql: result.sql }),
|
|
126
172
|
};
|
|
127
173
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
};
|
|
174
|
+
// A compile that returns error diagnostics is still a successful
|
|
175
|
+
// tool call in the transport sense, but isError tells the agent not
|
|
176
|
+
// to treat the model as valid. This is the most common way the tool
|
|
177
|
+
// fails, so it carries a text block for the same reason the catch
|
|
178
|
+
// below does: the diagnostics are only the message to a client that
|
|
179
|
+
// parses the resource. The payload keeps its documented
|
|
180
|
+
// {status, diagnostics} shape rather than the {error, suggestions}
|
|
181
|
+
// of jsonToolError, so parsing clients are unaffected.
|
|
182
|
+
const isError = result.status === "error";
|
|
183
|
+
return jsonResource(uri, payload, {
|
|
184
|
+
isError,
|
|
185
|
+
...(isError && { text: formatDiagnosticsText(diagnostics) }),
|
|
186
|
+
});
|
|
141
187
|
} catch (error) {
|
|
142
188
|
// Unknown environment/package, a notebook (.malloynb) rejected up
|
|
143
189
|
// front, an authorize denial, or a system error: surface as a clean
|
|
@@ -155,22 +201,7 @@ export function registerCompileTool(
|
|
|
155
201
|
`${environmentName}/${packageName}/${modelPath}`,
|
|
156
202
|
error,
|
|
157
203
|
);
|
|
158
|
-
return
|
|
159
|
-
isError: true,
|
|
160
|
-
content: [
|
|
161
|
-
{
|
|
162
|
-
type: "resource" as const,
|
|
163
|
-
resource: {
|
|
164
|
-
type: "application/json",
|
|
165
|
-
uri,
|
|
166
|
-
text: JSON.stringify({
|
|
167
|
-
error: errorDetails.message,
|
|
168
|
-
suggestions: errorDetails.suggestions,
|
|
169
|
-
}),
|
|
170
|
-
},
|
|
171
|
-
},
|
|
172
|
-
],
|
|
173
|
-
};
|
|
204
|
+
return jsonToolError(uri, errorDetails);
|
|
174
205
|
}
|
|
175
206
|
},
|
|
176
207
|
);
|