Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

15.2 KB
Raw Blame
import { readFile, readdir } from "node:fs/promises";
import { createRequire } from "node:module";
import { join, relative, resolve, sep } from "node:path";
import { fileURLToPath } from "node:url";

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

export const REPO_ROOT = resolve(fileURLToPath(import.meta.url), "../../..");
export const EVE_ROOT = join(REPO_ROOT, "packages/eve");
export const COMPATIBILITY_SOURCE = join(EVE_ROOT, "src/compiler/extension-compatibility.ts");
export const CONTRACT_ROOT = join(EVE_ROOT, "extension-contracts");
export const ENTRYPOINT_ROOT = join(CONTRACT_ROOT, "entrypoints");
export const COMPATIBILITY_FIXTURE_ROOT = join(CONTRACT_ROOT, "compatibility");
export const REPORT_ROOT = join(CONTRACT_ROOT, "reports");
export const COMPATIBILITY_FIXTURE_PLACEHOLDER = "REPLACE_WITH_RETAINED_AUTHORING_EXAMPLE";

export const PUBLIC_SURFACES = [
  { path: "src/public/extension/index.ts", capabilities: ["extension", "config"] },
  { path: "src/public/channels/index.ts", capabilities: ["channel"] },
  { path: "src/public/schedules/index.ts", capabilities: ["schedule"] },
  { path: "src/public/index.ts", capabilities: ["subagent"] },
  {
    paths: [
      "src/public/tools/index.ts",
      "src/public/tools/agent-router.ts",
      "src/public/tools/web-search.ts",
      "src/public/tools/workflow.ts",
      "src/public/ai/index.ts",
      "src/public/models/index.ts",
    ],
    capabilities: ["tool", "dynamicTool"],
  },
  { path: "src/public/connections/index.ts", capabilities: ["connection"] },
  { path: "src/public/hooks/index.ts", capabilities: ["hook"] },
  { path: "src/public/skills/index.ts", capabilities: ["skill", "dynamicSkill"] },
  {
    path: "src/public/instructions/index.ts",
    capabilities: ["instructions", "dynamicInstructions"],
  },
  { path: "src/public/context/index.ts", capabilities: ["state"] },
];

export function publicSurfacePaths(surface) {
  return surface.paths ?? [surface.path];
}

export function toPosix(path) {
  return sep === "/" ? path : path.split(sep).join("/");
}

function unwrapExpression(expression) {
  let current = expression;
  while (
    ts.isAsExpression(current) ||
    ts.isSatisfiesExpression(current) ||
    ts.isParenthesizedExpression(current)
  ) {
    current = current.expression;
  }
  return current;
}

function propertyName(property) {
  if (
    ts.isIdentifier(property.name) ||
    ts.isStringLiteral(property.name) ||
    ts.isNumericLiteral(property.name)
  ) {
    return property.name.text;
  }
  throw new Error("Extension capability contracts must use static property names.");
}

function objectLiteral(expression, description) {
  const unwrapped = unwrapExpression(expression);
  if (!ts.isObjectLiteralExpression(unwrapped)) {
    throw new Error(`${description} must be an object literal.`);
  }
  return unwrapped;
}

function propertyAssignment(object, name, description) {
  const property = object.properties.find(
    (candidate) => ts.isPropertyAssignment(candidate) && propertyName(candidate) === name,
  );
  if (!property || !ts.isPropertyAssignment(property)) {
    throw new Error(`${description} must define ${name}.`);
  }
  return property;
}

function numericValue(expression, description) {
  const unwrapped = unwrapExpression(expression);
  if (!ts.isNumericLiteral(unwrapped)) throw new Error(`${description} must be a number.`);
  return Number(unwrapped.text);
}

function numericArray(expression, description) {
  const unwrapped = unwrapExpression(expression);
  if (!ts.isArrayLiteralExpression(unwrapped)) {
    throw new Error(`${description} must be an array literal.`);
  }
  return unwrapped.elements.map((element) => numericValue(element, `${description} entry`));
}

function droppedEpochs(expression, description) {
  const object = objectLiteral(expression, description);
  return Object.fromEntries(
    object.properties.map((property) => {
      if (!ts.isPropertyAssignment(property)) {
        throw new Error(`${description} must contain property assignments.`);
      }
      const reason = unwrapExpression(property.initializer);
      if (!ts.isStringLiteral(reason)) {
        throw new Error(`${description}.${propertyName(property)} must be a string literal.`);
      }
      return [propertyName(property), reason.text];
    }),
  );
}

function contractTable(source) {
  const sourceFile = ts.createSourceFile(
    COMPATIBILITY_SOURCE,
    source,
    ts.ScriptTarget.Latest,
    true,
    ts.ScriptKind.TS,
  );
  for (const statement of sourceFile.statements) {
    if (!ts.isVariableStatement(statement)) continue;
    for (const declaration of statement.declarationList.declarations) {
      if (
        ts.isIdentifier(declaration.name) &&
        declaration.name.text === "EXTENSION_CAPABILITY_CONTRACTS" &&
        declaration.initializer
      ) {
        return objectLiteral(declaration.initializer, "EXTENSION_CAPABILITY_CONTRACTS");
      }
    }
  }
  throw new Error("Could not find EXTENSION_CAPABILITY_CONTRACTS.");
}

