@usecds/server 0.0.0-stage → 0.1.1

package/dist/core/jsonld.d.ts

@@ -0,0 +1,33 @@
+import { CollectionItem } from "../types.js";
+export declare const JSONLD_COLLECTION = "_jsonld";
+/**
+ * Field paths in a definition's map:
+ *   name, address.city, amenities[0]   field of the item (translations[locale] first, then the item)
+ *   media[0]                           the item's first media file, as an ImageObject
+ *   ref:hotels                         the item's reference into "hotels", with that collection's JSON-LD
+ */
+export declare const JSONLD_PATH: RegExp;
+export interface JsonLdDefinition extends CollectionItem {
+    type: string;
+    appliesTo?: string;
+    values?: Record<string, any>;
+    map?: Record<string, string>;
+}
+/**
+ * Checks the _jsonld collection against the content. Throws on the first problem:
+ * invalid definitions or paths, ref: to unknown collections, references to unknown
+ * definitions, and more than one default (appliesTo) per collection.
+ */
+export declare function validateJsonLd(collections: Record<string, CollectionItem[]>): void;
+/**
+ * The definition that describes an item: its own reference into _jsonld, else its collection's default.
+ */
+export declare function jsonLdDefinitionFor(collections: Record<string, CollectionItem[]>, collection: string, item: CollectionItem): JsonLdDefinition | undefined;
+/**
+ * Value of a plain field path (not media[] or ref:) for one locale; undefined if absent.
+ */
+export declare function readFieldPath(item: CollectionItem, locale: string, path: string): unknown;
+/**
+ * Whether a mapped path yields nothing for an item and locale (used for report recommendations).
+ */
+export declare function isJsonLdPathEmpty(collections: Record<string, CollectionItem[]>, item: CollectionItem, locale: string, path: string): boolean;

package/dist/core/jsonld.js

@@ -0,0 +1,94 @@
+import { validateJsonLdDefinition } from "../validation.js";
+// Reserved collection holding schema.org JSON-LD definitions
+export const JSONLD_COLLECTION = "_jsonld";
+/**
+ * Field paths in a definition's map:
+ *   name, address.city, amenities[0]   field of the item (translations[locale] first, then the item)
+ *   media[0]                           the item's first media file, as an ImageObject
+ *   ref:hotels                         the item's reference into "hotels", with that collection's JSON-LD
+ */
+export const JSONLD_PATH = /^(?:media\[\d+\]|ref:[\w-]+|[A-Za-z_]\w*(?:\[\d+\])?(?:\.[A-Za-z_]\w*(?:\[\d+\])?)*)$/;
+/**
+ * Checks the _jsonld collection against the content. Throws on the first problem:
+ * invalid definitions or paths, ref: to unknown collections, references to unknown
+ * definitions, and more than one default (appliesTo) per collection.
+ */
+export function validateJsonLd(collections) {
+    const definitions = (collections[JSONLD_COLLECTION] ?? []);
+    const ids = new Set(definitions.map((d) => d.id));
+    const defaults = new Map();
+    for (const def of definitions) {
+        validateJsonLdDefinition(def);
+        if (def.appliesTo) {
+            if (!collections[def.appliesTo]) {
+                throw new Error(`Invalid _jsonld item (${def.id}): appliesTo unknown collection "${def.appliesTo}"`);
+            }
+            const existing = defaults.get(def.appliesTo);
+            if (existing) {
+                throw new Error(`Collection "${def.appliesTo}" has two JSON-LD defaults: ${existing} and ${def.id}`);
+            }
+            defaults.set(def.appliesTo, def.id);
+        }
+        for (const [property, path] of Object.entries(def.map ?? {})) {
+            if (!JSONLD_PATH.test(path)) {
+                throw new Error(`Invalid _jsonld item (${def.id}): "${property}" has an invalid path "${path}"`);
+            }
+            const ref = path.match(/^ref:(.+)$/);
+            if (ref && !collections[ref[1]]) {
+                throw new Error(`Invalid _jsonld item (${def.id}): "${property}" refers to unknown collection "${ref[1]}"`);
+            }
+        }
+    }
+    for (const [collection, items] of Object.entries(collections)) {
+        for (const item of items) {
+            for (const ref of item.references ?? []) {
+                if (ref.collection === JSONLD_COLLECTION && !ids.has(ref.id)) {
+                    throw new Error(`Item ${collection}/${item.id} references unknown _jsonld definition "${ref.id}"`);
+                }
+            }
+        }
+    }
+}
+/**
+ * The definition that describes an item: its own reference into _jsonld, else its collection's default.
+ */
+export function jsonLdDefinitionFor(collections, collection, item) {
+    const definitions = (collections[JSONLD_COLLECTION] ?? []);
+    const own = item.references?.find((r) => r.collection === JSONLD_COLLECTION);
+    if (own)
+        return definitions.find((d) => d.id === own.id);
+    return definitions.find((d) => d.appliesTo === collection);
+}
+/**
+ * Value of a plain field path (not media[] or ref:) for one locale; undefined if absent.
+ */
+export function readFieldPath(item, locale, path) {
+    const segments = path.split(".");
+    const step = (value, segment) => {
+        const [, key, index] = segment.match(/^(\w+)(?:\[(\d+)\])?$/) ?? [];
+        const next = value?.[key];
+        return index === undefined ? next : next?.[Number(index)];
+    };
+    const [first, ...rest] = segments;
+    const localized = step(item.translations[locale], first);
+    let value = localized !== undefined ? localized : step(item, first);
+    for (const segment of rest)
+        value = step(value, segment);
+    return value;
+}
+/**
+ * Whether a mapped path yields nothing for an item and locale (used for report recommendations).
+ */
+export function isJsonLdPathEmpty(collections, item, locale, path) {
+    const media = path.match(/^media\[(\d+)\]$/);
+    if (media)
+        return !item.media?.[Number(media[1])];
+    const ref = path.match(/^ref:(.+)$/);
+    if (ref) {
+        const ids = new Set((collections[ref[1]] ?? []).map((i) => i.id));
+        return !(item.references ?? []).some((r) => r.collection === ref[1] && ids.has(r.id));
+    }
+    const value = readFieldPath(item, locale, path);
+    return value === undefined || value === null || value === "";
+}
+//# sourceMappingURL=jsonld.js.map

