@lokascript/framework 4.6.0 → 4.8.0

package/dist/api/translation-loss.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Fail-loud translation: what a translation checks before it returns (domains
+ * rethink Phase 4.5, `docs-internal/DOMAINS_RETHINK.md`). Moved from
+ * `@lokascript/semantic`'s `explicit/lossy.ts`, whose `translate` runs it with
+ * hyperscript's rules; `createMultilingualDSL`'s `translate` keeps its own
+ * read-back (`TranslationReadBackError`).
+ *
+ * A parse that matches a prefix of a script and leaves the rest unread used to
+ * come back from `translate()` as though it were the whole: `toggle .a .b`
+ * became `toggle .a`. A surface that cannot carry a script now says so: the
+ * translation throws a {@link LossyTranslationError}, which carries the output
+ * it would have returned and what it loses. Four checks, cheapest first:
+ *
+ *   - `truncation`  the parse of the input left input bound to no role (its
+ *                   `unconsumed-input` diagnostics);
+ *   - `core-only`   the input holds a form the grammar's writer has no spelling
+ *                   for (hyperscript: a form only `@hyperfixi/core` ran, which
+ *                   upstream reads with another meaning) — `rules.unwritable`;
+ *   - `read-back`   the output, read in the target language, does not read,
+ *                   leaves input unread, or differs from what was written
+ *                   (`rules.differences`, in order);
+ *   - `invariant`   a value the translation must write verbatim is missing
+ *                   from the output (`rules.missingValues`).
+ *
+ * None of them can say a translation is right. Each says one way it is wrong.
+ */
+export type TranslationLossKind = 'truncation' | 'core-only' | 'read-back' | 'invariant';
+/** One way a translation loses part of its input. */
+export interface TranslationLoss {
+    kind: TranslationLossKind;
+    /**
+     * What is lost: the input left unread (`truncation`); the forms nothing
+     * writes (`core-only`, as `swap <strategy>`); the output left unread or what
+     * it reads back without or with in excess (`read-back`, as `-cmd` / `+cmd`);
+     * or the verbatim values missing from the output (`invariant`).
+     */
+    lost: string[];
+}
+export declare class LossyTranslationError extends Error {
+    /** The output `translate()` would have returned: NOT the whole script. */
+    readonly partial: string;
+    readonly loss: TranslationLoss;
+    readonly from: string;
+    readonly to: string;
+    readonly name = "LossyTranslationError";
+    constructor(
+    /** The output `translate()` would have returned: NOT the whole script. */
+    partial: string, loss: TranslationLoss, from: string, to: string);
+}
+/** What the checks read of a parse: its diagnostics. */
+export interface LossCheckedNode {
+    readonly diagnostics?: ReadonlyArray<{
+        readonly code?: string;
+        readonly message: string;
+    }>;
+}
+/** The spans a parse left bound to no role (its top node carries them all). */
+export declare function unconsumedSpans(node: LossCheckedNode): string[];
+/** A grammar's rules for `findTranslationLoss`, for its node type `N`. */
+export interface TranslationLossRules<N extends LossCheckedNode> {
+    /** The forms in `node` the grammar's writer has no spelling for (`core-only`). */
+    unwritable?(node: N): string[];
+    /**
+     * `node` as it was written into the target language, to compare its
+     * read-back with (hyperscript: in upstream's spelling for English). Default:
+     * `node` itself.
+     */
+    written?(node: N): N;
+    /**
+     * How the read-back differs from what was written, checked in order: the
+     * first that finds a difference is the loss (hyperscript: commands, then
+     * roles, then clauses kept as written).
+     */
+    readonly differences: ReadonlyArray<(written: N, back: N) => string[]>;
+    /** The values `input` holds that `output` must write verbatim and does not (`invariant`). */
+    missingValues?(input: string, output: string): string[];
+}
+/**
+ * How a translation of `input` (parsed as `node`) into `output` loses part of
+ * it, or undefined. `readBack` parses the output in the target language; it
+ * throws when the output does not read.
+ */
+export declare function findTranslationLoss<N extends LossCheckedNode>(input: string, node: N, output: string, readBack: (output: string) => N, rules: TranslationLossRules<N>): TranslationLoss | undefined;
+//# sourceMappingURL=translation-loss.d.ts.map

package/dist/api/translation-loss.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-loss.d.ts","sourceRoot":"","sources":["../../src/api/translation-loss.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAEzF,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAC;IAC1B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAI5C,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,IAAI,EAAE,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM;IAPrB,SAAkB,IAAI,2BAA2B;;IAG/C,0EAA0E;IACjE,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM;CAOtB;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5F;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,CAO/D;AAED,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,eAAe;IAC7D,kFAAkF;IAClF,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC;IAC/B;;;;OAIG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;IACvE,6FAA6F;IAC7F,aAAa,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACzD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,eAAe,EAC3D,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,CAAC,EAC/B,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC7B,eAAe,GAAG,SAAS,CAuB7B"}

package/dist/core/index.d.ts

@@ -4,4 +4,5 @@
 export * from './types';
 export * from './tokenization';
 export * from './pattern-matching';
+export * from './matching';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC"}