@lupinum/ginko-content 0.1.0

package/dist/core/content/graph.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The content graph is the precomputed, read-only index every query reads
+ * from. `buildContentGraph(documents)` turns a flat list of parsed content
+ * into the cross-referenced lookup tables below.
+ *
+ * Key concepts:
+ *
+ *  - **Canonical key**: the locale-independent identity of a document. Two
+ *    locale variants of the same page share the same canonical key; the
+ *    key is what refs point at and what navigation deduplicates on.
+ *  - **`byId`**: lookup by the fully-qualified, locale-suffixed content id.
+ *    One entry per file-on-disk variant.
+ *  - **`byCanonical`**: the core locale-aware index. `byCanonical[key]` is
+ *    a `{ [locale]: variant }` map so resolving a page in a given locale
+ *    is an O(1) lookup rather than a linear scan.
+ *  - **`byRoute`**: route path (user-visible URL) → content id. Used by the
+ *    page resolver when the request arrives as a localized URL.
+ *  - **`byRef`**: normalized ref string → canonical key. This is how
+ *    `[link](ref:authors/evan)` finds its target without a scan.
+ *  - **`referenceTargets`**: the `buildReferenceTargets` map — every shape
+ *    the user might plausibly write to point at a document (canonical
+ *    name, locale-prefixed path, short slug) pre-resolved to a canonical
+ *    key.
+ *
+ * The graph is rebuilt from scratch on every request in dev; in production
+ * it is memoized per-request via `memoizeRuntimeValue(event, 'graph', ...)`.
+ */
+import type { ParsedContent } from '../../types/content';
+import type { ContentLocaleEntry } from '../../types/query';
+import type { ContentManifest, ManifestVariant, ResolvedVariant } from '../../types/runtime';
+export interface ContentGraphVariant extends ManifestVariant {
+    document: ParsedContent;
+}
+export interface ContentGraph {
+    documents: ParsedContent[];
+    /** id → document. Keys include the locale suffix; one entry per source file. */
+    byId: Record<string, ParsedContent>;
+    /** collection name → ordered list of document ids. */
+    byCollection: Record<string, string[]>;
+    /** localized route path → list of document ids sharing that path. */
+    byPath: Record<string, string[]>;
+    /** canonical key → `{ [locale]: variant }`. The locale-aware index. */
+    byCanonical: Record<string, Record<string, ContentGraphVariant>>;
+    /** route path → content id. Used by page resolution. */
+    byRoute: Record<string, string>;
+    /** normalized ref string → canonical key. */
+    byRef: Record<string, string>;
+    /** navigation path → `{ [locale]: document }`. Drives `.navigation.yml` merging. */
+    byNavigationPath: Record<string, Record<string, ParsedContent>>;
+    /** Every user-writable reference shape pre-resolved to a canonical key. */
+    referenceTargets: Map<string, string>;
+    manifest: ContentManifest;
+}
+/**
+ * Build the locale resolution chain for a request.
+ *
+ * Order, from highest to lowest priority:
+ *   1. The explicitly requested locale (if any).
+ *   2. Author-configured fallbacks for that locale.
+ *   3. The site-wide default locale.
+ *
+ * Duplicates are removed while preserving first-occurrence order, so the
+ * caller can walk the chain and stop at the first hit without worrying
+ * about re-visiting the default.
+ *
+ * @example
+ * resolveLocaleChain('fr', 'en', { fr: ['de'] })  // ['fr', 'de', 'en']
+ * resolveLocaleChain(undefined, 'en')            // ['en']
+ */
+export declare const resolveLocaleChain: (requestedLocale: string | undefined, defaultLocale?: string, fallback?: Record<string, string[]>) => string[];
+/**
+ * Build a `ContentGraph` from a flat list of parsed documents.
+ *
+ * The function is pure: given the same documents it returns equivalent
+ * lookup tables. Callers memoize this per-request — see
+ * `storage/content.ts:createServerQueryFetch` and
+ * `memoizeRuntimeValue(event, 'graph', ...)`.
+ *
+ * INVARIANT: documents without `_path` are still indexed by id (so refs can
+ * find them) but are excluded from path/route/canonical lookups. Partials
+ * and navigation documents are likewise indexed by id only.
+ */
+export declare const buildContentGraph: (documents: ParsedContent[], options?: {
+    locales?: string[];
+    defaultLocale?: string;
+}) => ContentGraph;
+/**
+ * Resolve a canonical key to a concrete locale variant.
+ *
+ * `exact: true` disables fallback — the caller only wants the requested
+ * locale, period. Without `exact`, the locale chain (requested → explicit
+ * `fallback` → configured `localeFallback` → `defaultLocale`) is walked
+ * until a variant is found.
+ *
+ * Returns `null` if the canonical key does not exist *or* if `exact` is
+ * set and the requested locale has no variant.
+ */
+export declare const resolveGraphVariant: (graph: ContentGraph, canonicalKey: string, requestedLocale?: string, options?: {
+    defaultLocale?: string;
+    fallback?: string[];
+    exact?: boolean;
+    localeFallback?: Record<string, string[]>;
+    /**
+     * Restrict the locale variants considered to ones that live in this
+     * collection. Without this, a canonical key shared by two collections
+     * (e.g. `authors` and `docs` cross-referencing the same id) can resolve
+     * to a wrong-collection variant whose post-hoc filter then drops the
+     * result entirely — even though the requested collection has a perfectly
+     * good variant in another locale.
+     */
+    collection?: string;
+}) => ResolvedVariant | null;
+/**
+ * Resolve a **route path** (the URL the user visited) to a locale variant.
+ *
+ * Walks the locale chain and consults `byRoute` (keyed `${locale}:${path}`)
+ * for each candidate. Falls back to scanning every locale in the graph if
+ * the chain is empty — this is what powers language-agnostic dev links
+ * where the locale has to be inferred from the content.
+ */
+export declare const resolveGraphRouteVariant: (graph: ContentGraph, routePath: string, requestedLocale?: string, options?: {
+    defaultLocale?: string;
+    fallback?: string[];
+    exact?: boolean;
+    localeFallback?: Record<string, string[]>;
+    collection?: string;
+}) => ResolvedVariant | null;
+/**
+ * Turn a user-written identity string (`'guide/intro'`, `'intro'`,
+ * `'de/leitfaden/einstieg'`) into its canonical key, optionally scoped to
+ * a collection.
+ *
+ * Consults — in order — `byCanonical` (already canonical), `byRef`
+ * (explicit `ref:` field in front-matter), then the full
+ * `referenceTargets` index (built from every plausible shape). Returns
+ * `null` if nothing matches.
+ *
+ * GOTCHA: when `collection` is provided but the collection is empty, we
+ * short-circuit to `null` rather than letting a stale canonical match
+ * leak through.
+ */
+export declare const resolveGraphCanonicalKey: (graph: ContentGraph, identity: string, collection?: string) => string | null;
+export declare const resolveGraphCollectionLocales: (graph: ContentGraph, identity: string, collection?: string) => ContentLocaleEntry[];
+export declare const selectGraphDocuments: (graph: ContentGraph, options?: {
+    collection?: string;
+    paths?: Array<string | RegExp>;
+}) => ParsedContent[];