package/dist/core/jsonld.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonld.js","sourceRoot":"","sources":["../../src/core/jsonld.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,6DAA6D;AAC7D,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,uFAAuF,CAAC;AASnH;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,WAA6C;IAC1E,MAAM,WAAW,GAAG,CAAC,WAAW,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAuB,CAAC;IACjF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE3C,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,wBAAwB,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YAClB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBAChC,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,CAAC,EAAE,oCAAoC,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC;YACvG,CAAC;YACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC7C,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CAAC,eAAe,GAAG,CAAC,SAAS,+BAA+B,QAAQ,QAAQ,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;YACvG,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACtC,CAAC;QACD,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;YAC7D,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,CAAC,EAAE,OAAO,QAAQ,0BAA0B,IAAI,GAAG,CAAC,CAAC;YACnG,CAAC;YACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YACrC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChC,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,CAAC,EAAE,OAAO,QAAQ,mCAAmC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC9G,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QAC9D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;gBACxC,IAAI,GAAG,CAAC,UAAU,KAAK,iBAAiB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;oBAC7D,MAAM,IAAI,KAAK,CAAC,QAAQ,UAAU,IAAI,IAAI,CAAC,EAAE,2CAA2C,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;gBACrG,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,WAA6C,EAC7C,UAAkB,EAClB,IAAoB;IAEpB,MAAM,WAAW,GAAG,CAAC,WAAW,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAuB,CAAC;IACjF,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,iBAAiB,CAAC,CAAC;IAC7E,IAAI,GAAG;QAAE,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;IACzD,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,UAAU,CAAC,CAAC;AAC7D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,IAAoB,EAAE,MAAc,EAAE,IAAY;IAC9E,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,CAAC,KAAU,EAAE,OAAe,EAAE,EAAE;QAC3C,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,IAAI,EAAE,CAAC;QACpE,MAAM,IAAI,GAAG,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;QAC1B,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5D,CAAC,CAAC;IACF,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,QAAQ,CAAC;IAClC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,CAAC;IACzD,IAAI,KAAK,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACpE,KAAK,MAAM,OAAO,IAAI,IAAI;QAAE,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACzD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,WAA6C,EAC7C,IAAoB,EACpB,MAAc,EACd,IAAY;IAEZ,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC7C,IAAI,KAAK;QAAE,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACrC,IAAI,GAAG,EAAE,CAAC;QACR,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAClE,OAAO,CAAC,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAChD,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;AAC/D,CAAC"}

