@stati/core 1.26.2 → 1.27.1

package/dist/core/utils/context-validation.utils.js

@@ -0,0 +1,175 @@
+import { isDevelopment } from '../../env.js';
+import { findSimilarNames } from './similarity.utils.js';
+/**
+ * Properties that must resolve normally even when they are not defined on the
+ * object, because the runtime, serializers, or test tooling probe for them.
+ */
+const PASSTHROUGH_PROPERTIES = new Set([
+    'length',
+    'constructor',
+    'then', // Promise detection
+    '$$typeof', // React inspection
+    'nodeType', // DOM node detection
+    'asymmetricMatch', // Jest/Vitest matcher
+    'toJSON', // JSON serialization
+]);
+/**
+ * Checks whether a property access should bypass validation.
+ */
+export function isPassthroughProperty(prop) {
+    return typeof prop === 'symbol' || prop in Object.prototype || PASSTHROUGH_PROPERTIES.has(prop);
+}
+/**
+ * Every `SiteConfig` field. Optional fields that a site leaves unset are absent at
+ * runtime, so they are listed here to keep `stati.site.description` from being
+ * reported as unknown. Typed as a Record so a new `SiteConfig` field fails to compile
+ * until it is added.
+ */
+const SITE_CONFIG_KEYS = {
+    title: true,
+    baseUrl: true,
+    defaultLocale: true,
+    description: true,
+};
+/**
+ * Context properties whose own keys form a closed set and are validated one level
+ * down, with keys that may be legitimately absent at runtime.
+ * `page` is left out because frontmatter keys differ from page to page, and
+ * `partials` already has its own validating proxy.
+ */
+const VALIDATED_NESTED_PROPERTIES = {
+    site: Object.keys(SITE_CONFIG_KEYS),
+    nav: [],
+    collection: [],
+    generator: [],
+};
+/**
+ * Context properties searched for an exact match when a key is missing from the
+ * root, so that `stati.title` can suggest `stati.page.title` and `stati.header`
+ * can suggest `stati.partials.header`.
+ */
+const CROSS_LEVEL_PROPERTIES = ['page', 'site', 'nav', 'partials'];
+/**
+ * Thrown in development when a template reads a property that does not exist
+ * on the template context.
+ *
+ * The suggestions are encoded in the message because Eta's debug mode rethrows
+ * runtime errors as a new error that only keeps the original message and name.
+ * Use {@link parseUnknownPropertyMessage} to read them back.
+ */
+export class UnknownTemplatePropertyError extends Error {
+    propertyPath;
+    suggestions;
+    constructor(propertyPath, suggestions, availableKeys) {
+        super(formatUnknownPropertyMessage(propertyPath, suggestions, availableKeys));
+        this.name = 'UnknownTemplatePropertyError';
+        this.propertyPath = propertyPath;
+        this.suggestions = suggestions;
+    }
+}
+function formatUnknownPropertyMessage(propertyPath, suggestions, availableKeys) {
+    const base = `Unknown property "${propertyPath}".`;
+    if (suggestions.length > 0) {
+        const quoted = suggestions.map((s) => `"${s}"`);
+        const list = quoted.length === 1 ? quoted[0] : `${quoted.slice(0, -1).join(', ')} or ${quoted.at(-1)}`;
+        return `${base} Did you mean ${list}?`;
+    }
+    return `${base} Available properties: ${availableKeys.join(', ')}.`;
+}
+/**
+ * Reads an {@link UnknownTemplatePropertyError} message back into a short message
+ * and a list of overlay suggestions. Returns `undefined` for any other message.
+ *
+ * @example
+ * ```typescript
+ * parseUnknownPropertyMessage('Unknown property "stati.paeg". Did you mean "stati.page"?');
+ * // { message: 'Unknown property "stati.paeg"', suggestions: ['Did you mean "stati.page"?'] }
+ * ```
+ */
+export function parseUnknownPropertyMessage(message) {
+    const match = message.match(/^Unknown property "([^"]+)"\.(?: Did you mean (.+)\?| Available properties: (.*)\.)?$/);
+    if (!match) {
+        return undefined;
+    }
+    const [, propertyPath, didYouMean, available] = match;
+    const suggestions = [];
+    if (didYouMean) {
+        for (const [, name] of didYouMean.matchAll(/"([^"]+)"/g)) {
+            suggestions.push(`Did you mean "${name}"?`);
+        }
+    }
+    else if (available !== undefined) {
+        const parentPath = propertyPath.slice(0, propertyPath.lastIndexOf('.'));
+        suggestions.push(`Available properties on ${parentPath}: ${available || '(none)'}`);
+    }
+    return { message: `Unknown property "${propertyPath}"`, suggestions };
+}
+function listKeys(target, extraKeys) {
+    return [...new Set([...Object.keys(target), ...extraKeys])].sort();
+}
+function createValidatingObjectProxy(target, path, extraKeys) {
+    return new Proxy(target, {
+        get(obj, prop, receiver) {
+            if (prop in obj || isPassthroughProperty(prop) || extraKeys.includes(prop)) {
+                return Reflect.get(obj, prop, receiver);
+            }
+            const name = String(prop);
+            const availableKeys = listKeys(obj, extraKeys);
+            const suggestions = findSimilarNames(name, availableKeys).map((key) => `${path}.${key}`);
+            throw new UnknownTemplatePropertyError(`${path}.${name}`, suggestions, availableKeys);
+        },
+    });
+}
+/**
+ * Wraps the template context so that reading a property that does not exist
+ * throws an {@link UnknownTemplatePropertyError} with "did you mean" suggestions
+ * instead of silently rendering `undefined`. The error reaches the dev server's
+ * error overlay.
+ *
+ * Validates the top-level `stati.*` keys (including custom filters, which are
+ * spread onto the context) and one level down for `site`, `nav`, `collection`,
+ * and `generator`. Frontmatter under `stati.page` is not validated.
+ *
+ * Only active in development; other environments get the context back unchanged.
+ */
+export function createValidatingContextProxy(context) {
+    if (!isDevelopment()) {
+        return context;
+    }
+    const nestedProxies = new Map();
+    return new Proxy(context, {
+        get(obj, prop, receiver) {
+            if (prop in obj || isPassthroughProperty(prop)) {
+                const value = Reflect.get(obj, prop, receiver);
+                const nestedExtraKeys = typeof prop === 'string' && Object.hasOwn(VALIDATED_NESTED_PROPERTIES, prop)
+                    ? VALIDATED_NESTED_PROPERTIES[prop]
+                    : undefined;
+                if (nestedExtraKeys && typeof value === 'object' && value !== null) {
+                    // Cache so that repeated reads return the same proxy (stati.nav === stati.nav)
+                    let nested = nestedProxies.get(prop);
+                    if (!nested) {
+                        nested = createValidatingObjectProxy(value, `stati.${String(prop)}`, nestedExtraKeys);
+                        nestedProxies.set(prop, nested);
+                    }
+                    return nested;
+                }
+                return value;
+            }
+            const name = String(prop);
+            const availableKeys = listKeys(obj, []);
+            // An exact match one level down (stati.title -> stati.page.title) is a
+            // stronger signal than a spelling match, so it goes first
+            const suggestions = [];
+            for (const parent of CROSS_LEVEL_PROPERTIES) {
+                const parentValue = obj[parent];
+                if (typeof parentValue === 'object' &&
+                    parentValue !== null &&
+                    Object.hasOwn(parentValue, name)) {
+                    suggestions.push(`stati.${parent}.${name}`);
+                }
+            }
+            suggestions.push(...findSimilarNames(name, availableKeys).map((key) => `stati.${key}`));
+            throw new UnknownTemplatePropertyError(`stati.${name}`, suggestions.slice(0, 3), availableKeys);
+        },
+    });
+}

