@shd101wyy/yo 0.1.13 → 0.1.15

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shd101wyy/yo",
   "displayName": "Yo",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "main": "./out/cjs/index.cjs",
   "module": "./out/esm/index.mjs",
   "types": "./out/types/src/index.d.ts",
@@ -48,6 +48,8 @@
   },
   "dependencies": {
     "markdown_yo": "0.0.4",
+    "vscode-languageserver": "^9.0.1",
+    "vscode-languageserver-textdocument": "^1.0.12",
     "yargs": "^17.7.2"
   },
   "devDependencies": {

package/scripts/build-site.ts

@@ -20,18 +20,19 @@ import * as fs from "fs";
 import * as path from "path";
 import { createRenderer } from "markdown_yo";
 import type { MarkdownRenderer } from "markdown_yo";
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
 
 const ROOT = path.resolve(import.meta.dir, "..");
 const GITHUB_REPO = "https://github.com/shd101wyy/Yo";
 
 // Detect the latest release tag for stable links.
 // Falls back to "main" if no tags exist or git fails.
-function getLatestTag(): string {
+export function getLatestTag(rootDir: string = ROOT): string {
   try {
-    const result = execSync("git describe --tags --abbrev=0 2>/dev/null", {
-      cwd: ROOT,
+    const result = execFileSync("git", ["describe", "--tags", "--abbrev=0"], {
+      cwd: rootDir,
       encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
       timeout: 5000,
     }).trim();
     return result || "main";
@@ -43,6 +44,16 @@ function getLatestTag(): string {
 const GITHUB_REF = getLatestTag();
 const GITHUB_BLOB = `${GITHUB_REPO}/blob/${GITHUB_REF}`;
 
+export function getStdDocCommand(rootDir: string = ROOT): {
+  command: string;
+  args: string[];
+} {
+  return {
+    command: "node",
+    args: [path.join(rootDir, "out", "cjs", "yo-cli.cjs"), "doc", "std/"],
+  };
+}
+
 // ── Parse args ───────────────────────────────────────────────────────
 
 let outputDir = path.join(ROOT, "site");
@@ -75,6 +86,42 @@ function escapeHtml(s: string): string {
  * - `https://shd101wyy.github.io/Yo/` → `std/index.html` (relative, same site)
  * - `#anchor` links → kept as-is
  */
+/**
+ * Generate a GitHub-compatible slug from heading text.
+ * - Strip HTML tags
+ * - Lowercase
+ * - Replace spaces with hyphens
+ * - Remove non-alphanumeric characters (except hyphens)
+ */
+function slugify(text: string): string {
+  return text
+    .replace(/<[^>]+>/g, "") // strip HTML tags
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+/**
+ * Add `id` attributes to heading elements so that #anchor links work.
+ * Handles duplicate slugs by appending `-1`, `-2`, etc.
+ */
+function injectHeadingIds(html: string): string {
+  const slugCounts = new Map<string, number>();
+  return html.replace(
+    /<(h[1-6])>([\s\S]*?)<\/\1>/gi,
+    (_match: string, tag: string, content: string) => {
+      let slug = slugify(content);
+      const count = slugCounts.get(slug) ?? 0;
+      slugCounts.set(slug, count + 1);
+      if (count > 0) slug = `${slug}-${count}`;
+      return `<${tag} id="${slug}">${content}</${tag}>`;
+    }
+  );
+}
+
 function rewriteReadmeLinks(html: string): string {
   // Rewrite the generated docs link to relative std/ path (same site)
   html = html.replace(
@@ -363,7 +410,7 @@ function injectHomeLinks(stdDir: string): void {
 
 // ── Main ─────────────────────────────────────────────────────────────
 
-async function main(): Promise<void> {
+export async function main(): Promise<void> {
   console.log("Building documentation site...");
   console.log(`  Output: ${outputDir}`);
 
@@ -383,6 +430,7 @@ async function main(): Promise<void> {
   });
 
   let readmeHtml = md.render(readmeSrc);
+  readmeHtml = injectHeadingIds(readmeHtml);
   readmeHtml = rewriteReadmeLinks(readmeHtml);
 
   const css = generateHomepageCSS();
@@ -412,12 +460,16 @@ async function main(): Promise<void> {
   const stdOutputDir = path.join(outputDir, "std");
 
   try {
-    const yoCli = path.join(ROOT, "yo-cli");
-    execSync(`${yoCli} doc std/ --output "${stdOutputDir}"`, {
-      cwd: ROOT,
-      stdio: ["pipe", "pipe", "inherit"],
-      timeout: 120_000,
-    });
+    const stdDocCommand = getStdDocCommand();
+    execFileSync(
+      stdDocCommand.command,
+      [...stdDocCommand.args, "--output", stdOutputDir],
+      {
+        cwd: ROOT,
+        stdio: ["ignore", "inherit", "inherit"],
+        timeout: 600_000,
+      }
+    );
     console.log("  ✓ Standard library docs generated");
   } catch (err) {
     console.error(
@@ -455,7 +507,9 @@ function getTotalSize(dir: string): number {
   return Math.round(total / 1024);
 }
 
-main().catch((err) => {
-  console.error("Fatal error:", err);
-  process.exit(1);
-});
+if (import.meta.main) {
+  main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+  });
+}

package/scripts/check-liburing.js

@@ -9,9 +9,9 @@ const fs = require("fs");
 function checkLiburing() {
   const platform = os.platform();
 
-  // Only check on Linux
+  // Only check on Linux. Other platforms don't use io_uring, so keep postinstall
+  // quiet instead of printing a Linux-specific note.
   if (platform !== "linux") {
-    console.log("ℹ️  Async I/O with io_uring is only supported on Linux.");
     return;
   }
 

package/std/build.yo

@@ -18,13 +18,17 @@
 
 /// Optimization level for compiled artifacts.
 Optimize :: enum(
-  /// No optimizations, full debug info.
+  /// No optimizations, full debug info.  
+  /// Compiler Flags: `-O0 -g`
   Debug,
-  /// Optimized with safety checks.
+  /// Optimized with safety checks.  
+  /// Compiler Flags: `-O2 -g`
   ReleaseSafe,
-  /// Maximum speed optimizations.
+  /// Maximum speed optimizations.  
+  /// Compiler Flags: `-O3`
   ReleaseFast,
-  /// Optimize for binary size.
+  /// Optimize for binary size.  
+  /// Compiler Flags `-O2`
   ReleaseSmall
 );
 export Optimize;

package/std/encoding/base64.yo

@@ -1,10 +1,13 @@
 //! Base64 encoding and decoding (RFC 4648) with standard and URL-safe variants.
 //!
-//! Example:
-//!   { base64_encode, base64_decode } :: import "std/encoding/base64";
+//! # Example
 //!
-//!   s := base64_encode(data);
-//!   b := base64_decode(s.to_str()).unwrap();
+//! ```rust
+//! { base64_encode, base64_decode } :: import "std/encoding/base64";
+//!
+//! s := base64_encode(data);
+//! b := base64_decode(s.to_str()).unwrap();
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";

package/std/encoding/hex.yo

@@ -2,11 +2,14 @@
 //!
 //! Converts between raw bytes (`ArrayList(u8)`) and hex strings.
 //!
-//! Example:
-//!   { hex_encode, hex_decode } :: import "std/encoding/hex";
+//! # Example
 //!
-//!   s := hex_encode(data);         // "deadbeef"
-//!   b := hex_decode("deadbeef");
+//! ```rust
+//! { hex_encode, hex_decode } :: import "std/encoding/hex";
+//!
+//! s := hex_encode(data);         // "deadbeef"
+//! b := hex_decode("deadbeef");
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";

package/std/encoding/html.yo

@@ -3,11 +3,14 @@
 //! Decodes named (&), decimal (&), and hex (&) HTML character references.
 //! Uses Legacy mode — entities without trailing semicolon are also decoded.
 //!
-//! Example:
-//!   { decode_html } :: import "std/encoding/html";
+//! # Example
 //!
-//!   result := decode_html(`& < & &`);
-//!   assert((result == `& < & &`), "decoded entities");
+//! ```rust
+//! { decode_html } :: import "std/encoding/html";
+//!
+//! result := decode_html(`&amp; &lt; &#38; &#x26;`);
+//! assert((result == `& < & &`), "decoded entities");
+//! ```
 
 open import "../string";
 { HashMap } :: import "../collections/hash_map";

package/std/encoding/json.yo

@@ -2,13 +2,16 @@
 //!
 //! Provides a dynamically-typed JSON value tree.
 //!
-//! Example:
-//!   { json_parse, json_stringify, JsonValue } :: import "std/encoding/json";
-//!   { Exception } :: import "std/error";
+//! # Example
 //!
-//!   given(exn) := Exception(throw : ((err) -> { escape (); }));
-//!   v := json_parse(`{"x": 1}`);
-//!   println(json_stringify(v));
+//! ```rust
+//! { json_parse, json_stringify, JsonValue } :: import "std/encoding/json";
+//! { Exception } :: import "std/error";
+//!
+//! given(exn) := Exception(throw : ((err) -> { escape (); }));
+//! v := json_parse(`{"x": 1}`);
+//! println(json_stringify(v));
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";

package/std/encoding/punycode.yo

@@ -2,13 +2,16 @@
 //!
 //! Provides punycode encoding/decoding and IDN hostname conversion.
 //!
-//! Example:
-//!   { punycode_decode, punycode_encode, to_unicode, to_ascii } :: import "std/encoding/punycode";
+//! # Example
 //!
-//!   encoded := punycode_encode(`München`);
-//!   decoded := punycode_decode(encoded);
-//!   ascii_domain := to_ascii(`münchen.de`);  // "xn--mnchen-3ya.de"
-//!   unicode_domain := to_unicode(ascii_domain);  // "münchen.de"
+//! ```rust
+//! { punycode_decode, punycode_encode, to_unicode, to_ascii } :: import "std/encoding/punycode";
+//!
+//! encoded := punycode_encode(`München`);
+//! decoded := punycode_decode(encoded);
+//! ascii_domain := to_ascii(`münchen.de`);  // "xn--mnchen-3ya.de"
+//! unicode_domain := to_unicode(ascii_domain);  // "münchen.de"
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";

package/std/encoding/toml.yo

@@ -3,10 +3,13 @@
 //! Parses a subset of TOML into a `TomlValue` tree.
 //! Supports: strings, integers, booleans, table sections, comments.
 //!
-//! Example:
-//!   { toml_parse, TomlValue } :: import "std/encoding/toml";
-//!   // Or via the encoding index:
-//!   { toml_parse, TomlValue } :: import "std/encoding";
+//! # Example
+//!
+//! ```rust
+//! { toml_parse, TomlValue } :: import "std/encoding/toml";
+//! // Or via the encoding index:
+//! { toml_parse, TomlValue } :: import "std/encoding";
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";

package/std/encoding/utf16.yo

@@ -2,11 +2,14 @@
 //!
 //! Converts between Yo's UTF-8 `str` and UTF-16 code units (`ArrayList(u16)`).
 //!
-//! Example:
-//!   { utf8_to_utf16, utf16_to_utf8 } :: import "std/encoding/utf16";
+//! # Example
 //!
-//!   words := utf8_to_utf16("hello");
-//!   s := utf16_to_utf8(words);
+//! ```rust
+//! { utf8_to_utf16, utf16_to_utf8 } :: import "std/encoding/utf16";
+//!
+//! words := utf8_to_utf16("hello");
+//! s := utf16_to_utf8(words);
+//! ```
 
 open import "../string";
 { ArrayList } :: import "../collections/array_list";

package/std/fs/dir.yo

@@ -2,21 +2,24 @@
 //!
 //! Wraps low-level `std/sys/dir` with typed APIs using the `Exception` effect.
 //!
-//! Example:
-//!   { create_dir, remove_dir, read_dir } :: import "std/fs/dir";
-//!   { Path } :: import "std/path";
+//! # Example
 //!
-//!   main :: (fn(using(io : IO)) -> unit)({
-//!     given(exn) : Exception = {
-//!       throw : (fn(forall(T : Type), error: AnyError) -> T)(
-//!         { println(error.to_string()); exit(i32(1)); }
-//!       )
-//!     };
+//! ```rust
+//! { create_dir, remove_dir, read_dir } :: import "std/fs/dir";
+//! { Path } :: import "std/path";
 //!
-//!     io.await(create_dir(Path.new(`/tmp/yo_test`)));
-//!     entries := io.await(read_dir(Path.new(`/tmp/yo_test`)));
-//!     io.await(remove_dir(Path.new(`/tmp/yo_test`)));
-//!   });
+//! main :: (fn(using(io : IO)) -> unit)({
+//!   given(exn) : Exception = {
+//!     throw : (fn(forall(T : Type), error: AnyError) -> T)(
+//!       { println(error.to_string()); exit(i32(1)); }
+//!     )
+//!   };
+//!
+//!   io.await(create_dir(Path.new(`/tmp/yo_test`)));
+//!   entries := io.await(read_dir(Path.new(`/tmp/yo_test`)));
+//!   io.await(remove_dir(Path.new(`/tmp/yo_test`)));
+//! });
+//! ```
 
 { GlobalAllocator } :: import "../allocator";
 { malloc, free } :: GlobalAllocator;

package/std/fs/file.yo

@@ -3,26 +3,29 @@
 //! Wraps a file descriptor with typed async I/O operations.
 //! Uses the `Exception` effect for error handling.
 //!
-//! Example:
-//!   { File, read_string, write_file, OpenMode } :: import "std/fs/file";
+//! # Example
 //!
-//!   main :: (fn(using(io : IO)) -> unit)({
-//!     given(exn) := Exception(
-//!       throw : (fn(forall(T : Type), error: AnyError) -> T)(
-//!         { println(error); panic("Exception found."); }
-//!       )
-//!     );
+//! ```rust
+//! { File, read_string, write_file, OpenMode } :: import "std/fs/file";
 //!
-//!     // Write a file
-//!     io.await(write_file(Path.new(`test.txt`), `hello world`));
+//! main :: (fn(using(io : IO)) -> unit)({
+//!   given(exn) := Exception(
+//!     throw : (fn(forall(T : Type), error: AnyError) -> T)(
+//!       { println(error); panic("Exception found."); }
+//!     )
+//!   );
 //!
-//!     // Read it back
-//!     content := io.await(read_string(Path.new(`test.txt`)));
-//!     println(content);
+//!   // Write a file
+//!   io.await(write_file(Path.new(`test.txt`), `hello world`));
 //!
-//!     // Open with OpenMode
-//!     f := io.await(File.open(Path.new(`test.txt`), .Read));
-//!   });
+//!   // Read it back
+//!   content := io.await(read_string(Path.new(`test.txt`)));
+//!   println(content);
+//!
+//!   // Open with OpenMode
+//!   f := io.await(File.open(Path.new(`test.txt`), .Read));
+//! });
+//! ```
 
 { GlobalAllocator } :: import "../allocator";
 { malloc, free } :: GlobalAllocator;

package/std/http/client.yo

@@ -245,9 +245,12 @@ _read_http_response :: (fn(stream: TcpStream, using(io : IO, exn : Exception)) -
 
 /// Perform an HTTP request with custom options.
 ///
-/// Example:
-///   opts := FetchOptions.new().with_method(.POST).with_body(`{"key": "value"}`);
-///   resp := io.await(fetch_with(`http://example.com/api`, opts, using(io)));
+/// # Example
+///
+/// ```rust
+/// opts := FetchOptions.new().with_method(.POST).with_body(`{"key": "value"}`);
+/// resp := io.await(fetch_with(`http://example.com/api`, opts, using(io)));
+/// ```
 fetch_with :: (fn(url_str: String, opts: FetchOptions, using(io : IO)) ->
   Impl(Future(HttpResponse, IO, Exception))
 )(
@@ -359,9 +362,12 @@ export fetch_with;
 /// Perform an HTTP GET request to the given URL string.
 /// Returns the `HttpResponse` on success.
 ///
-/// Example:
-///   resp := io.await(fetch(`http://example.com`, using(io)));
-///   cond(resp.is_ok() => println(resp.body), true => println(`Error`));
+/// # Example
+///
+/// ```rust
+/// resp := io.await(fetch(`http://example.com`, using(io)));
+/// cond(resp.is_ok() => println(resp.body), true => println(`Error`));
+/// ```
 fetch :: (fn(url_str: String, using(io : IO)) ->
   Impl(Future(HttpResponse, IO, Exception))
 )(