kopscript 0.1.0 → 0.3.0

package/dist/modules.js

@@ -29,7 +29,7 @@ export function loadModuleGraph(entryAbsPath) {
         const diagnostics = new DiagnosticBag();
         const tokens = new Lexer(source, diagnostics).tokenize();
         const program = new Parser(tokens, diagnostics).parseProgram();
-        const record = { absPath, source, program, diagnostics, dependencies: [] };
+        const record = { absPath, source, program, diagnostics, dependencies: [], hoverEntries: [] };
         modules.set(absPath, record);
         stack.push(absPath);
         for (const u of program.usings) {
@@ -66,6 +66,7 @@ export function compileGraph(entryAbsPath) {
         return { success: false, entryMissing: true, modules, order, outputs: new Map() };
     }
     const exportsByModule = new Map();
+    const rawContentsByModule = new Map();
     let hasErrors = false;
     for (const absPath of order) {
         const mod = modules.get(absPath);
@@ -104,11 +105,13 @@ export function compileGraph(entryAbsPath) {
             for (const [name, info] of depExports.enums)
                 merged.enums.set(name, info);
         }
-        const checker = new Checker(mod.program, mod.diagnostics, merged);
+        const checker = new Checker(mod.program, mod.diagnostics, merged, absPath);
         checker.check();
+        mod.hoverEntries = checker.hoverEntries;
         if (mod.diagnostics.hasErrors)
             hasErrors = true;
         exportsByModule.set(absPath, checker.getExports());
+        rawContentsByModule.set(absPath, checker.getRawContents());
     }
     if (hasErrors) {
         return { success: false, entryMissing: false, modules, order, outputs: new Map() };
@@ -127,7 +130,7 @@ export function compileGraph(entryAbsPath) {
                 usingExports.set(u.path, [...importableTypeNames, ...depExports.functions.keys(), ...depExports.externValues.keys()]);
             }
         }
-        outputs.set(absPath, new CodeGenerator().generate(mod.program, usingExports));
+        outputs.set(absPath, new CodeGenerator().generate(mod.program, usingExports, rawContentsByModule.get(absPath) ?? new Map()));
     }
     return { success: true, entryMissing: false, modules, order, outputs };
 }

package/dist/parser.js

