@soundscript/soundscript 0.1.13 → 0.1.15

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

@@ -0,0 +1,99 @@
+import ts from 'typescript';
+import { getLoadedMacroDefinitionMetadata } from './macro_api_internal.js';
+import { collectResolvedMacroPlaceholders } from './macro_resolver.js';
+function toGeneratedSpan(fileName, replacement) {
+    return replacement
+        ? {
+            fileName,
+            start: replacement.rewrittenSpan.start,
+            end: replacement.rewrittenSpan.end,
+        }
+        : undefined;
+}
+export function createMacroDebugSnapshot(options) {
+    const sourceFileName = options.preparedProgram.toSourceFileName(options.filePath);
+    const preparedSource = options.preparedProgram.preparedHost.getPreparedSourceFile(sourceFileName);
+    if (!preparedSource) {
+        return null;
+    }
+    const printer = ts.createPrinter();
+    const programFileName = options.preparedProgram.toProgramFileName(sourceFileName);
+    const programSourceFile = options.program.getSourceFile(programFileName);
+    if (!programSourceFile) {
+        return null;
+    }
+    const debugPreparedSource = options.diagnosticPreparedFiles.get(sourceFileName) ?? preparedSource;
+    const definitions = options.macroEnvironment.definitionsForFile(programSourceFile);
+    const registries = options.macroEnvironment.registriesForFile(programSourceFile);
+    const generatedReplacementsById = new Map(debugPreparedSource.rewriteResult.replacements.map((replacement) => [replacement.id, replacement]));
+    const traces = collectResolvedMacroPlaceholders(options.preparedProgram)
+        .filter((entry) => options.preparedProgram.toSourceFileName(entry.sourceFile.fileName) === sourceFileName)
+        .map((entry) => {
+        const invocation = entry.resolved.placeholder.invocation;
+        const definition = definitions.get(invocation.nameText);
+        const metadata = definition ? getLoadedMacroDefinitionMetadata(definition) : null;
+        let runtimeImports = [];
+        const diagnostics = [];
+        try {
+            const advancedExpander = registries.advancedRegistry.get(invocation.nameText);
+            if (advancedExpander) {
+                const advancedExpansion = advancedExpander(entry.resolved, {
+                    advanced: registries.advancedRegistry,
+                    rewrite: registries.registry,
+                });
+                if (advancedExpansion) {
+                    runtimeImports = advancedExpansion.runtimeImports ?? [];
+                }
+                else {
+                    runtimeImports = registries.registry.get(invocation.nameText)?.(entry.resolved)?.runtimeImports ??
+                        [];
+                }
+            }
+            else {
+                runtimeImports = registries.registry.get(invocation.nameText)?.(entry.resolved)?.runtimeImports ?? [];
+            }
+        }
+        catch (error) {
+            diagnostics.push(error instanceof Error ? error.message : String(error));
+        }
+        return {
+            declarationTarget: invocation.declarationSpan && invocation.declarationKind
+                ? {
+                    declarationKind: invocation.declarationKind,
+                    name: invocation.declarationName ?? null,
+                    span: invocation.declarationSpan,
+                }
+                : undefined,
+            definingModuleFileName: metadata?.moduleFileName,
+            definingModuleSpecifier: metadata?.moduleSpecifier,
+            diagnostics,
+            generatedSpan: toGeneratedSpan(sourceFileName, generatedReplacementsById.get(entry.resolved.placeholder.id)),
+            invocationId: entry.resolved.placeholder.id,
+            macroForm: metadata?.form ?? (invocation.siteKind === 'annotation'
+                ? 'decl'
+                : invocation.siteKind),
+            macroName: invocation.nameText,
+            runtimeImports,
+            sourceSpan: invocation.span,
+        };
+    });
+    return {
+        expandedText: printer.printFile(programSourceFile),
+        preparedText: preparedSource.rewrittenText,
+        projectedText: debugPreparedSource.rewrittenText,
+        rewriteText: preparedSource.rewriteResult.rewrittenText,
+        traces,
+    };
+}
+export function readMacroDebugStageText(snapshot, stage) {
+    switch (stage) {
+        case 'rewrite':
+            return snapshot.rewriteText;
+        case 'expanded':
+            return snapshot.expandedText;
+        case 'prepared':
+            return snapshot.preparedText;
+        case 'projected':
+            return snapshot.projectedText;
+    }
+}

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

