@lupinum/ginko-content 0.1.0

package/dist/storage/references

@@ -0,0 +1 @@
+export * from './references.js'

package/dist/storage/references.d.ts

@@ -0,0 +1,13 @@
+import type { H3Event } from 'h3';
+import type { ContentQueryBuilderParams } from '../types/query';
+import type { ContentQueryResponse } from '../types/api';
+export declare const withResolvedRefs: <T>(event: H3Event, content: T, requestedLocale?: string) => Promise<T>;
+export declare const withResolvedRefsList: <T>(event: H3Event, items: T[], requestedLocale?: string) => Promise<T[]>;
+export declare const withResolvedRefsQueryResponse: <T>(event: H3Event, response: ContentQueryResponse<T>, params: ContentQueryBuilderParams) => Promise<import("../types/api").ContentQueryCountResponse | {
+    result: T | T[] | undefined;
+} | {
+    result: T | T[] | undefined;
+    skip: number;
+    limit: number;
+    total: number;
+}>;

package/dist/storage/references.js

@@ -0,0 +1,78 @@
+import { collectMarkdownRefLinks, parseRefLink } from "../core/references/resolve";
+import { contentConfig } from "./driver.js";
+import { getContentManifest, resolveVariant } from "./manifest.js";
+const prefixLocaleRoute = (path, locale) => {
+  const defaultLocale = contentConfig().defaultLocale;
+  if (!locale || locale === defaultLocale) {
+    return path;
+  }
+  return path === "/" ? `/${locale}` : `/${locale}${path}`;
+};
+const resolveDocumentRefLinks = async (event, content, requestedLocale) => {
+  if (!content || content._type !== "markdown" || !content.body) {
+    return void 0;
+  }
+  const hrefs = collectMarkdownRefLinks(content.body);
+  if (!hrefs.length) {
+    return void 0;
+  }
+  const manifest = await getContentManifest(event);
+  const entries = await Promise.all(hrefs.map(async (href) => {
+    const parsed = parseRefLink(href);
+    if (!parsed) {
+      return null;
+    }
+    const canonicalKey = manifest.byRef[parsed.ref];
+    if (!canonicalKey) {
+      if (import.meta.dev) {
+        console.warn(`[content] Could not resolve markdown ref "${href}" in "${content._file || content._id}"`);
+      }
+      return [href, href];
+    }
+    const variant = await resolveVariant(event, canonicalKey, requestedLocale);
+    if (!variant?.path) {
+      if (import.meta.dev) {
+        console.warn(`[content] Could not resolve markdown ref "${href}" in "${content._file || content._id}"`);
+      }
+      return [href, href];
+    }
+    if (import.meta.dev && requestedLocale && variant.resolvedLocale && variant.resolvedLocale !== requestedLocale) {
+      console.warn(`[content] Markdown ref "${href}" in "${content._file || content._id}" fell back from locale "${requestedLocale}" to "${variant.resolvedLocale}"`);
+    }
+    return [href, `${prefixLocaleRoute(variant.path, variant.resolvedLocale)}${parsed.hash}`];
+  }));
+  const resolvedRefs = Object.fromEntries(entries.filter((entry) => Boolean(entry)));
+  return Object.keys(resolvedRefs).length ? resolvedRefs : void 0;
+};
+export const withResolvedRefs = async (event, content, requestedLocale) => {
+  if (!content || Array.isArray(content)) {
+    return content;
+  }
+  const resolvedRefs = await resolveDocumentRefLinks(event, content, requestedLocale);
+  if (!resolvedRefs) {
+    return content;
+  }
+  return {
+    ...content,
+    _resolvedRefs: resolvedRefs
+  };
+};
+export const withResolvedRefsList = async (event, items, requestedLocale) => {
+  return await Promise.all(items.map((item) => withResolvedRefs(event, item, requestedLocale)));
+};
+export const withResolvedRefsQueryResponse = async (event, response, params) => {
+  if (typeof response.result === "number") {
+    return response;
+  }
+  const requestedLocale = params.resolveLocale?.locale;
+  if (params.first) {
+    return {
+      ...response,
+      result: await withResolvedRefs(event, response.result, requestedLocale)
+    };
+  }
+  return {
+    ...response,
+    result: Array.isArray(response.result) ? await withResolvedRefsList(event, response.result, requestedLocale) : response.result
+  };
+};

package/dist/storage/validation

@@ -0,0 +1 @@
+export * from './validation.js'

package/dist/storage/validation.d.ts