package/dist/core/content/graph.js

@@ -0,0 +1,189 @@
+import { normalizeReferenceValue, buildReferenceTargets } from "../references/resolve.js";
+const normalizePath = (path) => {
+  if (!path || path === "/") {
+    return "/";
+  }
+  return path.startsWith("/") ? path.endsWith("/") ? path.slice(0, -1) || "/" : path : `/${path.replace(/\/+$/, "")}`;
+};
+const emptyManifest = () => ({
+  byCanonical: {},
+  byRef: {},
+  byRoute: {},
+  paths: {},
+  collections: {}
+});
+export const resolveLocaleChain = (requestedLocale, defaultLocale, fallback = {}) => {
+  const chain = [
+    ...requestedLocale ? [requestedLocale] : [],
+    ...requestedLocale && fallback[requestedLocale] || [],
+    ...defaultLocale ? [defaultLocale] : []
+  ].filter(Boolean);
+  return Array.from(new Set(chain));
+};
+export const buildContentGraph = (documents, options = {}) => {
+  const manifest = emptyManifest();
+  const byId = {};
+  const byCanonical = {};
+  const byNavigationPath = {};
+  const defaultLocale = options.defaultLocale || "";
+  for (const document of documents) {
+    const documentId = document._id || `${document._collection || "content"}:${document._path || "document"}`;
+    byId[documentId] = document;
+    if (!document._path) {
+      continue;
+    }
+    const path = normalizePath(document._path);
+    manifest.paths[path] ||= [];
+    if (document._locale === defaultLocale) {
+      manifest.paths[path].unshift(documentId);
+    } else {
+      manifest.paths[path].push(documentId);
+    }
+    if (document._collection) {
+      manifest.collections[document._collection] ||= [];
+      manifest.collections[document._collection].push(documentId);
+    }
+    if (document._navigation) {
+      const locale2 = document._locale || defaultLocale;
+      byNavigationPath[path] ||= {};
+      byNavigationPath[path][locale2] = document;
+    }
+    const isVariantDocument = !document._partial && !document._navigation && document._canonicalKey;
+    if (!isVariantDocument) {
+      continue;
+    }
+    const locale = document._locale || defaultLocale;
+    const variant = {
+      canonicalKey: document._canonicalKey,
+      contentId: documentId,
+      locale,
+      path,
+      document
+    };
+    manifest.byCanonical[document._canonicalKey] ||= {};
+    manifest.byCanonical[document._canonicalKey][locale] = variant;
+    manifest.byRoute[`${locale}:${path}`] = document._canonicalKey;
+    if (document._type === "markdown" && typeof document.ref === "string" && document.ref.length) {
+      manifest.byRef[document.ref] = document._canonicalKey;
+    }
+  }
+  for (const [canonicalKey, variants] of Object.entries(manifest.byCanonical)) {
+    byCanonical[canonicalKey] = Object.fromEntries(
+      Object.entries(variants).map(([locale, variant]) => [
+        locale,
+        {
+          ...variant,
+          document: byId[variant.contentId]
+        }
+      ])
+    );
+  }
+  return {
+    documents,
+    byId,
+    byCollection: manifest.collections,
+    byPath: manifest.paths,
+    byCanonical,
+    byRoute: manifest.byRoute,
+    byRef: manifest.byRef,
+    byNavigationPath,
+    referenceTargets: buildReferenceTargets(documents.filter((document) => !document._partial && !document._navigation), options.locales || []),
+    manifest
+  };
+};
+export const resolveGraphVariant = (graph, canonicalKey, requestedLocale, options = {}) => {
+  const variants = graph.byCanonical[canonicalKey];
+  if (!variants) {
+    return null;
+  }
+  const collectionIds = options.collection ? new Set(graph.byCollection[options.collection] || []) : null;
+  const scopedVariants = collectionIds ? Object.fromEntries(Object.entries(variants).filter(([, v]) => collectionIds.has(v.contentId))) : variants;
+  if (!Object.keys(scopedVariants).length) {
+    return null;
+  }
+  const availableLocales = Object.keys(scopedVariants);
+  const localeChain = options.exact ? requestedLocale ? [requestedLocale] : [] : options.fallback?.length ? Array.from(new Set([requestedLocale, ...options.fallback].filter(Boolean))) : resolveLocaleChain(requestedLocale, options.defaultLocale, options.localeFallback || {});
+  const resolvedLocale = localeChain.find((locale) => scopedVariants[locale]) || (options.exact ? void 0 : availableLocales[0]);
+  if (resolvedLocale === void 0) {
+    return null;
+  }
+  const variant = scopedVariants[resolvedLocale];
+  return {
+    canonicalKey,
+    contentId: variant.contentId,
+    locale: variant.locale,
+    path: variant.path,
+    requestedLocale,
+    resolvedLocale,
+    fallback: Boolean(requestedLocale && resolvedLocale !== requestedLocale),
+    availableLocales
+  };
+};
+export const resolveGraphRouteVariant = (graph, routePath, requestedLocale, options = {}) => {
+  const normalizedPath = normalizePath(routePath);
+  const localeChain = options.exact ? requestedLocale ? [requestedLocale] : [] : options.fallback?.length ? Array.from(new Set([requestedLocale, ...options.fallback].filter(Boolean))) : resolveLocaleChain(requestedLocale, options.defaultLocale, options.localeFallback || {});
+  const localesToSearch = localeChain.length ? localeChain : Array.from(new Set(Object.values(graph.byCanonical).flatMap((variants) => Object.keys(variants))));
+  for (const locale of localesToSearch) {
+    const canonicalKey = graph.byRoute[`${locale}:${normalizedPath}`];
+    if (!canonicalKey) {
+      continue;
+    }
+    const variant = resolveGraphVariant(graph, canonicalKey, requestedLocale, options);
+    if (variant) return variant;
+  }
+  return null;
+};
+export const resolveGraphCanonicalKey = (graph, identity, collection) => {
+  const normalizedIdentity = normalizeReferenceValue(identity);
+  if (!normalizedIdentity) {
+    return null;
+  }
+  const hasCollectionVariant = (canonicalKey) => {
+    if (!collection) {
+      return true;
+    }
+    const collectionIds = new Set(graph.byCollection[collection] || []);
+    return Object.values(graph.byCanonical[canonicalKey] || {}).some((variant) => collectionIds.has(variant.contentId));
+  };
+  if (graph.byCanonical[normalizedIdentity] && hasCollectionVariant(normalizedIdentity)) {
+    return normalizedIdentity;
+  }
+  const refCanonicalKey = graph.byRef[normalizedIdentity];
+  if (refCanonicalKey && hasCollectionVariant(refCanonicalKey)) {
+    return refCanonicalKey;
+  }
+  if (collection && !(graph.byCollection[collection] || []).length) {
+    return null;
+  }
+  const targetCanonicalKey = graph.referenceTargets.get(normalizedIdentity);
+  return targetCanonicalKey && hasCollectionVariant(targetCanonicalKey) ? targetCanonicalKey : null;
+};
+export const resolveGraphCollectionLocales = (graph, identity, collection) => {
+  const canonicalKey = resolveGraphCanonicalKey(graph, identity, collection);
+  if (!canonicalKey) {
+    return [];
+  }
+  return Object.values(graph.byCanonical[canonicalKey] || {}).sort((a, b) => a.locale.localeCompare(b.locale)).map((variant) => ({
+    canonicalKey,
+    locale: variant.locale,
+    ...variant.path ? { path: variant.path } : {}
+  }));
+};
+export const selectGraphDocuments = (graph, options = {}) => {
+  const { collection, paths = [] } = options;
+  const hasIndexedFilter = Boolean(collection || paths.length);
+  let ids = collection ? [...graph.byCollection[collection] || []] : [];
+  if (paths.length) {
+    const pathIds = Array.from(new Set(paths.flatMap((path) => {
+      return Object.keys(graph.byPath).filter((key) => path instanceof RegExp ? path.test(key) : key === path).flatMap((key) => graph.byPath[key] || []);
+    })));
+    ids = ids.length ? pathIds.filter((id) => ids.includes(id)) : pathIds;
+  }
+  if (!ids.length) {
+    if (hasIndexedFilter) {
+      return [];
+    }
+    return graph.documents;
+  }
+  return ids.map((id) => graph.byId[id]).filter(Boolean);
+};