@@ -0,0 +1,157 @@
+import ts from 'typescript';
+
+import type { MacroRuntimeImportRequest } from './macro_output.ts';
+import { getLoadedMacroDefinitionMetadata } from './macro_api_internal.ts';
+import { collectResolvedMacroPlaceholders } from './macro_resolver.ts';
+import type { PreparedProgram, PreparedSourceFile } from './project_frontend.ts';
+import type { ProjectMacroEnvironment } from './project_macro_support.ts';
+import type { SourceSpan } from './macro_types.ts';
+
+export type MacroDebugStage = 'expanded' | 'prepared' | 'projected' | 'rewrite';
+
+export interface MacroExpansionTrace {
+  readonly declarationTarget?: {
+    readonly declarationKind: 'class' | 'function' | 'interface' | 'typeAlias';
+    readonly name: string | null;
+    readonly span: SourceSpan;
+  };
+  readonly definingModuleFileName?: string;
+  readonly definingModuleSpecifier?: string;
+  readonly diagnostics: readonly string[];
+  readonly generatedSpan?: SourceSpan;
+  readonly invocationId: number;
+  readonly macroForm: 'call' | 'decl' | 'tag';
+  readonly macroName: string;
+  readonly runtimeImports: readonly MacroRuntimeImportRequest[];
+  readonly sourceSpan: SourceSpan;
+}
+
+export interface MacroDebugSnapshot {
+  readonly expandedText: string;
+  readonly preparedText: string;
+  readonly projectedText: string;
+  readonly rewriteText: string;
+  readonly traces: readonly MacroExpansionTrace[];
+}
+
+export interface CreateMacroDebugSnapshotOptions {
+  readonly diagnosticPreparedFiles: ReadonlyMap<string, PreparedSourceFile>;
+  readonly filePath: string;
+  readonly macroEnvironment: ProjectMacroEnvironment;
+  readonly preparedProgram: PreparedProgram;
+  readonly program: ts.Program;
+}
+
+function toGeneratedSpan(
+  fileName: string,
+  replacement: PreparedSourceFile['rewriteResult']['replacements'][number] | undefined,
+): SourceSpan | undefined {
+  return replacement
+    ? {
+      fileName,
+      start: replacement.rewrittenSpan.start,
+      end: replacement.rewrittenSpan.end,
+    }
+    : undefined;
+}
+
+export function createMacroDebugSnapshot(
+  options: CreateMacroDebugSnapshotOptions,
+): MacroDebugSnapshot | null {
+  const sourceFileName = options.preparedProgram.toSourceFileName(options.filePath);
+  const preparedSource = options.preparedProgram.preparedHost.getPreparedSourceFile(sourceFileName);
+  if (!preparedSource) {
+    return null;
+  }
+  const printer = ts.createPrinter();
+
+  const programFileName = options.preparedProgram.toProgramFileName(sourceFileName);
+  const programSourceFile = options.program.getSourceFile(programFileName);
+  if (!programSourceFile) {
+    return null;
+  }
+
+  const debugPreparedSource = options.diagnosticPreparedFiles.get(sourceFileName) ?? preparedSource;
+  const definitions = options.macroEnvironment.definitionsForFile(programSourceFile);
+  const registries = options.macroEnvironment.registriesForFile(programSourceFile);
+  const generatedReplacementsById = new Map(
+    debugPreparedSource.rewriteResult.replacements.map((replacement) => [replacement.id, replacement] as const),
+  );
+  const traces = collectResolvedMacroPlaceholders(options.preparedProgram)
+    .filter((entry) => options.preparedProgram.toSourceFileName(entry.sourceFile.fileName) === sourceFileName)
+    .map((entry): MacroExpansionTrace => {
+      const invocation = entry.resolved.placeholder.invocation;
+      const definition = definitions.get(invocation.nameText);
+      const metadata = definition ? getLoadedMacroDefinitionMetadata(definition) : null;
+      let runtimeImports: readonly MacroRuntimeImportRequest[] = [];
+      const diagnostics: string[] = [];
+
+      try {
+        const advancedExpander = registries.advancedRegistry.get(invocation.nameText);
+        if (advancedExpander) {
+          const advancedExpansion = advancedExpander(entry.resolved, {
+            advanced: registries.advancedRegistry,
+            rewrite: registries.registry,
+          });
+          if (advancedExpansion) {
+            runtimeImports = advancedExpansion.runtimeImports ?? [];
+          } else {
+            runtimeImports = registries.registry.get(invocation.nameText)?.(entry.resolved)?.runtimeImports ??
+              [];
+          }
+        } else {
+          runtimeImports = registries.registry.get(invocation.nameText)?.(entry.resolved)?.runtimeImports ?? [];
+        }
+      } catch (error) {
+        diagnostics.push(error instanceof Error ? error.message : String(error));
+      }
+
+      return {
+        declarationTarget: invocation.declarationSpan && invocation.declarationKind
+          ? {
+            declarationKind: invocation.declarationKind,
+            name: invocation.declarationName ?? null,
+            span: invocation.declarationSpan,
+          }
+          : undefined,
+        definingModuleFileName: metadata?.moduleFileName,
+        definingModuleSpecifier: metadata?.moduleSpecifier,
+        diagnostics,
+        generatedSpan: toGeneratedSpan(
+          sourceFileName,
+          generatedReplacementsById.get(entry.resolved.placeholder.id),
+        ),
+        invocationId: entry.resolved.placeholder.id,
+        macroForm: metadata?.form ?? (invocation.siteKind === 'annotation'
+          ? 'decl'
+          : invocation.siteKind),
+        macroName: invocation.nameText,
+        runtimeImports,
+        sourceSpan: invocation.span,
+      };
+    });
+
+  return {
+    expandedText: printer.printFile(programSourceFile),
+    preparedText: preparedSource.rewrittenText,
+    projectedText: debugPreparedSource.rewrittenText,
+    rewriteText: preparedSource.rewriteResult.rewrittenText,
+    traces,
+  };
+}
+
+export function readMacroDebugStageText(
+  snapshot: MacroDebugSnapshot,
+  stage: MacroDebugStage,
+): string {
+  switch (stage) {
+    case 'rewrite':
+      return snapshot.rewriteText;
+    case 'expanded':
+      return snapshot.expandedText;
+    case 'prepared':
+      return snapshot.preparedText;
+    case 'projected':
+      return snapshot.projectedText;
+  }
+}

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

