@soundscript/soundscript 0.1.12 → 0.1.15

package/project-transform/src/public_macro_api/macro_semantic_types.d.ts

@@ -0,0 +1,66 @@
+import type { SourceSpan } from './macro_types.d.ts';
+export interface MacroType {
+    readonly displayText: string;
+}
+export type MacroRuntimeKind = 'bigint' | 'boolean' | 'function' | 'number' | 'object' | 'string' | 'symbol' | 'undefined';
+export type MacroFiniteCase = {
+    readonly elements: readonly MacroFiniteTupleElement[];
+    readonly exactLength: number;
+    readonly kind: 'array';
+} | {
+    readonly kind: 'class';
+    readonly className: string;
+} | {
+    readonly kind: 'literal';
+    readonly code: string;
+} | {
+    readonly kind: 'object';
+    readonly properties: readonly MacroFiniteObjectProperty[];
+} | {
+    readonly kind: 'runtime';
+    readonly typeName: MacroRuntimeKind;
+};
+export interface MacroFiniteObjectProperty {
+    readonly finiteCase: MacroFiniteCase | null;
+    readonly key: string;
+}
+export interface MacroFiniteTupleElement {
+    readonly finiteCase: MacroFiniteCase | null;
+}
+export interface MacroFunctionContext {
+    readonly fileName: string;
+    readonly isAsync: boolean;
+    readonly isGenerator: boolean;
+    readonly name?: string;
+    readonly returnType: MacroType;
+    readonly span: SourceSpan;
+}
+export interface MacroDependencyReference {
+    readonly kind: 'binding' | 'this-member';
+    readonly name: string;
+}
+export interface MacroDependencySet {
+    readonly dependencies: readonly MacroDependencyReference[];
+    readonly unknown: boolean;
+}
+export interface CanonicalResultInfo {
+    readonly errType: MacroType;
+    readonly okType: MacroType;
+    readonly resultType: MacroType;
+}
+export interface CanonicalResultCarrierInfo extends CanonicalResultInfo {
+    readonly requiresAwait: boolean;
+}
+export interface CanonicalFailureInfo {
+    readonly failureType: MacroType;
+}
+export interface MacroTryResultCarrierInfo extends CanonicalResultInfo {
+    readonly kind: 'result';
+}
+export interface MacroTryNullishCarrierInfo {
+    readonly carrierType: MacroType;
+    readonly kind: 'nullish';
+    readonly nullishKinds: readonly ('null' | 'undefined')[];
+    readonly valueType: MacroType;
+}
+export type MacroTryCarrierInfo = MacroTryNullishCarrierInfo | MacroTryResultCarrierInfo;

package/project-transform/src/public_macro_api/macro_types.d.ts

@@ -0,0 +1,70 @@
+export interface SourceSpan {
+    fileName: string;
+    start: number;
+    end: number;
+}
+export type HashKind = 'macro-start' | 'private-name';
+export interface ScannedHash {
+    kind: HashKind;
+    nameText: string;
+    span: SourceSpan;
+}
+export type HashDiagnosticReason = 'not-followed-by-identifier' | 'illegal-context';
+export interface HashDiagnostic {
+    fileName: string;
+    reason: HashDiagnosticReason;
+    span: SourceSpan;
+}
+export interface ScanResult {
+    diagnostics: readonly HashDiagnostic[];
+    hashes: readonly ScannedHash[];
+}
+export type ParsedMacroInvocationKind = 'block' | 'arglist' | 'arglist+block' | 'decl' | 'arglist+decl';
+export type ParsedMacroDeclarationKind = 'class' | 'function' | 'interface' | 'typeAlias';
+export type ParsedMacroArgument = {
+    kind: 'ExprArg';
+    span: SourceSpan;
+} | {
+    kind: 'BlockArg';
+    span: SourceSpan;
+};
+export interface ParsedMacroInvocation {
+    argumentSpans: readonly ParsedMacroArgument[];
+    declarationKind?: ParsedMacroDeclarationKind;
+    declarationName?: string | null;
+    declarationSpan?: SourceSpan;
+    fileName: string;
+    hashSpan: SourceSpan;
+    nameSpan: SourceSpan;
+    nameText: string;
+    span: SourceSpan;
+    trailingBlockSpan?: SourceSpan;
+    invocationKind: ParsedMacroInvocationKind;
+    rewriteKind: 'expr' | 'stmt';
+}
+export type MacroParseDiagnosticReason = 'missing-macro-name' | 'unterminated-arglist' | 'unterminated-block' | 'missing-expression' | 'unexpected-token';
+export interface MacroParseDiagnostic {
+    fileName: string;
+    reason: MacroParseDiagnosticReason;
+    span: SourceSpan;
+}
+export interface MacroGeneratedSpan {
+    generatedEnd: number;
+    generatedFileName: string;
+    generatedStart: number;
+    id: number;
+    originalSpan: SourceSpan;
+}
+export interface MacroReplacement {
+    id: number;
+    originalSpan: SourceSpan;
+    rewriteText: string;
+    rewrittenSpan: SourceSpan;
+}
+export interface RewriteResult {
+    diagnostics: readonly (HashDiagnostic | MacroParseDiagnostic)[];
+    generatedSpans: readonly MacroGeneratedSpan[];
+    macrosById: ReadonlyMap<number, ParsedMacroInvocation>;
+    replacements: readonly MacroReplacement[];
+    rewrittenText: string;
+}