package/dist/core/media-metadata.d.ts

@@ -0,0 +1,20 @@
+import { CollectionItem, MediaMeta } from "../types.js";
+export declare const MEDIA_COLLECTION = "_media";
+/**
+ * Checks the _media collection: every item must match the schema and refer to a media
+ * file in the release, and no media file may be described twice. Throws on the first problem.
+ * (The publisher has already dropped entries for media that isn't published.)
+ */
+export declare function validateMediaMetadata(items: CollectionItem[], media: Record<string, MediaMeta>): void;
+/**
+ * Where media files are used: "all" when listed in an item's media array, otherwise the
+ * locales whose translations list it (translations[locale].media, for language-specific media).
+ * Media that isn't used anywhere is not published.
+ */
+export type MediaUsage = Map<string, "all" | Set<string>>;
+export declare function collectMediaUsage(collections: Record<string, CollectionItem[]>): MediaUsage;
+/**
+ * Locales in which a media file is shown, so its _media texts are expected only there.
+ * Undefined means every locale.
+ */
+export declare function mediaLocales(usage: MediaUsage, path: string): string[] | undefined;

package/dist/core/media-metadata.js

@@ -0,0 +1,53 @@
+import { validateMediaMetadataItem } from "../validation.js";
+// Reserved collection holding metadata (alt text, description, focal point, size) per media file
+export const MEDIA_COLLECTION = "_media";
+/**
+ * Checks the _media collection: every item must match the schema and refer to a media
+ * file in the release, and no media file may be described twice. Throws on the first problem.
+ * (The publisher has already dropped entries for media that isn't published.)
+ */
+export function validateMediaMetadata(items, media) {
+    const seen = new Set();
+    for (const item of items) {
+        validateMediaMetadataItem(item);
+        if (!media[item.id]) {
+            throw new Error(`Invalid _media item (${item.id}): no media file with this virtual path in the release`);
+        }
+        if (seen.has(item.id)) {
+            throw new Error(`Invalid _media item (${item.id}): described more than once`);
+        }
+        seen.add(item.id);
+    }
+}
+export function collectMediaUsage(collections) {
+    const usage = new Map();
+    for (const [collection, items] of Object.entries(collections)) {
+        if (collection === MEDIA_COLLECTION)
+            continue;
+        for (const item of items) {
+            for (const path of item.media ?? [])
+                usage.set(path, "all");
+            for (const [locale, fields] of Object.entries(item.translations)) {
+                const localized = fields?.media;
+                if (!Array.isArray(localized))
+                    continue;
+                for (const path of localized) {
+                    const current = usage.get(path);
+                    if (current === "all")
+                        continue;
+                    usage.set(path, (current ?? new Set()).add(locale));
+                }
+            }
+        }
+    }
+    return usage;
+}
+/**
+ * Locales in which a media file is shown, so its _media texts are expected only there.
+ * Undefined means every locale.
+ */
+export function mediaLocales(usage, path) {
+    const used = usage.get(path);
+    return used === undefined || used === "all" ? undefined : [...used].sort();
+}
+//# sourceMappingURL=media-metadata.js.map

package/dist/core/media-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-metadata.js","sourceRoot":"","sources":["../../src/core/media-metadata.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,iGAAiG;AACjG,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC;AAEzC;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAuB,EAAE,KAAgC;IAC7F,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,yBAAyB,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,EAAE,wDAAwD,CAAC,CAAC;QAC3G,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,EAAE,6BAA6B,CAAC,CAAC;QAChF,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AASD,MAAM,UAAU,iBAAiB,CAAC,WAA6C;IAC7E,MAAM,KAAK,GAAe,IAAI,GAAG,EAAE,CAAC;IACpC,KAAK,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QAC9D,IAAI,UAAU,KAAK,gBAAgB;YAAE,SAAS;QAC9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE;gBAAE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC5D,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;gBACjE,MAAM,SAAS,GAAG,MAAM,EAAE,KAAK,CAAC;gBAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;oBAAE,SAAS;gBACxC,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;oBAC7B,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;oBAChC,IAAI,OAAO,KAAK,KAAK;wBAAE,SAAS;oBAChC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,IAAI,IAAI,GAAG,EAAU,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC9D,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAiB,EAAE,IAAY;IAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;AAC7E,CAAC"}

