insights-js/scripts/docs/methods.js

const { ReleaseTag, ApiItemKind } = require('@microsoft/api-extractor-model');
const { getInheritanceChain } = require('./inheritance');

// for release tag mapping
const releaseTagMap = {
  [ReleaseTag.Internal]: 'internal',
  [ReleaseTag.Alpha]: 'alpha',
  [ReleaseTag.Beta]: 'beta',
  [ReleaseTag.Public]: 'public'
};

/**
 * Get method release tag
 * @param {any} apiMethod - API method to get release tag from
 * @returns {string} - Release tag string
 */
const getMethodReleaseTag = (apiMethod) => 
  releaseTagMap[apiMethod.releaseTag] || 'public';

// Deprecation detection functions
const hasDeprecatedBlock = (apiMethod) => 
  apiMethod.tsdocComment?.deprecatedBlock !== undefined;

/**
 * Check if method is deprecated
 * @param {any} apiMethod - API method to check
 * @returns {boolean} - Whether method is deprecated
 */
const isMethodDeprecated = hasDeprecatedBlock;

/**
 * Collect all public methods from a class and its inheritance chain
 * @param {any} insightsClass - Starting class
 * @param {string} rootClass - Root class name for constructor display
 * @returns {any[]} - Array of unique public methods
 */
const collectMethodsWithInheritance = (insightsClass, rootClass) => {
    if (!insightsClass) return [];

    const allMethods = new Map();
    const apiPackage = insightsClass.getAssociatedPackage();
    const inheritanceChain = getInheritanceChain(insightsClass, apiPackage);
    
    // Collect methods from each class in the inheritance chain
    for (const currentClass of inheritanceChain) {
        const inheritanceResult = currentClass.findMembersWithInheritance();
        const members = inheritanceResult.items || [];
        
        const methods = members.filter(member => {
          if (member.kind === ApiItemKind.Constructor) return true;
          if (member.kind !== ApiItemKind.Method) return false;
          // Exclude private-by-convention (leading _) and protected methods
          if (member.name.startsWith('_')) return false;
          if (member.isProtected) return false;
          return true;
        });

        // Add methods to map (child methods take precedence over parent methods)
        methods.forEach(method => {
            if (method.kind === ApiItemKind.Constructor) {
              method.name = rootClass;
            }
            if (!allMethods.has(method.name)) {
                allMethods.set(method.name, method);
            }
        });
    }
    
    return Array.from(allMethods.values());
};

module.exports = {
  getMethodReleaseTag,
  isMethodDeprecated,
  collectMethodsWithInheritance,
};