@@ -0,0 +1,28 @@
+import { formatMacroSignature, tryReadMacroSignature } from './macro_api.js';
+export function validateMacroInvocationSignature(definition, ctx) {
+    if (!definition.signature) {
+        return null;
+    }
+    const decoded = tryReadMacroSignature(definition.signature, ctx);
+    if (decoded) {
+        if (definition.signature.validators) {
+            for (const validator of definition.signature.validators) {
+                validator(ctx, decoded);
+            }
+        }
+        return decoded;
+    }
+    return ctx.error(`${ctx.name} only supports: ${formatMacroSignature(definition.signature, ctx.name)}.`);
+}
+export function parseMacroSyntaxNodeForDefinition(definition, ctx) {
+    if (definition.parse) {
+        return definition.parse(ctx);
+    }
+    return null;
+}
+export function fragmentsForMacroDefinition(definition, ctx) {
+    return definition.fragments?.(ctx) ?? [];
+}
+export function analysisRegionForMacroDefinition(definition, ctx) {
+    return definition.analysisRegion?.(ctx) ?? null;
+}

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

@@ -0,0 +1,73 @@
+import type {
+  MacroAnalysisContext,
+  MacroAnalysisRegion,
+  MacroContext,
+  MacroDecodedSignature,
+  MacroDecodedSignatureCase,
+  MacroDefinition,
+  MacroEmbeddedFragment,
+  MacroSignature,
+  MacroSyntaxNode,
+} from './macro_api.ts';
+import { formatMacroSignature, tryReadMacroSignature } from './macro_api.ts';
+
+type SignatureValidationContext = Pick<
+  MacroContext,
+  'declarationSpan' | 'error' | 'hasBlock' | 'invocation' | 'name' | 'syntax'
+> &
+  Partial<MacroContext>;
+
+export function validateMacroInvocationSignature<
+  Signature extends MacroSignature | undefined,
+>(
+  definition: MacroDefinition<Signature>,
+  ctx: SignatureValidationContext,
+): Signature extends MacroSignature ? MacroDecodedSignature<Signature> : null {
+  if (!definition.signature) {
+    return null as Signature extends MacroSignature ? MacroDecodedSignature<Signature> : null;
+  }
+
+  const decoded = tryReadMacroSignature(definition.signature, ctx);
+  if (decoded) {
+    if (definition.signature.validators) {
+      for (const validator of definition.signature.validators) {
+        validator(ctx as MacroContext, decoded);
+      }
+    }
+    return decoded as Signature extends MacroSignature ? MacroDecodedSignature<Signature> : null;
+  }
+
+  return ctx.error(
+    `${ctx.name} only supports: ${formatMacroSignature(definition.signature, ctx.name)}.`,
+  );
+}
+
+export function parseMacroSyntaxNodeForDefinition<
+  Signature extends MacroSignature | undefined,
+>(
+  definition: MacroDefinition<Signature>,
+  ctx: MacroContext,
+): MacroSyntaxNode | null {
+  if (definition.parse) {
+    return definition.parse(ctx);
+  }
+  return null;
+}
+
+export function fragmentsForMacroDefinition<
+  Signature extends MacroSignature | undefined,
+>(
+  definition: MacroDefinition<Signature>,
+  ctx: MacroContext,
+): readonly MacroEmbeddedFragment[] {
+  return definition.fragments?.(ctx) ?? [];
+}
+
+export function analysisRegionForMacroDefinition<
+  Signature extends MacroSignature | undefined,
+>(
+  definition: MacroDefinition<Signature>,
+  ctx: MacroAnalysisContext,
+): MacroAnalysisRegion | null {
+  return definition.analysisRegion?.(ctx) ?? null;
+}

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

