skir 0.0.6 → 0.0.7

package/src/config.ts

@@ -2,13 +2,11 @@ import { z } from "zod";
 
 export const GeneratorConfig = z.strictObject({
   mod: z.string(),
+  outDir: z.union([
+    z.string().endsWith("/skirout"),
+    z.array(z.string().endsWith("/skirout")),
+  ]),
   config: z.any(),
-  outDir: z
-    .union([
-      z.string().endsWith("/skirout"),
-      z.array(z.string().endsWith("/skirout")),
-    ])
-    .optional(),
 });
 
 export type GeneratorConfig = z.infer<typeof GeneratorConfig>;

package/src/config_parser.ts

@@ -1,16 +1,22 @@
-import * as ccGen from "skir-cc-gen";
-import * as dartGen from "skir-dart-gen";
+import * as CcGen from "skir-cc-gen";
+import * as DartGen from "skir-dart-gen";
 import { CodeGenerator } from "skir-internal";
-import * as javaGen from "skir-java-gen";
-import * as kotlinGen from "skir-kotlin-gen";
-import * as pythonGen from "skir-python-gen";
-import * as typescriptGen from "skir-typescript-gen";
+import * as JavaGen from "skir-java-gen";
+import * as KotlinGen from "skir-kotlin-gen";
+import * as PythonGen from "skir-python-gen";
+import * as TypescriptGen from "skir-typescript-gen";
 import { LineCounter, parseDocument, Scalar, YAMLMap } from "yaml";
 import { SkirConfig } from "./config.js";
 
 export interface SkirConfigResult {
+  /** Defined if and only if `errors` is empty. */
   skirConfig: SkirConfig | undefined;
   errors: readonly SkirConfigError[];
+  /**
+   * If true, the user may have forgotten to edit skir.yml after running
+   * `npx skir init`.
+   */
+  maybeForgotToEditAfterInit?: boolean;
 }
 
 export interface SkirConfigError {
@@ -66,6 +72,34 @@ export async function parseSkirConfig(
     }
     return offsetRangeToRange(node.range[0], node.range[1]);
   };
+  const pushErrorAtPath = (
+    path: readonly PropertyKey[],
+    message: string,
+  ): void => {
+    const pathRemainder: PropertyKey[] = [];
+    while (path.length !== 0) {
+      const range = pathToRange(path);
+      if (range) {
+        break;
+      } else {
+        // It's possible that 'path' does not map to a node if 'path' refers to
+        // a property which is missing. In that case, we pop the last element
+        // of 'path' and try again, until we find a node that exists. The
+        // elements which were popped will be included in the error message.
+        pathRemainder.push(path.at(-1)!);
+        path = path.slice(0, -1);
+      }
+    }
+    pathRemainder.reverse();
+    const messagePrefix = pathRemainder.length
+      ? `Missing property '${pathRemainder.join(".")}': `
+      : "";
+    const range = pathToRange(path);
+    errors.push({
+      message: messagePrefix + message,
+      range: range,
+    });
+  };
 
   // Check for YAML parsing errors
   if (doc.errors.length > 0) {
@@ -76,24 +110,27 @@ export async function parseSkirConfig(
         range: range,
       });
     }
-    return { skirConfig: undefined, errors: errors };
+    return {
+      skirConfig: undefined,
+      errors: errors,
+    };
   }
 
-  const jsData = doc.toJS();
-
   // 2. Validate with Zod schema
+  const jsData = doc.toJS();
   const result = SkirConfig.safeParse(jsData);
 
   if (!result.success) {
     for (const issue of result.error.issues) {
-      // Map the Zod path to the YAML node
-      const range = pathToRange(issue.path);
-      errors.push({
-        message: issue.message,
-        range: range,
-      });
+      pushErrorAtPath(issue.path, issue.message);
     }
-    return { skirConfig: undefined, errors: errors };
+    const maybeForgotToEditAfterInit =
+      jsData && typeof jsData === "object" && jsData.generators === null;
+    return {
+      skirConfig: undefined,
+      errors: errors,
+      maybeForgotToEditAfterInit,
+    };
   }
 
   // 3. Validate each generator's config with Zod schema
