qsharp-lang 0.1.0-dev.1

package/dist/katas.d.ts

@@ -0,0 +1,55 @@
+export type Example = {
+    type: "example";
+    id: string;
+    code: string;
+};
+export type TextContent = {
+    type: "text-content";
+    asHtml: string;
+    asMarkdown: string;
+};
+export type ContentItem = Example | TextContent;
+export type Solution = {
+    type: "solution";
+    id: string;
+    code: string;
+};
+export type ExplainedSolutionItem = ContentItem | Solution;
+export type ExplainedSolution = {
+    type: "explained-solution";
+    items: ExplainedSolutionItem[];
+};
+export type Exercise = {
+    type: "exercise";
+    id: string;
+    title: string;
+    description: TextContent;
+    sourceIds: string[];
+    placeholderCode: string;
+    explainedSolution: ExplainedSolution;
+};
+export type Answer = {
+    type: "answer";
+    items: ContentItem[];
+};
+export type Question = {
+    type: "question";
+    description: TextContent;
+    answer: Answer;
+};
+export type LessonItem = ContentItem | Question;
+export type Lesson = {
+    type: "lesson";
+    id: string;
+    title: string;
+    items: LessonItem[];
+};
+export type KataSection = Exercise | Lesson;
+export type Kata = {
+    id: string;
+    title: string;
+    sections: KataSection[];
+};
+export declare function getAllKatas(): Promise<Kata[]>;
+export declare function getKata(id: string): Promise<Kata>;
+export declare function getExerciseSources(exercise: Exercise): Promise<string[]>;

package/dist/katas.js

@@ -0,0 +1,16 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { default as katasContent } from "./katas-content.generated.js";
+export async function getAllKatas() {
+    return katasContent.katas;
+}
+export async function getKata(id) {
+    const katas = await getAllKatas();
+    return (katas.find((k) => k.id === id) ||
+        Promise.reject(`Failed to get kata with id: ${id}`));
+}
+export async function getExerciseSources(exercise) {
+    return katasContent.globalCodeSources
+        .filter((source) => exercise.sourceIds.indexOf(source.id) > -1)
+        .map((source) => source.code);
+}

package/dist/language-service/language-service.d.ts

@@ -0,0 +1,48 @@
+import type { IDiagnostic, ICompletionList, IHover, IDefinition } from "../../lib/node/qsc_wasm.cjs";
+import { VSDiagnostic } from "../vsdiagnostic.js";
+import { IServiceProxy } from "../worker-proxy.js";
+type QscWasm = typeof import("../../lib/node/qsc_wasm.cjs");
+export type LanguageServiceEvent = {
+    type: "diagnostics";
+    detail: {
+        uri: string;
+        version: number;
+        diagnostics: VSDiagnostic[];
+    };
+};
+export interface ILanguageService {
+    updateDocument(uri: string, version: number, code: string, isExe: boolean): Promise<void>;
+    closeDocument(uri: string): Promise<void>;
+    getCompletions(documentUri: string, offset: number): Promise<ICompletionList>;
+    getHover(documentUri: string, offset: number): Promise<IHover | null>;
+    getDefinition(documentUri: string, offset: number): Promise<IDefinition | null>;
+    dispose(): Promise<void>;
+    addEventListener<T extends LanguageServiceEvent["type"]>(type: T, listener: (event: Extract<LanguageServiceEvent, {
+        type: T;
+    }>) => void): void;
+    removeEventListener<T extends LanguageServiceEvent["type"]>(type: T, listener: (event: Extract<LanguageServiceEvent, {
+        type: T;
+    }>) => void): void;
+}
+export declare const qsharpLibraryUriScheme = "qsharp-library-source";
+export type ILanguageServiceWorker = ILanguageService & IServiceProxy;
+export declare class QSharpLanguageService implements ILanguageService {
+    private languageService;
+    private eventHandler;
+    private code;
+    constructor(wasm: QscWasm);
+    updateDocument(documentUri: string, version: number, code: string, isExe: boolean): Promise<void>;
+    closeDocument(documentUri: string): Promise<void>;
+    getCompletions(documentUri: string, offset: number): Promise<ICompletionList>;
+    getHover(documentUri: string, offset: number): Promise<IHover | null>;
+    getDefinition(documentUri: string, offset: number): Promise<IDefinition | null>;
+    dispose(): Promise<void>;
+    addEventListener<T extends LanguageServiceEvent["type"]>(type: T, listener: (event: Extract<LanguageServiceEvent, {
+        type: T;
+    }>) => void): void;
+    removeEventListener<T extends LanguageServiceEvent["type"]>(type: T, listener: (event: Extract<LanguageServiceEvent, {
+        type: T;
+    }>) => void): void;
+    onDiagnostics(uri: string, version: number, diagnostics: IDiagnostic[]): void;
+}
+export {};

