@shd101wyy/yo 0.1.16 → 0.1.18

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shd101wyy/yo",
   "displayName": "Yo",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "main": "./out/cjs/index.cjs",
   "module": "./out/esm/index.mjs",
   "types": "./out/types/src/index.d.ts",
@@ -13,7 +13,8 @@
     "out",
     "scripts",
     "vendor",
-    "std"
+    "std",
+    ".github/skills"
   ],
   "repository": "https://github.com/shd101wyy/yo",
   "author": "Yiyi Wang <shd101wyy@gmail.com>",

package/scripts/build-site.ts

@@ -25,25 +25,26 @@ 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.
-export function getLatestTag(rootDir: string = ROOT): string {
+// Detect the exact tag on HEAD for stable GitHub blob links.
+// Falls back to "develop" if HEAD has no exact tag or git fails.
+export function getExactTagOrDevelop(rootDir: string = ROOT): string {
   try {
-    const result = execFileSync("git", ["describe", "--tags", "--abbrev=0"], {
-      cwd: rootDir,
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 5000,
-    }).trim();
-    return result || "main";
+    const result = execFileSync(
+      "git",
+      ["describe", "--tags", "--exact-match", "HEAD"],
+      {
+        cwd: rootDir,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5000,
+      }
+    ).trim();
+    return result || "develop";
   } catch {
-    return "main";
+    return "develop";
   }
 }
 
-const GITHUB_REF = getLatestTag();
-const GITHUB_BLOB = `${GITHUB_REPO}/blob/${GITHUB_REF}`;
-
 export function getStdDocCommand(rootDir: string = ROOT): {
   command: string;
   args: string[];
@@ -57,12 +58,50 @@ export function getStdDocCommand(rootDir: string = ROOT): {
 // ── Parse args ───────────────────────────────────────────────────────
 
 let outputDir = path.join(ROOT, "site");
+let siteVersion: string | undefined;
 const args = process.argv.slice(2);
 for (let i = 0; i < args.length; i++) {
   if (args[i] === "--output" && args[i + 1]) {
     outputDir = path.resolve(args[i + 1]!);
     i++;
+  } else if (args[i] === "--version" && args[i + 1]) {
+    siteVersion = args[i + 1]!;
+    i++;
+  }
+}
+
+// Fallback: auto-detect version from git (tag or commit hash)
+if (!siteVersion) {
+  siteVersion = detectGitVersion(ROOT);
+}
+
+// Use the explicit version (e.g., "v0.1.17" from --version flag) for blob links
+// when it looks like a tag; otherwise use the exact tag on HEAD; otherwise "develop".
+const GITHUB_REF =
+  siteVersion && /^v\d/.test(siteVersion)
+    ? siteVersion
+    : getExactTagOrDevelop(ROOT);
+const GITHUB_BLOB = `${GITHUB_REPO}/blob/${GITHUB_REF}`;
+
+function detectGitVersion(cwd: string): string | undefined {
+  function git(...gitArgs: string[]): string | undefined {
+    try {
+      return (
+        execFileSync("git", gitArgs, {
+          cwd,
+          encoding: "utf-8",
+          timeout: 5000,
+        }).trim() || undefined
+      );
+    } catch {
+      return undefined;
+    }
   }
+  // Show exact tag only if HEAD is exactly at that tag; otherwise show short commit hash
+  return (
+    git("describe", "--tags", "--exact-match", "HEAD") ??
+    git("rev-parse", "--short", "HEAD")
+  );
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────
@@ -306,6 +345,17 @@ th {
   margin-top: 8px;
 }
 
+.version-badge {
+  font-size: 0.4em;
+  font-weight: 500;
+  color: var(--accent);
+  background: var(--bg-secondary);
+  padding: 2px 10px;
+  border-radius: 4px;
+  vertical-align: middle;
+  margin-left: 8px;
+}
+
 .site-nav {
   margin-top: 16px;
   display: flex;
@@ -341,7 +391,15 @@ th {
 `;
 }
 
-function wrapHomepage(title: string, bodyHtml: string, css: string): string {
+function wrapHomepage(
+  title: string,
+  bodyHtml: string,
+  css: string,
+  version?: string
+): string {
+  const versionBadge = version
+    ? `<span class="version-badge">${escapeHtml(version)}</span>`
+    : "";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -354,7 +412,7 @@ function wrapHomepage(title: string, bodyHtml: string, css: string): string {
   <div class="container">
     <div class="site-header">
       <img src="Yo_logo.png" alt="Yo logo" width="80" height="80">
-      <h1>Yo Programming Language</h1>
+      <h1>Yo Programming Language ${versionBadge}</h1>
       <p class="tagline">A general-purpose, ahead-of-time compiled language with algebraic effects</p>
       <div class="site-nav">
         <a href="${GITHUB_REPO}">GitHub</a>
@@ -434,7 +492,12 @@ export async function main(): Promise<void> {
   readmeHtml = rewriteReadmeLinks(readmeHtml);
 
   const css = generateHomepageCSS();
-  const homepage = wrapHomepage("Yo Programming Language", readmeHtml, css);
+  const homepage = wrapHomepage(
+    "Yo Programming Language",
+    readmeHtml,
+    css,
+    siteVersion
+  );
   fs.writeFileSync(path.join(outputDir, "index.html"), homepage, "utf-8");
   console.log("  ✓ index.html");
 
@@ -461,15 +524,15 @@ export async function main(): Promise<void> {
 
   try {
     const stdDocCommand = getStdDocCommand();
-    execFileSync(
-      stdDocCommand.command,
-      [...stdDocCommand.args, "--output", stdOutputDir],
-      {
-        cwd: ROOT,
-        stdio: ["ignore", "inherit", "inherit"],
-        timeout: 600_000,
-      }
-    );
+    const docArgs = [...stdDocCommand.args, "--output", stdOutputDir];
+    if (siteVersion) {
+      docArgs.push("--version", siteVersion);
+    }
+    execFileSync(stdDocCommand.command, docArgs, {
+      cwd: ROOT,
+      stdio: ["ignore", "inherit", "inherit"],
+      timeout: 600_000,
+    });
     console.log("  ✓ Standard library docs generated");
   } catch (err) {
     console.error(

package/std/build.yo

@@ -460,6 +460,9 @@ DocConfig :: struct(
   (include_deps : bool) ?= false,
   /// Custom site title (default: project name).
   (title : comptime_string) ?= "",
+  /// Release version to display (e.g., "v1.0.0").
+  /// When empty, auto-detects from git tag or commit hash.
+  (version : comptime_string) ?= "",
   /// Path to logo image.
   (logo : comptime_string) ?= "",
   /// Path to favicon.
@@ -483,7 +486,8 @@ export DocConfig;
 ///   root: "./src",
 ///   output: "docs/api",
 ///   format: DocFormat.Markdown,
-///   title: "My Library API"
+///   title: "My Library API",
+///   version: "v1.0.0"
 /// });
 ///
 /// install :: build.step("install", "Build all artifacts");
@@ -498,7 +502,8 @@ doc :: (fn(comptime(config) : DocConfig) -> comptime(Step)) {
   __yo_build_doc(
     config.name, config.root, config.output, fmt_str,
     config.include_private, config.include_deps,
-    config.title, config.logo, config.favicon
+    config.title, config.logo, config.favicon,
+    config.version
   );
   Step(name: config.name, kind: StepKind.Documentation)
 };

package/std/collections/array_list.yo

@@ -490,7 +490,10 @@ impl(forall(T : Type), ArrayList(T),
   })
 );
 impl(forall(T : Type), ArrayList(T), Index(usize)(
+  /// The output type is the element type `T`.
   Output : T,
+
+  /// Returns a pointer to the element at the given index. Panics if the index is out of bounds.
   index : (fn(self: *(Self), idx: usize) -> *(Self.Output))({
     assert((idx < self.*._length), "ArrayList: index out of bounds");
     match(self.*._ptr,