Merge dev branch into main

.gitattributes

@@ -0,0 +1,2 @@
+# This raw-code fixture intentionally contains tab-indented Scala.
+tests/number-placement/4-longcode.typ whitespace=-space-before-tab

.github/workflows/test.yml

@@ -8,6 +8,23 @@ on:
     branches: [ main ]
 
 jobs:
+  formatting:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Typstyle
+        uses: baptiste0928/cargo-install@v3.0.0
+        with:
+          crate: typstyle
+          version: '0.15.1'
+
+      - name: Check Typst formatting
+        run: >-
+          typstyle --check --line-width 100 --indent-width 2
+          --no-reorder-import-items codly.typ src tests
+
   tests:
     runs-on: ubuntu-latest
     steps:
@@ -17,20 +34,20 @@ jobs:
       - name: Probe runner package cache
         uses: awalsh128/cache-apt-pkgs-action@latest
         with:
-          packages: cargo
+          packages: cargo poppler-utils
           version: 1.0
 
-      - name: Install tytanic from github
+      - name: Install Tytanic
         uses: baptiste0928/cargo-install@v3.0.0
         with:
           crate: tytanic
-          version: '0.2.1'
+          version: '0.4.1'
       - name: Setup typst
         uses: typst-community/setup-typst@v4
         with:
-          version: 'v0.13.1'
+          version: 'v0.15.1'
       - name: Run test suite
-        run: tt run --no-fail-fast --font-path ./docs/fonts
+        run: python3 tests/run.py
       - name: Archive diffs
         uses: actions/upload-artifact@v4
         if: always()

Justfile

@@ -9,25 +9,25 @@ export TYPST_ROOT := root
 default:
 	@just --list --unsorted
 
-# generate manual
-doc *args:
-	typst compile docs/docs.typ docs.pdf --root . --font-path ./docs/fonts --ignore-system-fonts {{ args }}
-
-# watch the manual
-doc-watch *args:
-	typst watch docs/docs.typ docs.pdf --root . --font-path ./docs/fonts --ignore-system-fonts {{ args }}
-
 # generate the codly function signature in codly.typ
 signature:
 	python3 ./scripts/gen-signature.py
 
 # run test suite
 test *args:
-	tt run --no-fail-fast --font-path ./docs/fonts {{ args }}
+	tt run --no-fail-fast --font-path ./fonts {{ args }}
 
 # update test cases
 update *args:
-	tt update --font-path ./docs/fonts {{ args }}
+	tt update --font-path ./fonts {{ args }}
+
+# format Typst library, tests, and documentation sources
+fmt:
+	typstyle --inplace --line-width 100 --indent-width 2 --no-reorder-import-items codly.typ src tests
+
+# verify Typst formatting without changing files
+fmt-check:
+	typstyle --check --line-width 100 --indent-width 2 --no-reorder-import-items codly.typ src tests
 
 # package the library into the specified destination folder
 package target:
@@ -55,4 +55,4 @@ uninstall: (remove "@local")
 uninstall-preview: (remove "@preview")
 
 # run ci suite
-ci: test doc
+ci: fmt-check test

README.md

@@ -104,6 +104,19 @@ Codly offers a wide range of features for referencing code blocks, lines, highli
 
 ![highlight-ref](./assets/highlight-ref.png)
 
+### Querying a code block (development API)
+
+References remain native Typst references and do not require a custom `ref` show rule. For queried information, `codly.info` reads a small metadata record:
+
+```typ
+#import "codly.typ" as codly
+#codly.new(raw("first\nsecond", block: true))<source>
+
+#context [This block has #codly.info(<source>).lines source lines.]
+```
+
+`lines` counts source lines before ranges and skips. `last-number` is the last displayed line number, including offsets, or `none` for an empty block. `offset-from` uses the same record. Pass the label of the code block or its containing figure.
+
 ### Setting an offset
 
 If you wish to add an offset to your code block, but without selecting a subset of lines, you can use the `codly-offset` function:

