UseCmdletCorrectly.cs

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Management.Automation;
using System.Management.Automation.Language;
using Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic;
using System.Collections.Concurrent;
#if !CORECLR
using System.ComponentModel.Composition;
#endif
using System.Globalization;

namespace Microsoft.Windows.PowerShell.ScriptAnalyzer.BuiltinRules
{
    /// <summary>
    /// Use CmdletCorrectly: Check that cmdlets are invoked with the correct mandatory parameter
    /// </summary>
#if !CORECLR
[Export(typeof(IScriptRule))]
#endif
    public class UseCmdletCorrectly : IScriptRule
    {
        // Cache of the mandatory parameters of cmdlets in PackageManagement
        // Key:   Cmdlet name
        // Value: List of mandatory parameters
        private static readonly ConcurrentDictionary<string, IReadOnlyList<string>> s_pkgMgmtMandatoryParameters =
            new ConcurrentDictionary<string, IReadOnlyList<string>>(new Dictionary<string, IReadOnlyList<string>>
            {
                { "Find-Package", Array.Empty<string>() },
                { "Find-PackageProvider", Array.Empty<string>() },
                { "Get-Package", Array.Empty<string>() },
                { "Get-PackageProvider", Array.Empty<string>() },
                { "Get-PackageSource", Array.Empty<string>() },
                { "Import-PackageProvider", new string[] { "Name" } },
                { "Install-Package", new string[] { "Name" } },
                { "Install-PackageProvider", new string[] { "Name" } },
                { "Register-PackageSource", new string[] { "ProviderName" } },
                { "Save-Package", new string[] { "Name", "InputObject" } },
                { "Set-PackageSource", new string[] { "Name", "Location" } },
                { "Uninstall-Package", new string[] { "Name", "InputObject" } },
                { "Unregister-PackageSource", new string[] { "Name", "InputObject" } },
            });

        /// <summary>
        /// AnalyzeScript: Check that cmdlets are invoked with the correct mandatory parameter
        /// </summary>
        /// <param name="ast"></param>
        /// <param name="fileName"></param>
        /// <returns></returns>
        public IEnumerable<DiagnosticRecord> AnalyzeScript(Ast ast, string fileName)
        {
            if (ast == null) throw new ArgumentNullException(Strings.NullAstErrorMessage);

            // Finds all CommandAsts.
            IEnumerable<Ast> foundAsts = ast.FindAll(testAst => testAst is CommandAst, true);

            // Iterates all CommandAsts and check the command name.
            foreach (Ast foundAst in foundAsts)
            {
                CommandAst cmdAst = (CommandAst)foundAst;

                // Handles the exception caused by commands like, {& $PLINK $args 2> $TempErrorFile}.
                // You can also review the remark section in following document,
                // MSDN: CommandAst.GetCommandName Method
                if (cmdAst.GetCommandName() == null) continue;

                // Checks mandatory parameters.
                if (!MandatoryParameterExists(cmdAst))
                {
                    yield return new DiagnosticRecord(String.Format(CultureInfo.CurrentCulture, Strings.UseCmdletCorrectlyError, cmdAst.GetCommandName()),
                        cmdAst.Extent, GetName(), DiagnosticSeverity.Warning, fileName);
                }
            }
        }

