docs: Documenting support for full lock files

Author: yhakbar

docs/package.json

@@ -7,7 +7,8 @@
     "start": "astro dev",
     "build": "astro build",
     "preview": "astro preview",
-    "astro": "astro"
+    "astro": "astro",
+    "test": "bun test"
   },
   "dependencies": {
     "@astrojs/compiler-rs": "^0.1.6",

docs/src/data/changelog/v1.0.4/full-provider-lock-files.mdx

@@ -0,0 +1,30 @@
+---
+version: "v1.0.4"
+category: "new-features"
+---
+
+import { Aside } from '@astrojs/starlight/components'
+
+#### Full `.terraform.lock.hcl` files from the provider cache server
+
+When the [provider cache server](/features/caching/provider-cache-server) is used against the OpenTofu provider registry, Terragrunt now writes `.terraform.lock.hcl` files containing `h1:` hashes for every platform the registry supports. A single `terragrunt init` produces a lock file that works on every platform, removing the need to run `tofu providers lock -platform=...` separately for each target architecture.
+
+```hcl
+provider "registry.opentofu.org/hashicorp/null" {
+  version     = "3.2.2"
+  constraints = "3.2.2"
+  hashes = [
+    "h1:+1mRmfyz6oA00IhrrSkHK3h/Mdh032x2p0F6OMdMo5s=",
+    "h1:FjLTqvaaYo+vHN8pHZB1cOwEGiNzOj+I9kQyHmr9/7o=",
+    # ... one entry per supported platform ...
+    "zh:00e5877d19fb1c1d8c4b3536334a46a5c86f57146fd115c7b7b4b5d2bf2de86d",
+    # ... one entry per supported platform ...
+  ]
+}
+```
+
+The hashes come from the registry's per-platform download response. When the registry does not supply them (for example, a third-party registry that has not adopted the field), Terragrunt falls back to its previous behavior of writing an `h1:` hash for the current platform plus `zh:` hashes for every platform listed in the shasums document.
+
+<Aside type="tip" title="Thanks to the OpenTofu team">
+  This feature builds on work done by the OpenTofu team to expose per-platform hashes directly from the OpenTofu provider registry. Starting with [OpenTofu 1.12](https://opentofu.org/), `tofu init` populates `.terraform.lock.hcl` with hashes for every supported platform out of the box, with no Terragrunt or `tofu providers lock` invocation required. Users on older OpenTofu versions still get the same lock files when running through Terragrunt's provider cache server, but upgrading to 1.12 is the easiest way to get the same behavior everywhere.
+</Aside>

docs/src/lib/changelog.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, test } from "bun:test";
+import {
+  categorySlugSort,
+  compareVersionsDesc,
+  isReleased,
+  parsePullRequests,
+  prepareForGitHub,
+  pullRequestsToMarkdown,
+} from "./changelog";
+
+const SITE = "https://terragrunt.gruntwork.io";
+
+describe("compareVersionsDesc", () => {
+  test("orders semver versions descending", () => {
+    const sorted = ["v1.0.10", "v1.0.2", "v1.0.0"].sort(compareVersionsDesc);
+    expect(sorted).toEqual(["v1.0.10", "v1.0.2", "v1.0.0"]);
+  });
+
+  test("non-version strings sort before semver versions", () => {
+    const sorted = ["v1.0.0", "draft", "v0.99.0"].sort(compareVersionsDesc);
+    expect(sorted[0]).toBe("draft");
+  });
+});
+
+describe("isReleased", () => {
+  test("returns true when version is at or below latest", () => {
+    expect(isReleased("v1.0.3", "1.0.3")).toBe(true);
+    expect(isReleased("v1.0.0", "1.0.3")).toBe(true);
+  });
+
+  test("returns false when version is newer than latest", () => {
+    expect(isReleased("v1.0.4", "1.0.3")).toBe(false);
+  });
+
+  test("returns false for non-semver tags", () => {
+    expect(isReleased("draft", "1.0.3")).toBe(false);
+  });
+});
+
+describe("categorySlugSort", () => {
+  test("uses the canonical category order", () => {
+    const slugs = ["bug-fixes", "breaking-changes", "new-features"].sort(categorySlugSort);
+    expect(slugs).toEqual(["breaking-changes", "new-features", "bug-fixes"]);
+  });
+});
+
+describe("parsePullRequests", () => {
+  test("returns empty array on null body", () => {
+    expect(parsePullRequests(null)).toEqual([]);
+  });
+
+  test("groups items under their conventional type and stops at next h2", () => {
+    const body = [
+      "## What's Changed",
+      "* feat: add a thing by @alice in https://github.com/o/r/pull/1",
+      "* fix(parser): tighten regex by @bob in https://github.com/o/r/pull/2",
+      "* feat!: rip out the old API by @carol in https://github.com/o/r/pull/3",
+      "* docs: tidy README by @dan in https://github.com/o/r/pull/4",
+      "",
+      "## New Contributors",
+      "* should not be parsed by @eve in https://github.com/o/r/pull/99",
+    ].join("\n");
+
+    const groups = parsePullRequests(body);
+    const labels = groups.map((g) => g.type.key);
+
+    expect(labels).toEqual(["breaking", "feat", "fix", "docs"]);
+    expect(groups[1].items[0].prNumber).toBe(1);
+    expect(groups[0].items[0].prNumber).toBe(3);
+    expect(groups.flatMap((g) => g.items.map((i) => i.author))).not.toContain("eve");
+  });
+
+  test("ignores text outside the What's Changed section", () => {
+    const body = [
+      "Intro paragraph",
+      "* fix: should not be picked up by @x in https://github.com/o/r/pull/1",
+      "## What's Changed",
+      "* feat: real entry by @y in https://github.com/o/r/pull/2",
+    ].join("\n");
+
+    const groups = parsePullRequests(body);
+    expect(groups).toHaveLength(1);
+    expect(groups[0].items[0].author).toBe("y");
+  });
+});
+
+describe("pullRequestsToMarkdown", () => {
+  test("formats grouped items with author and PR links", () => {
+    const md = pullRequestsToMarkdown(
+      parsePullRequests(
+        [
+          "## What's Changed",
+          "* feat: add a thing by @alice in https://github.com/o/r/pull/1",
+        ].join("\n"),
+      ),
+    );
+
+    expect(md).toContain("## Pull Requests");
+    expect(md).toContain("### ✨ Features");
+    expect(md).toContain("[@alice](https://github.com/alice)");
+    expect(md).toContain("[#1](https://github.com/o/r/pull/1)");
+  });
+});
+
+describe("prepareForGitHub", () => {
+  test("rewrites root-relative links to absolute URLs", () => {
+    const out = prepareForGitHub("See [the docs](/features/x).", SITE);
+    expect(out).toBe(`See [the docs](${SITE}/features/x).`);
+  });
+
+  test("flattens entry and category headings to h2 and strips horizontal rules", () => {
+    // The wrapping page renders categories as `### Label` and entries as
+    // `#### Title`. The two-step rewrite below collapses both to `##`, since
+    // pass two also catches the `###` produced by pass one. GitHub releases
+    // render `##` as the largest distinguishable section heading.
+    const out = prepareForGitHub(
+      ["### ✨ New Features", "", "---", "", "#### Did a thing", "", "Body."].join("\n"),
+      SITE,
+    );
+    expect(out).toBe(["## ✨ New Features", "", "## Did a thing", "", "Body."].join("\n"));
+  });
+
+  test("strips MDX import lines", () => {
+    const out = prepareForGitHub(
+      [
+        "import { Aside } from '@astrojs/starlight/components'",
+        "",
+        "#### Title",
+        "",
+        "Body.",
+      ].join("\n"),
+      SITE,
+    );
+    expect(out).toBe(["## Title", "", "Body."].join("\n"));
+  });
+
+  test("converts a tip Aside with a title to a GitHub TIP alert", () => {
+    const out = prepareForGitHub(
+      ['<Aside type="tip" title="Heads up">', "Be aware.", "</Aside>"].join("\n"),
+      SITE,
+    );
+    expect(out).toBe(["> [!TIP]", "> **Heads up**", ">", "> Be aware."].join("\n"));
+  });
+
+  test("uses NOTE for default Aside type and omits title line when absent", () => {
+    const out = prepareForGitHub("<Aside>Just a note.</Aside>", SITE);
+    expect(out).toBe(["> [!NOTE]", "> Just a note."].join("\n"));
+  });
+
+  test("maps Starlight caution and danger to WARNING and CAUTION", () => {
+    const caution = prepareForGitHub('<Aside type="caution">be careful</Aside>', SITE);
+    const danger = prepareForGitHub('<Aside type="danger">stop</Aside>', SITE);
+    expect(caution).toContain("> [!WARNING]");
+    expect(danger).toContain("> [!CAUTION]");
+  });
+
+  test("transforms multiple Asides independently", () => {
+    const out = prepareForGitHub(
+      ['<Aside type="tip">first</Aside>', "", '<Aside type="caution">second</Aside>'].join("\n"),
+      SITE,
+    );
+    expect(out).toContain("> [!TIP]");
+    expect(out).toContain("> first");
+    expect(out).toContain("> [!WARNING]");
+    expect(out).toContain("> second");
+  });
+
+  test("preserves blank lines inside an Aside body as `>` continuation rows", () => {
+    const out = prepareForGitHub(
+      [
+        '<Aside type="note" title="Heads up">',
+        "para one",
+        "",
+        "para two",
+        "</Aside>",
+      ].join("\n"),
+      SITE,
+    );
+    expect(out).toContain("> para one");
+    expect(out).toContain(">\n> para two");
+  });
+
+  test("collapses runs of blank lines to a single blank line", () => {
+    const out = prepareForGitHub("a\n\n\n\nb", SITE);
+    expect(out).toBe("a\n\nb");
+  });
+});

docs/src/lib/changelog.ts

@@ -218,9 +218,50 @@ export function pullRequestsToMarkdown(groups: PullRequestGroup[]): string {
   return `## Pull Requests\n\n${sections.join("\n\n")}`;
 }
 
+// Maps Starlight `<Aside type="...">` values to the closest GitHub Flavored
+// Markdown alert label. GitHub renders these as colored callout boxes in
+// release notes and READMEs.
+const ASIDE_TYPE_TO_GH_ALERT: Record<string, string> = {
+  note: "NOTE",
+  tip: "TIP",
+  caution: "WARNING",
+  danger: "CAUTION",
+};
+
+const ASIDE_BLOCK = /<Aside(?:\s+([^>]*?))?\s*>([\s\S]*?)<\/Aside>/g;
+const ASIDE_TYPE_ATTR = /\btype\s*=\s*"([^"]+)"/;
+const ASIDE_TITLE_ATTR = /\btitle\s*=\s*"([^"]+)"/;
+const MDX_IMPORT_LINE = /^\s*import\s+[^\n]*\s+from\s+['"][^'"]+['"];?\s*$/gm;
+
+function attrValue(attrs: string, pattern: RegExp): string | null {
+  const match = attrs.match(pattern);
+  return match ? match[1] : null;
+}
+
+function transformAsidesToGitHubAlerts(input: string): string {
+  return input.replace(ASIDE_BLOCK, (_match, attrs: string | undefined, content: string) => {
+    const attrString = attrs ?? "";
+    const type = attrValue(attrString, ASIDE_TYPE_ATTR) ?? "note";
+    const title = attrValue(attrString, ASIDE_TITLE_ATTR) ?? "";
+    const alert = ASIDE_TYPE_TO_GH_ALERT[type] ?? "NOTE";
+
+    const titleSection = title ? `**${title}**\n\n` : "";
+    const body = `[!${alert}]\n${titleSection}${content.trim()}`;
+
+    return body
+      .split("\n")
+      .map((line) => (line.length === 0 ? ">" : `> ${line}`))
+      .join("\n");
+  });
+}
+
 export function prepareForGitHub(body: string, siteUrl: string): string {
   let result = body;
 
+  result = result.replace(MDX_IMPORT_LINE, "");
+
+  result = transformAsidesToGitHubAlerts(result);
+
   result = result.replace(/\]\(\//g, `](${siteUrl}/`);
 
   result = result.replace(/^####\s/gm, "### ");