@codedrifters/configulator 0.0.272 → 0.0.273

package/lib/index.mjs

@@ -8737,6 +8737,295 @@ 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 buildDocsSyncBundle(paths = DEFAULT_AGENT_PATHS) {
   return {
     name: "docs-sync",
@@ -8786,7 +9075,7 @@ function buildDocsSyncBundle(paths = DEFAULT_AGENT_PATHS) {
     ],
     skills: [buildDocsSyncPrSkill(), buildDocsSyncAuditSkill()],
     subAgents: [buildDocsSyncSubAgent(paths)],
-    procedures: [extractApiProcedure],
+    procedures: [extractApiProcedure, checkLinksProcedure],
     labels: [
       {
         name: "type:docs-sync",
@@ -31262,6 +31551,7 @@ export {
   buildStandardsResearchBundle,
   buildUnblockDependentsProcedure,
   businessModelsBundle,
+  checkLinksProcedure,
   classifyIssueScope,
   classifyRun,
   companyProfileBundle,
@@ -31285,6 +31575,7 @@ export {
   regulatoryResearchBundle,
   renderAgentTierCaseStatement,
   renderAgentTierSection,
+  renderCheckLinksProcedure,
   renderCustomDocSectionBlock,
   renderCustomDocSections,
   renderExtractApiProcedure,