@getrefino/core 0.1.0-rc.5 → 0.1.0

package/dist/documents/config.js

@@ -0,0 +1,152 @@
+import { isDocumentId } from "../document.js";
+import { ContentError } from "../errors.js";
+export const SUPPORTED_EXTENSIONS = [".md", ".mdx"];
+export const MAX_CONTENT_SOURCES = 16;
+export const EMPTY_CONTENT_CONFIG = { sources: [] };
+const SOURCE_ID = /^[A-Za-z0-9_-]+$/;
+const PATH_SEGMENT = /^[A-Za-z0-9_-]+$/;
+function configError(message) {
+    return new ContentError("NOT_CONFIGURED", `refino.config.json: ${message}`);
+}
+function validateDir(value, sourceId) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw configError(`content source "${sourceId}" needs a "dir".`);
+    }
+    const dir = value.trim().replace(/\/+$/, "");
+    if (dir.startsWith("/") || dir.includes("\\") || dir.includes("\0")) {
+        throw configError(`content source "${sourceId}" has a "dir" that is not repository-relative.`);
+    }
+    const segments = dir.split("/");
+    if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw configError(`content source "${sourceId}" has a "dir" with invalid segments.`);
+    }
+    return dir;
+}
+function validateExtensions(value, sourceId) {
+    if (value === undefined)
+        return SUPPORTED_EXTENSIONS;
+    if (!Array.isArray(value) || value.length === 0) {
+        throw configError(`content source "${sourceId}" has an empty "extensions".`);
+    }
+    const extensions = [];
+    for (const entry of value) {
+        if (typeof entry !== "string" || !SUPPORTED_EXTENSIONS.includes(entry)) {
+            throw configError(`content source "${sourceId}" lists extension ${JSON.stringify(entry)}; Refino edits ${SUPPORTED_EXTENSIONS.join(" and ")}.`);
+        }
+        if (!extensions.includes(entry))
+            extensions.push(entry);
+    }
+    return extensions;
+}
+function validateFields(value, sourceId) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw configError(`content source "${sourceId}" has a "fields" that is not an object.`);
+    }
+    const fields = {};
+    for (const [field, key] of Object.entries(value)) {
+        if (typeof key !== "string" || key.length === 0) {
+            throw configError(`content source "${sourceId}" maps "${field}" to something that is not a frontmatter key.`);
+        }
+        fields[field] = key;
+    }
+    return fields;
+}
+/** Read and validate the `content` block. An absent block means no articles, not an error. */
+export function parseContentConfig(value) {
+    if (value === undefined || value === null)
+        return EMPTY_CONTENT_CONFIG;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw configError('"content" must be an object with a "sources" array.');
+    }
+    const rawSources = value.sources;
+    if (rawSources === undefined)
+        return EMPTY_CONTENT_CONFIG;
+    if (!Array.isArray(rawSources))
+        throw configError('"content.sources" must be an array.');
+    if (rawSources.length > MAX_CONTENT_SOURCES) {
+        throw configError(`"content.sources" lists more than ${MAX_CONTENT_SOURCES} sources.`);
+    }
+    const sources = [];
+    for (const raw of rawSources) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            throw configError('every entry in "content.sources" must be an object.');
+        }
+        const entry = raw;
+        const id = entry.id;
+        if (typeof id !== "string" || !SOURCE_ID.test(id)) {
+            throw configError(`content source id ${JSON.stringify(id)} must be letters, digits, "-" or "_".`);
+        }
+        if (sources.some((source) => source.id === id)) {
+            throw configError(`content source "${id}" is declared twice.`);
+        }
+        sources.push({
+            id,
+            dir: validateDir(entry.dir, id),
+            extensions: validateExtensions(entry.extensions, id),
+            fields: validateFields(entry.fields, id),
+        });
+    }
+    return { sources };
+}
+/**
+ * Move a configuration's directories from being relative to the config file
+ * to being relative to the repository root.
+ *
+ * Sites declare `dir` next to their own `refino.config.json`, which in a
+ * monorepo is not the repository root. The server reads the file from the
+ * repository, so it has to say where it found it.
+ */
+export function rebaseContentConfig(config, baseDir) {
+    const base = baseDir.replace(/^\/+|\/+$/g, "");
+    if (base === "")
+        return config;
+    return { sources: config.sources.map((source) => ({ ...source, dir: `${base}/${source.dir}` })) };
+}
+export function sourceTypeForPath(path) {
+    return path.endsWith(".mdx") ? "mdx" : "markdown";
+}
+/**
+ * Every path a document id could resolve to, in the source's extension
+ * order. Returns an empty list when no configured source claims the id.
+ */
+export function documentCandidates(config, documentId) {
+    if (!isDocumentId(documentId))
+        return [];
+    const [sourceId, ...segments] = documentId.split(".");
+    const source = config.sources.find((candidate) => candidate.id === sourceId);
+    if (!source || segments.length === 0)
+        return [];
+    if (!segments.every((segment) => PATH_SEGMENT.test(segment)))
+        return [];
+    const stem = `${source.dir}/${segments.join("/")}`;
+    return source.extensions.map((extension) => ({
+        documentId,
+        source,
+        path: `${stem}${extension}`,
+        sourceType: sourceTypeForPath(`${stem}${extension}`),
+    }));
+}
+/**
+ * The document id for a repository-relative source path, or null when no
+ * configured source claims it. This is how an integration turns the file it
+ * just rendered into the id it passes to the editor.
+ */
+export function documentIdForPath(config, path) {
+    const normalized = path.replace(/^\.\//, "").replace(/\\/g, "/");
+    for (const source of config.sources) {
+        const prefix = `${source.dir}/`;
+        if (!normalized.startsWith(prefix))
+            continue;
+        const extension = source.extensions.find((candidate) => normalized.endsWith(candidate));
+        if (!extension)
+            continue;
+        const slug = normalized.slice(prefix.length, normalized.length - extension.length);
+        const segments = slug.split("/");
+        if (segments.length === 0 || !segments.every((segment) => PATH_SEGMENT.test(segment)))
+            continue;
+        return `${source.id}.${segments.join(".")}`;
+    }
+    return null;
+}

package/dist/documents/fields.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Which frontmatter keys Refino offers as article metadata.
+ *
+ * The canonical names are Refino's; the aliases are what sites actually
+ * write. Matching is pragmatic and deliberately conservative: an alias is
+ * only accepted when it can mean one thing, and when two keys in the same
+ * article would map to the same field, neither is matched and the site is
+ * told to say which it meant. Keys Refino does not recognize are left
+ * completely alone — they are still in the file, Refino simply does not
+ * offer them.
+ */
+/** The metadata fields Content Editing V1 knows about. Order is the order the editor shows them in. */
+export declare const METADATA_FIELDS: readonly ["title", "subtitle", "excerpt", "description", "seoTitle", "seoDescription", "author", "date", "ctaLabel", "ctaText"];
+export type MetadataFieldName = (typeof METADATA_FIELDS)[number];
+/** Human labels for the metadata panel. */
+export declare const METADATA_LABELS: Readonly<Record<MetadataFieldName, string>>;
+/**
+ * Frontmatter keys that mean each field. Compared after lowercasing and
+ * dropping `-` and `_`, so `seo_title`, `seoTitle` and `SEO-Title` are one
+ * alias.
+ */
+export declare const METADATA_ALIASES: Readonly<Record<MetadataFieldName, readonly string[]>>;
+export declare function normalizeKey(key: string): string;
+export interface MetadataMatch {
+    readonly field: MetadataFieldName;
+    /** The frontmatter key this field reads and writes. */
+    readonly key: string;
+}
+export interface MetadataMatchResult {
+    readonly matches: readonly MetadataMatch[];
+    /** Fields skipped because more than one key in the article could have been them. */
+    readonly ambiguous: readonly {
+        readonly field: MetadataFieldName;
+        readonly keys: readonly string[];
+    }[];
+}
+/**
+ * Match an article's frontmatter keys to metadata fields.
+ *
+ * `overrides` is the source's `fields` configuration: a canonical field name
+ * mapped to the exact key to use. An override is authoritative — it settles
+ * ambiguity and can name a key that is not an alias of anything.
+ */
+export declare function matchMetadataFields(keys: readonly string[], overrides?: Readonly<Record<string, string>>): MetadataMatchResult;

package/dist/documents/fields.js

@@ -0,0 +1,105 @@
+/**
+ * Which frontmatter keys Refino offers as article metadata.
+ *
+ * The canonical names are Refino's; the aliases are what sites actually
+ * write. Matching is pragmatic and deliberately conservative: an alias is
+ * only accepted when it can mean one thing, and when two keys in the same
+ * article would map to the same field, neither is matched and the site is
+ * told to say which it meant. Keys Refino does not recognize are left
+ * completely alone — they are still in the file, Refino simply does not
+ * offer them.
+ */
+/** The metadata fields Content Editing V1 knows about. Order is the order the editor shows them in. */
+export const METADATA_FIELDS = [
+    "title",
+    "subtitle",
+    "excerpt",
+    "description",
+    "seoTitle",
+    "seoDescription",
+    "author",
+    "date",
+    "ctaLabel",
+    "ctaText",
+];
+/** Human labels for the metadata panel. */
+export const METADATA_LABELS = {
+    title: "Title",
+    subtitle: "Subtitle",
+    excerpt: "Excerpt",
+    description: "Description",
+    seoTitle: "SEO title",
+    seoDescription: "SEO description",
+    author: "Author",
+    date: "Date",
+    ctaLabel: "CTA label",
+    ctaText: "CTA text",
+};
+/**
+ * Frontmatter keys that mean each field. Compared after lowercasing and
+ * dropping `-` and `_`, so `seo_title`, `seoTitle` and `SEO-Title` are one
+ * alias.
+ */
+export const METADATA_ALIASES = {
+    title: ["title", "heading", "headline"],
+    subtitle: ["subtitle", "subhead", "subheading", "tagline", "standfirst"],
+    excerpt: ["excerpt", "summary", "abstract", "blurb", "lede", "lead"],
+    description: ["description", "desc"],
+    seoTitle: ["seotitle", "metatitle", "ogtitle"],
+    seoDescription: ["seodescription", "metadescription", "ogdescription"],
+    author: ["author", "byline", "writtenby"],
+    date: ["date", "publishedat", "publishdate", "pubdate", "published", "publisheddate"],
+    ctaLabel: ["ctalabel", "ctabutton", "calltoactionlabel"],
+    ctaText: ["ctatext", "cta", "calltoaction"],
+};
+export function normalizeKey(key) {
+    return key.toLowerCase().replace(/[-_\s]/g, "");
+}
+const BY_ALIAS = (() => {
+    const map = new Map();
+    for (const field of METADATA_FIELDS) {
+        for (const alias of METADATA_ALIASES[field])
+            map.set(normalizeKey(alias), field);
+    }
+    return map;
+})();
+/**
+ * Match an article's frontmatter keys to metadata fields.
+ *
+ * `overrides` is the source's `fields` configuration: a canonical field name
+ * mapped to the exact key to use. An override is authoritative — it settles
+ * ambiguity and can name a key that is not an alias of anything.
+ */
+export function matchMetadataFields(keys, overrides = {}) {
+    const present = new Set(keys);
+    const claimed = new Map();
+    for (const key of keys) {
+        const field = BY_ALIAS.get(normalizeKey(key));
+        if (!field)
+            continue;
+        const existing = claimed.get(field);
+        if (existing)
+            existing.push(key);
+        else
+            claimed.set(field, [key]);
+    }
+    const matches = [];
+    const ambiguous = [];
+    for (const field of METADATA_FIELDS) {
+        const override = overrides[field];
+        if (override !== undefined) {
+            if (present.has(override))
+                matches.push({ field, key: override });
+            continue;
+        }
+        const candidates = claimed.get(field);
+        if (!candidates || candidates.length === 0)
+            continue;
+        if (candidates.length > 1) {
+            ambiguous.push({ field, keys: candidates });
+            continue;
+        }
+        matches.push({ field, key: candidates[0] });
+    }
+    return { matches, ambiguous };
+}

package/dist/documents/file-store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The path-generic persistence seam.
+ *
+ * `ContentAdapter` is bound to one file — the copy file — at construction,
+ * which is exactly right for copy and no use at all for articles, of which
+ * there are many. A store reads and writes any allow-listed path in the same
+ * repository, with the same conflict rule: a write on a revision that has
+ * moved is refused, never merged.
+ *
+ * Two implementations ship: `createLocalFileStore` in
+ * `@getrefino/core/local-file` (development) and `createGitHubFileStore` in
+ * `@getrefino/github` (production). `createGitHubContentAdapter` is built on
+ * the same store, so copy and articles commit through one code path.
+ */
+import type { CommitInfo } from "../adapter.js";
+export interface SourceFile {
+    /** The file exactly as stored. */
+    readonly text: string;
+    /** Opaque revision of these bytes: a git blob SHA, or a hash of the file. */
+    readonly revision: string;
+}
+export interface SourceFileWrite {
+    readonly path: string;
+    readonly text: string;
+    /** The revision the new text was derived from. A store must refuse a stale one. */
+    readonly baseRevision: string;
+    /** Commit message, for stores that make commits. */
+    readonly message: string;
+}
+export interface SourceFileWriteResult {
+    readonly revision: string;
+    readonly commit?: CommitInfo;
+}
+export interface SourceFileStore {
+    /** Human-readable name for logs, e.g. "github" or "local-file". */
+    readonly name: string;
+    /** Read a repository-relative path. Returns null when it does not exist. */
+    readFile(path: string): Promise<SourceFile | null>;
+    /**
+     * Write a repository-relative path.
+     * Must throw `ContentError` with code `CONFLICT` when the stored revision
+     * is not `baseRevision`.
+     */
+    writeFile(write: SourceFileWrite): Promise<SourceFileWriteResult>;
+}

package/dist/documents/file-store.js

@@ -0,0 +1 @@
+export {};

package/dist/documents/frontmatter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A span parser for YAML frontmatter.
+ *
+ * It does not build a document tree and it cannot serialize one. For each
+ * top-level entry it records where the key is, where its value is, and how
+ * that value is written. Reading a field is a slice; writing one replaces a
+ * single span and leaves every other byte of the file alone.
+ *
+ * That is the whole reason it exists: key order, unknown keys, comments,
+ * indentation, blank lines and quoting style are preserved because they are
+ * never in the code path. Anything this parser cannot represent honestly is
+ * reported as not editable rather than guessed at.
+ *
+ * The YAML subset understood here is the one blog frontmatter actually uses:
+ * top-level scalar entries in plain, single-quoted, double-quoted, literal
+ * (`|`) or folded (`>`) form.
+ */
+export type ScalarStyle = "plain" | "empty" | "single" | "double" | "literal" | "folded";
+export interface FrontmatterEntry {
+    readonly key: string;
+    /** Offset of the first character of the entry's key line. */
+    readonly entryStart: number;
+    /** Offset just past the entry's last line, including its line terminator. */
+    readonly entryEnd: number;
+    /** The span a write replaces. */
+    readonly valueStart: number;
+    readonly valueEnd: number;
+    readonly style: ScalarStyle | "unsupported";
+    /** The decoded value, or null when the style is unsupported. */
+    readonly value: string | null;
+    /** Why this entry cannot be edited, when it cannot. */
+    readonly reason: string | null;
+    /** Literal and folded entries only: the header token and the content indent. */
+    readonly block: {
+        readonly header: string;
+        readonly indent: string;
+    } | null;
+}
+export interface FrontmatterBlock {
+    /** Offset of the opening fence. */
+    readonly start: number;
+    /** Offset just past the closing fence's line terminator. */
+    readonly end: number;
+    readonly entries: readonly FrontmatterEntry[];
+}
+interface Line {
+    readonly start: number;
+    /** End of the text, before the line terminator. */
+    readonly contentEnd: number;
+    /** End including the line terminator. */
+    readonly end: number;
+    readonly text: string;
+}
+export declare function splitLines(text: string): Line[];
+export declare function encodeDouble(value: string): string;
+export declare function encodeSingle(value: string): string;
+/** Whether a value can be written as a plain scalar without changing what it means. */
+export declare function isPlainSafe(value: string): boolean;
+/**
+ * Find and parse the leading frontmatter block. Returns null when the file
+ * does not open with one, which is not an error: a Markdown file without
+ * frontmatter simply has no metadata fields.
+ */
+export declare function parseFrontmatter(text: string): FrontmatterBlock | null;
+/** The replacement text for one entry's value span. Throws when the style cannot carry the value. */
+export declare function renderScalar(text: string, entry: FrontmatterEntry, value: string): string;
+export {};