@snolla/data 0.0.0-stage → 1.0.7

package/dist/templateDefs.js

@@ -0,0 +1,163 @@
+// schema-as-file — portable, file-based TEMPLATE DEFINITIONS (snolla-dev-workflow Фаза 0).
+//
+// A "template-def" (the legacy MoreThenCms ContentTools concept) is the definition of an
+// entity/page template: its field list + each field's type. In prod these live DB-only —
+// a row in a `*Template` model whose `Content` column holds a JSON STRING: an array of
+// field-defs `{ name, fieldTemplate, value, valueType, options, partTemplate, ... }`.
+// `@snolla/core`'s `fillViewModel` and `@snolla/content-schema-gen` both already consume
+// exactly that array (via `JSON.parse(template.content)`).
+//
+// schema-as-file makes the local template file CANONICAL (design §"Local template is
+// canonical"): the same field-def vocabulary, authored as a readable/diffable JSON file
+// in the repo, from which mocks/defaults/lint/intellisense/type-gen derive. We deliberately
+// REUSE the existing field-def shape (a derivative of the content-schema-gen parse) rather than
+// invent a new JSON-schema-like DSL — one parser feeds both render and codegen, zero
+// translation drift. Prior art: Strapi `schema.json`-in-repo (adopt the PATTERN — one
+// canonical schema file per template — but keep snolla's native `fieldTemplate` vocabulary,
+// which is already proven in prod, instead of Strapi's attribute vocabulary).
+//
+// This module is PURE (no Sequelize/config) and lives at the `@snolla/data` floor so both
+// the engine (`@snolla/core`) and the codegen tool (`@snolla/content-schema-gen`) can import
+// it without pulling the DB barrel. Import the subpath directly:
+//   import { parseTemplateDef, loadTemplateDefFile } from '@snolla/data/templateDefs.js';
+//
+// FILE SHAPE (readable — `fields` is a real array, not a JSON-string-in-JSON):
+//   {
+//     "kind": "pageTemplate",              // which template model this def is for
+//     "id": "…uuid…",                      // optional — maps to the DB row on sync; absent = greenfield
+//     "alias": "landing",                  // required — the discriminator used everywhere (template.alias)
+//     "name": "Landing Page",              // optional — defaults to alias
+//     "customDefaultLayout": "landing",    // optional — liquid layout name
+//     "layouts": { … },                    // optional — named-layouts blob (object or string)
+//     "fields": [                          // the field-defs — same vocabulary as DB Content JSON
+//       { "name": "headline", "fieldTemplate": "textEditorTemplate", "value": "Welcome" },
+//       { "name": "parts",   "fieldTemplate": "partEditorTemplate", "partTemplate": "hero" }
+//     ]
+//   }
+//
+// `parseTemplateDef` NORMALIZES this to the DB-loaded shape (a drop-in for a Sequelize
+// template instance): `{ id, kind, alias, name, description, customDefaultLayout, layouts,
+// content }` where `content` is `JSON.stringify(fields)` — so downstream `JSON.parse(content)`
+// yields the original `fields` verbatim (the round-trip invariant). `kind` is additive
+// routing metadata the DB row lacks (the table implies it); the DB scoping FK (siteId/ownerId)
+// is likewise absent — a file in the repo is scoped by its site/location, and render-time
+// site context is passed to fillViewModel separately.
+import { readFileSync } from 'fs';
+// Template model kinds (recon §1 — every `*Template` model in packages/data/sequelize/snolla).
+// A file-def declares which one it is so a loader/codegen routes it to the right model/group.
+export const TEMPLATE_KINDS = new Set([
+    'pageTemplate', 'pagePartTemplate',
+    'blogPostTemplate', 'blogPostPartTemplate',
+    'storeProductTemplate', 'storeProductPartTemplate', 'storeProductVariantTemplate', 'storePartTemplate',
+    'catalogProductTemplate', 'catalogProductPartTemplate',
+    'reviewTemplate',
+    'tableTemplate', 'tableRecordPartTemplate',
+]);
+// The field-type vocabulary — every `fieldTemplate` value the render engine handles.
+// GROUND TRUTH is the switch in `@snolla/core` viewModels/index.js `fillViewModel`
+// (recon §3); this set MUST stay in sync with it (the Ф2 linter should reconcile the two
+// mechanically). Validating file-defs against this set is the seed of "schema-as-file is
+// canonical → lint derives from it": an unknown/typo'd type is caught at load, not silently
+// rendered empty.
+export const FIELD_TEMPLATE_TYPES = new Set([
+    // string / text / html (pass-through)
+    'colorEditorTemplate', 'markItUpHtmlEditorTemplate', 'textAreaEditorTemplate',
+    'textEditorTemplate', 'telEditorTemplate', 'emailEditorTemplate', 'urlEditorTemplate',
+    'tinymceEditorTemplate',
+    // markup-rendered
+    'markItUpMarkdownEditorTemplate', 'markItUpTextileEditorTemplate',
+    // literals (value from template only)
+    'hiddenFieldTemplate', 'htmlLiteralTemplate', 'markdownLiteralTemplate', 'textileLiteralTemplate',
+    // structured
+    'jsonEditorTemplate',
+    // numeric
+    'numericEditorTemplate', 'integerEditorTemplate',
+    // date / time
+    'dateTimeEditorTemplate', 'dateEditorTemplate', 'timeEditorTemplate',
+    // boolean / selection
+    'checkboxEditorTemplate', 'selectListEditorTemplate', 'radioButtonsEditorTemplate', 'checkboxesEditorTemplate',
+    // media (gallery-backed)
+    'galleryEditorTemplate', 'imageEditorTemplate',
+    // composition / relational
+    'partEditorTemplate', 'linkedItemEditorTemplate',
+    // no-op / TODO (accepted by the engine as inert)
+    'feedSelectListEditorTemplate', 'fileUploadTemplate',
+]);
+function validateFields(fields, ctx) {
+    if (!Array.isArray(fields)) {
+        throw new Error(`template-def ${ctx}: "fields" must be an array`);
+    }
+    fields.forEach((f, i) => {
+        if (!f || typeof f !== 'object' || Array.isArray(f)) {
+            throw new Error(`template-def ${ctx}: field[${i}] must be an object`);
+        }
+        if (!f.name || typeof f.name !== 'string') {
+            throw new Error(`template-def ${ctx}: field[${i}] is missing a string "name"`);
+        }
+        if (!f.fieldTemplate || !FIELD_TEMPLATE_TYPES.has(f.fieldTemplate)) {
+            throw new Error(`template-def ${ctx}: field "${f.name}" has unknown fieldTemplate ${JSON.stringify(f.fieldTemplate)}`);
+        }
+        if (f.fieldTemplate === 'partEditorTemplate' && (!f.partTemplate || typeof f.partTemplate !== 'string')) {
+            throw new Error(`template-def ${ctx}: part field "${f.name}" requires a string "partTemplate" (the referenced part-template alias)`);
+        }
+    });
+}
+/**
+ * Validate + normalize a schema-as-file template-def object into the DB-loaded shape.
+ * Pure. Throws on structural / vocabulary errors (the load-time lint seam).
+ *
+ * @param {object} def parsed file object (see FILE SHAPE above)
+ * @returns {{id, kind, alias, name, description, customDefaultLayout, layouts, content}}
+ *   `content` is `JSON.stringify(def.fields)` — a drop-in for a Sequelize template row.
+ */
+export function parseTemplateDef(def) {
+    if (!def || typeof def !== 'object' || Array.isArray(def)) {
+        throw new Error('template-def must be an object');
+    }
+    const { kind, alias } = def;
+    if (!kind || !TEMPLATE_KINDS.has(kind)) {
+        throw new Error(`template-def: unknown kind ${JSON.stringify(kind)} — expected one of: ${[...TEMPLATE_KINDS].join(', ')}`);
+    }
+    if (!alias || typeof alias !== 'string') {
+        throw new Error(`template-def (${kind}): "alias" is required (a string)`);
+    }
+    const fields = def.fields == null ? [] : def.fields;
+    validateFields(fields, `${kind}:${alias}`);
+    return {
+        id: def.id,
+        kind,
+        alias,
+        name: def.name == null ? alias : def.name,
+        description: def.description == null ? null : def.description,
+        customDefaultLayout: def.customDefaultLayout == null ? null : def.customDefaultLayout,
+        layouts: def.layouts == null
+            ? null
+            : (typeof def.layouts === 'string' ? def.layouts : JSON.stringify(def.layouts)),
+        content: JSON.stringify(fields),
+    };
+}
+/**
+ * Read + parse a template-def JSON file from disk into the normalized DB-loaded shape.
+ * The thin IO wrapper over `parseTemplateDef` (the file-loader the engine plugs in alongside
+ * its DB loader).
+ *
+ * @param {string} filePath absolute or cwd-relative path to a template-def `.json` file
+ * @returns {{id, kind, alias, name, description, customDefaultLayout, layouts, content}}
+ */
+export function loadTemplateDefFile(filePath) {
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf8');
+    }
+    catch (e) {
+        throw new Error(`template-def file ${filePath}: cannot read — ${e.message}`);
+    }
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`template-def file ${filePath}: invalid JSON — ${e.message}`);
+    }
+    return parseTemplateDef(obj);
+}