@@ -0,0 +1,46 @@
+import type { ParsedContent } from '../types/content';
+import type { ContentCollectionConfig } from '../types/config';
+import { ContentError, type ContentErrorCode } from '../core/errors';
+import { type Result } from '../core/result';
+/**
+ * Build a `ContentError` with a consistent "Invalid content in <file>: <reason>"
+ * message format.
+ */
+export declare function createContentError(code: ContentErrorCode, file: string, reason: string, details?: string, extraContext?: Record<string, unknown>): ContentError;
+export declare const getCanonicalContentId: (document: ParsedContent, locales?: string[]) => string;
+/**
+ * Validate a single document against its collection schema.
+ *
+ * - Non-strict collections: schema errors log `console.warn(...)` and the
+ *   original document passes through.
+ * - Strict collections (default): schema errors produce a `SCHEMA_VALIDATION_FAILED`
+ *   failure.
+ *
+ * Also chains into `validateNavigationDocument` for `_navigation: true` files,
+ * which can fail with `INVALID_NAVIGATION_YAML`.
+ */
+export declare const validateCollectionDocument: (document: ParsedContent, collections?: Record<string, ContentCollectionConfig>) => Result<ParsedContent, ContentError>;
+/**
+ * Graph-level invariants across a whole content tree.
+ *
+ * Checks, in order:
+ *   1. Translated-slug sibling conflicts (`TRANSLATED_SLUG_CONFLICT`, errors only; warns are logged in place)
+ *   2. Explicit `id` alignment across locale variants (`CONFLICTING_REFS`)
+ *   3. Explicit `id` uniqueness across unrelated content identities (`CONFLICTING_REFS`)
+ *   4. Explicit `ref` alignment across locale variants (`CONFLICTING_REFS`)
+ *   5. Duplicate canonical id / localized path per locale (`DUPLICATE_CANONICAL_ID` / `DUPLICATE_LOCALIZED_PATH`)
+ *   6. Cross-document ref uniqueness (`CONFLICTING_REFS`)
+ *   7. Invalid `ref` value shape (`INVALID_REF_VALUE`)
+ *   8. Unresolved content-reference links per collection schema (`SCHEMA_VALIDATION_FAILED`; non-strict: warn+pass)
+ *
+ * Returns `ok(undefined)` when every invariant holds. On the first failing
+ * invariant, returns `fail(ContentError)` — graph validation is fail-fast;
+ * this mirrors the old throw-on-first behavior while giving callers a typed
+ * code to branch on.
+ */
+export declare const validateContentGraph: (contents: ParsedContent[], config: {
+    collections?: Record<string, ContentCollectionConfig>;
+    locales?: string[];
+    translatedSlugs?: boolean;
+    strictTranslatedSlugs?: boolean;
+}) => Result<void, ContentError>;

package/dist/storage/validation.js