package/dist/core/content/ignore

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

package/dist/core/content/ignore.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Creates a predicate for storage keys such as `content:source:docs:intro.md`
+ * against configured content ignore patterns.
+ */
+export declare function makeIgnored(ignores: string[]): (key: string) => boolean;

package/dist/core/content/ignore.js

@@ -0,0 +1,10 @@
+export function makeIgnored(ignores) {
+  const patterns = ["/\\.", "/-", ...ignores.filter(Boolean)].map((pattern) => new RegExp(pattern));
+  return function isIgnored(key) {
+    const path = `/${key.replace(/:/g, "/")}`;
+    if (path.endsWith("/.navigation.yml")) {
+      return false;
+    }
+    return patterns.some((pattern) => pattern.test(path));
+  };
+}

package/dist/core/content/locale

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

package/dist/core/content/locale.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Locale utilities shared by the graph, the query planner, and the ingest
+ * pipeline. Three concepts to keep straight:
+ *
+ *  1. **Fallback chain** — the ordered list of locales to try when a
+ *     variant is missing (`buildLocaleFallbackChain`). User-configured
+ *     per-locale fallbacks come first; the site default ties it off.
+ *
+ *  2. **Inline locale variant id** — YAML/JSON sources can carry locale
+ *     overrides inline (`i18n: { de: { title: '…' } }`). We split each
+ *     such document into one variant per locale at ingest; the
+ *     synthetic variants share a `_id` shape of
+ *     `${sourceId}#__locale=${locale}`. `splitInlineLocaleVariantId`
+ *     reverses that for lookups.
+ *
+ *  3. **Inline override merge** — `expandDataLocaleVariants` does a
+ *     deep merge of the base document with each locale-specific
+ *     override, cloning values along the way so variants never share
+ *     references with the base or with each other.
+ */
+import type { ParsedContent } from '../../types/content';
+import type { ContentCollectionI18nConfig } from '../../types/config';
+/** Separator between source id and locale in inline-variant ids. */
+export declare const INLINE_LOCALE_ID_SEPARATOR = "#__locale=";
+/**
+ * Produce the fallback chain for a specific locale (excluding the locale
+ * itself). The caller prepends the requested locale if it wants a
+ * walkable chain — this helper is what to look at *after* the requested
+ * locale missed.
+ *
+ * @example
+ * buildLocaleFallbackChain('fr', 'en', { fr: ['de'] })  // ['de', 'en']
+ * buildLocaleFallbackChain('en', 'en')                 // []
+ */
+export declare const buildLocaleFallbackChain: (locale: string, defaultLocale?: string, fallback?: Record<string, string[]>) => string[];
+/**
+ * Split an inline-variant id back into `{ sourceId, locale }`. Returns the
+ * input unchanged (with `locale: undefined`) when no separator is found.
+ */
+export declare const splitInlineLocaleVariantId: (id: string) => {
+    sourceId: string;
+    locale: string | undefined;
+};
+/**
+ * Expand a single YAML/JSON document with inline `i18n` overrides into one
+ * document per configured locale.
+ *
+ * Markdown documents are returned unchanged — they express locale
+ * variants via filename (`index.en.md`, `index.de.md`) rather than
+ * inline keys, so the ingest pipeline already produces one document
+ * per variant.
+ *
+ * The base document (without the `i18n` key) becomes the source-locale
+ * variant. Each sibling locale gets a deep-merged variant that inherits
+ * from the base and overrides keys listed under `i18n[locale]`.
+ *
+ * GOTCHA: a non-object override (e.g. a string) is skipped with a warn.
+ * We do not throw — translation data is user-authored and one malformed
+ * override should not fail ingest for the whole document.
+ */
+export declare const expandDataLocaleVariants: (document: ParsedContent, i18nConfig?: ContentCollectionI18nConfig) => ParsedContent[];

