skir 0.0.1 → 0.0.2

package/src/module_set.ts

@@ -1,40 +1,44 @@
 import * as paths from "path";
+import {
+  unquoteAndUnescape,
+  type DenseJson,
+  type ErrorSink,
+  type FieldPath,
+  type Import,
+  type ImportAlias,
+  type Method,
+  type Module,
+  type MutableArrayType,
+  type MutableConstant,
+  type MutableDocReference,
+  type MutableMethod,
+  type MutableModule,
+  type MutableRecord,
+  type MutableRecordField,
+  type MutableRecordLocation,
+  type MutableResolvedType,
+  type MutableValue,
+  type Record,
+  type RecordKey,
+  type RecordLocation,
+  type ResolvedRecordRef,
+  type ResolvedType,
+  type Result,
+  type SkirError,
+  type Token,
+  type UnresolvedRecordRef,
+  type UnresolvedType,
+  type Value,
+} from "skir-internal";
 import { FileReader } from "./io.js";
 import {
   isStringLiteral,
   literalValueToDenseJson,
   literalValueToIdentity,
-  unquoteAndUnescape,
   valueHasPrimitiveType,
 } from "./literals.js";
 import { parseModule } from "./parser.js";
 import { tokenizeModule } from "./tokenizer.js";
-import type {
-  DenseJson,
-  ErrorSink,
-  FieldPath,
-  Import,
-  ImportAlias,
-  Method,
-  Module,
-  MutableArrayType,
-  MutableModule,
-  MutableRecord,
-  MutableRecordLocation,
-  MutableResolvedType,
-  MutableValue,
-  Record,
-  RecordKey,
-  RecordLocation,
-  ResolvedRecordRef,
-  ResolvedType,
-  Result,
-  SkirError,
-  Token,
-  UnresolvedRecordRef,
-  UnresolvedType,
-  Value,
-} from "./types.js";
 
 export class ModuleSet {
   static create(fileReader: FileReader, rootPath: string): ModuleSet {
@@ -42,7 +46,11 @@ export class ModuleSet {
   }
 
   static fromMap(map: ReadonlyMap<string, string>): ModuleSet {
-    return new ModuleSet(new MapBasedModuleParser(map));
+    const result = new ModuleSet(new MapBasedModuleParser(map));
+    for (const modulePath of map.keys()) {
+      result.parseAndResolve(modulePath);
+    }
+    return result;
   }
 
   constructor(private readonly moduleParser: ModuleParser) {}
@@ -141,6 +149,29 @@ export class ModuleSet {
             errorIsInOtherModule: true,
           });
         }
+      } else if (declaration.kind === "import") {
+        // Make sure that the symbols we are importing exist in the imported
+        // module and are not imported symbols themselves.
+        for (const importedName of declaration.importedNames) {
+          const importedDeclaration =
+            otherModule.result.nameToDeclaration[importedName.text];
+          if (importedDeclaration === undefined) {
+            errors.push({
+              token: importedName,
+              message: "Not found",
+            });
+          } else if (importedDeclaration.kind === "import") {
+            errors.push({
+              token: importedName,
+              message: "Cannot reimport imported record",
+            });
+          } else if (importedDeclaration.kind !== "record") {
+            errors.push({
+              token: importedName,
+              message: "Not a record",
+            });
+          }
+        }
       }
     }
 
@@ -232,7 +263,6 @@ export class ModuleSet {
     const usedImports = new Set<string>();
     const typeResolver = new TypeResolver(
       module,
-      modulePath,
       this.modules,
       usedImports,
       errors,
@@ -248,16 +278,25 @@ export class ModuleSet {
       // type depends on the record where the field is defined.
       // Store the result in the Field object.
       this.storeFieldRecursivity(record);
-      // If the record has explicit numbering, register an error if any field
-      // has a direct dependency on a record with implicit numbering.
-      this.verifyNumberingConstraint(record, errors);
       // Verify that the `key` field of every array type is valid.
       for (const field of record.fields) {
         const { type } = field;
         if (type) {
           this.validateArrayKeys(type, errors);
         }
+        // Resolve the references in the doc comments of the field.
+        this.resolveDocReferences(
+          {
+            kind: "field",
+            field: field,
+            record: record,
+          },
+          module,
+          errors,
+        );
       }
+      // Resolve the references in the doc comments of the record.
+      this.resolveDocReferences(record, module, errors);
     }
     // Resolve every request/response type of every method in the module.
     // Store the result in the Method object.
@@ -290,6 +329,8 @@ export class ModuleSet {
           message: `Same number as ${otherMethodName} in ${otherModulePath}`,
         });
       }