@@ -106,11 +143,7 @@ export async function parseSkirConfig(
         generator = await importCodeGenerator(mod);
       } catch (e) {
         if (e instanceof Error) {
-          const range = pathToRange(["generators", i, "mod"]);
-          errors.push({
-            message: e.message,
-            range: range,
-          });
+          pushErrorAtPath(["generators", i, "mod"], e.message);
           continue;
         } else {
           throw e;
@@ -119,13 +152,13 @@ export async function parseSkirConfig(
     } else {
       // TODO: rm the casts
       const modToGenerator: Record<string, CodeGenerator<unknown>> = {
-        "skir-cc-gen": ccGen.GENERATOR as any as CodeGenerator<unknown>,
-        "skir-dart-gen": dartGen.GENERATOR as any as CodeGenerator<unknown>,
-        "skir-java-gen": javaGen.GENERATOR as any as CodeGenerator<unknown>,
-        "skir-kotlin-gen": kotlinGen.GENERATOR as any as CodeGenerator<unknown>,
-        "skir-python-gen": pythonGen.GENERATOR as any as CodeGenerator<unknown>,
+        "skir-cc-gen": CcGen.GENERATOR as any as CodeGenerator<unknown>,
+        "skir-dart-gen": DartGen.GENERATOR as any as CodeGenerator<unknown>,
+        "skir-java-gen": JavaGen.GENERATOR as any as CodeGenerator<unknown>,
+        "skir-kotlin-gen": KotlinGen.GENERATOR as any as CodeGenerator<unknown>,
+        "skir-python-gen": PythonGen.GENERATOR as any as CodeGenerator<unknown>,
         "skir-typescript-gen":
-          typescriptGen.GENERATOR as any as CodeGenerator<unknown>,
+          TypescriptGen.GENERATOR as any as CodeGenerator<unknown>,
       };
       generator = modToGenerator[mod];
     }
@@ -141,11 +174,7 @@ export async function parseSkirConfig(
             "config",
             ...issue.path,
           ];
-          const range = pathToRange(path);
-          errors.push({
-            message: issue.message ?? "Error",
-            range: range,
-          });
+          pushErrorAtPath(path, issue.message ?? "Error");
         }
       }
     }

package/src/error_renderer.ts