package/dist/core/media-names.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Explains why a media file name doesn't describe the image (camera/app/AI defaults, ids,
+ * dates and numbers only), or returns undefined if it contains at least one descriptive word.
+ */
+export declare function meaninglessNameReason(fileName: string): string | undefined;
+/**
+ * A name suggestion from a text such as the alt text: its first meaningful words as a slug.
+ */
+export declare function suggestMediaName(text: string, maxWords?: number): string;

package/dist/core/media-names.js

@@ -0,0 +1,58 @@
+// Words that don't describe what an image shows: camera and app prefixes, generic nouns,
+// AI tool names, versioning words and month names (English and German)
+const FILLER = new Set([
+    "img", "image", "images", "photo", "photos", "foto", "fotos", "bild", "bilder", "pic", "pics", "picture", "pictures",
+    "screenshot", "screen", "shot", "bildschirmfoto", "scan", "scans", "capture",
+    "dsc", "dscn", "dscf", "pxl", "mvimg", "gopr", "dji", "vid", "video", "camera", "cam",
+    "whatsapp", "telegram", "signal",
+    "chatgpt", "dall", "dalle", "gemini", "generated", "midjourney", "firefly", "copilot",
+    "copy", "kopie", "final", "edited", "edit", "new", "neu", "old", "alt", "untitled", "unnamed", "unbenannt",
+    "download", "downloads", "file", "datei", "unknown", "default", "temp", "tmp", "test", "version", "export", "uhr",
+    "jan", "january", "januar", "feb", "february", "februar", "mar", "march", "maerz", "apr", "april", "may", "mai",
+    "jun", "june", "juni", "jul", "july", "juli", "aug", "august", "sep", "sept", "september", "oct", "october",
+    "okt", "oktober", "nov", "november", "dec", "december", "dez", "dezember"
+]);
+// Recognizable defaults, used to explain why a name says nothing
+const DEFAULTS = [
+    { reason: "UUID", pattern: /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i },
+    { reason: "AI tool default name", pattern: /chatgpt|dall[·.\-_ ]?e|gemini[_ -]?generated|midjourney|firefly|copilot/i },
+    { reason: "screenshot default name", pattern: /screen ?shot|bildschirmfoto|capture/i },
+    { reason: "messenger default name", pattern: /whatsapp|telegram|signal|^photo_\d{4}-\d{2}-\d{2}/i },
+    { reason: "camera default name", pattern: /^(img|dsc[nf]?|pxl|mvimg|gopr|dji|vid)[_-]?\d|^p\d{7}/i },
+    { reason: "hash or random id", pattern: /^[0-9a-f_-]{12,}$/i }
+];
+const STOP_WORDS = new Set(["a", "an", "the", "with", "and", "of", "on", "in", "at", "to", "ein", "eine", "einem", "einer", "der", "die", "das", "mit", "und", "von", "im", "am", "zu", "auf"]);
+const baseName = (path) => path.split("/").pop().replace(/\.[^.]+$/, "");
+/**
+ * Explains why a media file name doesn't describe the image (camera/app/AI defaults, ids,
+ * dates and numbers only), or returns undefined if it contains at least one descriptive word.
+ */
+export function meaninglessNameReason(fileName) {
+    const name = baseName(fileName);
+    const words = name
+        .toLowerCase()
+        .replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss")
+        .split(/[^a-z0-9]+/)
+        // ids and hashes: long hex runs with digits
+        .filter((token) => !(/^[0-9a-f]{6,}$/.test(token) && /\d/.test(token)))
+        // "img2034" -> "img", "2034"
+        .flatMap((token) => token.match(/[a-z]+|\d+/g) ?? [])
+        .filter((token) => /^[a-z]{3,}$/.test(token) && !FILLER.has(token));
+    if (words.length > 0)
+        return undefined;
+    return DEFAULTS.find((d) => d.pattern.test(name))?.reason ?? "no descriptive words";
+}
+/**
+ * A name suggestion from a text such as the alt text: its first meaningful words as a slug.
+ */
+export function suggestMediaName(text, maxWords = 5) {
+    return text
+        .toLowerCase()
+        .replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss")
+        .normalize("NFKD").replace(/[\u0300-\u036f]/g, "")
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word && !STOP_WORDS.has(word))
+        .slice(0, maxWords)
+        .join("-");
+}
+//# sourceMappingURL=media-names.js.map

package/dist/core/media-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-names.js","sourceRoot":"","sources":["../../src/core/media-names.ts"],"names":[],"mappings":"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"}

package/dist/core/menu.d.ts

