@tenphi/docs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Yamanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @tenphi/docs
+
+Renderer-neutral configuration, source discovery, npm artifact locking, content
+graph construction, Markdown reference rewriting, and diagnostics for Tasty
+Docs.
+
+```ts
+import { createDocsGraph, defineDocsConfig } from "@tenphi/docs";
+```

package/dist/config/index.d.ts

@@ -0,0 +1,12 @@
+import { E as SiteConfig, O as ThemeConfig, T as SearchConfig, _ as MarkdownConfig, c as DocsConfig, g as DocsSource, i as ContentConfig, l as DocsDiagnostic, n as BuildConfig, r as ComponentsConfig, t as BrandConfig, v as NavigationConfig, x as NormalizedDocsConfig, y as NavigationItem } from "../types-rjENJzWH.js";
+//#region src/config/index.d.ts
+declare class DocsConfigError extends Error {
+  readonly diagnostics: DocsDiagnostic[];
+  constructor(diagnostics: DocsDiagnostic[]);
+}
+declare function validateConfig(config: DocsConfig): DocsDiagnostic[];
+declare function normalizeDocsConfig(config?: DocsConfig): NormalizedDocsConfig;
+declare function defineDocsConfig<const T extends DocsConfig>(config: T): T;
+//#endregion
+export { type BrandConfig, type BuildConfig, type ComponentsConfig, type ContentConfig, type DocsConfig, DocsConfigError, type DocsSource, type MarkdownConfig, type NavigationConfig, type NavigationItem, type NormalizedDocsConfig, type SearchConfig, type SiteConfig, type ThemeConfig, defineDocsConfig, normalizeDocsConfig, validateConfig };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/config/index.ts"],"mappings":";;cA4Ca,wBAAwB;WAC1B,aAAa;EAEtB,YAAY,aAAa;;iBAOX,eAAe,QAAQ,aAAa;iBA6DpC,oBACd,SAAQ,aACP;iBAwCa,uBAAuB,UAAU,YAAY,QAAQ,IAAI"}

package/dist/config/index.js