bench/indent-guides.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Compare indentation guides with the disabled path and an optional old checkout."""
+import argparse
+import json
+from pathlib import Path
+import statistics
+import subprocess
+import tempfile
+import time
+
+ROOT = Path(__file__).resolve().parents[1]
+SOURCES = {
+    "typical": "\n".join(
+        f"fn f{i}() {{\n    if true {{\n        call({i});\n    }}\n}}"
+        for i in range(200)
+    ),
+    "deep": "\n".join("    " * (i % 16) + "call(value);" for i in range(1000)),
+    "blank-lines": "\n".join("root\n    child\n\n        leaf\n\n    child\nroot" for _ in range(140)),
+    "no-indent": "\n".join(f"let value{i} = {i};" for i in range(1000)),
+    "wrapped": "\n".join("    " * (i % 4) + "call(" + "long_argument, " * 12 + ");" for i in range(300)),
+}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--baseline", type=Path, help="An old checkout containing codly.typ")
+    parser.add_argument("--repeats", type=int, default=3)
+    parser.add_argument("--case", choices=SOURCES, action="append", dest="cases")
+    args = parser.parse_args()
+    if args.repeats < 1:
+        parser.error("--repeats must be positive")
+    variants = [("disabled", ROOT, ""), ("monochrome", ROOT, ", indent-guides: true"),
+                ("rainbow-guides", ROOT, ", indent-guides: (rainbow: true)"),
+                ("both", ROOT, ", indent-guides: true, rainbow: true")]
+    if args.baseline:
+        variants.insert(0, ("baseline", args.baseline.resolve(), ""))
+    with tempfile.TemporaryDirectory(prefix="codly-indent-bench-") as directory:
+        temporary = Path(directory)
+        for case in args.cases or SOURCES:
+            paths = {}
+            for name, root, options in variants:
+                path = temporary / f"{name}.typ"
+                path.write_text(
+                    f'#import {json.dumps(str(root / "codly.typ"), ensure_ascii=False)} as codly\n'
+                    '#set page(width: 400pt, height: 600pt, margin: 10pt)\n'
+                    f'#codly.new(raw({json.dumps(SOURCES[case])}, lang: "rs", block: true)'
+                    + options + ")\n"
+                )
+                paths[name] = path
+            times = {name: [] for name in paths}
+            for _ in range(args.repeats):
+                for name, path in paths.items():
+                    start = time.perf_counter()
+                    subprocess.run(
+                        ["typst", "compile", "--root", "/", str(path), str(temporary / "out.pdf")],
+                        check=True, stdout=subprocess.DEVNULL,
+                    )
+                    times[name].append(time.perf_counter() - start)
+            print(json.dumps({
+                "case": case,
+                "median_seconds": {name: round(statistics.median(runs), 3) for name, runs in times.items()},
+                "runs_seconds": {name: [round(t, 3) for t in runs] for name, runs in times.items()},
+            }), flush=True)
+
+
+if __name__ == "__main__":
+    main()

bench/rainbow.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Compare rainbow coloring with the disabled path and an optional old checkout."""
+import argparse
+import json
+from pathlib import Path
+import statistics
+import subprocess
+import tempfile
+import time
+
+ROOT = Path(__file__).resolve().parents[1]
+SOURCES = {
+    "typical": "\n".join(
+        f'fn f{i}() {{\n    let value = {i};\n    println!("value", value);\n}}'
+        for i in range(250)
+    ),
+    "dense": "\n".join(
+        f'fn f{i}() {{ let x = [1, 2]; println!("{{}}", x[0]); }}'
+        for i in range(1000)
+    ),
+    "no-delimiters": "\n".join(f"let value{i} = {i};" for i in range(1000)),
+}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--baseline", type=Path, help="An old checkout containing codly.typ")
+    parser.add_argument("--repeats", type=int, default=3)
+    parser.add_argument("--case", choices=SOURCES, action="append", dest="cases")
+    args = parser.parse_args()
+    if args.repeats < 1:
+        parser.error("--repeats must be positive")
+    variants = [("disabled", ROOT, False), ("enabled", ROOT, True)]
+    if args.baseline:
+        variants.insert(0, ("baseline", args.baseline.resolve(), False))
+    with tempfile.TemporaryDirectory(prefix="codly-rainbow-bench-") as directory:
+        temporary = Path(directory)
+        for case in args.cases or SOURCES:
+            paths = {}
+            for name, root, enabled in variants:
+                path = temporary / f"{name}.typ"
+                path.write_text(
+                    f'#import {json.dumps(str(root / "codly.typ"), ensure_ascii=False)} as codly\n'
+                    '#set page(width: 400pt, height: 600pt, margin: 10pt)\n'
+                    f'#codly.new(raw({json.dumps(SOURCES[case])}, lang: "rs", block: true)'
+                    + (", rainbow: true" if enabled else "") + ")\n"
+                )
+                paths[name] = path
+            times = {name: [] for name in paths}
+            for _ in range(args.repeats):
+                for name, path in paths.items():
+                    start = time.perf_counter()
+                    subprocess.run(
+                        ["typst", "compile", "--root", "/", str(path), str(temporary / "out.pdf")],
+                        check=True, stdout=subprocess.DEVNULL,
+                    )
+                    times[name].append(time.perf_counter() - start)
+            print(json.dumps({
+                "case": case,
+                "median_seconds": {name: round(statistics.median(runs), 3) for name, runs in times.items()},
+                "runs_seconds": {name: [round(t, 3) for t in runs] for name, runs in times.items()},
+            }), flush=True)
+
+
+if __name__ == "__main__":
+    main()

