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

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

/**
 * Parse a feature.manifest.ts file and extract per-use-case attributes.
 * Walks the AST to find the `defineFeature({...} as const)` call expression
 * and reads literal values from its argument object.
 *
 * Returns: { [useCaseName]: { mutates, audits[], publishes[], consumes[] } }
 * Returns null if the file is missing or doesn't match the expected shape.
 */
export function parseManifestUseCases(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;
  const useCasesProp = arg.properties.find(
    (p) => p.type === "Property" && p.key.type === "Identifier" && p.key.name === "useCases",
  );
  if (!useCasesProp || useCasesProp.value.type !== "ObjectExpression") return {};
  const result = {};
  for (const entry of useCasesProp.value.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;
}

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) {
  if (node && node.type === "TSAsExpression") return node.expression;
  return node;
}

function extractUseCaseEntry(objExpr) {
  const entry = { mutates: false, audits: [], publishes: [], consumes: [] };
  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") && prop.value.type === "ArrayExpression") {
      entry[key] = prop.value.elements
        .filter((el) => el && el.type === "Literal" && typeof el.value === "string")
        .map((el) => el.value);
    }
  }
  return entry;
}

/**
 * Parse a feature.manifest.ts and return the full manifest shape:
 *   { name, requiredCores: string[], useCases: { [name]: {...} } }
 *
 * Same AST walking as parseManifestUseCases but additionally extracts
 * the top-level name + requiredCores fields. Returns null on parse failure.
 */
export function parseManifestFully(manifestPath) {
  // Reuse the AST parser used by parseManifestUseCases by inlining the
  // file-read + AST walk. We need access to the manifest's top-level
  // argument object beyond just useCases.
  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 = findDefineFeatureCallFromBody(ast);
  if (!defineCall) return null;
  const arg = unwrapAsConstNode(defineCall.arguments[0]);
  if (!arg || arg.type !== "ObjectExpression") return null;

  let name = null;
  let requiredCores = [];
  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 = prop.value.elements
        .filter((el) => el && el.type === "Literal" && typeof el.value === "string")
        .map((el) => el.value);
    } else if (prop.key.name === "useCases" && prop.value.type === "ObjectExpression") {
      for (const entry of prop.value.properties) {
        if (entry.type !== "Property" || entry.value.type !== "ObjectExpression") continue;
        const ucName = entry.key.type === "Identifier" ? entry.key.name : entry.key.value;
        useCases[ucName] = extractUseCaseEntryFromObj(entry.value);
      }
    }
  }

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

// Helper aliases for the existing private functions — exposed under
// different names to avoid touching existing code paths.
function findDefineFeatureCallFromBody(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 unwrapAsConstNode(node) {
  if (node && node.type === "TSAsExpression") return node.expression;
  return node;
}

function extractUseCaseEntryFromObj(objExpr) {
  const entry = { mutates: false, audits: [], publishes: [], consumes: [] };
  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") && prop.value.type === "ArrayExpression") {
      entry[key] = prop.value.elements
        .filter((el) => el && el.type === "Literal" && typeof el.value === "string")
        .map((el) => el.value);
    }
  }
  return entry;
}