worldmonitor/scripts/lib/sebuf-query-param-contract.mjs

import { existsSync, readFileSync, readdirSync } from 'node:fs';
import { basename, join, relative, sep } from 'node:path';
import ts from 'typescript';

export const NOOP_QUERY_DESCRIPTION_RE = /\b(?:accepted but currently ignored|currently (?:ignored|a no-op)|no-op|no op)\b/i;

const DEFAULT_SCOPED_PROTO_FILES = new Set([
  'worldmonitor/aviation/v1/list_airport_delays.proto',
  'worldmonitor/climate/v1/list_climate_anomalies.proto',
  'worldmonitor/conflict/v1/list_acled_events.proto',
  'worldmonitor/conflict/v1/list_ucdp_events.proto',
  'worldmonitor/cyber/v1/list_cyber_threats.proto',
  'worldmonitor/economic/v1/get_economic_calendar.proto',
  'worldmonitor/economic/v1/get_energy_capacity.proto',
  'worldmonitor/economic/v1/list_world_bank_indicators.proto',
  'worldmonitor/infrastructure/v1/list_internet_outages.proto',
  'worldmonitor/intelligence/v1/search_gdelt_documents.proto',
  'worldmonitor/maritime/v1/list_navigational_warnings.proto',
  'worldmonitor/market/v1/get_sector_summary.proto',
  'worldmonitor/market/v1/list_earnings_calendar.proto',
  'worldmonitor/military/v1/get_theater_posture.proto',
  'worldmonitor/military/v1/list_military_flights.proto',
  'worldmonitor/natural/v1/list_natural_events.proto',
  'worldmonitor/prediction/v1/list_prediction_markets.proto',
  'worldmonitor/research/v1/list_arxiv_papers.proto',
  'worldmonitor/seismology/v1/list_earthquakes.proto',
  'worldmonitor/trade/v1/get_trade_barriers.proto',
  'worldmonitor/trade/v1/get_trade_restrictions.proto',
  'worldmonitor/unrest/v1/list_unrest_events.proto',
  'worldmonitor/wildfire/v1/list_fire_detections.proto',
]);

