Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

4.7 KB
Raw Blame
import { createRequire } from "node:module";

const require = createRequire(import.meta.url);
const extractorRequire = createRequire(require.resolve("@microsoft/api-extractor/package.json"));
const ts = extractorRequire("typescript");

function reportSource(report) {
  const match = report.match(/```ts\n([\s\S]*?)\n```/);
  if (!match)
    throw new Error("Could not read the TypeScript declaration block from an API report.");
  return match[1];
}

function parsedReport(report, name) {
  const source = reportSource(report);
  return ts.createSourceFile(name, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
}

/** Names every declaration API Extractor traced from one capability root. */
export function collectReportDeclarationNames(report) {
  const sourceFile = parsedReport(report, "capability-report.d.ts");
  const names = new Set();
  for (const statement of sourceFile.statements) {
    if (
      (ts.isClassDeclaration(statement) ||
        ts.isEnumDeclaration(statement) ||
        ts.isFunctionDeclaration(statement) ||
        ts.isInterfaceDeclaration(statement) ||
        ts.isTypeAliasDeclaration(statement)) &&
      statement.name
    ) {
      names.add(statement.name.text);
      continue;
    }
    if (ts.isVariableStatement(statement)) {
      for (const declaration of statement.declarationList.declarations) {
        if (ts.isIdentifier(declaration.name)) names.add(declaration.name.text);
      }
    }
  }
  return names;
}

function interfaceName(statement) {
  return statement.name.text;
}

function textMultiset(nodes, sourceFile) {
  const counts = new Map();
  for (const node of nodes) {
    const text = node.getText(sourceFile);
    counts.set(text, (counts.get(text) ?? 0) + 1);
  }
  return counts;
}

function consumeText(counts, text) {
  const count = counts.get(text) ?? 0;
  if (count === 0) return false;
  if (count === 1) counts.delete(text);
  else counts.set(text, count - 1);
  return true;
}

function interfaceCompatibility(previous, current, previousSource, currentSource) {
  const reasons = [];
  const currentMembers = textMultiset(current.members, currentSource);
  for (const member of previous.members) {
    const text = member.getText(previousSource);
    if (!consumeText(currentMembers, text)) {
      reasons.push(`${interfaceName(previous)} changed or removed member: ${text}`);
    }
  }

  const previousShape = [
    ...(previous.typeParameters ?? []).map((node) => node.getText(previousSource)),
    ...(previous.heritageClauses ?? []).map((node) => node.getText(previousSource)),
  ];
  const currentShape = [
    ...(current.typeParameters ?? []).map((node) => node.getText(currentSource)),
    ...(current.heritageClauses ?? []).map((node) => node.getText(currentSource)),
  ];
  if (JSON.stringify(previousShape) !== JSON.stringify(currentShape)) {
    reasons.push(`${interfaceName(previous)} changed its type parameters or heritage clauses.`);
  }

  for (const [text, count] of currentMembers) {
    const members = current.members.filter((member) => member.getText(currentSource) === text);
    if (members.slice(0, count).some((member) => member.questionToken === undefined)) {
      reasons.push(`${interfaceName(previous)} added a required member: ${text}`);
    }
  }
  return reasons;
}

/**
 * Conservatively recognizes declaration changes that preserve old authored
 * source: new top-level declarations and optional interface members. Anything
 * else requires an explicit compatibility decision.
 */
export function classifyStructuralBackwardCompatibility(previousReport, currentReport) {
  const previous = parsedReport(previousReport, "previous.d.ts");
  const current = parsedReport(currentReport, "current.d.ts");
  const reasons = [];

  const currentInterfaces = new Map(
    current.statements
      .filter(ts.isInterfaceDeclaration)
      .map((statement) => [interfaceName(statement), statement]),
  );
  for (const previousInterface of previous.statements.filter(ts.isInterfaceDeclaration)) {
    const name = interfaceName(previousInterface);
    const currentInterface = currentInterfaces.get(name);
    if (!currentInterface) {
      reasons.push(`Interface ${name} was removed.`);
      continue;
    }
    reasons.push(...interfaceCompatibility(previousInterface, currentInterface, previous, current));
  }

  const currentStatements = textMultiset(
    current.statements.filter((statement) => !ts.isInterfaceDeclaration(statement)),
    current,
  );
  for (const statement of previous.statements.filter(
    (candidate) => !ts.isInterfaceDeclaration(candidate),
  )) {
    const text = statement.getText(previous);
    if (!consumeText(currentStatements, text)) {
      reasons.push(`Declaration changed or was removed: ${text.split("\n", 1)[0]}`);
    }
  }

  return { compatible: reasons.length === 0, reasons };
}