Merge branch 'topic/gnatcheck/import_in_rule_files' into 'master'

Implement features required for LKQL rule files composition

Closes #470

See merge request eng/libadalang/langkit-query-language!437

Author: HugoGGuerrier

lkql_checker/doc/gnatcheck_rm/using_gnatcheck.rst

@@ -239,6 +239,13 @@ The following switches control the general ``gnatcheck`` behavior
   Specify the charset of the source files. By default, ``ISO-8859-1`` is
   used if no charset is specified.
 
+  .. index:: --lkql-path
+
+``--lkql-path=dir``
+  Specify directory to add to the ``LKQL_PATH`` environment variable when
+  GNATcheck is spawning the LKQL engine. You can specify this option multiple
+  times to add multiple directories.
+
   .. index:: --rules-dir
 
 ``--rules-dir=dir``
@@ -361,6 +368,16 @@ GNATcheck:
   file defining this attribute, then, an error is emitted and ``gnatcheck``
   will exit with an error code.
 
+``Lkql_Path``
+  Value is a list of directories to add to the ``LKQL_PATH`` environment
+  variable when GNATcheck is spawning the LKQL engine. This variable is
+  used to resolve module importations in LKQL sources. If not absolute, paths
+  provided through this attribute are relatives to the project file defining
+  it.
+
+  This attributes may work combined with the ``--lkql-path`` switch, in that
+  case, all directories are added to the ``LKQL_PATH`` environment variable.
+
 ``Switches``
   Index is a language name. Value is a list of additional switches to be used
   when invoking ``gnatcheck``.
@@ -381,6 +398,7 @@ GNATcheck:
     * ``-eL``
     * ``-r, --rule [rule_name]`` (use ``Rules`` attribute instead)
     * ``--rule-file=filename`` (use ``Rule_File`` attribute instead)
+    * ``--lkql-path=dir`` (use ``Lkql_Path`` attributes instead)
     * ``--target`` (use the ``Target`` GPR attribute instead)
     * ``--RTS`` (use the ``Runtime`` GPR attribute instead)
 
@@ -456,9 +474,9 @@ it was provided by the --rule-file option.
 An LKQL rule file can be any valid LKQL file, the only requirement is that it
 must export a ``rules`` top-level symbol. This symbol defines an object value
 containing rules configuration; keys are GNATcheck rules to enable; and values
-are objects containing the rule parameters. A rule parameter value can be of
-the boolean, the integer, the string, or the list of strings type, as shown in
-the simple example below:
+are list of objects, each one representing an instance of the rule with its
+parameters. A rule parameter value can be of the boolean, the integer, the
+string, or the list of strings type, as shown in the simple example below:
 
 ::
 
@@ -467,6 +485,9 @@ the simple example below:
     Forbidden_Attributes: {Forbidden: ["GNAT"], Allowed: ["First", "Last"]}
   }
 
+Using the "@" object notation is strongly advised to make your configuration
+file way more understandable:
+
 Please read the :ref:`Predefined_Rules` documentation to view examples on how
 to provide parameters to rules through LKQL rule files.
 
@@ -543,7 +564,7 @@ the following configuration will raise an error:
 ::
 
   val spark_rules = @{
-    Warnings: "a"
+    Warnings: {Arg: "a"}
   }
 
 .. attention::
@@ -569,6 +590,62 @@ the following configuration will raise an error:
       Forbidden_Attributes: {Forbidden: ["Length"], instance_name: "Forbid_Attr"}
     }
 