export function parseCapabilityConfiguration(source) {
  const contracts = Object.fromEntries(
    contractTable(source).properties.map((property) => {
      if (!ts.isPropertyAssignment(property)) {
        throw new Error("EXTENSION_CAPABILITY_CONTRACTS must contain property assignments.");
      }
      const capability = propertyName(property);
      const contract = objectLiteral(property.initializer, `Capability ${capability}`);
      return [
        capability,
        {
          current: numericValue(
            propertyAssignment(contract, "current", `Capability ${capability}`).initializer,
            `Capability ${capability}.current`,
          ),
          supported: numericArray(
            propertyAssignment(contract, "supported", `Capability ${capability}`).initializer,
            `Capability ${capability}.supported`,
          ),
          dropped: droppedEpochs(
            propertyAssignment(contract, "dropped", `Capability ${capability}`).initializer,
            `Capability ${capability}.dropped`,
          ),
        },
      ];
    }),
  );
  return {
    contracts,
    current: Object.fromEntries(
      Object.entries(contracts).map(([capability, contract]) => [capability, contract.current]),
    ),
    support: Object.fromEntries(
      Object.entries(contracts).map(([capability, contract]) => [capability, contract.supported]),
    ),
  };
}

export function bumpCapabilityConfiguration(source, capability, decision) {
  const table = contractTable(source);
  const property = table.properties.find(
    (candidate) => ts.isPropertyAssignment(candidate) && propertyName(candidate) === capability,
  );
  if (!property || !ts.isPropertyAssignment(property)) {
    throw new Error(`Unknown extension capability "${capability}".`);
  }

  const configuration = parseCapabilityConfiguration(source);
  const contract = configuration.contracts[capability];
  const nextVersion = contract.current + 1;
  const supported = decision.retain
    ? [...contract.supported, nextVersion]
    : [...contract.supported.filter((version) => version !== contract.current), nextVersion];
  const dropped = decision.retain
    ? contract.dropped
    : { ...contract.dropped, [contract.current]: decision.reason };
  const droppedSource = Object.entries(dropped)
    .map(([version, reason]) => `${version}: ${JSON.stringify(reason)}`)
    .join(", ");
  const replacement = `${capability}: { current: ${nextVersion}, supported: [${supported.join(", ")}], dropped: {${droppedSource === "" ? "" : ` ${droppedSource} `}} }`;

  return {
    source: `${source.slice(0, property.getStart())}${replacement}${source.slice(property.end)}`,
    previousVersion: contract.current,
    version: nextVersion,
  };
}

export function retainedCompatibilityFixture(capability, version) {
  return `/**
 * Replace this scaffold with a representative ${capability} epoch ${version}
 * authoring example that must continue to compile against the current eve API.
 * ${COMPATIBILITY_FIXTURE_PLACEHOLDER}
 */
export {};
`;
}

export function collectExportNames(source, { valuesOnly = false } = {}) {
  const names = new Set();
  const sourceFile = ts.createSourceFile(
    "extension-capability-entrypoint.ts",
    source,
    ts.ScriptTarget.Latest,
    true,
    ts.ScriptKind.TS,
  );
  for (const statement of sourceFile.statements) {
    if (ts.isExportDeclaration(statement) && statement.exportClause) {
      if (!ts.isNamedExports(statement.exportClause)) continue;
      for (const specifier of statement.exportClause.elements) {
        if (valuesOnly && (statement.isTypeOnly || specifier.isTypeOnly)) continue;
        names.add(specifier.name.text);
      }
      continue;
    }
    const isExported = statement.modifiers?.some(
      (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,
    );
    if (!isExported) continue;
    if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) {
      if (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);
      }
      continue;
    }
    if (ts.isEnumDeclaration(statement)) {
      names.add(statement.name.text);
      continue;
    }
    if (
      !valuesOnly &&
      (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement))
    ) {
      names.add(statement.name.text);
    }
  }
  return names;
}

