diff --git a/changelog.d/pts-shdy.md b/changelog.d/pts-shdy.md new file mode 100644 index 0000000..baf119c --- /dev/null +++ b/changelog.d/pts-shdy.md @@ -0,0 +1,3 @@ +### Added + +- `DecompileResult` names the result `decompile` answers - the rendered `source` on the succeeding arm, or the `ParseError` that refused the tree on the failing one - so a host can annotate it by name, as it does `ParseResult` and `CompileResult`, instead of deriving it from the function; the shape is unchanged. diff --git a/docs/adr/0004-the-compiler-surface.md b/docs/adr/0004-the-compiler-surface.md index a010c14..2fb32a2 100644 --- a/docs/adr/0004-the-compiler-surface.md +++ b/docs/adr/0004-the-compiler-surface.md @@ -1653,3 +1653,49 @@ close the block", ahead of the same "but found" tail, while `Unterminated single-quoted string literal` substitutes one word of `Unterminated double-quoted string literal` and adds none. The mapping stands as that amendment states it. + +## Amendment: `decompile`'s result type is exported, as `DecompileResult` (2026-10-01) + +Status: proposed (2026-10-01) + +Recorded for `pts-shdy`. This entry amends what the record decides about the +names the package exports: the result type `decompile` answers gains a public +name, and that supersedes one sentence of an accepted amendment above. It +changes nothing about what `decompile` answers, and it removes no line above. +Code is cited as the change carrying this entry leaves it. + +**The sentence this entry supersedes.** In the amendment headed "`decompile` +refuses a tree past the source depth bound, as a value", the section headed +"What changed" ends: "No name is exported for the result type." From this +change the package's main entry exports that type as `DecompileResult` +(`DecompileResult` in `src/decompile.ts`, re-exported from `src/index.ts` and +listed in `test/export-surface.json`), beside `ParseResult` and +`CompileResult`. Exporting it was ruled by the operator, 2026-10-01. The +sentence stands as a statement about the package before this change. + +### Typespecs + +One type joins the main entry point, and the `decompile` declaration names it: + +```typescript +export type DecompileResult = + | { readonly ok: true; readonly source: string } + | { readonly ok: false; readonly error: ParseError }; + +export declare function decompile(ast: Ast, options?: DecompileOptions): DecompileResult; +``` + +### What is unchanged + +The type is the union that amendment quotes, member for member: `decompile`'s +parameters, its two arms and its refusal are as the amendment states them. A +host that wrote the union out, or derived it from the function, holds the same +type it held. + +Two statements nearby are NOT superseded, and are named so a reader does not +go looking. The note on that amendment's acceptance says the type behind +`decompile` is not exported from the package's entry; it is a reading of +`1ddd46b`, the commit it names, and still holds there. The amendment on the +statement grammar says no name is exported for the result types of +`compileProgramWithPositions` and `compileProgramWithSpans`; it is about those +two results, and this change exports neither. diff --git a/src/decompile.ts b/src/decompile.ts index 2c100b1..f4580d2 100644 --- a/src/decompile.ts +++ b/src/decompile.ts @@ -163,7 +163,7 @@ const SPACING_TEXT = { * refused here exactly when `compile` refuses the same source for its depth, * with the same reason, message, position and span. */ -type DecompileResult = +export type DecompileResult = | { readonly ok: true; readonly source: string } | { readonly ok: false; readonly error: ParseError }; diff --git a/src/index.ts b/src/index.ts index 1537f7c..b4e80ab 100644 --- a/src/index.ts +++ b/src/index.ts @@ -44,7 +44,7 @@ export { compileWithSpans, } from "./compile.js"; export type { UnboundPolicy } from "./context.js"; -export type { Ast, DecompileOptions } from "./decompile.js"; +export type { Ast, DecompileOptions, DecompileResult } from "./decompile.js"; export { decompile } from "./decompile.js"; export { durationToMilliseconds } from "./duration-units.js"; export type { ParseReason, Position, PredicatorError, Reason, Span } from "./errors.js"; diff --git a/test/export-surface.json b/test/export-surface.json index 5148c4a..3627220 100644 --- a/test/export-surface.json +++ b/test/export-surface.json @@ -5,6 +5,7 @@ "CompileWithPositionsResult", "CompileWithSpansResult", "DecompileOptions", + "DecompileResult", "Duration", "DurationParts", "EvaluateOptions",