`,
+ // Underline: 1+3+3 = 7 chars of lead, then column-1, then ^ x length.
+ "\n" + strings.Repeat(" ", 7+2) + `
`,
+ } {
+ if !strings.Contains(html, want) {
+ t.Errorf("rendered report missing %q:\n%s", want, html)
+ }
+ }
+
+ // Context lines are dimmed; the error line is not.
+ if !strings.Contains(html, `
`) {
+ t.Errorf("the error line must not be dimmed:\n%s", html)
+ }
+
+ // The cause section has no location, so exactly two snippets render.
+ if got := strings.Count(html, ``); got != 2 {
+ t.Errorf("got %d snippets, want 2 (cause has no location):\n%s", got, html)
+ }
+}
+
+// Snippet lines are highlighted as one fragment: a template string spanning
+// lines must not reset per line. Guarded by cgo builds only in effect —
+// without a grammar highlightSnippetLines degrades to escaped plain text,
+// and the per-line split alone is still exercised.
+func TestHighlightSnippetLinesSplit(t *testing.T) {
+ lines := highlightSnippetLines([]string{"let a = 1", "let b = 2"})
+ if len(lines) != 2 {
+ t.Fatalf("got %d lines, want 2: %q", len(lines), lines)
+ }
+ for i, l := range lines {
+ if strings.Contains(l, "\n") {
+ t.Errorf("line %d contains a newline: %q", i, l)
+ }
+ }
+ if !strings.Contains(lines[0], "let a = 1") && !strings.Contains(lines[0], "let") {
+ t.Errorf("line 0 lost its text: %q", lines[0])
+ }
+}
diff --git a/docs/go/literate.go b/docs/go/literate.go
index 7d1b914c..8f4e9003 100644
--- a/docs/go/literate.go
+++ b/docs/go/literate.go
@@ -3,8 +3,8 @@ package dangdocs
import (
"bytes"
"context"
- "errors"
"fmt"
+ "regexp"
"strings"
"github.com/vito/booklit"
@@ -20,6 +20,32 @@ import (
type literateSession struct {
typeScope dang.TypeScope
valueScope dang.ValueScope
+
+ // blocks counts the session's evaluated blocks; each parses under the
+ // synthetic filename blockFilename(n), and sources records every block's
+ // text by that name. Error locations carry the defining block's filename,
+ // so a failure in one block can quote a function raised blocks earlier.
+ blocks int
+ sources map[string]string
+}
+
+// blockFilename names the nth block of a session. The wasm replay
+// (cmd/dang-playground) numbers its session entries with the same scheme —
+// a page replay visits the same blocks in the same order — so any location
+// a message spells out matches what the build baked.
+func blockFilename(n int) string {
+ return fmt.Sprintf("snippet-%d", n)
+}
+
+// nextBlock assigns the next block filename and records its source.
+func (s *literateSession) nextBlock(source string) string {
+ s.blocks++
+ name := blockFilename(s.blocks)
+ if s.sources == nil {
+ s.sources = map[string]string{}
+ }
+ s.sources[name] = source
+ return name
}
// literateFencesPartial is the section partial under which \literate-fences
@@ -139,7 +165,7 @@ func (p Plugin) DangLiterateFailure(code booklit.Content) (booklit.Content, erro
return p.literateFailureBlock(code, `\dang-literate-failure block`)
}
-// stageLabels mirrors playground.js's STAGE_LABEL: the baked error line must
+// stageLabels mirrors playground.js's STAGE_LABEL: the baked error header must
// read exactly like the one renderReplOutput shows after a client-side
// replay, label and all.
var stageLabels = map[string]string{
@@ -148,6 +174,17 @@ var stageLabels = map[string]string{
"eval": "Runtime error",
}
+// stripANSI removes ANSI SGR escape sequences from build-time captured
+// output: escape codes have no business in HTML, and warnings printed
+// during evaluation (WarnAtSource) color themselves for a terminal. The
+// wasm module strips its captured output the same way (cmd/dang-playground)
+// so a replay shows exactly what the build baked.
+var ansiSGR = regexp.MustCompile(`\x1b\[[0-9;]*m`)
+
+func stripANSI(s string) string {
+ return ansiSGR.ReplaceAllString(s, "")
+}
+
// literateBlock evaluates and renders one literate snippet; label names the
// originating syntax in build errors.
func (p Plugin) literateBlock(code booklit.Content, label string) (booklit.Content, error) {
@@ -186,13 +223,18 @@ func (p Plugin) literateFailureBlock(code booklit.Content, label string) (bookli
source := strings.TrimRight(code.String(), "\n")
sess := literateSessionFor(p.section)
- stdout, stage, failure := literateFailEval(source, sess)
+ stdout, stage, failure, blockName := literateFailEval(source, sess)
if failure == nil {
return nil, fmt.Errorf("%s in %s: expected the snippet to fail, but it succeeded — use a plain ```dang fence", label, p.section.FilePath())
}
+ report := dang.ErrorReporter{
+ Filename: blockName,
+ Source: source,
+ Sources: sess.sources,
+ }.Report(failure)
partials := booklit.Partials{
- "Error": booklit.String(stageLabels[stage] + ": " + failureMessage(failure)),
+ "Error": renderErrorReport(report, stageLabels[stage]),
}
if stdout != "" {
partials["Stdout"] = booklit.String(stdout)
@@ -206,20 +248,6 @@ func (p Plugin) literateFailureBlock(code booklit.Content, label string) (bookli
}, nil
}
-// failureMessage extracts the bare message from a snippet's failure.
-// SourceError.Error() renders for a terminal — ANSI colors plus a quoted
-// source span — but the snippet already sits right above the baked error,
-// and escape codes have no business in HTML. The same unwrap lives in
-// dangLiterateFailEval (cmd/dang-playground) so a client-side replay shows
-// the identical line.
-func failureMessage(err error) string {
- var srcErr *dang.SourceError
- if errors.As(err, &srcErr) {
- return srcErr.Inner.Error()
- }
- return err.Error()
-}
-
// literateFailEval runs source the way literateEval does, but against
// throwaway forks of the session's scopes: a cloned type scope (declarations
// land in the discarded child layer) and a sealed child value scope (even
@@ -227,16 +255,21 @@ func failureMessage(err error) string {
// failing block's partial state is unknowable, so it contributes nothing to
// the page's chain — the same isolation dangLiterateFailEval
// (cmd/dang-playground) applies when the page is replayed client-side. It
-// returns the captured output plus the failing stage ("parse" | "type" |
-// "eval") and error; a nil error means the snippet unexpectedly succeeded.
-func literateFailEval(source string, sess *literateSession) (string, string, error) {
- parsed, err := dang.ParseWithRecovery("literate", []byte(source))
+// returns the captured output, the failing stage ("parse" | "type" |
+// "eval") and error, and the block's assigned filename; a nil error means
+// the snippet unexpectedly succeeded.
+func literateFailEval(source string, sess *literateSession) (string, string, error, string) {
+ // The block still takes its place in the session's numbering — the wasm
+ // replay counts every block of the chain the same way.
+ name := sess.nextBlock(source)
+
+ parsed, err := dang.ParseWithRecovery(name, []byte(source), dang.GlobalStore("filePath", name))
if err != nil {
- return "", "parse", err
+ return "", "parse", err, name
}
file, ok := parsed.(*dang.FileBlock)
if !ok {
- return "", "parse", fmt.Errorf("unexpected parse result")
+ return "", "parse", fmt.Errorf("unexpected parse result"), name
}
forms := file.Forms
@@ -245,19 +278,22 @@ func literateFailEval(source string, sess *literateSession) (string, string, err
fresh := hm.NewSimpleFresher()
if _, err := dang.InferFormsWithPhases(context.Background(), forms, typeScope, fresh); err != nil {
- return "", "type", err
+ return "", "type", err, name
}
var out bytes.Buffer
ctx := ioctx.StdoutToContext(context.Background(), &out)
ctx = ioctx.StderrToContext(ctx, &out)
+ // Runtime faults that aren't raises only carry a location when an
+ // EvalContext supplies one, the same wiring RunFile does.
+ ctx = dang.WithEvalContext(ctx, dang.NewEvalContext(name, source))
for _, node := range forms {
if _, err := dang.EvalNode(ctx, valueScope, node); err != nil {
- return strings.TrimRight(out.String(), "\n"), "eval", err
+ return strings.TrimRight(stripANSI(out.String()), "\n"), "eval", err, name
}
}
- return strings.TrimRight(out.String(), "\n"), "", nil
+ return strings.TrimRight(stripANSI(out.String()), "\n"), "", nil, name
}
// literateEval parses, type-checks, and evaluates source against the
@@ -278,7 +314,9 @@ func literateEval(source string, sess *literateSession) (string, string, error)
// bundled in-process schema. The base context backs both phases so the import's
// schema-module identity is shared between them.
func literateEvalCtx(base context.Context, source string, sess *literateSession) (string, string, error) {
- parsed, err := dang.ParseWithRecovery("literate", []byte(source))
+ name := sess.nextBlock(source)
+
+ parsed, err := dang.ParseWithRecovery(name, []byte(source), dang.GlobalStore("filePath", name))
if err != nil {
return "", "", err
}
@@ -296,6 +334,7 @@ func literateEvalCtx(base context.Context, source string, sess *literateSession)
var out bytes.Buffer
ctx := ioctx.StdoutToContext(base, &out)
ctx = ioctx.StderrToContext(ctx, &out)
+ ctx = dang.WithEvalContext(ctx, dang.NewEvalContext(name, source))
var last dang.Node
var lastVal dang.Value
@@ -312,5 +351,5 @@ func literateEvalCtx(base context.Context, source string, sess *literateSession)
if lastVal != nil && (last == nil || len(last.DeclaredSymbols()) == 0) {
value = dang.Repr(lastVal)
}
- return strings.TrimRight(out.String(), "\n"), value, nil
+ return strings.TrimRight(stripANSI(out.String()), "\n"), value, nil
}
diff --git a/docs/go/literate_test.go b/docs/go/literate_test.go
index 6c1089d1..8b8632dc 100644
--- a/docs/go/literate_test.go
+++ b/docs/go/literate_test.go
@@ -149,7 +149,10 @@ func TestCodeBlockFailureRouting(t *testing.T) {
t.Fatalf("seeding session: %v", err)
}
- // The failure block sees the session's state (x) and bakes its error.
+ // The failure block sees the session's state (x) and bakes its error as a
+ // structured report: a header labeled like playground.js's STAGE_LABEL
+ // (errorReportHtml must render the same DOM on replay), then the annotated
+ // source snippet with gutter and underline.
failed, err := render("dang-failure", "x.toUpper")
if err != nil {
t.Fatalf("dang-failure fence: %v", err)
@@ -158,8 +161,19 @@ func TestCodeBlockFailureRouting(t *testing.T) {
if errPartial == nil {
t.Fatal("dang-failure fence baked no Error partial")
}
- if got := errPartial.String(); !strings.HasPrefix(got, "Type error: ") {
- t.Errorf("baked error %q, want a %q prefix matching playground.js's STAGE_LABEL", got, "Type error: ")
+ baked := errPartial.String()
+ if want := `Type error:`; !strings.Contains(baked, want) {
+ t.Errorf("baked error %q missing header label %q", baked, want)
+ }
+ if want := ` --> 1:`; !strings.Contains(baked, want) {
+ t.Errorf("baked error %q missing location arrow %q", baked, want)
+ }
+ if !strings.Contains(baked, `dang-error-underline`) || !strings.Contains(baked, "^") {
+ t.Errorf("baked error %q missing the ^^^ underline", baked)
+ }
+ // The failing line is quoted (split across tok-* spans, so compare text).
+ if text := valueText(errPartial); !strings.Contains(text, "x.toUpper") {
+ t.Errorf("baked error text %q does not quote the failing source line", text)
}
if failed.Partials["Value"] != nil {
t.Errorf("dang-failure fence baked a Value: %v", failed.Partials["Value"])
@@ -197,6 +211,40 @@ func TestCodeBlockFailureRouting(t *testing.T) {
}
}
+// A failure whose raise site lives in an earlier fence quotes that fence's
+// source: blocks parse under per-block filenames and the session records
+// each block's text, so cross-fence locations resolve to the right snippet
+// instead of misquoting the failing fence (or dangling with no snippet).
+func TestFailureQuotesEarlierFence(t *testing.T) {
+ root := &booklit.Section{Path: "cross-fence-test.md"}
+ lit := &booklit.Section{Parent: root}
+ Plugin{section: lit}.LiterateFences()
+
+ render := func(language, source string) (booklit.Styled, error) {
+ t.Helper()
+ content, err := Plugin{section: lit}.CodeBlock(language, booklit.Preformatted{booklit.String(source)})
+ if err != nil {
+ return booklit.Styled{}, err
+ }
+ return content.(booklit.Styled), nil
+ }
+
+ if _, err := render("dang", `boom: String! { raise "kapow" }`); err != nil {
+ t.Fatalf("defining fence: %v", err)
+ }
+ failed, err := render("dang-failure", "boom")
+ if err != nil {
+ t.Fatalf("dang-failure fence: %v", err)
+ }
+ text := valueText(failed.Partials["Error"])
+ if !strings.Contains(text, "kapow") {
+ t.Fatalf("baked error %q missing the raised message", text)
+ }
+ if !strings.Contains(text, `raise "kapow"`) {
+ t.Errorf("baked error %q does not quote the raise site from the earlier fence", text)
+ }
+}
+
// Booklit's dev server re-loads the whole book on every page request,
// concurrently across requests, and Dang scopes are not safe for concurrent
// use — so each load must get its own sessions. Each goroutine here simulates
diff --git a/docs/go/render.go b/docs/go/render.go
index fb86b05a..b2bdd79c 100644
--- a/docs/go/render.go
+++ b/docs/go/render.go
@@ -164,6 +164,13 @@ func renderCode(section *booklit.Section, language, source string, links []linkS
// inherit the result line's color (.dang-playground-result, green). Without a
// grammar (or cgo) it degrades to escaped plain text.
func highlightResult(value string) booklit.Content {
+ return booklit.Styled{Style: "raw-html", Content: booklit.String(highlightResultHTML(value))}
+}
+
+// highlightResultHTML is highlightResult's raw HTML form: escaped text in
+// bare tok-* spans. It also backs the quoted source lines and field values
+// in baked error reports (errorreport.go).
+func highlightResultHTML(value string) string {
classes := classifyCode("dang", value)
classAt := func(i int) string {
if classes == nil {
@@ -187,5 +194,5 @@ func highlightResult(value string) booklit.Content {
}
i = j
}
- return booklit.Styled{Style: "raw-html", Content: booklit.String(raw.String())}
+ return raw.String()
}
diff --git a/docs/html/page.tmpl b/docs/html/page.tmpl
index 3e51b457..face64b1 100644
--- a/docs/html/page.tmpl
+++ b/docs/html/page.tmpl
@@ -172,6 +172,23 @@ pre code{display:block}
.dang-playground-stdout{color:var(--fg);margin-bottom:.3rem;white-space:pre-wrap}
.dang-playground-result{color:var(--green);white-space:pre-wrap}
.dang-playground-error{color:var(--pink);white-space:pre-wrap}
+/* Structured error reports: the annotated source snippet the CLI prints,
+ as HTML (docs/go/errorreport.go bakes it; playground.js re-renders the
+ same DOM on replay). The header keeps the pink error color; the quoted
+ source goes back to full syntax coloring, with context lines dimmed the
+ way the terminal dims them. */
+.dang-error-section+.dang-error-section{margin-top:.6rem}
+.dang-error-label{font-weight:600}
+.dang-error-field{color:var(--fg);opacity:.75;white-space:pre-wrap}
+.dang-error-snippet{
+ color:var(--fg);font-size:inherit;line-height:var(--code-line-height);
+ margin:.2rem 0 0;white-space:pre;overflow-x:auto;
+}
+.dang-error-arrow{color:var(--link);opacity:.8}
+.dang-error-gutter{color:var(--fg2);opacity:.7}
+.dang-error-gutter.is-hl{color:var(--link);opacity:1;font-weight:600}
+.dang-error-dim{opacity:.55}
+.dang-error-underline{color:var(--pink);font-weight:700}
.dang-playground-fallback{
background:var(--code-bg);color:var(--base05);font-family:'JetBrains Mono',monospace;
font-size:.8rem;line-height:var(--code-line-height);padding:1rem 1.25rem;margin:0;white-space:pre;overflow-x:auto;
@@ -285,6 +302,12 @@ pre code{display:block}
.dang-carousel .dang-playground textarea {
font-size: 16px;
}
+/* …except the quoted snippet inside an error report, which stays at the
+ output panel's size (an edited slide that errors renders one there). */
+.dang-carousel .dang-literate pre.dang-error-snippet,
+.dang-carousel .dang-playground pre.dang-error-snippet {
+ font-size: inherit;
+}
/* The single bar: a horizontally-clipped track of feature tabs. carousel.js
slides the track so the active tab sits at the left as the header. */
.dang-carousel-tabs{
diff --git a/docs/js/playground.js b/docs/js/playground.js
index 97620dc7..b2f14844 100644
--- a/docs/js/playground.js
+++ b/docs/js/playground.js
@@ -161,7 +161,10 @@
} catch (e) {
if (window.console) console.warn("dang playground: injection query unavailable:", e);
}
- ts = { parser: parser, query: query, injQuery: injQuery, mod: mod };
+ // retryWrap mirrors highlight.go's signaturePrefix/Suffix: fragments
+ // that don't parse bare (declaration signatures, error-snippet windows)
+ // retry inside a synthetic interface body.
+ ts = { parser: parser, query: query, injQuery: injQuery, mod: mod, retryWrap: ["interface _ {\n", "\n}"] };
return ts;
})().catch(function (err) {
// Highlighting is best-effort; fall back to plain text on failure.
@@ -256,32 +259,72 @@
return null;
}
+ // captureSpans parses src inside optional affixes and returns highlight
+ // spans translated back to src's coordinates, plus the number of characters
+ // covered by ERROR/MISSING nodes within src — the same measure
+ // docs/go/highlight.go's capture uses to decide the wrap retry.
+ function captureSpans(langObj, src, prefix, suffix) {
+ var tree = langObj.parser.parse(prefix + src + suffix);
+ var errChars = errorChars(tree.rootNode, prefix.length, prefix.length + src.length);
+ var caps = langObj.query.captures(tree.rootNode);
+ var spans = [];
+ for (var i = 0; i < caps.length; i++) {
+ var c = caps[i];
+ var s = c.node.startIndex - prefix.length, e = c.node.endIndex - prefix.length;
+ if (e <= 0 || s >= src.length) continue;
+ spans.push({
+ start: Math.max(s, 0),
+ end: Math.min(e, src.length),
+ name: c.name,
+ });
+ }
+ tree.delete();
+ return { spans: spans, errChars: errChars };
+ }
+
+ // errorChars sums the characters of ERROR/MISSING nodes intersecting
+ // [start, end); mirrors errorBytes in docs/go/highlight.go.
+ function errorChars(node, start, end) {
+ if (node.isError || node.isMissing) {
+ var s = node.startIndex, e = node.endIndex;
+ if (e < start || s > end) return 0;
+ // A zero-width MISSING node still poisons the parse it appears in.
+ return Math.max(Math.min(e, end) - Math.max(s, start), 1);
+ }
+ var total = 0;
+ for (var i = 0; i < node.childCount; i++) {
+ total += errorChars(node.child(i), start, end);
+ }
+ return total;
+ }
+
// classify(langObj, src) -> a token class per character (null where unstyled),
// using langObj's parser + highlight query. langObj.wrap, when set, is a
// synthetic prefix that makes a bare fragment parse (e.g. Go's "package p\n");
- // its captures are shifted back so they line up with src.
+ // its captures are shifted back so they line up with src. langObj.retryWrap
+ // ([prefix, suffix]) retries a source that didn't fully parse inside the
+ // synthetic wrapper and keeps whichever parse recovered more — mirroring
+ // classify in docs/go/highlight.go (the two must stay in lockstep), so
+ // fragments like error-snippet windows highlight the same here as baked.
function classify(langObj, src) {
var names = new Array(src.length).fill(null);
if (!langObj || !langObj.parser) return names;
- var wrap = langObj.wrap || "";
- var tree = langObj.parser.parse(wrap + src);
- var caps = langObj.query.captures(tree.rootNode);
+ var res = captureSpans(langObj, src, langObj.wrap || "", "");
+ if (res.errChars > 0 && langObj.retryWrap) {
+ var wrapped = captureSpans(langObj, src, langObj.retryWrap[0], langObj.retryWrap[1]);
+ if (wrapped.errChars < res.errChars) res = wrapped;
+ }
// Wider captures first, narrower (and later) override.
- caps.sort(function (a, b) {
- var d = a.node.startIndex - b.node.startIndex;
+ res.spans.sort(function (a, b) {
+ var d = a.start - b.start;
if (d) return d;
- return (b.node.endIndex - b.node.startIndex) - (a.node.endIndex - a.node.startIndex);
+ return (b.end - b.start) - (a.end - a.start);
});
- for (var i = 0; i < caps.length; i++) {
- var c = caps[i], cls = tokenClass(c.name);
+ for (var i = 0; i < res.spans.length; i++) {
+ var sp = res.spans[i], cls = tokenClass(sp.name);
if (!cls) continue; // unmapped captures (e.g. @error) stay unstyled
- var s = c.node.startIndex - wrap.length, e = c.node.endIndex - wrap.length;
- if (e <= 0 || s >= src.length) continue;
- if (s < 0) s = 0;
- if (e > src.length) e = src.length;
- for (var j = s; j < e; j++) names[j] = cls;
+ for (var j = sp.start; j < sp.end; j++) names[j] = cls;
}
- tree.delete();
return names;
}
@@ -335,6 +378,35 @@
return out;
}
+ // Highlight an error snippet's quoted source lines as one Dang fragment
+ // (so multi-line tokens keep their context), returning per-line HTML.
+ // Mirrors highlightSnippetLines in docs/go/errorreport.go (the two must
+ // stay in lockstep); without tree-sitter the lines come back escaped
+ // but unstyled.
+ function highlightLinesHtml(lines) {
+ var joined = lines.join("\n");
+ var names;
+ if (ts) {
+ names = classify(ts, joined);
+ applyInjections(joined, names);
+ } else {
+ names = new Array(joined.length).fill(null);
+ }
+ var out = [], offset = 0;
+ for (var li = 0; li < lines.length; li++) {
+ var line = lines[li], html = "", k = offset;
+ while (k < offset + line.length) {
+ var cls = names[k], start = k;
+ while (k < offset + line.length && names[k] === cls) k++;
+ var chunk = escapeHtml(joined.slice(start, k));
+ html += cls ? '' + chunk + "" : chunk;
+ }
+ out.push(html);
+ offset += line.length + 1; // the joining newline
+ }
+ return out;
+ }
+
// ── editor autosizing ─────────────────────────────────────────────────────
//
// Every editor textarea autosizes to its content by measuring scrollHeight.
@@ -360,6 +432,80 @@
var STAGE_LABEL = { parse: "Parse error", type: "Type error", eval: "Runtime error", auth: "GitHub error" };
+ // Append a failed result's error to the output container. A structured
+ // report (res.report, from the wasm module) renders as annotated source
+ // sections — the DOM must match what the docs build bakes via
+ // renderErrorReport in docs/go/errorreport.go (the two must stay in
+ // lockstep) — with a plain label + message line as the fallback (e.g. the
+ // synthesized "expected this block to fail" error, or GitHub auth
+ // failures).
+ function renderError(out, res) {
+ out.classList.add("is-error");
+ var err = document.createElement("div");
+ err.className = "dang-playground-error";
+ var label = STAGE_LABEL[res.stage] || "Error";
+ var sections = res.report && res.report.sections;
+ if (sections && sections.length) {
+ err.innerHTML = errorReportHtml(sections, label);
+ } else {
+ err.textContent = label + ": " + res.error;
+ }
+ out.appendChild(err);
+ }
+
+ function errorReportHtml(sections, stageLabel) {
+ var html = "";
+ for (var i = 0; i < sections.length; i++) {
+ var sec = sections[i];
+ var label = stageLabel + ":";
+ if (sec.role === "cause") label = "caused by:";
+ else if (sec.role === "sibling") label = "also failed:";
+ html += '';
+ html += '
' +
+ escapeHtml(label) + " " + escapeHtml(sec.message) + "
";
+ var fields = sec.fields || [];
+ for (var f = 0; f < fields.length; f++) {
+ html += '
' + escapeHtml(fields[f].name) + ": " +
+ highlightHtml(fields[f].value) + "
";
+ }
+ if (sec.location) {
+ html += '
' +
+ errorSnippetHtml(sec.location, sec.snippet) + "
";
+ }
+ html += "