const DEFAULT_FORCED_NOOP_QUERY_PARAMS = new Set([
  'worldmonitor/aviation/v1/list_airport_delays.proto:page_size',
  'worldmonitor/aviation/v1/list_airport_delays.proto:cursor',
  'worldmonitor/aviation/v1/list_airport_delays.proto:region',
  'worldmonitor/aviation/v1/list_airport_delays.proto:min_severity',
  'worldmonitor/climate/v1/list_climate_anomalies.proto:page_size',
  'worldmonitor/climate/v1/list_climate_anomalies.proto:cursor',
  'worldmonitor/climate/v1/list_climate_anomalies.proto:min_severity',
  'worldmonitor/conflict/v1/list_acled_events.proto:page_size',
  'worldmonitor/conflict/v1/list_acled_events.proto:cursor',
  'worldmonitor/conflict/v1/list_ucdp_events.proto:start',
  'worldmonitor/conflict/v1/list_ucdp_events.proto:end',
  'worldmonitor/conflict/v1/list_ucdp_events.proto:page_size',
  'worldmonitor/conflict/v1/list_ucdp_events.proto:cursor',
  'worldmonitor/cyber/v1/list_cyber_threats.proto:start',
  'worldmonitor/cyber/v1/list_cyber_threats.proto:end',
  'worldmonitor/economic/v1/get_economic_calendar.proto:fromDate',
  'worldmonitor/economic/v1/get_economic_calendar.proto:toDate',
  'worldmonitor/economic/v1/get_energy_capacity.proto:years',
  'worldmonitor/economic/v1/list_world_bank_indicators.proto:page_size',
  'worldmonitor/economic/v1/list_world_bank_indicators.proto:cursor',
  'worldmonitor/infrastructure/v1/list_internet_outages.proto:page_size',
  'worldmonitor/infrastructure/v1/list_internet_outages.proto:cursor',
  'worldmonitor/intelligence/v1/search_gdelt_documents.proto:timespan',
  'worldmonitor/intelligence/v1/search_gdelt_documents.proto:tone_filter',
  'worldmonitor/intelligence/v1/search_gdelt_documents.proto:sort',
  'worldmonitor/maritime/v1/list_navigational_warnings.proto:page_size',
  'worldmonitor/maritime/v1/list_navigational_warnings.proto:cursor',
  'worldmonitor/market/v1/get_sector_summary.proto:period',
  'worldmonitor/market/v1/list_earnings_calendar.proto:fromDate',
  'worldmonitor/market/v1/list_earnings_calendar.proto:toDate',
  'worldmonitor/military/v1/get_theater_posture.proto:theater',
  'worldmonitor/military/v1/list_military_flights.proto:operator',
  'worldmonitor/military/v1/list_military_flights.proto:aircraft_type',
  'worldmonitor/natural/v1/list_natural_events.proto:days',
  'worldmonitor/prediction/v1/list_prediction_markets.proto:cursor',
  'worldmonitor/research/v1/list_arxiv_papers.proto:cursor',
  'worldmonitor/research/v1/list_arxiv_papers.proto:query',
  'worldmonitor/seismology/v1/list_earthquakes.proto:start',
  'worldmonitor/seismology/v1/list_earthquakes.proto:end',
  'worldmonitor/seismology/v1/list_earthquakes.proto:cursor',
  'worldmonitor/seismology/v1/list_earthquakes.proto:min_magnitude',
  'worldmonitor/trade/v1/get_trade_barriers.proto:countries',
  'worldmonitor/trade/v1/get_trade_barriers.proto:measure_type',
  'worldmonitor/trade/v1/get_trade_restrictions.proto:countries',
  'worldmonitor/unrest/v1/list_unrest_events.proto:page_size',
  'worldmonitor/unrest/v1/list_unrest_events.proto:cursor',
  'worldmonitor/unrest/v1/list_unrest_events.proto:min_severity',
  'worldmonitor/unrest/v1/list_unrest_events.proto:ne_lat',
  'worldmonitor/unrest/v1/list_unrest_events.proto:ne_lon',
  'worldmonitor/unrest/v1/list_unrest_events.proto:sw_lat',
  'worldmonitor/unrest/v1/list_unrest_events.proto:sw_lon',
  'worldmonitor/wildfire/v1/list_fire_detections.proto:start',
  'worldmonitor/wildfire/v1/list_fire_detections.proto:end',
  'worldmonitor/wildfire/v1/list_fire_detections.proto:page_size',
  'worldmonitor/wildfire/v1/list_fire_detections.proto:cursor',
  'worldmonitor/wildfire/v1/list_fire_detections.proto:ne_lat',
  'worldmonitor/wildfire/v1/list_fire_detections.proto:ne_lon',
  'worldmonitor/wildfire/v1/list_fire_detections.proto:sw_lat',
  'worldmonitor/wildfire/v1/list_fire_detections.proto:sw_lon',
]);

function walk(dir, acc = []) {
  if (!existsSync(dir)) return acc;
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const full = join(dir, entry.name);
    if (entry.isDirectory()) {
      walk(full, acc);
    } else {
      acc.push(full);
    }
  }
  return acc;
}

function slash(path) {
  return path.split(sep).join('/');
}

function snakeToCamel(value) {
  return value.replace(/_([a-z0-9])/g, (_, ch) => ch.toUpperCase());
}

function snakeToKebab(value) {
  return value.replace(/_/g, '-');
}

function parseProtoQueryFields(protoFile) {
  const lines = readFileSync(protoFile, 'utf8').split('\n');
  const fields = [];
  let comments = [];

  for (let i = 0; i < lines.length; i++) {
    const trimmed = lines[i].trim();

    if (trimmed.startsWith('//')) {
      comments.push(trimmed.replace(/^\/\/\s?/, ''));
      continue;
    }
    if (trimmed === '') {
      comments = [];
      continue;
    }

    const fieldMatch = trimmed.match(/^(?:optional\s+|repeated\s+)?(?:map<[^>]+>|[A-Za-z_][\w.]*)\s+([a-z][a-z0-9_]*)\s*=\s*\d+\b/);
    if (!fieldMatch) {
      comments = [];
      continue;
    }

    const startLine = i + 1;
    let declaration = trimmed;
    while (!declaration.includes(';') && i + 1 < lines.length) {
      i++;
      declaration += ' ' + lines[i].trim();
    }

    if (declaration.includes('(sebuf.http.query)')) {
      const fieldName = fieldMatch[1];
      const queryName = declaration.match(/\(sebuf\.http\.query\)\s*=\s*\{[^}]*\bname\s*:\s*"([^"]+)"/)?.[1] ?? fieldName;
      fields.push({
        file: protoFile,
        line: startLine,
        fieldName,
        tsName: snakeToCamel(fieldName),
        queryName,
        unimplemented: /\(sebuf\.http\.unimplemented\)\s*=\s*true\b/.test(declaration),
        comment: comments.join(' '),
      });
    }

    comments = [];
  }

  return fields;
}