package/project-transform/src/run_program.js

@@ -0,0 +1,14 @@
+import { formatDiagnostics, hasErrorDiagnostics, } from './checker/diagnostics.js';
+import { analyzeProject } from './checker/analyze_project.js';
+export function runProgram(options) {
+    const analysis = analyzeProject({
+        projectPath: options.projectPath,
+        target: options.target,
+        workingDirectory: options.workingDirectory,
+    });
+    return {
+        diagnostics: analysis.diagnostics,
+        output: formatDiagnostics(analysis.diagnostics, options.workingDirectory),
+        exitCode: hasErrorDiagnostics(analysis.diagnostics) ? 1 : 0,
+    };
+}

package/project-transform/src/run_program.ts

@@ -0,0 +1,33 @@
+import {
+  formatDiagnostics,
+  hasErrorDiagnostics,
+  type MergedDiagnostic,
+} from './checker/diagnostics.ts';
+import { analyzeProject } from './checker/analyze_project.ts';
+import type { RuntimeTarget } from './config.ts';
+
+export interface RunProgramOptions {
+  projectPath: string;
+  target?: RuntimeTarget;
+  workingDirectory: string;
+}
+
+export interface RunProgramResult {
+  diagnostics: MergedDiagnostic[];
+  output: string;
+  exitCode: number;
+}
+
+export function runProgram(options: RunProgramOptions): RunProgramResult {
+  const analysis = analyzeProject({
+    projectPath: options.projectPath,
+    target: options.target,
+    workingDirectory: options.workingDirectory,
+  });
+
+  return {
+    diagnostics: analysis.diagnostics,
+    output: formatDiagnostics(analysis.diagnostics, options.workingDirectory),
+    exitCode: hasErrorDiagnostics(analysis.diagnostics) ? 1 : 0,
+  };
+}

package/project-transform/src/runtime/materialize.js