bench/wrap-marker.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Compare soft-wrap markers with the disabled path and an optional old checkout."""
+import argparse
+import json
+from pathlib import Path
+import statistics
+import subprocess
+import tempfile
+import time
+
+ROOT = Path(__file__).resolve().parents[1]
+SOURCES = {
+    "short": "\n".join(f"    call({i});" for i in range(1000)),
+    "wrapped": "\n".join(f"    call({i}, " + "long_argument, " * 12 + ");" for i in range(300)),
+    "unicode": "\n".join("    " + "中文内容" * 24 for _ in range(200)),
+}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--baseline", type=Path, help="An old checkout containing codly.typ")
+    parser.add_argument("--repeats", type=int, default=3)
+    parser.add_argument("--case", choices=SOURCES, action="append", dest="cases")
+    args = parser.parse_args()
+    if args.repeats < 1:
+        parser.error("--repeats must be positive")
+    variants = [("disabled", ROOT, ""),
+                ("marker", ROOT, ", wrap-marker: [↪]"),
+                ("smart-off", ROOT, ", wrap-marker: [↪], smart-indent: false"),
+                ("combined", ROOT, ", wrap-marker: [↪], indent-guides: true, rainbow: true")]
+    if args.baseline:
+        variants.insert(0, ("baseline", args.baseline.resolve(), ""))
+    with tempfile.TemporaryDirectory(prefix="codly-wrap-bench-") as directory:
+        temporary = Path(directory)
+        for case in args.cases or SOURCES:
+            paths = {}
+            for name, root, options in variants:
+                path = temporary / f"{name}.typ"
+                path.write_text(
+                    f'#import {json.dumps(str(root / "codly.typ"), ensure_ascii=False)} as codly\n'
+                    '#set page(width: 400pt, height: 600pt, margin: 10pt)\n'
+                    f'#codly.new(raw({json.dumps(SOURCES[case])}, lang: "rs", block: true)'
+                    + options + ")\n"
+                )
+                paths[name] = path
+            times = {name: [] for name in paths}
+            for _ in range(args.repeats):
+                for name, path in paths.items():
+                    start = time.perf_counter()
+                    subprocess.run(
+                        ["typst", "compile", "--root", "/", str(path), str(temporary / "out.pdf")],
+                        check=True, stdout=subprocess.DEVNULL,
+                    )
+                    times[name].append(time.perf_counter() - start)
+            print(json.dumps({
+                "case": case,
+                "median_seconds": {name: round(statistics.median(runs), 3) for name, runs in times.items()},
+                "runs_seconds": {name: [round(t, 3) for t in runs] for name, runs in times.items()},
+            }), flush=True)
+
+
+if __name__ == "__main__":
+    main()