@johnhenry/sitefile 0.0.0-stage → 0.0.0

package/lib/src/pages.js

@@ -0,0 +1,54 @@
+// What a `RENDER … FOR x IN list [BY key] [PAGE n [FIRST <dest>]]` loop renders (docs/LANGUAGE.md, "Tag pages,
+// pagination and drafts"):
+//
+// - BY key: one element per distinct value of `key` (a list field gives one per element), `{ key, count, items }`,
+//   keys in SORT BY order (numeric strings numerically, otherwise UTF-16 order); items keep the list's order.
+// - PAGE n: the list (or each group) cut into pages of n items: `{ [key,] count, items, number, total }`; the
+//   executor adds `url`, `prev` and `next` once it knows each page's destination. An empty list (without BY) is
+//   one page with no items, so an index always exists.
+import { SitefileError } from './errors.js';
+import { compareValues } from './resources/documents.js';
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/** Group documents by a field; `what` prefixes messages (`FOR tag IN posts BY tags`). */
+export function groupBy(items, key, what, span) {
+    const groups = new Map();
+    items.forEach((item, i) => {
+        if (!isObject(item))
+            throw new SitefileError('E_TYPE', `${what}: element ${i + 1} is not a document (an object with a '${key}' field)`, span);
+        const v = item[key];
+        const name = typeof item['path'] === 'string' ? item['path'] : `#${i + 1}`;
+        const seen = new Set();
+        for (const x of Array.isArray(v) ? v : [v]) {
+            if (x === undefined || x === null || x === '')
+                continue;
+            if (typeof x !== 'string' && typeof x !== 'number' && typeof x !== 'boolean') {
+                throw new SitefileError('E_TYPE', `${what}: '${key}' of document '${name}' is not text or a list of text`, span);
+            }
+            const k = String(x);
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            const g = groups.get(k);
+            if (g)
+                g.push(item);
+            else
+                groups.set(k, [item]);
+        }
+    });
+    const keys = [...groups.keys()].sort((a, b) => compareValues(a, b));
+    return keys.map((k) => ({ key: k, count: groups.get(k).length, items: groups.get(k) }));
+}
+/** Cut each group (or the whole list, as one group without a key) into pages of `size` items. */
+export function paginate(groups, size) {
+    return groups.map((g) => {
+        const total = Math.max(1, Math.ceil(g.items.length / size));
+        return Array.from({ length: total }, (_, i) => ({
+            ...(g.key !== undefined ? { key: g.key } : {}),
+            count: g.items.length,
+            items: g.items.slice(i * size, (i + 1) * size),
+            number: i + 1,
+            total,
+        }));
+    });
+}
+//# sourceMappingURL=pages.js.map

package/lib/src/paths.d.ts

@@ -0,0 +1,39 @@
+import { type SourceSpan } from './errors.js';
+/**
+ * Unicode NFC. Every virtual path (Sitefile operands, names read from the
+ * context, archive entries, plugin outputs) is stored in NFC, so NFC and NFD
+ * spellings of a name are the same path on every OS.
+ */
+export declare function nfc(s: string): string;
+/**
+ * Unicode simple case folding (CaseFolding.txt status C and S, one code
+ * point to one code point; no full or Turkic mappings), applied code point
+ * by code point. Two paths with the same fold differ only in case.
+ * `rust/src/paths.rs` uses the same generated table.
+ */
+export declare function foldCase(s: string): string;
+export interface VirtualPath {
+    /** Normalized absolute POSIX path inside the artifact, `/` for the root. */
+    readonly path: string;
+    /** The original ended with `/` (or was the root). */
+    readonly trailingSlash: boolean;
+}
+/**
+ * Normalize an artifact (virtual) path. Must be absolute; `.` and repeated
+ * slashes collapse; any `..` segment is rejected outright; the result is NFC.
+ */
+export declare function normalizeVirtual(raw: string, span?: SourceSpan, what?: string): VirtualPath;
+/**
+ * Normalize a host path relative to the build context. Returns a relative
+ * POSIX path (`''` for the context root). Rejects absolute paths and anything
+ * that escapes the context with `..`. The result is NFC; LocalContext finds
+ * the file whatever normalization its on-disk name uses.
+ */
+export declare function normalizeLocal(raw: string, span?: SourceSpan): {
+    path: string;
+    trailingSlash: boolean;
+};
+export declare function joinVirtual(dir: string, name: string): string;
+export declare function basenameVirtual(p: string): string;
+/** Ancestors of a virtual path, excluding the root and the path itself. */
+export declare function ancestorsVirtual(p: string): string[];