function handlerPathForProto(root, protoFile) {
  const rel = slash(relative(join(root, 'proto'), protoFile));
  const parts = rel.split('/');
  if (parts[0] !== 'worldmonitor' || parts.length < 4) return null;

  const snakeDomain = parts[1];
  const version = parts[2];
  const filename = parts[3];
  const handlerName = snakeToKebab(basename(filename, '.proto'));
  return join(root, 'server', 'worldmonitor', snakeToKebab(snakeDomain), version, handlerName + '.ts');
}

function isStringLiteralLike(node) {
  return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node);
}

function bindingElementUsesField(node, field) {
  const candidates = [node.propertyName, node.name].filter(Boolean);
  return candidates.some((candidate) => {
    if (ts.isIdentifier(candidate)) return candidate.text === field.tsName;
    if (isStringLiteralLike(candidate)) return candidate.text === field.tsName || candidate.text === field.queryName;
    return false;
  });
}

function bindingPatternUsesField(pattern, field) {
  return pattern.elements.some((element) => ts.isBindingElement(element) && bindingElementUsesField(element, field));
}

function hasExportModifier(node) {
  return Boolean(node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword));
}

function collectHandlerRequestNames(source, field) {
  const requestNames = new Set();
  let requestParamUsesField = false;

  function collectFunctionLike(node) {
    const requestParam = node.parameters[1];
    if (!requestParam) return;
    if (ts.isIdentifier(requestParam.name)) {
      requestNames.add(requestParam.name.text);
    } else if (ts.isObjectBindingPattern(requestParam.name) && bindingPatternUsesField(requestParam.name, field)) {
      requestParamUsesField = true;
    }
  }

  for (const statement of source.statements) {
    if (ts.isFunctionDeclaration(statement) && hasExportModifier(statement)) {
      collectFunctionLike(statement);
      continue;
    }

    if (!ts.isVariableStatement(statement) || !hasExportModifier(statement)) continue;
    for (const declaration of statement.declarationList.declarations) {
      const initializer = declaration.initializer;
      if (initializer && (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer))) {
        collectFunctionLike(initializer);
      }
    }
  }

  return { requestNames, requestParamUsesField };
}

function isRequestIdentifier(expression, requestNames) {
  return ts.isIdentifier(expression) && requestNames.has(expression.text);
}

function collectRequestAliases(source, requestNames) {
  const aliases = new Set(requestNames);
  let changed = true;

  while (changed) {
    changed = false;
    function visit(node) {
      if (
        ts.isVariableDeclaration(node) &&
        ts.isIdentifier(node.name) &&
        node.initializer &&
        isRequestIdentifier(node.initializer, aliases) &&
        !aliases.has(node.name.text)
      ) {
        aliases.add(node.name.text);
        changed = true;
      }
      ts.forEachChild(node, visit);
    }
    visit(source);
  }

  return aliases;
}

function bindingElementIsFromRequest(node, requestNames) {
  const pattern = node.parent;
  if (!ts.isObjectBindingPattern(pattern)) return false;
  const declaration = pattern.parent;
  return (
    ts.isVariableDeclaration(declaration) &&
    declaration.initializer &&
    isRequestIdentifier(declaration.initializer, requestNames)
  );
}

