@soundscript/soundscript 0.1.13 → 0.1.15

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

@@ -0,0 +1,35 @@
+const MACRO_FACTORY_METADATA = Symbol.for('soundscript.macro-factory-metadata');
+const MACRO_DEFINITION_METADATA = Symbol.for('soundscript.macro-definition-metadata');
+export function attachMacroFactoryMetadata(factory, metadata) {
+    Object.defineProperty(factory, MACRO_FACTORY_METADATA, {
+        configurable: true,
+        enumerable: false,
+        value: metadata,
+        writable: true,
+    });
+    return factory;
+}
+export function getMacroFactoryMetadata(value) {
+    return typeof value === 'function' &&
+        MACRO_FACTORY_METADATA in value &&
+        typeof value[MACRO_FACTORY_METADATA]?.form === 'string'
+        ? value[MACRO_FACTORY_METADATA] ?? null
+        : null;
+}
+export function attachLoadedMacroDefinitionMetadata(definition, metadata) {
+    Object.defineProperty(definition, MACRO_DEFINITION_METADATA, {
+        configurable: true,
+        enumerable: false,
+        value: metadata,
+        writable: true,
+    });
+    return definition;
+}
+export function getLoadedMacroDefinitionMetadata(value) {
+    return typeof value === 'object' &&
+        value !== null &&
+        MACRO_DEFINITION_METADATA in value &&
+        typeof value[MACRO_DEFINITION_METADATA]?.form === 'string'
+        ? value[MACRO_DEFINITION_METADATA] ?? null
+        : null;
+}

package/project-transform/src/frontend/macro_api_internal.ts

@@ -0,0 +1,80 @@
+import type {
+  MacroDeclarationExpansionMode,
+  MacroDeclarationKind,
+  MacroDefinition,
+} from './macro_api.ts';
+
+export type InternalMacroFactoryForm = 'call' | 'decl' | 'tag';
+
+export interface InternalLoadedMacroDefinitionMetadata {
+  readonly declarationKinds?: readonly MacroDeclarationKind[];
+  readonly expansionMode: MacroDeclarationExpansionMode;
+  readonly form: InternalMacroFactoryForm;
+  readonly moduleFileName?: string;
+  readonly moduleSpecifier: string;
+}
+
+const MACRO_FACTORY_METADATA = Symbol.for('soundscript.macro-factory-metadata');
+const MACRO_DEFINITION_METADATA = Symbol.for('soundscript.macro-definition-metadata');
+
+interface InternalMacroFactoryMetadata {
+  readonly form: InternalMacroFactoryForm;
+  readonly moduleFileName?: string;
+}
+
+type InternalMacroFactoryShape = (() => MacroDefinition) & {
+  readonly [MACRO_FACTORY_METADATA]?: InternalMacroFactoryMetadata;
+};
+
+type InternalMacroDefinitionShape = MacroDefinition & {
+  readonly [MACRO_DEFINITION_METADATA]?: InternalLoadedMacroDefinitionMetadata;
+};
+
+export function attachMacroFactoryMetadata(
+  factory: () => MacroDefinition,
+  metadata: InternalMacroFactoryMetadata,
+): typeof factory {
+  Object.defineProperty(factory, MACRO_FACTORY_METADATA, {
+    configurable: true,
+    enumerable: false,
+    value: metadata,
+    writable: true,
+  });
+  return factory;
+}
+
+export function getMacroFactoryMetadata(
+  value: unknown,
+): InternalMacroFactoryMetadata | null {
+  return typeof value === 'function' &&
+      MACRO_FACTORY_METADATA in value &&
+      typeof (value as InternalMacroFactoryShape)[MACRO_FACTORY_METADATA]?.form === 'string'
+    ? (value as InternalMacroFactoryShape)[MACRO_FACTORY_METADATA] ?? null
+    : null;
+}
+
+export function attachLoadedMacroDefinitionMetadata<
+  Definition extends MacroDefinition,
+>(
+  definition: Definition,
+  metadata: InternalLoadedMacroDefinitionMetadata,
+): Definition {
+  Object.defineProperty(definition, MACRO_DEFINITION_METADATA, {
+    configurable: true,
+    enumerable: false,
+    value: metadata,
+    writable: true,
+  });
+  return definition;
+}
+
+export function getLoadedMacroDefinitionMetadata(
+  value: unknown,
+): InternalLoadedMacroDefinitionMetadata | null {
+  return typeof value === 'object' &&
+      value !== null &&
+      MACRO_DEFINITION_METADATA in value &&
+      typeof (value as InternalMacroDefinitionShape)[MACRO_DEFINITION_METADATA]?.form === 'string'
+    ? (value as InternalMacroDefinitionShape)[MACRO_DEFINITION_METADATA] ?? null
+    : null;
+}

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