@@ -0,0 +1,341 @@
+import { buildReferenceTargets, normalizeReferenceValue } from "../core/references/resolve";
+import { getObjectShape, getReferenceDescriptor, getSchemaDef, getSchemaTypeName, unwrapSchema } from "../core/references/schema";
+import { collectTranslatedSlugValidationIssues } from "../features/localization/translated-slugs";
+import { ContentError } from "../core/errors";
+import { fail, ok } from "../core/result";
+const hasSafeParse = (schema) => {
+  return Boolean(schema) && typeof schema.safeParse === "function";
+};
+const getCollectionConfig = (collectionName, collections = {}) => {
+  if (!collectionName) {
+    return void 0;
+  }
+  return collections?.[collectionName];
+};
+export function createContentError(code, file, reason, details, extraContext) {
+  return new ContentError(
+    code,
+    `Invalid content in ${file}${details ? ` (${details})` : ""}: ${reason}`,
+    { file, reason, ...details ? { details } : {}, ...extraContext || {} }
+  );
+}
+const collectReferenceIssues = (schema, value, resolveReference, issues, path = []) => {
+  const current = unwrapSchema(schema);
+  if (!current || typeof value === "undefined" || value === null) {
+    return;
+  }
+  const ref = getReferenceDescriptor(current);
+  if (ref) {
+    if (typeof value !== "string") {
+      issues.push(`${path.join(".") || "document"}: expected a string reference`);
+      return;
+    }
+    if (!resolveReference(value, ref.collection)) {
+      issues.push(`${path.join(".") || "document"}: unresolved reference "${value}"${ref.collection ? ` in collection "${ref.collection}"` : ""}`);
+    }
+    return;
+  }
+  if (getSchemaTypeName(current) === "ZodArray" && Array.isArray(value)) {
+    const def = getSchemaDef(current);
+    value.forEach((item, index) => collectReferenceIssues(def.element || def.type, item, resolveReference, issues, [...path, index]));
+    return;
+  }
+  if (getSchemaTypeName(current) === "ZodObject" && typeof value === "object") {
+    const shape = getObjectShape(current);
+    for (const [key, childSchema] of Object.entries(shape)) {
+      collectReferenceIssues(childSchema, value[key], resolveReference, issues, [...path, key]);
+    }
+  }
+};
+const internalDocumentFields = /* @__PURE__ */ new Set([
+  "_id",
+  "_file",
+  "_path",
+  "_type",
+  "_collection",
+  "_dir",
+  "_locale",
+  "_canonicalKey",
+  "_partial",
+  "_navigation",
+  "_draft",
+  "_stem",
+  "_extension",
+  "_resolvedLocale",
+  "_requestedLocale",
+  "_fallback",
+  "_availableLocales",
+  "_variantPaths",
+  "_resolvedRefs",
+  "_source",
+  "body",
+  "draft"
+]);
+const toUserContentDocument = (document) => {
+  const userDocument = {};
+  for (const [key, value] of Object.entries(document)) {
+    if (!internalDocumentFields.has(key)) {
+      userDocument[key] = value;
+    }
+  }
+  return userDocument;
+};
+const validateNavigationDocument = (document) => {
+  if (!document._navigation) {
+    return ok(void 0);
+  }
+  const invalidFields = [];
+  if (typeof document.title !== "undefined" && typeof document.title !== "string") {
+    invalidFields.push("title must be a string");
+  }
+  if (typeof document.order !== "undefined" && typeof document.order !== "number") {
+    invalidFields.push("order must be a number");
+  }
+  if (typeof document.icon !== "undefined" && typeof document.icon !== "string" && document.icon !== false) {
+    invalidFields.push("icon must be a string or false");
+  }
+  if (typeof document.hidden !== "undefined" && typeof document.hidden !== "boolean") {
+    invalidFields.push("hidden must be a boolean");
+  }
+  if (typeof document.navigation !== "undefined" && typeof document.navigation !== "boolean" && typeof document.navigation !== "object") {
+    invalidFields.push("navigation must be false or an object");
+  }
+  if (typeof document.badge !== "undefined" && typeof document.badge !== "string" && typeof document.badge !== "object") {
+    invalidFields.push("badge must be a string or an object");
+  }
+  if (invalidFields.length) {
+    return fail(createContentError(
+      "INVALID_NAVIGATION_YAML",
+      document._file || document._id,
+      "malformed .navigation.yml",
+      invalidFields.join("; ")
+    ));
+  }
+  return ok(void 0);
+};
+export const getCanonicalContentId = (document, locales = []) => {
+  if (typeof document.id === "string" && document.id.length) {
+    return document.id;
+  }
+  if (typeof document._canonicalKey === "string" && document._canonicalKey.length) {
+    return document._canonicalKey;
+  }
+  const file = (document._file || "").replace(/^\/+/, "");
+  const parts = file.split("/").filter(Boolean);
+  const normalized = parts[0] && locales.includes(parts[0]) ? parts.slice(1) : parts;
+  return normalized.join("/").replace(/\.[^.]+$/, "");
+};
+export const validateCollectionDocument = (document, collections = {}) => {
+  const navigationResult = validateNavigationDocument(document);
+  if (!navigationResult.ok) {
+    return navigationResult;
+  }
+  if (!document._collection) {
+    return ok(document);
+  }
+  const collection = getCollectionConfig(document._collection, collections);
+  const schema = collection?.schema;
+  if (!hasSafeParse(schema)) {
+    return ok(document);
+  }
+  const parsed = schema.safeParse(toUserContentDocument(document));
+  if (parsed.success) {
+    return ok({
+      ...document,
+      ...parsed.data
+    });
+  }
+  const details = parsed.error.issues?.map((issue) => {
+    const path = issue.path?.length ? issue.path.join(".") : "document";
+    return `${path}: ${issue.message}`;
+  }).join("; ");
+  const message = `Invalid content in ${document._file || document._id}${details ? ` (${details})` : ""}`;
+  if (collection?.strict === false) {
+    console.warn(message);
+    return ok(document);
+  }
+  return fail(new ContentError(
+    "SCHEMA_VALIDATION_FAILED",
+    message,
+    {
+      file: document._file || document._id,
+      collection: document._collection,
+      ...details ? { details } : {}
+    }
+  ));
+};
+export const validateContentGraph = (contents, config) => {
+  const locales = config.locales || [];
+  const docs = contents.filter((content) => content && content._path);
+  const routeEntries = docs.filter((content) => !content._partial && !content._navigation);
+  const markdownEntries = routeEntries.filter((content) => content._type === "markdown");
+  const idsByLocale = /* @__PURE__ */ new Map();
+  const pathsByLocale = /* @__PURE__ */ new Map();
+  const referenceTargets = buildReferenceTargets(routeEntries, locales);
+  const targetCollections = /* @__PURE__ */ new Map();
+  const variantsByCanonicalKey = /* @__PURE__ */ new Map();
+  const markdownVariantsByCanonicalKey = /* @__PURE__ */ new Map();
+  const explicitIdsByValue = /* @__PURE__ */ new Map();
+  const refsByValue = /* @__PURE__ */ new Map();
+  for (const document of routeEntries) {
+    const canonicalId = document._canonicalKey || getCanonicalContentId(document, locales);
+    if (!canonicalId || !document._collection) {
+      continue;
+    }
+    const collections = targetCollections.get(canonicalId) || /* @__PURE__ */ new Set();
+    collections.add(document._collection);
+    targetCollections.set(canonicalId, collections);
+  }
+  for (const issue of collectTranslatedSlugValidationIssues(markdownEntries, {
+    translatedSlugs: config.translatedSlugs,
+    locales
+  })) {
+    if (issue.level === "warn" && config.strictTranslatedSlugs) {
+      return fail(createContentError("TRANSLATED_SLUG_CONFLICT", issue.file, issue.reason, issue.details));
+    }
+    if (issue.level === "warn") {
+      console.warn(createContentError("INVALID_CONTENT", issue.file, issue.reason, issue.details).message);
+      continue;
+    }
+    return fail(createContentError("TRANSLATED_SLUG_CONFLICT", issue.file, issue.reason, issue.details));
+  }
+  for (const document of routeEntries) {
+    const variantKey = document._canonicalKey || getCanonicalContentId(document, locales);
+    const siblings = variantsByCanonicalKey.get(variantKey) || [];
+    siblings.push(document);
+    variantsByCanonicalKey.set(variantKey, siblings);
+  }
+  for (const document of markdownEntries) {
+    const variantKey = document._canonicalKey || getCanonicalContentId(document, locales);
+    const siblings = markdownVariantsByCanonicalKey.get(variantKey) || [];
+    siblings.push(document);
+    markdownVariantsByCanonicalKey.set(variantKey, siblings);
+  }
+  for (const [variantKey, variants] of variantsByCanonicalKey.entries()) {
+    const explicitIds = Array.from(new Set(variants.map((document) => typeof document.id === "string" && document.id.length ? document.id : void 0).filter((value) => Boolean(value))));
+    if (explicitIds.length > 1) {
+      return fail(createContentError(
+        "CONFLICTING_REFS",
+        variants[0]?._file || variants[0]?._id || variantKey,
+        `conflicting explicit ids across locale variants for canonical key "${variantKey}"`,
+        explicitIds.join(", ")
+      ));
+    }
+    if (explicitIds.length === 1 && variants.some((document) => document.id !== explicitIds[0])) {
+      return fail(createContentError(
+        "CONFLICTING_REFS",
+        variants[0]?._file || variants[0]?._id || variantKey,
+        `explicit id "${explicitIds[0]}" must be declared consistently across locale variants for canonical key "${variantKey}"`
+      ));
+    }
+  }
+  for (const document of routeEntries) {
+    const explicitId = typeof document.id === "string" && document.id.length ? document.id : void 0;
+    if (!explicitId) {
+      continue;
+    }
+    const variantKey = document._canonicalKey || getCanonicalContentId(document, locales);
+    const previous = explicitIdsByValue.get(explicitId);
+    if (previous && previous.variantKey !== variantKey) {
+      return fail(createContentError(
+        "CONFLICTING_REFS",
+        document._file || document._id,
+        `duplicate explicit id "${explicitId}"`,
+        `conflicts with ${previous.document._file || previous.document._id}`
+      ));
+    }
+    explicitIdsByValue.set(explicitId, { document, variantKey });
+  }
+  for (const [variantKey, variants] of markdownVariantsByCanonicalKey.entries()) {
+    const explicitRefs = Array.from(new Set(variants.map((document) => typeof document.ref === "string" && document.ref.length ? document.ref : void 0).filter((value) => Boolean(value))));
+    if (explicitRefs.length > 1) {
+      return fail(createContentError(
+        "CONFLICTING_REFS",
+        variants[0]?._file || variants[0]?._id || variantKey,
+        `conflicting refs across locale variants for canonical key "${variantKey}"`,
+        explicitRefs.join(", ")
+      ));
+    }
+  }
+  for (const document of routeEntries) {
+    const canonicalId = document._canonicalKey || getCanonicalContentId(document, locales);
+    const localeKey = `${canonicalId}:${document._locale || ""}`;
+    if (idsByLocale.has(localeKey)) {
+      const previous = idsByLocale.get(localeKey);
+      return fail(createContentError(
+        "DUPLICATE_CANONICAL_ID",
+        document._file || document._id,
+        `duplicate canonical id "${canonicalId}" for locale "${document._locale || "default"}"`,
+        `conflicts with ${previous._file || previous._id}`
+      ));
+    }
+    idsByLocale.set(localeKey, document);
+    const pathKey = `${document._locale || ""}:${document._path || ""}`;
+    if (pathsByLocale.has(pathKey)) {
+      const previous = pathsByLocale.get(pathKey);
+      return fail(createContentError(
+        "DUPLICATE_LOCALIZED_PATH",
+        document._file || document._id,
+        `duplicate localized path "${document._path}" for locale "${document._locale || "default"}"`,
+        `conflicts with ${previous._file || previous._id}`
+      ));
+    }
+    pathsByLocale.set(pathKey, document);
+  }
+  for (const document of markdownEntries) {
+    if (typeof document.ref !== "undefined" && (typeof document.ref !== "string" || !document.ref.length)) {
+      return fail(createContentError(
+        "INVALID_REF_VALUE",
+        document._file || document._id,
+        "ref must be a non-empty string"
+      ));
+    }
+    const ref = typeof document.ref === "string" && document.ref.length ? document.ref : void 0;
+    if (!ref) {
+      continue;
+    }
+    const previous = refsByValue.get(ref);
+    if (previous && (previous._canonicalKey || getCanonicalContentId(previous, locales)) !== (document._canonicalKey || getCanonicalContentId(document, locales))) {
+      return fail(createContentError(
+        "CONFLICTING_REFS",
+        document._file || document._id,
+        `duplicate ref "${ref}"`,
+        `conflicts with ${previous._file || previous._id}`
+      ));
+    }
+    refsByValue.set(ref, document);
+  }
+  for (const document of docs) {
+    if (!document._collection) {
+      continue;
+    }
+    const collection = getCollectionConfig(document._collection, config.collections);
+    const schema = collection?.schema;
+    if (!schema) {
+      continue;
+    }
+    const issues = [];
+    collectReferenceIssues(schema, document, (value, collection2) => {
+      const canonicalId = referenceTargets.get(normalizeReferenceValue(value));
+      if (!canonicalId) {
+        return false;
+      }
+      return collection2 ? targetCollections.get(canonicalId)?.has(collection2) === true : true;
+    }, issues);
+    if (!issues.length) {
+      continue;
+    }
+    const error = createContentError(
+      "SCHEMA_VALIDATION_FAILED",
+      document._file || document._id,
+      "unresolved content references",
+      issues.join("; ")
+    );
+    if (collection?.strict === false) {
+      console.warn(error.message);
+      continue;
+    }
+    return fail(error);
+  }
+  return ok(void 0);
+};

