@brandon_m_behring/book-scaffold-astro 4.14.3 → 4.15.0

package/components/CodeBlock.astro

@@ -4,9 +4,9 @@
  * build time, with syntax highlighting and a "View on GitHub" header
  * link pointing to the exact line range.
  *
- * Reads the file from the repo root (resolved relative to
- * guides/web/), slices `lines` ("N-M" or "N"), and hands the snippet
- * to Astro's `<Code>` component for Shiki rendering.
+ * Reads the file from the code repo root (the consumer's project root by
+ * default; set BOOK_REPO_ROOT for a monorepo subdir layout), slices `lines`
+ * ("N-M" or "N"), and hands the snippet to Astro's `<Code>` for Shiki.
  *
  * Build fails if:
  *   - The file does not exist on disk
@@ -28,6 +28,7 @@ import { Code } from 'astro:components';
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { buildGithubUrl } from '../src/lib/repo-url';
+import bookConfig from 'virtual:book-scaffold/book-config';
 
 interface Props {
   src: string;
@@ -37,11 +38,15 @@ interface Props {
 
 const { src, lines, lang } = Astro.props;
 
-// Resolve src relative to repo root. Astro's build runs with cwd =
-// guides/web/, so the repo root is two levels up. Using process.cwd()
+// #109: resolve src relative to the code repo root. Defaults to the consumer's
+// project root (process.cwd() during astro build — book + code in one repo);
+// set BOOK_REPO_ROOT when the code lives elsewhere (e.g. a monorepo where the
+// book is a subdir, the old guides/web/ → '../..' case). Using an env + cwd
 // (not import.meta.dirname) survives Astro's bundling — at runtime
 // import.meta.dirname points to the emitted .mjs chunk, not the source.
-const REPO_ROOT = resolve(process.cwd(), '..', '..');
+const REPO_ROOT = process.env.BOOK_REPO_ROOT
+  ? resolve(process.env.BOOK_REPO_ROOT)
+  : process.cwd();
 const absPath = resolve(REPO_ROOT, src);
 
 if (!existsSync(absPath)) {
@@ -102,7 +107,15 @@ const inferLang = (path: string): string => {
 
 const language = (lang ?? inferLang(src)) as Parameters<typeof Code>[0]['lang'];
 
-const githubUrl = buildGithubUrl(src, startLine, endLine);
+// #109: fail loud rather than link the wrong repo (see CodeRef for the rationale).
+if (!bookConfig.githubRepo) {
+  throw new Error(
+    `<CodeBlock src="${src}">: no GitHub repo resolved. Set githubRepo in ` +
+      `defineBookConfig(), or add a "repository" field to package.json (or an ` +
+      `origin git remote) so the scaffold can auto-detect owner/repo.`,
+  );
+}
+const githubUrl = buildGithubUrl(bookConfig.githubRepo, bookConfig.githubBranch, src, startLine, endLine);
 const rangeText = startLine === endLine ? `:${startLine}` : `:${startLine}-${endLine}`;
 const displayPath = `${src}${rangeText}`;
 ---

package/components/CodeRef.astro

@@ -1,7 +1,8 @@
 ---
 /**
  * CodeRef — inline reference to a specific file (and optional line range)
- * in the post_transformers repo on GitHub.
+ * in the book's GitHub repo (resolved per book — #109: defineBookConfig
+ * `githubRepo`, else auto-detected from package.json / git remote).
  *
  * Maps the LaTeX `\code{path:N}` and `\path{path}` idioms (which only
  * styled monospace text) to a real hyperlink that lands the reader on
@@ -26,6 +27,7 @@
  * synthesized.
  */
 import { buildGithubUrl } from '../src/lib/repo-url';
+import bookConfig from 'virtual:book-scaffold/book-config';
 
 interface Props {
   path: string;
@@ -34,7 +36,18 @@ interface Props {
 }
 
 const { path, line, lineEnd } = Astro.props;
-const url = buildGithubUrl(path, line, lineEnd);
+
+// #109: fail loud rather than link to the wrong repo. `githubRepo` is null
+// only when neither defineBookConfig({ githubRepo }) nor auto-detection
+// (package.json repository / git remote) resolved one.
+if (!bookConfig.githubRepo) {
+  throw new Error(
+    `<CodeRef path="${path}">: no GitHub repo resolved. Set githubRepo in ` +
+      `defineBookConfig(), or add a "repository" field to package.json (or an ` +
+      `origin git remote) so the scaffold can auto-detect owner/repo.`,
+  );
+}
+const url = buildGithubUrl(bookConfig.githubRepo, bookConfig.githubBranch, path, line, lineEnd);
 const hasSlot = await Astro.slots.has('default');
 const basename = path.split('/').pop() ?? path;
 const defaultText =

package/components/PocLayout.astro

@@ -11,12 +11,20 @@
  * Closed `kind` union: discriminated literal type. To add a 6th kind in
  * a future release, expand the union + add a CSS block in poc-layouts.css.
  */
-export type PocLayoutKind = 'tutorial' | 'how-to' | 'tldr' | 'part-summary' | 'cheat-sheet';
+import { assertEnumProp } from '../src/lib/assert-prop';
+
+const POC_LAYOUT_KINDS = ['tutorial', 'how-to', 'tldr', 'part-summary', 'cheat-sheet'] as const;
+export type PocLayoutKind = (typeof POC_LAYOUT_KINDS)[number];
 
 interface Props {
   kind: PocLayoutKind;
 }
-const { kind } = Astro.props;
+// #109 sweep: fail loud on an out-of-union kind instead of emitting a
+// poc-layout-<bogus> class that matches no CSS rule.
+const kind = assertEnumProp(Astro.props.kind, POC_LAYOUT_KINDS, {
+  component: 'PocLayout',
+  prop: 'kind',
+});
 ---
 <div class={`poc-layout poc-layout-${kind}`}>
   <slot />

package/components/Practice.astro

@@ -11,12 +11,21 @@
  *
  * Family: book-genre (cross-profile).
  */
-type Difficulty = '1' | '2' | '3' | '4';
+import { assertEnumProp } from '../src/lib/assert-prop';
+
+const PRACTICE_DIFFICULTIES = ['1', '2', '3', '4'] as const;
+type Difficulty = (typeof PRACTICE_DIFFICULTIES)[number];
 interface Props {
   id: string;
   difficulty: Difficulty;
 }
-const { id, difficulty } = Astro.props;
+const { id } = Astro.props;
+// #109 sweep: coerce (tolerates difficulty={3} numeric usage), then fail loud
+// on anything outside 1-4 instead of rendering empty / NaN diamond markers.
+const difficulty = assertEnumProp(String(Astro.props.difficulty), PRACTICE_DIFFICULTIES, {
+  component: 'Practice',
+  prop: 'difficulty',
+});
 const anchorId = `practice-${id}`;
 const filled = Number.parseInt(difficulty, 10);
 const markers = '◆'.repeat(filled) + '◇'.repeat(4 - filled);

package/components/StatusBadge.astro

@@ -11,14 +11,18 @@
  * Internal frontmatter retains the 7-state value for STATUS.md alignment;
  * this component is the public-facing translator.
  */
-type InternalStatus =
-  | 'implemented'
-  | 'chapter_only'
-  | 'reading_only'
-  | 'prose_only'
-  | 'code_only'
-  | 'scaffolded'
-  | 'planned';
+import { assertEnumProp } from '../src/lib/assert-prop';
+
+const INTERNAL_STATUSES = [
+  'implemented',
+  'chapter_only',
+  'reading_only',
+  'prose_only',
+  'code_only',
+  'scaffolded',
+  'planned',
+] as const;
+type InternalStatus = (typeof INTERNAL_STATUSES)[number];
 
 type PublicStatus = 'published' | 'draft' | 'coming-soon';
 
@@ -42,7 +46,12 @@ interface Props {
   status: InternalStatus;
 }
 
-const { status } = Astro.props;
+// #109 sweep: fail loud on an unknown status instead of rendering an empty
+// badge label (PUBLIC_OF[undefined] -> undefined -> blank).
+const status = assertEnumProp(Astro.props.status, INTERNAL_STATUSES, {
+  component: 'StatusBadge',
+  prop: 'status',
+});
 const publicStatus = PUBLIC_OF[status];
 const label = PUBLIC_LABEL[publicStatus];
 ---

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, r as academicParts, o as Style } from './types-CULHImU4.js';
-export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-CULHImU4.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, r as academicParts, o as Style } from './types-CjOseOSG.js';
+export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-CjOseOSG.js';
 import 'astro/zod';
 
 /**
@@ -252,6 +252,74 @@ interface ResolvedTheoremLabel {
  */
 declare function theoremLabel(props: TheoremLabelProps): ResolvedTheoremLabel;
 
+/**
+ * repo-url — resolve and build GitHub source links for CodeRef / CodeBlock.
+ *
+ * The repo is no longer hardcoded (#109). `buildGithubUrl` takes an explicit
+ * `repo` + `branch`; the integration resolves them per book — from
+ * `defineBookConfig({ githubRepo })` (override), else auto-detected from the
+ * consumer's own `package.json` `repository` (or git remote) via
+ * `parseRepoSlug`. When nothing resolves, the components throw rather than
+ * emit links to the wrong repo (the old silent default was
+ * `brandon-behring/post_transformers`).
+ */
+/** Default branch when a book configures a repo but no branch. */
+declare const DEFAULT_GITHUB_BRANCH = "main";
+/**
+ * Derive an `owner/repo` slug from an npm `repository` field (string or
+ * `{ url }`) or a raw git remote URL. Handles https, ssh, the `git+` prefix,
+ * a trailing `.git`, and the `github:owner/repo` npm shorthand. Returns null
+ * for anything that isn't a recognizable GitHub repo — no silent guess.
+ */
+declare function parseRepoSlug(repository: string | {
+    url?: string;
+} | null | undefined): string | null;
+/** Extract the `origin` remote URL from the text of a `.git/config` file. */
+declare function originUrlFromGitConfig(gitConfigText: string): string | null;
+/**
+ * Resolve a GitHub `owner/repo` by precedence (#109) — the rule that keeps a
+ * book from ever silently linking to the wrong repo:
+ *   1. explicit `override` (defineBookConfig `githubRepo`)
+ *   2. the consumer's `package.json` `repository`
+ *   3. the `origin` remote in `.git/config`
+ *   4. null — the components then throw rather than guess.
+ */
+declare function resolveGithubRepo(sources: {
+    override?: string | null;
+    packageJsonRepository?: string | {
+        url?: string;
+    } | null;
+    gitConfigText?: string | null;
+}): string | null;
+/**
+ * Build a GitHub line-anchor URL for an explicit repo + branch.
+ *   buildGithubUrl('o/r', 'main', 'a/b.py')        -> https://github.com/o/r/blob/main/a/b.py
+ *   buildGithubUrl('o/r', 'main', 'a/b.py', 42)     -> …/a/b.py#L42
+ *   buildGithubUrl('o/r', 'main', 'a/b.py', 42, 58) -> …/a/b.py#L42-L58
+ */
+declare function buildGithubUrl(repo: string, branch: string, path: string, line?: number, lineEnd?: number): string;
+
+/**
+ * assert-prop — shared fail-loud validator for closed-union component props
+ * (#109 / the v4.15.0 parseProps sweep).
+ *
+ * Astro has no runtime prop validation, so a closed-union prop given an
+ * out-of-range value silently produces a broken render — an empty StatusBadge
+ * label, a `poc-layout-<bogus>` class that matches no CSS, NaN difficulty
+ * markers. This is the same silent-degradation class as the #121 Theorem bug.
+ * `assertEnumProp` converts it into a loud, actionable build-time throw.
+ */
+/**
+ * Return `value` when it's one of `allowed`; otherwise throw an actionable
+ * error naming the component, prop, the offending value, and the legal set.
+ * Never returns a fallback — a closed union with no valid value is an authoring
+ * error that should stop the build, not render something wrong.
+ */
+declare function assertEnumProp<T extends string>(value: unknown, allowed: readonly T[], ctx: {
+    component: string;
+    prop: string;
+}): T;
+
 /**
  * src/styles/built-in.ts — toolkit-shipped Styles, one per BookPreset (v4.0.0).
  *
@@ -353,4 +421,4 @@ type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVe
  */
 declare function defineTips(opts: TipsConfigInput): TipsConfig;
 
-export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, type Freshness, type FreshnessStatus, KIND_LABEL, type ResolvedTheoremLabel, Style, THEOREM_KINDS, type TheoremKind, type TheoremLabelProps, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, bookScaffoldIntegration, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, researchPortfolioStyle, theoremLabel, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, KIND_LABEL, type ResolvedTheoremLabel, Style, THEOREM_KINDS, type TheoremKind, type TheoremLabelProps, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, assertEnumProp, bookScaffoldIntegration, buildGithubUrl, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, originUrlFromGitConfig, parseRepoSlug, researchPortfolioStyle, resolveGithubRepo, theoremLabel, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -788,6 +788,8 @@ function resolveProfile(explicit) {
 
 // src/integration.ts
 import { fileURLToPath } from "url";
+import { readFileSync as readFileSync2 } from "fs";
+import { join } from "path";
 
 // src/lib/define-style.ts
 function defineStyle(opts) {
@@ -855,6 +857,44 @@ function normalizeFrontmatterConfig(v) {
   return v;
 }
 
+// src/lib/repo-url.ts
+var DEFAULT_GITHUB_BRANCH = "main";
+function parseRepoSlug(repository) {
+  const raw = typeof repository === "string" ? repository : repository && typeof repository === "object" ? repository.url : void 0;
+  if (!raw || typeof raw !== "string") return null;
+  const s = raw.trim();
+  if (s === "") return null;
+  const shorthand = s.match(/^github:([\w.-]+)\/([\w.-]+?)(?:\.git)?$/i);
+  if (shorthand) return `${shorthand[1]}/${shorthand[2]}`;
+  const m = s.replace(/^git\+/, "").match(/github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:[/#?].*)?$/i);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+function originUrlFromGitConfig(gitConfigText) {
+  const m = gitConfigText.match(/\[remote "origin"\][^[]*?url\s*=\s*(\S+)/);
+  return m ? m[1] : null;
+}
+function resolveGithubRepo(sources) {
+  if (sources.override) return sources.override;
+  const fromPkg = parseRepoSlug(sources.packageJsonRepository ?? null);
+  if (fromPkg) return fromPkg;
+  if (sources.gitConfigText) {
+    const fromGit = parseRepoSlug(originUrlFromGitConfig(sources.gitConfigText));
+    if (fromGit) return fromGit;
+  }
+  return null;
+}
+function buildGithubUrl(repo, branch, path, line, lineEnd) {
+  const cleanPath = path.replace(/^\/+/, "");
+  let url = `https://github.com/${repo}/blob/${branch}/${cleanPath}`;
+  if (line !== void 0) {
+    url += `#L${line}`;
+    if (lineEnd !== void 0 && lineEnd !== line) {
+      url += `-L${lineEnd}`;
+    }
+  }
+  return url;
+}
+
 // src/mdx-components-resolver.ts
 import { existsSync as existsSync2 } from "fs";
 import { resolve } from "path";
@@ -915,6 +955,23 @@ function makeBookConfigVitePlugin(config) {
     }
   };
 }
+function resolveBookGithubRepo(override, consumerRoot) {
+  let packageJsonRepository = null;
+  let gitConfigText = null;
+  try {
+    packageJsonRepository = JSON.parse(readFileSync2(join(consumerRoot, "package.json"), "utf8")).repository ?? null;
+  } catch {
+  }
+  try {
+    gitConfigText = readFileSync2(join(consumerRoot, ".git", "config"), "utf8");
+  } catch {
+  }
+  return resolveGithubRepo({
+    override,
+    packageJsonRepository,
+    gitConfigText
+  });
+}
 var PACKAGE_NAME = "@brandon_m_behring/book-scaffold-astro";
 var ROUTE_REGISTRY = {
   references: { pattern: "/references", file: "references.astro" },
@@ -968,7 +1025,10 @@ function bookScaffoldIntegration(opts) {
     // v4.6.0: book-level author + SEO config, propagated through the
     // (renamed) book-config virtual module to Base.astro + Chapter.astro.
     author,
-    seo
+    seo,
+    // v4.15.0 (#109): optional GitHub repo/branch override for CodeRef/CodeBlock.
+    githubRepo,
+    githubBranch
   } = opts;
   const def = PROFILES[profile];
   const fmNormalized = normalizeFrontmatterConfig(userOverrides.frontmatter);
@@ -1009,6 +1069,8 @@ function bookScaffoldIntegration(opts) {
         }
         const consumerRoot = fileURLToPath(config.root);
         const resolvedMdxPath = resolveMdxComponentsPath(consumerRoot, mdxComponentsModule);
+        const resolvedGithubRepo = resolveBookGithubRepo(githubRepo, consumerRoot);
+        const resolvedGithubBranch = githubBranch ?? DEFAULT_GITHUB_BRANCH;
         const presetLiteral = JSON.stringify(profile);
         const enabledRouteNames = Object.entries(enabledRoutes).filter(([, on]) => on).map(([name]) => name);
         updateConfig({
@@ -1024,7 +1086,9 @@ function bookScaffoldIntegration(opts) {
                 seo: {
                   ogImage: seo?.ogImage ?? null,
                   twitterHandle: seo?.twitterHandle ?? null
-                }
+                },
+                githubRepo: resolvedGithubRepo,
+                githubBranch: resolvedGithubBranch
               })
             ],
             define: {
@@ -1157,7 +1221,10 @@ async function defineBookConfig(opts) {
       // Base.astro + Chapter.astro. `seo.sitemap` is NOT passed through —
       // it's consumed below at config-time by the @astrojs/sitemap call.
       author: opts.author,
-      seo: opts.seo ? { ogImage: opts.seo.ogImage, twitterHandle: opts.seo.twitterHandle } : void 0
+      seo: opts.seo ? { ogImage: opts.seo.ogImage, twitterHandle: opts.seo.twitterHandle } : void 0,
+      // v4.15.0 (#109): repo/branch override; integration auto-detects when undefined.
+      githubRepo: opts.githubRepo,
+      githubBranch: opts.githubBranch
     }),
     ...mergedExtraIntegrations
   ];
@@ -1199,6 +1266,9 @@ async function defineBookConfig(opts) {
     // v4.6.0: strip new book-level SEO opts (author + seo block).
     author: _author,
     seo: _seo,
+    // v4.15.0: strip repo opts so they don't leak into AstroUserConfig.
+    githubRepo: _githubRepo,
+    githubBranch: _githubBranch,
     ...rest
   } = opts;
   void _styles;
@@ -1215,6 +1285,8 @@ async function defineBookConfig(opts) {
   void _portfolio;
   void _author;
   void _seo;
+  void _githubRepo;
+  void _githubBranch;
   const katexExternals = wantsKatex ? [] : ["remark-math", "rehype-katex", "katex"];
   const restVite = rest.vite ?? {};
   const restSsr = restVite.ssr ?? {};
@@ -1294,6 +1366,17 @@ function theoremLabel(props) {
   return { kind: raw, fullLabel };
 }
 
+// src/lib/assert-prop.ts
+function assertEnumProp(value, allowed, ctx) {
+  if (typeof value === "string" && allowed.includes(value)) {
+    return value;
+  }
+  const got = value === void 0 ? "nothing" : JSON.stringify(value);
+  throw new Error(
+    `<${ctx.component}>: ${ctx.prop}=${got} is not one of ${allowed.join(", ")}.`
+  );
+}
+
 // src/styles/built-in.ts
 var academicStyle = defineStyle({
   name: "academic",
@@ -1340,6 +1423,7 @@ export {
   BRANDON_PORTFOLIO_DEFAULT,
   BUILTIN_STYLES,
   BookConfigError,
+  DEFAULT_GITHUB_BRANCH,
   KIND_LABEL,
   THEOREM_KINDS,
   UNKNOWN_PART_ORDINAL,
@@ -1350,7 +1434,9 @@ export {
   academicPartOrdinal,
   academicParts,
   academicStyle,
+  assertEnumProp,
   bookScaffoldIntegration,
+  buildGithubUrl,
   changeKinds,
   changelogSchema,
   chapterSortKey,
@@ -1370,12 +1456,15 @@ export {
   minimalChapterSchema,
   minimalStyle,
   normalizeFrontmatterConfig,
+  originUrlFromGitConfig,
+  parseRepoSlug,
   patternCategories,
   patternsSchema,
   provenanceObject,
   provenanceSchema,
   researchPortfolioChapterSchema,
   researchPortfolioStyle,
+  resolveGithubRepo,
   resolvePreset,
   resolveProfile,
   sourceTiers,

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { g as BookSchemasOptions } from './types-CULHImU4.js';
+import { g as BookSchemasOptions } from './types-CjOseOSG.js';
 import 'astro';
 import 'astro/zod';
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "4.14.3",
+  "version": "4.15.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/src/lib/assert-prop.ts

@@ -0,0 +1,30 @@
+/**
+ * assert-prop — shared fail-loud validator for closed-union component props
+ * (#109 / the v4.15.0 parseProps sweep).
+ *
+ * Astro has no runtime prop validation, so a closed-union prop given an
+ * out-of-range value silently produces a broken render — an empty StatusBadge
+ * label, a `poc-layout-<bogus>` class that matches no CSS, NaN difficulty
+ * markers. This is the same silent-degradation class as the #121 Theorem bug.
+ * `assertEnumProp` converts it into a loud, actionable build-time throw.
+ */
+
+/**
+ * Return `value` when it's one of `allowed`; otherwise throw an actionable
+ * error naming the component, prop, the offending value, and the legal set.
+ * Never returns a fallback — a closed union with no valid value is an authoring
+ * error that should stop the build, not render something wrong.
+ */
+export function assertEnumProp<T extends string>(
+  value: unknown,
+  allowed: readonly T[],
+  ctx: { component: string; prop: string },
+): T {
+  if (typeof value === 'string' && (allowed as readonly string[]).includes(value)) {
+    return value as T;
+  }
+  const got = value === undefined ? 'nothing' : JSON.stringify(value);
+  throw new Error(
+    `<${ctx.component}>: ${ctx.prop}=${got} is not one of ${allowed.join(', ')}.`,
+  );
+}

package/src/lib/repo-url.ts

@@ -1,27 +1,92 @@
 /**
- * Repository URL constants used by CodeRef and CodeBlock components.
+ * repo-url — resolve and build GitHub source links for CodeRef / CodeBlock.
  *
- * Centralized here so renaming the repo or moving branches is a one-file
- * change rather than a hunt across components.
- *
- * If the repo is later mirrored to a different host, update GITHUB_BASE
- * accordingly; the components do not assume GitHub-specific anchor syntax
- * beyond #L<N>-L<M>, which all major hosts (GitHub, GitLab, Codeberg)
- * support.
+ * The repo is no longer hardcoded (#109). `buildGithubUrl` takes an explicit
+ * `repo` + `branch`; the integration resolves them per book — from
+ * `defineBookConfig({ githubRepo })` (override), else auto-detected from the
+ * consumer's own `package.json` `repository` (or git remote) via
+ * `parseRepoSlug`. When nothing resolves, the components throw rather than
+ * emit links to the wrong repo (the old silent default was
+ * `brandon-behring/post_transformers`).
+ */
+
+/** Default branch when a book configures a repo but no branch. */
+export const DEFAULT_GITHUB_BRANCH = 'main';
+
+/**
+ * Derive an `owner/repo` slug from an npm `repository` field (string or
+ * `{ url }`) or a raw git remote URL. Handles https, ssh, the `git+` prefix,
+ * a trailing `.git`, and the `github:owner/repo` npm shorthand. Returns null
+ * for anything that isn't a recognizable GitHub repo — no silent guess.
  */
-export const GITHUB_REPO = 'brandon-behring/post_transformers';
-export const GITHUB_BRANCH = 'main';
-export const GITHUB_BASE = `https://github.com/${GITHUB_REPO}/blob/${GITHUB_BRANCH}`;
+export function parseRepoSlug(
+  repository: string | { url?: string } | null | undefined,
+): string | null {
+  const raw =
+    typeof repository === 'string'
+      ? repository
+      : repository && typeof repository === 'object'
+        ? repository.url
+        : undefined;
+  if (!raw || typeof raw !== 'string') return null;
+  const s = raw.trim();
+  if (s === '') return null;
+
+  // npm shorthand: github:owner/repo
+  const shorthand = s.match(/^github:([\w.-]+)\/([\w.-]+?)(?:\.git)?$/i);
+  if (shorthand) return `${shorthand[1]}/${shorthand[2]}`;
+
+  // https://github.com/owner/repo(.git), git+https://…, ssh git@github.com:owner/repo(.git)
+  const m = s
+    .replace(/^git\+/, '')
+    .match(/github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:[/#?].*)?$/i);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** Extract the `origin` remote URL from the text of a `.git/config` file. */
+export function originUrlFromGitConfig(gitConfigText: string): string | null {
+  const m = gitConfigText.match(/\[remote "origin"\][^[]*?url\s*=\s*(\S+)/);
+  return m ? m[1]! : null;
+}
+
+/**
+ * Resolve a GitHub `owner/repo` by precedence (#109) — the rule that keeps a
+ * book from ever silently linking to the wrong repo:
+ *   1. explicit `override` (defineBookConfig `githubRepo`)
+ *   2. the consumer's `package.json` `repository`
+ *   3. the `origin` remote in `.git/config`
+ *   4. null — the components then throw rather than guess.
+ */
+export function resolveGithubRepo(sources: {
+  override?: string | null;
+  packageJsonRepository?: string | { url?: string } | null;
+  gitConfigText?: string | null;
+}): string | null {
+  if (sources.override) return sources.override;
+  const fromPkg = parseRepoSlug(sources.packageJsonRepository ?? null);
+  if (fromPkg) return fromPkg;
+  if (sources.gitConfigText) {
+    const fromGit = parseRepoSlug(originUrlFromGitConfig(sources.gitConfigText));
+    if (fromGit) return fromGit;
+  }
+  return null;
+}
 
 /**
- * Build a GitHub line-anchor URL.
- *   buildGithubUrl('experiments/jax/week04/s4.py', 42)        -> .../s4.py#L42
- *   buildGithubUrl('experiments/jax/week04/s4.py', 42, 58)    -> .../s4.py#L42-L58
- *   buildGithubUrl('experiments/jax/week04/s4.py')            -> .../s4.py
+ * Build a GitHub line-anchor URL for an explicit repo + branch.
+ *   buildGithubUrl('o/r', 'main', 'a/b.py')        -> https://github.com/o/r/blob/main/a/b.py
+ *   buildGithubUrl('o/r', 'main', 'a/b.py', 42)     -> …/a/b.py#L42
+ *   buildGithubUrl('o/r', 'main', 'a/b.py', 42, 58) -> …/a/b.py#L42-L58
  */
-export function buildGithubUrl(path: string, line?: number, lineEnd?: number): string {
+export function buildGithubUrl(
+  repo: string,
+  branch: string,
+  path: string,
+  line?: number,
+  lineEnd?: number,
+): string {
   const cleanPath = path.replace(/^\/+/, '');
-  let url = `${GITHUB_BASE}/${cleanPath}`;
+  let url = `https://github.com/${repo}/blob/${branch}/${cleanPath}`;
   if (line !== undefined) {
     url += `#L${line}`;
     if (lineEnd !== undefined && lineEnd !== line) {