@@ -0,0 +1,39 @@
+import ts from 'typescript';
+import { fromFileUrl } from '../platform/path.js';
+export const MACRO_API_MODULE_SPECIFIER = 'sts:macros';
+export const MACRO_API_MODULE_FILE = fromFileUrl(new URL('../macros.d.ts', import.meta.url));
+function createModuleResolutionHost(baseHost) {
+    return {
+        directoryExists: baseHost.directoryExists?.bind(baseHost),
+        fileExists: baseHost.fileExists.bind(baseHost),
+        getCurrentDirectory: baseHost.getCurrentDirectory?.bind(baseHost) ??
+            (() => ts.sys.getCurrentDirectory()),
+        getDirectories: baseHost.getDirectories?.bind(baseHost),
+        readFile: baseHost.readFile.bind(baseHost),
+        realpath: baseHost.realpath?.bind(baseHost),
+        useCaseSensitiveFileNames: () => ts.sys.useCaseSensitiveFileNames,
+    };
+}
+export function withMacroApiModuleResolution(baseHost) {
+    return {
+        ...baseHost,
+        resolveModuleNames(moduleNames, containingFile, reusedNames, redirectedReference, options) {
+            const fallbackHost = createModuleResolutionHost(baseHost);
+            const delegated = baseHost.resolveModuleNames?.(moduleNames, containingFile, reusedNames, redirectedReference, options ?? {});
+            return moduleNames.map((moduleName, index) => {
+                if (moduleName === MACRO_API_MODULE_SPECIFIER) {
+                    return {
+                        resolvedFileName: MACRO_API_MODULE_FILE,
+                        extension: ts.Extension.Dts,
+                        isExternalLibraryImport: true,
+                    };
+                }
+                if (delegated?.[index]) {
+                    return delegated[index];
+                }
+                const resolved = ts.resolveModuleName(moduleName, containingFile, options ?? {}, fallbackHost, undefined, redirectedReference);
+                return resolved.resolvedModule;
+            });
+        },
+    };
+}

package/project-transform/src/frontend/macro_api_module_support.ts

@@ -0,0 +1,65 @@
+import ts from 'typescript';
+
+import { fromFileUrl } from '../platform/path.ts';
+
+export const MACRO_API_MODULE_SPECIFIER = 'sts:macros';
+export const MACRO_API_MODULE_FILE = fromFileUrl(new URL('../macros.d.ts', import.meta.url));
+
+function createModuleResolutionHost(baseHost: ts.CompilerHost): ts.ModuleResolutionHost {
+  return {
+    directoryExists: baseHost.directoryExists?.bind(baseHost),
+    fileExists: baseHost.fileExists.bind(baseHost),
+    getCurrentDirectory: baseHost.getCurrentDirectory?.bind(baseHost) ??
+      (() => ts.sys.getCurrentDirectory()),
+    getDirectories: baseHost.getDirectories?.bind(baseHost),
+    readFile: baseHost.readFile.bind(baseHost),
+    realpath: baseHost.realpath?.bind(baseHost),
+    useCaseSensitiveFileNames: () => ts.sys.useCaseSensitiveFileNames,
+  };
+}
+
+export function withMacroApiModuleResolution(baseHost: ts.CompilerHost): ts.CompilerHost {
+  return {
+    ...baseHost,
+    resolveModuleNames(
+      moduleNames: string[],
+      containingFile: string,
+      reusedNames?: string[],
+      redirectedReference?: ts.ResolvedProjectReference,
+      options?: ts.CompilerOptions,
+    ): (ts.ResolvedModule | undefined)[] {
+      const fallbackHost = createModuleResolutionHost(baseHost);
+      const delegated = baseHost.resolveModuleNames?.(
+        moduleNames,
+        containingFile,
+        reusedNames,
+        redirectedReference,
+        options ?? {},
+      );
+
+      return moduleNames.map((moduleName, index) => {
+        if (moduleName === MACRO_API_MODULE_SPECIFIER) {
+          return {
+            resolvedFileName: MACRO_API_MODULE_FILE,
+            extension: ts.Extension.Dts,
+            isExternalLibraryImport: true,
+          };
+        }
+
+        if (delegated?.[index]) {
+          return delegated[index];
+        }
+
+        const resolved = ts.resolveModuleName(
+          moduleName,
+          containingFile,
+          options ?? {},
+          fallbackHost,
+          undefined,
+          redirectedReference,
+        );
+        return resolved.resolvedModule;
+      });
+    },
+  };
+}

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

