@tenphi/docs 0.12.0 → 0.15.0

package/README.md

@@ -5,4 +5,26 @@ graph construction, Markdown reference rewriting, and diagnostics for Cookbook.
 
 ```ts
 import { createDocsGraph, defineDocsConfig } from "@tenphi/docs";
+
+const config = defineDocsConfig({
+  content: {
+    localizeRepositoryLinks: true,
+    sources: [
+      { file: "README.md", route: "/" },
+      { glob: "docs/**/*.{md,mdx}", base: "docs" },
+    ],
+  },
+});
+
+const graph = await createDocsGraph({ root: process.cwd(), config });
 ```
+
+The graph validates routes, fragments, navigation, raw HTML policy, and assets
+without mutating source files. It rewrites inline, reference-style, and matched
+absolute repository links; hashes and collects local images/downloads;
+understands trusted MDX syntax; and confines locked npm artifacts to their
+extraction root.
+
+Most applications should install `@tenphi/cookbook`, which combines this engine
+with the supported Astro/Starlight renderer. This package is useful for custom
+tooling, validation, and alternate renderers. Node.js 22.14 or newer is required.

package/dist/config/index.d.ts

@@ -1,4 +1,4 @@
-import { A as NavigationConfig, B as SiteIconConfig, D as HeadConfig, E as EditLinkConfig, G as TypographyPreset, H as ThemePaletteConfig, K as TypographyPresets, N as NavigationTab, O as LocaleConfig, P as NormalizedDocsConfig, R as SearchConfig, T as DocsSource, U as ThemeTokenValue, V as ThemeConfig, W as ThemeTokens, _ as DocsConfig, a as ComponentStyleConfig, c as ComponentsConfig, j as NavigationItem, k as MarkdownConfig, l as ContentConfig, n as BuildConfig, o as ComponentStyles, s as ComponentStylesConfig, t as BrandConfig, u as CookbookComponentName, v as DocsDiagnostic, z as SiteConfig } from "../types-m7SvwRsi.js";
+import { A as NavigationConfig, B as SiteIconConfig, D as HeadConfig, E as EditLinkConfig, G as TypographyPreset, H as ThemePaletteConfig, K as TypographyPresets, M as NavigationPlacement, N as NavigationTab, O as LocaleConfig, P as NormalizedDocsConfig, R as SearchConfig, T as DocsSource, U as ThemeTokenValue, V as ThemeConfig, W as ThemeTokens, _ as DocsConfig, a as ComponentStyleConfig, c as ComponentsConfig, i as COOKBOOK_COMPONENT_SUB_ELEMENTS, j as NavigationItem, k as MarkdownConfig, l as ContentConfig, n as BuildConfig, o as ComponentStyles, r as COOKBOOK_COMPONENT_NAMES, s as ComponentStylesConfig, t as BrandConfig, u as CookbookComponentName, v as DocsDiagnostic, z as SiteConfig } from "../types-B-msp1dH.js";
 //#region src/config/index.d.ts
 declare class DocsConfigError extends Error {
   readonly diagnostics: DocsDiagnostic[];
@@ -6,7 +6,9 @@ declare class DocsConfigError extends Error {
 }
 declare function validateConfig(config: DocsConfig): DocsDiagnostic[];
 declare function normalizeDocsConfig(config?: DocsConfig): NormalizedDocsConfig;
-declare function defineDocsConfig<const T extends DocsConfig>(config: T): T;
+declare function defineDocsConfig(config: DocsConfig): DocsConfig;
+/** Compose presets. Objects merge, arrays replace, and styles use Tasty semantics. */
+declare function mergeDocsConfig(...configs: DocsConfig[]): DocsConfig;
 //#endregion
-export { type BrandConfig, type BuildConfig, type ComponentStyleConfig, type ComponentStyles, type ComponentStylesConfig, type ComponentsConfig, type ContentConfig, type CookbookComponentName, type DocsConfig, DocsConfigError, type DocsSource, type EditLinkConfig, type HeadConfig, type LocaleConfig, type MarkdownConfig, type NavigationConfig, type NavigationItem, type NavigationTab, type NormalizedDocsConfig, type SearchConfig, type SiteConfig, type SiteIconConfig, type ThemeConfig, type ThemePaletteConfig, type ThemeTokenValue, type ThemeTokens, type TypographyPreset, type TypographyPresets, defineDocsConfig, normalizeDocsConfig, validateConfig };
+export { type BrandConfig, type BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, type ComponentStyleConfig, type ComponentStyles, type ComponentStylesConfig, type ComponentsConfig, type ContentConfig, type CookbookComponentName, type DocsConfig, DocsConfigError, type DocsSource, type EditLinkConfig, type HeadConfig, type LocaleConfig, type MarkdownConfig, type NavigationConfig, type NavigationItem, type NavigationPlacement, type NavigationTab, type NormalizedDocsConfig, type SearchConfig, type SiteConfig, type SiteIconConfig, type ThemeConfig, type ThemePaletteConfig, type ThemeTokenValue, type ThemeTokens, type TypographyPreset, type TypographyPresets, defineDocsConfig, mergeDocsConfig, normalizeDocsConfig, validateConfig };
 //# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/config/index.ts"],"mappings":";;cAoEa,wBAAwB;WAC1B,aAAa;EAEtB,YAAY,aAAa;;iBAOX,eAAe,QAAQ,aAAa;iBA0OpC,oBACd,SAAQ,aACP;iBA6Ca,uBAAuB,UAAU,YAAY,QAAQ,IAAI"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/config/index.ts"],"mappings":";;cAyEa,wBAAwB;WAC1B,aAAa;EAEtB,YAAY,aAAa;;iBAOX,eAAe,QAAQ,aAAa;iBA4iBpC,oBACd,SAAQ,aACP;iBA4Ca,iBAAiB,QAAQ,aAAa;;iBAOtC,mBAAmB,SAAS,eAAe"}

package/dist/config/index.js

@@ -1,240 +1,2 @@
-//#region src/config/index.ts
-const DEFAULT_BRAND = "#315efb";
-const HEAD_KEYS = /* @__PURE__ */ new Set([
-	"tag",
-	"attrs",
-	"content"
-]);
-const SITE_ICON_KEYS = /* @__PURE__ */ new Set(["source", "background"]);
-const ROOT_KEYS = /* @__PURE__ */ new Set([
-	"site",
-	"head",
-	"editLink",
-	"lastUpdated",
-	"locales",
-	"defaultLocale",
-	"content",
-	"navigation",
-	"theme",
-	"markdown",
-	"search",
-	"components",
-	"build"
-]);
-const OBJECT_KEYS = {
-	site: /* @__PURE__ */ new Set([
-		"title",
-		"version",
-		"description",
-		"url",
-		"repository",
-		"favicon"
-	]),
-	content: /* @__PURE__ */ new Set([
-		"sources",
-		"allowOutsideRoot",
-		"localizeRepositoryLinks"
-	]),
-	markdown: /* @__PURE__ */ new Set([
-		"stripLeadingBadges",
-		"rawHtml",
-		"strictLanguages",
-		"executablePreviews",
-		"remarkPlugins",
-		"rehypePlugins"
-	]),
-	search: /* @__PURE__ */ new Set(["enabled"]),
-	components: /* @__PURE__ */ new Set(["overrides"]),
-	theme: /* @__PURE__ */ new Set([
-		"variant",
-		"brand",
-		"palette",
-		"states",
-		"tokens",
-		"presets",
-		"styles",
-		"contrastLevel"
-	]),
-	build: /* @__PURE__ */ new Set([
-		"strict",
-		"ci",
-		"base",
-		"cacheDir",
-		"maxArtifactBytes",
-		"maxUnpackedBytes",
-		"maxFiles",
-		"maxPathDepth",
-		"maxAssetBytes"
-	])
-};
-var DocsConfigError = class extends Error {
-	diagnostics;
-	constructor(diagnostics) {
-		super(diagnostics.map((diagnostic) => diagnostic.message).join("\n"));
-		this.name = "DocsConfigError";
-		this.diagnostics = diagnostics;
-	}
-};
-function validateConfig(config) {
-	const diagnostics = [];
-	for (const key of Object.keys(config)) if (!ROOT_KEYS.has(key)) unknown(diagnostics, key);
-	for (const [section, keys] of Object.entries(OBJECT_KEYS)) {
-		const value = config[section];
-		if (value === void 0 || Array.isArray(value) || typeof value !== "object") continue;
-		for (const key of Object.keys(value)) if (!keys.has(key)) unknown(diagnostics, `${section}.${key}`);
-	}
-	const head = config.head;
-	if (head !== void 0 && !Array.isArray(head)) invalid(diagnostics, "head must be an array.");
-	else for (const [index, entry] of (head ?? []).entries()) {
-		if (!isRecord(entry)) {
-			invalid(diagnostics, `head[${index}] must be an object.`);
-			continue;
-		}
-		for (const key of Object.keys(entry)) if (!HEAD_KEYS.has(key)) unknown(diagnostics, `head[${index}].${key}`);
-		if (typeof entry.tag !== "string") invalid(diagnostics, `head[${index}].tag must be a string.`);
-		if (entry.attrs !== void 0 && !isRecord(entry.attrs)) invalid(diagnostics, `head[${index}].attrs must be an object.`);
-		else for (const [name, value] of Object.entries(entry.attrs ?? {})) if (value !== void 0 && typeof value !== "string" && typeof value !== "boolean") invalid(diagnostics, `head[${index}].attrs.${name} must be a string or boolean.`);
-		if (entry.content !== void 0 && typeof entry.content !== "string") invalid(diagnostics, `head[${index}].content must be a string.`);
-	}
-	const favicon = config.site?.favicon;
-	if (favicon !== void 0) {
-		if (typeof favicon === "string") {
-			if (favicon.trim() === "") invalid(diagnostics, "site.favicon must be a non-empty local path.");
-		} else if (!isRecord(favicon)) invalid(diagnostics, "site.favicon must be a local path or an object with a source path.");
-		else {
-			for (const key of Object.keys(favicon)) if (!SITE_ICON_KEYS.has(key)) unknown(diagnostics, `site.favicon.${key}`);
-			if (typeof favicon.source !== "string" || favicon.source.trim() === "") invalid(diagnostics, "site.favicon.source must be a non-empty string.");
-			if (favicon.background !== void 0 && (typeof favicon.background !== "string" || favicon.background.trim() === "")) invalid(diagnostics, "site.favicon.background must be a non-empty color string.");
-		}
-	}
-	if (config.editLink !== void 0 && (!isRecord(config.editLink) || typeof config.editLink.baseUrl !== "string")) invalid(diagnostics, "editLink must contain a string baseUrl.");
-	else if (config.editLink !== void 0) {
-		for (const key of Object.keys(config.editLink)) if (key !== "baseUrl") unknown(diagnostics, `editLink.${key}`);
-		try {
-			new URL(config.editLink.baseUrl);
-		} catch {
-			invalid(diagnostics, "editLink.baseUrl must be an absolute URL.");
-		}
-	}
-	if (config.lastUpdated !== void 0 && typeof config.lastUpdated !== "boolean") invalid(diagnostics, "lastUpdated must be a boolean.");
-	if (config.locales !== void 0 && !isRecord(config.locales)) invalid(diagnostics, "locales must be an object.");
-	else for (const [key, locale] of Object.entries(config.locales ?? {})) {
-		if (!isRecord(locale) || typeof locale.label !== "string") {
-			invalid(diagnostics, `locales.${key} must contain a string label.`);
-			continue;
-		}
-		for (const property of Object.keys(locale)) if (![
-			"label",
-			"lang",
-			"dir"
-		].includes(property)) unknown(diagnostics, `locales.${key}.${property}`);
-		if (locale.lang !== void 0 && typeof locale.lang !== "string") invalid(diagnostics, `locales.${key}.lang must be a string.`);
-		if (locale.dir !== void 0 && locale.dir !== "ltr" && locale.dir !== "rtl") invalid(diagnostics, `locales.${key}.dir must be "ltr" or "rtl".`);
-	}
-	if (config.defaultLocale !== void 0 && typeof config.defaultLocale !== "string") invalid(diagnostics, "defaultLocale must be a string.");
-	else if (config.defaultLocale !== void 0 && (config.locales === void 0 || !(config.defaultLocale in config.locales))) invalid(diagnostics, `defaultLocale must match a key in locales; received "${config.defaultLocale}".`);
-	const sources = config.content?.sources ?? [];
-	for (const [index, source] of sources.entries()) if ([
-		"file",
-		"glob",
-		"package"
-	].filter((key) => key in source).length !== 1) diagnostics.push({
-		code: "DOCS_CONFIG_INVALID",
-		severity: "error",
-		message: `content.sources[${index}] must select exactly one of file, glob, or package.`
-	});
-	const brand = config.theme?.brand;
-	if (typeof brand === "object" && brand !== null && "contrast" in brand && !brand.unsafeContrast) {
-		const target = brand.contrast?.apca;
-		const normal = Array.isArray(target) ? target[0] : target;
-		if (typeof normal === "number" && normal < 45) diagnostics.push({
-			code: "DOCS_CONFIG_INVALID",
-			severity: "error",
-			message: "theme.brand.contrast.apca cannot be below 45 without unsafeContrast.",
-			hint: "Remove the override, use 45 or higher, or explicitly set unsafeContrast: true."
-		});
-	}
-	for (const [name, entry] of Object.entries(config.theme?.styles ?? {})) if (!isRecord(entry)) invalid(diagnostics, `theme.styles.${name} must be a Tasty style object.`);
-	else if ("mode" in entry) invalid(diagnostics, `theme.styles.${name} must contain only the Tasty style properties to override, without a mode wrapper.`);
-	const componentOverrides = config.components?.overrides;
-	if (componentOverrides !== void 0 && !isRecord(componentOverrides)) invalid(diagnostics, "components.overrides must be an object.");
-	else for (const [name, override] of Object.entries(componentOverrides ?? {})) {
-		if (typeof override === "string") continue;
-		if (name === "Footer" && override === false) continue;
-		invalid(diagnostics, `components.overrides.${name} must be an Astro component path${name === "Footer" ? " or false" : ""}.`);
-	}
-	return diagnostics;
-}
-function unknown(diagnostics, path) {
-	diagnostics.push({
-		code: "DOCS_CONFIG_UNKNOWN_KEY",
-		severity: "error",
-		message: `Unknown configuration key "${path}".`
-	});
-}
-function invalid(diagnostics, message) {
-	diagnostics.push({
-		code: "DOCS_CONFIG_INVALID",
-		severity: "error",
-		message
-	});
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function normalizeDocsConfig(config = {}) {
-	const diagnostics = validateConfig(config);
-	if (diagnostics.length > 0) throw new DocsConfigError(diagnostics);
-	const navigation = Array.isArray(config.navigation) ? { items: config.navigation } : config.navigation ?? {};
-	return {
-		site: { ...config.site },
-		head: [...config.head ?? []],
-		...config.editLink ? { editLink: { ...config.editLink } } : {},
-		lastUpdated: config.lastUpdated ?? false,
-		...config.locales ? { locales: { ...config.locales } } : {},
-		...config.defaultLocale ? { defaultLocale: config.defaultLocale } : {},
-		content: {
-			allowOutsideRoot: false,
-			localizeRepositoryLinks: false,
-			...config.content
-		},
-		navigation,
-		theme: {
-			...config.theme,
-			brand: config.theme?.brand ?? DEFAULT_BRAND
-		},
-		markdown: {
-			stripLeadingBadges: true,
-			rawHtml: "sanitize",
-			strictLanguages: false,
-			executablePreviews: true,
-			...config.markdown
-		},
-		search: {
-			enabled: true,
-			...config.search
-		},
-		components: { ...config.components },
-		build: {
-			strict: true,
-			ci: process.env.CI === "true",
-			base: "/",
-			cacheDir: "",
-			maxArtifactBytes: 26214400,
-			maxUnpackedBytes: 104857600,
-			maxFiles: 1e4,
-			maxPathDepth: 24,
-			maxAssetBytes: 20971520,
-			...config.build
-		}
-	};
-}
-function defineDocsConfig(config) {
-	const diagnostics = validateConfig(config);
-	if (diagnostics.length > 0) throw new DocsConfigError(diagnostics);
-	return config;
-}
-//#endregion
-export { DocsConfigError, defineDocsConfig, normalizeDocsConfig, validateConfig };
-
-//# sourceMappingURL=index.js.map
+import { a as validateConfig, i as normalizeDocsConfig, n as defineDocsConfig, o as COOKBOOK_COMPONENT_NAMES, r as mergeDocsConfig, s as COOKBOOK_COMPONENT_SUB_ELEMENTS, t as DocsConfigError } from "../config-DoR8g9IM.js";
+export { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, DocsConfigError, defineDocsConfig, mergeDocsConfig, normalizeDocsConfig, validateConfig };