@soundscript/soundscript 0.1.13 → 0.1.15

package/project-transform/src/frontend/builtin_macros.js

@@ -0,0 +1,409 @@
+import { macroSignature } from './macro_api.js';
+import { attachMacroFactoryMetadata } from './macro_api_internal.js';
+import { cssFragments, expandCssMacro } from './css_macro.js';
+import { expandGraphqlMacro, graphqlFragments } from './graphql_macro.js';
+export { Do, hkt } from './hkt_macro.js';
+import { expandMatchMacro, hoverMatchMacro, hoverMatchMacroPosition, semanticTokensForMatchMacro, } from './match_macro.js';
+import { expandSqlMacro, sqlFragments } from './sql_macro.js';
+import { fromFileUrl } from '../platform/path.js';
+const EXPR_BUILTIN_SUMMARY_DETAILS = {
+    Try: [
+        'Unwraps `Result<Ok, Err>`. If the operand is `err`, the enclosing function returns that error immediately.',
+    ],
+    lazy: ['Wraps the operand in a thunk so it is only evaluated when later invoked.'],
+    log: [
+        'Evaluates the operand, logs its source text and value, then yields the original value unchanged.',
+    ],
+    memo: [
+        'Wraps the operand in a thunk that caches the first computed value and returns it on later calls.',
+    ],
+};
+function containsOffset(span, position) {
+    return position >= span.start && position < span.end;
+}
+function buildExprBuiltinMacroSyntaxNode(ctx, kind, details) {
+    return {
+        data: {
+            details: [...details],
+            operandSpan: ctx.invocation.args[0]?.span ?? null,
+        },
+        kind,
+        span: ctx.invocationSpan(),
+    };
+}
+function hoverExprBuiltinMacro(ctx) {
+    const node = ctx.node;
+    const macroKind = (node.kind === 'Try' ||
+        node.kind === 'lazy' ||
+        node.kind === 'log' ||
+        node.kind === 'memo'
+        ? node.kind
+        : node.name);
+    if (!macroKind) {
+        return null;
+    }
+    const operandSpan = node.data?.operandSpan ?? null;
+    const position = node.span.start + ctx.offset;
+    if (operandSpan && containsOffset(operandSpan, position)) {
+        return null;
+    }
+    const details = node.data?.details ?? EXPR_BUILTIN_SUMMARY_DETAILS[macroKind];
+    return {
+        contents: [
+            `**macro** \`${macroKind}\``,
+            '',
+            ...details,
+        ].join('\n'),
+    };
+}
+function formatMatchBuiltinMacro(ctx) {
+    const node = ctx.node;
+    const [value, arms] = node.args;
+    if (!value || !arms) {
+        return node.text();
+    }
+    return `Match(${ctx.formatExpression(value.text())}, ${ctx.formatExpression(arms.text())})`;
+}
+const SINGLE_EXPR_SIGNATURE = macroSignature.of(macroSignature.expr('value'));
+const OPTIONAL_SINGLE_EXPR_SIGNATURE = macroSignature.of(macroSignature.optional(macroSignature.expr('message')));
+const EXPR_CASE = macroSignature.case('expr', macroSignature.expr('value'));
+const BLOCK_CASE = macroSignature.case('block', macroSignature.block('body'));
+const EXPR_OR_BLOCK_SIGNATURE = macroSignature.oneOf(EXPR_CASE, BLOCK_CASE);
+const BLOCK_SIGNATURE = macroSignature.of(macroSignature.block('body'));
+const DEFER_SIGNATURE = macroSignature.of(macroSignature.functionExpr('cleanup'));
+const MATCH_SIGNATURE = macroSignature.of(macroSignature.expr('value'), macroSignature.arrayLiteral('arms'));
+const TEMPLATE_SIGNATURE = macroSignature.of(macroSignature.template('template'));
+const BUILTIN_MACRO_FILE_NAME = fromFileUrl(import.meta.url);
+function attachBuiltinFactory(factory, form) {
+    return attachMacroFactoryMetadata(factory, {
+        form,
+        moduleFileName: BUILTIN_MACRO_FILE_NAME,
+    });
+}
+// #[macro(call)]
+export function log() {
+    return {
+        expand(ctx, signature) {
+            const expr = signature.args.value;
+            const valueName = ctx.fresh.binding('__sts_log_value');
+            return ctx.output.expr(ctx.quote.expr `
+          (() => {
+            const ${valueName} = ${expr};
+            console.log(${JSON.stringify(expr.text())}, ${valueName});
+            return ${valueName};
+          })()
+        `);
+        },
+        hover(ctx) {
+            return hoverExprBuiltinMacro(ctx);
+        },
+        parse(ctx) {
+            return buildExprBuiltinMacroSyntaxNode(ctx, 'log', ['Evaluates the operand, logs its source text and value, then yields the original value unchanged.']);
+        },
+        signature: SINGLE_EXPR_SIGNATURE,
+    };
+}
+attachBuiltinFactory(log, 'call');
+function expandedPrimaryExprText(ctx) {
+    return ctx.semantics.primaryExprExpanded()?.text() ?? ctx.syntax.primaryExpr().text();
+}
+// #[macro(call)]
+export function lazy() {
+    return {
+        expand(ctx, signature) {
+            if (signature.caseName === 'expr') {
+                return ctx.output.expr(ctx.quote.expr `() => (${expandedPrimaryExprText(ctx)})`);
+            }
+            return ctx.output.expr(ctx.quote.expr `() => (() => ${signature.args.body})()`);
+        },
+        hover(ctx) {
+            return hoverExprBuiltinMacro(ctx);
+        },
+        parse(ctx) {
+            return buildExprBuiltinMacroSyntaxNode(ctx, 'lazy', ['Wraps the operand in a thunk so it is not evaluated until the thunk is invoked.']);
+        },
+        signature: EXPR_OR_BLOCK_SIGNATURE,
+    };
+}
+attachBuiltinFactory(lazy, 'call');
+// #[macro(call)]
+export function memo() {
+    return {
+        expand(ctx, signature) {
+            const readyName = ctx.fresh.binding('__sts_memo_ready');
+            const valueName = ctx.fresh.binding('__sts_memo_value');
+            const computation = signature.caseName === 'block'
+                ? `(() => ${signature.args.body.text()})()`
+                : `(${expandedPrimaryExprText(ctx)})`;
+            return ctx.output.expr(ctx.quote.expr `
+        (() => {
+          let ${readyName} = false;
+          let ${valueName};
+          return () => {
+            if (!${readyName}) {
+              ${valueName} = ${computation};
+              ${readyName} = true;
+            }
+            return ${valueName};
+          };
+        })()
+      `);
+        },
+        hover(ctx) {
+            return hoverExprBuiltinMacro(ctx);
+        },
+        parse(ctx) {
+            return buildExprBuiltinMacroSyntaxNode(ctx, 'memo', ['Wraps the operand in a thunk that caches the first computed value and returns it on later calls.']);
+        },
+        signature: EXPR_OR_BLOCK_SIGNATURE,
+    };
+}
+attachBuiltinFactory(memo, 'call');
+// #[macro(call)]
+export function Try() {
+    return {
+        expand(ctx) {
+            const placement = ctx.controlFlow.placement();
+            if (placement.kind === 'unsupported') {
+                if (placement.reason === 'multi-declaration') {
+                    ctx.error('Try currently only supports declarations with a single variable declarator.');
+                }
+                ctx.error('Try currently only supports expression sites that can be hoisted through the nearest enclosing statement.');
+            }
+            const enclosingFunction = ctx.semantics.primaryExprEnclosingFunction() ??
+                ctx.semantics.enclosingFunction();
+            const activeEnclosingFunction = enclosingFunction ??
+                ctx.error('Try can only be used inside a function or method body.');
+            if (activeEnclosingFunction.isGenerator) {
+                ctx.error('Try does not yet support generators or yield-based Result flows.');
+            }
+            const expandedOperand = ctx.semantics.primaryExprExpanded() ??
+                ctx.error('Try could not resolve the operand expression for semantic analysis.');
+            const operandPrelude = ctx.semantics.primaryExprPrelude() ?? [];
+            const operandType = ctx.semantics.primaryExprType();
+            const activeOperandCarrier = (() => {
+                const carrier = ctx.semantics.primaryExprTryCarrier();
+                if (carrier) {
+                    return carrier;
+                }
+                const canonicalCarrier = operandType
+                    ? ctx.semantics.classifyCanonicalResultCarrierType(operandType)
+                    : null;
+                if (canonicalCarrier?.requiresAwait) {
+                    return ctx.error('Try requires a direct Result, Option, or nullish carrier. Await Promises explicitly before calling Try.');
+                }
+                return ctx.error('Try requires a direct Result, Option, or nullish carrier.');
+            })();
+            const temp = ctx.controlFlow.freshBinding('__sts_attempt');
+            const expandedOperandText = expandedOperand.text();
+            if (activeOperandCarrier.kind === 'result') {
+                const isOptionCarrier = activeOperandCarrier.family === 'option';
+                const enclosingResult = ctx.semantics.primaryExprEnclosingFunctionCanonicalResult() ??
+                    ctx.semantics.enclosingFunctionCanonicalResult();
+                const activeEnclosingResult = enclosingResult ??
+                    ctx.error(activeEnclosingFunction.isAsync
+                        ? 'Try requires async functions to return Promise<soundscript Result<Ok, Err>>.'
+                        : 'Try requires the enclosing function to return soundscript Result<Ok, Err>.');
+                if (activeEnclosingFunction.hasDeclaredReturnType &&
+                    !ctx.semantics.isAssignable(activeOperandCarrier.errType, activeEnclosingResult.errType)) {
+                    ctx.error('Try cannot return this error type from the enclosing function.');
+                }
+                const isErr = !isOptionCarrier ? ctx.runtime.named('sts:result', 'isErr').text() : null;
+                const isNone = isOptionCarrier ? ctx.runtime.named('sts:result', 'isNone').text() : null;
+                const errFactory = !isOptionCarrier ? ctx.runtime.named('sts:result', 'err').text() : null;
+                const location = ctx.location();
+                const traceFrame = [
+                    `{ file: ${JSON.stringify(location.filePath)}, line: ${location.line}, column: ${location.column}${activeEnclosingFunction.name
+                        ? `, fn: ${JSON.stringify(activeEnclosingFunction.name)}`
+                        : ''} }`,
+                ].join('');
+                const tracesFailure = !isOptionCarrier &&
+                    ctx.semantics.classifyCanonicalFailureType(activeOperandCarrier.errType) !== null;
+                const errorReturn = tracesFailure && errFactory
+                    ? `${errFactory}(${temp}.error.withFrame(${traceFrame}))`
+                    : temp;
+                const failureCheck = isOptionCarrier && isNone ? `${isNone}(${temp})` : `${isErr}(${temp})`;
+                return ctx.controlFlow.rewriteWithValue([
+                    ...operandPrelude,
+                    ...ctx.quote.stmts `
+              const ${temp} = ${expandedOperandText};
+              if (${failureCheck}) { return ${errorReturn}; }
+            `,
+                ], ctx.quote.expr `${temp}.value`);
+            }
+            const enclosingReturnType = activeEnclosingFunction.isAsync
+                ? ctx.semantics.awaitedType(activeEnclosingFunction.returnType)
+                : activeEnclosingFunction.returnType;
+            for (const nullishKind of activeOperandCarrier.nullishKinds) {
+                const nullishType = nullishKind === 'null'
+                    ? ctx.semantics.nullType()
+                    : ctx.semantics.undefinedType();
+                if (!ctx.semantics.isAssignable(nullishType, enclosingReturnType)) {
+                    ctx.error('Try cannot return this nullish value from the enclosing function.');
+                }
+            }
+            const nullishCheck = activeOperandCarrier.nullishKinds.length === 2
+                ? `${temp} == null`
+                : activeOperandCarrier.nullishKinds[0] === 'null'
+                    ? `${temp} === null`
+                    : `${temp} === undefined`;
+            return ctx.controlFlow.rewriteWithValue([
+                ...operandPrelude,
+                ...ctx.quote.stmts `
+            const ${temp} = ${expandedOperandText};
+            if (${nullishCheck}) { return ${temp}; }
+          `,
+            ], ctx.quote.expr `${temp}`);
+        },
+        hover(ctx) {
+            return hoverExprBuiltinMacro(ctx);
+        },
+        parse(ctx) {
+            const details = [
+                'Unwraps a direct `Result<Ok, Err>`, `Option<T>`, or nullish carrier. Failing carriers return early from the enclosing function.',
+            ];
+            const tryCarrier = ctx.semantics.primaryExprTryCarrier();
+            if (tryCarrier?.kind === 'result') {
+                details.push(`operand: \`${tryCarrier.resultType.displayText}\``);
+                details.push(`yields: \`${tryCarrier.okType.displayText}\``);
+                details.push(`returns early on: \`${tryCarrier.family === 'option' ? 'None' : tryCarrier.errType.displayText}\``);
+            }
+            else if (tryCarrier?.kind === 'nullish') {
+                details.push(`operand: \`${tryCarrier.carrierType.displayText}\``);
+                details.push(`yields: \`${tryCarrier.valueType.displayText}\``);
+                details.push(`returns early on: \`${tryCarrier.nullishKinds.join(' | ')}\``);
+            }
+            return buildExprBuiltinMacroSyntaxNode(ctx, 'Try', details);
+        },
+        signature: SINGLE_EXPR_SIGNATURE,
+    };
+}
+attachBuiltinFactory(Try, 'call');
+// #[macro(call)]
+export function Defer() {
+    return {
+        expand(ctx, signature) {
+            if (!ctx.semantics.enclosingFunction()) {
+                ctx.error('Defer can only be used inside a function or method body.');
+            }
+            const cleanupBody = signature.args.cleanup.body() ??
+                ctx.error('Defer only supports: Defer(() => { ... }).');
+            return ctx.controlFlow.deferCleanup(cleanupBody);
+        },
+        signature: DEFER_SIGNATURE,
+    };
+}
+attachBuiltinFactory(Defer, 'call');
+// #[macro(call)]
+export function assert() {
+    return {
+        expand(ctx, signature) {
+            const operandText = ctx.semantics.argExpanded(0)?.text() ?? signature.args.value.text();
+            const message = JSON.stringify(`Assertion failed: ${ctx.syntax.primaryExpr().text()}`);
+            if (ctx.kind === 'stmt') {
+                return ctx.output.stmt(ctx.quote.stmt `if (!(${operandText})) { throw new Error(${message}); }`);
+            }
+            const temp = ctx.fresh.binding('__sts_assert');
+            return ctx.output.expr(ctx.quote.expr `
+        (() => {
+          const ${temp} = (${operandText});
+          if (!${temp}) { throw new Error(${message}); }
+          return ${temp};
+        })()
+      `);
+        },
+        signature: SINGLE_EXPR_SIGNATURE,
+    };
+}
+attachBuiltinFactory(assert, 'call');
+function buildThrowingBuiltinMacro(name, prefix) {
+    return {
+        expand(ctx, signature) {
+            const messageExpr = signature.args.message === null
+                ? null
+                : ctx.semantics.argExpanded(0)?.text() ?? signature.args.message.text();
+            const messageText = messageExpr === null
+                ? JSON.stringify(prefix)
+                : `\`${prefix}: \${String(${messageExpr})}\``;
+            if (ctx.kind === 'stmt') {
+                return ctx.output.stmt(ctx.quote.stmt `throw new Error(${messageText});`);
+            }
+            return ctx.output.expr(ctx.quote.expr `(() => { throw new Error(${messageText}); })()`);
+        },
+        signature: OPTIONAL_SINGLE_EXPR_SIGNATURE,
+    };
+}
+// #[macro(call)]
+export function todo() {
+    return buildThrowingBuiltinMacro('todo', 'TODO');
+}
+attachBuiltinFactory(todo, 'call');
+// #[macro(call)]
+export function unreachable() {
+    return buildThrowingBuiltinMacro('unreachable', 'Unreachable');
+}
+attachBuiltinFactory(unreachable, 'call');
+// #[macro(call)]
+export function Match() {
+    return {
+        expand(ctx, signature) {
+            return expandMatchMacro(ctx, signature.args.value, signature.args.arms);
+        },
+        format(ctx) {
+            return formatMatchBuiltinMacro(ctx);
+        },
+        hover(ctx) {
+            return hoverMatchMacro(ctx);
+        },
+        positionHover(ctx) {
+            return hoverMatchMacroPosition(ctx);
+        },
+        parse(ctx) {
+            return ctx.syntax.root();
+        },
+        semanticTokens(ctx) {
+            return semanticTokensForMatchMacro(ctx);
+        },
+        signature: MATCH_SIGNATURE,
+    };
+}
+attachBuiltinFactory(Match, 'call');
+// #[macro(tag)]
+export function sql() {
+    return {
+        expand(ctx) {
+            return expandSqlMacro(ctx);
+        },
+        fragments(ctx) {
+            return sqlFragments(ctx);
+        },
+        signature: TEMPLATE_SIGNATURE,
+    };
+}
+attachBuiltinFactory(sql, 'tag');
+// #[macro(tag)]
+export function css() {
+    return {
+        expand(ctx) {
+            return expandCssMacro(ctx);
+        },
+        fragments(ctx) {
+            return cssFragments(ctx);
+        },
+        signature: TEMPLATE_SIGNATURE,
+    };
+}
+attachBuiltinFactory(css, 'tag');
+// #[macro(tag)]
+export function graphql() {
+    return {
+        expand(ctx) {
+            return expandGraphqlMacro(ctx);
+        },
+        fragments(ctx) {
+            return graphqlFragments(ctx);
+        },
+        signature: TEMPLATE_SIGNATURE,
+    };
+}
+attachBuiltinFactory(graphql, 'tag');