@malloydata/malloy 0.0.395 → 0.0.397

package/dist/model/query_query.js

@@ -13,6 +13,7 @@ const stage_writer_1 = require("./stage_writer");
 const field_instance_1 = require("./field_instance");
 const sql_compiled_1 = require("./sql_compiled");
 const source_def_utils_1 = require("./source_def_utils");
+const malloy_compile_error_1 = require("./malloy_compile_error");
 function pathToCol(path) {
     return path.map(el => encodeURIComponent(el)).join('/');
 }
@@ -142,7 +143,8 @@ class QueryQuery extends query_node_1.QueryField {
             for (const pathSegment of ungrouping.path) {
                 const nextStruct = destResult.allFields.get(pathSegment);
                 if (!(nextStruct instanceof field_instance_1.FieldInstanceResult)) {
-                    throw new Error(`Ungroup path ${ungrouping.path.join('.')} segment '${pathSegment}' is not a nested query`);
+                    throw new malloy_compile_error_1.MalloyCompileError(`Ungrouping path '${ungrouping.path.join('.')}' references ` +
+                        `'${pathSegment}', which is not a nested view at this level.`, 'compiler-ungrouped-invalid-path', this.fieldDef.location);
                 }
                 destResult = nextStruct;
             }
@@ -192,7 +194,9 @@ class QueryQuery extends query_node_1.QueryField {
             const drillExpression = this.getDrillExpression(f);
             if (field instanceof QueryQuery) {
                 if (this.firstSegment.type === 'project') {
-                    throw new Error(`Nested views cannot be used in select - '${field.fieldDef.name}'`);
+                    throw new malloy_compile_error_1.MalloyCompileError(`Cannot include nested view '${field.fieldDef.name}' in a ` +
+                        "'select:' stage. Nested views require `group_by:` or " +
+                        '`aggregate:` to be included in output.', 'compiler-nested-view-in-select', field.fieldDef.location);
                 }
                 const fir = new field_instance_1.FieldInstanceResult(field.fieldDef, resultStruct);
                 this.expandFields(fir);
@@ -212,7 +216,8 @@ class QueryQuery extends query_node_1.QueryField {
                 }
                 if ((0, query_node_1.isBasicAggregate)(field)) {
                     if (this.firstSegment.type === 'project') {
-                        throw new Error(`Aggregate Fields cannot be used in select - '${field.fieldDef.name}'`);
+                        throw new malloy_compile_error_1.MalloyCompileError(`Cannot include aggregate field '${field.fieldDef.name}' in ` +
+                            "a 'select:' stage. Use `aggregate:` instead to compute aggregates.", 'compiler-aggregate-in-select', field.fieldDef.location);
                     }
                 }
             }
@@ -523,7 +528,9 @@ class QueryQuery extends query_node_1.QueryField {
                 const virtualMap = (_a = qs.prepareResultOptions) === null || _a === void 0 ? void 0 : _a.virtualMap;
                 const tablePath = (_b = virtualMap === null || virtualMap === void 0 ? void 0 : virtualMap.get(qs.structDef.connection)) === null || _b === void 0 ? void 0 : _b.get(qs.structDef.name);
                 if (!tablePath) {
-                    throw new Error(`No virtual map entry for '${qs.structDef.name}' on connection '${qs.structDef.connection}'`);
+                    throw new malloy_compile_error_1.MalloyCompileError(`No virtual-map entry for virtual source '${qs.structDef.name}' ` +
+                        `on connection '${qs.structDef.connection}'. ` +
+                        'Add a virtual-map entry via the `virtualMap` runtime option.', 'runtime-virtual-map-missing', qs.structDef.location);
                 }
                 // virtualMap entries are application-supplied — assumed already
                 // canonical SQL.
@@ -559,10 +566,12 @@ class QueryQuery extends query_node_1.QueryField {
                             return entry.tableName;
                         }
                         if (buildManifest.strict) {
-                            const base = `Persist source '${qs.structDef.sourceID}' not found in manifest (buildId: ${buildId})`;
-                            throw new Error(buildManifest.loadError
+                            const base = `Persist source '${qs.structDef.sourceID}' not found ` +
+                                `in manifest (buildId: ${buildId}); strict manifest mode ` +
+                                'forbids fallback to live compilation.';
+                            throw new malloy_compile_error_1.MalloyCompileError(buildManifest.loadError
                                 ? `${base}\n  ${buildManifest.loadError}`
-                                : base);
+                                : base, 'runtime-manifest-strict-miss', qs.structDef.location);
                         }
                     }
                 }
@@ -598,7 +607,8 @@ class QueryQuery extends query_node_1.QueryField {
         if (typeof structRef === 'string') {
             const struct = this.structRefToQueryStruct(structRef);
             if (!struct) {
-                throw new Error(`Unexpected reference to an undefined source '${structRef}'`);
+                throw new malloy_compile_error_1.MalloyCompileError(`Query references source '${structRef}', ` +
+                    'which is not defined in this model.', 'compiler-undefined-source', undefined);
             }
             sourceStruct = struct;
         }
@@ -858,7 +868,7 @@ class QueryQuery extends query_node_1.QueryField {
                     }
                 }
                 else {
-                    throw new Error(`Unknown field in ORDER BY ${f.field}`);
+                    throw new malloy_compile_error_1.MalloyCompileError(`ORDER BY references unknown field '${f.field}'.`, 'compiler-orderby-field-not-found', queryDef.referencedAt);
                 }
             }
             else {
@@ -1210,7 +1220,9 @@ class QueryQuery extends query_node_1.QueryField {
         this.generateStage0Fields(this.rootResult, f, stageWriter);
         if (this.firstSegment.type === 'project' &&
             !this.parent.modelCompilerFlags().has('unsafe_complex_select_query')) {
-            throw new Error('PROJECT cannot be used on queries with turtles');
+            throw new malloy_compile_error_1.MalloyCompileError("Cannot use 'select:' in a stage that contains nested views. " +
+                'Use `group_by:` or restructure the pipeline. ' +
+                'Set `##! unsafe_complex_select_query` to bypass at your own risk.', 'compiler-project-with-turtles', this.fieldDef.location);
         }
         const groupBy = 'GROUP BY ' + f.dimensionIndexes.join(',') + '\n';
         from += this.parent.dialect.sqlGroupSetTable(this.maxGroupSet) + '\n';
@@ -1611,7 +1623,7 @@ class QueryQueryIndexStage extends QueryQuery {
     }
     expandField(f) {
         const as = f.path.join('.');
-        const field = this.parent.getQueryFieldByName(f.path);
+        const field = this.parent.getQueryFieldByName(f.path, f.at);
         return { as, field };
     }
     expandFields(resultStruct) {

package/dist/model/sql_compiled.js

@@ -8,6 +8,7 @@ exports.getCompiledSQL = getCompiledSQL;
 exports.getSourceSQL = getSourceSQL;
 const malloy_types_1 = require("./malloy_types");
 const source_def_utils_1 = require("./source_def_utils");
+const malloy_compile_error_1 = require("./malloy_compile_error");
 /**
  * Compile a SQLSourceDef to its final SQL string.
  *
@@ -66,10 +67,12 @@ function expandPersistableSource(source, opts, compileQuery) {
             }
             // Not in manifest
             if (buildManifest.strict) {
-                const base = `Persist source '${source.sourceID}' not found in manifest (buildId: ${buildId})`;
-                throw new Error(buildManifest.loadError
+                const base = `Persist source '${source.sourceID}' not found in manifest ` +
+                    `(buildId: ${buildId}); strict manifest mode forbids fallback ` +
+                    'to live compilation.';
+                throw new malloy_compile_error_1.MalloyCompileError(buildManifest.loadError
                     ? `${base}\n  ${buildManifest.loadError}`
-                    : base);
+                    : base, 'runtime-manifest-strict-miss', source.location);
             }
         }
     }

package/dist/prefix.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The result of parsing an annotation's leading prefix.
+ *
+ * An annotation is `prefix sep content`. `parsePrefix` splits the captured
+ * annotation text at the first whitespace, strips the sigil (`#`/`##` plus an
+ * optional block `|`), and classifies the routing into one of three forms.
+ * `route` is one field; `contentIndex` and `malformation` are equally why this
+ * routine exists.
+ */
+export interface ParsedPrefix {
+    /** The route the prefix resolves to. `''` is the MOTLY (empty) route. */
+    route: string;
+    /**
+     * Offset into the annotation text where the content begins;
+     * `text.slice(contentIndex)` is the content, with the single separator
+     * character excluded.
+     */
+    contentIndex: number;
+    /**
+     * Set iff the prefix is not a well-formed route. The annotation is still
+     * stored and reachable via the all-routes API; this only drives a warning.
+     * - `malformed-route`: not one of the three forms — a bare word, an unclosed
+     *   or mismatched bracket, an empty bracketed name, or trailing junk.
+     * - `reserved-route`: a punct-only (sigil) routing that Malloy has not
+     *   claimed; the punct-only namespace is reserved for Malloy's own use.
+     */
+    malformation?: 'malformed-route' | 'reserved-route';
+}
+/**
+ * Parse the leading prefix of a captured annotation.
+ *
+ * `text` is the entire annotation as the lexer captured it, marker included: a
+ * single line `#... content`, or a block `#|...\n<body>` whose body the lexer
+ * has already de-indented and whose closer it has removed. This routine never
+ * parses the content — it returns where the content begins.
+ *
+ * The prefix runs from the marker to the **first whitespace**; that boundary
+ * never moves (no bracket or quote changes it, so a route can never contain
+ * whitespace). After stripping the sigil (`^##?\|?`), the routing matches one
+ * of three forms:
+ *
+ *   1. empty                 -> route `''`        (MOTLY, the human default)
+ *   2. PUNCT+ (no bracket)   -> sigil route       (reserved; unclaimed warns)
+ *   3. OPEN ... CLOSE        -> route = bracketed text (opaque app route)
+ *
+ * Anything else is `malformed-route`. Bracket pairs are `()`, `<>`, `[]`, `{}`;
+ * the route is everything up to the matching close (first close wins, no
+ * nesting), taken literally — no character classification, so `#(bar-chart)`,
+ * `#(https://x/y)`, and `#(v1.2.3)` are all just their bracketed text.
+ */
+export declare function parsePrefix(text: string): ParsedPrefix;

package/dist/prefix.js

@@ -0,0 +1,99 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePrefix = parsePrefix;
+/**
+ * Punct-only (sigil) routes are reserved for Malloy's own use. This is the
+ * closed, enumerated set the compiler claims; any other punct-only routing
+ * warns `reserved-route`. The set being closed is what makes the warning
+ * possible — the compiler knows its own complete sigil vocabulary.
+ */
+const CLAIMED_SIGILS = new Set(['!', '@', '"', ':']);
+/** Bracket pairs an app route may use, as [open, close] — the single source. */
+const BRACKET_PAIRS = [
+    ['(', ')'],
+    ['<', '>'],
+    ['[', ']'],
+    ['{', '}'],
+];
+/** Two views of BRACKET_PAIRS: open->close for lookup, all halves for membership. */
+const OPEN_TO_CLOSE = new Map(BRACKET_PAIRS);
+const BRACKETS = new Set(BRACKET_PAIRS.flat());
+/** Letter, number, or underscore — the "word" characters. */
+const WORDISH = /[\p{L}\p{N}_]/u;
+/**
+ * Parse the leading prefix of a captured annotation.
+ *
+ * `text` is the entire annotation as the lexer captured it, marker included: a
+ * single line `#... content`, or a block `#|...\n<body>` whose body the lexer
+ * has already de-indented and whose closer it has removed. This routine never
+ * parses the content — it returns where the content begins.
+ *
+ * The prefix runs from the marker to the **first whitespace**; that boundary
+ * never moves (no bracket or quote changes it, so a route can never contain
+ * whitespace). After stripping the sigil (`^##?\|?`), the routing matches one
+ * of three forms:
+ *
+ *   1. empty                 -> route `''`        (MOTLY, the human default)
+ *   2. PUNCT+ (no bracket)   -> sigil route       (reserved; unclaimed warns)
+ *   3. OPEN ... CLOSE        -> route = bracketed text (opaque app route)
+ *
+ * Anything else is `malformed-route`. Bracket pairs are `()`, `<>`, `[]`, `{}`;
+ * the route is everything up to the matching close (first close wins, no
+ * nesting), taken literally — no character classification, so `#(bar-chart)`,
+ * `#(https://x/y)`, and `#(v1.2.3)` are all just their bracketed text.
+ */
+function parsePrefix(text) {
+    // 1. Split prefix from content at the first whitespace. The single separator
+    //    character is excluded from the content.
+    //    `\r` is in the class because Windows line endings put a `\r` right before
+    //    the `\n` at every line end (the lexer keeps `\r` out of line *content*),
+    //    so on a content-less prefix like `#(docs)\r\n` the `\r` must not be pulled
+    //    into the routing. We split on it rather than mutating the text, so source
+    //    offsets stay intact for error mapping; any line-ending bytes remain in the
+    //    content, which is faithful to source and harmless to payload parsers.
+    const boundary = text.search(/[ \t\r\n]/);
+    const prefix = boundary === -1 ? text : text.slice(0, boundary);
+    const contentIndex = boundary === -1 ? text.length : boundary + 1;
+    // 2. Strip the sigil: one or two '#', then an optional block '|'.
+    const sigil = /^(#{1,2})(\|?)/.exec(prefix);
+    if (!sigil) {
+        // A captured annotation always starts with '#'; if it somehow does not,
+        // there is no route to speak of — likely a compiler bug upstream.
+        return { route: prefix, contentIndex, malformation: 'malformed-route' };
+    }
+    const routing = prefix.slice(sigil[0].length);
+    // Form 1: empty routing -> the MOTLY namespace.
+    if (routing === '') {
+        return { route: '', contentIndex };
+    }
+    // Form 3: opens with a bracket -> route is the text up to the matching close.
+    // A non-undefined close both proves routing[0] is an open bracket and gives
+    // us its partner in one lookup.
+    const close = OPEN_TO_CLOSE.get(routing[0]);
+    if (close !== undefined) {
+        const closeIdx = routing.indexOf(close, 1);
+        const malformed = closeIdx === -1 || // unclosed
+            closeIdx !== routing.length - 1 || // trailing junk after the close
+            closeIdx === 1; // empty bracketed text: `#()`
+        if (malformed) {
+            return { route: routing, contentIndex, malformation: 'malformed-route' };
+        }
+        return { route: routing.slice(1, closeIdx), contentIndex };
+    }
+    // Form 2: pure punctuation (no word chars, no brackets) -> sigil route.
+    const isPurePunct = [...routing].every(c => !WORDISH.test(c) && !BRACKETS.has(c));
+    if (isPurePunct) {
+        return {
+            route: routing,
+            contentIndex,
+            malformation: CLAIMED_SIGILS.has(routing) ? undefined : 'reserved-route',
+        };
+    }
+    // Otherwise: a bare word, or mixed text with no brackets.
+    return { route: routing, contentIndex, malformation: 'malformed-route' };
+}
+//# sourceMappingURL=prefix.js.map

package/dist/taggable.d.ts

@@ -1,10 +1,26 @@
-import type { TagParseSpec, MalloyTagParse } from './annotation';
+import type { TagParseSpec, MalloyTagParse, Annotations } from './annotation';
 /**
  * Interface for objects that have Malloy tag annotations.
  * This is part of the runtime API - objects returned from the Malloy
  * runtime implement this interface to expose their tag metadata.
  */
 export interface Taggable {
+    /**
+     * Route-aware annotation access — read annotations by *route*. See
+     * `Annotations` for what a route is and which ones are claimed. Unlike
+     * `tagParse`/`getTaglines`, this sees block annotations (`#|`…`|#`).
+     */
+    readonly annotations: Annotations;
+    /**
+     * @deprecated The RegExp form cannot see block annotations (`#|`…`|#`) and
+     * cannot report content offsets for error mapping. Use
+     * `annotations.parseAsTag(route)` instead.
+     */
     tagParse: (spec?: TagParseSpec) => MalloyTagParse;
+    /**
+     * @deprecated The RegExp form cannot see block annotations. Use
+     * `annotations.texts(route)` (raw strings) or `annotations.forRoute(route)`
+     * (objects with offsets) instead.
+     */
     getTaglines: (prefix?: RegExp) => string[];
 }

package/dist/test/resultMatchers.js

@@ -70,7 +70,8 @@ async function runQueryInternal(tm, src) {
     let queryTestTag = undefined;
     try {
         query = tm.model.loadQuery(src);
-        const queryTags = (await query.getPreparedQuery()).tagParse().tag;
+        const queryTags = (await query.getPreparedQuery()).annotations.parseAsTag()
+            .tag;
         queryTestTag = queryTags.tag('test');
     }
     catch (e) {

package/dist/to_stable.d.ts

@@ -1,8 +1,14 @@
 import * as Malloy from '@malloydata/malloy-interfaces';
-import type { FieldDef, ModelDef, ResultStructMetadataDef, SourceDef } from './model';
+import type { Annotation, FieldDef, ModelDef, ResultStructMetadataDef, SourceDef } from './model';
 import { Tag } from '@malloydata/malloy-tag';
 export declare function sourceDefToSourceInfo(sourceDef: SourceDef): Malloy.SourceInfo;
 export declare function modelDefToModelInfo(modelDef: ModelDef): Malloy.ModelInfo;
+/**
+ * IR annotation → stable `Malloy.Annotation[]` shape used across `to_stable`
+ * and the api surfaces. The stable shape carries the raw annotation strings;
+ * routes are derivable at the consumer via `parsePrefix` (`./prefix.ts`).
+ */
+export declare function toStableAnnotations(annot: Annotation | undefined): Malloy.Annotation[];
 export declare function convertFieldInfos(source: SourceDef, fields: FieldDef[]): Malloy.FieldInfo[];
 export declare function writeLiteralToTag(tag: Tag, path: (string | number)[], literal: Malloy.LiteralValue): void;
 export declare function getResultStructMetadataAnnotation(field: SourceDef, resultMetadata: ResultStructMetadataDef): Malloy.Annotation | undefined;

package/dist/to_stable.js

@@ -41,6 +41,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sourceDefToSourceInfo = sourceDefToSourceInfo;
 exports.modelDefToModelInfo = modelDefToModelInfo;
+exports.toStableAnnotations = toStableAnnotations;
 exports.convertFieldInfos = convertFieldInfos;
 exports.writeLiteralToTag = writeLiteralToTag;
 exports.getResultStructMetadataAnnotation = getResultStructMetadataAnnotation;
@@ -77,7 +78,7 @@ function sourceDefToSourceInfo(sourceDef) {
             fields: convertFieldInfos(sourceDef, sourceDef.fields),
         },
         parameters,
-        annotations: getAnnotationsFromField(sourceDef),
+        annotations: toStableAnnotations(sourceDef.annotation),
     };
     return sourceInfo;
 }
@@ -98,7 +99,7 @@ function modelDefToModelInfo(modelDef) {
         }
         else if (entry.type === 'query') {
             const outputStruct = (0, model_1.getResultStructDefForQuery)(modelDef, entry);
-            const annotations = getAnnotationsFromField(entry);
+            const annotations = toStableAnnotations(entry.annotation);
             const resultMetadataAnnotation = outputStruct.resultMetadata
                 ? getResultStructMetadataAnnotation(outputStruct, outputStruct.resultMetadata)
                 : undefined;
@@ -119,7 +120,7 @@ function modelDefToModelInfo(modelDef) {
     }
     for (const query of modelDef.queryList) {
         const outputStruct = (0, model_1.getResultStructDefForQuery)(modelDef, query);
-        const annotations = getAnnotationsFromField(query);
+        const annotations = toStableAnnotations(query.annotation);
         const resultMetadataAnnotation = outputStruct.resultMetadata
             ? getResultStructMetadataAnnotation(outputStruct, outputStruct.resultMetadata)
             : undefined;
@@ -173,11 +174,13 @@ function convertParameterDefaultValue(value) {
             throw new Error('Invalid parameter default value');
     }
 }
-function getAnnotationsFromField(field) {
-    const taglines = (0, annotation_1.annotationToTaglines)(field.annotation);
-    return taglines.map(tagline => ({
-        value: tagline,
-    }));
+/**
+ * IR annotation → stable `Malloy.Annotation[]` shape used across `to_stable`
+ * and the api surfaces. The stable shape carries the raw annotation strings;
+ * routes are derivable at the consumer via `parsePrefix` (`./prefix.ts`).
+ */
+function toStableAnnotations(annot) {
+    return new annotation_1.Annotations(annot).texts().map(value => ({ value }));
 }
 function convertFieldInfos(source, fields) {
     var _a, _b, _c;
@@ -186,10 +189,7 @@ function convertFieldInfos(source, fields) {
         const isPublic = field.accessModifier === undefined;
         if (!isPublic)
             continue;
-        const taglines = (0, annotation_1.annotationToTaglines)(field.annotation);
-        const rawAnnotations = taglines.map(tagline => ({
-            value: tagline,
-        }));
+        const rawAnnotations = toStableAnnotations(field.annotation);
         const annotations = rawAnnotations.length > 0 ? rawAnnotations : undefined;
         if ((0, model_1.isTurtle)(field)) {
             const outputStruct = (0, model_1.getResultStructDefForView)(source, field);
@@ -452,10 +452,7 @@ function convertRecordType(field) {
                 }
             }
             if (f.annotation) {
-                const taglines = (0, annotation_1.annotationToTaglines)(f.annotation);
-                annotations.push(...taglines.map(tagline => ({
-                    value: tagline,
-                })));
+                annotations.push(...toStableAnnotations(f.annotation));
             }
             if ((0, model_1.isAtomic)(f)) {
                 return {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const MALLOY_VERSION = "0.0.395";
+export declare const MALLOY_VERSION = "0.0.397";

package/dist/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MALLOY_VERSION = void 0;
 // generated with 'generate-version-file' script; do not edit manually
-exports.MALLOY_VERSION = '0.0.395';
+exports.MALLOY_VERSION = '0.0.397';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@malloydata/malloy",
-  "version": "0.0.395",
+  "version": "0.0.397",
   "license": "MIT",
   "exports": {
     ".": "./dist/index.js",
@@ -51,9 +51,9 @@
     "generate-version-file": "VERSION=$(npm pkg get version --workspaces=false | tr -d \\\")\necho \"// generated with 'generate-version-file' script; do not edit manually\\nexport const MALLOY_VERSION = '$VERSION';\" > src/version.ts"
   },
   "dependencies": {
-    "@malloydata/malloy-filter": "0.0.395",
-    "@malloydata/malloy-interfaces": "0.0.395",
-    "@malloydata/malloy-tag": "0.0.395",
+    "@malloydata/malloy-filter": "0.0.397",
+    "@malloydata/malloy-interfaces": "0.0.397",
+    "@malloydata/malloy-tag": "0.0.397",
     "@noble/hashes": "^1.8.0",
     "antlr4ts": "^0.5.0-alpha.4",
     "assert": "^2.0.0",