@@ -0,0 +1,33 @@
+import { CollectionItem } from "../types.js";
+export declare const MENU_COLLECTION = "_menu";
+export declare const MAX_MENU_DEPTH = 3;
+export interface MenuLink {
+    route?: string;
+    block?: string;
+    url?: string;
+}
+export interface MenuItem extends CollectionItem {
+    children?: string[];
+    link?: MenuLink;
+}
+/**
+ * Checks _menu and the links blocks use. Throws on the first problem: schema errors, unknown
+ * children, cycles, menus nested deeper than MAX_MENU_DEPTH, links with neither or both of
+ * route/url, unknown routes or blocks, a block that isn't on the route's page, relative URLs,
+ * and block links to unknown items.
+ */
+export declare function validateMenu(collections: Record<string, CollectionItem[]>): void;
+/**
+ * Menus: _menu items that no other item lists as a child.
+ */
+export declare function menuRoots(collections: Record<string, CollectionItem[]>): MenuItem[];
+/**
+ * Entries (items with a link) that have no label in any locale.
+ */
+export declare function menuRecommendations(collections: Record<string, CollectionItem[]>): {
+    collection: string;
+    id: string;
+    issue: string;
+    field: string;
+    message: string;
+}[];

package/dist/core/menu.js

@@ -0,0 +1,89 @@
+import { validateMenuItem } from "../validation.js";
+import { BLOCKS_COLLECTION, PAGES_COLLECTION, ROUTES_COLLECTION } from "./site.js";
+// Optional, typed reserved collection of nestable link items
+export const MENU_COLLECTION = "_menu";
+export const MAX_MENU_DEPTH = 3; // entry levels below a menu
+// Protocol-relative //host links are external too
+const EXTERNAL_URL = /^(https?:\/\/|\/\/|mailto:|tel:)/;
+/**
+ * Checks _menu and the links blocks use. Throws on the first problem: schema errors, unknown
+ * children, cycles, menus nested deeper than MAX_MENU_DEPTH, links with neither or both of
+ * route/url, unknown routes or blocks, a block that isn't on the route's page, relative URLs,
+ * and block links to unknown items.
+ */
+export function validateMenu(collections) {
+    const items = new Map((collections[MENU_COLLECTION] ?? []).map((i) => [i.id, i]));
+    const routes = new Map((collections[ROUTES_COLLECTION] ?? []).map((r) => [r.id, r]));
+    const pages = new Map((collections[PAGES_COLLECTION] ?? []).map((p) => [p.id, p]));
+    const blocks = new Map((collections[BLOCKS_COLLECTION] ?? []).map((b) => [b.id, b]));
+    for (const item of items.values()) {
+        validateMenuItem(item);
+        for (const child of item.children ?? []) {
+            if (!items.has(child))
+                throw new Error(`Invalid _menu item (${item.id}): unknown child "${child}"`);
+        }
+        const link = item.link;
+        if (!link)
+            continue;
+        if (!!link.route === !!link.url) {
+            throw new Error(`Invalid _menu item (${item.id}): a link needs either a route or a url`);
+        }
+        if (link.url && !EXTERNAL_URL.test(link.url)) {
+            throw new Error(`Invalid _menu item (${item.id}): url must be absolute (https://, //host, mailto:, tel:), got "${link.url}"`);
+        }
+        if (link.route) {
+            const route = routes.get(link.route);
+            if (!route)
+                throw new Error(`Invalid _menu item (${item.id}): unknown route "${link.route}"`);
+            if (link.block) {
+                if (!blocks.has(link.block))
+                    throw new Error(`Invalid _menu item (${item.id}): unknown block "${link.block}"`);
+                const onPage = route.page ? pages.get(route.page)?.blocks?.includes(link.block) : false;
+                if (!onPage) {
+                    throw new Error(`Invalid _menu item (${item.id}): block "${link.block}" isn't on the page of route "${link.route}"`);
+                }
+            }
+        }
+        else if (link.block) {
+            throw new Error(`Invalid _menu item (${item.id}): a block anchor needs a route`);
+        }
+    }
+    // Cycles and depth, walking down from every item
+    const walk = (id, path) => {
+        if (path.includes(id))
+            throw new Error(`Menu cycle: ${[...path, id].join(" -> ")}`);
+        if (path.length > MAX_MENU_DEPTH) {
+            throw new Error(`Menu ${path[0]} is nested deeper than ${MAX_MENU_DEPTH} levels (${[...path, id].join(" -> ")})`);
+        }
+        for (const child of items.get(id)?.children ?? [])
+            walk(child, [...path, id]);
+    };
+    for (const root of menuRoots(collections))
+        walk(root.id, []);
+    // Items in a cycle aren't reachable from any root, so check them as well
+    for (const item of items.values())
+        walk(item.id, []);
+    for (const block of blocks.values()) {
+        for (const linkId of block.links ?? []) {
+            if (!items.has(linkId))
+                throw new Error(`Invalid _blocks item (${block.id}): unknown _menu link "${linkId}"`);
+        }
+    }
+}
+/**
+ * Menus: _menu items that no other item lists as a child.
+ */
+export function menuRoots(collections) {
+    const items = (collections[MENU_COLLECTION] ?? []);
+    const children = new Set(items.flatMap((i) => i.children ?? []));
+    return items.filter((i) => !children.has(i.id));
+}
+/**
+ * Entries (items with a link) that have no label in any locale.
+ */
+export function menuRecommendations(collections) {
+    return (collections[MENU_COLLECTION] ?? [])
+        .filter((i) => i.link && !Object.values(i.translations).some((t) => typeof t?.label === "string" && t.label))
+        .map((i) => ({ collection: MENU_COLLECTION, id: i.id, issue: "missing-label", field: "label", message: `Menu entry ${i.id} has no label in any locale, so it's never shown` }));
+}
+//# sourceMappingURL=menu.js.map