package/dist/test/fixtures/broken-driver/index.d.ts

@@ -0,0 +1,3 @@
+export const Pool: {
+    new (): {};
+};

package/dist/test/fixtures/broken-driver/index.js

@@ -0,0 +1,5 @@
+// Stands in for an *installed* driver whose own dependency is missing: the failure is a real
+// resolution bug inside the driver, and it must reach the caller unchanged.
+import 'definitely-not-installed-inner';
+export const Pool = class {
+};

package/dist/test/support/dialect-stand.d.ts

@@ -0,0 +1,37 @@
+export function fillCanonRow(table: any, values?: {}): {};
+export function dialectDdl(dialect: any, tables: any, { constraints }?: {
+    constraints?: boolean;
+}): string;
+export function sqliteStand({ ddl }: {
+    ddl: any;
+}): Promise<{
+    db: Kysely<any>;
+    query: (statement: any) => Promise<Record<string, import("node:sqlite").SQLOutputValue>[]>;
+    cleanup: () => Promise<void>;
+}>;
+export function postgresStand(url: any, { ddl, database }: {
+    ddl: any;
+    database?: string;
+}): Promise<{
+    db: Kysely<any>;
+    url: string;
+    cleanup: () => Promise<void>;
+}>;
+export function mariadbStand(url: any, { ddl, database }: {
+    ddl: any;
+    database?: string;
+}): Promise<{
+    db: Kysely<any>;
+    url: any;
+    cleanup: () => Promise<void>;
+}>;
+export function stringColumnType(dialect: any, length: any): any;
+export function mssqlStand(dsn: any, { ddl, database }: {
+    ddl: any;
+    database?: string;
+}): Promise<{
+    db: Kysely<any>;
+    url: any;
+    cleanup: () => Promise<void>;
+}>;
+import { Kysely } from 'kysely';