+      // Resolve the references in the doc comments of the method.
+      this.resolveDocReferences(method, module, errors);
     }
     // Resolve every constant type. Store the result in the constant object.
     for (const constant of module.constants) {
@@ -301,6 +342,8 @@ export class ModuleSet {
         constant.valueAsDenseJson = //
           this.valueToDenseJson(constant.value, type, errors);
       }
+      // Resolve the references in the doc comments of the constant.
+      this.resolveDocReferences(constant, module, errors);
     }
 
     ensureAllImportsAreUsed(module, usedImports, errors);
@@ -371,46 +414,6 @@ export class ModuleSet {
     }
   }
 
-  /**
-   * If the record has explicit numbering, register an error if any field has a
-   * direct dependency on a record with implicit numbering.
-   */
-  private verifyNumberingConstraint(record: Record, errors: ErrorSink): void {
-    if (record.numbering !== "explicit") {
-      return;
-    }
-    for (const field of record.fields) {
-      if (!field.type) continue;
-      const invalidRef = this.referencesImplicitlyNumberedRecord(field.type);
-      if (invalidRef) {
-        errors.push({
-          token: invalidRef.refToken,
-          message:
-            `Field type references a ${invalidRef.recordType} with implicit ` +
-            `numbering, but field belongs to a ${record.recordType} with ` +
-            `explicit numbering`,
-        });
-      }
-    }
-  }
-
-  private referencesImplicitlyNumberedRecord(
-    input: ResolvedType,
-  ): ResolvedRecordRef | false {
-    switch (input.kind) {
-      case "array":
-        return this.referencesImplicitlyNumberedRecord(input.item);
-      case "optional":
-        return this.referencesImplicitlyNumberedRecord(input.other);
-      case "primitive":
-        return false;
-      case "record": {
-        const record = this.recordMap.get(input.key)!.record;
-        return record.numbering === "implicit" && input;
-      }
-    }
-  }
-
   /**
    * Verifies that the `key` field of every array type found in `topLevelType`
    * is valid. Populates the `keyType` field of every field path.
@@ -467,7 +470,7 @@ export class ModuleSet {
           if (fieldName.text !== "kind") {
             errors.push({
               token: fieldName,
-              expected: '"kind"',
+              expected: "'kind'",
             });
             return undefined;
           }
@@ -799,6 +802,171 @@ export class ModuleSet {
     }
   }
 
+  /** Resolve the references in the doc comments of the given declaration. */
+  private resolveDocReferences(
+    documentee:
+      | MutableConstant
+      | MutableMethod
+      | MutableRecord
+      | MutableRecordField,
+    module: Module,
+    errors: ErrorSink,
+  ): void {
+    const doc =
+      documentee.kind === "field" ? documentee.field.doc : documentee.doc;
+
+    const docReferences = doc.pieces.filter(
+      (p): p is MutableDocReference => p.kind === "reference",
+    );
+    if (docReferences.length <= 0) {
+      return;
+    }
+
+    // Try to resolve a reference by looking it up in the given scope.
+    // Returns true if resolved, false otherwise.
+    const tryResolveReference = (
+      ref: MutableDocReference,
+      nameChain: readonly Token[],
+      scope: Record | Module,
+    ): boolean => {
+      if (ref.absolute && scope !== module) {
+        return false;
+      }
+      const firstName = nameChain[0]!;
+      const match = scope.nameToDeclaration[firstName.text];
+      if (!match) {
+        return false;
+      }
+      if (nameChain.length === 1) {
+        // Single name: must refer to a declaration.
+        switch (match.kind) {
+          case "constant":
+          case "method":
+          case "record": {
+            ref.referee = match;
+            return true;
+          }
+          case "field": {
+            if (scope.kind !== "record") {
+              throw new TypeError(scope.kind);
+            }
+            ref.referee = {
+              kind: "field",
+              field: match,
+              record: scope,
+            };
+            return true;
+          }
+          case "import":
+          case "import-alias":
+          case "removed":
+            return false;
+        }
+      } else {
+        // Multi-part name: first part must be a naming scope.
+        switch (match.kind) {
+          case "record":
+            return tryResolveReference(ref, nameChain.slice(1), match);
+          case "import":
+          case "import-alias": {
+            if (scope !== module) {
+              // Cannot refer to other module's imports.
+              return false;
+            }
+            const { resolvedModulePath } = match;
+            if (!resolvedModulePath) {
+              return false;
+            }
+            const importedModule = this.modules.get(resolvedModulePath!);
+            if (!importedModule?.result) {
+              return false;
+            }
+            const newNameChain = nameChain.slice(
+              match.kind === "import" ? 0 : 1,
+            );
+            return tryResolveReference(
+              ref,
+              newNameChain,
+              importedModule.result,
+            );
+          }
+          case "constant":
+          case "field":
+          case "method":
+          case "removed":
+            return false;
+        }
+      }
+    };
+
+    const { recordMap } = this;
+    // Build list of naming scopes to search, in order of priority.
+    const scopes: Array<Record | Module> = [];
+    const pushRecordAncestorsToScopes = (record: Record): void => {
+      const { key } = record;
+      const location = recordMap.get(key)!;
+      const ancestors = [...location.recordAncestors].reverse();
+      for (const ancestor of ancestors) {
+        scopes.push(ancestor);
+      }
+    };
+    const pushTypeToScopes = (type: ResolvedType | undefined): void => {
+      if (type) {
+        const recordKey = tryFindRecordForType(type);
+        if (recordKey) {
+          const { record } = recordMap.get(recordKey)!;
+          scopes.push(record);
+        }
+      }
+    };
+    switch (documentee.kind) {
+      case "constant": {
+        scopes.push(module);
+        pushTypeToScopes(documentee.type);
+        break;
+      }
+      case "field": {
+        const { field, record } = documentee;
+        pushRecordAncestorsToScopes(record);
+        scopes.push(module);
+        pushTypeToScopes(field.type);
+        break;
+      }
+      case "method": {
+        scopes.push(module);
+        pushTypeToScopes(documentee.requestType);
+        pushTypeToScopes(documentee.responseType);
+        break;
+      }
+      case "record": {
+        pushRecordAncestorsToScopes(documentee);
+        scopes.push(module);
+        break;
+      }
+    }
+
+    // Resolve each reference by searching through scopes in priority order.
+    for (const reference of docReferences) {
+      const { nameChain } = reference;
+      if (nameChain.length <= 0) {
+        continue;
+      }
+      let resolved = false;
+      for (const scope of scopes) {
+        if (tryResolveReference(reference, nameChain, scope)) {
+          resolved = true;
+          break;
+        }
+      }
+      if (!resolved) {
+        errors.push({
+          token: reference.referenceRange,
+          message: "Cannot resolve reference",
+        });
+      }
+    }
+  }
+
   private readonly modules = new Map<string, Result<Module | null>>();
   private readonly mutableRecordMap = new Map<RecordKey, RecordLocation>();
   private readonly mutableResolvedModules: MutableModule[] = [];