export async function validateCapabilityConfiguration(configuration) {
  const issues = [];
  const capabilities = Object.keys(configuration.current);
  const entrypointEntries = await readdir(ENTRYPOINT_ROOT, { withFileTypes: true });
  const entrypointCapabilities = entrypointEntries
    .filter((entry) => entry.isFile() && entry.name.endsWith(".ts"))
    .map((entry) => entry.name.slice(0, -3))
    .sort();

  for (const capability of capabilities) {
    const { current: version, dropped, supported } = configuration.contracts[capability];
    if (!Number.isInteger(version) || version < 1) {
      issues.push({
        file: toPosix(relative(REPO_ROOT, COMPATIBILITY_SOURCE)),
        message: `Capability "${capability}" must have a positive integer epoch.`,
      });
    }
    if (!supported.includes(version)) {
      issues.push({
        file: toPosix(relative(REPO_ROOT, COMPATIBILITY_SOURCE)),
        message: `Capability "${capability}" does not list its current epoch ${version} as supported.`,
      });
    }
    if (new Set(supported).size !== supported.length) {
      issues.push({
        file: toPosix(relative(REPO_ROOT, COMPATIBILITY_SOURCE)),
        message: `Capability "${capability}" lists a supported epoch more than once.`,
      });
    }
    const droppedVersions = Object.keys(dropped).map(Number);
    for (const supportedVersion of supported) {
      if (
        !Number.isInteger(supportedVersion) ||
        supportedVersion < 1 ||
        supportedVersion > version
      ) {
        issues.push({
          file: toPosix(relative(REPO_ROOT, COMPATIBILITY_SOURCE)),
          message: `Capability "${capability}" has invalid supported epoch ${supportedVersion}; supported epochs must be positive and no newer than current epoch ${version}.`,
        });
      }
    }
    for (const droppedVersion of droppedVersions) {
      if (!Number.isInteger(droppedVersion) || droppedVersion < 1 || droppedVersion >= version) {
        issues.push({
          file: toPosix(relative(REPO_ROOT, COMPATIBILITY_SOURCE)),
          message: `Capability "${capability}" has invalid dropped epoch ${droppedVersion}; only historical epochs before current epoch ${version} can be dropped.`,
        });
      }
      if (dropped[String(droppedVersion)].trim() === "") {
        issues.push({
          file: toPosix(relative(REPO_ROOT, COMPATIBILITY_SOURCE)),
          message: `Capability "${capability}" must record why epoch ${droppedVersion} was dropped.`,
        });
      }
    }
    for (let historicalVersion = 1; historicalVersion < version; historicalVersion++) {
      const isSupported = supported.includes(historicalVersion);
      const isDropped = Object.hasOwn(dropped, historicalVersion);
      if (isSupported === isDropped) {
        issues.push({
          file: toPosix(relative(REPO_ROOT, COMPATIBILITY_SOURCE)),
          message: `Capability "${capability}" epoch ${historicalVersion} must be classified exactly once as supported or dropped.`,
        });
      }
      if (!isSupported) continue;
      const fixturePath = join(COMPATIBILITY_FIXTURE_ROOT, capability, `v${historicalVersion}.ts`);
      try {
        const fixture = await readFile(fixturePath, "utf8");
        if (fixture.includes(COMPATIBILITY_FIXTURE_PLACEHOLDER)) {
          issues.push({
            file: toPosix(relative(REPO_ROOT, fixturePath)),
            message: `Replace the scaffold with a representative ${capability} epoch ${historicalVersion} authoring example before advertising retained support.`,
          });
        }
      } catch (error) {
        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
          issues.push({
            file: toPosix(relative(REPO_ROOT, fixturePath)),
            message: `Advertising ${capability} epoch ${historicalVersion} requires an immutable compatibility fixture that exercises the retained authoring contract.`,
          });
          continue;
        }
        throw error;
      }
    }
  }

  const configured = [...capabilities].sort();
  if (JSON.stringify(configured) !== JSON.stringify(entrypointCapabilities)) {
    issues.push({
      file: toPosix(relative(REPO_ROOT, ENTRYPOINT_ROOT)),
      message: `Contract entrypoints must exactly match configured capabilities. Expected ${configured.join(", ")}; found ${entrypointCapabilities.join(", ")}.`,
    });
  }

  for (const surface of PUBLIC_SURFACES) {
    const paths = publicSurfacePaths(surface);
    const publicNames = new Set();
    for (const path of paths) {
      const publicSource = await readFile(join(EVE_ROOT, path), "utf8");
      for (const name of collectExportNames(publicSource, { valuesOnly: true })) {
        publicNames.add(name);
      }
    }
    const contractNames = new Set();
    for (const capability of surface.capabilities) {
      const contractSource = await readFile(join(ENTRYPOINT_ROOT, `${capability}.ts`), "utf8");
      for (const name of collectExportNames(contractSource, { valuesOnly: true })) {
        contractNames.add(name);
      }
    }
    const missing = [...publicNames].filter((name) => !contractNames.has(name)).sort();
    const extra = [...contractNames].filter((name) => !publicNames.has(name)).sort();
    if (missing.length > 0 || extra.length > 0) {
      const details = [
        missing.length > 0 ? `unassigned exports: ${missing.join(", ")}` : "",
        extra.length > 0 ? `unknown exports: ${extra.join(", ")}` : "",
      ]
        .filter(Boolean)
        .join("; ");
      issues.push({
        file: toPosix(relative(REPO_ROOT, join(EVE_ROOT, paths[0]))),
        message: `Capability contract roots are incomplete (${details}). Assign every public authoring value to one of: ${surface.capabilities.join(", ")}.`,
      });
    }
  }

  return issues;
}