function handlerUsesField(handlerPath, field) {
  const source = ts.createSourceFile(
    handlerPath,
    readFileSync(handlerPath, 'utf8'),
    ts.ScriptTarget.Latest,
    true,
    ts.ScriptKind.TS,
  );
  const { requestNames, requestParamUsesField } = collectHandlerRequestNames(source, field);
  if (requestParamUsesField) return true;

  const requestAliases = collectRequestAliases(source, requestNames);
  if (requestAliases.size === 0) return false;

  let used = false;

  function visit(node) {
    if (used) return;

    if (
      ts.isPropertyAccessExpression(node) &&
      isRequestIdentifier(node.expression, requestAliases) &&
      node.name.text === field.tsName
    ) {
      used = true;
      return;
    }

    if (
      ts.isElementAccessExpression(node) &&
      isRequestIdentifier(node.expression, requestAliases) &&
      node.argumentExpression &&
      isStringLiteralLike(node.argumentExpression) &&
      (node.argumentExpression.text === field.tsName || node.argumentExpression.text === field.queryName)
    ) {
      used = true;
      return;
    }

    if (ts.isBindingElement(node) && bindingElementIsFromRequest(node, requestAliases) && bindingElementUsesField(node, field)) {
      used = true;
      return;
    }

    ts.forEachChild(node, visit);
  }

  visit(source);
  return used;
}

export function collectQueryParamContractViolations(root, options = {}) {
  const scopedProtoFiles = options.scopedProtoFiles ?? DEFAULT_SCOPED_PROTO_FILES;
  const forcedNoopQueryParams = options.forcedNoopQueryParams ?? DEFAULT_FORCED_NOOP_QUERY_PARAMS;
  const seenQueryParams = new Set();
  const protoRoot = join(root, 'proto', 'worldmonitor');
  const protoFiles = walk(protoRoot).filter((file) => file.endsWith('.proto'));
  const violations = [];
  const stats = {
    protoFiles: protoFiles.length,
    queryFields: 0,
    unimplementedFields: 0,
    scopedQueryFields: 0,
  };

  for (const protoFile of protoFiles) {
    const handlerPath = handlerPathForProto(root, protoFile);
    const fields = parseProtoQueryFields(protoFile);
    if (fields.length === 0) continue;

    const protoRel = slash(relative(join(root, 'proto'), protoFile));
    const isScopedProto = scopedProtoFiles.has(protoRel);
    const hasAnnotatedField = fields.some((field) => field.unimplemented);
    if (!isScopedProto && !hasAnnotatedField) continue;

    if (!handlerPath || !existsSync(handlerPath)) {
      for (const field of fields) {
        violations.push({
          file: slash(relative(root, field.file)) + ':' + field.line,
          message: 'query param "' + field.queryName + '" has no matching handler file to verify',
          remedy: 'Restore the server/worldmonitor handler or move/remove the query annotation.',
        });
      }
      continue;
    }

    for (const field of fields) {
      stats.queryFields++;
      if (isScopedProto) stats.scopedQueryFields++;
      if (field.unimplemented) stats.unimplementedFields++;

      const queryParamKey = protoRel + ':' + field.queryName;
      seenQueryParams.add(queryParamKey);
      const mustBeNoop = forcedNoopQueryParams.has(queryParamKey);
      const relativeField = slash(relative(root, field.file)) + ':' + field.line;
      if (field.unimplemented && !NOOP_QUERY_DESCRIPTION_RE.test(field.comment)) {
        violations.push({
          file: relativeField,
          message: 'query param "' + field.queryName + '" is marked unimplemented but its proto comment does not disclose accepted-but-ignored/no-op behavior',
          remedy: 'Update the field comment so generated OpenAPI explicitly states the parameter is currently a no-op.',
        });
      }

      if (mustBeNoop && !field.unimplemented) {
        violations.push({
          file: relativeField,
          message: 'query param "' + field.queryName + '" is in the #4607 no-op registry but is not marked unimplemented',
          remedy: 'Mark the proto field with (sebuf.http.unimplemented) = true and document the accepted-but-ignored behavior.',
        });
      }

      if (isScopedProto && !field.unimplemented && !handlerUsesField(handlerPath, field)) {
        violations.push({
          file: relativeField,
          message: 'query param "' + field.queryName + '" is declared but not referenced by ' + slash(relative(root, handlerPath)),
          remedy: 'Implement the parameter in the handler, or mark the proto field with (sebuf.http.unimplemented) = true and document the no-op behavior in the field comment.',
        });
      }
    }
  }

  for (const forced of forcedNoopQueryParams) {
    if (!seenQueryParams.has(forced)) {
      violations.push({
        file: 'scripts/lib/sebuf-query-param-contract.mjs',
        message: '#4607 no-op registry entry "' + forced + '" no longer matches a proto query param',
        remedy: 'Update the registry after renaming/removing the query param, or restore the proto annotation.',
      });
    }
  }

  return { violations, stats };
}