@intersystems-community/ascot 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @intersystems-community/ascot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[ascot](https://github.com/intersystems-community/ascot) is a type checker and code
+intelligence engine for InterSystems ObjectScript. This package is its WebAssembly build
+for Node and other JavaScript hosts, with a small TypeScript wrapper. It is the engine
+behind the InterSystems Language Server's ascot features; it does not include the `ascot`
+command-line tool.
+
+```sh
+npm install @intersystems-community/ascot
+```
+
+## Usage
+
+```ts
+import { createWorkspace, type Imported } from "@intersystems-community/ascot";
+
+// What the engine asks you for when a name isn't defined in the workspace, typically
+// answered from an IRIS instance over its REST API. Return `undefined` for "not found",
+// or for everything if you have no instance: the workspace is then checked on its own.
+class NoIris implements Imported {
+  async getCls(cls: string) { return undefined; }      // a class's members and metadata
+  async getInc(name: string) { return undefined; }     // the text of `name.inc`
+  async getIntOrMac(name: string) { return undefined; } // the text of routine `name`
+}
+
+const ws = await createWorkspace(new NoIris());
+
+// `open` is both open and edit: it stores the raw text (the kind comes from the uri's
+// extension: .cls, .mac, .int, .inc) and returns the uris whose cached analysis is now
+// stale, this one and anything that includes or references it.
+await ws.open("file:///T.cls", `Class T Extends %RegisteredObject
+{
+ClassMethod M() As %Status
+{
+ Set x = 1
+ Write x
+ Quit
+}
+}
+`);
+
+await ws.diagnostics("file:///T.cls");
+// [{ severity: "error", message: "Expected return value of type '%Status' but got nothing",
+//    range: { start: { line: 6, character: 5 }, ... }, relatedInformation: [...] }]
+
+await ws.hover("file:///T.cls", { line: 5, character: 7 }); // the `x` being written
+// "```objectscript\n%DataType = 1\n```"
+```
+
+Load every file of a project into one `Workspace` so cross-file references resolve, and
+call `open` again on each edit. `close(uri)` removes a document; a closed editor tab is
+usually not a removal, so keep the on-disk text open instead.
+
+## API
+
+`createWorkspace(imported)` returns a `Workspace` whose methods mirror the engine's
+exports, all returning promises. Positions and ranges are zero-based line/character pairs,
+as in the Language Server Protocol.
+
+| Method | Returns |
+| --- | --- |
+| `open(uri, text)` | uris whose analysis is now stale |
+| `close(uri)` | uris whose analysis is now stale |
+| `diagnostics(uri)` | `Diagnostic[]` |
+| `inlayHint(uri, range)` | `InlayHint[]` |
+| `definition(uri, position)` | `Location \| undefined` |
+| `references(uri, position, includeDeclaration)` | `Location[]` |
+| `hover(uri, position)` | markdown `string \| undefined` |
+| `documentSymbol(uri)` | the class or routine and its members or labels |
+| `workspaceSymbol(query)` | classes and members across the workspace by prefix |
+| `queryCls(query)` | `[uri, ClassInfo][]` for classes by prefix |
+| `queryMem(cls, query)` | `[uri, MemberInfo][]` for a class's members by prefix |
+
+All result types (`Diagnostic`, `Location`, `ClassInfo`, `MemberInfo`, ...) are exported
+from the package.
+
+Calls are serialized: one runs at a time, and the rest queue behind it. Every `Workspace`
+created by this package shares one wasm instance and one `Imported` class, so construct
+them all from the same implementation.
+
+## Bundling
+
+The core wasm modules are read from this package's `lib/` directory at runtime, relative
+to the wrapper's own location. If you bundle the JavaScript, copy `lib/*.core*.wasm` to a
+`lib/` directory next to your bundle's output directory.
+
+## License
+
+MIT or Apache-2.0, at your option.

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import type { Root } from "../generated/ascot.js" with { "resolution-mode": "import" };
+import type { ClassInfo, RoutineSource } from "../generated/interfaces/iris-ascot-common.js" with { "resolution-mode": "import"
+};
+export type * from "../generated/interfaces/iris-ascot-common.js";
+type RawWorkspace = InstanceType<Root["exported"]["Workspace"]>;
+/** Every method of the wasm `Workspace`, as `createWorkspace` hands it out: all async, since
+ * `serialize` below queues each call behind the previous one. */
+export type Workspace = {
+    [K in keyof RawWorkspace]: RawWorkspace[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<Awaited<R>> : RawWorkspace[K];
+};
+/** The shape your `imported.iris-connection` implementation must satisfy. */
+export interface Imported {
+    getCls(cls: string): Promise<ClassInfo | undefined>;
+    getInc(name: string): Promise<RoutineSource | undefined>;
+    getIntOrMac(name: string): Promise<RoutineSource | undefined>;
+}
+/**
+ * A `Workspace` backed by `imported`, with every method pre-serialized so overlapping
+ * calls (e.g. from two documents' diagnostics resolving concurrently) can't trip ascot's
+ * internal `RefCell` borrows or jco's single-in-flight-call constraint.
+ */
+export declare function createWorkspace(imported: Imported): Promise<Workspace>;

package/dist/index.js

@@ -0,0 +1,87 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWorkspace = createWorkspace;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+// jco needs the actual `IrisConnection` class (not just an instance) up front, to bind
+// resource-identity checks (`instanceof`) at instantiation time -- so the wasm module is
+// loaded lazily on the first `createWorkspace` call, using that call's own argument's
+// class. Every later call must be constructed from that same class; in practice callers
+// only ever have one `Imported` implementation, so this holds.
+let wasm;
+async function loadWasm(IrisConnection) {
+    return (wasm ??= import("../generated/ascot.js").then(({ instantiate }) => instantiate((name) => new WebAssembly.Module(fs.readFileSync(path.resolve(__dirname, "../lib", name))), {
+        "iris:ascot/common": {},
+        "iris:ascot/imported": { IrisConnection },
+    })));
+}
+// jco's jspi glue allows only one in-flight suspended call per component instance --
+// overlapping calls (e.g. diagnostics() and hover() both awaiting a REST round trip)
+// trip its exclusive-lock check. Every `Workspace` this package creates shares the same
+// wasm instance, so this queue is module-wide, not per-Workspace.
+let tail = Promise.resolve();
+function serialize(instance) {
+    return new Proxy(instance, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function")
+                return value;
+            return async (...args) => {
+                const prev = tail;
+                let release;
+                tail = new Promise((resolve) => (release = resolve));
+                await prev;
+                try {
+                    return await value.apply(target, args);
+                }
+                finally {
+                    release();
+                }
+            };
+        },
+    });
+}
+/**
+ * A `Workspace` backed by `imported`, with every method pre-serialized so overlapping
+ * calls (e.g. from two documents' diagnostics resolving concurrently) can't trip ascot's
+ * internal `RefCell` borrows or jco's single-in-flight-call constraint.
+ */
+async function createWorkspace(imported) {
+    const IrisConnection = Object.getPrototypeOf(imported).constructor;
+    const root = await loadWasm(IrisConnection);
+    return serialize(new root.exported.Workspace(imported));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,MAAY,EAAE,oCAAgB;AAC9B,MAAY,IAAI,sCAAkB;AA+BlC,uFAAuF;AACvF,yFAAyF;AACzF,sFAAsF;AACtF,wFAAwF;AACxF,+DAA+D;AAC/D,IAAI,IAA+B,CAAC;AAEpC,KAAK,UAAU,QAAQ,CAAC,cAA2D;IAClF,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,uBAAuB,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CACzE,WAAW,CACV,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,EAClG;QACC,mBAAmB,EAAE,EAAE;QACvB,qBAAqB,EAAE,EAAE,cAAc,EAAE;KAChC,CACV,CACD,CAAC,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,qFAAqF;AACrF,wFAAwF;AACxF,kEAAkE;AAClE,IAAI,IAAI,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;AAE5C,SAAS,SAAS,CAAC,QAAsB;IACxC,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE;QAC1B,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;YACzB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YAClD,IAAI,OAAO,KAAK,KAAK,UAAU;gBAAE,OAAO,KAAK,CAAC;YAC9C,OAAO,KAAK,EAAE,GAAG,IAAe,EAAE,EAAE;gBACnC,MAAM,IAAI,GAAG,IAAI,CAAC;gBAClB,IAAI,OAAoB,CAAC;gBACzB,IAAI,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;gBAC3D,MAAM,IAAI,CAAC;gBACX,IAAI,CAAC;oBACJ,OAAO,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACxC,CAAC;wBAAS,CAAC;oBACV,OAAO,EAAE,CAAC;gBACX,CAAC;YACF,CAAC,CAAC;QACH,CAAC;KACD,CAAyB,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACI,KAAK,0BAA0B,QAAkB;IACvD,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,WAAW,CAAC;IACnE,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC5C,OAAO,SAAS,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;AACzD,CAAC"}

package/generated/ascot.d.ts

@@ -0,0 +1,43 @@
+// world root:component/root
+import type * as IrisAscotCommon from './interfaces/iris-ascot-common.js'; // iris:ascot/common
+import type * as IrisAscotImported from './interfaces/iris-ascot-imported.js'; // iris:ascot/imported
+import type * as IrisAscotExported from './interfaces/iris-ascot-exported.js'; // iris:ascot/exported
+export interface ImportObject {
+  'iris:ascot/common': typeof IrisAscotCommon,
+  'iris:ascot/imported': typeof IrisAscotImported,
+}
+export interface Root {
+  'iris:ascot/exported': typeof IrisAscotExported,
+  exported: typeof IrisAscotExported,
+}
+
+/**
+* Instantiates this component with the provided imports and
+* returns a map of all the exports of the component.
+*
+* This function is intended to be similar to the
+* `WebAssembly.Instantiate` constructor. The second `imports`
+* argument is the "import object" for wasm, except here it
+* uses component-model-layer types instead of core wasm
+* integers/numbers/etc.
+*
+* The first argument to this function, `getCoreModule`, is
+* used to compile core wasm modules within the component.
+* Components are composed of core wasm modules and this callback
+* will be invoked per core wasm module. The caller of this
+* function is responsible for reading the core wasm module
+* identified by `path` and returning its compiled
+* `WebAssembly.Module` object. This would use the
+* `WebAssembly.Module` constructor on the web, for example.
+*/
+export function instantiate(
+getCoreModule: (path: string) => WebAssembly.Module,
+imports: ImportObject,
+instantiateCore?: (module: WebAssembly.Module, imports: Record<string, any>) => WebAssembly.Instance
+): Root;
+export function instantiate(
+getCoreModule: (path: string) => WebAssembly.Module | Promise<WebAssembly.Module>,
+imports: ImportObject,
+instantiateCore?: (module: WebAssembly.Module, imports: Record<string, any>) => WebAssembly.Instance | Promise<WebAssembly.Instance>
+): Root | Promise<Root>;
+