@codedrifters/configulator 0.0.272 → 0.0.274

package/lib/index.js

@@ -223,6 +223,7 @@ __export(index_exports, {
   DEFAULT_PROGRESS_FILES_STATE_DIR: () => DEFAULT_PROGRESS_FILES_STATE_DIR,
   DEFAULT_REQUIRE_LINKED_ISSUE: () => DEFAULT_REQUIRE_LINKED_ISSUE,
   DEFAULT_REQUIRE_PRODUCT_CONTEXT: () => DEFAULT_REQUIRE_PRODUCT_CONTEXT,
+  DEFAULT_SAMPLE_COMPILER_OPTIONS: () => DEFAULT_SAMPLE_COMPILER_OPTIONS,
   DEFAULT_SCHEDULED_TASKS_ROOT: () => DEFAULT_SCHEDULED_TASKS_ROOT,
   DEFAULT_SCHEDULED_TASK_ENTRIES: () => DEFAULT_SCHEDULED_TASK_ENTRIES,
   DEFAULT_SHARED_EDITING_CONFLICT_STRATEGY: () => DEFAULT_SHARED_EDITING_CONFLICT_STRATEGY,
@@ -268,6 +269,7 @@ __export(index_exports, {
   SCOPE_CLASS_VALUES: () => SCOPE_CLASS_VALUES,
   SHARED_EDITING_CONFLICT_STRATEGY_VALUES: () => SHARED_EDITING_CONFLICT_STRATEGY_VALUES,
   STARLIGHT_ROLE: () => STARLIGHT_ROLE,
+  SampleLang: () => SampleLang,
   StarlightProject: () => StarlightProject,
   TestRunner: () => TestRunner,
   TsDocCoverageKind: () => TsDocCoverageKind,
@@ -310,13 +312,17 @@ __export(index_exports, {
   buildStandardsResearchBundle: () => buildStandardsResearchBundle,
   buildUnblockDependentsProcedure: () => buildUnblockDependentsProcedure,
   businessModelsBundle: () => businessModelsBundle,
+  checkDocSamplesProcedure: () => checkDocSamplesProcedure,
+  checkLinksProcedure: () => checkLinksProcedure,
   classifyIssueScope: () => classifyIssueScope,
   classifyRun: () => classifyRun,
   companyProfileBundle: () => companyProfileBundle,
+  compileFencedSamples: () => compileFencedSamples,
   customerProfileBundle: () => customerProfileBundle,
   docsSyncBundle: () => docsSyncBundle,
   extractApiProcedure: () => extractApiProcedure,
   extractDocReferences: () => extractDocReferences,
+  extractFencedSamples: () => extractFencedSamples,
   formatLayoutViolation: () => formatLayoutViolation,
   formatStarlightSingletonViolation: () => formatStarlightSingletonViolation,
   getLatestEligibleVersion: () => getLatestEligibleVersion,
@@ -333,6 +339,8 @@ __export(index_exports, {
   regulatoryResearchBundle: () => regulatoryResearchBundle,
   renderAgentTierCaseStatement: () => renderAgentTierCaseStatement,
   renderAgentTierSection: () => renderAgentTierSection,
+  renderCheckDocSamplesProcedure: () => renderCheckDocSamplesProcedure,
+  renderCheckLinksProcedure: () => renderCheckLinksProcedure,
   renderCustomDocSectionBlock: () => renderCustomDocSectionBlock,
   renderCustomDocSections: () => renderCustomDocSections,
   renderExtractApiProcedure: () => renderExtractApiProcedure,
@@ -8978,6 +8986,415 @@ var extractApiProcedure = {
   description: "Run @microsoft/api-extractor for a single package and write the .api.md rollup to the scratch folder declared by the package's api-extractor.json. Rollups are regenerate-on-scan per docs-sync epic #448 resolved decision #3 \u2014 never committed to git.",
   content: renderExtractApiProcedure()
 };
+function renderCheckLinksProcedure() {
+  return [
+    "#!/usr/bin/env bash",
+    "# check-links.sh \u2014 Link integrity checker for the Starlight docs site.",
+    "#",
+    "# Usage:",
+    "#   .claude/procedures/check-links.sh <mode> <docs-root> [<site-dir>]",
+    "#",
+    "# Where:",
+    "#   <mode>      \u2014 one of `internal`, `external`, or `all`.",
+    "#   <docs-root> \u2014 path to the markdown content tree",
+    "#                 (e.g. `docs/src/content/docs`). Walked recursively",
+    "#                 for `*.md` / `*.mdx` files.",
+    "#   <site-dir>  \u2014 (optional, internal/all only) path to the Starlight",
+    "#                 project root that contains `astro.config.{ts,mjs,js}`.",
+    "#                 Defaults to two levels up from `<docs-root>` so the",
+    "#                 standard Starlight layout (`<site>/src/content/docs`)",
+    "#                 resolves automatically.",
+    "#",
+    "# Wraps two external tools:",
+    "#   - `astro check`  \u2014 internal links and content-collection refs",
+    "#                      inside the Starlight site.",
+    "#   - `lychee`       \u2014 external `https://\u2026` URLs across the docs tree",
+    "#                      (https://github.com/lycheeverse/lychee).",
+    "#",
+    "# Output (stdout, single JSON array):",
+    "#",
+    "#   [",
+    "#     {",
+    '#       "url":     "<href as written in the markdown source>",',
+    '#       "docPath": "<path relative to <docs-root>>",',
+    '#       "line":    <1-indexed line number>,',
+    '#       "kind":    "internal" | "external",',
+    '#       "reason":  "<short tool-supplied diagnostic>"',
+    "#     },",
+    "#     ...",
+    "#   ]",
+    "#",
+    "# An empty array (`[]`) is emitted when no broken links are found.",
+    "# Detection is **data**, not failure: this helper exits 0 when a",
+    "# tool ran successfully and reported zero or more broken links.",
+    "# The downstream docs-sync scan phase (#519/#520) is responsible",
+    "# for deciding which findings are advisory and which block.",
+    "#",
+    "# Exit codes:",
+    "#   0  \u2014 every requested tool ran successfully; findings (zero or",
+    "#        more) are on stdout as a JSON array.",
+    "#   1  \u2014 usage error (missing args, unreadable docs root).",
+    "#   2  \u2014 a required external tool is not installed or not on PATH",
+    "#        (`astro` / `lychee` / `node` / `jq`).",
+    "#   3  \u2014 a tool ran but exited non-zero for a reason other than",
+    "#        broken-link detection (config error, IO error, network",
+    "#        failure for lychee, etc.). Stderr carries the diagnostic.",
+    "#",
+    "# The script never edits files. Diagnostics flow to stderr; the",
+    "# only thing on stdout is the normalized JSON array.",
+    "",
+    "set -uo pipefail",
+    "",
+    "err() {",
+    '  printf "check-links.sh: %s\\n" "$*" >&2',
+    "}",
+    "",
+    'if [ "$#" -lt 2 ]; then',
+    '  err "usage: check-links.sh <internal|external|all> <docs-root> [<site-dir>]"',
+    "  exit 1",
+    "fi",
+    "",
+    'mode="$1"',
+    'docs_root="$2"',
+    'site_dir="${3:-}"',
+    "",
+    'case "$mode" in',
+    "  internal | external | all) ;;",
+    "  *)",
+    `    err "unknown mode '$mode' \u2014 expected 'internal', 'external', or 'all'"`,
+    "    exit 1",
+    "    ;;",
+    "esac",
+    "",
+    'if [ ! -d "$docs_root" ]; then',
+    '  err "docs root not found: $docs_root"',
+    "  exit 1",
+    "fi",
+    "",
+    'if [ -z "$site_dir" ]; then',
+    "  # Standard Starlight layout: <site>/src/content/docs. Walk two",
+    "  # parents up from the content root to recover the site dir.",
+    '  site_dir="$(cd "$docs_root/../../.." && pwd)"',
+    "fi",
+    "",
+    "# `jq` is required to merge the per-tool JSON output streams. Fail",
+    "# fast with the dedicated tool-missing exit code if it is absent.",
+    "if ! command -v jq >/dev/null 2>&1; then",
+    '  err "jq is required but not on PATH"',
+    "  exit 2",
+    "fi",
+    "",
+    'tmp_dir="$(mktemp -d -t check-links-XXXXXX)"',
+    "# shellcheck disable=SC2064",
+    `trap "rm -rf '$tmp_dir'" EXIT`,
+    "",
+    'internal_json="$tmp_dir/internal.json"',
+    'external_json="$tmp_dir/external.json"',
+    'printf "[]" > "$internal_json"',
+    'printf "[]" > "$external_json"',
+    "",
+    "# ---------------------------------------------------------------",
+    "# Internal-link check",
+    "# ---------------------------------------------------------------",
+    "# `astro check` runs inside the Starlight project root and walks",
+    "# content collections to validate internal references. It exits",
+    "# non-zero when references are broken \u2014 that is a *finding* for",
+    "# this helper, not a tool failure, so we capture stderr and parse",
+    "# it into the normalized record shape rather than propagating the",
+    "# non-zero exit.",
+    'if [ "$mode" = "internal" ] || [ "$mode" = "all" ]; then',
+    "  if ! command -v node >/dev/null 2>&1; then",
+    '    err "node is required but not on PATH"',
+    "    exit 2",
+    "  fi",
+    "",
+    '  if [ ! -d "$site_dir" ]; then',
+    '    err "site dir not found: $site_dir"',
+    "    exit 1",
+    "  fi",
+    "",
+    "  # Locate the astro binary in the site's local node_modules first",
+    "  # so the version matches what `pnpm install` resolved for the",
+    "  # Starlight site. Fall back to a workspace-aware `pnpm exec`.",
+    '  if [ -x "$site_dir/node_modules/.bin/astro" ]; then',
+    '    astro_bin=("$site_dir/node_modules/.bin/astro")',
+    "  elif command -v pnpm >/dev/null 2>&1; then",
+    '    astro_bin=(pnpm --dir "$site_dir" exec astro)',
+    "  else",
+    '    err "astro binary not found in $site_dir/node_modules/.bin and pnpm is unavailable"',
+    "    exit 2",
+    "  fi",
+    "",
+    '  astro_log="$tmp_dir/astro.log"',
+    "  set +e",
+    '  ( cd "$site_dir" && "${astro_bin[@]}" check ) > "$astro_log" 2>&1',
+    "  astro_status=$?",
+    "  set -e",
+    "",
+    "  # `astro check` exits 1 on findings and >=2 on tool failure.",
+    "  # Translate to the normalized record stream regardless of exit.",
+    '  if [ "$astro_status" -ge 2 ]; then',
+    '    err "astro check exited with status $astro_status (tool failure)"',
+    '    cat "$astro_log" >&2 || true',
+    "    exit 3",
+    "  fi",
+    "",
+    "  # Parse the line-oriented log into JSON records. The `astro",
+    "  # check` output for a broken reference looks like:",
+    "  #",
+    "  #   src/content/docs/foo.md:42:8 - error <code>: <reason>",
+    "  #",
+    "  # The helper extracts `<docPath>`, `<line>`, and `<reason>` and",
+    "  # synthesises a `url` field by quoting the offending excerpt",
+    "  # when astro reports one (it does not always); when no excerpt",
+    "  # is available we fall back to an empty string so the schema",
+    "  # stays uniform.",
+    `  awk -v docs_root="$docs_root" -v site_dir="$site_dir" '`,
+    "    BEGIN {",
+    '      printf "[";',
+    "      first = 1;",
+    "    }",
+    '    # Match "<path>:<line>:<col> - <severity> <code>: <message>"',
+    "    /^.+:[0-9]+:[0-9]+ - / {",
+    '      split($0, head, " - ");',
+    '      n = split(head[1], loc, ":");',
+    "      file = loc[1];",
+    '      for (i = 2; i < n - 1; i++) { file = file ":" loc[i]; }',
+    "      line = loc[n - 1];",
+    '      message = "";',
+    "      for (i = 2; i <= length(head); i++) {",
+    '        if (i > 2) message = message " - ";',
+    "        message = message head[i];",
+    "      }",
+    "      # Resolve the file relative to docs_root for stability.",
+    "      abs = file;",
+    '      if (substr(abs, 1, 1) != "/") {',
+    '        abs = site_dir "/" abs;',
+    "      }",
+    '      sub(docs_root "/", "", abs);',
+    '      gsub(/"/, "\\\\\\"", message);',
+    '      gsub(/"/, "\\\\\\"", abs);',
+    '      if (!first) printf ",";',
+    "      first = 0;",
+    '      printf "{\\"url\\":\\"\\",\\"docPath\\":\\"%s\\",\\"line\\":%s,\\"kind\\":\\"internal\\",\\"reason\\":\\"%s\\"}", abs, line, message;',
+    "    }",
+    "    END {",
+    '      printf "]";',
+    "    }",
+    `  ' "$astro_log" > "$internal_json"`,
+    "",
+    "  # Validate the JSON we synthesised. Catches awk escaping bugs",
+    "  # before we hand the payload to the merge step.",
+    '  if ! jq -e . "$internal_json" >/dev/null 2>&1; then',
+    '    err "failed to normalize astro check output to JSON"',
+    '    cat "$internal_json" >&2 || true',
+    "    exit 3",
+    "  fi",
+    "fi",
+    "",
+    "# ---------------------------------------------------------------",
+    "# External-link check",
+    "# ---------------------------------------------------------------",
+    "# `lychee` walks the markdown tree and reports unreachable URLs.",
+    "# Its `--format json` output is structured per-link; we project",
+    "# only the failed entries into the normalized record shape.",
+    'if [ "$mode" = "external" ] || [ "$mode" = "all" ]; then',
+    "  if ! command -v lychee >/dev/null 2>&1; then",
+    '    err "lychee is required but not on PATH (https://github.com/lycheeverse/lychee)"',
+    "    exit 2",
+    "  fi",
+    "",
+    '  lychee_json="$tmp_dir/lychee.json"',
+    "  set +e",
+    "  # `--no-progress` avoids interactive carriage-returns mangling",
+    "  # the JSON. `--format json` emits a single object whose `fail_map`",
+    "  # field lists the broken URLs grouped by source file.",
+    "  # `--exclude-mail` skips mailto: links (out of scope for this",
+    "  # helper).",
+    '  lychee --no-progress --format json --exclude-mail "$docs_root" > "$lychee_json" 2>"$tmp_dir/lychee.err"',
+    "  lychee_status=$?",
+    "  set -e",
+    "",
+    "  # lychee exits 0 when every link resolved, 2 when one or more",
+    "  # links failed. Anything else is a tool failure (config, IO).",
+    '  if [ "$lychee_status" -ne 0 ] && [ "$lychee_status" -ne 2 ]; then',
+    '    err "lychee exited with status $lychee_status (tool failure)"',
+    '    cat "$tmp_dir/lychee.err" >&2 || true',
+    "    exit 3",
+    "  fi",
+    "",
+    "  # Project lychee's `fail_map` into the normalized record shape.",
+    '  # The `fail_map` is `{ "<source-path>": [ { url, status: { details? } }, ... ] }`.',
+    "  # lychee does not report a line number for every match, so we",
+    "  # default to 0 when it is missing (downstream consumers treat",
+    '  # 0 as "unknown line").',
+    `  jq --arg root "$docs_root" '`,
+    "    def trim_root($p; $r):",
+    '      if ($p | startswith($r + "/")) then ($p | ltrimstr($r + "/"))',
+    '      elif ($p == $r) then ""',
+    "      else $p end;",
+    "    [",
+    "      ( .fail_map // {} ) as $map",
+    "      | $map | to_entries[]",
+    "      | .key as $src",
+    "      | .value[]",
+    "      | {",
+    '          url: (.url // ""),',
+    "          docPath: trim_root($src; $root),",
+    "          line: ((.line // 0) | tonumber? // 0),",
+    '          kind: "external",',
+    '          reason: ( (.status.details // .status.text // .status.code // "broken") | tostring )',
+    "        }",
+    "    ]",
+    `  ' "$lychee_json" > "$external_json" 2>"$tmp_dir/lychee.parse.err"`,
+    "",
+    '  if ! jq -e . "$external_json" >/dev/null 2>&1; then',
+    '    err "failed to parse lychee JSON output"',
+    '    cat "$tmp_dir/lychee.parse.err" >&2 || true',
+    '    cat "$lychee_json" >&2 || true',
+    "    exit 3",
+    "  fi",
+    "fi",
+    "",
+    "# ---------------------------------------------------------------",
+    "# Merge & emit",
+    "# ---------------------------------------------------------------",
+    "# Sort records deterministically (kind, docPath, line, url) so",
+    "# downstream consumers can compare reports across runs without",
+    "# fighting platform-specific ordering noise.",
+    "jq -s '",
+    "  add",
+    "  | sort_by(.kind, .docPath, .line, .url)",
+    `' "$internal_json" "$external_json"`,
+    "",
+    "exit 0"
+  ].join("\n");
+}
+var checkLinksProcedure = {
+  name: "check-links.sh",
+  description: "Link integrity checker that wraps `astro check` (internal links) and `lychee` (external URLs) and normalizes their output into a single JSON-array stream of { url, docPath, line, kind, reason } records. Detection is data: the helper exits 0 when a tool ran successfully regardless of how many broken links it reported. Non-zero exits are reserved for tool-level failures.",
+  content: renderCheckLinksProcedure()
+};
+function renderCheckDocSamplesProcedure() {
+  const nodeScript = [
+    "(async () => {",
+    "  const { compileFencedSamples } = await import('@codedrifters/configulator');",
+    "  const docsRoot = process.argv[1];",
+    "  const failures = compileFencedSamples({ docsRoot });",
+    "  process.stdout.write(JSON.stringify(failures));",
+    "})().catch((err) => {",
+    "  console.error('check-doc-samples.sh: ' + (err && err.stack ? err.stack : err));",
+    "  process.exit(3);",
+    "});"
+  ].join("\n");
+  return [
+    "#!/usr/bin/env bash",
+    "# check-doc-samples.sh \u2014 Compile fenced TS/TSX samples in the Starlight docs.",
+    "#",
+    "# Usage:",
+    "#   .claude/procedures/check-doc-samples.sh <docs-root>",
+    "#",
+    "# Where:",
+    "#   <docs-root> \u2014 path to the markdown content tree",
+    "#                 (e.g. `docs/src/content/docs`). Walked recursively",
+    "#                 for `*.md` files.",
+    "#",
+    "# Wraps the `compileFencedSamples` API exported from",
+    "# `@codedrifters/configulator`. For every fenced ` ```ts `,",
+    "# ` ```typescript `, ` ```tsx `, or ` ```typescriptreact ` block in",
+    "# the docs, the helper writes the sample to an in-memory file,",
+    "# runs the TypeScript compiler against it (in-process, via the TS",
+    "# compiler API), and reports any compilation diagnostics.",
+    "#",
+    "# Skipped samples (fence meta `skip` / `no-check`, or first line",
+    "# `// @no-check`) are passed through unchecked.",
+    "#",
+    "# Output (stdout, single JSON array):",
+    "#",
+    "#   [",
+    "#     {",
+    '#       "docPath":     "<path relative to <docs-root>>",',
+    '#       "line":        <1-indexed line number of the opening fence>,',
+    '#       "fenceIndex":  <0-indexed fenced-block position within the doc>,',
+    '#       "lang":        "ts" | "typescript" | "tsx" | "typescriptreact",',
+    '#       "diagnostics": [ "<TS<code>: <message>>", ... ]',
+    "#     },",
+    "#     ...",
+    "#   ]",
+    "#",
+    "# An empty array (`[]`) is emitted when every sample compiled.",
+    "# Detection is **data**, not failure: this helper exits 0 when the",
+    "# compilation phase ran successfully, regardless of how many",
+    "# samples failed to compile. The downstream docs-sync scan phase",
+    "# (#520) is responsible for treating failures as one of the two",
+    "# hard-block cases per the parent epic.",
+    "#",
+    "# Exit codes:",
+    "#   0  \u2014 compilation phase ran; failures (zero or more) are on",
+    "#        stdout as a JSON array.",
+    "#   1  \u2014 usage error (missing args, unreadable docs root).",
+    "#   2  \u2014 a required binary is not on PATH (`node` / `pnpm`).",
+    "#   3  \u2014 the compilation phase threw an unhandled exception.",
+    "#        Stderr carries the diagnostic.",
+    "#",
+    "# Dependencies: expects `node` and `pnpm` on PATH and the workspace",
+    "# `@codedrifters/configulator` package to be installed (the helper",
+    "# resolves the API through `pnpm exec node` from the repo root).",
+    "",
+    "set -uo pipefail",
+    "",
+    "err() {",
+    '  printf "check-doc-samples.sh: %s\\n" "$*" >&2',
+    "}",
+    "",
+    'if [ "$#" -lt 1 ]; then',
+    '  err "usage: check-doc-samples.sh <docs-root>"',
+    "  exit 1",
+    "fi",
+    "",
+    'docs_root="$1"',
+    "",
+    'if [ ! -d "$docs_root" ]; then',
+    '  err "docs root not found: $docs_root"',
+    "  exit 1",
+    "fi",
+    "",
+    "if ! command -v node >/dev/null 2>&1; then",
+    '  err "node is required but not on PATH"',
+    "  exit 2",
+    "fi",
+    "",
+    "if ! command -v pnpm >/dev/null 2>&1; then",
+    '  err "pnpm is required but not on PATH"',
+    "  exit 2",
+    "fi",
+    "",
+    "# Resolve docs_root to an absolute path so the inline node script",
+    "# is independent of the cwd `pnpm exec` chooses.",
+    'docs_root_abs="$(cd "$docs_root" && pwd)"',
+    "",
+    "# Run the inline node script through `pnpm exec` so module",
+    "# resolution finds `@codedrifters/configulator` via the workspace",
+    "# even when the helper is invoked from a sub-package directory.",
+    "# The `--input-type=module` flag lets us use top-level `await` and",
+    "# `import()` cleanly. Diagnostics from the script flow to stderr;",
+    "# stdout carries only the JSON array.",
+    'pnpm exec node --input-type=module -e "' + nodeScript.replace(/"/g, '\\"') + '" "$docs_root_abs"',
+    "status=$?",
+    "",
+    'if [ "$status" -ne 0 ]; then',
+    '  err "compileFencedSamples exited with status $status"',
+    "  exit 3",
+    "fi",
+    "",
+    "exit 0"
+  ].join("\n");
+}
+var checkDocSamplesProcedure = {
+  name: "check-doc-samples.sh",
+  description: "Fenced-sample compilation checker that wraps the `compileFencedSamples` API and emits a JSON-array stream of { docPath, line, fenceIndex, lang, diagnostics } failure records. Skipped samples (meta `skip`/`no-check`, or first-line `// @no-check`) are passed through unchecked. Detection is data: the helper exits 0 whenever compilation ran successfully regardless of failure count.",
+  content: renderCheckDocSamplesProcedure()
+};
 function buildDocsSyncBundle(paths = DEFAULT_AGENT_PATHS) {
   return {
     name: "docs-sync",
@@ -9027,7 +9444,11 @@ function buildDocsSyncBundle(paths = DEFAULT_AGENT_PATHS) {
     ],
     skills: [buildDocsSyncPrSkill(), buildDocsSyncAuditSkill()],
     subAgents: [buildDocsSyncSubAgent(paths)],
-    procedures: [extractApiProcedure],
+    procedures: [
+      extractApiProcedure,
+      checkLinksProcedure,
+      checkDocSamplesProcedure
+    ],
     labels: [
       {
         name: "type:docs-sync",
@@ -26771,8 +27192,8 @@ var FALLBACKS = {
   monorepoLayoutSeedBlock: ""
 };
 var TEMPLATE_RE = /\{\{(\w+(?:\.\w+)*)\}\}/g;
-function getNestedValue(obj, path4) {
-  const parts = path4.split(".");
+function getNestedValue(obj, path6) {
+  const parts = path6.split(".");
   let current = obj;
   for (const part of parts) {
     if (current == null || typeof current !== "object") {
@@ -26998,20 +27419,20 @@ var ClaudeRenderer = class _ClaudeRenderer {
       obj.excludedCommands = [...sandbox.excludedCommands];
     }
     if (sandbox.filesystem) {
-      const fs2 = {};
+      const fs3 = {};
       if (sandbox.filesystem.allowRead?.length) {
-        fs2.allowRead = [...sandbox.filesystem.allowRead];
+        fs3.allowRead = [...sandbox.filesystem.allowRead];
       }
       if (sandbox.filesystem.denyRead?.length) {
-        fs2.denyRead = [...sandbox.filesystem.denyRead];
+        fs3.denyRead = [...sandbox.filesystem.denyRead];
       }
       if (sandbox.filesystem.allowWrite?.length) {
-        fs2.allowWrite = [...sandbox.filesystem.allowWrite];
+        fs3.allowWrite = [...sandbox.filesystem.allowWrite];
       }
       if (sandbox.filesystem.denyWrite?.length) {
-        fs2.denyWrite = [...sandbox.filesystem.denyWrite];
+        fs3.denyWrite = [...sandbox.filesystem.denyWrite];
       }
-      if (Object.keys(fs2).length > 0) obj.filesystem = fs2;
+      if (Object.keys(fs3).length > 0) obj.filesystem = fs3;
     }
     if (sandbox.network) {
       const net = {};
@@ -28873,10 +29294,357 @@ function stripYamlFrontmatter(source) {
   return lines.join("\n");
 }
 
-// src/docs-sync/tsdoc-coverage/coverage.ts
+// src/docs-sync/sample-compilation/compilation.ts
+var path4 = __toESM(require("path"));
+var ts = __toESM(require("typescript"));
+
+// src/docs-sync/sample-compilation/extraction.ts
+var fs2 = __toESM(require("fs"));
 var path3 = __toESM(require("path"));
+var import_mdast_util_from_markdown2 = require("mdast-util-from-markdown");
+var SampleLang = {
+  Ts: "ts",
+  Typescript: "typescript",
+  Tsx: "tsx",
+  Typescriptreact: "typescriptreact"
+};
+var DEFAULT_DOCS_ROOT2 = "docs/src/content/docs";
+var PLAIN_LANGS = /* @__PURE__ */ new Set([SampleLang.Ts, SampleLang.Typescript]);
+var JSX_LANGS = /* @__PURE__ */ new Set([
+  SampleLang.Tsx,
+  SampleLang.Typescriptreact
+]);
+function extractFencedSamples(options = {}) {
+  const docsRoot = path3.resolve(options.docsRoot ?? DEFAULT_DOCS_ROOT2);
+  const includeTsx = options.includeTsx ?? true;
+  if (!fs2.existsSync(docsRoot)) {
+    return [];
+  }
+  const records = [];
+  for (const absolutePath of walkMarkdownFiles2(docsRoot)) {
+    const docPath = toPosix2(path3.relative(docsRoot, absolutePath));
+    const source = fs2.readFileSync(absolutePath, "utf-8");
+    const tree = (0, import_mdast_util_from_markdown2.fromMarkdown)(stripYamlFrontmatter2(source));
+    let fenceIndex = 0;
+    collectFencedCode(tree, (node) => {
+      const lang = normalizeLang(node.lang);
+      if (lang === void 0) {
+        return;
+      }
+      if (!includeTsx && JSX_LANGS.has(lang)) {
+        return;
+      }
+      if (!PLAIN_LANGS.has(lang) && !JSX_LANGS.has(lang)) {
+        return;
+      }
+      const start = node.position?.start;
+      if (!start) {
+        return;
+      }
+      const skip = detectSkip(node);
+      records.push({
+        docPath,
+        line: start.line,
+        fenceIndex,
+        lang,
+        code: node.value ?? "",
+        skipped: skip.skipped,
+        skipReason: skip.reason
+      });
+      fenceIndex += 1;
+    });
+  }
+  records.sort((a, b) => {
+    if (a.docPath !== b.docPath) {
+      return a.docPath.localeCompare(b.docPath);
+    }
+    if (a.line !== b.line) {
+      return a.line - b.line;
+    }
+    return a.fenceIndex - b.fenceIndex;
+  });
+  return records;
+}
+function walkMarkdownFiles2(root) {
+  const out = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs2.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path3.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile() && full.toLowerCase().endsWith(".md")) {
+        out.push(full);
+      }
+    }
+  }
+  out.sort();
+  return out;
+}
+function collectFencedCode(tree, visit) {
+  walk(tree);
+  function walk(node) {
+    if (node.type === "code") {
+      visit(node);
+      return;
+    }
+    if (node.type === "html") {
+      return;
+    }
+    const parent = node;
+    if (Array.isArray(parent.children)) {
+      for (const child of parent.children) {
+        walk(child);
+      }
+    }
+  }
+}
+function normalizeLang(raw) {
+  if (!raw) {
+    return void 0;
+  }
+  const lower = raw.toLowerCase();
+  switch (lower) {
+    case "ts":
+      return SampleLang.Ts;
+    case "typescript":
+      return SampleLang.Typescript;
+    case "tsx":
+      return SampleLang.Tsx;
+    case "typescriptreact":
+      return SampleLang.Typescriptreact;
+    default:
+      return void 0;
+  }
+}
+var META_SKIP_PATTERN = /\b(skip|no-check)\b/i;
+var PRAGMA_NO_CHECK_PATTERN = /^\s*\/\/\s*@no-check\b/i;
+function detectSkip(node) {
+  const meta = node.meta ?? "";
+  const metaMatch = META_SKIP_PATTERN.exec(meta);
+  if (metaMatch) {
+    return { skipped: true, reason: `meta:${metaMatch[1].toLowerCase()}` };
+  }
+  const code = node.value ?? "";
+  const firstLine = firstNonBlankLine(code);
+  if (firstLine !== void 0 && PRAGMA_NO_CHECK_PATTERN.test(firstLine)) {
+    return { skipped: true, reason: "pragma:@no-check" };
+  }
+  return { skipped: false, reason: "" };
+}
+function firstNonBlankLine(source) {
+  for (const line of source.split("\n")) {
+    if (line.trim().length > 0) {
+      return line;
+    }
+  }
+  return void 0;
+}
+function toPosix2(p) {
+  return p.split(path3.sep).join("/");
+}
+function stripYamlFrontmatter2(source) {
+  if (!source.startsWith("---")) {
+    return source;
+  }
+  const lines = source.split("\n");
+  if (lines[0] !== "---") {
+    return source;
+  }
+  let endIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") {
+      endIndex = i;
+      break;
+    }
+  }
+  if (endIndex < 0) {
+    return source;
+  }
+  for (let i = 0; i <= endIndex; i++) {
+    lines[i] = "";
+  }
+  return lines.join("\n");
+}
+
+// src/docs-sync/sample-compilation/compilation.ts
+var DEFAULT_SAMPLE_COMPILER_OPTIONS = {
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  lib: ["lib.es2022.d.ts", "lib.dom.d.ts"],
+  strict: true,
+  noUnusedLocals: false,
+  noUnusedParameters: false,
+  skipLibCheck: true,
+  esModuleInterop: true,
+  resolveJsonModule: true,
+  isolatedModules: true,
+  jsx: ts.JsxEmit.Preserve,
+  noEmit: true,
+  allowSyntheticDefaultImports: true
+};
+var REPO_RELATIVE_MODULE_PATTERN = /^['"](?:\.\.?\/|\/)/;
+function compileFencedSamples(options = {}) {
+  const samples = extractFencedSamples(options);
+  const tolerateRepoRelative = options.tolerateRepoRelativeMissingModule ?? true;
+  const failures = [];
+  for (const sample of samples) {
+    if (sample.skipped) {
+      continue;
+    }
+    const diagnostics = compileSingleSample(
+      sample,
+      options.compilerOptions,
+      tolerateRepoRelative
+    );
+    if (diagnostics.length > 0) {
+      failures.push({
+        docPath: sample.docPath,
+        line: sample.line,
+        fenceIndex: sample.fenceIndex,
+        lang: sample.lang,
+        diagnostics
+      });
+    }
+  }
+  return failures;
+}
+function compileSingleSample(sample, overrides, tolerateRepoRelative) {
+  const filename = sampleFilename(sample);
+  const compilerOptions = mergeCompilerOptions(overrides);
+  const host = createSingleFileHost(filename, sample.code, compilerOptions);
+  const program = ts.createProgram({
+    rootNames: [filename],
+    options: compilerOptions,
+    host
+  });
+  const sourceFile = program.getSourceFile(filename);
+  const collected = [];
+  if (sourceFile) {
+    collected.push(...program.getSyntacticDiagnostics(sourceFile));
+    collected.push(...program.getSemanticDiagnostics(sourceFile));
+  } else {
+    collected.push(...program.getSyntacticDiagnostics());
+    collected.push(...program.getSemanticDiagnostics());
+  }
+  const diagnostics = [];
+  for (const d of collected) {
+    if (tolerateRepoRelative && isRepoRelativeMissingModule(d, sample.code)) {
+      continue;
+    }
+    diagnostics.push(formatDiagnostic(d));
+  }
+  return diagnostics;
+}
+function sampleFilename(sample) {
+  const safeDoc = sample.docPath.replace(/[^a-zA-Z0-9]+/g, "_");
+  const ext = sample.lang === SampleLang.Tsx || sample.lang === SampleLang.Typescriptreact ? "tsx" : "ts";
+  return path4.posix.join("/", `${safeDoc}__${sample.fenceIndex}.${ext}`);
+}
+function mergeCompilerOptions(overrides) {
+  if (!overrides) {
+    return { ...DEFAULT_SAMPLE_COMPILER_OPTIONS };
+  }
+  const merged = { ...DEFAULT_SAMPLE_COMPILER_OPTIONS };
+  for (const key of Object.keys(overrides)) {
+    const value = overrides[key];
+    if (value === void 0) {
+      delete merged[key];
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+function createSingleFileHost(filename, source, compilerOptions) {
+  const baseHost = ts.createCompilerHost(compilerOptions, true);
+  return {
+    ...baseHost,
+    getSourceFile(name, languageVersionOrOptions, onError, shouldCreate) {
+      if (name === filename) {
+        return ts.createSourceFile(
+          name,
+          source,
+          languageVersionOrOptions,
+          true
+        );
+      }
+      return baseHost.getSourceFile(
+        name,
+        languageVersionOrOptions,
+        onError,
+        shouldCreate
+      );
+    },
+    fileExists(name) {
+      if (name === filename) {
+        return true;
+      }
+      return baseHost.fileExists(name);
+    },
+    readFile(name) {
+      if (name === filename) {
+        return source;
+      }
+      return baseHost.readFile(name);
+    },
+    writeFile() {
+    },
+    getCanonicalFileName(name) {
+      return baseHost.getCanonicalFileName(name);
+    },
+    useCaseSensitiveFileNames() {
+      return baseHost.useCaseSensitiveFileNames();
+    },
+    getNewLine() {
+      return baseHost.getNewLine();
+    },
+    getDefaultLibFileName(o) {
+      return baseHost.getDefaultLibFileName(o);
+    },
+    getCurrentDirectory() {
+      return baseHost.getCurrentDirectory();
+    }
+  };
+}
+function isRepoRelativeMissingModule(d, code) {
+  if (d.code !== 2307) {
+    return false;
+  }
+  const text = ts.flattenDiagnosticMessageText(d.messageText, "\n");
+  const match = /'([^']+)'/.exec(text);
+  if (!match) {
+    return false;
+  }
+  const specifier = match[1];
+  if (!specifier) {
+    return false;
+  }
+  const inSourceSingle = `'${specifier}'`;
+  const inSourceDouble = `"${specifier}"`;
+  if (!code.includes(inSourceSingle) && !code.includes(inSourceDouble)) {
+    return false;
+  }
+  return REPO_RELATIVE_MODULE_PATTERN.test(`'${specifier}'`);
+}
+function formatDiagnostic(d) {
+  const text = ts.flattenDiagnosticMessageText(d.messageText, " ");
+  const code = d.code === void 0 ? "" : `TS${d.code}: `;
+  return `${code}${text}`.trim();
+}
+
+// src/docs-sync/tsdoc-coverage/coverage.ts
+var path5 = __toESM(require("path"));
 var import_tsdoc = require("@microsoft/tsdoc");
-var ts = __toESM(require("typescript"));
+var ts2 = __toESM(require("typescript"));
 var TsDocCoverageKind = {
   Class: "Class",
   Interface: "Interface",
@@ -28892,8 +29660,8 @@ var DEFAULT_THIN_SUMMARY_WORD_THRESHOLD = 4;
 var DEFAULT_ENTRY_POINT = "src/index.ts";
 function analyzeTsDocCoverage(options) {
   const resolvedOptions = typeof options === "string" ? { packageRoot: options } : options;
-  const packageRoot = path3.resolve(resolvedOptions.packageRoot);
-  const entryPoint = path3.resolve(
+  const packageRoot = path5.resolve(resolvedOptions.packageRoot);
+  const entryPoint = path5.resolve(
     packageRoot,
     resolvedOptions.entryPoint ?? DEFAULT_ENTRY_POINT
   );
@@ -28902,7 +29670,7 @@ function analyzeTsDocCoverage(options) {
     packageRoot,
     resolvedOptions.tsconfigPath
   );
-  const program = ts.createProgram({
+  const program = ts2.createProgram({
     rootNames: [entryPoint],
     options: compilerOptions
   });
@@ -28956,24 +29724,24 @@ function analyzeTsDocCoverage(options) {
 }
 function resolveCompilerOptions(packageRoot, tsconfigPath) {
   if (tsconfigPath) {
-    const absoluteTsconfig = path3.resolve(packageRoot, tsconfigPath);
-    const configFile = ts.readConfigFile(absoluteTsconfig, ts.sys.readFile);
+    const absoluteTsconfig = path5.resolve(packageRoot, tsconfigPath);
+    const configFile = ts2.readConfigFile(absoluteTsconfig, ts2.sys.readFile);
     if (configFile.error) {
       throw new Error(
-        `analyzeTsDocCoverage: failed to read tsconfig at ${absoluteTsconfig}: ${ts.flattenDiagnosticMessageText(configFile.error.messageText, "\n")}`
+        `analyzeTsDocCoverage: failed to read tsconfig at ${absoluteTsconfig}: ${ts2.flattenDiagnosticMessageText(configFile.error.messageText, "\n")}`
       );
     }
-    const parsed = ts.parseJsonConfigFileContent(
+    const parsed = ts2.parseJsonConfigFileContent(
       configFile.config,
-      ts.sys,
-      path3.dirname(absoluteTsconfig)
+      ts2.sys,
+      path5.dirname(absoluteTsconfig)
     );
     return { ...parsed.options, noEmit: true };
   }
   return {
-    target: ts.ScriptTarget.ESNext,
-    module: ts.ModuleKind.NodeNext,
-    moduleResolution: ts.ModuleResolutionKind.NodeNext,
+    target: ts2.ScriptTarget.ESNext,
+    module: ts2.ModuleKind.NodeNext,
+    moduleResolution: ts2.ModuleResolutionKind.NodeNext,
     allowJs: false,
     declaration: false,
     noEmit: true,
@@ -28998,7 +29766,7 @@ function resolveAlias(symbol, checker) {
   return current;
 }
 function isAlias(symbol) {
-  return (symbol.flags & ts.SymbolFlags.Alias) !== 0;
+  return (symbol.flags & ts2.SymbolFlags.Alias) !== 0;
 }
 function pickPrimaryDeclaration(symbol) {
   const declarations = symbol.getDeclarations();
@@ -29006,53 +29774,53 @@ function pickPrimaryDeclaration(symbol) {
     return void 0;
   }
   const concrete = declarations.find(
-    (d) => !ts.isExportSpecifier(d) && !ts.isExportAssignment(d) && !ts.isExportDeclaration(d)
+    (d) => !ts2.isExportSpecifier(d) && !ts2.isExportAssignment(d) && !ts2.isExportDeclaration(d)
   );
   return concrete ?? declarations[0];
 }
 function classifyDeclaration(declaration) {
-  if (ts.isClassDeclaration(declaration)) {
+  if (ts2.isClassDeclaration(declaration)) {
     return TsDocCoverageKind.Class;
   }
-  if (ts.isInterfaceDeclaration(declaration)) {
+  if (ts2.isInterfaceDeclaration(declaration)) {
     return TsDocCoverageKind.Interface;
   }
-  if (ts.isTypeAliasDeclaration(declaration)) {
+  if (ts2.isTypeAliasDeclaration(declaration)) {
     return TsDocCoverageKind.TypeAlias;
   }
-  if (ts.isEnumDeclaration(declaration)) {
+  if (ts2.isEnumDeclaration(declaration)) {
     return TsDocCoverageKind.Enum;
   }
-  if (ts.isFunctionDeclaration(declaration) || ts.isMethodDeclaration(declaration)) {
+  if (ts2.isFunctionDeclaration(declaration) || ts2.isMethodDeclaration(declaration)) {
     return TsDocCoverageKind.Function;
   }
-  if (ts.isVariableDeclaration(declaration) || ts.isVariableStatement(declaration)) {
+  if (ts2.isVariableDeclaration(declaration) || ts2.isVariableStatement(declaration)) {
     return TsDocCoverageKind.Variable;
   }
-  if (ts.isModuleDeclaration(declaration)) {
+  if (ts2.isModuleDeclaration(declaration)) {
     return TsDocCoverageKind.Module;
   }
-  if (ts.isExportAssignment(declaration)) {
+  if (ts2.isExportAssignment(declaration)) {
     return TsDocCoverageKind.Default;
   }
   return TsDocCoverageKind.Other;
 }
 function resolveLocation(declaration) {
-  const target = ts.isVariableDeclaration(declaration) ? declaration.parent.parent ?? declaration : declaration;
+  const target = ts2.isVariableDeclaration(declaration) ? declaration.parent.parent ?? declaration : declaration;
   const source = target.getSourceFile();
   const { line } = source.getLineAndCharacterOfPosition(target.getStart());
   return { file: source.fileName, line: line + 1 };
 }
 function parseTsDocFor(declaration, parser) {
-  const target = ts.isVariableDeclaration(declaration) ? declaration.parent.parent ?? declaration : declaration;
+  const target = ts2.isVariableDeclaration(declaration) ? declaration.parent.parent ?? declaration : declaration;
   const sourceText = target.getSourceFile().getFullText();
-  const ranges = ts.getLeadingCommentRanges(sourceText, target.getFullStart());
+  const ranges = ts2.getLeadingCommentRanges(sourceText, target.getFullStart());
   if (!ranges || ranges.length === 0) {
     return void 0;
   }
   for (let i = ranges.length - 1; i >= 0; i--) {
     const range = ranges[i];
-    if (range.kind !== ts.SyntaxKind.MultiLineCommentTrivia) {
+    if (range.kind !== ts2.SyntaxKind.MultiLineCommentTrivia) {
       continue;
     }
     const text = sourceText.slice(range.pos, range.end);
@@ -29275,14 +30043,14 @@ var LAYOUT_ROOT_BY_PROJECT_TYPE = {
 };
 function validateMonorepoLayout(root) {
   const violations = [];
-  const rootOutdir = toPosix2(root.outdir);
+  const rootOutdir = toPosix3(root.outdir);
   for (const sub of root.subprojects) {
     const className = sub.constructor.name;
     const expectedRoot = expectedRootFor(sub, className);
     if (expectedRoot === void 0) {
       continue;
     }
-    const relOutdir = relativeOutdir(rootOutdir, toPosix2(sub.outdir));
+    const relOutdir = relativeOutdir(rootOutdir, toPosix3(sub.outdir));
     if (!outdirMatchesRoot(relOutdir, expectedRoot)) {
       violations.push({
         projectName: sub.name,
@@ -29341,7 +30109,7 @@ function outdirMatchesRoot(relOutdir, expectedRoot) {
   }
   return segments.length >= 2;
 }
-function toPosix2(p) {
+function toPosix3(p) {
   return p.replace(/\\/g, "/");
 }
 function relativeOutdir(rootOutdir, subOutdir) {
@@ -29421,8 +30189,8 @@ var ResetTask = class _ResetTask extends import_projen14.Component {
     const resetTask = this.project.tasks.addTask(this.taskName, {
       description: "Delete build artifacts specified by pathsToRemove option, or artifactsDirectory if pathsToRemove is empty"
     });
-    this.pathsToRemove.forEach((path4) => {
-      resetTask.exec(`[ -e "${path4}" ] && rm -rf ${path4} || true`);
+    this.pathsToRemove.forEach((path6) => {
+      resetTask.exec(`[ -e "${path6}" ] && rm -rf ${path6} || true`);
     });
     const rootHasTurbo = TurboRepo.of(this.project.root) !== void 0;
     const isSubproject = this.project !== this.project.root;
@@ -31404,6 +32172,7 @@ var TypeScriptConfig = class extends import_projen23.Component {
   DEFAULT_PROGRESS_FILES_STATE_DIR,
   DEFAULT_REQUIRE_LINKED_ISSUE,
   DEFAULT_REQUIRE_PRODUCT_CONTEXT,
+  DEFAULT_SAMPLE_COMPILER_OPTIONS,
   DEFAULT_SCHEDULED_TASKS_ROOT,
   DEFAULT_SCHEDULED_TASK_ENTRIES,
   DEFAULT_SHARED_EDITING_CONFLICT_STRATEGY,
@@ -31449,6 +32218,7 @@ var TypeScriptConfig = class extends import_projen23.Component {
   SCOPE_CLASS_VALUES,
   SHARED_EDITING_CONFLICT_STRATEGY_VALUES,
   STARLIGHT_ROLE,
+  SampleLang,
   StarlightProject,
   TestRunner,
   TsDocCoverageKind,
@@ -31491,13 +32261,17 @@ var TypeScriptConfig = class extends import_projen23.Component {
   buildStandardsResearchBundle,
   buildUnblockDependentsProcedure,
   businessModelsBundle,
+  checkDocSamplesProcedure,
+  checkLinksProcedure,
   classifyIssueScope,
   classifyRun,
   companyProfileBundle,
+  compileFencedSamples,
   customerProfileBundle,
   docsSyncBundle,
   extractApiProcedure,
   extractDocReferences,
+  extractFencedSamples,
   formatLayoutViolation,
   formatStarlightSingletonViolation,
   getLatestEligibleVersion,
@@ -31514,6 +32288,8 @@ var TypeScriptConfig = class extends import_projen23.Component {
   regulatoryResearchBundle,
   renderAgentTierCaseStatement,
   renderAgentTierSection,
+  renderCheckDocSamplesProcedure,
+  renderCheckLinksProcedure,
   renderCustomDocSectionBlock,
   renderCustomDocSections,
   renderExtractApiProcedure,