[pull] main from withastro:main

.agents/skills/writing-comments/SKILL.md

@@ -61,6 +61,48 @@ Do not mix the jobs. Implementation details do not belong in the `/** */`
 contract — put them as `//` comments inside the body. The contract does not
 belong scattered across inline comments — put it on the declaration.
 
+## Behavior Documentation
+
+When item documentation is warranted, write the contract for a human reader,
+not as a translation of the implementation. This does not require JSDoc for
+every function; names, types, and structure should carry straightforward
+behavior on their own.
+
+- Start with a plain-language description of what the function returns or
+  accomplishes.
+- Use short or medium-length sentences with one main idea each.
+- Avoid internal Astro jargon when callers do not need it. If a technical term
+  is necessary, explain it in the same paragraph.
+- Describe caller-visible caveats that can be surprising: fallback behavior,
+  work limits, ambiguous results, overload ordering, side effects, and the
+  conditions that return `undefined`, `null`, an empty result, or another
+  indeterminate value.
+- Document thrown errors when callers are expected to distinguish or recover
+  from them.
+- Do not describe implementation details unless callers need them to understand
+  the behavior or use the API safely.
+
+Add an example when behavior depends on a relationship the signature cannot
+show clearly. Common Astro and TypeScript cases include:
+
+- which overload is selected;
+- how arguments map to optional or rest parameters;
+- which public Astro entrypoint exposes a symbol that is implemented or
+  re-exported elsewhere;
+- fallback behavior for ambiguous routes, incomplete configuration, or missing
+  content;
+- a result whose meaning is not obvious from its type.
+
+Introduce the example in prose before the code block. State what it demonstrates
+and what result is expected. Keep snippets minimal, self-contained, and written
+from the perspective of an Astro user or the internal caller that owns the
+contract.
+
+Module documentation should describe a durable concept, architectural boundary,
+or design reason. Do not list individual exports merely to summarize the file;
+such inventories become stale as symbols are added or renamed. If a module has
+no durable concept to explain, use a brief one-line description or no overview.
+
 ## The Deletion Test
 
 Before writing any comment, ask: **does this state something the reader cannot

.changeset/strict-socks-decide.md

@@ -0,0 +1,7 @@
+---
+'astro': patch
+'@astrojs/internal-helpers': patch
+'astro-vscode': patch
+---
+
+Updates dependency `js-yaml` to v4.3.0

packages/astro/package.json

@@ -143,7 +143,7 @@
     "github-slugger": "^2.0.0",
     "html-escaper": "3.0.3",
     "http-cache-semantics": "^4.2.0",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.3.0",
     "jsonc-parser": "^3.3.1",
     "magic-string": "^1.0.0",
     "magicast": "^0.5.2",

packages/internal-helpers/package.json

@@ -42,7 +42,7 @@
   "dependencies": {
     "@types/hast": "^3.0.4",
     "@types/mdast": "^4.0.4",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.3.0",
     "picomatch": "^4.0.4",
     "retext-smartypants": "^6.2.0",
     "shiki": "^4.0.2",

packages/language-tools/vscode/package.json

@@ -258,7 +258,7 @@
     "@vscode/vsce": "2.32.0",
     "esbuild": "^0.17.19",
     "esbuild-plugin-copy": "^2.1.1",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.3.0",
     "kleur": "^4.1.5",
     "mocha": "^11.7.5",
     "ovsx": "^0.10.10",