@codedrifters/configulator 0.0.273 → 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,14 +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,
@@ -334,6 +339,7 @@ __export(index_exports, {
   regulatoryResearchBundle: () => regulatoryResearchBundle,
   renderAgentTierCaseStatement: () => renderAgentTierCaseStatement,
   renderAgentTierSection: () => renderAgentTierSection,
+  renderCheckDocSamplesProcedure: () => renderCheckDocSamplesProcedure,
   renderCheckLinksProcedure: () => renderCheckLinksProcedure,
   renderCustomDocSectionBlock: () => renderCustomDocSectionBlock,
   renderCustomDocSections: () => renderCustomDocSections,
@@ -9269,6 +9275,126 @@ var checkLinksProcedure = {
   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",
@@ -9318,7 +9444,11 @@ function buildDocsSyncBundle(paths = DEFAULT_AGENT_PATHS) {
     ],
     skills: [buildDocsSyncPrSkill(), buildDocsSyncAuditSkill()],
     subAgents: [buildDocsSyncSubAgent(paths)],
-    procedures: [extractApiProcedure, checkLinksProcedure],
+    procedures: [
+      extractApiProcedure,
+      checkLinksProcedure,
+      checkDocSamplesProcedure
+    ],
     labels: [
       {
         name: "type:docs-sync",
@@ -27062,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") {
@@ -27289,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 = {};
@@ -29164,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",
@@ -29183,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
   );
@@ -29193,7 +29670,7 @@ function analyzeTsDocCoverage(options) {
     packageRoot,
     resolvedOptions.tsconfigPath
   );
-  const program = ts.createProgram({
+  const program = ts2.createProgram({
     rootNames: [entryPoint],
     options: compilerOptions
   });
@@ -29247,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,
@@ -29289,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();
@@ -29297,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);
@@ -29566,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,
@@ -29632,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) {
@@ -29712,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;
@@ -31695,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,
@@ -31740,6 +32218,7 @@ var TypeScriptConfig = class extends import_projen23.Component {
   SCOPE_CLASS_VALUES,
   SHARED_EDITING_CONFLICT_STRATEGY_VALUES,
   STARLIGHT_ROLE,
+  SampleLang,
   StarlightProject,
   TestRunner,
   TsDocCoverageKind,
@@ -31782,14 +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,
@@ -31806,6 +32288,7 @@ var TypeScriptConfig = class extends import_projen23.Component {
   regulatoryResearchBundle,
   renderAgentTierCaseStatement,
   renderAgentTierSection,
+  renderCheckDocSamplesProcedure,
   renderCheckLinksProcedure,
   renderCustomDocSectionBlock,
   renderCustomDocSections,