@@ -61,6 +61,7 @@ export function renderSkirConfigErrors(
   errors: readonly SkirConfigError[],
   context: {
     skirConfigPath: string;
+    maybeForgotToEditAfterInit: boolean | undefined;
   },
 ): void {
   for (const error of errors) {
@@ -68,6 +69,13 @@ export function renderSkirConfigErrors(
     console.error(formatSkirConfigError(error, context));
   }
   console.error();
+  if (context.maybeForgotToEditAfterInit) {
+    const { skirConfigPath } = context;
+    console.warn(
+      `Did you forget to edit ${skirConfigPath} after running 'npx skir init'?`,
+    );
+    console.warn();
+  }
 }
 
 function formatSkirConfigError(
@@ -179,9 +187,9 @@ function formatBreakingChange(
       const { enumEpression, number, record, variantName } = breakingChange;
       const errorHeader = makeRed("Illegal variant kind change");
       const enumName = map(record, getQualifiedName);
-      const variantKind = map(variantName, (vn) => {
-        caseMatches(vn.text, "lower_underscore") ? "wrapper" : "constant";
-      });
+      const variantKind = map(variantName, (vn) =>
+        caseMatches(vn.text, "lower_underscore") ? "wrapper" : "constant",
+      );
       return [
         `${locationPrefix}${errorHeader}\n`,
         "  [Last snapshot]\n",

package/src/exit_error.ts

@@ -0,0 +1,6 @@
+/**
+ * If this error is thrown during the execution of the compiler, the message
+ * will be printed to stderr before exiting. The stack trace will not be
+ * printed.
+ */
+export class ExitError extends Error {}

package/src/io.ts

@@ -1,4 +1,6 @@
-import * as fs from "fs";
+import * as FileSystem from "fs";
+import * as FileSystemPromises from "fs/promises";
+import * as Paths from "path";
 
 export interface FileReader {
   readTextFile(path: string): string | undefined;
@@ -11,7 +13,7 @@ export interface FileWriter {
 class RealFileSystem implements FileReader, FileWriter {
   readTextFile(path: string): string | undefined {
     try {
-      return fs.readFileSync(path, "utf-8");
+      return FileSystem.readFileSync(path, "utf-8");
     } catch (error) {
       if (
         error &&
@@ -26,8 +28,25 @@ class RealFileSystem implements FileReader, FileWriter {
   }
 
   writeTextFile(path: string, contents: string): void {
-    fs.writeFileSync(path, contents, "utf-8");
+    FileSystem.writeFileSync(path, contents, "utf-8");
   }
 }
 
 export const REAL_FILE_SYSTEM = new RealFileSystem();
+
+export async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await FileSystemPromises.lstat(path)).isDirectory();
+  } catch (_e) {
+    return false;
+  }
+}
+
+export function rewritePathForRendering(path: string): string {
+  if (Paths.isAbsolute(path) || /^\.{1,2}[/\\]$/.test(path)) {
+    return path;
+  } else {
+    // To make it clear that it's a path, prepend "./"
+    return `.${Paths.sep}${path}`;
+  }
+}

package/src/module_collector.ts

@@ -1,21 +1,35 @@
 import { glob } from "glob";
-import * as paths from "path";
-import { REAL_FILE_SYSTEM } from "./io.js";
+import * as Paths from "path";
+import { ExitError } from "./exit_error.js";
+import {
+  isDirectory,
+  REAL_FILE_SYSTEM,
+  rewritePathForRendering,
+} from "./io.js";
 import { ModuleSet } from "./module_set.js";
 
 export async function collectModules(srcDir: string): Promise<ModuleSet> {
   const modules = ModuleSet.create(REAL_FILE_SYSTEM, srcDir);
-  const skirFiles = await glob(paths.join(srcDir, "**/*.skir"), {
+  const skirFiles = await glob(Paths.join(srcDir, "**/*.skir"), {
     stat: true,
     withFileTypes: true,
   });
-  for await (const skirFile of skirFiles) {
+  if (skirFiles.length === 0) {
+    const isDir = await isDirectory(srcDir);
+    if (!isDir) {
+      throw new ExitError(
+        "Source directory does not exist: " + rewritePathForRendering(srcDir),
+      );
+    }
+  }
+  for (const skirFile of skirFiles) {
     if (!skirFile.isFile) {
       continue;
     }
-    const relativePath = paths
-      .relative(srcDir, skirFile.fullpath())
-      .replace(/\\/g, "/");
+    const relativePath = Paths.relative(srcDir, skirFile.fullpath()).replace(
+      /\\/g,
+      "/",
+    );
     modules.parseAndResolve(relativePath);
   }
   return modules;

package/src/module_set.ts

@@ -1,4 +1,4 @@
-import * as paths from "path";
+import * as Paths from "path";
 import {
   MutableDocReferenceName,
   unquoteAndUnescape,
@@ -1311,7 +1311,7 @@ class DefaultModuleParser extends ModuleParserBase {
   }
 
   readSourceCode(modulePath: string): string | undefined {
-    return this.fileReader.readTextFile(paths.join(this.rootPath, modulePath));
+    return this.fileReader.readTextFile(Paths.join(this.rootPath, modulePath));
   }
 }
 
@@ -1341,12 +1341,12 @@ function resolveModulePath(
   if (modulePath.startsWith("./") || modulePath.startsWith("../")) {
     // This is a relative path from the module. Let's transform it into a
     // relative path from root.
-    modulePath = paths.join(originModulePath, "..", modulePath);
+    modulePath = Paths.join(originModulePath, "..", modulePath);
   }
   // "a/./b/../c" => "a/c"
   // Note that `paths.normalize` will use backslashes on Windows.
   // We don't want that.
-  modulePath = paths.normalize(modulePath).replace(/\\/g, "/");
+  modulePath = Paths.normalize(modulePath).replace(/\\/g, "/");
   if (modulePath.startsWith(`../`)) {
     errors.push({
       token: pathToken,

package/src/parser.ts

@@ -28,7 +28,7 @@ import type {
   UnresolvedType,
 } from "skir-internal";
 import { convertCase, simpleHash } from "skir-internal";
-import * as casing from "./casing.js";
+import * as Casing from "./casing.js";
 import { mergeDocs } from "./doc_comment_parser.js";
 import { ModuleTokens } from "./tokenizer.js";
 
@@ -398,7 +398,7 @@ function parseRecord(
     if (nameMatch.case < 0) {
       return null;
     }
-    casing.validate(nameMatch.token, "UpperCamel", it.errors);
+    Casing.validate(nameMatch.token, "UpperCamel", it.errors);
     nameToken = nameMatch.token;
   }
   let stableId: number | null = null;
@@ -476,7 +476,7 @@ function parseField(
       }
       case 2: {
         const expectedCasing = type ? "lower_underscore" : "UPPER_UNDERSCORE";
-        casing.validate(name, expectedCasing, it.errors);
+        Casing.validate(name, expectedCasing, it.errors);
         if (recordType === "enum" && name.text === "UNKNOWN") {
           it.errors.push({
             token: name,
@@ -790,7 +790,7 @@ function parseImportAs(it: TokenIterator): ImportAlias | null {
   if (aliasMatch.case < 0) {
     return null;
   }
-  casing.validate(aliasMatch.token, "lower_underscore", it.errors);
+  Casing.validate(aliasMatch.token, "lower_underscore", it.errors);
   if (it.expectThenNext(["from"]).case < 0) return null;
   const modulePathMatch = it.expectThenNext([TOKEN_IS_STRING_LITERAL]);
   if (modulePathMatch.case < 0) {
@@ -838,7 +838,7 @@ function parseMethod(it: TokenIterator, doc: Doc): MutableMethod | null {
     return null;
   }
   const name = nameMatch.token;
-  casing.validate(name, "UpperCamel", it.errors);
+  Casing.validate(name, "UpperCamel", it.errors);
   if (it.expectThenNext(["("]).case < 0) {
     return null;
   }
@@ -898,7 +898,7 @@ function parseConstant(it: TokenIterator, doc: Doc): MutableConstant | null {
   if (nameMatch.case < 0) {
     return null;
   }
-  casing.validate(nameMatch.token, "UPPER_UNDERSCORE", it.errors);
+  Casing.validate(nameMatch.token, "UPPER_UNDERSCORE", it.errors);
   if (it.expectThenNext([":"]).case < 0) {
     return null;
   }

package/src/project_initializer.ts

@@ -1,11 +1,12 @@
-import * as fs from "fs";
-import * as paths from "path";
+import * as FileSystem from "fs";
+import * as Paths from "path";
+import { rewritePathForRendering } from "./io.js";
 
 export function initializeProject(rootDir: string): void {
-  const skirYmlPath = paths.join(rootDir, "skir.yml");
+  const skirYmlPath = Paths.join(rootDir, "skir.yml");
 
   // Check if skir.yml already exists
-  if (fs.existsSync(skirYmlPath)) {
+  if (FileSystem.existsSync(skirYmlPath)) {
     console.log(
       "A skir.yml file already exists in this directory. Skipping project initialization.",
     );
@@ -13,28 +14,109 @@ export function initializeProject(rootDir: string): void {
   }
 
   // Create skir.yml file
-  fs.writeFileSync(skirYmlPath, SKIR_YML_CONTENT, "utf-8");
+  FileSystem.writeFileSync(skirYmlPath, SKIR_YML_CONTENT, "utf-8");
 
   // Check if skir-src directory exists
-  const skirSrcDir = paths.join(rootDir, "skir-src");
-  if (!fs.existsSync(skirSrcDir)) {
+  const skirSrcDir = Paths.join(rootDir, "skir-src");
+  if (!FileSystem.existsSync(skirSrcDir)) {
     // Create skir-src directory
-    fs.mkdirSync(skirSrcDir, { recursive: true });
+    FileSystem.mkdirSync(skirSrcDir, { recursive: true });
 
     // Create hello_world.skir file
-    const helloWorldPath = paths.join(skirSrcDir, "hello_world.skir");
-    fs.writeFileSync(helloWorldPath, HELLO_WORLD_SKIR_CONTENT, "utf-8");
+    const helloWorldPath = Paths.join(skirSrcDir, "hello_world.skir");
+    FileSystem.writeFileSync(helloWorldPath, HELLO_WORLD_SKIR_CONTENT, "utf-8");
   }
 
-  console.log(`Done. Please edit: ${paths.resolve(skirYmlPath)}`);
+  console.log(`Done. Please edit: ${rewritePathForRendering(skirYmlPath)}`);
 }
 
-const SKIR_YML_CONTENT = `srcDir: skir-src
+const SKIR_YML_CONTENT = `# Configuration file for Skir code generator
+#
+# Documentation: https://skir.build/
+#
+# Cheat sheet:
+#   npx skir gen          Generate code from .skir files
+#   npx skir gen --watch  Watch for changes and regenerate automatically
+#   npx skir format       Format all .skir files
+#   npx skir snapshot     Take a snapshot of the source directory, verify no
+#                         breaking changes since last snapshot
 
+# Directory containing .skir files
+srcDir: skir-src
+
+# Uncomment and configure the generators for your target language(s).
 generators:
-  - mod: skir-python-gen
-    skiroutDir: ./skirout
-    config: {}
+  # # --------------------------------------------------------------------------
+  # # C++ code generator
+  # # Home: https://github.com/gepheum/skir-cc-gen
+  # # To install runtime dependencies, follow instructions in repository README
+  # # --------------------------------------------------------------------------
+  # - mod: skir-cc-gen
+  #   outDir: ./skirout
+  #   config:
+  #     # Set to true if you use GoogleTest
+  #     writeGoogleTestHeaders: false
+
+  # # --------------------------------------------------------------------------
+  # # Dart code generator
+  # # Home: https://github.com/gepheum/skir-dart-gen
+  # # To install runtime dependencies: dart pub add skir_client
+  # # --------------------------------------------------------------------------
+  # - mod: skir-dart-gen
+  #   outDir: ./skirout
+  #   config: {}
+
+  # # --------------------------------------------------------------------------
+  # # Java code generator
+  # # Home: https://github.com/gepheum/skir-java-gen
+  # # Add the following line to your build.gradle dependencies:
+  # #    implementation("build.skir:skir-client:latest.release")
+  # # --------------------------------------------------------------------------
+  # - mod: skir-java-gen
+  #   outDir: ./src/main/java/skirout
+  #   config: {}
+  #   # Alternatively:
+  #   # outDir: ./src/main/java/skirout/my/project
+  #   # config:
+  #   #   packagePrefix: "my.project."
+
+  # # --------------------------------------------------------------------------
+  # # Kotlin code generator
+  # # Home: https://github.com/gepheum/skir-kotlin-gen
+  # # Add the following line to your build.gradle dependencies:
+  # #   implementation("build.skir:skir-client:latest.release")
+  # # --------------------------------------------------------------------------
+  # - mod: skir-kotlin-gen
+  #   outDir: ./src/main/kotlin/skirout
+  #   config: {}
+  #   # Alternatively:
+  #   # outDir: ./src/main/kotlin/skirout/my/project
+  #   # config:
+  #   #   packagePrefix: "my.project."
+
+  # # --------------------------------------------------------------------------
+  # # Python code generator
+  # # Home: https://github.com/gepheum/skir-python-gen
+  # # To install runtime dependencies: pip install skir-client
+  # # --------------------------------------------------------------------------
+  # - mod: skir-python-gen
+  #   outDir: ./skirout
+  #   config: {}
+  #   # Alternatively:
+  #   # outDir: ./my/project/skirout
+  #   # config:
+  #   #   packagePrefix: "my.project."
+
+  # # --------------------------------------------------------------------------
+  # # TypeScript/JavaScript code generator
+  # # Home: https://github.com/gepheum/skir-typescript-gen
+  # # To install runtime dependencies: npm i skir-client
+  # # --------------------------------------------------------------------------
+  # - mod: skir-typescript-gen
+  #   outDir: ./src/skirout
+  #   config:
+  #     # Use ".js" for ES modules, "" for CommonJS
+  #     importPathExtension: ".js"
 `;
 
 const HELLO_WORLD_SKIR_CONTENT = `/// A point in 2D space.