@@ -0,0 +1,371 @@
+import { dirname, extname, join, relative } from '../platform/path.js';
+import ts from 'typescript';
+import { createSoundStdlibCompilerHost } from '../bundled/sound_stdlib.js';
+import { formatDiagnostics, hasErrorDiagnostics, toMergedDiagnostic, } from '../checker/diagnostics.js';
+import { analyzeProject } from '../checker/analyze_project.js';
+import { collectSoundscriptRootNames, getConfigFileParsingDiagnostics, loadConfig, } from '../config.js';
+import { createBuiltinExpandedProgram } from '../frontend/builtin_macro_support.js';
+import { MacroError } from '../frontend/macro_errors.js';
+import { isSoundscriptSourceFile } from '../frontend/project_frontend.js';
+import { copyFile, createSymlink, directoryExistsSync, fileExistsSync, makeDirectory, readDirectory, readLink, readTextFileSync, removePath, writeTextFile, } from '../platform/host.js';
+import { inlineSourceMapComment, stripTrailingSourceMapComment } from './source_maps.js';
+import { transpileTypeScriptModuleToEsm } from './transform.js';
+const PROJECT_CONFIG_CANDIDATES = ['tsconfig.soundscript.json', 'tsconfig.json'];
+const LOCAL_CODE_EXTENSIONS = [
+    '.sts',
+    '.ts',
+    '.tsx',
+    '.mts',
+    '.cts',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+];
+const LOCAL_ASSET_EXTENSIONS = ['.json', '.css', '.wasm'];
+async function copyDirectory(sourcePath, destinationPath) {
+    await makeDirectory(destinationPath);
+    for (const entry of await readDirectory(sourcePath)) {
+        const sourceEntryPath = join(sourcePath, entry.name);
+        const destinationEntryPath = join(destinationPath, entry.name);
+        if (entry.isDirectory) {
+            await copyDirectory(sourceEntryPath, destinationEntryPath);
+        }
+        else if (entry.isFile) {
+            await copyFile(sourceEntryPath, destinationEntryPath);
+        }
+        else if (entry.isSymlink) {
+            const targetPath = await readLink(sourceEntryPath);
+            await createSymlink(targetPath, destinationEntryPath, 'dir');
+        }
+    }
+}
+async function ensureRuntimePackageBoundary(outDir) {
+    await writeTextFile(join(outDir, 'package.json'), `${JSON.stringify({ private: true, type: 'module' }, null, 2)}\n`);
+}
+function findNearestRuntimeNodeModules(projectRoot) {
+    let currentDirectory = projectRoot;
+    while (true) {
+        const sourceNodeModules = join(currentDirectory, 'node_modules');
+        if (fileExistsSync(join(sourceNodeModules, '@soundscript', 'soundscript', 'package.json'))) {
+            return sourceNodeModules;
+        }
+        const parentDirectory = dirname(currentDirectory);
+        if (parentDirectory === currentDirectory) {
+            return undefined;
+        }
+        currentDirectory = parentDirectory;
+    }
+}
+async function ensureRuntimeNodeModules(projectRoot, outDir) {
+    const sourceNodeModules = findNearestRuntimeNodeModules(projectRoot);
+    if (!sourceNodeModules) {
+        return {
+            source: 'cli',
+            code: 'SOUNDSCRIPT_RUNTIME_PACKAGE_MISSING',
+            category: 'error',
+            message: 'Could not find @soundscript/soundscript in node_modules for runtime execution.',
+            filePath: projectRoot,
+            line: 1,
+            column: 1,
+            endLine: 1,
+            endColumn: 1,
+            hint: 'Install @soundscript/soundscript in this project or an ancestor workspace before using soundscript node or soundscript deno.',
+        };
+    }
+    const targetNodeModules = join(outDir, 'node_modules');
+    try {
+        await createSymlink(sourceNodeModules, targetNodeModules, 'dir');
+    }
+    catch {
+        await copyDirectory(sourceNodeModules, targetNodeModules);
+    }
+    return null;
+}
+function findNearestProjectPath(startPath) {
+    const initialDirectory = fileExistsSync(startPath) ? dirname(startPath) : startPath;
+    let currentDirectory = initialDirectory;
+    while (true) {
+        for (const candidate of PROJECT_CONFIG_CANDIDATES) {
+            const projectPath = join(currentDirectory, candidate);
+            if (fileExistsSync(projectPath)) {
+                return projectPath;
+            }
+        }
+        const parentDirectory = dirname(currentDirectory);
+        if (parentDirectory === currentDirectory) {
+            return undefined;
+        }
+        currentDirectory = parentDirectory;
+    }
+}
+function isRelativeOrAbsoluteSpecifier(specifier) {
+    return specifier.startsWith('./') || specifier.startsWith('../') || specifier.startsWith('/');
+}
+function normalizeLocalSpecifierPath(path) {
+    return path.replaceAll('\\', '/');
+}
+function toRuntimeCodeOutputPath(projectRoot, sourceFileName, outDir) {
+    const relativePath = normalizeLocalSpecifierPath(relative(projectRoot, sourceFileName));
+    const safeRelativePath = relativePath.startsWith('..')
+        ? sourceFileName.split(/[\\/]/u).at(-1) ?? sourceFileName
+        : relativePath;
+    const extension = extname(safeRelativePath);
+    return join(outDir, extension.length > 0
+        ? `${safeRelativePath.slice(0, -extension.length)}.js`
+        : `${safeRelativePath}.js`);
+}
+function toRuntimeAssetOutputPath(projectRoot, sourceFileName, outDir) {
+    const relativePath = normalizeLocalSpecifierPath(relative(projectRoot, sourceFileName));
+    const safeRelativePath = relativePath.startsWith('..')
+        ? sourceFileName.split(/[\\/]/u).at(-1) ?? sourceFileName
+        : relativePath;
+    return join(outDir, safeRelativePath);
+}
+function collectModuleSpecifiers(sourceText, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true);
+    const specifiers = [];
+    function pushSpecifier(specifier) {
+        specifiers.push(specifier.text);
+    }
+    function visit(node) {
+        if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+            node.moduleSpecifier &&
+            ts.isStringLiteralLike(node.moduleSpecifier)) {
+            pushSpecifier(node.moduleSpecifier);
+        }
+        else if (ts.isCallExpression(node) &&
+            node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+            node.arguments.length >= 1 &&
+            ts.isStringLiteralLike(node.arguments[0])) {
+            pushSpecifier(node.arguments[0]);
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return specifiers;
+}
+function resolvePathWithExtensions(basePath) {
+    for (const extension of LOCAL_CODE_EXTENSIONS) {
+        const candidate = `${basePath}${extension}`;
+        if (fileExistsSync(candidate)) {
+            return candidate;
+        }
+    }
+    for (const extension of LOCAL_ASSET_EXTENSIONS) {
+        const candidate = `${basePath}${extension}`;
+        if (fileExistsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function resolveLocalDependency(containingFileName, specifier) {
+    if (!isRelativeOrAbsoluteSpecifier(specifier)) {
+        return undefined;
+    }
+    const containingDirectory = dirname(containingFileName);
+    const candidateBase = specifier.startsWith('/')
+        ? specifier
+        : join(containingDirectory, specifier);
+    if (fileExistsSync(candidateBase)) {
+        return candidateBase;
+    }
+    const directMatch = resolvePathWithExtensions(candidateBase);
+    if (directMatch) {
+        return directMatch;
+    }
+    if (directoryExistsSync(candidateBase)) {
+        const indexMatch = resolvePathWithExtensions(join(candidateBase, 'index'));
+        if (indexMatch) {
+            return indexMatch;
+        }
+    }
+    return undefined;
+}
+function isRuntimeCodeFile(fileName) {
+    return LOCAL_CODE_EXTENSIONS.some((extension) => fileName.endsWith(extension));
+}
+function isRuntimeAssetFile(fileName) {
+    return LOCAL_ASSET_EXTENSIONS.some((extension) => fileName.endsWith(extension));
+}
+function createRuntimeMacroDiagnostic(error) {
+    return {
+        source: 'cli',
+        code: error.code,
+        category: 'error',
+        message: error.message,
+        filePath: error.filePath,
+        line: error.line,
+        column: error.column,
+        endLine: error.endLine,
+        endColumn: error.endColumn,
+    };
+}
+function createExpandedProgram(projectPath) {
+    const loadedConfig = loadConfig(projectPath);
+    const soundscriptRootNames = collectSoundscriptRootNames(projectPath, loadedConfig);
+    return createBuiltinExpandedProgram({
+        baseHost: createSoundStdlibCompilerHost(loadedConfig.commandLine.options, dirname(projectPath)),
+        configFileParsingDiagnostics: getConfigFileParsingDiagnostics(loadedConfig.diagnostics, soundscriptRootNames),
+        options: loadedConfig.commandLine.options,
+        projectReferences: loadedConfig.commandLine.projectReferences,
+        rootNames: [...new Set([...loadedConfig.commandLine.fileNames, ...soundscriptRootNames])],
+    });
+}
+function transpileExpandedSoundscriptModuleToEsm(expandedProgram, sourceFileName, outputPath) {
+    const programFileName = expandedProgram.preparedProgram.toProgramFileName(sourceFileName);
+    const expandedSourceFile = expandedProgram.program.getSourceFile(programFileName);
+    if (!expandedSourceFile) {
+        throw new Error(`Missing expanded source file for ${sourceFileName}.`);
+    }
+    const printer = ts.createPrinter();
+    return transpileTypeScriptModuleToEsm(sourceFileName, outputPath, printer.printFile(expandedSourceFile), {
+        module: ts.ModuleKind.ES2022,
+        target: ts.ScriptTarget.ES2022,
+    });
+}
+export async function materializeRuntimeGraph(options) {
+    if (options.entryPaths.length === 0) {
+        const diagnostics = [{
+                source: 'cli',
+                code: 'SOUNDSCRIPT_RUNTIME_NO_ENTRY',
+                category: 'error',
+                message: 'No entry file was provided for runtime materialization.',
+                filePath: options.workingDirectory,
+                line: 1,
+                column: 1,
+                endLine: 1,
+                endColumn: 1,
+            }];
+        return {
+            diagnostics,
+            exitCode: 1,
+            output: formatDiagnostics(diagnostics, options.workingDirectory),
+        };
+    }
+    const entryProjectPath = options.projectPath ??
+        findNearestProjectPath(options.entryPaths[0]);
+    if (!entryProjectPath) {
+        const diagnostics = [{
+                source: 'cli',
+                code: 'SOUNDSCRIPT_RUNTIME_NO_PROJECT',
+                category: 'error',
+                message: 'Could not find a tsconfig.soundscript.json or tsconfig.json for the runtime entry.',
+                filePath: options.entryPaths[0],
+                line: 1,
+                column: 1,
+                endLine: 1,
+                endColumn: 1,
+            }];
+        return {
+            diagnostics,
+            exitCode: 1,
+            output: formatDiagnostics(diagnostics, options.workingDirectory),
+        };
+    }
+    const analysis = analyzeProject({
+        projectPath: entryProjectPath,
+        workingDirectory: options.workingDirectory,
+    });
+    if (hasErrorDiagnostics(analysis.diagnostics)) {
+        return {
+            diagnostics: analysis.diagnostics,
+            exitCode: 1,
+            output: formatDiagnostics(analysis.diagnostics, options.workingDirectory),
+        };
+    }
+    const expandedProgram = createExpandedProgram(entryProjectPath);
+    const frontendDiagnostics = [
+        ...expandedProgram.frontendDiagnostics(),
+        ...ts.getPreEmitDiagnostics(expandedProgram.program).map(toMergedDiagnostic),
+    ];
+    if (hasErrorDiagnostics(frontendDiagnostics)) {
+        return {
+            diagnostics: frontendDiagnostics,
+            exitCode: 1,
+            output: formatDiagnostics(frontendDiagnostics, options.workingDirectory),
+        };
+    }
+    try {
+        void expandedProgram.program.getTypeChecker();
+    }
+    catch (error) {
+        const diagnostics = error instanceof MacroError ? [createRuntimeMacroDiagnostic(error)] : [];
+        return {
+            diagnostics,
+            exitCode: 1,
+            output: error instanceof MacroError
+                ? formatDiagnostics(diagnostics, options.workingDirectory)
+                : String(error),
+        };
+    }
+    await removePath(options.outDir);
+    await makeDirectory(options.outDir);
+    const emittedFiles = [];
+    const writtenSourceFiles = new Set();
+    const projectRoot = dirname(entryProjectPath);
+    await ensureRuntimePackageBoundary(options.outDir);
+    emittedFiles.push(join(options.outDir, 'package.json'));
+    const runtimePackageDiagnostic = await ensureRuntimeNodeModules(projectRoot, options.outDir);
+    if (runtimePackageDiagnostic) {
+        return {
+            diagnostics: [runtimePackageDiagnostic],
+            exitCode: 1,
+            output: formatDiagnostics([runtimePackageDiagnostic], options.workingDirectory),
+        };
+    }
+    const queue = [...options.entryPaths];
+    const visited = new Set();
+    const entryOutputPaths = [];
+    while (queue.length > 0) {
+        const sourceFileName = queue.shift();
+        if (visited.has(sourceFileName)) {
+            continue;
+        }
+        visited.add(sourceFileName);
+        if (isRuntimeAssetFile(sourceFileName)) {
+            const outputPath = toRuntimeAssetOutputPath(projectRoot, sourceFileName, options.outDir);
+            await makeDirectory(dirname(outputPath));
+            await copyFile(sourceFileName, outputPath);
+            emittedFiles.push(outputPath);
+            continue;
+        }
+        if (!isRuntimeCodeFile(sourceFileName)) {
+            continue;
+        }
+        const sourceText = readTextFileSync(sourceFileName);
+        const outputPath = toRuntimeCodeOutputPath(projectRoot, sourceFileName, options.outDir);
+        const artifact = isSoundscriptSourceFile(sourceFileName)
+            ? transpileExpandedSoundscriptModuleToEsm(expandedProgram, sourceFileName, outputPath)
+            : transpileTypeScriptModuleToEsm(sourceFileName, outputPath, sourceText, {
+                module: ts.ModuleKind.ES2022,
+                target: ts.ScriptTarget.ES2022,
+            });
+        await makeDirectory(dirname(outputPath));
+        await writeTextFile(outputPath, `${stripTrailingSourceMapComment(artifact.code)}\n${inlineSourceMapComment(artifact.mapText)}\n`);
+        emittedFiles.push(outputPath);
+        writtenSourceFiles.add(sourceFileName);
+        if (options.entryPaths.includes(sourceFileName)) {
+            entryOutputPaths.push(outputPath);
+        }
+        for (const specifier of collectModuleSpecifiers(sourceText, sourceFileName)) {
+            const dependencyPath = resolveLocalDependency(sourceFileName, specifier);
+            if (!dependencyPath || writtenSourceFiles.has(dependencyPath)) {
+                continue;
+            }
+            queue.push(dependencyPath);
+        }
+    }
+    return {
+        artifacts: {
+            emittedFiles,
+            entryOutputPaths,
+            outDir: options.outDir,
+            projectPath: entryProjectPath,
+        },
+        diagnostics: [],
+        exitCode: 0,
+        output: '',
+    };
+}