skir 0.0.5 → 0.0.7

package/src/module_set.ts

@@ -1,5 +1,6 @@
-import * as paths from "path";
+import * as Paths from "path";
 import {
+  MutableDocReferenceName,
   unquoteAndUnescape,
   type DenseJson,
   type ErrorSink,
@@ -10,6 +11,7 @@ import {
   type Module,
   type MutableArrayType,
   type MutableConstant,
+  type MutableDoc,
   type MutableDocReference,
   type MutableMethod,
   type MutableModule,
@@ -812,7 +814,7 @@ export class ModuleSet {
     module: Module,
     errors: ErrorSink,
   ): void {
-    const doc =
+    const doc: MutableDoc =
       documentee.kind === "field" ? documentee.field.doc : documentee.doc;
 
     const docReferences = doc.pieces.filter(
@@ -826,23 +828,24 @@ export class ModuleSet {
     // Returns true if resolved, false otherwise.
     const tryResolveReference = (
       ref: MutableDocReference,
-      nameChain: readonly Token[],
+      nameParts: readonly MutableDocReferenceName[],
       scope: Record | Module,
     ): boolean => {
       if (ref.absolute && scope !== module) {
         return false;
       }
-      const firstName = nameChain[0]!;
-      const match = scope.nameToDeclaration[firstName.text];
+      const firstName = nameParts[0]!;
+      const match = scope.nameToDeclaration[firstName.token.text];
       if (!match) {
         return false;
       }
-      if (nameChain.length === 1) {
+      if (nameParts.length === 1) {
         // Single name: must refer to a declaration.
         switch (match.kind) {
           case "constant":
           case "method":
           case "record": {
+            firstName.declaration = match;
             ref.referee = match;
             return true;
           }
@@ -850,6 +853,7 @@ export class ModuleSet {
             if (scope.kind !== "record") {
               throw new TypeError(scope.kind);
             }
+            firstName.declaration = match;
             ref.referee = {
               kind: "field",
               field: match,
@@ -857,16 +861,21 @@ export class ModuleSet {
             };
             return true;
           }
+          case "import-alias": {
+            firstName.declaration = match;
+            return false;
+          }
           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 "record": {
+            firstName.declaration = match;
+            return tryResolveReference(ref, nameParts.slice(1), match);
+          }
           case "import":
           case "import-alias": {
             if (scope !== module) {
@@ -881,9 +890,13 @@ export class ModuleSet {
             if (!importedModule?.result) {
               return false;
             }
-            const newNameChain = nameChain.slice(
-              match.kind === "import" ? 0 : 1,
-            );
+            let newNameChain: readonly MutableDocReferenceName[];
+            if (match.kind === "import") {
+              newNameChain = nameParts;
+            } else {
+              firstName.declaration = match;
+              newNameChain = nameParts.slice(1);
+            }
             return tryResolveReference(
               ref,
               newNameChain,
@@ -892,7 +905,10 @@ export class ModuleSet {
           }
           case "constant":
           case "field":
-          case "method":
+          case "method": {
+            firstName.declaration = match;
+            return false;
+          }
           case "removed":
             return false;
         }
@@ -947,13 +963,13 @@ export class ModuleSet {
 
     // Resolve each reference by searching through scopes in priority order.
     for (const reference of docReferences) {
-      const { nameChain } = reference;
-      if (nameChain.length <= 0) {
+      const { nameParts } = reference;
+      if (nameParts.length <= 0) {
         continue;
       }
       let resolved = false;
       for (const scope of scopes) {
-        if (tryResolveReference(reference, nameChain, scope)) {
+        if (tryResolveReference(reference, nameParts, scope)) {
           resolved = true;
           break;
         }
@@ -1295,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));
   }
 }
 
@@ -1325,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

@@ -7,6 +7,7 @@ import type {
   ImportAlias,
   MutableConstant,
   MutableDeclaration,
+  MutableDoc,
   MutableField,
   MutableMethod,
   MutableModule,
@@ -27,15 +28,15 @@ import type {
   UnresolvedType,
 } from "skir-internal";
 import { convertCase, simpleHash } from "skir-internal";
-import * as casing from "./casing.js";
-import { parseDocComments } from "./doc_comment_parser.js";
+import * as Casing from "./casing.js";
+import { mergeDocs } from "./doc_comment_parser.js";
 import { ModuleTokens } from "./tokenizer.js";
 
 /** Runs syntactic analysis on a module. */
 export function parseModule(moduleTokens: ModuleTokens): Result<MutableModule> {
-  const { tokens, modulePath, sourceCode } = moduleTokens;
+  const { modulePath, sourceCode } = moduleTokens;
   const errors: SkirError[] = [];
-  const it = new TokenIterator(tokens, errors);
+  const it = new TokenIterator(moduleTokens, errors);
   const declarations = parseDeclarations(it, "module");
   it.expectThenNext([""]);
   // Create a mappinng from names to declarations, and check for duplicates.
@@ -160,7 +161,7 @@ function parseDeclaration(
   it: TokenIterator,
   parentNode: "module" | "struct" | "enum",
 ): MutableDeclaration | null {
-  const doc = parseDoc(it);
+  const doc = collectDoc(it);
   let recordType: "struct" | "enum" = "enum";
   const parentIsRoot = parentNode === "module";
   const expected = [
@@ -397,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;
@@ -475,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,
@@ -789,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) {
@@ -837,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;
   }
@@ -897,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;
   }
@@ -1046,15 +1047,16 @@ function parseArrayValue(it: TokenIterator): MutableValue[] | null {
   }
 }
 
-function parseDoc(it: TokenIterator): Doc {
+function collectDoc(it: TokenIterator): MutableDoc {
+  const { moduleTokens } = it;
   const docComments: Token[] = [];
   while (it.current.startsWith("///")) {
     docComments.push(it.currentToken);
     it.next();
   }
-  const result = parseDocComments(docComments);
-  result.errors.forEach((e) => it.errors.push(e));
-  return result.result;
+  return mergeDocs(
+    docComments.map((c) => moduleTokens.posToDoc[c.position] ?? EMPTY_DOC),
+  );
 }
 
 const EMPTY_DOC: Doc = {
@@ -1121,10 +1123,14 @@ interface TokenMatch {
 }
 
 class TokenIterator {
+  private readonly tokens: readonly Token[];
+
   constructor(
-    private readonly tokens: readonly Token[],
+    readonly moduleTokens: ModuleTokens,
     readonly errors: ErrorSink,
-  ) {}
+  ) {
+    this.tokens = moduleTokens.tokens;
+  }
 
   // Returns both:
   //   · the index of the first predicate matching the current token, or -1 if

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.

package/src/tokenizer.ts

@@ -1,17 +1,23 @@
 import {
   unquoteAndUnescape,
   type CodeLine,
+  type Doc,
   type ErrorSink,
   type Result,
   type SkirError,
   type Token,
 } from "skir-internal";
+import { parseDocComment } from "./doc_comment_parser.js";
 
 export interface ModuleTokens {
-  /// Includes regular comments and doc comments.
+  /** Includes regular comments and doc comments. */
   readonly tokens: readonly Token[];
-  /// Includes both kinds of comments.
+  /** Includes both kinds of comments. */
   readonly tokensWithComments: readonly Token[];
+  /** Maps the start position of a doc comment (///) to the parsed documentation. */
+  readonly posToDoc: Readonly<{
+    [pos: number]: Doc;
+  }>;
   readonly sourceCode: string;
   readonly modulePath: string;
 }
@@ -133,10 +139,22 @@ export function tokenizeModule(
     }
   }
 
+  // Parse the doc comments.
+  const posToDoc: { [pos: number]: Doc } = {};
+  for (const token of tokens) {
+    if (!token.text.startsWith("///")) {
+      continue;
+    }
+    const docResult = parseDocComment(token);
+    posToDoc[token.position] = docResult.result;
+    docResult.errors.forEach((e) => errors.push(e));
+  }
+
   return {
     result: {
       tokens: tokens.filter((t) => !isRegularComment(t.originalText)),
       tokensWithComments: tokens,
+      posToDoc: posToDoc,
       sourceCode: sourceCode,
       modulePath: modulePath,
     },

package/dist/language_server.d.ts

@@ -1,15 +0,0 @@
-export declare class LanguageServerModuleSet {
-    private readonly rootPath;
-    constructor(rootPath: string);
-    setFileContent(uri: string, content: string): void;
-    deleteFile(uri: string): void;
-    private reassignModulesToWorkspaces;
-    private parseSkirConfig;
-    private parseSkirModule;
-    /** Finds the workspace which contains the given module URI. */
-    private findModuleWorkspace;
-    private reassigneModulesTimeout?;
-    private readonly moduleBundles;
-    private readonly workspaces;
-}
-//# sourceMappingURL=language_server.d.ts.map

package/dist/language_server.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"language_server.d.ts","sourceRoot":"","sources":["../src/language_server.ts"],"names":[],"mappings":"AAeA,qBAAa,uBAAuB;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,MAAM;IAE7C,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IA2BlD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAuB7B,OAAO,CAAC,2BAA2B;IAoBnC,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,eAAe;IAmBvB,+DAA+D;IAC/D,OAAO,CAAC,mBAAmB;IA8B3B,OAAO,CAAC,uBAAuB,CAAC,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgC;CAC5D"}