@@ -916,7 +1084,6 @@ function validateKeyedItems(
 class TypeResolver {
   constructor(
     private readonly module: Module,
-    private readonly modulePath: string,
     private readonly modules: Map<string, Result<Module | null>>,
     private readonly usedImports: Set<string>,
     private readonly errors: ErrorSink,
@@ -1006,12 +1173,12 @@ class TypeResolver {
       } else if (newIt.kind === "record") {
         it = newIt;
       } else if (newIt.kind === "import" || newIt.kind === "import-alias") {
-        const cannotReimportError = (): SkirError => ({
+        const transitiveImportError = (): SkirError => ({
           token: namePart,
-          message: `Cannot reimport imported name '${name}'`,
+          message: "Cannot refer to imports of imported module",
         });
         if (i !== 0) {
-          errors.push(cannotReimportError());
+          errors.push(transitiveImportError());
           return undefined;
         }
         usedImports.add(name);
@@ -1035,7 +1202,7 @@ class TypeResolver {
           if (!newIt || newIt.kind !== "record") {
             this.errors.push(
               newIt.kind === "import" || newIt.kind === "import-alias"
-                ? cannotReimportError()
+                ? transitiveImportError()
                 : makeNotARecordError(namePart),
             );
             return undefined;
@@ -1115,7 +1282,7 @@ abstract class ModuleParserBase implements ModuleParser {
       };
     }
 
-    return parseModule(tokens.result, modulePath, code);
+    return parseModule(tokens.result);
   }
 }
 
@@ -1173,3 +1340,16 @@ function resolveModulePath(
   }
   return modulePath;
 }
+
+function tryFindRecordForType(type: ResolvedType): RecordKey | null {
+  switch (type.kind) {
+    case "array":
+      return tryFindRecordForType(type.item);
+    case "optional":
+      return tryFindRecordForType(type.other);
+    case "record":
+      return type.key;
+    case "primitive":
+      return null;
+  }
+}