@listen-fire/movement-lang 0.12.0-rc.7 → 0.12.0

package/dist/catalog/types.d.ts

@@ -10,11 +10,13 @@ export interface ConstructionArg {
     name: string;
     /**
      * `credential` = names an imported credential whose `adapter` is this adapter
-     * (always required). `position` = an entry-position arg (e.g. Sheets'
+     * (required unless the adapter works without one: lf's email). `position` = an entry-position arg (e.g. Sheets'
      * `spreadsheet`) that pins where the instance starts.
      */
     kind: 'credential' | 'position';
-    /** Whether construction MUST supply it. Credential args are required; position args are optional today. */
+    /** Whether construction MUST supply it. A credential arg is required unless every credential the
+     *  adapter declares is optional (an absent one then instantiates the credential-free schema);
+     *  position args are optional today. */
     required: boolean;
     /**
      * Position args only: the collection/type whose members are the value enum

package/dist/checker/rust_checker.d.ts

@@ -12,6 +12,8 @@ export interface RustCheckOptions {
  *  snapshot does not load. */
 export declare class RustCheckRefused extends Error {
     constructor(message: string);
+    /** The refusal an artifact's `{error: {message}}` reply carries. */
+    static of(json: unknown): RustCheckRefused;
 }
 /** The language the artifact reads: its release's version. */
 export declare function languageVersion(): LanguageVersion;
@@ -87,3 +89,7 @@ export declare function compatibleInRust(request: {
 } | {
     undescribed: true;
 };
+/** One diagnostic of an artifact's reply, validated.
+ *
+ * @internal Used by the story analysis's wrapper (checker/story_analysis.ts). */
+export declare function diagnosticOf(value: unknown): Diagnostic;

package/dist/checker/rust_checker.js

@@ -15,6 +15,7 @@ exports.languageStanding = languageStanding;
 exports.checkSourceInRust = checkSourceInRust;
 exports.checkAnswerInRust = checkAnswerInRust;
 exports.compatibleInRust = compatibleInRust;
+exports.diagnosticOf = diagnosticOf;
 const loader_1 = require("../wasm/loader");
 const language_version_1 = require("../language_version");
 /** A source the Rust checker could not check: it does not parse, or the
@@ -24,6 +25,11 @@ class RustCheckRefused extends Error {
         super(message);
         this.name = 'RustCheckRefused';
     }
+    /** The refusal an artifact's `{error: {message}}` reply carries. */
+    static of(json) {
+        const error = isRecord(json) && isRecord(json.error) ? json.error : undefined;
+        return new RustCheckRefused(typeof error?.message === 'string' ? error.message : 'the Rust checker refused the check');
+    }
 }
 exports.RustCheckRefused = RustCheckRefused;
 /** The language the artifact reads: its release's version. */
@@ -57,7 +63,7 @@ function checkSourceInRust(source, snapshot, options) {
     const reply = (0, loader_1.callCheckProgram)(source, JSON.stringify(snapshot), callOptions(options));
     const json = reply.json;
     if (!reply.ok)
-        throw refused(json);
+        throw RustCheckRefused.of(json);
     const diagnostics = isRecord(json) ? json.diagnostics : undefined;
     if (!Array.isArray(diagnostics))
         throw new Error('the Rust checker answered no diagnostics');
@@ -71,7 +77,7 @@ function checkAnswerInRust(source, snapshot, options) {
     const reply = (0, loader_1.callCheckAnswer)(source, JSON.stringify(snapshot), callOptions(options));
     const json = reply.json;
     if (!reply.ok)
-        throw refused(json);
+        throw RustCheckRefused.of(json);
     if (!isRecord(json) || !Array.isArray(json.diagnostics) || !Array.isArray(json.stamps)) {
         throw new Error(`the Rust checker answered no check: ${JSON.stringify(json)?.slice(0, 200)}`);
     }
@@ -89,7 +95,7 @@ function compatibleInRust(request) {
     const reply = (0, loader_1.callCheckCompatible)(JSON.stringify(request));
     const json = reply.json;
     if (!reply.ok)
-        throw refused(json);
+        throw RustCheckRefused.of(json);
     if (isRecord(json) && json.undescribed === true)
         return { undescribed: true };
     if (isRecord(json) && typeof json.fits === 'boolean')
@@ -99,10 +105,6 @@ function compatibleInRust(request) {
 function callOptions(options) {
     return options.upgradingFrom === undefined ? {} : { upgradingFrom: options.upgradingFrom };
 }
-function refused(json) {
-    const error = isRecord(json) && isRecord(json.error) ? json.error : undefined;
-    return new RustCheckRefused(typeof error?.message === 'string' ? error.message : 'the Rust checker refused the check');
-}
 function stampOf(value) {
     if (!isRecord(value) || typeof value.path !== 'string' || (value.file !== undefined && typeof value.file !== 'string')) {
         throw new Error(`the Rust checker answered a stamp that is not one: ${JSON.stringify(value)}`);
@@ -156,6 +158,9 @@ function linkedKindOf(value) {
         return value;
     throw new Error(`the Rust checker answered the import kind ${JSON.stringify(value)}`);
 }
+/** One diagnostic of an artifact's reply, validated.
+ *
+ * @internal Used by the story analysis's wrapper (checker/story_analysis.ts). */
 function diagnosticOf(value) {
     if (!isRecord(value) || typeof value.code !== 'string' || typeof value.message !== 'string') {
         throw new Error(`the Rust checker answered a diagnostic that is not one: ${JSON.stringify(value)}`);

package/dist/checker/story_analysis.d.ts

@@ -0,0 +1,236 @@
+import type { CollectionOpExpression, CombinatorKind, ExprSlot, FieldEntry, MembersExpression, ShapeNode, Span } from '../parser/ast';
+import type { TraversalStep } from '../expression/types';
+import type { CatalogSnapshot } from '../service/snapshot';
+import type { Diagnostic } from './diagnostic';
+import { type RustCheckOptions } from './rust_checker';
+/** The analysis's shape version this binding writes and reads. */
+export declare const STORY_ANALYSIS_VERSION = 1;
+/** Every analysis version this binding reads; any other is refused by name. */
+export declare const SUPPORTED_STORY_ANALYSIS_VERSIONS: readonly number[];
+export interface StoryAnalysis {
+    storyAnalysisVersion: number;
+    diagnostics: Diagnostic[];
+    /** The file's scope is 0. */
+    scopes: StoryScope[];
+    symbols: StorySymbol[];
+    writes: StoryWrite[];
+    nodes: StoryNode[];
+    bodies: StoryBody[];
+    shapes: StoryShape[];
+}
+/** One scope: the last binding of each name in it, as the walk left it. A
+ *  scope with no text of its own has no `span`. */
+export interface StoryScope {
+    parent?: number;
+    span?: Span;
+    symbols: Record<string, number>;
+}
+export type StorySymbolKind = 'adapter' | 'credential' | 'plugin' | 'fileImport' | 'binding' | 'instance' | 'param' | 'movement' | 'shape' | 'alias' | 'type';
+/** Where a record is: a system's binding name, and its record type where one place holds it. */
+export interface StoryAddress {
+    instance: string;
+    position?: string;
+}
+/** What a movement may do. `reads` and `writes` name instance bindings;
+ *  `partial` is set where a callee or a site could not be placed. */
+export interface StoryEffects {
+    reads: string[];
+    writes: string[];
+    ai: boolean;
+    now: boolean;
+    suspend: boolean;
+    partial: boolean;
+}
+export interface StorySymbol {
+    name: string;
+    kind: StorySymbolKind;
+    span: Span;
+    adapter?: string;
+    address?: StoryAddress;
+    /** The binding holds an extraction's graph; `entity` the node's name, absent at its root. */
+    extracted?: {
+        entity?: string;
+    };
+    /** Movements only. */
+    effects?: StoryEffects;
+}
+export interface StoryWrite {
+    span: Span;
+    scope: number;
+    /** The field lines, spreads written out (a spread's line carries `spread`). */
+    fields: FieldEntry[];
+    hasUniqueBy: boolean;
+    /** `update` is a write to a position; `find` a match. */
+    action: 'create' | 'update' | 'find';
+    parents: Array<{
+        edge: string;
+        type?: string;
+    }>;
+    binding?: string;
+    target?: {
+        instance: string;
+        recordType?: string;
+    };
+}
+/** Every node has its `span` and the `scope` it sits in. */
+export type StoryNode = {
+    span: Span;
+    scope: number;
+} & ({
+    kind: 'instance';
+    name: string;
+    adapterType?: string;
+} | {
+    kind: 'listen';
+    instance: string;
+    adapterType?: string;
+    fires: string;
+    firesMovement: boolean;
+    events?: string[];
+    narrowing: Record<string, string>;
+    eventTypes: Array<{
+        key: string;
+        display?: string;
+    }>;
+} | {
+    kind: 'link';
+    from: string;
+    edge: string;
+    to: {
+        kind: 'handle';
+        name: string;
+    } | {
+        kind: 'match';
+        span: Span;
+    };
+} | {
+    kind: 'unlink';
+    from: string;
+    edge: string;
+    to: {
+        kind: 'handle';
+        name: string;
+    };
+} | {
+    kind: 'await';
+    binding?: string;
+    source: StoryAwaitedSource;
+} | {
+    kind: 'combinator';
+    combinator: CombinatorKind;
+    binding?: string;
+    arms: Array<{
+        span: Span;
+        scope?: number;
+    }>;
+} | {
+    kind: 'branch';
+    arms: Array<{
+        span: Span;
+        scope: number;
+        conditionSpan: Span;
+    }>;
+    otherwise?: {
+        span: Span;
+        scope: number;
+    };
+} | {
+    kind: 'extract';
+    binding?: string;
+    node?: StoryExtractNode;
+}
+/** `argParams[i]` is null for an argument past the callee's last parameter. */
+ | {
+    kind: 'call';
+    binding?: string;
+    callee: string;
+    isMovement: boolean;
+    argParams?: Array<string | null>;
+} | {
+    kind: 'callReading';
+    reading: StoryCallReading;
+} | (StoryWalk & {
+    kind: 'traversal';
+    from?: 'graph' | 'result';
+})
+/** `key` is the walk's comparable token (its root and steps as JSON, keys sorted). */
+ | (StoryWalk & {
+    kind: 'valuePath';
+    key: string;
+}) | {
+    kind: 'delete';
+    subject: string;
+} | {
+    kind: 'refresh';
+    subject: string;
+});
+export type StoryNodeKind = StoryNode['kind'];
+/** A walk's root, its hops, and where each hop landed (null where it did not type). */
+export interface StoryWalk {
+    root?: string;
+    steps: TraversalStep[];
+    landings: Array<StoryAddress | null>;
+}
+export type StoryAwaitedSource = {
+    kind: 'traversal';
+    root?: string;
+    edge?: string;
+    awaitable?: boolean;
+    resolvesEmpty?: boolean;
+} | {
+    kind: 'sleep';
+    duration: string;
+} | {
+    kind: 'until';
+    every?: string;
+};
+export type StoryCallReading = {
+    kind: 'value';
+    expr: ExprSlot;
+} | {
+    kind: 'collection';
+    collection: CollectionOpExpression;
+} | {
+    kind: 'members';
+    members: MembersExpression;
+} | {
+    kind: 'refused';
+    refusal: {
+        code: string;
+        message: string;
+        span: Span;
+    };
+};
+/** An extraction's graph: each field's `type` in the author's words. */
+export interface StoryExtractNode {
+    name: string;
+    fields: Array<{
+        name: string;
+        at: Span;
+        type?: string;
+    }>;
+    children: StoryExtractNode[];
+}
+/** A statement list the story caps a lane by, and whether it leaves. */
+export interface StoryBody {
+    span: Span;
+    kind: 'movement' | 'arm' | 'else' | 'combinatorArm' | 'callback';
+    terminates: boolean;
+}
+/** A file-level node declaration, `extends` folded into `root`. */
+export interface StoryShape {
+    name: string;
+    span: Span;
+    root: ShapeNode;
+}
+/**
+ * The story analysis of `source` against `snapshot`. A pin this release
+ * does not read is its version diagnostic alone, every list empty, the
+ * artifact not asked (`refused_story_analysis` in Rust). Throws
+ * `RustCheckRefused` for a source that does not parse or a snapshot that
+ * does not load, and for an analysis version this binding does not read.
+ */
+export declare function storyAnalysisInRust(source: string, snapshot: CatalogSnapshot, options: RustCheckOptions): StoryAnalysis;
+/** `name` from scope `scope`, through the table: the last binding of the
+ *  name in the nearest enclosing scope that binds it. */
+export declare function resolveInAnalysis(analysis: StoryAnalysis, scope: number, name: string): StorySymbol | undefined;

package/dist/checker/story_analysis.js

@@ -0,0 +1,168 @@
+"use strict";
+// The story analysis (crates/movement-checker/src/story.rs), through the
+// movement artifact's `story_analysis` export: what the one check walk
+// resolved, as data a story projection reads. A scope is an id into
+// `scopes`, a symbol an id into `symbols`; spans are the AST's (1-based).
+// The diagnostics are the check's own, so one call gives both the verdict
+// and the picture.
+//
+// The envelope and every record's identity (its kind, span and scope) are
+// validated here. What a record carries from the AST (a write's fields, a
+// walk's steps, a node declaration's tree) is trusted as the Rust's own
+// output, as the parser's tree is (parser/rust_parser.ts).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_STORY_ANALYSIS_VERSIONS = exports.STORY_ANALYSIS_VERSION = void 0;
+exports.storyAnalysisInRust = storyAnalysisInRust;
+exports.resolveInAnalysis = resolveInAnalysis;
+const loader_1 = require("../wasm/loader");
+const language_version_1 = require("../language_version");
+const rust_checker_1 = require("./rust_checker");
+/** The analysis's shape version this binding writes and reads. */
+exports.STORY_ANALYSIS_VERSION = 1;
+/** Every analysis version this binding reads; any other is refused by name. */
+exports.SUPPORTED_STORY_ANALYSIS_VERSIONS = [exports.STORY_ANALYSIS_VERSION];
+/**
+ * The story analysis of `source` against `snapshot`. A pin this release
+ * does not read is its version diagnostic alone, every list empty, the
+ * artifact not asked (`refused_story_analysis` in Rust). Throws
+ * `RustCheckRefused` for a source that does not parse or a snapshot that
+ * does not load, and for an analysis version this binding does not read.
+ */
+function storyAnalysisInRust(source, snapshot, options) {
+    const refusal = (0, language_version_1.languageVersionDiagnostic)(options.languageVersion);
+    if (refusal !== undefined) {
+        return {
+            storyAnalysisVersion: exports.STORY_ANALYSIS_VERSION,
+            diagnostics: [refusal],
+            scopes: [],
+            symbols: [],
+            writes: [],
+            nodes: [],
+            bodies: [],
+            shapes: [],
+        };
+    }
+    const reply = (0, loader_1.callStoryAnalysis)(source, JSON.stringify(snapshot), options.upgradingFrom === undefined ? {} : { upgradingFrom: options.upgradingFrom });
+    const json = reply.json;
+    if (!reply.ok)
+        throw rust_checker_1.RustCheckRefused.of(json);
+    return analysisOf(json);
+}
+/** `name` from scope `scope`, through the table: the last binding of the
+ *  name in the nearest enclosing scope that binds it. */
+function resolveInAnalysis(analysis, scope, name) {
+    for (let at = scope; at !== undefined; at = analysis.scopes[at]?.parent) {
+        const bound = analysis.scopes[at]?.symbols[name];
+        if (bound !== undefined)
+            return analysis.symbols[bound];
+    }
+    return undefined;
+}
+function analysisOf(json) {
+    if (!isRecord(json))
+        throw malformed('analysis', json);
+    const version = json.storyAnalysisVersion;
+    if (typeof version !== 'number' || !exports.SUPPORTED_STORY_ANALYSIS_VERSIONS.includes(version)) {
+        throw new rust_checker_1.RustCheckRefused(`the story analysis is version ${JSON.stringify(version)}, which this binding does not read (it reads ${exports.SUPPORTED_STORY_ANALYSIS_VERSIONS.join(', ')})`);
+    }
+    const { diagnostics, scopes, symbols, writes, nodes, bodies, shapes } = json;
+    if (!Array.isArray(diagnostics) ||
+        !Array.isArray(scopes) ||
+        !Array.isArray(symbols) ||
+        !Array.isArray(writes) ||
+        !Array.isArray(nodes) ||
+        !Array.isArray(bodies) ||
+        !Array.isArray(shapes)) {
+        throw malformed('analysis', json);
+    }
+    return {
+        storyAnalysisVersion: version,
+        diagnostics: diagnostics.map(rust_checker_1.diagnosticOf),
+        scopes: scopes.map(each(isScope, 'scope')),
+        symbols: symbols.map(each(isSymbol, 'symbol')),
+        writes: writes.map(each(isWrite, 'write')),
+        nodes: nodes.map(each(isNode, 'node')),
+        bodies: bodies.map(each(isBody, 'body')),
+        shapes: shapes.map(each(isShape, 'shape')),
+    };
+}
+function each(is, what) {
+    return value => {
+        if (!is(value))
+            throw malformed(what, value);
+        return value;
+    };
+}
+const SYMBOL_KINDS = new Set([
+    'adapter',
+    'credential',
+    'plugin',
+    'fileImport',
+    'binding',
+    'instance',
+    'param',
+    'movement',
+    'shape',
+    'alias',
+    'type',
+]);
+const NODE_KINDS = new Set([
+    'instance',
+    'listen',
+    'link',
+    'unlink',
+    'await',
+    'combinator',
+    'branch',
+    'extract',
+    'call',
+    'callReading',
+    'traversal',
+    'valuePath',
+    'delete',
+    'refresh',
+]);
+const BODY_KINDS = new Set(['movement', 'arm', 'else', 'combinatorArm', 'callback']);
+function isScope(value) {
+    return (isRecord(value) &&
+        (value.parent === undefined || isId(value.parent)) &&
+        (value.span === undefined || isSpan(value.span)) &&
+        isRecord(value.symbols) &&
+        Object.values(value.symbols).every(isId));
+}
+function isSymbol(value) {
+    return isRecord(value) && typeof value.name === 'string' && typeof value.kind === 'string' && SYMBOL_KINDS.has(value.kind) && isSpan(value.span);
+}
+function isWrite(value) {
+    return (isRecord(value) &&
+        isSpan(value.span) &&
+        isId(value.scope) &&
+        Array.isArray(value.fields) &&
+        typeof value.hasUniqueBy === 'boolean' &&
+        (value.action === 'create' || value.action === 'update' || value.action === 'find') &&
+        Array.isArray(value.parents));
+}
+function isNode(value) {
+    return isRecord(value) && typeof value.kind === 'string' && NODE_KINDS.has(value.kind) && isSpan(value.span) && isId(value.scope);
+}
+function isBody(value) {
+    return isRecord(value) && isSpan(value.span) && typeof value.kind === 'string' && BODY_KINDS.has(value.kind) && typeof value.terminates === 'boolean';
+}
+function isShape(value) {
+    return isRecord(value) && typeof value.name === 'string' && isSpan(value.span) && isRecord(value.root);
+}
+function isId(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+function isSpan(value) {
+    return isRecord(value) && isLoc(value.start) && isLoc(value.end);
+}
+function isLoc(value) {
+    return isRecord(value) && typeof value.line === 'number' && typeof value.col === 'number';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function malformed(what, value) {
+    return new Error(`the story analysis answered a ${what} that is not one: ${JSON.stringify(value)?.slice(0, 200)}`);
+}

package/dist/index.d.ts

@@ -13,7 +13,9 @@ export * from './checker/fixes';
 export * from './checker/diagnostic';
 export * from './checker/linked_types';
 export * from './checker/rust_checker';
+export * from './checker/story_analysis';
 export * from './checker/standard_library';
 export type { MExpr } from './parser/expression/tree';
 export * from './service/snapshot';
+export * from './service/language_service';
 export * from './language_version';

package/dist/index.js

@@ -36,6 +36,8 @@ __exportStar(require("./checker/fixes"), exports);
 __exportStar(require("./checker/diagnostic"), exports);
 __exportStar(require("./checker/linked_types"), exports);
 __exportStar(require("./checker/rust_checker"), exports);
+__exportStar(require("./checker/story_analysis"), exports);
 __exportStar(require("./checker/standard_library"), exports);
 __exportStar(require("./service/snapshot"), exports);
+__exportStar(require("./service/language_service"), exports);
 __exportStar(require("./language_version"), exports);

package/dist/language_version_value.d.ts

@@ -1 +1 @@
-export declare const PACKAGE_VERSION = "0.12.0-rc.7";
+export declare const PACKAGE_VERSION = "0.12.0";

package/dist/language_version_value.js

@@ -5,4 +5,4 @@ exports.PACKAGE_VERSION = void 0;
 // scripts/build-packages.cjs (a source and its build sit at different depths
 // beside package.json, so neither can require it by one relative path).
 // __test__/language_version.unit.test.ts holds it equal to package.json.
-exports.PACKAGE_VERSION = '0.12.0-rc.7';
+exports.PACKAGE_VERSION = '0.12.0';

package/dist/service/language_service.d.ts

@@ -0,0 +1,82 @@
+import { type LanguageVersion } from '../language_version';
+import type { CatalogSnapshot } from './snapshot';
+export interface LanguageServiceOptions {
+    /** The program's pin. A pin this release does not read gets empty answers,
+     *  the artifact not asked. */
+    languageVersion: LanguageVersion;
+}
+/** A 0-based line and a UTF-16 column within it, as the wasm counts. */
+export interface LinePosition {
+    line: number;
+    character: number;
+}
+export type CompletionKind = 'variable' | 'function' | 'field' | 'edge' | 'module' | 'keyword' | 'property' | 'credential' | 'type' | 'namespace';
+/** An entry that opens a connection flow rather than inserting text: the
+ *  adapter's snapshot entry declares it (`connectActions`). */
+export interface CompletionConnectAction {
+    kind: string;
+    adapter: string;
+    credential?: string;
+}
+export interface CompletionItem {
+    label: string;
+    kind: CompletionKind;
+    detail?: string;
+    /** The text to insert, where it is not the label. */
+    insert?: string;
+    /** What the item replaces: its own range, or the word before the cursor. */
+    from: number;
+    to: number;
+    connectAction?: CompletionConnectAction;
+}
+export interface Completions {
+    /** The word before the cursor, which an item replaces unless it says otherwise. */
+    from: number;
+    to: number;
+    items: CompletionItem[];
+}
+export interface HoverCard {
+    from: number;
+    to: number;
+    markdown: string;
+}
+export type ModuleNamespace = 'adapters' | 'credentials' | 'plugins';
+/** Where a name is defined: this file (`file: null`), a library file of the
+ *  snapshot (offsets into its text), or a module the name was imported from. */
+export type Definition = {
+    file: null;
+    from: number;
+    to: number;
+} | {
+    file: string;
+    from: number;
+    to: number;
+} | {
+    module: {
+        namespace: ModuleNamespace;
+        name: string;
+    };
+};
+export interface QuickFix {
+    title: string;
+    /** The diagnostic code the fix answers. */
+    code: string;
+    preferred: boolean;
+    edits: Array<{
+        from: number;
+        to: number;
+        insert: string;
+    }>;
+}
+/** The completions at `offset`. */
+export declare function completionsAt(source: string, offset: number, snapshot: CatalogSnapshot, options: LanguageServiceOptions): Completions;
+/** The card for what is under `offset`, or null where there is none. */
+export declare function hoverAt(source: string, offset: number, snapshot: CatalogSnapshot, options: LanguageServiceOptions): HoverCard | null;
+/** Where the name under `offset` is defined, or null. */
+export declare function definitionAt(source: string, offset: number, snapshot: CatalogSnapshot, options: LanguageServiceOptions): Definition | null;
+/** The quick fixes for the diagnostics touching `from`..`to`. */
+export declare function quickFixesIn(source: string, from: number, to: number, snapshot: CatalogSnapshot, options: LanguageServiceOptions): QuickFix[];
+/** The UTF-16 offset of `position` in `text`, clamped to its line and to the text. */
+export declare function offsetOf(text: string, position: LinePosition): number;
+/** The line and UTF-16 column of `offset` in `text`, `offset` clamped to the text. */
+export declare function positionOf(text: string, offset: number): LinePosition;

package/dist/service/language_service.js

@@ -0,0 +1,186 @@
+"use strict";
+// The language service (crates/movement-language), through the movement
+// artifact's `language_query` export: completion, hover, go-to-definition
+// and quick fixes for a program in this release's language, answered as the
+// native service answers `lf lsp`.
+//
+// Positions are UTF-16 offsets into the source string (CodeMirror's unit,
+// and a JavaScript string's own); the wasm counts 0-based lines and UTF-16
+// columns, split on `\n` as the native service splits them. A definition in
+// a library file is an offset into that file's text in `snapshot.files`.
+//
+// It loads with the engine artifact, which a browser never downloads: the
+// editor asks it through the server, as it asks for the check.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.completionsAt = completionsAt;
+exports.hoverAt = hoverAt;
+exports.definitionAt = definitionAt;
+exports.quickFixesIn = quickFixesIn;
+exports.offsetOf = offsetOf;
+exports.positionOf = positionOf;
+const loader_1 = require("../wasm/loader");
+const language_version_1 = require("../language_version");
+const rust_checker_1 = require("../checker/rust_checker");
+/** The completions at `offset`. */
+function completionsAt(source, offset, snapshot, options) {
+    if (unread(options))
+        return { from: offset, to: offset, items: [] };
+    const answer = ask(source, snapshot, { kind: 'complete', position: positionOf(source, offset) });
+    if (!isRecord(answer) || !Array.isArray(answer.items))
+        throw malformed('completion', answer);
+    const word = rangeOf(source, answer.word);
+    return { ...word, items: answer.items.map(item => itemOf(source, item, word)) };
+}
+/** The card for what is under `offset`, or null where there is none. */
+function hoverAt(source, offset, snapshot, options) {
+    if (unread(options))
+        return null;
+    const answer = ask(source, snapshot, { kind: 'hover', position: positionOf(source, offset) });
+    if (answer === null)
+        return null;
+    if (!isRecord(answer) || typeof answer.contents !== 'string')
+        throw malformed('hover', answer);
+    return { ...rangeOf(source, answer.range), markdown: answer.contents };
+}
+/** Where the name under `offset` is defined, or null. */
+function definitionAt(source, offset, snapshot, options) {
+    if (unread(options))
+        return null;
+    const answer = ask(source, snapshot, { kind: 'definition', position: positionOf(source, offset) });
+    if (answer === null)
+        return null;
+    if (!isRecord(answer) || (answer.file !== null && typeof answer.file !== 'string'))
+        throw malformed('definition', answer);
+    if (answer.module !== undefined)
+        return { module: moduleOf(answer.module) };
+    if (answer.file === null)
+        return { file: null, ...rangeOf(source, answer.range) };
+    // A library file the snapshot does not carry has no text: its offsets clamp to 0.
+    const text = snapshot.files?.[answer.file]?.source ?? '';
+    return { file: answer.file, ...rangeOf(text, answer.range) };
+}
+/** The quick fixes for the diagnostics touching `from`..`to`. */
+function quickFixesIn(source, from, to, snapshot, options) {
+    if (unread(options))
+        return [];
+    const range = { start: positionOf(source, from), end: positionOf(source, to) };
+    const answer = ask(source, snapshot, { kind: 'codeActions', position: range.start, range });
+    if (!Array.isArray(answer))
+        throw malformed('code actions', answer);
+    return answer.map(action => {
+        if (!isRecord(action) ||
+            typeof action.title !== 'string' ||
+            typeof action.code !== 'string' ||
+            typeof action.preferred !== 'boolean' ||
+            !Array.isArray(action.edits)) {
+            throw malformed('code action', action);
+        }
+        return {
+            title: action.title,
+            code: action.code,
+            preferred: action.preferred,
+            edits: action.edits.map(edit => {
+                if (!isRecord(edit) || typeof edit.newText !== 'string')
+                    throw malformed('edit', edit);
+                return { ...rangeOf(source, edit.range), insert: edit.newText };
+            }),
+        };
+    });
+}
+/** The UTF-16 offset of `position` in `text`, clamped to its line and to the text. */
+function offsetOf(text, position) {
+    let start = 0;
+    for (let line = 0; line < position.line; line++) {
+        const newline = text.indexOf('\n', start);
+        if (newline === -1)
+            return text.length;
+        start = newline + 1;
+    }
+    const newline = text.indexOf('\n', start);
+    const end = newline === -1 ? text.length : newline;
+    return Math.min(start + position.character, end);
+}
+/** The line and UTF-16 column of `offset` in `text`, `offset` clamped to the text. */
+function positionOf(text, offset) {
+    const at = Math.max(0, Math.min(offset, text.length));
+    let line = 0;
+    let start = 0;
+    for (let newline = text.indexOf('\n'); newline !== -1 && newline < at; newline = text.indexOf('\n', start)) {
+        line += 1;
+        start = newline + 1;
+    }
+    return { line, character: at - start };
+}
+function unread(options) {
+    return (0, language_version_1.languageVersionDiagnostic)(options.languageVersion) !== undefined;
+}
+function ask(source, snapshot, query) {
+    const reply = (0, loader_1.callLanguageQuery)(source, JSON.stringify(snapshot), JSON.stringify(query));
+    if (!reply.ok)
+        throw rust_checker_1.RustCheckRefused.of(reply.json);
+    return reply.json;
+}
+const KINDS = new Set([
+    'variable',
+    'function',
+    'field',
+    'edge',
+    'module',
+    'keyword',
+    'property',
+    'credential',
+    'type',
+    'namespace',
+]);
+function isKind(value) {
+    return typeof value === 'string' && KINDS.has(value);
+}
+function itemOf(source, value, word) {
+    if (!isRecord(value) || typeof value.label !== 'string' || !isKind(value.kind))
+        throw malformed('completion item', value);
+    const { label, kind, detail, insert, replace, connectAction } = value;
+    if ((detail !== undefined && typeof detail !== 'string') || (insert !== undefined && typeof insert !== 'string')) {
+        throw malformed('completion item', value);
+    }
+    return {
+        label,
+        kind,
+        ...(detail !== undefined ? { detail } : {}),
+        ...(insert !== undefined ? { insert } : {}),
+        ...(replace !== undefined ? rangeOf(source, replace) : word),
+        ...(connectAction !== undefined ? { connectAction: connectActionOf(connectAction) } : {}),
+    };
+}
+function connectActionOf(value) {
+    if (!isRecord(value) ||
+        typeof value.kind !== 'string' ||
+        typeof value.adapter !== 'string' ||
+        (value.credential !== undefined && typeof value.credential !== 'string')) {
+        throw malformed('connect action', value);
+    }
+    return { kind: value.kind, adapter: value.adapter, ...(value.credential !== undefined ? { credential: value.credential } : {}) };
+}
+function moduleOf(value) {
+    if (!isRecord(value) || typeof value.name !== 'string')
+        throw malformed('module', value);
+    const { namespace, name } = value;
+    if (namespace !== 'adapters' && namespace !== 'credentials' && namespace !== 'plugins')
+        throw malformed('module', value);
+    return { namespace, name };
+}
+function rangeOf(text, value) {
+    if (!isRecord(value))
+        throw malformed('range', value);
+    return { from: offsetOf(text, linePositionOf(value.start)), to: offsetOf(text, linePositionOf(value.end)) };
+}
+function linePositionOf(value) {
+    if (!isRecord(value) || typeof value.line !== 'number' || typeof value.character !== 'number')
+        throw malformed('position', value);
+    return { line: value.line, character: value.character };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function malformed(what, value) {
+    return new Error(`the language service answered a ${what} that is not one: ${JSON.stringify(value)?.slice(0, 200)}`);
+}

package/dist/service/snapshot.js

@@ -190,6 +190,10 @@ function fromCatalogSnapshot(snapshot) {
             // without pre-processing (defense-in-depth: callers should unwrap first,
             // but the snapshot instantiate is the last lookup that can catch it).
             const rawCredName = args?.[credArg?.name ?? 'credentials']?.trim();
+            // A credential the adapter can do without, not given: the
+            // credential-free instance (lf's email, which receives with none).
+            if (rawCredName === undefined && credArg !== undefined && !credArg.required)
+                return at();
             const credentialName = rawCredName !== undefined
                 ? ((0, scan_1.unwrapCredentialArg)(rawCredName) ?? rawCredName)
                 : rawCredName;

package/dist/wasm/loader.d.ts

@@ -128,6 +128,31 @@ export declare function callLanguageStanding(pin: string): {
     ok: boolean;
     json: unknown;
 };
+/**
+ * The language service (crates/movement-language/src/abi.rs
+ * `language_query`): the source, the snapshot and the query as JSON, and the
+ * reply — the native service's answer (an object, an array or `null`), or
+ * `{error}` for a snapshot or a query that does not read.
+ *
+ * @internal Used by the service's wrapper (service/language_service.ts).
+ */
+export declare function callLanguageQuery(source: string, snapshotJson: string, queryJson: string): {
+    ok: boolean;
+    json: unknown;
+};
+/**
+ * The checker's story analysis (crates/movement-checker/src/story.rs
+ * `story_analysis`): `callCheckProgram`'s inputs, and the reply —
+ * `{storyAnalysisVersion, diagnostics, scopes, symbols, writes, nodes,
+ * bodies, shapes}`, or `{error}` for a source that does not parse or a
+ * snapshot that does not load.
+ *
+ * @internal Used by the analysis's wrapper (checker/story_analysis.ts).
+ */
+export declare function callStoryAnalysis(source: string, snapshotJson: string, options: CheckCallOptions): {
+    ok: boolean;
+    json: unknown;
+};
 /**
  * One engine segment's conversation (crates/movement-engine/src/abi.rs):
  * `start` and `answer` each return the next step as `{ok: true, json}` —

package/dist/wasm/loader.js

@@ -34,6 +34,8 @@ exports.callCheckCompatible = callCheckCompatible;
 exports.callStandardLibrary = callStandardLibrary;
 exports.callLanguageVersion = callLanguageVersion;
 exports.callLanguageStanding = callLanguageStanding;
+exports.callLanguageQuery = callLanguageQuery;
+exports.callStoryAnalysis = callStoryAnalysis;
 exports.initEngine = initEngine;
 exports.openEngineSegment = openEngineSegment;
 exports.parserGeneration = parserGeneration;
@@ -185,6 +187,29 @@ function callLanguageVersion() {
 function callLanguageStanding(pin) {
     return callChecker('language_standing', [pin], []);
 }
+/**
+ * The language service (crates/movement-language/src/abi.rs
+ * `language_query`): the source, the snapshot and the query as JSON, and the
+ * reply — the native service's answer (an object, an array or `null`), or
+ * `{error}` for a snapshot or a query that does not read.
+ *
+ * @internal Used by the service's wrapper (service/language_service.ts).
+ */
+function callLanguageQuery(source, snapshotJson, queryJson) {
+    return callChecker('language_query', [source, snapshotJson, queryJson], []);
+}
+/**
+ * The checker's story analysis (crates/movement-checker/src/story.rs
+ * `story_analysis`): `callCheckProgram`'s inputs, and the reply —
+ * `{storyAnalysisVersion, diagnostics, scopes, symbols, writes, nodes,
+ * bodies, shapes}`, or `{error}` for a source that does not parse or a
+ * snapshot that does not load.
+ *
+ * @internal Used by the analysis's wrapper (checker/story_analysis.ts).
+ */
+function callStoryAnalysis(source, snapshotJson, options) {
+    return callChecker('story_analysis', [source, snapshotJson, optionsJson(options)], []);
+}
 function callChecker(fn, inputs, extra) {
     const exports = currentExports();
     const checker = exports.checker[fn];
@@ -400,7 +425,16 @@ function readExports(raw) {
         catalog_query: exported('catalog_query'),
     };
     const checker = {};
-    for (const fn of ['check_program', 'check_answer', 'check_compatible', 'standard_library', 'language_version', 'language_standing']) {
+    for (const fn of [
+        'check_program',
+        'check_answer',
+        'check_compatible',
+        'standard_library',
+        'language_version',
+        'language_standing',
+        'language_query',
+        'story_analysis',
+    ]) {
         if (typeof raw[fn] !== 'function')
             continue;
         const call = exported(fn);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@listen-fire/movement-lang",
   "license": "Apache-2.0",
-  "version": "0.12.0-rc.7",
+  "version": "0.12.0",
   "description": "The data-movement language: the wasm parser, checker and engine with their loader and bindings, the version rule, the expression AST and the types the contracts name",
   "engines": {
-    "node": "22.20.0"
+    "node": ">=22.23.4 <23"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -26,8 +26,7 @@
     "dist"
   ],
   "publishConfig": {
-    "access": "public",
-    "tag": "next"
+    "access": "public"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json && cp wasm/*.wasm dist/wasm/",