feat(api): Accept structured imports [LNG-288] (#989)

* Refactor sources

* Fix FuncCompiler compilation

* Normalize imports

* Add relative imports

* Remove Prelude

* Remove import

* Add a log

* Add more logs

* Use snapshot of fs2

* Remove prints

* Add comments

* Savepoint

* Rewrite imports resolution

* Fix relative import

* Add comment

* Added comments

* Fix comment

* Add comments

* Refactor

* Refactor

* Add tests

* Fix tests

* Update tests

* Add comment

* Lower number of tests

* Comment, rename

* Add comment

* Add emptiness check

api/api-npm/index.d.ts

@@ -20,11 +20,47 @@ export declare class CompilationResult {
   warnings: string[];
   generatedSources: GeneratedSource[];
 }
+/**
+ * Imports configuration for the compiler.
+ * Structure:
+ * {
+ *  "<compiled-path-prefix-1>": {
+ *   "<import-path-prefix-1>": ["<import-path-1>", "<import-path-2>"],
+ *   "<import-path-prefix-2>": "<import-path-3>",
+ *   ...
+ *  }
+ *  ...
+ * }
+ * Import `import` written in file with path `path`
+ * is resolved as follows:
+ * 1. Try to resolve `import` as relative import from `path`
+ * 2. If relative resolution failed:
+ *  a. Find **the longest** <compiled-path-prefix>
+ *     that is a prefix of `path` in the imports configuration
+ *  b. In obtained map, find **the longest** <import-path-prefix>
+ *     that is a prefix of `import`
+ *  c. Replace prefix in `import` with <import-path>
+ *  d. Try to resolve import with obtained path
+ *     (try a few paths if array was provided)
+ *
+ * WARNING: <compiled-path-prefix> in 2.a is compared with
+ *          absolute normalized path of `path`, so <compiled-path-prefix>
+ *          should be absolute normalized path as well
+ * NOTE: <import-path-prefix> could be empty string,
+ *       in which case it will match any import
+ * NOTE: passing just an array of strings is a shorthand for
+ * {
+ *   "/": {
+ *     "": <array>
+ *   }
+ * }
+ */
+type Imports = Record<string, Record<string, string[] | string>> | string[];
 
 /** Common arguments for all compile functions */
 type CommonArgs = {
-  /** Paths to directories, which you want to import .aqua files from. Example: ["./path/to/dir"] */
-  imports?: string[] | undefined;
+  /** Imports */
+  imports?: Imports | undefined;
   /** Constants to be passed to the compiler. Example: ["CONSTANT1=1", "CONSTANT2=2"] */
   constants?: string[] | undefined;
   /** Set log level for the compiler. Must be one of: Must be one of: all, trace, debug, info, warn, error, off. Default: info */

api/api-npm/index.js

@@ -24,6 +24,33 @@ function getConfig({
   );
 }
 
+function normalizeImports(imports) {
+  if (imports === undefined || imports === null) {
+    return {}; // No imports
+  }
+
+  if (Array.isArray(imports)) {
+    return {
+      "/": {
+        "": imports,
+      },
+    };
+  }
+
+  // Transform each inner string into an array
+  return Object.fromEntries(
+    Object.entries(imports).map(([pathPrefix, info]) => [
+      pathPrefix,
+      Object.fromEntries(
+        Object.entries(info).map(([importPrefix, locations]) => [
+          importPrefix,
+          Array.isArray(locations) ? locations : [locations],
+        ]),
+      ),
+    ]),
+  );
+}
+
 async function compile(...args) {
   try {
     const res = await Aqua.compile(...args);
@@ -42,11 +69,19 @@ async function compile(...args) {
 }
 
 export function compileFromString({ code, imports = [], ...commonArgs }) {
-  return compile(new Input(code), imports, getConfig(commonArgs));
+  return compile(
+    new Input(code),
+    normalizeImports(imports),
+    getConfig(commonArgs),
+  );
 }
 
 export function compileFromPath({ filePath, imports = [], ...commonArgs }) {
-  return compile(new Path(filePath), imports, getConfig(commonArgs));
+  return compile(
+    new Path(filePath),
+    normalizeImports(imports),
+    getConfig(commonArgs),
+  );
 }
 
 export function compileAquaCallFromString({
@@ -58,7 +93,7 @@ export function compileAquaCallFromString({
 }) {
   return compile(
     new Call(funcCall, data, new Input(code)),
-    imports,
+    normalizeImports(imports),
     getConfig(commonArgs),
   );
 }
@@ -72,7 +107,7 @@ export function compileAquaCallFromPath({
 }) {
   return compile(
     new Call(funcCall, data, new Input(filePath)),
-    imports,
+    normalizeImports(imports),
     getConfig(commonArgs),
   );
 }