package/dist/language-service/language-service.js

@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import * as wasm from "../../lib/web/qsc_wasm.js";
+import { log } from "../log.js";
+import { mapDiagnostics, mapUtf16UnitsToUtf8Units, mapUtf8UnitsToUtf16Units, } from "../vsdiagnostic.js";
+export const qsharpLibraryUriScheme = "qsharp-library-source";
+export class QSharpLanguageService {
+    constructor(wasm) {
+        this.eventHandler = new EventTarget();
+        // We need to keep a copy of the code for mapping diagnostics to utf16 offsets
+        this.code = {};
+        log.info("Constructing a QSharpLanguageService instance");
+        this.languageService = new wasm.LanguageService(this.onDiagnostics.bind(this));
+    }
+    async updateDocument(documentUri, version, code, isExe) {
+        this.code[documentUri] = code;
+        this.languageService.update_document(documentUri, version, code, isExe);
+    }
+    async closeDocument(documentUri) {
+        delete this.code[documentUri];
+        this.languageService.close_document(documentUri);
+    }
+    async getCompletions(documentUri, offset) {
+        const code = this.code[documentUri];
+        const convertedOffset = mapUtf16UnitsToUtf8Units([offset], code)[offset];
+        const result = this.languageService.get_completions(documentUri, convertedOffset);
+        result.items.forEach((item) => item.additionalTextEdits?.forEach((edit) => {
+            const mappedSpan = mapUtf8UnitsToUtf16Units([edit.range.start, edit.range.end], code);
+            edit.range.start = mappedSpan[edit.range.start];
+            edit.range.end = mappedSpan[edit.range.end];
+        }));
+        return result;
+    }
+    async getHover(documentUri, offset) {
+        const code = this.code[documentUri];
+        const convertedOffset = mapUtf16UnitsToUtf8Units([offset], code)[offset];
+        const result = this.languageService.get_hover(documentUri, convertedOffset);
+        if (result) {
+            const mappedSpan = mapUtf8UnitsToUtf16Units([result.span.start, result.span.end], code);
+            result.span.start = mappedSpan[result.span.start];
+            result.span.end = mappedSpan[result.span.end];
+        }
+        return result;
+    }
+    async getDefinition(documentUri, offset) {
+        let code = this.code[documentUri];
+        const convertedOffset = mapUtf16UnitsToUtf8Units([offset], code)[offset];
+        const result = this.languageService.get_definition(documentUri, convertedOffset);
+        if (result) {
+            // Inspect the URL protocol (equivalent to the URI scheme + ":").
+            // If the scheme is our library scheme, we need to call the wasm to
+            // provide the library file's contents to do the utf8->utf16 mapping.
+            const url = new URL(result.source);
+            if (url.protocol === qsharpLibraryUriScheme + ":") {
+                code = wasm.get_library_source_content(url.pathname);
+            }
+            result.offset = mapUtf8UnitsToUtf16Units([result.offset], code)[result.offset];
+        }
+        return result;
+    }
+    async dispose() {
+        this.languageService.free();
+    }
+    addEventListener(type, listener) {
+        this.eventHandler.addEventListener(type, listener);
+    }
+    removeEventListener(type, listener) {
+        this.eventHandler.removeEventListener(type, listener);
+    }
+    onDiagnostics(uri, version, diagnostics) {
+        try {
+            const code = this.code[uri];
+            const event = new Event("diagnostics");
+            event.detail = {
+                uri,
+                version,
+                diagnostics: mapDiagnostics(diagnostics, code),
+            };
+            this.eventHandler.dispatchEvent(event);
+        }
+        catch (e) {
+            log.error("Error in onDiagnostics", e);
+        }
+    }
+}

package/dist/language-service/worker-browser.d.ts