package/lib/src/paths.js

@@ -0,0 +1,101 @@
+import { posix } from 'node:path';
+import { SitefileError } from './errors.js';
+import { CASEFOLD_RUNS } from './casefold-data.js';
+const ASCII = /^[\x00-\x7f]*$/;
+/**
+ * Unicode NFC. Every virtual path (Sitefile operands, names read from the
+ * context, archive entries, plugin outputs) is stored in NFC, so NFC and NFD
+ * spellings of a name are the same path on every OS.
+ */
+export function nfc(s) {
+    return ASCII.test(s) ? s : s.normalize('NFC');
+}
+function foldCodePoint(c) {
+    let lo = 0;
+    let hi = CASEFOLD_RUNS.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const [start, end, delta, step] = CASEFOLD_RUNS[mid];
+        if (c < start)
+            hi = mid - 1;
+        else if (c > end)
+            lo = mid + 1;
+        else
+            return (c - start) % step === 0 ? c + delta : c;
+    }
+    return c;
+}
+/**
+ * Unicode simple case folding (CaseFolding.txt status C and S, one code
+ * point to one code point; no full or Turkic mappings), applied code point
+ * by code point. Two paths with the same fold differ only in case.
+ * `rust/src/paths.rs` uses the same generated table.
+ */
+export function foldCase(s) {
+    if (ASCII.test(s))
+        return s.toLowerCase();
+    let out = '';
+    for (const ch of s)
+        out += String.fromCodePoint(foldCodePoint(ch.codePointAt(0)));
+    return out;
+}
+/**
+ * Normalize an artifact (virtual) path. Must be absolute; `.` and repeated
+ * slashes collapse; any `..` segment is rejected outright; the result is NFC.
+ */
+export function normalizeVirtual(raw, span, what = 'path') {
+    raw = nfc(raw);
+    if (raw.includes('\0'))
+        throw new SitefileError('E_PATH', `${what} contains a NUL byte`, span);
+    if (!raw.startsWith('/')) {
+        throw new SitefileError('E_PATH', `${what} '${raw}' must be an absolute artifact path (start with '/')`, span);
+    }
+    const segments = [];
+    for (const seg of raw.split('/')) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..')
+            throw new SitefileError('E_PATH', `${what} '${raw}' must not contain '..'`, span);
+        segments.push(seg);
+    }
+    const path = '/' + segments.join('/');
+    return { path, trailingSlash: raw.endsWith('/') || path === '/' };
+}
+/**
+ * Normalize a host path relative to the build context. Returns a relative
+ * POSIX path (`''` for the context root). Rejects absolute paths and anything
+ * that escapes the context with `..`. The result is NFC; LocalContext finds
+ * the file whatever normalization its on-disk name uses.
+ */
+export function normalizeLocal(raw, span) {
+    raw = nfc(raw);
+    if (raw.includes('\0'))
+        throw new SitefileError('E_PATH', 'path contains a NUL byte', span);
+    if (raw.startsWith('/') || /^[A-Za-z]:[\\/]/.test(raw) || raw.startsWith('\\')) {
+        throw new SitefileError('E_PATH_ESCAPE', `local path '${raw}' must be relative to the build context`, span);
+    }
+    const norm = posix.normalize(raw === '' ? '.' : raw);
+    if (norm === '..' || norm.startsWith('../')) {
+        throw new SitefileError('E_PATH_ESCAPE', `local path '${raw}' escapes the build context`, span);
+    }
+    const path = norm === '.' || norm === './' ? '' : norm.replace(/\/+$/, '');
+    return { path, trailingSlash: raw.endsWith('/') };
+}
+export function joinVirtual(dir, name) {
+    name = nfc(name);
+    return dir === '/' ? `/${name}` : `${dir}/${name}`;
+}
+export function basenameVirtual(p) {
+    return posix.basename(p);
+}
+/** Ancestors of a virtual path, excluding the root and the path itself. */
+export function ancestorsVirtual(p) {
+    const out = [];
+    let i = p.indexOf('/', 1);
+    while (i !== -1) {
+        out.push(p.slice(0, i));
+        i = p.indexOf('/', i + 1);
+    }
+    return out;
+}
+//# sourceMappingURL=paths.js.map