@@ -0,0 +1,40 @@
+function getLineAndColumn(text, position) {
+    let line = 1;
+    let column = 1;
+    for (let index = 0; index < position; index += 1) {
+        if (text[index] === '\n') {
+            line += 1;
+            column = 1;
+        }
+        else {
+            column += 1;
+        }
+    }
+    return { column, line };
+}
+export class MacroError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = 'MacroError';
+        this.code = options.code ?? 'SOUNDSCRIPT_MACRO_EXPANSION';
+        this.column = options.column;
+        this.endColumn = options.endColumn;
+        this.endLine = options.endLine;
+        this.filePath = options.filePath;
+        this.line = options.line;
+        this.macroName = options.macroName;
+    }
+}
+export function createMacroError(resolved, message, span = resolved.placeholder.invocation.span) {
+    const originalText = resolved.placeholder.preparedFile.originalText;
+    const start = getLineAndColumn(originalText, span.start);
+    const end = getLineAndColumn(originalText, span.end);
+    return new MacroError(message, {
+        column: start.column,
+        endColumn: end.column,
+        endLine: end.line,
+        filePath: span.fileName,
+        line: start.line,
+        macroName: resolved.placeholder.invocation.nameText,
+    });
+}

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

@@ -0,0 +1,70 @@
+import type { ResolvedMacroPlaceholder } from './macro_resolver.ts';
+import type { SourceSpan } from './macro_types.ts';
+
+function getLineAndColumn(text: string, position: number): { column: number; line: number } {
+  let line = 1;
+  let column = 1;
+
+  for (let index = 0; index < position; index += 1) {
+    if (text[index] === '\n') {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+
+  return { column, line };
+}
+
+export class MacroError extends Error {
+  readonly code: string;
+  readonly column: number;
+  readonly endColumn: number;
+  readonly endLine: number;
+  readonly filePath: string;
+  readonly line: number;
+  readonly macroName: string;
+
+  constructor(
+    message: string,
+    options: {
+      column: number;
+      code?: string;
+      endColumn: number;
+      endLine: number;
+      filePath: string;
+      line: number;
+      macroName: string;
+    },
+  ) {
+    super(message);
+    this.name = 'MacroError';
+    this.code = options.code ?? 'SOUNDSCRIPT_MACRO_EXPANSION';
+    this.column = options.column;
+    this.endColumn = options.endColumn;
+    this.endLine = options.endLine;
+    this.filePath = options.filePath;
+    this.line = options.line;
+    this.macroName = options.macroName;
+  }
+}
+
+export function createMacroError(
+  resolved: ResolvedMacroPlaceholder,
+  message: string,
+  span: SourceSpan = resolved.placeholder.invocation.span,
+): MacroError {
+  const originalText = resolved.placeholder.preparedFile.originalText;
+  const start = getLineAndColumn(originalText, span.start);
+  const end = getLineAndColumn(originalText, span.end);
+
+  return new MacroError(message, {
+    column: start.column,
+    endColumn: end.column,
+    endLine: end.line,
+    filePath: span.fileName,
+    line: start.line,
+    macroName: resolved.placeholder.invocation.nameText,
+  });
+}