+You cannot provide more than **one** LKQL rule file when running GNATcheck. In
+order to compose a rule file with another you have to use the
+:ref:`LKQL importation mechanism<module_importation>` and concatenate rule
+objects. Here is an example of LKQL rule file composition:
+
+.. code-block:: lkql
+
+  # common_rules.lkql
+
+  val rules = @{
+    Goto_Statements
+  }
+
+.. code-block:: lkql
+
+  # specific_rules.lkql
+
+  import common_rules
+
+  val rules = common_rules.rules & @{
+    Redundant_Null_Statements
+  }
+
+Then you can run GNATcheck with the ``specific_rules.lkql`` file as coding
+standard to perform rules defined in ``common_rules.lkql`` combined to the ones
+defined in ``specific_rules.lkql``.
+
+.. note::
+
+  You can use the ``--lkql-path`` command-line switch and the
+  ``Check'Lkql_Path`` GPR attribute to configure directories LKQL rule files
+  are going to be searched in.
+
+You can enable the same rule in multiple files, but the constraint about the
+instance name uniqueness remains valid, meaning that such configuration is
+invalid:
+
+.. code-block:: lkql
+
+  # common_rules.lkql
+
+  val rules = @{
+    Forbidden_Attributes: {Forbidden: ["First"], instance_name: "Forbid_Attr"}
+  }
+
+.. code-block:: lkql
+
+  # specific_rules.lkql
+
+  import common_rules
+
+  val rules = common_rules.rules & @{
+    Forbidden_Attributes: {Forbidden: ["Last"], instance_name: "Forbid_Attr"}
+  }
+  # error: This rule configuration defines two instances with the same name: "Forbid_Attr"
+
 
 .. _gnatcheck_Rule_Options:
 

lkql_checker/src/gnatcheck-options.ads

@@ -14,6 +14,7 @@ with Ada.Strings.Unbounded; use Ada.Strings.Unbounded;
 with GNAT.OS_Lib;
 
 with Gnatcheck.Projects;
+with Gnatcheck.String_Utilities; use Gnatcheck.String_Utilities;
 
 with GNATCOLL.Opt_Parse; use GNATCOLL.Opt_Parse;
 
@@ -179,6 +180,10 @@ package Gnatcheck.Options is
    --  This variable should contain a full list of compilation options to be
    --  passed to gcc.
 
+   Additional_Lkql_Paths : String_Vector;
+   --  Additional paths to add to the ``LKQL_PATH`` environment variable when
+   --  spawning the LKQL worker.
+
    Instance_Help_Emitted : Boolean := False;
    --  Whether the help message about the new instance system has already been
    --  emitted. This message should be removed in 26.0.
@@ -272,6 +277,16 @@ package Gnatcheck.Options is
              "specify the charset of the source files (default is "
              & "latin-1)");
 