package/dist/core/utils/date.utils.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Date utilities for reading publish dates from front matter.
+ * @module core/utils/date
+ */
+/**
+ * Front matter fields checked for a page's publish date, in priority order.
+ * Collections, navigation, ISG aging and RSS all use this order.
+ */
+export declare const PUBLISHED_DATE_FIELDS: readonly ["publishedAt", "published", "date", "createdAt"];
+/**
+ * Returns the publish date from front matter, or `undefined` if none is usable.
+ *
+ * Checks {@link PUBLISHED_DATE_FIELDS} in order and returns the first valid value.
+ * Accepts strings (quoted YAML dates) and `Date` objects (unquoted YAML dates,
+ * which gray-matter parses into `Date`). Missing, `null` and empty values are skipped;
+ * other invalid values are reported through `onInvalid` and skipped, so a bad
+ * `publishedAt` does not hide a valid `date`.
+ *
+ * @param frontMatter - Parsed front matter of a page; `null`/`undefined` returns `undefined`
+ * @param onInvalid - Called for each present field whose value is not a valid date
+ * @returns A new `Date` instance, or `undefined`
+ *
+ * @example
+ * ```typescript
+ * getFrontMatterDate({ date: new Date('2026-01-01') }); // 2026-01-01T00:00:00.000Z
+ * getFrontMatterDate({ publishedAt: 'soon', date: '2026-06-01' }); // 2026-06-01T00:00:00.000Z
+ * getFrontMatterDate({ title: 'Undated' }); // undefined
+ * ```
+ */
+export declare function getFrontMatterDate(frontMatter: Record<string, unknown> | null | undefined, onInvalid?: (field: string, value: unknown) => void): Date | undefined;
+//# sourceMappingURL=date.utils.d.ts.map

