From 459489733483362e6d80e4fa043dd5b93c38d94b Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Sat, 14 Nov 2026 17:48:54 +0800 Subject: [PATCH] =?UTF-8?q?feat(reverse):=20reverse=20mode=20=E2=80=94=20p?= =?UTF-8?q?ort=20of=20interscript-rs=20src/reverse.rs=20(WO19=20G10)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror the rs reverse engine choice-for-choice at the compiled-IR level: stages reverse (children in reverse order), sub rules swap from/to with boundary-like alias hoisting across the transfer and the capture/ref exchange, to upcase/downcase swap via item case walks, funcalls invert through the Ruby Stdlib.reverse_function table, the document name goes through Document.reverse_name, metadata swaps source/destination scripts, aliases/languages/dependencies pass through. Runtime surface: InterscriptRuntime#reverse reverses the dependency closure and serves the reversed docs under their forward names (rs reverse_document recursion); loadMap/loadMapAsync gain the ruby DSL.parse reverse-name load fallback. Stdlib: unseparate added (reverse_function counterpart of separate); title_case corrected to ruby parity (upcase first char and the char after each separator — no lowering). Documented ruby-crash deviations surface as named MapLogicErrors at reverse time (rs Error::Unsupported): repeat under a to-upcase/downcase sub, a boundary hoist consuming the whole from group, a funcall outside the reverse_function map, an unhandled item kind in the transfer walk. Gates: vitest 404 passed / 4 skipped (408); eslint clean; prettier clean; tsc build clean. --- src/index.ts | 114 ++++ src/reverse.ts | 496 ++++++++++++++++++ src/runtime/executor.ts | 3 + src/stdlib.ts | 40 +- .../reverse/alalc-bul-Cyrl-Latn-1997.isc | 121 +++++ test/fixtures/reverse/rev-boundary.isc | 6 + test/fixtures/reverse/rev-capture.isc | 8 + test/fixtures/reverse/rev-case.isc | 9 + test/fixtures/reverse/rev-delete.isc | 5 + test/fixtures/reverse/rev-dep-lib.isc | 6 + test/fixtures/reverse/rev-dep.isc | 7 + test/fixtures/reverse/rev-funcall.isc | 6 + test/fixtures/reverse/rev-parallel.isc | 9 + test/fixtures/reverse/rev-sequence.isc | 8 + test/fixtures/reverse/rev-upcase-funcall.isc | 5 + test/fixtures/reverse/rev-upcase-repeat.isc | 8 + test/reverse.test.ts | 212 ++++++++ 17 files changed, 1056 insertions(+), 7 deletions(-) create mode 100644 src/reverse.ts create mode 100644 test/fixtures/reverse/alalc-bul-Cyrl-Latn-1997.isc create mode 100644 test/fixtures/reverse/rev-boundary.isc create mode 100644 test/fixtures/reverse/rev-capture.isc create mode 100644 test/fixtures/reverse/rev-case.isc create mode 100644 test/fixtures/reverse/rev-delete.isc create mode 100644 test/fixtures/reverse/rev-dep-lib.isc create mode 100644 test/fixtures/reverse/rev-dep.isc create mode 100644 test/fixtures/reverse/rev-funcall.isc create mode 100644 test/fixtures/reverse/rev-parallel.isc create mode 100644 test/fixtures/reverse/rev-sequence.isc create mode 100644 test/fixtures/reverse/rev-upcase-funcall.isc create mode 100644 test/fixtures/reverse/rev-upcase-repeat.isc create mode 100644 test/reverse.test.ts diff --git a/src/index.ts b/src/index.ts index aeb75b3..d956ed5 100644 --- a/src/index.ts +++ b/src/index.ts @@ -21,6 +21,7 @@ import { SystemConversionError, } from "./errors.js" import { detectInMaps, detectInMapsAsync } from "./detector.js" +import { reverseMap, reverseName } from "./reverse.js" export { InterscriptError, @@ -76,6 +77,7 @@ export { parseIsc } from "./isc/parser.js" export { IscParseError, IscLoadError } from "./isc/types.js" export { iscToCompiledMap, type IscToCompiledMapOptions } from "./isc/converter.js" export { expandDocument, requiredDependencyDocs, type DependencyDocResolver } from "./isc/expand.js" +export { reverseName, reverseMap } from "./reverse.js" export { setRababaConfig, resetRababaConfigs, type RababaConfigEntry } from "./stdlib/ml.js" export interface InterscriptConfig { @@ -99,8 +101,23 @@ class InterscriptRuntime { /** * Pre-load a map so subsequent transliterate() calls are fast. * Throws MapNotFoundError if the map can't be located. + * + * Carries the ruby `Interscript::DSL.parse` reverse-name fallback: a + * missing map whose reverse-named sibling exists loads that sibling + * and returns its reverse (cached under the requested code). */ loadMap(systemCode: SystemCode): CompiledMap { + try { + return this.loadMapWithDeps(systemCode) + } catch (e) { + if (e instanceof MapNotFoundError) return this.loadReversedFallback(systemCode, e) + throw e + } + } + + /** Load a map and warm its direct dependencies (shared by both load + * paths so the sync executor can resolve them without awaiting). */ + private loadMapWithDeps(systemCode: SystemCode): CompiledMap { const map = this.loader.load(systemCode) for (const dep of map.dependencies) { try { @@ -115,6 +132,27 @@ class InterscriptRuntime { return map } + /** + * Ruby DSL.parse fallback: `locate(map)` failed, so try + * `reverse_name(map)` and return the reversed document. Re-raises the + * original error when the fallback name is identical or also missing. + */ + private loadReversedFallback(systemCode: SystemCode, original: MapNotFoundError): CompiledMap { + const fallback = reverseName(systemCode) + if (fallback === systemCode) throw original + let forward: CompiledMap + try { + forward = this.loadMapWithDeps(fallback) + } catch (e) { + if (e instanceof MapNotFoundError) throw original + throw e + } + const reversed = reverseMap(forward) + // Ruby caches the reversed document under the requested name. + this.loader.register(systemCode, reversed) + return reversed + } + /** * Async pre-load. Required when async strategies (HTTP) are configured * and the map isn't already cached. @@ -123,6 +161,29 @@ class InterscriptRuntime { * execution path can resolve deps without awaiting. */ async loadMapAsync(systemCode: SystemCode): Promise { + try { + return await this.loadMapAsyncWithDeps(systemCode) + } catch (e) { + if (e instanceof MapNotFoundError) { + // Same reverse-name fallback as the sync path (ruby DSL.parse). + const fallback = reverseName(systemCode) + if (fallback !== systemCode) { + try { + const forward = await this.loadMapAsyncWithDeps(fallback) + const reversed = reverseMap(forward) + this.loader.register(systemCode, reversed) + return reversed + } catch (e2) { + if (e2 instanceof MapNotFoundError) throw e + throw e2 + } + } + } + throw e + } + } + + private async loadMapAsyncWithDeps(systemCode: SystemCode): Promise { const map = await this.loader.loadAsync(systemCode) // Recursively load every transitive dep. The synchronous executor // calls loader.load() during execution and can't await async @@ -196,6 +257,45 @@ class InterscriptRuntime { } } + /** + * Reverse-mode transliteration — the `iscrs reverse` analog: load the + * map, reverse it (mirroring rs `reverse_document`, which recursively + * reverses embedded dependency documents — here the whole dependency + * closure is reversed and served to execution), then run one stage of + * the reversed document. + */ + reverse(systemCode: SystemCode, input: string, stage?: string, language?: string): string { + const map = this.loadMap(systemCode) + + // rs: dependency documents reverse with the parent. Memoized + // closure walk — cycles recurse in rs/ruby too, only repeat work + // is skipped here. + const reversedDeps = new Map() + const collect = (m: CompiledMap): void => { + for (const dep of m.dependencies) { + if (reversedDeps.has(dep)) continue + let depMap: CompiledMap + try { + depMap = this.loader.load(dep) + } catch (e) { + if (e instanceof MapNotFoundError) throw new DependencyMissingError(dep) + throw e + } + reversedDeps.set(dep, reverseMap(depMap)) + collect(depMap) + } + } + collect(map) + + const reversed = reverseMap(map) + // Serve the reversed dependency documents under their original + // names (run rules reference the forward names). + const depLoader = new MapLoader([]) + for (const [code, depReversed] of reversedDeps) depLoader.register(code, depReversed) + const stageName = stage ?? this.defaultStage + return executeStage(reversed, stageName, input, depLoader, language) + } + /** List all maps currently loaded in the cache. */ loadedMaps(): readonly SystemCode[] { return this.loader.loadedMaps() @@ -270,6 +370,20 @@ export function transliterateAsync( return runtime().transliterateAsync(systemCode, input, stage, language) } +/** + * Public API — reverse-mode transliteration (`iscrs reverse`): load + * `systemCode`, reverse the document (dependencies reverse with the + * parent), and transliterate `input` through it. + */ +export function reverse( + systemCode: SystemCode, + input: string, + stage?: string, + language?: string, +): string { + return runtime().reverse(systemCode, input, stage, language) +} + /** Public API — mirrors Interscript.load. */ export function loadMap(systemCode: SystemCode): CompiledMap { return runtime().loadMap(systemCode) diff --git a/src/reverse.ts b/src/reverse.ts new file mode 100644 index 0000000..46a8c74 --- /dev/null +++ b/src/reverse.ts @@ -0,0 +1,496 @@ +/** + * Reverse mode — port of interscript-rs `src/reverse.rs`, which mirrors + * `Interscript::Node::*#reverse` (interscript-ruby origin/main, + * spec'd by spec/reversibility_spec.rb). + * + * The reversed document runs through the NORMAL executor: the + * inversion lives entirely in the produced document. What rs does at + * the node level, this module does at the compiled-map level: + * + * - stages reverse (children in REVERSE order, each rule reversed); + * - sub rules swap from/to, hoist boundary-like aliases across the + * transfer, and exchange capture groups/refs; + * - `to upcase`/`to downcase` swap via Item#downcase/#upcase parity; + * - funcalls map through the Ruby `Stdlib.reverse_function` table; + * - the document name goes through `Document.reverse_name`; + * - metadata swaps source_script/destination_script; + * - aliases, languages, tests (absent from the IR) pass through. + * + * Documented ruby-crash deviations (rs `Error::Unsupported`, mirrored + * here as MapLogicError with the same information): + * - a repeat item under a `to upcase`/`to downcase` sub + * (ruby: NoMethodError), + * - a boundary hoist consuming the whole from group + * (ruby: NoMethodError on `children=`), + * - a funcall outside the reverse_function map (ruby: nil.to_sym + * TypeError when the reversed funcall executes), + * - an unhandled item kind in the transfer walk (ruby: raise + * "Type ... unhandled!"). + * + * Compiled-IR deltas vs the rs node model (behavior identical): + * - the compiled IR carries no `reverse_run`; a rule whose reversed + * `from` is empty and has no assertions — which ruby marks + * reverse_run: true so the executor skips it — is DROPPED here + * (ruby's own JSON-IR compilers omit reverse_run rules too); + * - dependency documents are names in the IR, so rs's recursion into + * embedded dependency documents lives on the runtime entry point + * (`InterscriptRuntime#reverse`), not on this pure function; + * - capture groups carry no ids: the regex engine numbers them in + * regex order at compile time, which is exactly the numbering + * rs's `assign_group_ids` reproduces; refs keep their numbers; + * - `priority` (absent from the rs model) negates on reverse per + * ruby `Sub#reverse`. + */ + +import type { + CompiledMap, + FuncallInline, + FuncallRule, + Item, + ParallelRule, + Rule, + SequentialRule, + Stage, + StringItem, + SubRule, +} from "./types.js" +import { MapLogicError } from "./errors.js" + +/** + * `Interscript::Stdlib.reverse_function`: the inverse funcall used by + * `Funcall#reverse`. `upcase` has no entry (the Ruby map omits it, so + * reversing an upcase funcall crashes there) — and any other funcall + * name is equally unmapped, mirroring rs's `FuncallName::reverse_name`. + */ +const REVERSE_FUNCTION: Readonly> = Object.freeze({ + // Those two are best-effort, but probably wrong (per Ruby). + title_case: "downcase", + downcase: "title_case", + + compose: "decompose", + decompose: "compose", + + separate: "unseparate", + unseparate: "separate", +}) + +/** + * `Interscript::Stdlib.boundary_like_alias?` restricted to the prims + * rs treats as boundary-like (`Boundary`, `NonWordBoundary`, + * `LineStart`, `LineEnd` — the ISC grammar has no string_start / + * string_end spellings). Names as the ISC parser emits them. + */ +const BOUNDARY_LIKE_ALIASES: ReadonlySet = new Set([ + "boundary", + "non_boundary", + "non_word_boundary", + "line_start", + "line_end", +]) + +/** The compiled-IR form of ruby's `none` (converter lowering). */ +const EMPTY_STRING: StringItem = { kind: "string", value: "" } + +/** + * `Interscript::Node::Document.reverse_name`: split on `-`, swap + * positions 2/3 (source/target code) when there are at least 4 + * segments; otherwise strip a `-reverse` suffix, otherwise append one. + */ +export function reverseName(name: string): string { + const parts = name.split("-") + if (parts.length >= 4) { + const swapped = parts.slice() + const tmp = swapped[2]! + swapped[2] = swapped[3]! + swapped[3] = tmp + const joined = swapped.join("-") + if (joined !== name) return joined + } + const stripped = name.split("-reverse").join("") + return stripped !== name ? stripped : `${name}-reverse` +} + +/** + * `Interscript::Node::Document#reverse` over the compiled form. + * Aliases are NOT reversed (`rdoc.aliases = self.aliases`); dependency + * names pass through (see the module docstring for rs's dependency + * recursion and where it lives instead). + */ +export function reverseMap(map: CompiledMap): CompiledMap { + const stages = map.stages.map(reverseStage) + return { + schemaVersion: 1, + systemCode: reverseName(map.systemCode), + dependencies: [...map.dependencies], + ...(map.languages ? { languages: [...map.languages] } : {}), + ...(map.metadata ? { metadata: reverseMetadata(map.metadata) } : {}), + stages, + aliases: map.aliases, + functions: map.functions, + } +} + +/** + * `MetaData#reverse` swaps source_script/destination_script (each side + * only when the other is present — rs `reverse_metadata`). + */ +function reverseMetadata(metadata: Readonly>): Record { + const src = metadata["source_script"] + const dst = metadata["destination_script"] + const out = { ...metadata } + if ("source_script" in out && dst !== undefined) out["source_script"] = dst + if ("destination_script" in out && src !== undefined) out["destination_script"] = src + return out +} + +/** + * `Interscript::Node::Stage#reverse` / `Group#reverse`: children in + * REVERSE order, each reversed, reverse_run toggled. (The ISC grammar + * cannot express `dont_reverse`, so stages always reverse.) + */ +function reverseStage(stage: Stage): Stage { + const rules: Rule[] = [] + for (let i = stage.rules.length - 1; i >= 0; i--) { + const reversed = reverseRule(stage.rules[i]!) + // A sub whose reversed `from` is empty is dropped, not emitted + // (see the module docstring — ruby marks it reverse_run: true). + if (reversed !== null) rules.push(reversed) + } + return { kind: "stage", name: stage.name, rules } +} + +/** `null` = the reversed rule must not execute (ruby reverse_run: true). */ +function reverseRule(rule: Rule): Rule | null { + switch (rule.kind) { + case "sub": + return reverseSub(rule) + + case "run": + // rs toggles reverse_run; the compiled IR carries none → identity. + return rule + + case "funcall": { + // `Interscript::Node::Rule::Funcall#reverse`: the name maps + // through `Stdlib.reverse_function`; kwargs carry over. + const target = REVERSE_FUNCTION[rule.name] + if (!target) { + throw new MapLogicError( + `funcall ${rule.name} has no reverse (the Ruby reverse_function map omits it)`, + ) + } + const out: FuncallRule = { + kind: "funcall", + name: target, + ...(rule.kwargs ? { kwargs: rule.kwargs } : {}), + } + return out + } + + case "parallel": + case "sequential": { + const rules: Rule[] = [] + for (let i = rule.rules.length - 1; i >= 0; i--) { + const reversed = reverseRule(rule.rules[i]!) + if (reversed !== null) rules.push(reversed) + } + const out: ParallelRule | SequentialRule = + rule.kind === "parallel" ? { kind: "parallel", rules } : { kind: "sequential", rules } + return out + } + } +} + +/** + * `Interscript::Node::Rule::Sub#reverse`. + * Returns `null` when the reversed rule must not execute: a rule whose + * reversed `from` is empty (and carries no assertions) would match + * EVERYWHERE — ruby's Sub#reverse marks those reverse_run: true so the + * executor skips them, and the compiled-IR equivalent is absence. + */ +function reverseSub(rule: SubRule): SubRule | null { + if (!rule.from) throw new MapLogicError("sub rule missing 'from'") + + let xfrom: Item + let xto: Item | FuncallInline + const to = rule.to + + if (to && to.kind === "funcall_inline") { + // `sub from, to upcase` reverses to `sub from.downcase, to downcase` + // (Item#downcase / Item#upcase parity, and vice versa). + if (to.name === "upcase") { + xfrom = itemCase(rule.from, false) + xto = { kind: "funcall_inline", name: "downcase" } + } else if (to.name === "downcase") { + xfrom = itemCase(rule.from, true) + xto = { kind: "funcall_inline", name: "upcase" } + } else { + // rs builder: only upcase/downcase functions become SubTo + // targets; any other inline funcall walks the transfer and hits + // its unhandled arm. + const [f, t] = reverseTransfer(rule.from, to) + xfrom = f + xto = t + } + } else { + const [f, t] = reverseTransfer(rule.from, to ?? EMPTY_STRING) + xfrom = f + xto = t + } + + // Constraints pass through UNCHANGED (ruby keeps + // before/after/not_before/not_after as-is); `priority` negates + // (ruby Sub#reverse); `when` guards carry over unchanged (ISC-WF-1 + // W3 — the language selection filters the same rows on either + // surface). + const reversed: SubRule = { + kind: "sub", + from: xfrom, + to: xto, + ...(rule.before !== undefined ? { before: rule.before } : {}), + ...(rule.notBefore !== undefined ? { notBefore: rule.notBefore } : {}), + ...(rule.after !== undefined ? { after: rule.after } : {}), + ...(rule.notAfter !== undefined ? { notAfter: rule.notAfter } : {}), + ...(rule.priority !== undefined && rule.priority !== null ? { priority: -rule.priority } : {}), + ...(rule.when !== undefined && rule.when.length > 0 ? { when: rule.when } : {}), + } + + const hasAssertions = Boolean(rule.before || rule.notBefore || rule.after || rule.notAfter) + if (hasAssertions || !isEmptyFrom(xfrom)) return reversed + return null +} + +/** + * The ruby empty-from test: `xfrom == "" || String("")` (plus ruby's + * `Alias(:none)` arm, unreachable in the compiled IR — the converter + * lowers `none` to an empty string item). + */ +function isEmptyFrom(item: Item): boolean { + return item.kind === "string" && item.value === "" +} + +// --------------------------------------------------------------------------- +// Item#downcase / Item#upcase (Sub#reverse to upcase/downcase case) +// --------------------------------------------------------------------------- + +/** `Item#downcase`. */ +export function itemDowncase(item: Item): Item { + return itemCase(item, false) +} + +/** `Item#upcase`. */ +export function itemUpcase(item: Item): Item { + return itemCase(item, true) +} + +/** + * `Item#downcase`/`Item#upcase`: string data case-maps; groups and + * captures recurse; aliases (incl. boundary prims) and refs are + * identity; `any` rebuilds from per-entry case-mapped children; a + * char-class range rebuilds as the set of its per-char entries + * (`Any.new(data.map(&:downcase))` parity). + */ +function itemCase(item: Item, up: boolean): Item { + const apply = (s: string): string => (up ? s.toUpperCase() : s.toLowerCase()) + switch (item.kind) { + case "string": + return { kind: "string", value: apply(item.value) } + // Item::Alias#downcase/#upcase = self; refs too. + case "alias": + case "capture_ref": + return item + case "capture_group": + return { kind: "capture_group", data: itemCase(item.data, up) } + case "group": + return { kind: "group", items: item.items.map((c) => itemCase(c, up)) } + case "any": + return { kind: "any", of: item.of.map((c) => itemCase(c, up)) } + case "any_char_class": { + if (item.range) { + const [lo, hi] = item.range + const entries: Item[] = [] + for (let cp = lo.codePointAt(0)!; ; cp++) { + entries.push({ kind: "string", value: apply(String.fromCodePoint(cp)) }) + if (cp === hi.codePointAt(0)!) break + } + return { kind: "any", of: entries } + } + if (item.chars) { + return { kind: "any", of: item.chars.map((c) => ({ kind: "string", value: apply(c) })) } + } + return item + } + // Ruby Item::Repeat has no downcase/upcase: NoMethodError. + case "repeat": + throw new MapLogicError( + "repeat item in a to-upcase/downcase sub (the Ruby reverse raises NoMethodError)", + ) + case "stage_ref": + throw new MapLogicError( + `unhandled item kind ${item.kind} in a to-upcase/downcase sub (the Ruby reverse raises NoMethodError)`, + ) + } +} + +// --------------------------------------------------------------------------- +// Sub#reverse_transfer: boundary hoisting + capture/ref exchange +// --------------------------------------------------------------------------- + +function isBoundaryLike(item: Item): boolean { + return item.kind === "alias" && BOUNDARY_LIKE_ALIASES.has(item.name) +} + +/** Ruby `Group#compact` over an already-collected children list: + * drop none/"" children; 0 -> none (the IR empty string), 1 -> the child. */ +function compactItems(children: Item[]): Item { + const kept = children.filter((c) => !(c.kind === "string" && c.value === "")) + if (kept.length === 0) return { ...EMPTY_STRING } + if (kept.length === 1) return kept[0]! + return { kind: "group", items: kept } +} + +/** Ruby `Group.new + a + b ...` then `compact`: a fresh group whose + * children are the leading items plus `last` — flattened when `last` + * is itself a group (`Group#+` merges children). */ +function groupPlusCompact(prefix: Item[], last: Item): Item { + const children = prefix.slice() + if (last.kind === "group") children.push(...last.items) + else children.push(last) + return compactItems(children) +} + +/** + * `Interscript::Node::Rule::Sub#reverse_transfer`: boundary-like + * aliases at the from edges move onto the to side; then the + * capture/ref exchange runs. Returns (reversed_from, reversed_to) — + * the ruby multi-assign `xto, xfrom = reverse_transfer(from, to)` + * swaps the results. + */ +function reverseTransfer(from: Item, to: Item | FuncallInline): [Item, Item] { + let f = from + let t: Item | FuncallInline = to + + if (f.kind === "group") { + // Ruby reads first/last BEFORE either mutation. + const parts = f.items + const first = parts[0] + const last = parts[parts.length - 1] + + // first child boundary-like -> prepended to `to` + if (first && isBoundaryLike(first)) { + t = groupPlusCompact([first], t as Item) + f = compactItems(parts.slice(1)) + } + // last child boundary-like -> appended to `to`. Ruby mutates + // `from.children` here, which requires `from` to still be a Group; + // a first-hoist that consumed the whole group crashes there + // (NoMethodError). + if (last && isBoundaryLike(last)) { + if (f.kind !== "group") { + throw new MapLogicError( + "boundary hoist consumed the whole from group " + + "(the Ruby reverse raises NoMethodError)", + ) + } + const shorter = f.items.slice(0, -1) + t = groupPlusCompact([t as Item], last) + f = compactItems(shorter) + } + } else { + // Whole-from boundary alias: `_end`-suffixed names append after + // `to`, everything else prepends before it; from becomes `none`. + // Ruby tests `from.name.end_with?("_end")` — among the ISC prims + // only line_end qualifies (string_end is not in the grammar). + if (isBoundaryLike(f)) { + const boundary = f + t = + boundary.kind === "alias" && boundary.name === "line_end" + ? groupPlusCompact([t as Item], boundary) + : groupPlusCompact([boundary], t as Item) + f = { ...EMPTY_STRING } + } + } + + // --- capture/ref exchange --- + const state: TransferState = { left: [], right: new Set() } + const visitedFrom = transferVisit(f, "from", state) + const visitedTo = transferVisit(t, "to", state) + // xto, xfrom = reverse_transfer(from, to) + return [visitedTo, visitedFrom] +} + +interface TransferState { + /** Ruby state[:left]: every capture group seen, in visit order; + * minted ref ids index into it (1-based). */ + left: Item[] + /** Ruby state[:right]: ref ids already substituted on the `to` + * side (a second occurrence stays a literal ref). */ + right: Set +} + +/** + * `reverse_transfer_visit`. Refs stay positional numbers — the regex + * engine numbers the reversed rule's groups in regex order at compile + * time, the same numbers ruby's `build_regexp` assigns at build time. + */ +function transferVisit( + node: Item | FuncallInline, + side: "from" | "to", + state: TransferState, +): Item { + switch (node.kind) { + case "alias": + // Alias :kor_maybedash -> CaptureRef(left.length). (rs's builder + // expands the alias to its capture(maybe("-")) tree before + // reverse sees it, where the CaptureGroup branch handles it with + // identical numbering — this branch guards direct alias items + // and documents the Ruby special case.) + if (node.name === "kor_maybedash") { + state.left.push(node) + return { kind: "capture_ref", id: state.left.length } + } + return node + + case "string": + return node + + case "capture_ref": + if (side === "from") return node + // refs on the to side: the first occurrence substitutes the + // matching from-side group; further occurrences stay refs. + if (state.right.has(node.id)) return node + state.right.add(node.id) + { + const group = state.left[node.id - 1] + if (!group) throw new MapLogicError("Capture count doesn't match") + return group + } + + case "capture_group": { + state.left.push(node) + const out: Item = { kind: "capture_ref", id: state.left.length } + // Visit but don't care (inner groups still register). + transferVisit(node.data, side, state) + return out + } + + case "any": + return { kind: "any", of: node.of.map((c) => transferVisit(c, side, state)) } + + case "group": + return { kind: "group", items: node.items.map((c) => transferVisit(c, side, state)) } + + // Repeat: only the data is visited; the repeat kind survives. + case "repeat": + return { ...node, item: transferVisit(node.item, side, state) } + + case "any_char_class": + return node + + case "stage_ref": + case "funcall_inline": + throw new MapLogicError( + `Type ${node.kind} unhandled in reverse_transfer_visit ` + + '(the Ruby raises "Type ... unhandled!")', + ) + } +} diff --git a/src/runtime/executor.ts b/src/runtime/executor.ts index bce4d4a..1a95e85 100644 --- a/src/runtime/executor.ts +++ b/src/runtime/executor.ts @@ -26,6 +26,7 @@ import { upcase, titleCase, separate, + unseparate, compose, decompose, } from "../stdlib.js" @@ -43,6 +44,8 @@ const BUILTIN_FUNCTIONS: Record titleCase(i, o ?? {}), separate: (i, o) => separate(i, o ?? {}), + // Reverse-mode counterpart of `separate` (Stdlib.reverse_function). + unseparate: (i, o) => unseparate(i, o ?? {}), compose, decompose, } diff --git a/src/stdlib.ts b/src/stdlib.ts index 9912a67..ea362dc 100644 --- a/src/stdlib.ts +++ b/src/stdlib.ts @@ -170,16 +170,30 @@ export function upcase(input: string): string { } /** - * Capitalise each word; honours custom word separator. - * Maps to `Interscript.functions.title_case`. + * Title-case — `Interscript::Stdlib::Functions.title_case` / rs + * `title_case` parity: upcase the FIRST character of the string, then + * the character following each word separator. Other characters are + * untouched (ruby `gsub(/^(.)/)` + `gsub(/#{sep}(.)/)` — notably NOT + * full per-word title-casing). */ export function titleCase(input: string, opts: { wordSeparator?: string } = {}): string { const sep = opts.wordSeparator ?? " " - if (sep === "") return input.charAt(0).toUpperCase() + input.slice(1).toLowerCase() - return input - .split(sep) - .map((w) => (w.length === 0 ? w : w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())) - .join(sep) + const chars = Array.from(input) + if (chars.length > 0) chars[0] = chars[0]!.toUpperCase() + if (sep === "") return chars.join("") + const sepChars = Array.from(sep) + const out: string[] = [] + let i = 0 + while (i < chars.length) { + if (i + sepChars.length < chars.length && sepChars.every((c, k) => chars[i + k] === c)) { + out.push(sep, chars[i + sepChars.length]!.toUpperCase()) + i += sepChars.length + 1 + } else { + out.push(chars[i]!) + i += 1 + } + } + return out.join("") } /** @@ -191,6 +205,18 @@ export function separate(input: string, opts: { separator?: string } = {}): stri return input.split("").join(sep) } +/** + * Remove every separator (the inverse of `separate`). + * Maps to `Interscript.functions.unseparate` — used by reverse mode + * (`Stdlib.reverse_function` maps separate <-> unseparate). Split + * semantics mirror rs/ruby: trailing empty segments survive the split + * and rejoin (no trimming). + */ +export function unseparate(input: string, opts: { separator?: string } = {}): string { + const sep = opts.separator ?? " " + return input.split(sep).join("") +} + /** * Unicode NFC normalisation via String.prototype.normalize. */ diff --git a/test/fixtures/reverse/alalc-bul-Cyrl-Latn-1997.isc b/test/fixtures/reverse/alalc-bul-Cyrl-Latn-1997.isc new file mode 100644 index 0000000..dce3169 --- /dev/null +++ b/test/fixtures/reverse/alalc-bul-Cyrl-Latn-1997.isc @@ -0,0 +1,121 @@ +system "ALA-LC:bul-Cyrl:Latn:1997" { + +metadata { + authority_id alalc + id 1997 + language iso-639-2:bul + source_script Cyrl + destination_script Latn + name Romanization Table -- Bulgarian (1997) + url http://www.rechtertie.nl/databases/judd/downloads/Bulgarian.pdf + creation_date 1997 + + notes { + note " The letter Ъ in the initial and medial position is a vowel in Bulgarian and is romanized as ŭ.\n It appears in the final position chiefly in texts published before 1945, in which it serves as\n a hard sign and is romanized as ʺ." + note "The letters Ѣ and Ѫ are found chiefly in texts published before the orthographic reform of 1945." + } +} + +tests { + # missing +} + +# This map has been partially converted by the bin/maps_v1_to_v2 script +# The section below requires human attention. Remember to remove this +# comment and move the converted map to 'maps/' directory. Please also +# take note that the maps-staging directory will be cleaned up whenever +# you run the bin/maps_v1_to_v2 script. You should particularly be +# concerned about any regular expressions found in this file and about +# advanced expressions in parallel {} parts, and also about the order +# of particular parts of the stage. + +stage main { + + # RULES + # note[1] + sub { + from "\u042a" + to "ʺ" + before "" + after boundary + } + sub { + from "u044a" + to "ʺ" + before "" + after boundary + } + + + # CHARACTERS + parallel { + sub "\u0410" "A" + sub "\u0411" "B" + sub "\u0412" "V" + sub "\u0413" "G" + sub "\u0414" "D" + sub "\u0415" "E" + sub "\u0416" "Zh" + sub "\u0417" "Z" + sub "\u0418" "I" + sub "\u0419" "Ĭ" + sub "\u041a" "K" + sub "\u041b" "L" + sub "\u041c" "M" + sub "\u041d" "N" + sub "\u041e" "O" + sub "\u041f" "P" + sub "\u0420" "R" + sub "\u0421" "S" + sub "\u0422" "T" + sub "\u0423" "U" + sub "\u0424" "F" + sub "\u0425" "Kh" + sub "\u0426" "T͡S" + sub "\u0427" "Ch" + sub "\u0428" "Sh" + sub "\u0429" "Sht" + sub "\u042a" "Ŭ" + sub "\u042c" "\u02B9" + sub "\u0462" "I͡E" + sub "\u042e" "I͡U" + sub "\u042f" "I͡A" + sub "\u046A" "U̐" + + sub "\u0430" "a" + sub "\u0431" "b" + sub "\u0432" "v" + sub "\u0433" "g" + sub "\u0434" "d" + sub "\u0435" "e" + sub "\u0436" "zh" + sub "\u0437" "z" + sub "\u0438" "i" + sub "\u0439" "ĭ" + sub "\u043a" "k" + sub "\u043b" "l" + sub "\u043c" "m" + sub "\u043d" "n" + sub "\u043e" "o" + sub "\u043f" "p" + sub "\u0440" "r" + sub "\u0441" "s" + sub "\u0442" "t" + sub "\u0443" "u" + sub "\u0444" "f" + sub "\u0445" "kh" + sub "\u0446" "t͡s" + sub "\u0447" "ch" + sub "\u0448" "sh" + sub "\u0449" "sht" + sub "\u044a" "ŭ" + sub "\u044c" "\u02B9" + sub "\u0463" "i͡e" + sub "\u044e" "i͡u" + sub "\u044f" "i͡a" + sub "\u046B" "u̐" + } + +} + +} diff --git a/test/fixtures/reverse/rev-boundary.isc b/test/fixtures/reverse/rev-boundary.isc new file mode 100644 index 0000000..09e8b1c --- /dev/null +++ b/test/fixtures/reverse/rev-boundary.isc @@ -0,0 +1,6 @@ +system "rev:boundary" { +stage main { + sub "x" "y" after boundary + sub "q" "r" before line_end +} +} diff --git a/test/fixtures/reverse/rev-capture.isc b/test/fixtures/reverse/rev-capture.isc new file mode 100644 index 0000000..81d84ad --- /dev/null +++ b/test/fixtures/reverse/rev-capture.isc @@ -0,0 +1,8 @@ +system "rev:capture" { +stage main { + sub { + from "a" + capture("b" + maybe("c")) + "d" + to "X" + ref(1) + } +} +} diff --git a/test/fixtures/reverse/rev-case.isc b/test/fixtures/reverse/rev-case.isc new file mode 100644 index 0000000..da8fa91 --- /dev/null +++ b/test/fixtures/reverse/rev-case.isc @@ -0,0 +1,9 @@ +system "rev:case" { +stage main { + sub { + from "abc" + to upcase + } + downcase +} +} diff --git a/test/fixtures/reverse/rev-delete.isc b/test/fixtures/reverse/rev-delete.isc new file mode 100644 index 0000000..47ec578 --- /dev/null +++ b/test/fixtures/reverse/rev-delete.isc @@ -0,0 +1,5 @@ +system "rev:delete" { +stage main { + sub "h" none +} +} diff --git a/test/fixtures/reverse/rev-dep-lib.isc b/test/fixtures/reverse/rev-dep-lib.isc new file mode 100644 index 0000000..3745463 --- /dev/null +++ b/test/fixtures/reverse/rev-dep-lib.isc @@ -0,0 +1,6 @@ +system "rev:dep-lib" { +stage main { + sub "n" "p" + sub "e" "f" +} +} diff --git a/test/fixtures/reverse/rev-dep.isc b/test/fixtures/reverse/rev-dep.isc new file mode 100644 index 0000000..9c42580 --- /dev/null +++ b/test/fixtures/reverse/rev-dep.isc @@ -0,0 +1,7 @@ +system "rev:dep-main" { +dependency "rev-dep-lib" as base +stage main { + sub "m" "n" + run map.base.stage.main +} +} diff --git a/test/fixtures/reverse/rev-funcall.isc b/test/fixtures/reverse/rev-funcall.isc new file mode 100644 index 0000000..38e024b --- /dev/null +++ b/test/fixtures/reverse/rev-funcall.isc @@ -0,0 +1,6 @@ +system "rev:funcall" { +stage main { + separate separator "-" + compose +} +} diff --git a/test/fixtures/reverse/rev-parallel.isc b/test/fixtures/reverse/rev-parallel.isc new file mode 100644 index 0000000..2e050fc --- /dev/null +++ b/test/fixtures/reverse/rev-parallel.isc @@ -0,0 +1,9 @@ +system "rev:parallel" { +stage main { + parallel { + sub "ph" "f" + sub "th" "t" + sub "x" "ks" + } +} +} diff --git a/test/fixtures/reverse/rev-sequence.isc b/test/fixtures/reverse/rev-sequence.isc new file mode 100644 index 0000000..68f3f3e --- /dev/null +++ b/test/fixtures/reverse/rev-sequence.isc @@ -0,0 +1,8 @@ +system "rev:sequence" { +stage main { + sequence { + sub "ab" "X" + sub "X" "Q" + } +} +} diff --git a/test/fixtures/reverse/rev-upcase-funcall.isc b/test/fixtures/reverse/rev-upcase-funcall.isc new file mode 100644 index 0000000..272f792 --- /dev/null +++ b/test/fixtures/reverse/rev-upcase-funcall.isc @@ -0,0 +1,5 @@ +system "rev:upcase" { +stage main { + upcase +} +} diff --git a/test/fixtures/reverse/rev-upcase-repeat.isc b/test/fixtures/reverse/rev-upcase-repeat.isc new file mode 100644 index 0000000..7f90cbe --- /dev/null +++ b/test/fixtures/reverse/rev-upcase-repeat.isc @@ -0,0 +1,8 @@ +system "rev:upcase-repeat" { +stage main { + sub { + from maybe("a") + to upcase + } +} +} diff --git a/test/reverse.test.ts b/test/reverse.test.ts new file mode 100644 index 0000000..7016af7 --- /dev/null +++ b/test/reverse.test.ts @@ -0,0 +1,212 @@ +/** + * Reverse-mode parity — ported from interscript-rs `tests/reverse.rs`, + * whose expectations are ruby ground truth (`Document#reverse` over + * interscript-ruby origin/main, `spec/reversibility_spec.rb`). + * + * Fixtures: test/fixtures/reverse/*.isc (vendored from + * interscript-rs tests/reverse_maps/, plus rev-upcase-repeat for the + * repeat-item deviation). + * + * Documented ruby-crash deviations surface as named MapLogicErrors at + * reverse time (mirroring rs `Error::Unsupported` messages): + * - a repeat (maybe/some) item under a `to upcase`/`to downcase` sub + * - a boundary hoist that consumes the whole from group + * - a funcall outside the reverse_function map (upcase has no entry) + */ + +import { describe, it, expect, beforeAll } from "vitest" +import { readFileSync, readdirSync } from "fs" +import { join } from "path" +import { parseIsc } from "../src/isc/parser.ts" +import { iscToCompiledMap } from "../src/isc/converter.ts" +import { iscBundledStrategy } from "../src/isc/loader.ts" +import { normaliseMap } from "../src/loaders.js" +import { configure, reset, transliterate, reverse } from "../src/index.js" +import { reverseName, reverseMap } from "../src/reverse.js" +import type { CompiledMap, GroupItem, SubRule, AliasItem } from "../src/types.js" +import { MapLogicError } from "../src/errors.js" + +const FIXTURES_DIR = join(__dirname, "fixtures", "reverse") + +/** Load every fixture under both its file stem and its system code + * (dependency targets are file stems; top-level loads use the code). */ +function loadSources(): Record { + const sources: Record = {} + for (const f of readdirSync(FIXTURES_DIR).filter((f) => f.endsWith(".isc"))) { + const src = readFileSync(join(FIXTURES_DIR, f), "utf8") + const doc = parseIsc(src, f) + sources[f.replace(/\.isc$/, "")] = src + sources[doc.systemCode] = src + } + return sources +} + +const sources = loadSources() + +beforeAll(() => { + reset() + configure({ strategies: [iscBundledStrategy(sources)] }) +}) + +function compile(code: string): CompiledMap { + return normaliseMap(iscToCompiledMap(parseIsc(sources[code]!, code))) +} + +/** Reverse a map and transliterate `input` through its main stage — + * the mirror of the rs test's `reverse_run` helper (rt.load + + * reverse_document + execute): the runtime path, so dependency + * documents reverse with the parent exactly like rs. */ +function reverseRun(mapId: string, input: string): string { + return reverse(mapId, input) +} + +describe("reverseName (Document.reverse_name)", () => { + it("swaps source and target codes at 4+ dash segments", () => { + expect(reverseName("alalc-bul-Cyrl-Latn-1997")).toBe("alalc-bul-Latn-Cyrl-1997") + // the swap is an involution + expect(reverseName("alalc-bul-Latn-Cyrl-1997")).toBe("alalc-bul-Cyrl-Latn-1997") + }) + + it("strips a -reverse suffix, else appends one", () => { + expect(reverseName("some-map-reverse")).toBe("some-map") + expect(reverseName("short-x")).toBe("short-x-reverse") + expect(reverseName("a-b-c")).toBe("a-b-c-reverse") + }) +}) + +describe("reverseMap — rs reverse.rs parity slice", () => { + it("parallel rules swap and reverse order", () => { + expect(reverseRun("rev:parallel", "phth")).toBe("phthh") + expect(reverseRun("rev:parallel", "x")).toBe("x") + expect(reverseRun("rev:parallel", "fats")).toBe("phaths") + }) + + it("sequential children reverse order", () => { + expect(reverseRun("rev:sequence", "Q")).toBe("ab") + expect(reverseRun("rev:sequence", "X")).toBe("ab") + expect(reverseRun("rev:sequence", "ab")).toBe("ab") + expect(reverseRun("rev:sequence", "abq")).toBe("abq") + }) + + it("case swap downcases the from tree", () => { + expect(reverseRun("rev:case", "abc")).toBe("Abc") + expect(reverseRun("rev:case", "abc ABC")).toBe("Abc ABC") + }) + + it("boundary constraints pass through unchanged", () => { + expect(reverseRun("rev:boundary", "r y")).toBe("r x") + expect(reverseRun("rev:boundary", "yq")).toBe("yq") + expect(reverseRun("rev:boundary", "qr")).toBe("qr") + }) + + it("capture and ref exchange sides", () => { + expect(reverseRun("rev:capture", "Xbc")).toBe("abcd") + expect(reverseRun("rev:capture", "Xd")).toBe("Xd") + expect(reverseRun("rev:capture", "abcd")).toBe("abcd") + }) + + it("funcalls invert through the reverse function map", () => { + expect(reverseRun("rev:funcall", "a-b-c")).toBe("abc") + expect(reverseRun("rev:funcall", "abc")).toBe("abc") + }) + + it("dependency documents reverse with the parent", () => { + expect(reverseRun("rev:dep-main", "men")).toBe("mem") + expect(reverseRun("rev:dep-main", "pem")).toBe("mem") + }) + + it("real corpus map reverses like ruby (alalc-bul-Cyrl-Latn-1997)", () => { + expect(reverseRun("ALA-LC:bul-Cyrl:Latn:1997", "Kirillicata")).toBe("Кириллиcата") + expect(reverseRun("ALA-LC:bul-Cyrl:Latn:1997", "zapad")).toBe("запад") + expect(reverseRun("ALA-LC:bul-Cyrl:Latn:1997", "Sofiya")).toBe("Софиyа") + }) + + it("empty reversed from disables the rule", () => { + // sub "h" none reverses to a rule matching everywhere; ruby marks it + // reverse_run: true (executor skips) — the compiled-IR form drops it. + expect(reverseRun("rev:delete", "hh")).toBe("hh") + expect(reverseRun("rev:delete", "hi")).toBe("hi") + }) + + it("reverses the document name and swaps metadata scripts", () => { + const map = compile("ALA-LC:bul-Cyrl:Latn:1997") + const reversed = reverseMap(map) + // The system code has 3 dash-parts (colons separate the fields), + // so Document.reverse_name appends the -reverse suffix. + expect(reversed.systemCode).toBe("ALA-LC:bul-Cyrl:Latn:1997-reverse") + const md = reversed.metadata as Record + expect(md["source_script"]).toBe("Latn") + expect(md["destination_script"]).toBe("Cyrl") + // aliases and languages pass through untouched (rs: rdoc.aliases = self.aliases) + expect(reversed.aliases).toBe(map.aliases) + expect(reversed.languages).toBe(map.languages) + expect(reversed.dependencies).toEqual(map.dependencies) + }) +}) + +describe("runtime reverse + reverse-name load fallback", () => { + it("transliterate resolves a missing map through its reverse name", () => { + // no "rev:parallel-reverse" map exists — the fallback loads + // rev:parallel and returns its reverse (ruby DSL.parse behavior). + expect(transliterate("rev:parallel-reverse", "fats")).toBe("phaths") + }) + + it("runtime reverse executes dependency documents reversed", () => { + expect(reverse("rev:dep-main", "men")).toBe("mem") + expect(reverse("rev:dep-main", "pem")).toBe("mem") + }) +}) + +describe("documented ruby-crash deviations surface as named errors", () => { + it("upcase funcall has no reverse (rs: Error::Unsupported)", () => { + const map = compile("rev:upcase") + expect(() => reverseMap(map)).toThrow(/upcase has no reverse/) + }) + + it("repeat item under to-upcase raises (ruby NoMethodError)", () => { + const map = compile("rev:upcase-repeat") + expect(() => reverseMap(map)).toThrow(/repeat item in a to-upcase\/downcase sub/) + }) + + it("boundary hoist consuming the whole from group raises (ruby NoMethodError)", () => { + // Hand-built: a one-child group whose only child is boundary-like — + // unreachable through the ISC converter (single-part concats + // unwrap) but the same path rs guards with Error::Unsupported. + const boundary = { kind: "alias", name: "boundary" } as AliasItem + const from: GroupItem = { kind: "group", items: [boundary] } + const rule: SubRule = { kind: "sub", from, to: { kind: "string", value: "x" } } + const map: CompiledMap = { + schemaVersion: 1, + systemCode: "unit:hoist", + dependencies: [], + stages: [{ kind: "stage", name: "main", rules: [rule] }], + aliases: new Map(), + functions: new Map(), + } + let caught: unknown + try { + reverseMap(map) + } catch (e) { + caught = e + } + expect(caught).toBeInstanceOf(MapLogicError) + expect((caught as Error).message).toMatch(/boundary hoist consumed the whole from group/) + }) + + it("unhandled item kind in the from tree raises (ruby 'Type ... unhandled!')", () => { + const rule: SubRule = { + kind: "sub", + from: { kind: "stage_ref", name: "other" }, + to: { kind: "string", value: "x" }, + } + const map: CompiledMap = { + schemaVersion: 1, + systemCode: "unit:unhandled", + dependencies: [], + stages: [{ kind: "stage", name: "main", rules: [rule] }], + aliases: new Map(), + functions: new Map(), + } + expect(() => reverseMap(map)).toThrow(/unhandled in reverse_transfer/) + }) +})