Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.8 KB
Raw Blame
/**
 * Source scan behind test/config-reader-keys-registered.test.ts (#6780).
 *
 * Finds every `getConfig(<arg>)` call under a root and resolves its argument
 * syntactically: a string literal, a template literal (to its static prefix),
 * a const in scope (same file, named import, or a destructured dynamic
 * import), a const object's property, both arms of `?:`/`??`/`||`, or a
 * key-builder function whose returns resolve. Anything else (a parameter, a
 * `let`, a computed call) is reported unresolved with its source text.
 */
import ts from 'typescript';
import { readdirSync, readFileSync, statSync } from 'fs';
import { dirname, join, relative, resolve } from 'path';

export type ConfigReadTarget =
  | { kind: 'keys'; keys: string[] }
  | { kind: 'template'; prefix: string }
  | { kind: 'unresolved'; via: 'parameter' | 'other' };

export interface ConfigRead { file: string; line: number; expr: string; target: ConfigReadTarget }

const MAX_DEPTH = 8;

function walk(dir: string, out: string[]): string[] {
  for (const name of readdirSync(dir)) {
    const path = join(dir, name);
    if (statSync(path).isDirectory()) walk(path, out);
    else if (path.endsWith('.ts') && !path.endsWith('.d.ts')) out.push(path);
  }
  return out;
}

