skir 0.0.1 → 0.0.3

package/src/casing.ts

@@ -1,4 +1,4 @@
-import type { Casing, ErrorSink, Token } from "./types.js";
+import type { ErrorSink, Token } from "skir-internal";
 
 /** Registers an error if the given token does not match the expected casing. */
 export function validate(
@@ -14,41 +14,6 @@ export function validate(
   }
 }
 
-export function convertCase(
-  text: string,
-  source: Casing,
-  target: Casing,
-): string {
-  let words: string[];
-  switch (source) {
-    case "lowerCamel":
-    case "UpperCamel":
-      words = text.split(/(?=[A-Z])/).map((w) => w.toLowerCase());
-      break;
-    case "lower_underscore":
-      words = text.split("_");
-      break;
-    case "UPPER_UNDERSCORE":
-      words = text.split("_").map((w) => w.toLowerCase());
-      break;
-  }
-  switch (target) {
-    case "lowerCamel":
-      return words.map((w, i) => (i ? capitalize(w) : w)).join("");
-    case "lower_underscore":
-      return words.join("_");
-    case "UpperCamel":
-      return words.map(capitalize).join("");
-    case "UPPER_UNDERSCORE":
-      return words.map((w) => w.toUpperCase()).join("_");
-  }
-}
-
-/** Returns a new string with the first letter of `name` capitalized. */
-export function capitalize(name: string): string {
-  return name[0]!.toUpperCase() + name.slice(1);
-}
-
 export function caseMatches(
   name: string,
   expected: "lower_underscore" | "UpperCamel" | "UPPER_UNDERSCORE",

package/src/command_line_parser.ts

@@ -1,18 +1,18 @@
 export type ParsedArgs =
   | {
       kind: "gen";
+      subcommand?: "watch";
       root?: string;
-      watch?: true;
     }
   | {
       kind: "format";
+      subcommand?: "check";
       root?: string;
-      check?: true;
     }
   | {
       kind: "snapshot";
+      subcommand?: "check" | "view";
       root?: string;
-      check?: true;
     }
   | {
       kind: "init";
@@ -80,26 +80,30 @@ export function parseCommandLine(args: string[]): ParsedArgs {
 const COMMAND_BASE = "npx skir";
 
 const HELP_TEXT = `
-Usage: ${COMMAND_BASE} <command> [options]
+Usage: ${COMMAND_BASE} <command> [subcommand] [options]
 
 Commands:
-  gen         Generate code from Skir source files to target languages
-  format      Format all .skir files in the specified directory
-  snapshot    Verify compatibility by comparing current .skir files against the last snapshot
-  init        Initialize a new Skir project with a minimal skir.yml file
-  help        Display this help message
+  gen [watch]           Generate code from Skir source files to target languages
+                        watch: Automatically regenerate when .skir files change
+  format [check]        Format all .skir files in the specified directory
+                        check: Fail if code is not properly formatted
+  snapshot [check|view] Manage .skir file snapshots for compatibility checking
+                        check: Fail if there are breaking changes since last snapshot
+                        view: Display the last snapshot
+  init                  Initialize a new Skir project with a minimal skir.yml file
+  help                  Display this help message
 
 Options:
   --root, -r <path>    Path to the directory containing the skir.yml configuration file
-  --watch, -w          Enable watch mode to automatically regenerate code when .skir files change (gen only)
-  --check, -c          Check mode: fail if code is not properly formatted (format) or if there are breaking changes (snapshot)
 
 Examples:
   ${COMMAND_BASE} gen
+  ${COMMAND_BASE} gen watch
   ${COMMAND_BASE} format --root path/to/root/dir
-  ${COMMAND_BASE} format -r path/to/root/dir
-  ${COMMAND_BASE} gen -r path/to/root/dir --watch
-  ${COMMAND_BASE} snapshot --root path/to/root/dir
+  ${COMMAND_BASE} format check -r path/to/root/dir
+  ${COMMAND_BASE} snapshot
+  ${COMMAND_BASE} snapshot check
+  ${COMMAND_BASE} snapshot view --root path/to/root/dir
 `;
 
 export class CommandLineParseError extends Error {
@@ -111,8 +115,7 @@ export class CommandLineParseError extends Error {
 
 type ParsedOptions = {
   root?: string;
-  watch?: boolean;
-  check?: boolean;
+  subcommand?: string;
   unknown: string[];
 };
 
@@ -136,24 +139,14 @@ function parseOptions(args: string[]): ParsedOptions {
       }
       options.root = args[i + 1];
       i++; // Skip the next argument as it's the value
-    } else if (arg === "--watch" || arg === "-w") {
-      if (options.watch) {
-        throw new CommandLineParseError(
-          `Option ${arg} specified multiple times`,
-        );
-      }
-      options.watch = true;
-    } else if (arg === "--check" || arg === "-c") {
-      if (options.check) {
-        throw new CommandLineParseError(
-          `Option ${arg} specified multiple times`,
-        );
-      }
-      options.check = true;
     } else if (arg.startsWith("-")) {
       options.unknown.push(arg);
     } else {
-      throw new CommandLineParseError(`Unexpected argument: ${arg}`);
+      // Positional argument - treat as subcommand
+      if (options.subcommand !== undefined) {
+        throw new CommandLineParseError(`Unexpected argument: ${arg}`);
+      }
+      options.subcommand = arg;
     }
   }
 
@@ -163,63 +156,64 @@ function parseOptions(args: string[]): ParsedOptions {
 function buildGenCommand(options: ParsedOptions): ParsedArgs {
   validateNoUnknownOptions(options, "gen");
 
-  if (options.check) {
+  if (options.subcommand !== undefined && options.subcommand !== "watch") {
     throw new CommandLineParseError(
-      "Option --check is not valid for the 'gen' command",
+      `Unknown subcommand for 'gen': ${options.subcommand}`,
     );
   }
 
   return {
     kind: "gen",
     root: options.root,
-    watch: options.watch ? true : undefined,
+    subcommand: options.subcommand === "watch" ? "watch" : undefined,
   };
 }
 
 function buildFormatCommand(options: ParsedOptions): ParsedArgs {
   validateNoUnknownOptions(options, "format");
 
-  if (options.watch) {
+  if (options.subcommand !== undefined && options.subcommand !== "check") {
     throw new CommandLineParseError(
-      "Option --watch is not valid for the 'format' command",
+      `Unknown subcommand for 'format': ${options.subcommand}`,
     );
   }
 
   return {
     kind: "format",
     root: options.root,
-    check: options.check ? true : undefined,
+    subcommand: options.subcommand === "check" ? "check" : undefined,
   };
 }
 
 function buildSnapshotCommand(options: ParsedOptions): ParsedArgs {
   validateNoUnknownOptions(options, "snapshot");
 
-  if (options.watch) {
+  if (
+    options.subcommand !== undefined &&
+    options.subcommand !== "check" &&
+    options.subcommand !== "view"
+  ) {
     throw new CommandLineParseError(
-      "Option --watch is not valid for the 'snapshot' command",
+      `Unknown subcommand for 'snapshot': ${options.subcommand}`,
     );
   }
 
   return {
     kind: "snapshot",
     root: options.root,
-    check: options.check ? true : undefined,
+    subcommand:
+      options.subcommand === "check" || options.subcommand === "view"
+        ? options.subcommand
+        : undefined,
   };
 }
 
 function buildInitCommand(options: ParsedOptions): ParsedArgs {
   validateNoUnknownOptions(options, "init");
 
-  if (options.watch) {
-    throw new CommandLineParseError(
-      "Option --watch is not valid for the 'init' command",
-    );
-  }
-
-  if (options.check) {
+  if (options.subcommand !== undefined) {
     throw new CommandLineParseError(
-      "Option --check is not valid for the 'init' command",
+      `Unknown subcommand for 'init': ${options.subcommand}`,
     );
   }
 

package/src/compatibility_checker.ts

@@ -1,4 +1,3 @@
-import { ModuleSet } from "./module_set.js";
 import type {
   Field,
   Method,
@@ -7,7 +6,8 @@ import type {
   RecordLocation,
   ResolvedType,
   Token,
-} from "./types.js";
+} from "skir-internal";
+import { ModuleSet } from "./module_set.js";
 
 export interface BeforeAfter<T> {
   before: T;
@@ -50,7 +50,14 @@ export type BreakingChange =
       reintroducedAs: Token;
     }
   | {
-      kind: "enum-variant-kind-change";
+      kind: "missing-variant";
+      record: BeforeAfter<RecordLocation>;
+      enumEpression: BeforeAfter<Expression>;
+      variantName: Token;
+      number: number;
+    }
+  | {
+      kind: "variant-kind-change";
       record: BeforeAfter<RecordLocation>;
       enumEpression: BeforeAfter<Expression>;
       variantName: BeforeAfter<Token>;
@@ -210,9 +217,21 @@ class BackwardCompatibilityChecker {
         });
       }
     }
+    const removedNumbersAfter = new Set<number>(
+      record.after.record.removedNumbers,
+    );
     for (const fieldBefore of record.before.record.fields) {
       const fieldAfter = numberToFieldAfter.get(fieldBefore.number);
       if (fieldAfter === undefined) {
+        if (!removedNumbersAfter.has(fieldBefore.number)) {
+          this.pushBreakingChange({
+            kind: "missing-variant",
+            record,
+            enumEpression: recordExpression,
+            variantName: fieldBefore.name,
+            number: fieldBefore.number,
+          });
+        }
         continue;
       }
       if (fieldBefore.type && fieldAfter.type) {
@@ -249,7 +268,7 @@ class BackwardCompatibilityChecker {
         );
       } else if (fieldBefore.type || fieldAfter.type) {
         this.pushBreakingChange({
-          kind: "enum-variant-kind-change",
+          kind: "variant-kind-change",
           record,
           enumEpression: recordExpression,
           variantName: {
@@ -362,7 +381,7 @@ class BackwardCompatibilityChecker {
   private readonly seenRecordKeys = new Set<string>();
 }
 
-function getTokenForBreakingChange(
+export function getTokenForBreakingChange(
   breakingChange: BreakingChange,
 ): Token | null {
   switch (breakingChange.kind) {
@@ -371,7 +390,10 @@ function getTokenForBreakingChange(
     }
     case "missing-slots":
     case "record-kind-change":
-    case "enum-variant-kind-change": {
+    case "variant-kind-change": {
+      return breakingChange.record.after.record.name;
+    }
+    case "missing-variant": {
       return breakingChange.record.after.record.name;
     }
     case "removed-number-reintroduced": {
@@ -384,7 +406,7 @@ function getTokenForBreakingChange(
   }
 }
 
-export function getTokenForExpression(expression: Expression): Token {
+function getTokenForExpression(expression: Expression): Token {
   switch (expression.kind) {
     case "item": {
       return getTokenForExpression(expression.arrayExpression);

package/src/compiler.ts

@@ -2,6 +2,7 @@
 import * as fs from "fs/promises";
 import { glob } from "glob";
 import * as paths from "path";
+import type { CodeGenerator } from "skir-internal";
 import Watcher from "watcher";
 import * as yaml from "yaml";
 import { fromZodError } from "zod-validation-error";
@@ -17,9 +18,9 @@ import { formatModule } from "./formatter.js";
 import { REAL_FILE_SYSTEM } from "./io.js";
 import { collectModules } from "./module_collector.js";
 import { ModuleSet } from "./module_set.js";
-import { takeSnapshot } from "./snapshotter.js";
+import { initializeProject } from "./project_initializer.js";
+import { takeSnapshot, viewSnapshot } from "./snapshotter.js";
 import { tokenizeModule } from "./tokenizer.js";
-import type { CodeGenerator } from "./types.js";
 
 interface GeneratorBundle<Config = unknown> {
   generator: CodeGenerator<Config>;
@@ -136,6 +137,9 @@ class WatchModeMainLoop {
         renderErrors(errors);
         return false;
       } else {
+        if (moduleSet.recordMap.size <= 0) {
+          console.error(makeRed("No skir modules found in source directory"));
+        }
         await this.doGenerate(moduleSet);
         if (this.watchModeOn) {
           const date = new Date().toLocaleTimeString("en-US");
@@ -291,12 +295,12 @@ async function format(root: string, mode: "fix" | "check"): Promise<void> {
     if (unformattedCode === undefined) {
       throw new Error(`Cannot read ${skirFile.fullpath()}`);
     }
-    const tokens = tokenizeModule(unformattedCode, "", "keep-comments");
+    const tokens = tokenizeModule(unformattedCode, "");
     if (tokens.errors.length) {
       renderErrors(tokens.errors);
       process.exit(1);
     }
-    const formattedCode = formatModule(tokens.result);
+    const formattedCode = formatModule(tokens.result).newSourceCode;
     pathToFormatResult.set(skirFile.fullpath(), {
       formattedCode: formattedCode,
       alreadyFormatted: formattedCode === unformattedCode,
@@ -347,6 +351,17 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
+  switch (args.kind) {
+    case "init": {
+      initializeProject(root!);
+      return;
+    }
+    case "help":
+    case "error": {
+      return;
+    }
+  }
+
   // Use an absolute path to make error messages more helpful.
   const skirConfigPath = paths.resolve(paths.join(root!, "skir.yml"));
   const skirConfigContents = REAL_FILE_SYSTEM.readTextFile(skirConfigPath);
@@ -375,7 +390,7 @@ async function main(): Promise<void> {
   switch (args.kind) {
     case "format": {
       // Check or fix the formatting to the .skir files in the source directory.
-      await format(srcDir, args.check ? "check" : "fix");
+      await format(srcDir, args.subcommand === "check" ? "check" : "fix");
       break;
     }
     case "gen": {
@@ -399,7 +414,7 @@ async function main(): Promise<void> {
           process.exit(1);
         }
       }
-      const watch = !!args.watch;
+      const watch = args.subcommand === "watch";
       const watchModeMainLoop = new WatchModeMainLoop(
         srcDir,
         generatorBundles,
@@ -413,21 +428,23 @@ async function main(): Promise<void> {
       }
       break;
     }
-    case "init": {
-      // TODO
-      break;
-    }
     case "snapshot": {
-      takeSnapshot({
-        rootDir: root!,
-        srcDir: srcDir,
-        check: !!args.check,
-      });
+      if (args.subcommand === "view") {
+        viewSnapshot({
+          rootDir: root!,
+        });
+      } else {
+        takeSnapshot({
+          rootDir: root!,
+          srcDir: srcDir,
+          check: args.subcommand === "check",
+        });
+      }
       break;
     }
-    case "help":
-    case "error": {
-      break;
+    default: {
+      const _: never = args;
+      throw new TypeError(_);
     }
   }
 }

package/src/definition_finder.ts

@@ -2,7 +2,7 @@
  * Utilities to help implement the jump-to-definition functionality for skir
  * files in IDEs.
  */
-import type { Declaration, Module, ResolvedType, Token } from "./types.js";
+import type { Declaration, Module, ResolvedType, Token } from "skir-internal";
 
 export interface DefinitionMatch {
   modulePath: string;

package/src/doc_comment_parser.ts

@@ -0,0 +1,251 @@
+import { assert } from "node:console";
+import type {
+  Doc,
+  DocPiece,
+  DocReference,
+  Result,
+  SkirError,
+  Token,
+} from "skir-internal";
+
+export function parseDocComments(docComments: readonly Token[]): Result<Doc> {
+  const parser = new DocCommentsParser(docComments);
+  return parser.parse();
+}
+
+class DocCommentsParser {
+  private readonly pieces: DocPiece[] = [];
+  private readonly errors: SkirError[] = [];
+  private currentText = "";
+  private docCommentIndex = -1;
+  private charIndex = -1;
+  private contentOffset = -1;
+
+  constructor(private readonly docComments: readonly Token[]) {}
+
+  parse(): Result<Doc> {
+    while (this.nextDocComment()) {
+      this.parseCurrentDocComment();
+    }
+
+    // Add any remaining text
+    if (this.currentText.length > 0) {
+      this.pieces.push({ kind: "text", text: this.currentText });
+    }
+
+    const text = this.docComments
+      .map((c) => c.text.slice(c.text.startsWith("/// ") ? 4 : 3))
+      .join("\n");
+
+    return {
+      result: {
+        text: text,
+        pieces: this.pieces,
+      },
+      errors: this.errors,
+    };
+  }
+
+  private parseCurrentDocComment(): void {
+    // Matches unescaped [ or ], OR escaped [[ or ]]
+    const specialCharRegex = /\[\[|\]\]|\[|\]/g;
+
+    while (this.charIndex < this.content.length) {
+      // Find next special character or escaped bracket
+      specialCharRegex.lastIndex = this.charIndex;
+      const match = specialCharRegex.exec(this.content);
+
+      if (!match) {
+        // No more special characters, add rest as text
+        this.currentText += this.content.slice(this.charIndex);
+        break;
+      }
+
+      // Add text before the special character
+      if (match.index > this.charIndex) {
+        this.currentText += this.content.slice(this.charIndex, match.index);
+      }
+
+      const matched = match[0];
+      this.charIndex = match.index;
+
+      if (matched === "[[") {
+        // Escaped left bracket
+        this.currentText += "[";
+        this.charIndex += 2;
+      } else if (matched === "]]") {
+        // Escaped right bracket
+        this.currentText += "]";
+        this.charIndex += 2;
+      } else if (matched === "[") {
+        // Start of a reference - save current text if any
+        if (this.currentText.length > 0) {
+          this.pieces.push({ kind: "text", text: this.currentText });
+          this.currentText = "";
+        }
+
+        // Parse the reference
+        const reference = this.parseReference();
+        this.pieces.push(reference);
+      } else if (matched === "]") {
+        // Unmatched right bracket - treat as text
+        this.currentText += matched;
+        this.charIndex++;
+      }
+    }
+
+    // Add newline between comment lines (except after the last line)
+    if (this.docCommentIndex < this.docComments.length - 1) {
+      this.currentText += "\n";
+    }
+  }
+
+  private parseReference(): DocReference {
+    const { content, docComment } = this;
+
+    const leftBracketCharIndex = this.charIndex;
+    const startPosition = docComment.position + leftBracketCharIndex;
+
+    const rightBracketCharIndex = content.indexOf("]", leftBracketCharIndex);
+
+    // End position: right after the closing bracket or at end of the line if
+    // not found.
+    const endCharIndex =
+      rightBracketCharIndex < 0 ? content.length : rightBracketCharIndex + 1;
+
+    const referenceText = content.slice(leftBracketCharIndex, endCharIndex);
+    const referenceRange: Token = {
+      text: referenceText,
+      originalText: referenceText,
+      position: startPosition,
+      line: docComment.line,
+      colNumber: startPosition - docComment.line.position,
+    };
+
+    let hasError = false;
+    if (rightBracketCharIndex < 0) {
+      hasError = true;
+      this.errors.push({
+        token: referenceRange,
+        message: "Unterminated reference",
+      });
+    }
+
+    // Move past the left bracket
+    this.charIndex++;
+
+    const wordRegex = /[a-zA-Z][_a-zA-Z0-9]*/g;
+
+    const tokens: Token[] = [];
+    while (this.charIndex < endCharIndex) {
+      const char = content[this.charIndex]!;
+      const position = docComment.position + this.charIndex;
+
+      const makeToken = (text: string): Token => ({
+        text: text,
+        originalText: text,
+        position: position,
+        line: docComment.line,
+        colNumber: position - docComment.line.position,
+      });
+
+      if (char === ".") {
+        // Dot token
+        tokens.push(makeToken("."));
+        this.charIndex++;
+      } else if (/^[a-zA-Z]/.test(char)) {
+        // Start of a word token - use regex to match the whole word
+        wordRegex.lastIndex = this.charIndex;
+        const match = wordRegex.exec(content);
+        const word = match![0];
+        tokens.push(makeToken(word));
+        this.charIndex += word.length;
+      } else if (char === "]") {
+        // Reached the end of the reference
+        tokens.push(makeToken("]"));
+        this.charIndex++;
+      } else {
+        // Invalid character in reference (including whitespace)
+        const column = this.docComment.colNumber + this.charIndex;
+        hasError = true;
+        this.errors.push({
+          token: referenceRange,
+          message: `Invalid character in reference at column ${column + 1}`,
+        });
+        // Exit loop
+        this.charIndex = endCharIndex;
+      }
+    }
+
+    const nameChain = hasError ? [] : this.parseNameChain(tokens);
+
+    return {
+      kind: "reference",
+      nameChain: nameChain,
+      absolute: tokens[0]?.text === ".",
+      referee: undefined,
+      docComment: this.docComment,
+      referenceRange: referenceRange,
+    };
+  }
+
+  private parseNameChain(tokens: readonly Token[]): Token[] {
+    const nameChain: Token[] = [];
+    let expect: "identifier" | "identifier or '.'" | "'.' or ']'" =
+      "identifier or '.'";
+    for (const token of tokens) {
+      let expected: boolean;
+      if (/^[a-zA-Z]/.test(token.text)) {
+        expected = expect === "identifier or '.'" || expect === "identifier";
+        expect = "'.' or ']'";
+        nameChain.push(token);
+      } else if (token.text === ".") {
+        expected = expect === "identifier or '.'" || expect === "'.' or ']'";
+        expect = "identifier";
+      } else {
+        assert(token.text === "]");
+        expected = expect === "'.' or ']'";
+      }
+      if (!expected) {
+        this.errors.push({
+          token: token,
+          expected: expect,
+        });
+        return [];
+      }
+      if (token.text === "]") {
+        return nameChain;
+      }
+    }
+    // An error has already been pushed to signify the unterminated reference.
+    return [];
+  }
+
+  /// The current doc comment being parsed.
+  private get docComment(): Token {
+    return this.docComments[this.docCommentIndex]!;
+  }
+
+  /// The text of the current doc comment being parsed.
+  private get content(): string {
+    return this.docComment.text;
+  }
+
+  private nextDocComment(): boolean {
+    if (this.docCommentIndex < this.docComments.length - 1) {
+      this.docCommentIndex++;
+      const { content } = this;
+      if (content.startsWith("/// ")) {
+        this.contentOffset = 4;
+      } else if (content.startsWith("///")) {
+        this.contentOffset = 3;
+      } else {
+        throw new Error("Expected doc comment to start with ///");
+      }
+      this.charIndex = this.contentOffset;
+      return true;
+    } else {
+      return false;
+    }
+  }
+}