@@ -50,6 +50,8 @@ export class Parser {
                 return this.parseEnumDecl(true);
             if (this.check(TokenKind.Extern))
                 return this.parseExternDecl(true);
+            if (this.check(TokenKind.Raw))
+                return this.parseRawStringDecl(true);
             if (this.check(TokenKind.LBrace))
                 return this.parseBlock();
             if (this.check(TokenKind.If))
@@ -102,6 +104,8 @@ export class Parser {
             return this.parseEnumDecl(isExported);
         if (this.check(TokenKind.Extern))
             return this.parseExternDecl(isExported);
+        if (this.check(TokenKind.Raw))
+            return this.parseRawStringDecl(isExported);
         if (this.isDeclStart()) {
             const decl = this.parseDeclaration(isExported);
             if (decl.kind === "VarDecl") {
@@ -149,7 +153,8 @@ export class Parser {
             this.advance();
         }
         const type = this.parseType();
-        const name = this.consume(TokenKind.Identifier, "Expected name").lexeme;
+        const nameTok = this.consume(TokenKind.Identifier, "Expected name");
+        const name = nameTok.lexeme;
         if (this.check(TokenKind.LParen)) {
             const params = this.parseParamList();
             const body = this.parseBlock();
@@ -161,7 +166,7 @@ export class Parser {
         this.consume(TokenKind.Assign, "Expected '=' in variable declaration");
         const init = this.parseExpression();
         this.consume(TokenKind.Semicolon, "Expected ';' after variable declaration");
-        return { kind: "VarDecl", isConst: false, name, type, init, line: start.line, col: start.col };
+        return { kind: "VarDecl", isConst: false, name, nameLine: nameTok.line, nameCol: nameTok.col, type, init, line: start.line, col: start.col };
     }
     // Parses `Type name = init` without consuming a trailing terminator — used
     // both for top-level/block statements (which add the `;`) and for-loop
@@ -169,18 +174,18 @@ export class Parser {
     parseVarDeclHeader() {
         const start = this.peek();
         const type = this.parseType();
-        const name = this.consume(TokenKind.Identifier, "Expected variable name").lexeme;
+        const nameTok = this.consume(TokenKind.Identifier, "Expected variable name");
         this.consume(TokenKind.Assign, "Expected '=' in variable declaration");
         const init = this.parseExpression();
-        return { kind: "VarDecl", isConst: false, name, type, init, line: start.line, col: start.col };
+        return { kind: "VarDecl", isConst: false, name: nameTok.lexeme, nameLine: nameTok.line, nameCol: nameTok.col, type, init, line: start.line, col: start.col };
     }
     parseConstDecl() {
         const start = this.advance(); // 'const'
         const type = this.parseType();
-        const name = this.consume(TokenKind.Identifier, "Expected constant name").lexeme;
+        const nameTok = this.consume(TokenKind.Identifier, "Expected constant name");
         this.consume(TokenKind.Assign, "Expected '=' in constant declaration");
         const init = this.parseExpression();
-        return { kind: "VarDecl", isConst: true, name, type, init, line: start.line, col: start.col };
+        return { kind: "VarDecl", isConst: true, name: nameTok.lexeme, nameLine: nameTok.line, nameCol: nameTok.col, type, init, line: start.line, col: start.col };
     }
     parseParamList() {
         this.consume(TokenKind.LParen, "Expected '('");
@@ -256,7 +261,8 @@ export class Parser {
             }
             const memberStart = this.peek();
             const type = this.parseType();
-            const memberName = this.consume(TokenKind.Identifier, "Expected field, property, or method name").lexeme;
+            const memberNameTok = this.consume(TokenKind.Identifier, "Expected field, property, or method name");
+            const memberName = memberNameTok.lexeme;
             if (this.check(TokenKind.LParen)) {
                 const params = this.parseParamList();
                 const body = this.parseBlock();
@@ -271,6 +277,8 @@ export class Parser {
                     isVirtual,
                     isOverride,
                     name: memberName,
+                    nameLine: memberNameTok.line,
+                    nameCol: memberNameTok.col,
                     params,
                     returnType: type,
                     body,
@@ -303,6 +311,8 @@ export class Parser {
                     visibility,
                     hasSetter,
                     name: memberName,
+                    nameLine: memberNameTok.line,
+                    nameCol: memberNameTok.col,
                     type,
                     line: memberStart.line,
                     col: memberStart.col,
@@ -327,6 +337,8 @@ export class Parser {
                     isStatic,
                     initializer,
                     name: memberName,
+                    nameLine: memberNameTok.line,
+                    nameCol: memberNameTok.col,
                     type,
                     line: memberStart.line,
                     col: memberStart.col,
@@ -350,10 +362,18 @@ export class Parser {
         while (!this.check(TokenKind.RBrace) && !this.check(TokenKind.EOF)) {
             const memberStart = this.peek();
             const returnType = this.parseType();
-            const methodName = this.consume(TokenKind.Identifier, "Expected method name").lexeme;
+            const methodNameTok = this.consume(TokenKind.Identifier, "Expected method name");
             const params = this.parseParamList();
             this.consume(TokenKind.Semicolon, "Expected ';' after interface method signature");
-            methods.push({ name: methodName, params, returnType, line: memberStart.line, col: memberStart.col });
+            methods.push({
+                name: methodNameTok.lexeme,
+                nameLine: methodNameTok.line,
+                nameCol: methodNameTok.col,
+                params,
+                returnType,
+                line: memberStart.line,
+                col: memberStart.col,
+            });
         }
         this.consume(TokenKind.RBrace, "Expected '}' after interface body");
         return { kind: "InterfaceDecl", isExported, name, baseList, methods, line: start.line, col: start.col };
@@ -405,6 +425,22 @@ export class Parser {
         }
         return { modulePath, jsName };
     }
+    // `raw string <Name> from "<path>";` — embeds a real file's contents as a
+    // JS string constant at compile time. Type must be literally 'string' (no
+    // other type makes sense for file contents); no 'as' clause — there's no
+    // JS-side name to alias, unlike extern.
+    parseRawStringDecl(isExported) {
+        const start = this.advance(); // 'raw'
+        const typeTok = this.consume(TokenKind.Identifier, "Expected 'string' after 'raw'");
+        if (typeTok.lexeme !== "string") {
+            this.diagnostics.error(`'raw' declarations must be of type 'string', got '${typeTok.lexeme}'`, typeTok.line, typeTok.col);
+        }
+        const name = this.consume(TokenKind.Identifier, "Expected name").lexeme;
+        this.consume(TokenKind.From, "Expected 'from \"<path>\"' after 'raw string <Name>'");
+        const pathTok = this.consume(TokenKind.String, "Expected a file path string after 'from'");
+        this.consume(TokenKind.Semicolon, "Expected ';' after 'raw' declaration");
+        return { kind: "RawStringDecl", isExported, name, path: pathTok.lexeme, line: start.line, col: start.col };
+    }
     parseExternClassBody(start, isExported) {
         const name = this.consume(TokenKind.Identifier, "Expected class name").lexeme;
         this.consume(TokenKind.LBrace, "Expected '{' before extern class body");
@@ -584,8 +620,8 @@ export class Parser {
             type = this.parseFunctionType();
         }
         else if (this.check(TokenKind.Task)) {
-            this.advance();
-            let resultType = { kind: "NamedType", name: "void" };
+            const taskTok = this.advance();
+            let resultType = { kind: "NamedType", name: "void", line: taskTok.line, col: taskTok.col };
             if (this.match(TokenKind.Lt)) {
                 resultType = this.parseType();
                 this.consume(TokenKind.Gt, "Expected '>' after task result type");
@@ -601,12 +637,21 @@ export class Parser {
         }
         else {
             const nameToken = this.check(TokenKind.Void) ? this.advance() : this.consume(TokenKind.Identifier, "Expected type name");
-            type = { kind: "NamedType", name: nameToken.lexeme };
+            type = { kind: "NamedType", name: nameToken.lexeme, line: nameToken.line, col: nameToken.col };
         }
-        while (this.check(TokenKind.LBracket)) {
-            this.advance();
-            this.consume(TokenKind.RBracket, "Expected ']' after '[' in array type");
-            type = { kind: "ArrayType", element: type };
+        // `[]` and `?` are both postfix and can alternate in either order —
+        // `string?[]` (array of nullable strings) and `string[]?` (nullable
+        // array of strings) parse with the nesting their order implies.
+        while (this.check(TokenKind.LBracket) || this.check(TokenKind.Question)) {
+            if (this.check(TokenKind.LBracket)) {
+                this.advance();
+                this.consume(TokenKind.RBracket, "Expected ']' after '[' in array type");
+                type = { kind: "ArrayType", element: type };
+            }
+            else {
+                const q = this.advance();
+                type = { kind: "NullableType", inner: type, line: q.line, col: q.col };
+            }
         }
         return type;
     }
@@ -759,6 +804,10 @@ export class Parser {
             this.advance();
             return { kind: "BoolLiteral", value: t.kind === TokenKind.True, line: t.line, col: t.col };
         }
+        if (this.check(TokenKind.Null)) {
+            this.advance();
+            return { kind: "NullLiteral", line: t.line, col: t.col };
+        }
         if (this.check(TokenKind.This)) {
             this.advance();
             return { kind: "ThisExpr", line: t.line, col: t.col };
@@ -828,8 +877,18 @@ export class Parser {
         if (startKind !== TokenKind.Identifier && startKind !== TokenKind.Void)
             return false;
         i++;
-        while (this.tokens[i]?.kind === TokenKind.LBracket && this.tokens[i + 1]?.kind === TokenKind.RBracket) {
-            i += 2;
+        // Mirrors parseType's postfix loop: `[]` and `?` can alternate in
+        // either order (`string?[]`, `string[]?`) after the base type name.
+        while (true) {
+            if (this.tokens[i]?.kind === TokenKind.LBracket && this.tokens[i + 1]?.kind === TokenKind.RBracket) {
+                i += 2;
+            }
+            else if (this.tokens[i]?.kind === TokenKind.Question) {
+                i += 1;
+            }
+            else {
+                break;
+            }
         }
         return this.tokens[i]?.kind === TokenKind.Identifier;
     }
@@ -976,6 +1035,7 @@ export class Parser {
                 this.check(TokenKind.Interface) ||
                 this.check(TokenKind.Enum) ||
                 this.check(TokenKind.Extern) ||
+                this.check(TokenKind.Raw) ||
                 this.check(TokenKind.Const) ||
                 this.check(TokenKind.If) ||
                 this.check(TokenKind.While) ||

package/dist/tokens.js

@@ -8,9 +8,11 @@ export var TokenKind;
     TokenKind["Identifier"] = "Identifier";
     TokenKind["True"] = "True";
     TokenKind["False"] = "False";
+    TokenKind["Null"] = "Null";
     // Keywords
     TokenKind["Using"] = "Using";
     TokenKind["Extern"] = "Extern";
+    TokenKind["Raw"] = "Raw";
     TokenKind["From"] = "From";
     TokenKind["As"] = "As";
     TokenKind["Const"] = "Const";
@@ -61,6 +63,7 @@ export var TokenKind;
     TokenKind["Dot"] = "Dot";
     TokenKind["Arrow"] = "Arrow";
     TokenKind["Underscore"] = "Underscore";
+    TokenKind["Question"] = "Question";
     // Operators
     TokenKind["Plus"] = "Plus";
     TokenKind["Minus"] = "Minus";

package/dist/types.js

@@ -24,6 +24,9 @@ export function taskType(resultType) {
 export function stateType(valueType) {
     return { kind: "state", valueType };
 }
+export function nullableOf(inner) {
+    return inner.kind === "nullable" ? inner : { kind: "nullable", inner };
+}
 export function typeToString(t) {
     switch (t.kind) {
         case "number":
@@ -44,46 +47,55 @@ export function typeToString(t) {
             return t.resultType.kind === "void" ? "task" : `task<${typeToString(t.resultType)}>`;
         case "state":
             return `state<${typeToString(t.valueType)}>`;
+        case "nullable":
+            return `${typeToString(t.inner)}?`;
     }
 }
 const PRIMITIVE_NAMES = new Set(["number", "string", "bool", "void"]);
 // Resolves a syntactic type annotation to a Type, given the kind of every known
-// user-declared name (class, interface, or enum).
-export function resolveTypeNode(node, namedTypes) {
+// user-declared name (class, interface, or enum). `onNamedType`, when given, is
+// called with every `NamedType` leaf visited and the Type it resolved to — a
+// hook for tools (e.g. hover) that want to know what a type annotation in
+// source actually refers to, without duplicating this resolution logic.
+export function resolveTypeNode(node, namedTypes, onNamedType) {
     if (node.kind === "ArrayType") {
-        const element = resolveTypeNode(node.element, namedTypes);
+        const element = resolveTypeNode(node.element, namedTypes, onNamedType);
         return element ? arrayOf(element) : null;
     }
     if (node.kind === "FunctionType") {
         const params = [];
         for (const p of node.params) {
-            const resolved = resolveTypeNode(p, namedTypes);
+            const resolved = resolveTypeNode(p, namedTypes, onNamedType);
             if (!resolved)
                 return null;
             params.push(resolved);
         }
-        const returnType = resolveTypeNode(node.returnType, namedTypes);
+        const returnType = resolveTypeNode(node.returnType, namedTypes, onNamedType);
         return returnType ? functionType(params, returnType) : null;
     }
     if (node.kind === "TaskType") {
-        const resultType = resolveTypeNode(node.resultType, namedTypes);
+        const resultType = resolveTypeNode(node.resultType, namedTypes, onNamedType);
         return resultType ? taskType(resultType) : null;
     }
     if (node.kind === "StateType") {
-        const valueType = resolveTypeNode(node.valueType, namedTypes);
+        const valueType = resolveTypeNode(node.valueType, namedTypes, onNamedType);
         return valueType ? stateType(valueType) : null;
     }
+    if (node.kind === "NullableType") {
+        const inner = resolveTypeNode(node.inner, namedTypes, onNamedType);
+        return inner ? nullableOf(inner) : null;
+    }
+    let resolved;
     if (PRIMITIVE_NAMES.has(node.name)) {
-        return { kind: node.name };
+        resolved = { kind: node.name };
     }
-    const kind = namedTypes.get(node.name);
-    if (kind === "class")
-        return classType(node.name);
-    if (kind === "interface")
-        return interfaceType(node.name);
-    if (kind === "enum")
-        return enumType(node.name);
-    return null;
+    else {
+        const kind = namedTypes.get(node.name);
+        resolved = kind === "class" ? classType(node.name) : kind === "interface" ? interfaceType(node.name) : kind === "enum" ? enumType(node.name) : null;
+    }
+    if (resolved)
+        onNamedType?.(node, resolved);
+    return resolved;
 }
 export function typesEqual(a, b) {
     if (a.kind === "unknown" || b.kind === "unknown")
@@ -101,6 +113,9 @@ export function typesEqual(a, b) {
     if (a.kind === "state" && b.kind === "state") {
         return typesEqual(a.valueType, b.valueType);
     }
+    if (a.kind === "nullable" && b.kind === "nullable") {
+        return typesEqual(a.inner, b.inner);
+    }
     if ((a.kind === "class" || a.kind === "interface" || a.kind === "enum") && "name" in b) {
         return a.name === b.name;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopscript",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "KopScript: a small OOP, strongly-typed language that transpiles to JavaScript",
   "type": "module",
   "license": "MIT",
@@ -19,7 +19,9 @@
   "main": "./dist/modules.js",
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "assets",
+    "LLM.md"
   ],
   "bin": {
     "ks": "bin/ks.js"