@@ -0,0 +1 @@
+export declare function messageHandler(e: MessageEvent): void;

package/dist/language-service/worker-browser.js

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import * as wasm from "../../lib/web/qsc_wasm.js";
+import { log } from "../log.js";
+import { QSharpLanguageService } from "./language-service.js";
+import { createLanguageServiceDispatcher } from "./worker-proxy.js";
+let invokeCompiler = null;
+// This export should be assigned to 'self.onmessage' in a WebWorker
+export function messageHandler(e) {
+    const data = e.data;
+    if (!data.type || typeof data.type !== "string") {
+        log.error(`Unrecognized msg: ${data}`);
+        return;
+    }
+    switch (data.type) {
+        case "init":
+            {
+                log.setLogLevel(data.qscLogLevel);
+                wasm.initSync(data.wasmModule);
+                const languageService = new QSharpLanguageService(wasm);
+                invokeCompiler = createLanguageServiceDispatcher(self.postMessage.bind(self), languageService);
+            }
+            break;
+        default:
+            if (!invokeCompiler) {
+                log.error(`Received message before the compiler was initialized: %o`, data);
+            }
+            else {
+                invokeCompiler(data);
+            }
+    }
+}

package/dist/language-service/worker-node.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/language-service/worker-node.js

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+// This module supports running the qsharp compiler in a Node.js worker thread. It should be
+// used in a Node.js module in a manner similar to the below to create it with the right log level:
+//
+//     const worker = new Worker(join(thisDir,"worker-node.js"), {
+//         workerData: {qscLogLevel: log.getLogLevel() }
+//     });
+import { isMainThread, parentPort, workerData } from "node:worker_threads";
+import * as wasm from "../../lib/node/qsc_wasm.cjs";
+import { log } from "../log.js";
+import { QSharpLanguageService } from "./language-service.js";
+import { createLanguageServiceDispatcher } from "./worker-proxy.js";
+if (isMainThread)
+    throw "Worker script should be loaded in a Worker thread only";
+if (workerData && typeof workerData.qscLogLevel === "number") {
+    log.setLogLevel(workerData.qscLogLevel);
+}
+const port = parentPort; // eslint-disable-line @typescript-eslint/no-non-null-assertion
+const postMessage = port.postMessage.bind(port);
+const compiler = new QSharpLanguageService(wasm);
+const invokeCompiler = createLanguageServiceDispatcher(postMessage, compiler);
+function messageHandler(data) {
+    if (!data.type || typeof data.type !== "string") {
+        log.error(`Unrecognized msg: %O"`, data);
+        return;
+    }
+    invokeCompiler(data);
+}
+port.addListener("message", messageHandler);

package/dist/language-service/worker-proxy.d.ts

@@ -0,0 +1,6 @@
+import { EventMessage, RequestMessage, ResponseMessage } from "../worker-proxy.js";
+import { ILanguageService, LanguageServiceEvent } from "./language-service.js";
+export declare function createLanguageServiceDispatcher(postMessage: (msg: ResponseMessage<ILanguageService> | EventMessage<LanguageServiceEvent>) => void, service: ILanguageService): (req: RequestMessage<ILanguageService>) => any;
+export declare function createLanguageServiceProxy(postMessage: (msg: RequestMessage<ILanguageService>) => void, terminator: () => void): ILanguageService & import("../worker-proxy.js").IServiceProxy & {
+    onMsgFromWorker: (msg: ResponseMessage<ILanguageService> | EventMessage<LanguageServiceEvent>) => void;
+};

package/dist/language-service/worker-proxy.js

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { createDispatcher, createProxy, } from "../worker-proxy.js";
+const requests = {
+    updateDocument: "request",
+    closeDocument: "request",
+    getCompletions: "request",
+    getHover: "request",
+    getDefinition: "request",
+    dispose: "request",
+    addEventListener: "addEventListener",
+    removeEventListener: "removeEventListener",
+};
+const events = ["diagnostics"];
+export function createLanguageServiceDispatcher(postMessage, service) {
+    return createDispatcher(postMessage, service, requests, events);
+}
+export function createLanguageServiceProxy(postMessage, terminator) {
+    return createProxy(postMessage, terminator, requests);
+}

package/dist/log.d.ts