@@ -0,0 +1,272 @@
+import ts from 'typescript';
+import { createHostAccess, createMacroContext } from './macro_context.js';
+import { getLoadedMacroDefinitionMetadata } from './macro_api_internal.js';
+import { parseMacroSyntaxNodeForDefinition, validateMacroInvocationSignature, } from './macro_definition_support.js';
+import { createMacroError, MacroError } from './macro_errors.js';
+import { isMacroOutput, isMacroValueRewriteOutput } from './macro_output.js';
+import { createAdvancedMacroContext } from './macro_advanced_context.js';
+import { synthesizeHostNode } from './macro_host_ast_internal.js';
+import { createMacroRuntimeImportResolver } from './macro_runtime_support.js';
+import { parseSingleHostStatement } from './macro_host_ast_internal.js';
+export function lowerMacroOutput(output) {
+    switch (output.kind) {
+        case 'expr':
+            return {
+                kind: 'expr',
+                node: output.node,
+                runtimeImports: output.runtimeImports,
+            };
+        case 'stmt':
+            return {
+                kind: 'stmt',
+                nodes: output.nodes,
+                runtimeImports: output.runtimeImports,
+            };
+        case 'scope_exit':
+            return {
+                cleanupStatements: output.cleanupStatements,
+                kind: 'scope_exit',
+                runtimeImports: output.runtimeImports,
+            };
+        case 'value_rewrite':
+            throw new Error('Value-rewrite macro outputs must be handled by the advanced macro adapter.');
+    }
+}
+export function createExpandMacroPlaceholderFromDefinition(definition, macroName, preparedProgram) {
+    return (resolved) => {
+        try {
+            const definitionMetadata = getLoadedMacroDefinitionMetadata(definition);
+            const expansionMode = definitionMetadata?.expansionMode ?? definition.expansionMode ??
+                'replace';
+            const runtimeResolver = preparedProgram && definitionMetadata?.moduleFileName
+                ? createMacroRuntimeImportResolver(preparedProgram, resolved.placeholder.invocation.fileName, definitionMetadata.moduleFileName)
+                : null;
+            const compilerHost = preparedProgram?.preparedHost.host;
+            const hostAccess = preparedProgram && definitionMetadata?.moduleFileName
+                ? createHostAccess({
+                    env: compilerHost?.soundscriptEnvSnapshot?.(),
+                    fileExists: preparedProgram.preparedHost.host.fileExists.bind(preparedProgram.preparedHost.host),
+                    macroFileName: definitionMetadata.moduleFileName,
+                    projectDirectory: preparedProgram.preparedHost.host.getCurrentDirectory?.() ??
+                        ts.sys.getCurrentDirectory(),
+                    readBytes: compilerHost?.soundscriptReadBytes?.bind(compilerHost),
+                    readFile: preparedProgram.preparedHost.host.readFile.bind(preparedProgram.preparedHost.host),
+                })
+                : undefined;
+            const baseContext = preparedProgram
+                ? createAdvancedMacroContext(preparedProgram, resolved, undefined, runtimeResolver, hostAccess)
+                : createUnsupportedAdvancedContext(createMacroContext(resolved, runtimeResolver));
+            const decodedSignature = validateMacroInvocationSignature(definition, baseContext);
+            validateDeclarationMacroPlacement(resolved, baseContext);
+            const parsedSyntax = parseMacroSyntaxNodeForDefinition(definition, baseContext);
+            const context = {
+                ...baseContext,
+                parsedSyntax() {
+                    return parsedSyntax;
+                },
+            };
+            const output = definition.expand(context, decodedSignature);
+            if (!isMacroOutput(output)) {
+                throw new Error(`Macro "${macroName}" must return a value created by ctx.output.expr(...), ctx.output.stmt(...), ctx.output.stmts(...), ctx.controlFlow.rewriteWithValue(...), or ctx.controlFlow.deferCleanup(...).`);
+            }
+            if (isMacroValueRewriteOutput(output)) {
+                return undefined;
+            }
+            const lowered = lowerMacroOutput(output);
+            if (resolved.placeholder.invocation.declarationSpan && expansionMode === 'augment') {
+                return augmentDeclarationExpansion(resolved, baseContext, lowered);
+            }
+            return lowered;
+        }
+        catch (error) {
+            if (error instanceof MacroError) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw createMacroError(resolved, message);
+        }
+    };
+}
+function collectDeclaredNamesFromBindingName(bindingName, names) {
+    if (ts.isIdentifier(bindingName)) {
+        names.add(bindingName.text);
+        return;
+    }
+    for (const element of bindingName.elements) {
+        if (ts.isOmittedExpression(element)) {
+            continue;
+        }
+        collectDeclaredNamesFromBindingName(element.name, names);
+    }
+}
+function collectPrimaryStatementNames(statement) {
+    if ((ts.isClassDeclaration(statement) ||
+        ts.isFunctionDeclaration(statement) ||
+        ts.isInterfaceDeclaration(statement) ||
+        ts.isTypeAliasDeclaration(statement) ||
+        ts.isEnumDeclaration(statement) ||
+        ts.isModuleDeclaration(statement)) &&
+        statement.name) {
+        return [statement.name.text];
+    }
+    if (ts.isVariableStatement(statement)) {
+        const names = new Set();
+        for (const declaration of statement.declarationList.declarations) {
+            collectDeclaredNamesFromBindingName(declaration.name, names);
+        }
+        return [...names];
+    }
+    return [];
+}
+function augmentDeclarationExpansion(resolved, ctx, lowered) {
+    if (lowered.kind !== 'stmt') {
+        throw createMacroError(resolved, `${ctx.name} declaration macros with expansionMode "augment" must emit statements.`);
+    }
+    const declarationName = resolved.placeholder.invocation.declarationName;
+    if (declarationName) {
+        const duplicate = lowered.nodes.find((statement) => collectPrimaryStatementNames(statement).includes(declarationName));
+        if (duplicate) {
+            throw createMacroError(resolved, `${ctx.name} declaration macros with expansionMode "augment" cannot emit a declaration named "${declarationName}" because the original declaration is preserved.`);
+        }
+    }
+    const preservedDeclaration = synthesizeHostNode(parseSingleHostStatement(resolved.placeholder.invocation.fileName, 'macro_augment_decl', ctx.syntax.declaration().text(), `${ctx.name} declaration macros with expansionMode "augment" must preserve a valid declaration.`));
+    if (resolved.placeholder.invocation.preserveDeclaration === false) {
+        return lowered;
+    }
+    return {
+        ...lowered,
+        nodes: [
+            preservedDeclaration,
+            ...lowered.nodes,
+        ],
+    };
+}
+function validateDeclarationMacroPlacement(resolved, ctx) {
+    if (!resolved.placeholder.invocation.declarationSpan) {
+        return;
+    }
+    const parent = resolved.callExpression.parent;
+    if (ts.isExpressionStatement(parent) && ts.isSourceFile(parent.parent)) {
+        return;
+    }
+    ctx.error(`${ctx.name} declaration macros currently only support module-scope declarations.`);
+}
+function createUnsupportedAdvancedContext(baseContext) {
+    return {
+        ...baseContext,
+        controlFlow: {
+            deferCleanup() {
+                throw new Error('This macro requires advanced control-flow support, but no prepared program was available.');
+            },
+            freshBinding() {
+                throw new Error('This macro requires advanced control-flow support, but no prepared program was available.');
+            },
+            placement() {
+                throw new Error('This macro requires advanced control-flow support, but no prepared program was available.');
+            },
+            rewriteWithValue() {
+                throw new Error('This macro requires advanced control-flow support, but no prepared program was available.');
+            },
+        },
+        reflect: {
+            declarationShape() {
+                throw new Error('This macro requires declaration/type reflection, but no prepared program was available.');
+            },
+            typeShape() {
+                throw new Error('This macro requires declaration/type reflection, but no prepared program was available.');
+            },
+        },
+        semantics: {
+            argExpanded() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            argType() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            awaitedType() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            classDeclarationOfType() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            classifyCanonicalFailureType() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            classifyCanonicalResultCarrierType() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            classifyCanonicalResultType() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            classifyTryCarrierType() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            exprType() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            enclosingFunction() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            enclosingFunctionCanonicalResult() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            finiteCases() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            isAssignable() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            localDeclarationHasAnnotation() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            nullType() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            parameterType() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            primaryExprEnclosingFunction() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            primaryExprEnclosingFunctionCanonicalResult() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            primaryExprExpanded() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            primaryExprPrelude() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            primaryExprCanonicalResultCarrier() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            primaryExprCanonicalResult() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            primaryExprContainsMacroInvocations() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            primaryExprTryCarrier() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            primaryExprType() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            readSet() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            undefinedType() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            valueBindingCallableInScope() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            valueBindingInScope() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+            writeSet() {
+                throw new Error('This macro requires semantic queries, but no prepared program was available.');
+            },
+        },
+    };
+}