export function scanConfigReads(root: string, subdir = 'src'): ConfigRead[] {
  const sources = new Map<string, ts.SourceFile>();
  const source = (path: string): ts.SourceFile => {
    let sf = sources.get(path);
    if (!sf) {
      sf = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true);
      sources.set(path, sf);
    }
    return sf;
  };
  const moduleFile = (from: string, spec: string): string | null => {
    if (!spec.startsWith('.')) return null;
    const base = resolve(dirname(from), spec);
    for (const candidate of [base, base.replace(/\.js$/, '.ts'), `${base}.ts`, join(base, 'index.ts')]) {
      try { if (statSync(candidate).isFile()) return candidate; } catch { /* next candidate */ }
    }
    return null;
  };

  type Decl = ts.Expression | ts.FunctionLikeDeclaration | ts.ParameterDeclaration | ts.ForOfStatement | null;

  const exported = (file: string, name: string, depth: number): Decl => {
    if (depth > MAX_DEPTH) return null;
    for (const stmt of source(file).statements) {
      const found = declaredIn(stmt, name, file, depth);
      if (found !== undefined) return found;
      if (ts.isExportDeclaration(stmt) && stmt.moduleSpecifier && stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
        for (const el of stmt.exportClause.elements) {
          if (el.name.text !== name) continue;
          const target = moduleFile(file, (stmt.moduleSpecifier as ts.StringLiteral).text);
          return target ? exported(target, (el.propertyName ?? el.name).text, depth + 1) : null;
        }
      }
    }
    return null;
  };

  const importedDecl = (file: string, spec: string, name: string, depth: number): Decl => {
    const target = moduleFile(file, spec);
    return target ? exported(target, name, depth + 1) : null;
  };

  const dynamicImportSpec = (init: ts.Expression | undefined): string | null => {
    let e = init;
    while (e && (ts.isAwaitExpression(e) || ts.isParenthesizedExpression(e))) e = e.expression;
    if (e && ts.isCallExpression(e) && e.expression.kind === ts.SyntaxKind.ImportKeyword && e.arguments[0] && ts.isStringLiteralLike(e.arguments[0])) {
      return e.arguments[0].text;
    }
    return null;
  };

  /** undefined = not declared by this statement; null = declared but not a const value. */
  const declaredIn = (stmt: ts.Node, name: string, file: string, depth: number): Decl | undefined => {
    if (ts.isVariableStatement(stmt)) {
      const isConst = (stmt.declarationList.flags & ts.NodeFlags.Const) !== 0;
      for (const d of stmt.declarationList.declarations) {
        if (ts.isIdentifier(d.name) && d.name.text === name) {
          if (!isConst || !d.initializer) return null;
          return d.initializer;
        }
        if (ts.isObjectBindingPattern(d.name)) {
          for (const el of d.name.elements) {
            if (!ts.isIdentifier(el.name) || el.name.text !== name) continue;
            const spec = isConst ? dynamicImportSpec(d.initializer) : null;
            const prop = el.propertyName && ts.isIdentifier(el.propertyName) ? el.propertyName.text : name;
            return spec ? importedDecl(file, spec, prop, depth) : null;
          }
        }
      }
      return undefined;
    }
    if (ts.isFunctionDeclaration(stmt) && stmt.name?.text === name) return stmt;
    if (ts.isImportDeclaration(stmt) && stmt.importClause?.namedBindings && ts.isNamedImports(stmt.importClause.namedBindings)) {
      for (const el of stmt.importClause.namedBindings.elements) {
        if (el.name.text === name) return importedDecl(file, (stmt.moduleSpecifier as ts.StringLiteral).text, (el.propertyName ?? el.name).text, depth);
      }
    }
    return undefined;
  };

  const bindsName = (b: ts.BindingName, name: string): boolean => ts.isIdentifier(b)
    ? b.text === name
    : b.elements.some((el) => !ts.isOmittedExpression(el) && bindsName(el.name, name));

  /** Lexical lookup from a use site outward to the file's top level. */
  const lookup = (id: ts.Identifier, file: string, depth: number): Decl => {
    for (let node: ts.Node | undefined = id.parent; node; node = node.parent) {
      if (ts.isFunctionLike(node)) {
        const param = node.parameters.find((p) => bindsName(p.name, id.text));
        if (param) return param;
      }
      if ((ts.isForOfStatement(node) || ts.isForInStatement(node) || ts.isForStatement(node)) && node.initializer && ts.isVariableDeclarationList(node.initializer)
        && node.initializer.declarations.some((d) => bindsName(d.name, id.text))) {
        return ts.isForOfStatement(node) && ts.isIdentifier(node.initializer.declarations[0].name) ? node : null;
      }
      if (ts.isCatchClause(node) && node.variableDeclaration && bindsName(node.variableDeclaration.name, id.text)) return null;
      if (ts.isBlock(node) || ts.isSourceFile(node) || ts.isModuleBlock(node) || ts.isCaseClause(node) || ts.isDefaultClause(node)) {
        for (const stmt of node.statements) {
          const found = declaredIn(stmt, id.text, file, depth);
          if (found !== undefined) return found;
        }
      }
    }
    return null;
  };

  const strip = (e: ts.Expression): ts.Expression => {
    while (ts.isAsExpression(e) || ts.isParenthesizedExpression(e) || ts.isSatisfiesExpression(e) || ts.isNonNullExpression(e) || ts.isTypeAssertionExpression(e)) e = e.expression;
    return e;
  };

  const fileOf = (n: ts.Node): string => n.getSourceFile().fileName;

  const OTHER: ConfigReadTarget = { kind: 'unresolved', via: 'other' };

  /** A parameter typed as a union of string literals resolves to those literals. */
  const literalUnion = (type: ts.TypeNode | undefined): string[] | null => {
    if (!type) return null;
    const members = ts.isUnionTypeNode(type) ? type.types : [type];
    const out: string[] = [];
    for (const m of members) {
      if (!ts.isLiteralTypeNode(m) || !ts.isStringLiteral(m.literal)) return null;
      out.push(m.literal.text);
    }
    return out;
  };

  const resolveDecl = (decl: Decl, depth: number): ConfigReadTarget => {
    if (!decl) return OTHER;
    if (ts.isParameter(decl as ts.Node)) {
      const keys = literalUnion((decl as ts.ParameterDeclaration).type);
      return keys ? { kind: 'keys', keys } : { kind: 'unresolved', via: 'parameter' };
    }
    if (ts.isForOfStatement(decl as ts.Node)) return elementsOf((decl as ts.ForOfStatement).expression, depth + 1);
    if (ts.isFunctionLike(decl as ts.Node)) return OTHER;
    return resolveExpr(decl as ts.Expression, depth + 1);
  };

  /** `for (const k of X)`: X a const array literal, or Object.keys/values of a const object literal. */
  const elementsOf = (raw: ts.Expression, depth: number): ConfigReadTarget => {
    if (depth > MAX_DEPTH) return OTHER;
    const e = strip(raw);
    if (ts.isArrayLiteralExpression(e)) {
      const parts = e.elements.map((el) => ts.isSpreadElement(el) ? elementsOf(el.expression, depth + 1) : resolveExpr(el, depth + 1));
      return parts.length > 0 ? merge(parts) : OTHER;
    }
    if (ts.isCallExpression(e) && ts.isPropertyAccessExpression(e.expression) && ts.isIdentifier(e.expression.expression)
      && e.expression.expression.text === 'Object' && e.arguments[0]) {
      const obj = objectLiteral(e.arguments[0], depth + 1);
      const assignments = obj?.properties.filter(ts.isPropertyAssignment) ?? [];
      if (assignments.length === 0) return OTHER;
      if (e.expression.name.text === 'keys') {
        return { kind: 'keys', keys: assignments.map((p) => ts.isStringLiteral(p.name) || ts.isIdentifier(p.name) ? p.name.text : p.name.getText()) };
      }
      if (e.expression.name.text === 'values') return merge(assignments.map((p) => resolveExpr(p.initializer, depth + 1)));
      return OTHER;
    }
    if (ts.isIdentifier(e)) {
      const decl = lookup(e, fileOf(e), depth);
      return decl && !ts.isParameter(decl as ts.Node) && !ts.isFunctionLike(decl as ts.Node) && !ts.isForOfStatement(decl as ts.Node)
        ? elementsOf(decl as ts.Expression, depth + 1) : OTHER;
    }
    return OTHER;
  };

  const objectLiteral = (e: ts.Expression, depth: number): ts.ObjectLiteralExpression | null => {
    const s = strip(e);
    if (ts.isObjectLiteralExpression(s)) return s;
    if (ts.isCallExpression(s) && ts.isPropertyAccessExpression(s.expression) && s.expression.name.text === 'freeze' && s.arguments[0]) return objectLiteral(s.arguments[0], depth);
    if (ts.isIdentifier(s) && depth <= MAX_DEPTH) {
      const decl = lookup(s, fileOf(s), depth);
      if (decl && !ts.isFunctionLike(decl as ts.Node) && !ts.isParameter(decl as ts.Node) && !ts.isForOfStatement(decl as ts.Node)) return objectLiteral(decl as ts.Expression, depth + 1);
    }
    return null;
  };

  const merge = (targets: ConfigReadTarget[]): ConfigReadTarget => {
    if (targets.some((t) => t.kind !== 'keys')) {
      return targets.length === 1 ? targets[0] : (targets.find((t) => t.kind === 'unresolved') ?? targets.find((t) => t.kind === 'template')!);
    }
    return { kind: 'keys', keys: [...new Set(targets.flatMap((t) => (t as { keys: string[] }).keys))] };
  };

  const returnsOf = (fn: ts.FunctionLikeDeclaration): ts.Expression[] => {
    if (!fn.body) return [];
    if (!ts.isBlock(fn.body)) return [fn.body as ts.Expression];
    const out: ts.Expression[] = [];
    const visit = (n: ts.Node) => {
      if (n !== fn.body && ts.isFunctionLike(n)) return;
      if (ts.isReturnStatement(n) && n.expression) out.push(n.expression);
      ts.forEachChild(n, visit);
    };
    visit(fn.body);
    return out;
  };

  const resolveExpr = (raw: ts.Expression, depth: number): ConfigReadTarget => {
    if (depth > MAX_DEPTH) return OTHER;
    const e = strip(raw);
    if (ts.isStringLiteralLike(e)) return { kind: 'keys', keys: [e.text] };
    if (ts.isTemplateExpression(e)) {
      let keys = [e.head.text];
      for (const span of e.templateSpans) {
        const part = resolveExpr(span.expression, depth + 1);
        if (part.kind !== 'keys' || keys.length * part.keys.length > 16) {
          return keys.length === 1 ? { kind: 'template', prefix: keys[0] } : OTHER;
        }
        keys = keys.flatMap((k) => part.keys.map((p) => k + p + span.literal.text));
      }
      return { kind: 'keys', keys };
    }
    if (ts.isConditionalExpression(e)) return merge([resolveExpr(e.whenTrue, depth + 1), resolveExpr(e.whenFalse, depth + 1)]);
    if (ts.isBinaryExpression(e) && (e.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken || e.operatorToken.kind === ts.SyntaxKind.BarBarToken)) {
      return merge([resolveExpr(e.left, depth + 1), resolveExpr(e.right, depth + 1)]);
    }
    if (ts.isIdentifier(e)) return resolveDecl(lookup(e, fileOf(e), depth), depth);
    if (ts.isPropertyAccessExpression(e)) {
      const obj = objectLiteral(e.expression, depth + 1);
      const prop = obj?.properties.find((p) => ts.isPropertyAssignment(p) && p.name.getText() === e.name.text) as ts.PropertyAssignment | undefined;
      return prop ? resolveExpr(prop.initializer, depth + 1) : OTHER;
    }
    if (ts.isElementAccessExpression(e)) {
      const obj = objectLiteral(e.expression, depth + 1);
      const values = obj?.properties.filter(ts.isPropertyAssignment).map((p) => resolveExpr(p.initializer, depth + 1)) ?? [];
      return values.length > 0 ? merge(values) : OTHER;
    }
    if (ts.isCallExpression(e) && ts.isIdentifier(e.expression)) {
      const decl = lookup(e.expression, fileOf(e), depth);
      let fn: ts.FunctionLikeDeclaration | null = null;
      if (decl && ts.isFunctionLike(decl as ts.Node)) fn = decl as ts.FunctionLikeDeclaration;
      else if (decl && !ts.isParameter(decl as ts.Node) && !ts.isForOfStatement(decl as ts.Node) && (ts.isArrowFunction(strip(decl as ts.Expression)) || ts.isFunctionExpression(strip(decl as ts.Expression)))) fn = strip(decl as ts.Expression) as ts.ArrowFunction;
      const returns = fn ? returnsOf(fn) : [];
      return returns.length > 0 ? merge(returns.map((r) => resolveExpr(r, depth + 1))) : OTHER;
    }
    return OTHER;
  };

  const reads: ConfigRead[] = [];
  for (const path of walk(join(root, subdir), [])) {
    const sf = source(path);
    const visit = (n: ts.Node) => {
      if (ts.isCallExpression(n) && n.arguments.length > 0) {
        const callee = n.expression;
        const name = ts.isPropertyAccessExpression(callee) ? callee.name.text : ts.isIdentifier(callee) ? callee.text : '';
        if (name === 'getConfig') {
          const arg = n.arguments[0];
          reads.push({
            file: relative(root, path),
            line: sf.getLineAndCharacterOfPosition(n.getStart()).line + 1,
            expr: arg.getText().replace(/\s+/g, ' '),
            target: resolveExpr(arg, 0),
          });
        }
      }
      ts.forEachChild(n, visit);
    };
    visit(sf);
  }
  return reads;
}