package/dist/core/content/locale.js

@@ -0,0 +1,77 @@
+export const INLINE_LOCALE_ID_SEPARATOR = "#__locale=";
+const isPlainObject = (value) => {
+  return Boolean(value) && Object.prototype.toString.call(value) === "[object Object]";
+};
+const cloneValue = (value) => {
+  if (Array.isArray(value)) {
+    return value.map((item) => cloneValue(item));
+  }
+  if (isPlainObject(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, cloneValue(item)]));
+  }
+  return value;
+};
+const mergeLocaleOverride = (base, override) => {
+  if (typeof override === "undefined") {
+    return cloneValue(base);
+  }
+  if (Array.isArray(override)) {
+    return cloneValue(override);
+  }
+  if (isPlainObject(base) && isPlainObject(override)) {
+    const merged = Object.fromEntries(Object.entries(base).map(([key, value]) => [key, cloneValue(value)]));
+    for (const [key, value] of Object.entries(override)) {
+      merged[key] = key in merged ? mergeLocaleOverride(merged[key], value) : cloneValue(value);
+    }
+    return merged;
+  }
+  return cloneValue(override);
+};
+export const buildLocaleFallbackChain = (locale, defaultLocale, fallback) => {
+  return Array.from(/* @__PURE__ */ new Set([
+    ...fallback?.[locale] || [],
+    ...defaultLocale && defaultLocale !== locale ? [defaultLocale] : []
+  ]));
+};
+export const splitInlineLocaleVariantId = (id) => {
+  const separatorIndex = id.indexOf(INLINE_LOCALE_ID_SEPARATOR);
+  if (separatorIndex === -1) {
+    return { sourceId: id, locale: void 0 };
+  }
+  return {
+    sourceId: id.slice(0, separatorIndex),
+    locale: id.slice(separatorIndex + INLINE_LOCALE_ID_SEPARATOR.length) || void 0
+  };
+};
+export const expandDataLocaleVariants = (document, i18nConfig) => {
+  if (!i18nConfig || document._type !== "yaml" && document._type !== "json") {
+    return [document];
+  }
+  const rawI18n = isPlainObject(document.i18n) ? document.i18n : void 0;
+  if (!rawI18n) {
+    return [document];
+  }
+  const { i18n: _removed, ...baseDocument } = document;
+  const sourceLocale = document._locale || i18nConfig.defaultLocale;
+  const variants = [{ ...baseDocument, _locale: sourceLocale }];
+  for (const locale of i18nConfig.locales) {
+    if (locale === sourceLocale) {
+      continue;
+    }
+    const override = rawI18n[locale];
+    if (typeof override !== "undefined" && !isPlainObject(override)) {
+      console.warn(`[content] Inline i18n override for locale "${locale}" in "${document._id}" must be an object. Skipping invalid override.`);
+      continue;
+    }
+    if (!isPlainObject(override)) {
+      continue;
+    }
+    const merged = mergeLocaleOverride(baseDocument, override);
+    variants.push({
+      ...merged,
+      _id: `${document._id}${INLINE_LOCALE_ID_SEPARATOR}${locale}`,
+      _locale: locale
+    });
+  }
+  return variants;
+};

