@soundscript/soundscript 0.1.13 → 0.1.15

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

@@ -0,0 +1,176 @@
+import ts from 'typescript';
+import { createAnnotationLookup } from '../annotation_syntax.js';
+const MACRO_API_SPECIFIERS = new Set(['sts:macros', '@soundscript/macros']);
+function blankPreservingLines(text) {
+    return text.replace(/[^\r\n]/gu, ' ');
+}
+function macroFactoryAnnotationForNode(sourceFile, node) {
+    const block = createAnnotationLookup(sourceFile).getAttachedAnnotationBlock(node);
+    const annotation = block?.annotations.find((entry) => entry.name === 'macro');
+    const formValue = annotation?.arguments?.[0]?.value;
+    if (!block ||
+        !annotation ||
+        annotation.arguments?.length !== 1 ||
+        annotation.arguments[0]?.kind !== 'positional' ||
+        !formValue ||
+        formValue.kind !== 'identifier' ||
+        (formValue.name !== 'call' && formValue.name !== 'decl' && formValue.name !== 'tag')) {
+        return null;
+    }
+    return {
+        form: formValue.name,
+        span: {
+            fileName: sourceFile.fileName,
+            start: block.range.start,
+            end: block.range.end,
+        },
+    };
+}
+function getFunctionDeclarationExportName(node) {
+    if (!ts.isFunctionDeclaration(node)) {
+        return undefined;
+    }
+    const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+    const isExported = !!modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+    if (!isExported) {
+        return undefined;
+    }
+    const isDefault = !!modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+    if (isDefault) {
+        return 'default';
+    }
+    return node.name?.text;
+}
+function exportedDeclarationNames(statement) {
+    const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
+    const isExported = !!modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+    if (!isExported) {
+        return [];
+    }
+    const isDefault = !!modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+    if (isDefault) {
+        return ['default'];
+    }
+    if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) ||
+        ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) ||
+        ts.isEnumDeclaration(statement)) &&
+        statement.name) {
+        return [statement.name.text];
+    }
+    if (ts.isVariableStatement(statement)) {
+        return statement.declarationList.declarations.flatMap((declaration) => ts.isIdentifier(declaration.name) ? [declaration.name.text] : []);
+    }
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+        return ['default'];
+    }
+    return [];
+}
+export function sourceTextLooksLikeMacroModule(sourceText) {
+    return [...MACRO_API_SPECIFIERS].some((specifier) => sourceText.includes(specifier));
+}
+export function macroSiteKindForFactoryForm(form) {
+    switch (form) {
+        case 'call':
+            return 'call';
+        case 'tag':
+            return 'tag';
+        case 'decl':
+            return 'annotation';
+    }
+}
+export function scanMacroFactoryExports(fileName, sourceText) {
+    const sourceFile = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, /\.(?:[cm]?tsx|jsx|sts)$/iu.test(fileName) ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const exports = new Map();
+    for (const statement of sourceFile.statements) {
+        const exportName = getFunctionDeclarationExportName(statement);
+        if (!exportName || !ts.isFunctionDeclaration(statement)) {
+            continue;
+        }
+        const annotation = macroFactoryAnnotationForNode(sourceFile, statement);
+        if (!annotation) {
+            continue;
+        }
+        exports.set(exportName, {
+            exportName,
+            form: annotation.form,
+            span: {
+                fileName,
+                start: annotation.span.start,
+                end: statement.getEnd(),
+            },
+        });
+    }
+    return exports;
+}
+export function usesLegacyDefineMacroAuthoring(sourceText) {
+    return /\bdefineMacro\s*\(/u.test(sourceText) ||
+        /from ['"]@soundscript\/macros['"]/u.test(sourceText) ||
+        /from ['"]sts:macros['"][^]*\bdefineMacro\b/u.test(sourceText);
+}
+export function stripMacroFactoryAuthoringFromText(fileName, sourceText) {
+    const sourceFile = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, /\.(?:[cm]?tsx|jsx|sts)$/iu.test(fileName) ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const spansToBlank = [];
+    const strippedMacroExportNames = [];
+    for (const statement of sourceFile.statements) {
+        if (ts.isImportDeclaration(statement) &&
+            ts.isStringLiteral(statement.moduleSpecifier) &&
+            MACRO_API_SPECIFIERS.has(statement.moduleSpecifier.text)) {
+            spansToBlank.push({
+                start: statement.getFullStart(),
+                end: statement.getEnd(),
+            });
+            continue;
+        }
+        const exportName = getFunctionDeclarationExportName(statement);
+        if (!exportName || !ts.isFunctionDeclaration(statement)) {
+            continue;
+        }
+        const annotation = macroFactoryAnnotationForNode(sourceFile, statement);
+        if (!annotation) {
+            continue;
+        }
+        spansToBlank.push({
+            start: annotation.span.start,
+            end: statement.getEnd(),
+        });
+        strippedMacroExportNames.push(exportName);
+    }
+    if (spansToBlank.length === 0) {
+        return sourceText;
+    }
+    const originalWasModule = ts.isExternalModule(sourceFile);
+    let stripped = '';
+    let cursor = 0;
+    for (const span of spansToBlank.sort((left, right) => left.start - right.start)) {
+        if (span.start < cursor) {
+            continue;
+        }
+        stripped += sourceText.slice(cursor, span.start);
+        stripped += blankPreservingLines(sourceText.slice(span.start, span.end));
+        cursor = span.end;
+    }
+    stripped += sourceText.slice(cursor);
+    const strippedSourceFile = ts.createSourceFile(fileName, stripped, ts.ScriptTarget.Latest, true, /\.(?:[cm]?tsx|jsx|sts)$/iu.test(fileName) ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const survivingExportNames = new Set(strippedSourceFile.statements.flatMap((statement) => exportedDeclarationNames(statement)));
+    const missingExportNames = strippedMacroExportNames.filter((exportName) => !survivingExportNames.has(exportName));
+    if (missingExportNames.length > 0) {
+        const namedExportNames = missingExportNames.filter((exportName) => exportName !== 'default');
+        const missingDefaultExport = missingExportNames.includes('default');
+        const placeholderStatements = [
+            ...namedExportNames.map((exportName) => `export declare const ${exportName}: unknown;`),
+            ...(missingDefaultExport
+                ? [
+                    'declare const __soundscript_default_macro_export: unknown;',
+                    'export default __soundscript_default_macro_export;',
+                ]
+                : []),
+        ];
+        return `${stripped}\n/* soundscript:macros */\n${placeholderStatements.join('\n')}\n`;
+    }
+    if (!originalWasModule) {
+        return stripped;
+    }
+    return ts.isExternalModule(strippedSourceFile)
+        ? `${stripped}\n/* soundscript:macros */\n`
+        : `${stripped}\n/* soundscript:macros */\nexport {};\n`;
+}

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

@@ -0,0 +1,263 @@
+import ts from 'typescript';
+
+import { createAnnotationLookup } from '../annotation_syntax.ts';
+import type { SourceSpan } from './macro_types.ts';
+
+export type MacroFactoryForm = 'call' | 'decl' | 'tag';
+export type ImportedMacroSiteKind = 'annotation' | 'call' | 'tag';
+
+export interface ScannedMacroFactoryExport {
+  readonly exportName: string;
+  readonly form: MacroFactoryForm;
+  readonly span: SourceSpan;
+}
+
+const MACRO_API_SPECIFIERS = new Set(['sts:macros', '@soundscript/macros']);
+function blankPreservingLines(text: string): string {
+  return text.replace(/[^\r\n]/gu, ' ');
+}
+
+function macroFactoryAnnotationForNode(
+  sourceFile: ts.SourceFile,
+  node: ts.Node,
+): { form: MacroFactoryForm; span: SourceSpan } | null {
+  const block = createAnnotationLookup(sourceFile).getAttachedAnnotationBlock(node);
+  const annotation = block?.annotations.find((entry) => entry.name === 'macro');
+  const formValue = annotation?.arguments?.[0]?.value;
+  if (
+    !block ||
+    !annotation ||
+    annotation.arguments?.length !== 1 ||
+    annotation.arguments[0]?.kind !== 'positional' ||
+    !formValue ||
+    formValue.kind !== 'identifier' ||
+    (formValue.name !== 'call' && formValue.name !== 'decl' && formValue.name !== 'tag')
+  ) {
+    return null;
+  }
+
+  return {
+    form: formValue.name as MacroFactoryForm,
+    span: {
+      fileName: sourceFile.fileName,
+      start: block.range.start,
+      end: block.range.end,
+    },
+  };
+}
+
+function getFunctionDeclarationExportName(
+  node: ts.Statement,
+): 'default' | string | undefined {
+  if (!ts.isFunctionDeclaration(node)) {
+    return undefined;
+  }
+
+  const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+  const isExported = !!modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+  if (!isExported) {
+    return undefined;
+  }
+
+  const isDefault = !!modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+  if (isDefault) {
+    return 'default';
+  }
+
+  return node.name?.text;
+}
+
+function exportedDeclarationNames(statement: ts.Statement): readonly string[] {
+  const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
+  const isExported = !!modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+  if (!isExported) {
+    return [];
+  }
+
+  const isDefault = !!modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+  if (isDefault) {
+    return ['default'];
+  }
+
+  if (
+    (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) ||
+      ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) ||
+      ts.isEnumDeclaration(statement)) &&
+    statement.name
+  ) {
+    return [statement.name.text];
+  }
+
+  if (ts.isVariableStatement(statement)) {
+    return statement.declarationList.declarations.flatMap((declaration) =>
+      ts.isIdentifier(declaration.name) ? [declaration.name.text] : []
+    );
+  }
+
+  if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+    return ['default'];
+  }
+
+  return [];
+}
+
+export function sourceTextLooksLikeMacroModule(sourceText: string): boolean {
+  return [...MACRO_API_SPECIFIERS].some((specifier) => sourceText.includes(specifier));
+}
+
+export function macroSiteKindForFactoryForm(form: MacroFactoryForm): ImportedMacroSiteKind {
+  switch (form) {
+    case 'call':
+      return 'call';
+    case 'tag':
+      return 'tag';
+    case 'decl':
+      return 'annotation';
+  }
+}
+
+export function scanMacroFactoryExports(
+  fileName: string,
+  sourceText: string,
+): ReadonlyMap<string, ScannedMacroFactoryExport> {
+  const sourceFile = ts.createSourceFile(
+    fileName,
+    sourceText,
+    ts.ScriptTarget.Latest,
+    true,
+    /\.(?:[cm]?tsx|jsx|sts)$/iu.test(fileName) ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  );
+  const exports = new Map<string, ScannedMacroFactoryExport>();
+
+  for (const statement of sourceFile.statements) {
+    const exportName = getFunctionDeclarationExportName(statement);
+    if (!exportName || !ts.isFunctionDeclaration(statement)) {
+      continue;
+    }
+
+    const annotation = macroFactoryAnnotationForNode(sourceFile, statement);
+    if (!annotation) {
+      continue;
+    }
+
+    exports.set(exportName, {
+      exportName,
+      form: annotation.form,
+      span: {
+        fileName,
+        start: annotation.span.start,
+        end: statement.getEnd(),
+      },
+    });
+  }
+
+  return exports;
+}
+
+export function usesLegacyDefineMacroAuthoring(sourceText: string): boolean {
+  return /\bdefineMacro\s*\(/u.test(sourceText) ||
+    /from ['"]@soundscript\/macros['"]/u.test(sourceText) ||
+    /from ['"]sts:macros['"][^]*\bdefineMacro\b/u.test(sourceText);
+}
+
+export function stripMacroFactoryAuthoringFromText(
+  fileName: string,
+  sourceText: string,
+): string {
+  const sourceFile = ts.createSourceFile(
+    fileName,
+    sourceText,
+    ts.ScriptTarget.Latest,
+    true,
+    /\.(?:[cm]?tsx|jsx|sts)$/iu.test(fileName) ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  );
+  const spansToBlank: Array<{ start: number; end: number }> = [];
+  const strippedMacroExportNames: string[] = [];
+
+  for (const statement of sourceFile.statements) {
+    if (
+      ts.isImportDeclaration(statement) &&
+      ts.isStringLiteral(statement.moduleSpecifier) &&
+      MACRO_API_SPECIFIERS.has(statement.moduleSpecifier.text)
+    ) {
+      spansToBlank.push({
+        start: statement.getFullStart(),
+        end: statement.getEnd(),
+      });
+      continue;
+    }
+
+    const exportName = getFunctionDeclarationExportName(statement);
+    if (!exportName || !ts.isFunctionDeclaration(statement)) {
+      continue;
+    }
+
+    const annotation = macroFactoryAnnotationForNode(sourceFile, statement);
+    if (!annotation) {
+      continue;
+    }
+
+    spansToBlank.push({
+      start: annotation.span.start,
+      end: statement.getEnd(),
+    });
+    strippedMacroExportNames.push(exportName);
+  }
+
+  if (spansToBlank.length === 0) {
+    return sourceText;
+  }
+
+  const originalWasModule = ts.isExternalModule(sourceFile);
+
+  let stripped = '';
+  let cursor = 0;
+  for (const span of spansToBlank.sort((left, right) => left.start - right.start)) {
+    if (span.start < cursor) {
+      continue;
+    }
+
+    stripped += sourceText.slice(cursor, span.start);
+    stripped += blankPreservingLines(sourceText.slice(span.start, span.end));
+    cursor = span.end;
+  }
+  stripped += sourceText.slice(cursor);
+
+  const strippedSourceFile = ts.createSourceFile(
+    fileName,
+    stripped,
+    ts.ScriptTarget.Latest,
+    true,
+    /\.(?:[cm]?tsx|jsx|sts)$/iu.test(fileName) ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  );
+  const survivingExportNames = new Set(
+    strippedSourceFile.statements.flatMap((statement) => exportedDeclarationNames(statement)),
+  );
+  const missingExportNames = strippedMacroExportNames.filter((exportName) =>
+    !survivingExportNames.has(exportName)
+  );
+
+  if (missingExportNames.length > 0) {
+    const namedExportNames = missingExportNames.filter((exportName) => exportName !== 'default');
+    const missingDefaultExport = missingExportNames.includes('default');
+    const placeholderStatements = [
+      ...namedExportNames.map((exportName) => `export declare const ${exportName}: unknown;`),
+      ...(missingDefaultExport
+        ? [
+          'declare const __soundscript_default_macro_export: unknown;',
+          'export default __soundscript_default_macro_export;',
+        ]
+        : []),
+    ];
+    return `${stripped}\n/* soundscript:macros */\n${
+      placeholderStatements.join('\n')
+    }\n`;
+  }
+
+  if (!originalWasModule) {
+    return stripped;
+  }
+  return ts.isExternalModule(strippedSourceFile)
+    ? `${stripped}\n/* soundscript:macros */\n`
+    : `${stripped}\n/* soundscript:macros */\nexport {};\n`;
+}

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

@@ -0,0 +1,64 @@
+import ts from 'typescript';
+// Internal TypeScript host parsing and synthesis helpers.
+// Macro authors should depend on macro_api.ts instead of this module.
+function getFragmentScriptKind(fileName) {
+    const lowered = fileName.toLowerCase();
+    if (lowered.endsWith('.sts') || lowered.endsWith('.tsx') || lowered.endsWith('.jsx')) {
+        return ts.ScriptKind.TSX;
+    }
+    if (lowered.endsWith('.js') || lowered.endsWith('.mjs') || lowered.endsWith('.cjs')) {
+        return ts.ScriptKind.JS;
+    }
+    return ts.ScriptKind.TS;
+}
+function createFragmentSourceFile(hostFileName, suffix, text) {
+    const match = /(\.[^.]+)$/u.exec(hostFileName);
+    const extension = match ? match[1] : '.ts';
+    const fragmentFileName = `/virtual/${suffix}${extension === '.sts' ? '.tsx' : extension}`;
+    return ts.createSourceFile(fragmentFileName, text, ts.ScriptTarget.Latest, true, getFragmentScriptKind(hostFileName));
+}
+export function synthesizeHostNode(node) {
+    ts.setTextRange(node, { pos: -1, end: -1 });
+    ts.setOriginalNode(node, undefined);
+    ts.forEachChild(node, (child) => {
+        synthesizeHostNode(child);
+    });
+    return node;
+}
+function ensureNoParseDiagnostics(sourceFile, message) {
+    const parseDiagnostics = sourceFile.parseDiagnostics ?? [];
+    if (parseDiagnostics.length > 0) {
+        throw new Error(message);
+    }
+}
+export function parseHostExpression(hostFileName, code, message) {
+    const sourceFile = createFragmentSourceFile(hostFileName, 'macro_expr', `const __macro_expr = (${code});`);
+    ensureNoParseDiagnostics(sourceFile, message);
+    if (sourceFile.statements.length !== 1) {
+        throw new Error(message);
+    }
+    const [statement] = sourceFile.statements;
+    if (!statement ||
+        !ts.isVariableStatement(statement) ||
+        statement.declarationList.declarations.length !== 1) {
+        throw new Error(message);
+    }
+    const [declaration] = statement.declarationList.declarations;
+    if (!declaration?.initializer ||
+        !ts.isParenthesizedExpression(declaration.initializer)) {
+        throw new Error(message);
+    }
+    return declaration.initializer.expression;
+}
+export function parseHostStatements(hostFileName, suffix, code, message) {
+    const sourceFile = createFragmentSourceFile(hostFileName, suffix, code);
+    ensureNoParseDiagnostics(sourceFile, message);
+    return [...sourceFile.statements];
+}
+export function parseSingleHostStatement(hostFileName, suffix, code, message) {
+    const statements = parseHostStatements(hostFileName, suffix, code, message);
+    if (statements.length !== 1) {
+        throw new Error(message);
+    }
+    return statements[0];
+}

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

@@ -0,0 +1,109 @@
+import ts from 'typescript';
+
+// Internal TypeScript host parsing and synthesis helpers.
+// Macro authors should depend on macro_api.ts instead of this module.
+
+function getFragmentScriptKind(fileName: string): ts.ScriptKind {
+  const lowered = fileName.toLowerCase();
+  if (lowered.endsWith('.sts') || lowered.endsWith('.tsx') || lowered.endsWith('.jsx')) {
+    return ts.ScriptKind.TSX;
+  }
+  if (lowered.endsWith('.js') || lowered.endsWith('.mjs') || lowered.endsWith('.cjs')) {
+    return ts.ScriptKind.JS;
+  }
+  return ts.ScriptKind.TS;
+}
+
+function createFragmentSourceFile(
+  hostFileName: string,
+  suffix: string,
+  text: string,
+): ts.SourceFile {
+  const match = /(\.[^.]+)$/u.exec(hostFileName);
+  const extension = match ? match[1] : '.ts';
+  const fragmentFileName = `/virtual/${suffix}${extension === '.sts' ? '.tsx' : extension}`;
+  return ts.createSourceFile(
+    fragmentFileName,
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    getFragmentScriptKind(hostFileName),
+  );
+}
+
+export function synthesizeHostNode<T extends ts.Node>(node: T): T {
+  ts.setTextRange(node, { pos: -1, end: -1 });
+  ts.setOriginalNode(node, undefined);
+  ts.forEachChild(node, (child) => {
+    synthesizeHostNode(child);
+  });
+  return node;
+}
+
+function ensureNoParseDiagnostics(sourceFile: ts.SourceFile, message: string): void {
+  const parseDiagnostics = (sourceFile as ts.SourceFile & {
+    parseDiagnostics?: readonly ts.Diagnostic[];
+  }).parseDiagnostics ?? [];
+  if (parseDiagnostics.length > 0) {
+    throw new Error(message);
+  }
+}
+
+export function parseHostExpression(
+  hostFileName: string,
+  code: string,
+  message: string,
+): ts.Expression {
+  const sourceFile = createFragmentSourceFile(
+    hostFileName,
+    'macro_expr',
+    `const __macro_expr = (${code});`,
+  );
+  ensureNoParseDiagnostics(sourceFile, message);
+  if (sourceFile.statements.length !== 1) {
+    throw new Error(message);
+  }
+
+  const [statement] = sourceFile.statements;
+  if (
+    !statement ||
+    !ts.isVariableStatement(statement) ||
+    statement.declarationList.declarations.length !== 1
+  ) {
+    throw new Error(message);
+  }
+
+  const [declaration] = statement.declarationList.declarations;
+  if (
+    !declaration?.initializer ||
+    !ts.isParenthesizedExpression(declaration.initializer)
+  ) {
+    throw new Error(message);
+  }
+
+  return declaration.initializer.expression;
+}
+
+export function parseHostStatements(
+  hostFileName: string,
+  suffix: string,
+  code: string,
+  message: string,
+): readonly ts.Statement[] {
+  const sourceFile = createFragmentSourceFile(hostFileName, suffix, code);
+  ensureNoParseDiagnostics(sourceFile, message);
+  return [...sourceFile.statements];
+}
+
+export function parseSingleHostStatement(
+  hostFileName: string,
+  suffix: string,
+  code: string,
+  message: string,
+): ts.Statement {
+  const statements = parseHostStatements(hostFileName, suffix, code, message);
+  if (statements.length !== 1) {
+    throw new Error(message);
+  }
+  return statements[0]!;
+}

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

@@ -0,0 +1,27 @@
+export function buildMacroPlaceholderIndex(preparedFiles) {
+    const entries = preparedFiles.flatMap((preparedFile) => preparedFile.rewriteResult.replacements.flatMap((replacement) => {
+        const invocation = preparedFile.rewriteResult.macrosById.get(replacement.id);
+        if (!invocation) {
+            return [];
+        }
+        return [{
+                fileName: replacement.originalSpan.fileName,
+                id: replacement.id,
+                invocation,
+                preparedFile,
+                replacement,
+            }];
+    }));
+    const byFileAndId = new Map();
+    for (const entry of entries) {
+        byFileAndId.set(`${entry.fileName}:${entry.id}`, entry);
+    }
+    return {
+        entries() {
+            return entries;
+        },
+        get(fileName, id) {
+            return byFileAndId.get(`${fileName}:${id}`);
+        },
+    };
+}

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

@@ -0,0 +1,50 @@
+import type { MacroReplacement, ParsedMacroInvocation } from './macro_types.ts';
+import type { PreparedSourceFile } from './project_frontend.ts';
+
+export interface IndexedMacroPlaceholder {
+  fileName: string;
+  id: number;
+  invocation: ParsedMacroInvocation;
+  preparedFile: PreparedSourceFile;
+  replacement: MacroReplacement;
+}
+
+export interface MacroPlaceholderIndex {
+  entries(): readonly IndexedMacroPlaceholder[];
+  get(fileName: string, id: number): IndexedMacroPlaceholder | undefined;
+}
+
+export function buildMacroPlaceholderIndex(
+  preparedFiles: readonly PreparedSourceFile[],
+): MacroPlaceholderIndex {
+  const entries = preparedFiles.flatMap((preparedFile) =>
+    preparedFile.rewriteResult.replacements.flatMap((replacement) => {
+      const invocation = preparedFile.rewriteResult.macrosById.get(replacement.id);
+      if (!invocation) {
+        return [];
+      }
+
+      return [{
+        fileName: replacement.originalSpan.fileName,
+        id: replacement.id,
+        invocation,
+        preparedFile,
+        replacement,
+      }];
+    })
+  );
+  const byFileAndId = new Map<string, IndexedMacroPlaceholder>();
+
+  for (const entry of entries) {
+    byFileAndId.set(`${entry.fileName}:${entry.id}`, entry);
+  }
+
+  return {
+    entries(): readonly IndexedMacroPlaceholder[] {
+      return entries;
+    },
+    get(fileName: string, id: number): IndexedMacroPlaceholder | undefined {
+      return byFileAndId.get(`${fileName}:${id}`);
+    },
+  };
+}