@@ -0,0 +1,143 @@
+//#region src/config/index.ts
+const DEFAULT_BRAND = "#315efb";
+const ROOT_KEYS = /* @__PURE__ */ new Set([
+	"site",
+	"content",
+	"navigation",
+	"theme",
+	"markdown",
+	"search",
+	"components",
+	"build"
+]);
+const OBJECT_KEYS = {
+	site: /* @__PURE__ */ new Set([
+		"title",
+		"description",
+		"url",
+		"repository"
+	]),
+	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"]),
+	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 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."
+		});
+	}
+	return diagnostics;
+}
+function unknown(diagnostics, path) {
+	diagnostics.push({
+		code: "DOCS_CONFIG_UNKNOWN_KEY",
+		severity: "error",
+		message: `Unknown configuration key "${path}".`
+	});
+}
+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 },
+		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

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/config/index.ts"],"sourcesContent":["import type {\n  DocsConfig,\n  DocsDiagnostic,\n  NormalizedDocsConfig,\n} from \"../types.js\";\n\nconst DEFAULT_BRAND = \"#315efb\";\nconst ROOT_KEYS = new Set([\n  \"site\",\n  \"content\",\n  \"navigation\",\n  \"theme\",\n  \"markdown\",\n  \"search\",\n  \"components\",\n  \"build\",\n]);\n\nconst OBJECT_KEYS: Record<string, Set<string>> = {\n  site: new Set([\"title\", \"description\", \"url\", \"repository\"]),\n  content: new Set([\"sources\", \"allowOutsideRoot\", \"localizeRepositoryLinks\"]),\n  markdown: new Set([\n    \"stripLeadingBadges\",\n    \"rawHtml\",\n    \"strictLanguages\",\n    \"executablePreviews\",\n    \"remarkPlugins\",\n    \"rehypePlugins\",\n  ]),\n  search: new Set([\"enabled\"]),\n  components: new Set([\"overrides\"]),\n  build: new Set([\n    \"strict\",\n    \"ci\",\n    \"base\",\n    \"cacheDir\",\n    \"maxArtifactBytes\",\n    \"maxUnpackedBytes\",\n    \"maxFiles\",\n    \"maxPathDepth\",\n    \"maxAssetBytes\",\n  ]),\n};\n\nexport class DocsConfigError extends Error {\n  readonly diagnostics: DocsDiagnostic[];\n\n  constructor(diagnostics: DocsDiagnostic[]) {\n    super(diagnostics.map((diagnostic) => diagnostic.message).join(\"\\n\"));\n    this.name = \"DocsConfigError\";\n    this.diagnostics = diagnostics;\n  }\n}\n\nexport function validateConfig(config: DocsConfig): DocsDiagnostic[] {\n  const diagnostics: DocsDiagnostic[] = [];\n  for (const key of Object.keys(config)) {\n    if (!ROOT_KEYS.has(key)) unknown(diagnostics, key);\n  }\n  for (const [section, keys] of Object.entries(OBJECT_KEYS)) {\n    const value = config[section as keyof DocsConfig];\n    if (\n      value === undefined ||\n      Array.isArray(value) ||\n      typeof value !== \"object\"\n    ) {\n      continue;\n    }\n    for (const key of Object.keys(value)) {\n      if (!keys.has(key)) unknown(diagnostics, `${section}.${key}`);\n    }\n  }\n\n  const sources = config.content?.sources ?? [];\n  for (const [index, source] of sources.entries()) {\n    const variants = [\"file\", \"glob\", \"package\"].filter((key) => key in source);\n    if (variants.length !== 1) {\n      diagnostics.push({\n        code: \"DOCS_CONFIG_INVALID\",\n        severity: \"error\",\n        message: `content.sources[${index}] must select exactly one of file, glob, or package.`,\n      });\n    }\n  }\n\n  const brand = config.theme?.brand;\n  if (\n    typeof brand === \"object\" &&\n    brand !== null &&\n    \"contrast\" in brand &&\n    !brand.unsafeContrast\n  ) {\n    const target = brand.contrast?.apca;\n    const normal = Array.isArray(target) ? target[0] : target;\n    if (typeof normal === \"number\" && normal < 45) {\n      diagnostics.push({\n        code: \"DOCS_CONFIG_INVALID\",\n        severity: \"error\",\n        message:\n          \"theme.brand.contrast.apca cannot be below 45 without unsafeContrast.\",\n        hint: \"Remove the override, use 45 or higher, or explicitly set unsafeContrast: true.\",\n      });\n    }\n  }\n  return diagnostics;\n}\n\nfunction unknown(diagnostics: DocsDiagnostic[], path: string): void {\n  diagnostics.push({\n    code: \"DOCS_CONFIG_UNKNOWN_KEY\",\n    severity: \"error\",\n    message: `Unknown configuration key \"${path}\".`,\n  });\n}\n\nexport function normalizeDocsConfig(\n  config: DocsConfig = {},\n): NormalizedDocsConfig {\n  const diagnostics = validateConfig(config);\n  if (diagnostics.length > 0) throw new DocsConfigError(diagnostics);\n  const navigation = Array.isArray(config.navigation)\n    ? { items: config.navigation }\n    : (config.navigation ?? {});\n\n  return {\n    site: { ...config.site },\n    content: {\n      allowOutsideRoot: false,\n      localizeRepositoryLinks: false,\n      ...config.content,\n    },\n    navigation,\n    theme: { ...config.theme, brand: config.theme?.brand ?? DEFAULT_BRAND },\n    markdown: {\n      stripLeadingBadges: true,\n      rawHtml: \"sanitize\",\n      strictLanguages: false,\n      executablePreviews: true,\n      ...config.markdown,\n    },\n    search: { enabled: true, ...config.search },\n    components: { ...config.components },\n    build: {\n      strict: true,\n      ci: process.env.CI === \"true\",\n      base: \"/\",\n      cacheDir: \"\",\n      maxArtifactBytes: 25 * 1024 * 1024,\n      maxUnpackedBytes: 100 * 1024 * 1024,\n      maxFiles: 10_000,\n      maxPathDepth: 24,\n      maxAssetBytes: 20 * 1024 * 1024,\n      ...config.build,\n    },\n  };\n}\n\nexport function defineDocsConfig<const T extends DocsConfig>(config: T): T {\n  const diagnostics = validateConfig(config);\n  if (diagnostics.length > 0) throw new DocsConfigError(diagnostics);\n  return config;\n}\n\nexport type {\n  BrandConfig,\n  BuildConfig,\n  ComponentsConfig,\n  ContentConfig,\n  DocsConfig,\n  DocsSource,\n  MarkdownConfig,\n  NavigationConfig,\n  NavigationItem,\n  NormalizedDocsConfig,\n  SearchConfig,\n  SiteConfig,\n  ThemeConfig,\n} from \"../types.js\";\n"],"mappings":"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"}