@@ -0,0 +1,33 @@
+declare global {
+    var qscLog: typeof log;
+    var qscGitHash: string;
+}
+export type LogLevel = "off" | "error" | "warn" | "info" | "debug" | "trace";
+export type TelemetryEvent = {
+    id: string;
+    data?: any;
+};
+export type TelemetryCollector = (event: TelemetryEvent) => void;
+export declare const log: {
+    setLogLevel(level: LogLevel | number): void;
+    onLevelChanged: ((level: number) => void) | null;
+    getLogLevel(): number;
+    error(...args: any): void;
+    warn(...args: any): void;
+    info(...args: any): void;
+    debug(...args: any): void;
+    trace(...args: any): void;
+    never(val: never): void;
+    /**
+     * @param level - A number indicating severity: 1 = Error, 2 = Warn, 3 = Info, 4 = Debug, 5 = Trace
+     * @param target - The area or component sending the messsage, e.g. "parser" (useful for filtering)
+     * @param args - The format string and args to log, e.g. ["Index of %s is %i", str, index]
+     */
+    logWithLevel(level: number, target: string, ...args: any): void;
+    setTelemetryCollector(handler: TelemetryCollector): void;
+    logTelemetry(event: {
+        id: string;
+        data?: any;
+    }): void;
+    isTelemetryEnabled(): boolean;
+};

package/dist/log.js

@@ -0,0 +1,92 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+let telemetryCollector = null;
+const levels = ["off", "error", "warn", "info", "debug", "trace"];
+let logLevel = 0;
+export const log = {
+    setLogLevel(level) {
+        if (typeof level === "string") {
+            // Convert to number
+            const lowerLevel = level.toLowerCase();
+            let newLevel = 0;
+            levels.forEach((name, idx) => {
+                if (name === lowerLevel)
+                    newLevel = idx;
+            });
+            logLevel = newLevel;
+        }
+        else {
+            logLevel = level;
+        }
+        this.onLevelChanged?.(logLevel);
+    },
+    onLevelChanged: null,
+    getLogLevel() {
+        return logLevel;
+    },
+    error(...args) {
+        if (logLevel >= 1)
+            console.error(...args);
+    },
+    warn(...args) {
+        if (logLevel >= 2)
+            console.warn(...args);
+    },
+    info(...args) {
+        if (logLevel >= 3)
+            console.info(...args);
+    },
+    debug(...args) {
+        if (logLevel >= 4)
+            console.debug(...args);
+    },
+    trace(...args) {
+        // console.trace in JavaScript just writes a stack trace at info level, so use 'debug'
+        if (logLevel >= 5)
+            console.debug(...args);
+    },
+    never(val) {
+        // Utility function to ensure exhaustive type checking. See https://stackoverflow.com/a/39419171
+        log.error("Exhaustive type checking didn't account for: %o", val);
+    },
+    /**
+     * @param level - A number indicating severity: 1 = Error, 2 = Warn, 3 = Info, 4 = Debug, 5 = Trace
+     * @param target - The area or component sending the messsage, e.g. "parser" (useful for filtering)
+     * @param args - The format string and args to log, e.g. ["Index of %s is %i", str, index]
+     */
+    logWithLevel(level, target, ...args) {
+        // Convert to a format string containing the target (if present)
+        const [, ...trailingArgs] = args; // All but first element of args
+        const outArgs = [`[%s] ${args[0]}`, target || "", ...trailingArgs];
+        switch (level) {
+            case 1:
+                log.error(...outArgs);
+                break;
+            case 2:
+                log.warn(...outArgs);
+                break;
+            case 3:
+                log.info(...outArgs);
+                break;
+            case 4:
+                log.debug(...outArgs);
+                break;
+            case 5:
+                log.trace(...outArgs);
+                break;
+            default:
+                log.error("Invalid logLevel: ", level);
+        }
+    },
+    setTelemetryCollector(handler) {
+        telemetryCollector = handler;
+    },
+    logTelemetry(event) {
+        telemetryCollector?.(event);
+    },
+    isTelemetryEnabled() {
+        return !!telemetryCollector;
+    },
+};
+// Enable globally for easy interaction and debugging in live environments
+globalThis.qscLog = log;

package/dist/main.d.ts