package/lib/src/planner.d.ts

@@ -0,0 +1,297 @@
+import { type SourceSpan } from './errors.js';
+import { type EscapeMode, type RedirectStatus, type ExportFormat, type ImportKind, type OciCompression, type Operand, type Program } from './language/ast.js';
+import { type Scalar } from './values.js';
+import { type GitLocation } from './resources/git.js';
+import type { TemplateNode } from './render.js';
+/** An html LET: its template, parsed, evaluated where a RENDER uses it. */
+export interface FragmentSpec {
+    readonly name: string;
+    /** The template as written (memo keys). */
+    readonly text: string;
+    readonly nodes: readonly TemplateNode[];
+    readonly span: SourceSpan;
+}
+/** Where a COPY/RENDER reads from. */
+export type SourceRef = 
+/** Content written in the Sitefile itself (heredoc); `bodyLine` is its first Sitefile line. */
+{
+    readonly kind: 'inline';
+    readonly text: string;
+    readonly delimiter: string;
+    readonly bodyLine: number;
+    readonly span: SourceSpan;
+}
+/** `path` is a normalized virtual path inside an earlier stage's final tree (`--from=name`). */
+ | {
+    readonly kind: 'stage';
+    readonly name: string;
+    readonly path: string;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'local';
+    readonly path: string;
+    readonly span: SourceSpan;
+}
+/** `path` is a normalized virtual path inside the import, `/` for the whole import. */
+ | {
+    readonly kind: 'import';
+    readonly name: string;
+    readonly path: string;
+    readonly span: SourceSpan;
+};
+export interface ImportSpec {
+    readonly name: string;
+    /** Interpolated URI as written. */
+    readonly uri: string;
+    readonly location: {
+        readonly kind: 'local';
+        readonly path: string;
+    } | {
+        readonly kind: 'remote';
+        readonly url: string;
+    } | ({
+        readonly kind: 'git';
+    } & GitLocation);
+    readonly as?: ImportKind;
+    readonly integrity?: string;
+    readonly sort?: {
+        readonly key: string;
+        readonly descending: boolean;
+    };
+    /** `SCHEMA <path>`: `uri` as written (for messages), `path` context-relative. */
+    readonly schema?: {
+        readonly uri: string;
+        readonly path: string;
+        readonly span: SourceSpan;
+    };
+    /** `DRAFTS true|false`: false leaves out the elements whose `draft` is true. */
+    readonly drafts?: boolean;
+    /** Build secrets sent as request headers (ids and header names only; values come from --secret). */
+    readonly secrets?: readonly {
+        readonly id: string;
+        readonly header: string;
+        readonly bearer: boolean;
+    }[];
+    /** `AS sitefile`: the `ARG NAME=value` clauses, evaluated (build args of the imported Sitefile). */
+    readonly args?: readonly {
+        readonly name: string;
+        readonly value: string;
+        readonly span: SourceSpan;
+    }[];
+    readonly span: SourceSpan;
+}
+/** A declared renderer plugin: a local `.mjs` file in its own folder, or a `.wasm` module. */
+export interface PluginSpec {
+    readonly name: string;
+    /** Context-relative path of the module. */
+    readonly path: string;
+    readonly integrity?: string;
+    readonly span: SourceSpan;
+}
+/** A declared external program; it runs only when the CLI allows it (`--allow-exec`). */
+export interface ToolSpec {
+    readonly name: string;
+    readonly span: SourceSpan;
+}
+/** A REDIRECT, evaluated; written to `/_redirects` at EXPORT. */
+export interface RedirectSpec {
+    readonly from: string;
+    readonly to: string;
+    readonly status: RedirectStatus;
+    readonly overwrite: boolean;
+    readonly span: SourceSpan;
+}
+/** A HEADER, evaluated; written to `/_headers` at EXPORT. */
+export interface HeaderSpec {
+    readonly pattern: string;
+    readonly name: string;
+    readonly value: string;
+    readonly overwrite: boolean;
+    readonly span: SourceSpan;
+}
+export type Operation = {
+    /** Report the references in the tree's HTML and CSS files that point at nothing. */
+    readonly kind: 'CHECKLINKS';
+    readonly warn: boolean;
+    readonly external: boolean;
+    /** The EXPORT path: absolute references resolve below it. */
+    readonly root: string;
+    /** Every REDIRECT source in the Sitefile: links to them are not broken. */
+    readonly redirects: readonly string[];
+    readonly span: SourceSpan;
+} | {
+    /** Rename the files matching `patterns` to `name.<hash>.ext` and rewrite the HTML and CSS that reference them. */
+    readonly kind: 'FINGERPRINT';
+    /** Checked absolute patterns, NFC; a trailing `/` became `/**`. */
+    readonly patterns: readonly string[];
+    /** `MANIFEST <dest>`: the JSON map of old to new paths. */
+    readonly manifest?: string;
+    /** The EXPORT path: absolute references (`/img/a.png`) in HTML and CSS name files below it. */
+    readonly root: string;
+    readonly overwrite: boolean;
+    readonly span: SourceSpan;
+} | {
+    /** sitemaps.org XML of the `.html` files in the tree at this point. */
+    readonly kind: 'SITEMAP';
+    /** Checked base URL without trailing slashes. */
+    readonly base: string;
+    readonly dest: string;
+    readonly overwrite: boolean;
+    readonly span: SourceSpan;
+} | {
+    /** An Atom feed of a list import; `link` is interpolated per element (`${item…}`). */
+    readonly kind: 'FEED';
+    readonly list: string;
+    readonly base: string;
+    readonly link: Operand;
+    readonly dest: string;
+    readonly title: string;
+    readonly overwrite: boolean;
+    readonly span: SourceSpan;
+} | {
+    /** Run a plugin; `dest` and option values are interpolated per FOR element at execution. */
+    readonly kind: 'TRANSFORM';
+    readonly source?: SourceRef;
+    readonly plugin: string;
+    readonly dest: Operand;
+    readonly options: ReadonlyArray<{
+        readonly key: string;
+        readonly value: Operand;
+    }>;
+    readonly each?: {
+        readonly as: string;
+        readonly list: string;
+    };
+    /** argv template when `plugin` names a TOOL. */
+    readonly args?: readonly Operand[];
+    /** A directory source's files to keep / leave out (`.sitefileignore` patterns, relative to it). */
+    readonly include?: readonly string[];
+    readonly exclude?: readonly string[];
+    readonly overwrite: boolean;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'COPY';
+    readonly source: SourceRef;
+    readonly dest: string;
+    readonly destIsDir: boolean;
+    readonly overwrite: boolean;
+    /** `--exclude` patterns (`.sitefileignore` syntax, relative to the source directory). */
+    readonly exclude?: readonly string[];
+    /** `--chmod`: 0o644 or 0o755 for every copied file. */
+    readonly chmod?: number;
+    /** `--parents`: the source's path is kept under `dest`. */
+    readonly parents?: true;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'RENDER';
+    readonly template: SourceRef;
+    /** Normalized destination; '' when `each` is set (computed per element). */
+    readonly dest: string;
+    /**
+     * `FOR as IN list [BY key] [PAGE size [FIRST <dest>]]`: render once per element (or group, or page); `dest`
+     * (and `first`, for the first page) is interpolated per element.
+     */
+    readonly each?: {
+        readonly as: string;
+        readonly list: string;
+        readonly dest: Operand;
+        readonly by?: string;
+        readonly page?: {
+            readonly size: number;
+            readonly first?: Operand;
+        };
+    };
+    readonly escape: EscapeMode;
+    readonly overwrite: boolean;
+    /** `--inline-svg`: `${file … | svg}` may paste SVG markup. */
+    readonly inlineSvg?: true;
+    readonly span: SourceSpan;
+};
+/** What a stage's tree starts as. */
+export type StageBase = {
+    readonly kind: 'scratch';
+}
+/** `path` is context-relative (`''` for the context root). */
+ | {
+    readonly kind: 'local';
+    readonly path: string;
+}
+/** A copy of an earlier stage's final tree. */
+ | {
+    readonly kind: 'stage';
+    readonly name: string;
+}
+/** `FROM image <ref> [AT <dir>]`: the files of an OCI site image. */
+ | ImageStageBase;
+export interface ImageStageBase {
+    readonly kind: 'image';
+    /** The evaluated reference, as written (validated). */
+    readonly ref: string;
+    /** No registry host: an image in the local store, never fetched. */
+    readonly local: boolean;
+    /** `AT`: normalized absolute directory inside the image (default: the image's root label). */
+    readonly at?: string;
+    /** `FROM` or `STAGE <name> FROM`, for messages. */
+    readonly lead: string;
+    readonly span: SourceSpan;
+}
+/** One FROM and the operations that follow it. */
+export interface Stage {
+    readonly name?: string;
+    readonly base: StageBase;
+    readonly operations: Operation[];
+    readonly span: SourceSpan;
+}
+/** A fully evaluated build: no variables left, no IO done yet. */
+export interface Plan {
+    readonly file: string;
+    /** In source order; EXPORT reads the last one. */
+    readonly stages: readonly Stage[];
+    readonly vars: ReadonlyMap<string, Scalar>;
+    /** html LETs by name, in source order (not in `vars`: they are not evaluated here). */
+    readonly fragments: ReadonlyMap<string, FragmentSpec>;
+    readonly imports: readonly ImportSpec[];
+    readonly plugins: readonly PluginSpec[];
+    readonly tools: readonly ToolSpec[];
+    readonly exportPath: string;
+    readonly exportFormat: ExportFormat;
+    /** Evaluated `BASE` clause of EXPORT, if any (raw string; validated when the export is written). */
+    readonly exportBase: string | undefined;
+    /** Evaluated `AT` clause of EXPORT ... AS oci: the root directory inside the image layer. */
+    readonly exportRoot: string | undefined;
+    /** `COMPRESSION` clause of EXPORT ... AS oci (undefined: gzip). */
+    readonly exportCompression: OciCompression | undefined;
+    /** REDIRECT lines in source order (any stage); EXPORT writes them to `/_redirects`. */
+    readonly redirects: readonly RedirectSpec[];
+    /** HEADER lines in source order (any stage); EXPORT writes them to `/_headers`. */
+    readonly headers: readonly HeaderSpec[];
+    readonly warnings: readonly string[];
+    /**
+     * `--target <stage>`: the build stops after this stage and exports its whole tree (see {@link targetPlan}).
+     * Undefined for a normal build.
+     */
+    readonly target?: string;
+}
+/**
+ * Evaluate a program. `argSource` names where a build arg came from in messages (`--build-arg NAME` for the
+ * CLI's; an imported Sitefile's come from the `ARG` clauses of its IMPORT).
+ */
+export declare function plan(program: Program, buildArgs?: Readonly<Record<string, string>>, argSource?: (name: string) => string): Plan;
+/**
+ * `--target <name>`: keep the stages up to and including the named one, and export that stage's whole tree
+ * (`/`) instead of the EXPORT path. The EXPORT's format and its options (AS, BASE, AT, COMPRESSION) still apply;
+ * the `/_redirects` and `/_headers` files EXPORT writes are not (they belong to the EXPORT path). An unknown
+ * name is a usage error that lists the named stages.
+ */
+export declare function targetPlan(p: Plan, name: string): Plan;
+/** A reference to a stage of an imported Sitefile (`FROM theme+assets`, `COPY --from=theme+assets …`). */
+export interface ImportedStageRef {
+    /** `theme+assets` */
+    readonly name: string;
+    readonly import: string;
+    readonly stage: string;
+    /** The instruction that names it. */
+    readonly span: SourceSpan;
+}
+/** Every reference to a stage of an imported Sitefile, in source order (stage bases, then `--from` sources, per stage). */
+export declare function importedStageRefs(stages: readonly Stage[]): ImportedStageRef[];