package/dist/core/content/path

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

package/dist/core/content/path.d.ts

@@ -0,0 +1,36 @@
+export declare const describeId: (id: string) => {
+    _source: string;
+    _path: string;
+    _extension: string;
+    _file: string;
+    _basename: string;
+};
+export declare const isDraftPath: (path: string) => boolean;
+export declare const isPartialPath: (path: string) => boolean;
+export declare const normalizeContentPath: (path: string) => string;
+export declare function refineUrlPart(name: string): string;
+export declare const generatePath: (path: string, { forceLeadingSlash, respectPathCase }?: {
+    forceLeadingSlash?: boolean;
+    respectPathCase?: boolean;
+}) => string;
+export declare const generateCanonicalKey: (parts: string[], { translatedSlugs, respectPathCase }?: {
+    translatedSlugs?: boolean;
+    respectPathCase?: boolean;
+}) => string;
+export declare const generateTitle: (path: string) => string;
+export type RouteMounts = Record<string, string>;
+export declare const normalizeRouteMounts: (route: string | Record<string, string> | undefined, locales?: string[], defaultLocale?: string) => RouteMounts | undefined;
+export declare const longestMountForPath: (path: string, mounts: RouteMounts) => [string, string];
+export declare const routeRemainder: (path: string, mount: string) => string;
+export declare const mountContentPath: (remainder: string, locale: string | undefined, mounts?: RouteMounts) => string;
+export declare const prefixPathWithLocale: (path: string, locale?: string, defaultLocale?: string) => string;
+export declare const stripLocalePrefix: (path: string, locales?: string[], defaultLocale?: string, explicitLocale?: string) => {
+    locale: string | undefined;
+    path: string;
+};
+export declare const routeToContentPathCandidates: (route: string, requestedLocale: string | undefined, localeChain: string[], defaultLocale?: string, mounts?: RouteMounts) => {
+    locale: string;
+    path: string;
+}[];
+export declare const projectContentPathToLocale: (path: string, locale?: string, defaultLocale?: string, mounts?: RouteMounts) => string;
+export declare const pathHasLocalePrefix: (path: string, locales: string[]) => boolean;