@@ -0,0 +1,11 @@
+import { ICompiler, ICompilerWorker } from "./compiler/compiler.js";
+import { ILanguageService, ILanguageServiceWorker, qsharpLibraryUriScheme } from "./language-service/language-service.js";
+import { IDebugService, IDebugServiceWorker } from "./debug-service/debug-service.js";
+export { qsharpLibraryUriScheme };
+export declare function getLibrarySourceContent(path: string): Promise<string | undefined>;
+export declare function getCompiler(): ICompiler;
+export declare function getCompilerWorker(): ICompilerWorker;
+export declare function getDebugService(): IDebugService;
+export declare function getDebugServiceWorker(): IDebugServiceWorker;
+export declare function getLanguageService(): ILanguageService;
+export declare function getLanguageServiceWorker(): ILanguageServiceWorker;

package/dist/main.js

@@ -0,0 +1,82 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+// This module is the main entry point for use in Node.js environments. For browser environments,
+// the "./browser.js" file is the entry point module.
+import { createRequire } from "node:module";
+import { Worker } from "node:worker_threads";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { log } from "./log.js";
+import { Compiler } from "./compiler/compiler.js";
+import { createCompilerProxy } from "./compiler/worker-proxy.js";
+import { QSharpLanguageService, qsharpLibraryUriScheme, } from "./language-service/language-service.js";
+import { createLanguageServiceProxy } from "./language-service/worker-proxy.js";
+import { QSharpDebugService, } from "./debug-service/debug-service.js";
+import { createDebugServiceProxy } from "./debug-service/worker-proxy.js";
+export { qsharpLibraryUriScheme };
+let wasm = null;
+const require = createRequire(import.meta.url);
+export async function getLibrarySourceContent(path) {
+    if (!wasm) {
+        wasm = require("../lib/node/qsc_wasm.cjs");
+        return wasm.get_library_source_content(path);
+    }
+}
+export function getCompiler() {
+    if (!wasm) {
+        wasm = require("../lib/node/qsc_wasm.cjs");
+        // Set up logging and telemetry as soon as possible after instantiating
+        wasm.initLogging(log.logWithLevel, log.getLogLevel());
+        log.onLevelChanged = (level) => wasm?.setLogLevel(level);
+    }
+    return new Compiler(wasm);
+}
+export function getCompilerWorker() {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const worker = new Worker(join(thisDir, "./compiler/worker-node.js"), {
+        workerData: { qscLogLevel: log.getLogLevel() },
+    });
+    // Create the proxy which will forward method calls to the worker
+    const proxy = createCompilerProxy(
+    // If you lose the 'this' binding, some environments have issues.
+    worker.postMessage.bind(worker), () => worker.terminate());
+    // Let proxy handle response and event messages from the worker
+    worker.addListener("message", proxy.onMsgFromWorker);
+    return proxy;
+}
+export function getDebugService() {
+    if (!wasm)
+        wasm = require("../lib/node/qsc_wasm.cjs");
+    return new QSharpDebugService(wasm);
+}
+export function getDebugServiceWorker() {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const worker = new Worker(join(thisDir, "./debug-service/worker-node.js"), {
+        workerData: { qscLogLevel: log.getLogLevel() },
+    });
+    // Create the proxy which will forward method calls to the worker
+    const proxy = createDebugServiceProxy(
+    // If you lose the 'this' binding, some environments have issues.
+    worker.postMessage.bind(worker), () => worker.terminate());
+    // Let proxy handle response and event messages from the worker
+    worker.addListener("message", proxy.onMsgFromWorker);
+    return proxy;
+}
+export function getLanguageService() {
+    if (!wasm)
+        wasm = require("../lib/node/qsc_wasm.cjs");
+    return new QSharpLanguageService(wasm);
+}
+export function getLanguageServiceWorker() {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const worker = new Worker(join(thisDir, "./language-service/worker-node.js"), {
+        workerData: { qscLogLevel: log.getLogLevel() },
+    });
+    // Create the proxy which will forward method calls to the worker
+    const proxy = createLanguageServiceProxy(
+    // If you lose the 'this' binding, some environments have issues.
+    worker.postMessage.bind(worker), () => worker.terminate());
+    // Let proxy handle response and event messages from the worker
+    worker.addListener("message", proxy.onMsgFromWorker);
+    return proxy;
+}

package/dist/samples.generated.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    title: string;
+    shots: number;
+    code: string;
+}[];
+export default _default;