@monosmith/plugin-sdk 0.0.0-stage → 0.1.0

package/templating/template-syntax.contract.js

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

package/templating/template.error.d.ts

@@ -0,0 +1,4 @@
+/** A template that cannot be parsed or rendered: bad syntax, a field the data does not have, a construct outside the supported subset. */
+export declare class TemplateError extends Error {
+    constructor(name: string, message: string);
+}

package/templating/template.error.js

@@ -0,0 +1,7 @@
+/** A template that cannot be parsed or rendered: bad syntax, a field the data does not have, a construct outside the supported subset. */
+export class TemplateError extends Error {
+    constructor(name, message) {
+        super(`template ${name}: ${message}`);
+        this.name = 'TemplateError';
+    }
+}

package/templating/tokenize-action.algorithm.d.ts

@@ -0,0 +1,20 @@
+export type Token = {
+    t: 'open' | 'close' | 'pipe';
+} | {
+    t: 'field';
+    root: boolean;
+    path: string[];
+} | {
+    t: 'string';
+    value: string;
+} | {
+    t: 'number';
+    value: number;
+} | {
+    t: 'word';
+    value: string;
+};
+/**
+ * Splits the text of an action into tokens. `fail` reports what cannot be a token.
+ */
+export declare function tokenizeAction(body: string, fail: (message: string) => never): Token[];

package/templating/tokenize-action.algorithm.js

@@ -0,0 +1,57 @@
+/**
+ * The elements of an action, in the order the alternatives are tried: space,
+ * brackets and pipe, a quoted or raw string, a number, a field (`.A.B`, `$`,
+ * `$.A`, or a lone `.`), a word, and `:=`/`=`, which are variables. Anything else
+ * is the last alternative, so every character belongs to some match.
+ */
+const ELEMENT = new RegExp([
+    String.raw `\s+`,
+    String.raw `(?<open>\()`,
+    String.raw `(?<close>\))`,
+    String.raw `(?<pipe>\|)`,
+    String.raw `(?<string>"(?:[^"\\]|\\.)*")`,
+    '(?<raw>`[^`]*`)',
+    String.raw `(?<number>-?\d+(?:\.\d+)?(?![\w.]))`,
+    String.raw `(?<field>\$(?:\.[A-Z_]\w*)*|(?:\.[A-Z_]\w*)+|\.)`,
+    String.raw `(?<word>[A-Z_]\w*)`,
+    '(?<variable>:?=)',
+    '(?<other>.)',
+].join('|'), 'gis');
+/**
+ * Splits the text of an action into tokens. `fail` reports what cannot be a token.
+ */
+export function tokenizeAction(body, fail) {
+    const tokens = [];
+    for (const match of body.matchAll(ELEMENT)) {
+        const found = match.groups ?? {};
+        if (found.open !== undefined)
+            tokens.push({ t: 'open' });
+        else if (found.close !== undefined)
+            tokens.push({ t: 'close' });
+        else if (found.pipe !== undefined)
+            tokens.push({ t: 'pipe' });
+        else if (found.string !== undefined)
+            tokens.push({ t: 'string', value: unquote(found.string, fail) });
+        else if (found.raw !== undefined)
+            tokens.push({ t: 'string', value: found.raw.slice(1, -1) });
+        else if (found.number !== undefined)
+            tokens.push({ t: 'number', value: Number(found.number) });
+        else if (found.field !== undefined)
+            tokens.push({ t: 'field', root: found.field.startsWith('$'), path: found.field.split('.').filter(part => part !== '' && part !== '$') });
+        else if (found.word !== undefined)
+            tokens.push({ t: 'word', value: found.word });
+        else if (found.variable !== undefined)
+            fail('variables are not supported by the SDK\'s templates');
+        else if (found.other !== undefined)
+            fail(`unexpected character "${found.other}" in action`);
+    }
+    return tokens;
+}
+function unquote(literal, fail) {
+    try {
+        return JSON.parse(literal);
+    }
+    catch {
+        return fail(`invalid string ${literal}`);
+    }
+}

package/templating/write-templates.use-case.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Renders every template in `files` (target path to template text) under
+ * `root` with `data`, creating directories as needed. A target path may itself
+ * contain template actions (`[[.Dir]]/main.ts`). Returns the written paths,
+ * forward-slashed and relative to `root`, in the order of the sorted templates.
+ *
+ * Nothing is written if any template fails to render or any target exists
+ * ({@link FileExistsError}): it never overwrites a file. A target that would
+ * land outside `root` is refused.
+ */
+export declare function writeTemplates(root: string, files: Record<string, string>, data?: unknown): Promise<string[]>;

package/templating/write-templates.use-case.js

@@ -0,0 +1,44 @@
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, posix, resolve, sep } from 'node:path';
+import { FileExistsError } from './file-exists.error.js';
+import { renderTemplate } from './render-template.algorithm.js';
+import { byKey } from './template-functions.algorithm.js';
+import { TemplateError } from './template.error.js';
+/**
+ * Renders every template in `files` (target path to template text) under
+ * `root` with `data`, creating directories as needed. A target path may itself
+ * contain template actions (`[[.Dir]]/main.ts`). Returns the written paths,
+ * forward-slashed and relative to `root`, in the order of the sorted templates.
+ *
+ * Nothing is written if any template fails to render or any target exists
+ * ({@link FileExistsError}): it never overwrites a file. A target that would
+ * land outside `root` is refused.
+ */
+export async function writeTemplates(root, files, data) {
+    const rendered = [];
+    for (const target of Object.keys(files).sort(byKey)) {
+        const path = posix.normalize(renderTemplate(target, data, 'path'));
+        const full = resolve(root, ...path.split('/'));
+        if (path === '..' || path.startsWith('../') || isAbsolute(path) || !full.startsWith(resolve(root) + sep)) {
+            throw new TemplateError(path, 'the target is outside the project root');
+        }
+        if (await exists(full))
+            throw new FileExistsError(path);
+        rendered.push({ path, content: renderTemplate(files[target], data, path) });
+    }
+    for (const file of rendered) {
+        const full = join(root, ...file.path.split('/'));
+        await mkdir(dirname(full), { recursive: true, mode: 0o755 });
+        await writeFile(full, file.content, { mode: 0o644 });
+    }
+    return rendered.map(file => file.path);
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}