skir 1.2.7 → 1.2.9

package/src/formatter.ts

@@ -1,4 +1,13 @@
-import type { Module, Range, SkirError, Token } from "skir-internal";
+import type {
+  Declaration,
+  Doc,
+  Module,
+  Range,
+  Record,
+  SkirError,
+  Token,
+  Value,
+} from "skir-internal";
 import { formatImportBlock } from "./import_block_formatter.js";
 import { parseModule } from "./parser.js";
 import { ModuleTokens, tokenizeModule } from "./tokenizer.js";
@@ -30,13 +39,19 @@ export type RandomGenerator = () => number;
 
 /**
  * Formats the given module and returns the new source code.
- * Preserves token ordering.
+ * If a resolved module is provided, the formatter will try to convert enum
+ * variants spelled with the legacy UPPERCASE format to the preferred lowercase
+ * format.
  */
-export function formatModule(
-  sourceCode: string,
-  modulePath: string,
-  randomGenerator: RandomGenerator = Math.random,
-): FormattedModule {
+export function formatModule(args: {
+  sourceCode: string;
+  modulePath: string;
+  resolvedModule?: Module;
+  randomGenerator?: RandomGenerator;
+}): FormattedModule {
+  const { modulePath, resolvedModule, randomGenerator = Math.random } = args;
+  let { sourceCode } = args;
+
   const makeErroredResult = (
     errors: readonly SkirError[],
   ): FormattedModule => ({
@@ -45,6 +60,15 @@ export function formatModule(
     errors: errors,
   });
 
+  if (resolvedModule) {
+    if (resolvedModule.sourceCode !== sourceCode) {
+      throw new Error(
+        "Resolved module's source code does not match the provided source code.",
+      );
+    }
+    sourceCode = convertLegacyVariantNames(resolvedModule).newSourceCode;
+  }
+
   const moduleTokens = tokenizeModule(sourceCode, modulePath);
   if (moduleTokens.errors.length > 0) {
     return makeErroredResult(moduleTokens.errors);
@@ -447,3 +471,106 @@ function normalizeToken(
     return token;
   }
 }
+
+/**
+ * Converts the constant variants spelled with the legacy UPPERCASE format to
+ * the preferred lowercase format.
+ * The enum must not be declared in an external dependency.
+ */
+function convertLegacyVariantNames(resolvedModule: Module): {
+  newSourceCode: string;
+} {
+  const legacyTokens: Token[] = [];
+  const isEligibleEnum = (record: Record): boolean =>
+    record.recordType === "enum" &&
+    !record.name.line.modulePath.startsWith("@");
+  const collectInDoc = (doc: Doc): void => {
+    for (const piece of doc.pieces) {
+      if (piece.kind !== "reference") continue;
+      const { referee } = piece;
+      if (
+        referee?.kind === "field" &&
+        !referee.field.unresolvedType &&
+        isEligibleEnum(referee.record) &&
+        /^[A-Z]/.test(referee.field.name.text)
+      ) {
+        const { token } = piece.nameParts.at(-1)!;
+        legacyTokens.push(token);
+      }
+    }
+  };
+  const collectInValue = (value: Value): void => {
+    switch (value.kind) {
+      case "array": {
+        return value.items.forEach(collectInValue);
+      }
+      case "object": {
+        return Object.values(value.entries).forEach((val) => {
+          collectInValue(val.value);
+        });
+      }
+      case "literal": {
+        if (
+          value.type &&
+          value.type.kind === "enum" &&
+          isEligibleEnum(value.type.enum) &&
+          /^['"][A-Z]/.test(value.token.text)
+        ) {
+          legacyTokens.push(value.token);
+        }
+      }
+    }
+  };
+  const collect = (declaration: Declaration, inEligibleEnum: boolean): void => {
+    // First, collect tokens from doc references.
+    switch (declaration.kind) {
+      case "constant":
+      case "field":
+      case "method":
+      case "record": {
+        collectInDoc(declaration.doc);
+      }
+    }
+    switch (declaration.kind) {
+      case "constant": {
+        return collectInValue(declaration.value);
+      }
+      case "field": {
+        if (
+          inEligibleEnum &&
+          !declaration.unresolvedType &&
+          /^[A-Z]/.test(declaration.name.text)
+        ) {
+          legacyTokens.push(declaration.name);
+        }
+        break;
+      }
+      case "record": {
+        const isEligible = isEligibleEnum(declaration);
+        declaration.declarations.forEach((decl) => collect(decl, isEligible));
+      }
+    }
+  };
+  for (const declaration of resolvedModule.declarations) {
+    const inEligibleEnum = false;
+    collect(declaration, inEligibleEnum);
+  }
+
+  const oldSourceCode = resolvedModule.sourceCode;
+  if (legacyTokens.length === 0) {
+    return { newSourceCode: oldSourceCode };
+  }
+  legacyTokens.sort((a, b) => a.position - b.position);
+
+  const fragments: string[] = [];
+  let lastPosition = 0;
+  for (const legacyToken of legacyTokens) {
+    fragments.push(oldSourceCode.slice(lastPosition, legacyToken.position));
+    fragments.push(legacyToken.text.toLowerCase());
+    lastPosition = legacyToken.position + legacyToken.text.length;
+  }
+  fragments.push(oldSourceCode.slice(lastPosition));
+  return {
+    newSourceCode: fragments.join(""),
+  };
+}

package/src/get_dependencies_flow.ts

@@ -168,7 +168,11 @@ export async function getModuleFromGithubUrl(
     }
   }
 
-  const moduleSet = ModuleSet.compile(modulePathToContent);
+  const moduleSet = ModuleSet.compile(
+    modulePathToContent,
+    "no-cache",
+    "strict",
+  );
   if (moduleSet.errors.length > 0) {
     return {
       kind: "error",

package/src/module_collector.ts

@@ -11,7 +11,8 @@ import { ModuleSet } from "./module_set.js";
 export async function collectModules(
   srcDir: string,
   dependencies: ModuleSet,
-  cache?: ModuleSet,
+  cache: ModuleSet | undefined,
+  parseMode: "strict" | "lenient",
 ): Promise<ModuleSet> {
   const modulePathToContent = new Map<string, string>();
   for (const [modulePath, module] of dependencies.modules) {
@@ -21,16 +22,19 @@ export async function collectModules(
   for (const { modulePath, content } of editableModules) {
     modulePathToContent.set(modulePath, content);
   }
-  return ModuleSet.compile(modulePathToContent, cache ?? dependencies);
+  return ModuleSet.compile(
+    modulePathToContent,
+    cache ?? dependencies,
+    parseMode,
+  );
 }
 
-export interface EditableModule {
-  readonly fullPath: string;
+interface EditableModule {
   readonly modulePath: string;
   readonly content: string;
 }
 
-export async function collectEditableModules(
+async function collectEditableModules(
   srcDir: string,
 ): Promise<ReadonlyArray<EditableModule>> {
   const skirFiles = await glob(Paths.join(srcDir, "**/*.skir"), {
@@ -57,7 +61,6 @@ export async function collectEditableModules(
         throw new ExitError("Cannot read " + rewritePathForRendering(fullPath));
       }
       return {
-        fullPath: fullPath,
         modulePath: relativePath,
         content: content,
       };

package/src/module_set.ts

@@ -49,8 +49,8 @@ import { ModuleTokens, tokenizeModule } from "./tokenizer.js";
 export class ModuleSet {
   static compile(
     modulePathToContent: ReadonlyMap<string, string>,
-    cache?: ModuleSet,
-    parseMode: "strict" | "lenient" = "strict",
+    cache: ModuleSet | "no-cache",
+    parseMode: "strict" | "lenient",
   ): ModuleSet {
     return new ModuleSet(modulePathToContent, cache, parseMode);
   }
@@ -59,7 +59,7 @@ export class ModuleSet {
     currentModulePath: string,
     currentPosition: number,
     modulePathToContent: ReadonlyMap<string, string>,
-    cache?: ModuleSet,
+    cache: ModuleSet | "no-cache",
   ): Result<Module> {
     if (!modulePathToContent.has(currentModulePath)) {
       throw new Error(`Not found: ${currentModulePath}`);
@@ -71,18 +71,23 @@ export class ModuleSet {
     return moduleSet.modules.get(currentModulePath)!;
   }
 
+  static empty(): ModuleSet {
+    return ModuleSet.compile(new Map(), "no-cache", "strict");
+  }
+
   constructor(
     private readonly modulePathToContent: ReadonlyMap<string, string>,
-    cache: ModuleSet | undefined,
+    cache: ModuleSet | "no-cache",
     private readonly parseMode: "strict" | "lenient",
     private readonly completionMode?: {
       readonly modulePath: string;
       readonly position: number;
     },
   ) {
-    this.cache = cache
-      ? new Cache(modulePathToContent, cache.moduleBundles, cache.registry)
-      : undefined;
+    this.cache =
+      cache !== "no-cache"
+        ? new Cache(modulePathToContent, cache.moduleBundles, cache.registry)
+        : undefined;
     // In completion mode, no need to recompile modules which are not dependencies of
     // the current module.
     const modulePaths = completionMode
@@ -153,15 +158,18 @@ export class ModuleSet {
 
     let module: MutableModule;
     const errors: SkirError[] = [];
+    const warnings: SkirError[] = [];
     {
       const parseResult = parseModule(moduleTokens.result, this.parseMode);
       errors.push(...parseResult.errors);
+      warnings.push(...(parseResult.warnings ?? []));
       module = parseResult.result;
     }
 
     const moduleBundle = new ModuleBundle(moduleTokens, {
       result: module,
       errors: errors,
+      warnings: warnings,
     });
 
     // Process all imports.
@@ -901,7 +909,8 @@ export class ModuleSet {
   finalize(): FinalizationResult {
     type MutableModuleResult = {
       result: Module;
-      errors: SkirError[];
+      readonly errors: SkirError[];
+      readonly warnings: SkirError[];
     };
     const modules = new Map<string, MutableModuleResult>();
 
@@ -911,6 +920,7 @@ export class ModuleSet {
       modules.set(modulePath, {
         result: module.result,
         errors: [...moduleErrors],
+        warnings: [...(module.warnings ?? [])],
       });
     }
 
@@ -961,12 +971,15 @@ export class ModuleSet {
 
     // Aggregate errors across all modules.
     const errors: SkirError[] = [];
+    const warnings: SkirError[] = [];
     for (const moduleBundle of modules.values()) {
       errors.push(...moduleBundle.errors);
+      warnings.push(...moduleBundle.warnings);
     }
     return {
       modules: modules,
       errors: errors,
+      warnings: warnings,
     };
   }
 
@@ -997,6 +1010,10 @@ export class ModuleSet {
     return this.finalizationResult.errors;
   }
 
+  get warnings(): readonly SkirError[] {
+    return this.finalizationResult.warnings;
+  }
+
   get modules(): ReadonlyMap<string, Result<Module>> {
     return this.finalizationResult.modules;
   }
@@ -1459,6 +1476,8 @@ interface FinalizationResult {
   readonly modules: ReadonlyMap<string, Result<Module>>;
   /** Errors aggregated across all modules. */
   readonly errors: readonly SkirError[];
+  /** Warnings aggregated across all modules. */
+  readonly warnings: readonly SkirError[];
 }
 
 function ensureAllImportsAreUsed(

package/src/parser.ts

@@ -46,7 +46,8 @@ export function parseModule(
 ): Result<MutableModule> {
   const { modulePath, sourceCode } = moduleTokens;
   const errors: SkirError[] = [];
-  const it = new TokenIterator(moduleTokens, mode, errors);
+  const warnings: SkirError[] = [];
+  const it = new TokenIterator(moduleTokens, mode, errors, warnings);
   const maybeBrokenDeclarations = parseDeclarations(it, "module");
   const brokenConstants: BrokenConstant[] = maybeBrokenDeclarations.filter(
     (d) => d.kind === "broken-constant",
@@ -182,6 +183,7 @@ export function parseModule(
       brokenConstants: brokenConstants,
     },
     errors: errors,
+    warnings: warnings,
   };
 }
 
@@ -429,6 +431,29 @@ class RecordBuilder {
         });
         break;
       }
+    } else {
+      // An enum. Make sure that constant variants are either all spelled in
+      // lowercase or all spelled in uppercase (legacy format).
+      const firstLegacyConstant = Object.values(this.nameToDeclaration).find(
+        (d): d is MutableField =>
+          d.kind === "field" &&
+          !d.unresolvedType &&
+          Casing.caseMatches(d.name.text, "UPPER_UNDERSCORE"),
+      );
+      if (
+        firstLegacyConstant &&
+        Object.values(this.nameToDeclaration).some(
+          (d) =>
+            d.kind === "field" &&
+            !d.unresolvedType &&
+            Casing.caseMatches(d.name.text, "lower_underscore"),
+        )
+      ) {
+        this.errors.push({
+          token: firstLegacyConstant.name,
+          message: "Cannot mix legacy format and lowercase format",
+        });
+      }
     }
 
     const declarations = Object.values(this.nameToDeclaration);
@@ -610,12 +635,28 @@ function parseField(
         break;
       }
       case 2: {
-        const expectedCasing = type ? "lower_underscore" : "UPPER_UNDERSCORE";
-        Casing.validate(name, expectedCasing, it.errors);
-        if (recordType === "enum" && name.text === "UNKNOWN") {
+        if (!type && Casing.caseMatches(name.text, "UPPER_UNDERSCORE")) {
+          // Legacy format for enum constant variants: UPPER_UNDERSCORE.
+          // Raise a warning unless the variant is defined in an external
+          // dependency.
+          if (!name.line.modulePath.startsWith("@")) {
+            it.warnings.push({
+              token: name,
+              message:
+                "Constant variants should be spelled in lowercase; uppercase format is legacy",
+              suggestReformat: true,
+            });
+          }
+        } else {
+          Casing.validate(name, "lower_underscore", it.errors);
+        }
+        if (
+          recordType === "enum" &&
+          ["UNKNOWN", "unknown"].includes(name.text)
+        ) {
           it.errors.push({
             token: name,
-            message: `Cannot name field of enum: UNKNOWN`,
+            message: `Cannot name field of enum: unknown`,
           });
         }
         return makeField();
@@ -1330,6 +1371,7 @@ class TokenIterator {
     readonly moduleTokens: ModuleTokens,
     readonly mode: "strict" | "lenient",
     readonly errors: ErrorSink,
+    readonly warnings: ErrorSink,
   ) {
     this.tokens = moduleTokens.tokens;
   }

package/src/snapshotter.ts

@@ -20,9 +20,14 @@ export async function takeSnapshot(args: {
   dependencies: ModuleSet;
   subcommand: "ci" | "dry-run" | undefined;
 }): Promise<boolean> {
-  const newModuleSet = await collectModules(args.srcDir, args.dependencies);
+  const newModuleSet = await collectModules(
+    args.srcDir,
+    args.dependencies,
+    undefined,
+    "strict",
+  );
   if (newModuleSet.errors.length) {
-    renderErrors(newModuleSet.errors);
+    renderErrors(newModuleSet.errors, "error");
     return false;
   }
   const snapshotPath = join(args.rootDir, "skir-snapshot.json");
@@ -113,7 +118,7 @@ async function readLastSnapshot(
     const isNotFoundError =
       error instanceof Error && "code" in error && error.code === "ENOENT";
     if (isNotFoundError) {
-      return ModuleSet.compile(new Map<string, string>());
+      return ModuleSet.empty();
     } else {
       // Rethrow I/O error
       throw error;
@@ -150,9 +155,9 @@ export function snapshotFileContentToModuleSet(
       error: error,
     };
   }
-  const moduleSet = ModuleSet.compile(pathToSourceCode);
+  const moduleSet = ModuleSet.compile(pathToSourceCode, "no-cache", "strict");
   if (moduleSet.errors.length) {
-    const firstError = formatError(moduleSet.errors[0]!);
+    const firstError = formatError(moduleSet.errors[0]!, "error");
     return {
       kind: "corrupted",
       error: new Error(`errors in modules; first error: ${firstError}`),