agentic-dev/packages/core-eslint/rules/_manifest-ast.js

import fs from "node:fs";
import { parse } from "@typescript-eslint/parser";

/**
 * ONE parser for feature.manifest.ts, shared by every conformance rule and
 * by scripts/conformance.mjs. Walks the AST to the `defineFeature({...})`
 * call (unwrapping `as const` / `satisfies` / both) and reads literal
 * values from its argument object.
 *
 * The file used to carry a verbatim second copy of this walk for
 * `parseManifestFully` — both public entry points now share the single
 * implementation below.
 */

function extractStringLiterals(arrayExpr) {
  return arrayExpr.elements
    .filter((el) => el && el.type === "Literal" && typeof el.value === "string")
    .map((el) => el.value);
}

/**
 * Extract budget names from a rateLimit array that contains either string
 * literals ("ip") or RateLimitBudget objects ({ name: "ip", window: "1m", budget: 5 }).
 */
function extractRateLimitNames(arrayExpr) {
  const names = [];
  for (const el of arrayExpr.elements) {
    if (!el) continue;
    if (el.type === "Literal" && typeof el.value === "string") {
      names.push(el.value);
    } else if (el.type === "ObjectExpression") {
      const nameProp = el.properties.find(
        (p) =>
          p.type === "Property" &&
          p.key.type === "Identifier" &&
          p.key.name === "name" &&
          p.value.type === "Literal" &&
          typeof p.value.value === "string",
      );
      if (nameProp) names.push(nameProp.value.value);
    }
  }
  return names;
}

function findDefineFeatureCall(ast) {
  for (const node of ast.body) {
    if (node.type !== "ExportNamedDeclaration" || !node.declaration) continue;
    if (node.declaration.type !== "VariableDeclaration") continue;
    for (const decl of node.declaration.declarations) {
      const init = decl.init;
      if (!init) continue;
      if (
        init.type === "CallExpression" &&
        init.callee.type === "Identifier" &&
        init.callee.name === "defineFeature"
      ) {
        return init;
      }
    }
  }
  return null;
}

function unwrapAsConst(node) {
  // Unwrap BOTH wrapper kinds, including the combined
  // `{...} as const satisfies FeatureManifest` idiom — a `satisfies`-shaped
  // manifest must never silently no-op the error-level conformance rules.
  while (
    node &&
    (node.type === "TSAsExpression" || node.type === "TSSatisfiesExpression")
  ) {
    node = node.expression;
  }
  return node;
}

function extractUseCaseEntry(objExpr) {
  const entry = {
    mutates: false,
    audits: [],
    publishes: [],
    consumes: [],
    analyticsEvents: [],
    rateLimit: [],
  };
  for (const prop of objExpr.properties) {
    if (prop.type !== "Property" || prop.key.type !== "Identifier") continue;
    const key = prop.key.name;
    if (key === "mutates" && prop.value.type === "Literal") {
      entry.mutates = prop.value.value === true;
    } else if (
      (key === "audits" ||
        key === "publishes" ||
        key === "consumes" ||
        key === "analyticsEvents") &&
      prop.value.type === "ArrayExpression"
    ) {
      entry[key] = extractStringLiterals(prop.value);
    } else if (key === "rateLimit" && prop.value.type === "ArrayExpression") {
      entry[key] = extractRateLimitNames(prop.value);
    }
  }
  return entry;
}

function extractUseCasesMap(useCasesObjExpr) {
  const result = {};
  for (const entry of useCasesObjExpr.properties) {
    if (entry.type !== "Property" || entry.value.type !== "ObjectExpression")
      continue;
    const name =
      entry.key.type === "Identifier" ? entry.key.name : entry.key.value;
    result[name] = extractUseCaseEntry(entry.value);
  }
  return result;
}

/**
 * Read + parse the manifest and return the `defineFeature` argument object,
 * or null when the file is missing / unparseable / not the expected shape.
 */
function parseManifestArg(manifestPath) {
  let src;
  try {
    src = fs.readFileSync(manifestPath, "utf8");
  } catch {
    return null;
  }
  let ast;
  try {
    ast = parse(src, {
      sourceType: "module",
      ecmaVersion: "latest",
      loc: false,
      range: false,
    });
  } catch {
    return null;
  }
  const defineCall = findDefineFeatureCall(ast);
  if (!defineCall) return null;
  const arg = unwrapAsConst(defineCall.arguments[0]);
  if (!arg || arg.type !== "ObjectExpression") return null;
  return arg;
}

/**
 * Parse a feature.manifest.ts and return the full manifest shape:
 *   { name, requiredCores: string[], requiresConsent: string[], useCases: { [name]: {...} } }
 * Returns null on parse failure or when the manifest has no `name`.
 */
export function parseManifestFully(manifestPath) {
  const arg = parseManifestArg(manifestPath);
  if (arg === null) return null;

  let name = null;
  let requiredCores = [];
  let requiresConsent = [];
  let useCases = {};

  for (const prop of arg.properties) {
    if (prop.type !== "Property" || prop.key.type !== "Identifier") continue;
    if (
      prop.key.name === "name" &&
      prop.value.type === "Literal" &&
      typeof prop.value.value === "string"
    ) {
      name = prop.value.value;
    } else if (
      prop.key.name === "requiredCores" &&
      prop.value.type === "ArrayExpression"
    ) {
      requiredCores = extractStringLiterals(prop.value);
    } else if (
      prop.key.name === "requiresConsent" &&
      prop.value.type === "ArrayExpression"
    ) {
      requiresConsent = extractStringLiterals(prop.value);
    } else if (
      prop.key.name === "useCases" &&
      prop.value.type === "ObjectExpression"
    ) {
      useCases = extractUseCasesMap(prop.value);
    }
  }

  if (name === null) return null;
  return { name, requiredCores, requiresConsent, useCases };
}

/**
 * Parse a feature.manifest.ts and extract per-use-case attributes only:
 *   { [useCaseName]: { mutates, audits[], publishes[], consumes[], analyticsEvents[], rateLimit[] } }
 * Returns null if the file is missing or doesn't match the expected shape;
 * returns {} for a manifest whose useCases object is empty/absent.
 */
export function parseManifestUseCases(manifestPath) {
  const arg = parseManifestArg(manifestPath);
  if (arg === null) return null;
  const useCasesProp = arg.properties.find(
    (p) =>
      p.type === "Property" &&
      p.key.type === "Identifier" &&
      p.key.name === "useCases",
  );
  if (!useCasesProp || useCasesProp.value.type !== "ObjectExpression")
    return {};
  return extractUseCasesMap(useCasesProp.value);
}