package/dist/testing/provider-contract

@@ -0,0 +1 @@
+export * from './provider-contract.js'

package/dist/testing/provider-contract.d.ts

@@ -0,0 +1,31 @@
+import { type ContentProvider } from '../public/provider';
+export interface SaasProviderFixtureContractSuiteOptions {
+    name: string;
+    expectedProviderName: string;
+    loadProvider: () => Promise<ContentProvider>;
+    createEvent: () => any;
+    collectNavPaths?: (items: Array<{
+        _path?: string;
+        children?: any[];
+    }>) => string[];
+}
+export interface AuthorDependencyContractOptions {
+    name: string;
+    loadProvider: () => Promise<ContentProvider>;
+    createEvent: () => any;
+    getCacheEvents: (provider: ContentProvider) => Array<{
+        type: string;
+        key: string;
+    }>;
+}
+export declare const runSaasProviderFixtureContractSuite: ({ name, expectedProviderName, loadProvider, createEvent, collectNavPaths }: SaasProviderFixtureContractSuiteOptions) => void;
+export declare const createAuthorDependencyContractProvider: () => {
+    fixture: import("./provider-fixture").ProviderFixture;
+    provider: ContentProvider & {
+        cache: import("./provider-fixture").ProviderFixtureCacheState;
+    };
+    createEvent: () => import("h3").H3Event<import("h3").EventHandlerRequest>;
+    getCacheEvents: () => import("./provider-fixture").ProviderFixtureCacheEvent[];
+};
+export declare const runAuthorDependencyContractTest: (options: AuthorDependencyContractOptions) => void;
+export declare const runAuthorDependencyFixtureSelfTest: () => void;