package/dist/core/menu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu.js","sourceRoot":"","sources":["../../src/core/menu.ts"],"names":[],"mappings":"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"}

package/dist/core/publisher.d.ts

@@ -0,0 +1,77 @@
+import { ContentSource, ObjectStore, ReleaseManifest, SourceMap } from "../types.js";
+import { StorageReport } from "./storage-report.js";
+import { TranslationReport } from "./translations.js";
+import { TargetDefinition } from "./targets.js";
+import { ContentReport } from "./content-report.js";
+export interface PublisherConfig {
+    retentionCount?: number;
+}
+export interface PublishOptions {
+    sourceLocale?: string;
+    targets?: TargetDefinition[];
+}
+export interface PublishArtifacts {
+    sourceMap?: SourceMap & {
+        releaseId: string;
+    };
+    translations: TranslationReport;
+    content: ContentReport;
+    targets: Record<string, TargetDefinition>;
+}
+/**
+ * Thrown when content fails a target requirement. Nothing has been written to the store.
+ * The artifacts (including the content report) are attached for the pipeline.
+ */
+export declare class PublishRequirementsError extends Error {
+    artifacts: PublishArtifacts;
+    constructor(artifacts: PublishArtifacts);
+}
+export interface PublishResult {
+    manifest: ReleaseManifest;
+    artifacts: PublishArtifacts;
+}
+export interface GarbageCollectOptions {
+    dryRun?: boolean;
+}
+export interface GarbageCollectResult {
+    dryRun: boolean;
+    deletedObjects: number;
+    deletedMedia: number;
+    freedBytes: number;
+    report: StorageReport;
+}
+export declare class Publisher {
+    private source;
+    private store;
+    private config;
+    constructor(source: ContentSource, store: ObjectStore, config?: PublisherConfig);
+    /**
+     * Compiles the source content and publishes a new release to the object store.
+     * Updates the channel manifest as the final atomic action.
+     */
+    publish(channel: string, releaseId: string, options?: PublishOptions): Promise<PublishResult>;
+    /**
+     * Source locale precedence: publish argument → ContentSource → inferred from markers → "en".
+     */
+    private resolveSourceLocale;
+    /**
+     * Reads the collections of the release a channel currently points to, or undefined
+     * if the channel, its release or any of its objects are missing.
+     */
+    private readChannelCollections;
+    /**
+     * Cleans up old releases that exceed the configured retention limit.
+     * Releases that a channel currently points to are never deleted.
+     */
+    private manageReleaseRetention;
+    /**
+     * Reports per-release storage usage, diffs between releases, channel pointers
+     * and orphaned files. Read-only.
+     */
+    analyzeStorage(): Promise<StorageReport>;
+    /**
+     * Deletes all objects/media not referenced by any retained release.
+     * Deletes exactly the orphans listed in the returned report.
+     */
+    garbageCollect(options?: GarbageCollectOptions): Promise<GarbageCollectResult>;
+}