package/dist/core/utils/date.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/date.utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,4DAA6D,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EACvD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GAClD,IAAI,GAAG,SAAS,CA0BlB"}

package/dist/core/utils/date.utils.js

@@ -0,0 +1,52 @@
+/**
+ * Date utilities for reading publish dates from front matter.
+ * @module core/utils/date
+ */
+/**
+ * Front matter fields checked for a page's publish date, in priority order.
+ * Collections, navigation, ISG aging and RSS all use this order.
+ */
+export const PUBLISHED_DATE_FIELDS = ['publishedAt', 'published', 'date', 'createdAt'];
+/**
+ * Returns the publish date from front matter, or `undefined` if none is usable.
+ *
+ * Checks {@link PUBLISHED_DATE_FIELDS} in order and returns the first valid value.
+ * Accepts strings (quoted YAML dates) and `Date` objects (unquoted YAML dates,
+ * which gray-matter parses into `Date`). Missing, `null` and empty values are skipped;
+ * other invalid values are reported through `onInvalid` and skipped, so a bad
+ * `publishedAt` does not hide a valid `date`.
+ *
+ * @param frontMatter - Parsed front matter of a page; `null`/`undefined` returns `undefined`
+ * @param onInvalid - Called for each present field whose value is not a valid date
+ * @returns A new `Date` instance, or `undefined`
+ *
+ * @example
+ * ```typescript
+ * getFrontMatterDate({ date: new Date('2026-01-01') }); // 2026-01-01T00:00:00.000Z
+ * getFrontMatterDate({ publishedAt: 'soon', date: '2026-06-01' }); // 2026-06-01T00:00:00.000Z
+ * getFrontMatterDate({ title: 'Undated' }); // undefined
+ * ```
+ */
+export function getFrontMatterDate(frontMatter, onInvalid) {
+    if (!frontMatter) {
+        return undefined;
+    }
+    for (const field of PUBLISHED_DATE_FIELDS) {
+        const value = frontMatter[field];
+        if (value === undefined || value === null || (typeof value === 'string' && !value.trim())) {
+            continue;
+        }
+        let date;
+        if (typeof value === 'string') {
+            date = new Date(value);
+        }
+        else if (value instanceof Date) {
+            date = new Date(value.getTime());
+        }
+        if (date && !isNaN(date.getTime())) {
+            return date;
+        }
+        onInvalid?.(field, value);
+    }
+    return undefined;
+}

package/dist/core/utils/error-overlay.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-overlay.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/error-overlay.utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IACF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAwbnF;AA0DD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,QAAQ,CAAC,EAAE,MAAM,GAChB,YAAY,CAkCd"}
+{"version":3,"file":"error-overlay.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/error-overlay.utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IACF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AA0sBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAiJnF;AAsFD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,QAAQ,CAAC,EAAE,MAAM,GAChB,YAAY,CAkCd"}