package/dist/config/schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tasty.style/schemas/tasty-docs.schema.json",
+  "title": "Tasty Docs configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "site": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "url": { "type": "string", "format": "uri" },
+        "repository": { "type": "string", "format": "uri" }
+      }
+    },
+    "content": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "allowOutsideRoot": { "type": "boolean", "default": false },
+        "localizeRepositoryLinks": { "type": "boolean", "default": false },
+        "sources": { "type": "array", "items": { "$ref": "#/$defs/source" } }
+      }
+    },
+    "navigation": { "type": ["object", "array"] },
+    "theme": { "type": "object" },
+    "markdown": { "type": "object" },
+    "search": { "type": "object" },
+    "components": { "type": "object" },
+    "build": { "type": "object" }
+  },
+  "$defs": {
+    "source": {
+      "type": "object",
+      "oneOf": [
+        { "required": ["file"] },
+        { "required": ["glob"] },
+        { "required": ["package"] }
+      ]
+    }
+  }
+}

package/dist/content/index.d.ts

@@ -0,0 +1,28 @@
+import { a as CreateDocsGraphOptions, c as DocsConfig, f as DocsGraph, h as DocsRoute, s as DocsAsset, u as DocsEntry } from "../types-rjENJzWH.js";
+//#region src/content/index.d.ts
+interface DocsLoaderContext {
+  store: {
+    clear(): void;
+    set(entry: {
+      id: string;
+      data: Record<string, unknown>;
+      body: string;
+      filePath?: string;
+    }): void;
+  };
+  logger?: {
+    info(message: string): void;
+  };
+  parseData?: (input: {
+    id: string;
+    data: Record<string, unknown>;
+    filePath?: string;
+  }) => Promise<Record<string, unknown>>;
+}
+declare function createDocsLoader(config?: DocsConfig, options?: Omit<CreateDocsGraphOptions, "config">): {
+  name: string;
+  load(context: DocsLoaderContext): Promise<void>;
+};
+//#endregion
+export { type DocsAsset, type DocsEntry, type DocsGraph, DocsLoaderContext, type DocsRoute, createDocsLoader };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/content/index.ts"],"mappings":";;UAQiB;EACf;IACE;IACA,IAAI;MACF;MACA,MAAM;MACN;MACA;;;EAGJ;IAAW,KAAK;;EAChB,aAAa;IACX;IACA,MAAM;IACN;QACI,QAAQ;;iBAGA,iBACd,SAAS,YACT,UAAS,KAAK;EAGZ;EACM,KAAI,SAAU,oBAAoB"}

package/dist/content/index.js

@@ -0,0 +1,2 @@
+import { t as createDocsLoader } from "../content-DStZeziu.js";
+export { createDocsLoader };