+      package Lkql_Path is new
+        Parse_Option_List
+          (Parser     => Parser,
+           Long       => "--lkql-path",
+           Arg_Type   => Unbounded_String,
+           Accumulate => True,
+           Help       =>
+             "specify directories to add to the 'LKQL_PATH' environment "
+             & "variable when spawning the LKQL worker");
+
       package Rules_Dirs is new
         Parse_Option_List
           (Parser     => Parser,

lkql_checker/src/gnatcheck-projects.adb

@@ -70,6 +70,8 @@ package body Gnatcheck.Projects is
      (GPR2."+" ("Check"), GPR2."+" ("Rules"));
    Rule_File_Attr        : constant GPR2.Q_Attribute_Id :=
      (GPR2."+" ("Check"), GPR2."+" ("Rule_File"));
+   Lkql_Path_Attr        : constant GPR2.Q_Attribute_Id :=
+     (GPR2."+" ("Check"), GPR2."+" ("Lkql_Path"));
    Default_Switches_Attr : constant GPR2.Q_Attribute_Id :=
      (GPR2."+" ("Check"), GPR2."+" ("Default_Switches"));
    Switches_Attr         : constant GPR2.Q_Attribute_Id :=
@@ -274,6 +276,17 @@ package body Gnatcheck.Projects is
          end;
       end if;
 
+      --  Process the LKQL path
+      if Proj.Has_Attribute (Lkql_Path_Attr) then
+         List_Val := Load_List_Attribute (Lkql_Path_Attr);
+         for Path of List_Val.all loop
+            Additional_Lkql_Paths.Append
+              (if Is_Absolute_Path (Path.all)
+               then Path.all
+               else Gnatcheck_Prj.Get_Project_Relative_File (Path.all));
+         end loop;
+      end if;
+
       --  Process additional GNATcheck switches
       if Proj.Has_Attribute (Switches_Attr, Ada_Idx) then
          List_Val := Load_List_Attribute (Switches_Attr, Indexed => True);
@@ -753,6 +766,17 @@ package body Gnatcheck.Projects is
         (Rule_File_Attr,
          "Value is the name of an LKQL rule file to use when running "
          & "GNATcheck in this project.");
+      Add
+        (Lkql_Path_Attr,
+         Index_Type           => GPR2.Project.Registry.Attribute.No_Index,
+         Value                => List,
+         Value_Case_Sensitive => True,
+         Is_Allowed_In        => Everywhere);
+      GPR2.Project.Registry.Attribute.Description.Set_Attribute_Description
+        (Lkql_Path_Attr,
+         "Value is a list of directories to add to the LKQL_PATH environment "
+         & "variable when GNATcheck is spawning the LKQL engine. This "
+         & "variable is used to resolve module importations in LKQL sources.");
       Add
         (Switches_Attr,
          Index_Type           => Language_Index,
@@ -1266,6 +1290,7 @@ package body Gnatcheck.Projects is
             Disallow (Arg.Transitive_Closure.This, "-U" & In_Project_Msg);
             Disallow (Arg.Scenario_Vars.This, "-Xname=val" & In_Project_Msg);
             Disallow (Arg.Follow_Symbolic_Links.This, "-eL" & In_Project_Msg);
+            Disallow (Arg.Lkql_Path.This, "--lkql-path" & In_Project_Msg);
             Disallow (Arg.Rules.This, "-r" & In_Project_Msg);
             Disallow (Arg.Rule_File.This, "--rule-file" & In_Project_Msg);
             Disallow (Arg.Target.This, "--target" & In_Project_Msg);
@@ -1291,6 +1316,7 @@ package body Gnatcheck.Projects is
          Allow (Arg.Aggregate_Subproject.This);
          Allow (Arg.Project_File.This);
          Allow (Arg.Follow_Symbolic_Links.This);
+         Allow (Arg.Lkql_Path.This);
          Allow (Arg.Rules.This);
          Allow (Arg.Rule_File.This);
          Allow (Arg.Target.This);

lkql_checker/src/gnatcheck_main.adb

@@ -129,6 +129,10 @@ procedure Gnatcheck_Main is
 
          Add_Path ("LD_LIBRARY_PATH", Lib);
          Add_Path ("LD_LIBRARY_PATH", Lib_LAL);
+
+         for Path of Additional_Lkql_Paths loop
+            Add_Path ("LKQL_PATH", Path);
+         end loop;
       end;
 
       Free (Executable);
@@ -484,6 +488,13 @@ begin
       Add_Rule_By_Name (To_String (Rule), Prepend => True);
    end loop;
 
+   --  Add the command-line LKQL_PATH elements to the vector of additional
+   --  searching paths.
+   for Working_Dir_Path of Arg.Lkql_Path.Get loop
+      Additional_Lkql_Paths.Append
+        (Normalize_Pathname (To_String (Working_Dir_Path)));
+   end loop;
+
    --  Then analyze the command-line parameters
 
    Gnatcheck_Prj.Scan_Arguments;

lkql_jit/cli/src/main/java/com/adacore/lkql_jit/cli/GNATCheckWorker.java

@@ -399,50 +399,19 @@ private static void processInstancesObject(
 
             // Check that the value associated to the rule name is an array like value
             if (args.hasArrayElements()) {
-                // If there is no element in the argument list, just create an instance with no
-                // argument and no alias.
-                if (args.getArraySize() == 0) {
-                    if (toPopulate.containsKey(lowerRuleName)) {
-                        errorInLKQLRuleFile(
-                            lkqlRuleFile,
-                            "Multiple instances with the same name: " + lowerRuleName
-                        );
-                    } else {
-                        toPopulate.put(
-                            lowerRuleName,
-                            new RuleInstance(
-                                lowerRuleName,
-                                Optional.empty(),
-                                sourceMode,
-                                new HashMap<>()
-                            )
-                        );
-                    }
-                }
                 // Else iterate over each argument object and create one instance for each
-                else {
-                    for (long i = 0; i < args.getArraySize(); i++) {
-                        processArgsObject(
-                            lkqlRuleFile,
-                            args.getArrayElement(i),
-                            sourceMode,
-                            lowerRuleName,
-                            toPopulate
-                        );
+                for (long i = 0; i < args.getArraySize(); i++) {
+                    var arg = args.getArrayElement(i);
+                    if (arg.hasMembers()) {
+                        processArgsObject(lkqlRuleFile, arg, sourceMode, lowerRuleName, toPopulate);
+                    } else if (acceptSoleArgs(ruleName) && arg.isString()) {
+                        processSoleArg(arg, sourceMode, ruleName, toPopulate);
+                    } else {
+                        errorInLKQLRuleFile(lkqlRuleFile, "Arguments should be in an object value");
                     }
                 }
-            } else if (args.hasMembers()) {
-                processArgsObject(lkqlRuleFile, args, sourceMode, lowerRuleName, toPopulate);
             } else {
-                // Allow sole arguments for some rules
-                if (acceptSoleArgs(lowerRuleName) && args.isString()) {
-                    processSoleArg(args, sourceMode, lowerRuleName, toPopulate);
-                } else {
-                    errorInLKQLRuleFile(
-                        lkqlRuleFile,
-                        "Rule arguments must be an object or indexable value"
-                    );
-                }
+                errorInLKQLRuleFile(lkqlRuleFile, "The value associated to a rule must be a list");
             }
         }
     }
@@ -455,43 +424,36 @@ private static void processArgsObject(
         final String ruleName,
         final Map<String, RuleInstance> toPopulate
     ) throws LKQLRuleFileError {
-        // Ensure that the given value has members (is an object)
-        if (!argsObject.hasMembers()) {
-            errorInLKQLRuleFile(lkqlRuleFile, "Arguments should be in an object value");
-        }
-        // If this is a valid value, process arguments in it
-        else {
-            // Compute the instance arguments and optional instance name
-            String instanceId = ruleName;
-            Optional<String> instanceName = Optional.empty();
-            Map<String, String> arguments = new HashMap<>();
-            for (String argName : argsObject.getMemberKeys()) {
-                if (argName.equals("instance_name")) {
-                    String aliasName = argsObject.getMember("instance_name").asString();
-                    instanceId = aliasName.toLowerCase();
-                    instanceName = Optional.of(aliasName);
-                } else {
-                    Value argValue = argsObject.getMember(argName);
-                    arguments.put(
-                        argName,
-                        argValue.isString() ? "\"" + argValue + "\"" : argValue.toString()
-                    );
-                }
-            }
-
-            // Add an instance in the instance map if it is not present
-            if (toPopulate.containsKey(instanceId)) {
-                errorInLKQLRuleFile(
-                    lkqlRuleFile,
-                    "Multiple instances with the same name: " + instanceId
-                );
+        // Compute the instance arguments and optional instance name
+        String instanceId = ruleName;
+        Optional<String> instanceName = Optional.empty();
+        Map<String, String> arguments = new HashMap<>();
+        for (String argName : argsObject.getMemberKeys()) {
+            if (argName.equals("instance_name")) {
+                String aliasName = argsObject.getMember("instance_name").asString();
+                instanceId = aliasName.toLowerCase();
+                instanceName = Optional.of(aliasName);
             } else {
-                toPopulate.put(
-                    instanceId,
-                    new RuleInstance(ruleName, instanceName, sourceMode, arguments)
+                Value argValue = argsObject.getMember(argName);
+                arguments.put(
+                    argName,
+                    argValue.isString() ? "\"" + argValue + "\"" : argValue.toString()
                 );
             }
         }
+
+        // Add an instance in the instance map if it is not present
+        if (toPopulate.containsKey(instanceId)) {
+            errorInLKQLRuleFile(
+                lkqlRuleFile,
+                "Multiple instances with the same name: " + instanceId
+            );
+        } else {
+            toPopulate.put(
+                instanceId,
+                new RuleInstance(ruleName, instanceName, sourceMode, arguments)
+            );
+        }
     }
 
     /** Internal function to process a sole string argument for a compiler-based rule. */

lkql_jit/language/src/main/java/com/adacore/lkql_jit/LKQLContext.java

@@ -52,6 +52,9 @@ public final class LKQLContext {
     /** The call stack of the current language thread. */
     public final CallStack callStack = new CallStack();
 
+    /** The stack representing the current LKQL source chain. */
+    public final Stack<Source> fromStack = new Stack<>();
+
     // ----- Ada project attributes -----
 
     /** The analysis context for the ada files. */