        /// <summary>
        /// Return true if mandatory parameters are used OR the cmdlet does not exist
        /// </summary>
        /// <param name="cmdAst"></param>
        /// <returns></returns>
        private bool MandatoryParameterExists(CommandAst cmdAst)
        {
            #region Compares parameter list and mandatory parameter list.

            CommandInfo cmdInfo = Helper.Instance.GetCommandInfo(cmdAst.GetCommandName());

            // If we can't resolve the command or it's not a cmdlet, we are done
            if (cmdInfo == null || (cmdInfo.CommandType != System.Management.Automation.CommandTypes.Cmdlet))
            {
                return true;
            }

            // We can't statically analyze splatted variables, so ignore them
            if (Helper.Instance.HasSplattedVariable(cmdAst))
            {
                return true;
            }

            // Positional parameters could be mandatory, so we assume all is well
            if (Helper.Instance.PositionalParameterUsed(cmdAst) && Helper.Instance.IsKnownCmdletFunctionOrExternalScript(cmdAst, out _))
            {
                return true;
            }

            // If the command is piped to, this also precludes mandatory parameters
            if (cmdAst.Parent is PipelineAst parentPipeline
                && parentPipeline.PipelineElements.Count > 1
                && parentPipeline.PipelineElements[0] != cmdAst)
            {
                return true;
            }

            // We want to check cmdlets from PackageManagement separately because they experience a deadlock
            // when cmdInfo.Parameters or cmdInfo.ParameterSets is accessed.
            // See https://github.com/PowerShell/PSScriptAnalyzer/issues/1297
            if (s_pkgMgmtMandatoryParameters.TryGetValue(cmdInfo.Name, out IReadOnlyList<string> pkgMgmtCmdletMandatoryParams))
            {
                // If the command has no parameter sets with mandatory parameters, we are done
                if (pkgMgmtCmdletMandatoryParams.Count == 0)
                {
                    return true;
                }

                // We make the following simplifications here that all apply to the PackageManagement cmdlets:
                //   - Only one mandatory parameter per parameter set
                //   - Any part of the parameter prefix is valid
                //   - There are no parameter sets without mandatory parameters
                IEnumerable<CommandParameterAst> parameterAsts = cmdAst.CommandElements.OfType<CommandParameterAst>();
                foreach (string mandatoryParameter in pkgMgmtCmdletMandatoryParams)
                {
                    foreach (CommandParameterAst parameterAst in parameterAsts)
                    {
                        if (mandatoryParameter.StartsWith(parameterAst.ParameterName))
                        {
                            return true;
                        }
                    }
                }

                return false;
            }

            // Gets mandatory parameters from cmdlet.
            // If cannot find any mandatory parameter, it's not necessary to do a further check for current cmdlet.
            var mandatoryParameters = new List<ParameterMetadata>();
            try
            {
                int noOfParamSets = cmdInfo.ParameterSets.Count;
                foreach (ParameterMetadata pm in cmdInfo.Parameters.Values)
                {
                    int count = 0;

                    if (pm.Attributes.Count < noOfParamSets)
                    {
                        continue;
                    }

                    foreach (Attribute attr in pm.Attributes)
                    {
                        if (!(attr is ParameterAttribute)) continue;
                        if (((ParameterAttribute)attr).Mandatory)
                        {
                            count += 1;
                        }
                    }

                    if (count >= noOfParamSets)
                    {
                        mandatoryParameters.Add(pm);
                    }
                }
            }
            catch (Exception)
            {
                // For cases like cmd.exe. Also for runtime exception
                return true;
            }

            if (mandatoryParameters.Count == 0)
            {
                return true;
            }

            // Compares parameter list and mandatory parameter list.
            foreach (CommandElementAst commandElementAst in cmdAst.CommandElements.OfType<CommandParameterAst>())
            {
                CommandParameterAst cpAst = (CommandParameterAst)commandElementAst;
                if (mandatoryParameters.Count<ParameterMetadata>(item =>
                    item.Name.Equals(cpAst.ParameterName, StringComparison.OrdinalIgnoreCase)) > 0)
                {
                    return true;
                }
            }

            #endregion

            return false;
        }

        /// <summary>
        /// GetName: Retrieves the name of this rule.
        /// </summary>
        /// <returns>The name of this rule</returns>
        public string GetName()
        {
            return string.Format(CultureInfo.CurrentCulture, Strings.NameSpaceFormat, GetSourceName(), Strings.UseCmdletCorrectlyName);
        }

        /// <summary>
        /// GetCommonName: Retrieves the common name of this rule.
        /// </summary>
        /// <returns>The common name of this rule</returns>
        public string GetCommonName()
        {
            return string.Format(CultureInfo.CurrentCulture, Strings.UseCmdletCorrectlyCommonName);
        }

        /// <summary>
        /// GetDescription: Retrieves the description of this rule.
        /// </summary>
        /// <returns>The description of this rule</returns>
        public string GetDescription()
        {
            return string.Format(CultureInfo.CurrentCulture, Strings.UseCmdletCorrectlyDescription);
        }

        /// <summary>
        /// GetSourceType: Retrieves the type of the rule: builtin, managed or module.
        /// </summary>
        public SourceType GetSourceType()
        {
            return SourceType.Builtin;
        }

        /// <summary>
        /// GetSeverity: Retrieves the severity of the rule: error, warning of information.
        /// </summary>
        /// <returns></returns>
        public RuleSeverity GetSeverity()
        {
            return RuleSeverity.Warning;
        }

        /// <summary>
        /// GetSourceName: Retrieves the module/assembly name the rule is from.
        /// </summary>
        public string GetSourceName()
        {
            return string.Format(CultureInfo.CurrentCulture, Strings.SourceName);
        }
    }
}