package/dist/test/support/dialect-stand.js

@@ -0,0 +1,162 @@
+// Shared stand harness for the dialect tests (task:3822, task:3821).
+//
+// Not a test file: the plumbing every dialect test needs — the node:sqlite Kysely
+// dialect, a fresh database per run, and the generated DDL narrowed to a set of
+// tables. The DDL always comes from the generated artifact (`renderDdlSql`), never
+// from a hand-written schema, so a dialect test exercises what the generator emits.
+//
+//   const stand = await sqliteStand({ ddl: dialectDdl('sqlite', ['Pages']) });
+//   try { ...stand.db... } finally { await stand.cleanup(); }
+import { Kysely, MysqlDialect, PostgresDialect } from 'kysely';
+import { canonicalSchema } from "../../schema/index.js";
+import { mapType, renderDdlSql } from '../../schema/generate.mjs';
+import { nodeSqliteDialect, openSqlite } from '../../sqliteDialect.js';
+/**
+ * Every NOT NULL column the canon declares, filled with a type-correct value so a
+ * test can insert a row without spelling out the whole table. `SiteId` is never
+ * filled: the guard owns the tenant key (R1), and a caller that wants it passes it
+ * explicitly in `values`.
+ */
+export const fillCanonRow = (table, values = {}) => {
+    const spec = canonicalSchema.tables.find((candidate) => candidate.name === table);
+    if (!spec)
+        throw new Error(`fillCanonRow: "${table}" is not a canon table`);
+    const row = { ...values };
+    for (const [name, column] of Object.entries(spec.columns)) {
+        if (name === 'SiteId' || column.nullable === true || column.default !== undefined || name in row)
+            continue;
+        row[name] =
+            column.type === 'bool' ? false
+                : column.type === 'int' || column.type === 'bigint' ? 0
+                    : column.type === 'decimal' ? '0'
+                        : column.type === 'datetime' || column.type === 'date' ? '2026-01-02 03:04:05'
+                            : column.type === 'uuid' ? '99999999-9999-9999-9999-999999999999'
+                                : 'x';
+    }
+    return row;
+};
+/** Generated DDL, narrowed to the tables a scenario touches (order preserved). */
+export const dialectDdl = (dialect, tables, { constraints = true } = {}) => {
+    const subjects = new Set(tables);
+    return renderDdlSql(dialect)
+        .split(/;\r?\n/)
+        .map((statement) => statement.trim())
+        .filter((statement) => statement && subjects.has(subjectTable(statement)))
+        // a narrowed stand may create one table whose parents are absent: the constraint
+        // would reference a table nobody built (SQL Server refuses immediately)
+        .filter((statement) => constraints || subjectTable(statement) === null || !/^alter\s+table/i.test(codeOf(statement)))
+        .map((statement) => `${statement};`)
+        .join('\n');
+};
+/** The statement with the generator's leading comments stripped. */
+const codeOf = (statement) => statement.replace(/^(?:\s*--[^\n]*\n)+/, '').trim();
+/** The table a generated statement acts on — `create table`, `alter table`, `create index`. */
+const subjectTable = (statement) => {
+    // the first chunk carries the generator's header comment; soft-fk comments ride
+    // ahead of the statement they describe
+    const code = statement.replace(/^(?:\s*--[^\n]*\n)+/, '').trim();
+    // `"x"` / `` `x` `` / `[x]` — the quoting differs per dialect, the shape does not
+    const match = code.match(/^(?:create\s+table|alter\s+table|create\s+(?:unique\s+)?index\s+\S+\s+on)\s+(?:([`"])([^`"]+)\1|\[([^\]]+)\])/i);
+    return match?.[2] ?? match?.[3] ?? null;
+};
+/** Kysely over an in-memory node:sqlite database created with `ddl`. */
+export const sqliteStand = ({ ddl }) => {
+    const sync = openSqlite(':memory:');
+    sync.exec(ddl);
+    const db = new Kysely({ dialect: nodeSqliteDialect(sync) });
+    return Promise.resolve({
+        db,
+        query: async (statement) => sync.prepare(statement).all(),
+        cleanup: async () => {
+            await db.destroy();
+        },
+    });
+};
+const DEFAULT_DATABASE = 'dialect_stand';
+/** A fresh Postgres database (not a schema) created with `ddl`. */
+export const postgresStand = async (url, { ddl, database = DEFAULT_DATABASE }) => {
+    const { Client, Pool } = await import('pg');
+    const admin = new Client({ connectionString: url });
+    await admin.connect();
+    await admin.query(`drop database if exists ${database} with (force)`);
+    await admin.query(`create database ${database}`);
+    await admin.end();
+    const target = new URL(url);
+    target.pathname = `/${database}`;
+    const connectionString = target.toString();
+    const setup = new Client({ connectionString });
+    await setup.connect();
+    await setup.query(ddl);
+    await setup.end();
+    const db = new Kysely({ dialect: new PostgresDialect({ pool: new Pool({ connectionString }) }) });
+    return {
+        db,
+        url: connectionString,
+        cleanup: async () => {
+            await db.destroy();
+        },
+    };
+};
+/** A fresh MariaDB database (utf8mb4) created with `ddl`. */
+export const mariadbStand = async (url, { ddl, database = DEFAULT_DATABASE }) => {
+    const parsed = new URL(url);
+    const base = {
+        host: parsed.hostname,
+        port: Number(parsed.port || 3306),
+        user: decodeURIComponent(parsed.username),
+        password: decodeURIComponent(parsed.password),
+    };
+    const promise = (await import('mysql2/promise')).default;
+    const setup = await promise.createConnection({ ...base, multipleStatements: true });
+    await setup.query(`drop database if exists ${database}`);
+    await setup.query(`create database ${database} character set utf8mb4 collate utf8mb4_unicode_ci`);
+    await setup.query(`use ${database}`);
+    await setup.query(ddl);
+    await setup.end();
+    // Kysely's MySQL driver speaks the callback API of mysql2, not the promise one.
+    const mysql = (await import('mysql2')).default;
+    const pool = mysql.createPool({ ...base, database, connectionLimit: 4 });
+    const db = new Kysely({ dialect: new MysqlDialect({ pool }) });
+    return {
+        db,
+        url,
+        cleanup: async () => {
+            await db.destroy();
+        },
+    };
+};
+/**
+ * A string column's type as the generator maps it for this dialect — a test that adds a
+ * column by hand must not re-invent the type map (MSSQL's `varchar` is not Unicode and
+ * silently mangles text; task:3994).
+ */
+export const stringColumnType = (dialect, length) => mapType({ type: 'string', length }, dialect);
+/**
+ * A fresh SQL Server database created with `ddl` (task:3994: MSSQL became a target, so it
+ * needs the same stand as the other engines). The DSN is the ADO form `openDb` expects.
+ */
+export const mssqlStand = async (dsn, { ddl, database = DEFAULT_DATABASE }) => {
+    const { openDb } = await import('../../dbProvider.js');
+    const { sql } = await import('kysely');
+    const onDatabase = (name) => dsn.replace(/(database|initial catalog)=[^;]*/i, `Database=${name}`);
+    const master = await openDb({ dialect: 'mssql', dsn: onDatabase('master') });
+    try {
+        await sql.raw(`if db_id('${database}') is not null begin alter database [${database}] set single_user with rollback immediate; drop database [${database}]; end`).execute(master);
+        await sql.raw(`create database [${database}]`).execute(master);
+    }
+    finally {
+        await master.destroy();
+    }
+    const db = await openDb({ dialect: 'mssql', dsn: onDatabase(database) });
+    const text = ddl.split('\n').filter((line) => !line.trim().startsWith('--')).join('\n');
+    for (const statement of text.split(/;\s*\n/).map((part) => part.trim()).filter(Boolean)) {
+        await sql.raw(statement).execute(db);
+    }
+    return {
+        db,
+        url: onDatabase(database),
+        cleanup: async () => {
+            await db.destroy();
+        },
+    };
+};

package/dist/test/support/render-parity.d.ts

@@ -0,0 +1,44 @@
+/** The fixed capture kinds (plan:50 Q7.1); a page set must match this exactly. */
+export const PAGE_KINDS: string[];
+export function loadPageSet(source?: any): Promise<any[]>;
+export function stripCacheBust(url: any): any;
+export function normalizeText(text: any, { origin, contentType }?: {
+    contentType?: string;
+}): any;
+export function normalizeHtml(html: any, { origin }?: {}): any;
+export function captureSite({ origin, pages, fetchImpl, timeoutMs }: {
+    origin: any;
+    pages?: any;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<{
+    origin: any;
+    pages: ({
+        name: any;
+        kind: any;
+        path: any;
+        status: number;
+        location: any;
+        error: any;
+        body: any;
+    } | {
+        name: any;
+        kind: any;
+        path: any;
+        status: any;
+        location: any;
+        error: string;
+        body: string;
+    })[];
+}>;
+export function diffSnapshots(baseline: any, target: any): {
+    name: any;
+    kind: string;
+    path: any;
+    lines: string[];
+}[];
+export function formatReport({ baseline, target, diffs }: {
+    baseline: any;
+    target: any;
+    diffs: any;
+}): string;