@tiaforge-ui/sinter 0.0.0-stage → 0.1.0

package/dist/check/shadow.js

@@ -0,0 +1,245 @@
+// Shadow files: one checked JavaScript file per page, in which every expression of
+// the page appears verbatim, inside nested blocks that declare what it can see.
+// TypeScript checks the file (`checkJs`); `mapLine` turns its positions back into
+// positions in the HTML.
+import { dirname, relative } from 'node:path';
+import { STORE_FNS, BUILTIN_HELPERS } from '../compiler/expr.js';
+import { schemaToTs, typeName } from './openapi-types.js';
+export function shadow(o) {
+    const { unit } = o;
+    const out = [];
+    const regions = [];
+    const line = (s) => out.push(s);
+    /** writes `src` from column 1 of the next line, so columns after its first line are the HTML's own */
+    const verbatim = (src, loc) => {
+        const lines = src.split('\n');
+        regions.push({ start: out.length + 1, lines: lines.length, loc });
+        out.push(...lines);
+    };
+    const spec = (target) => {
+        let s = relative(dirname(o.file), target).split('\\').join('/');
+        if (!s.startsWith('.'))
+            s = './' + s;
+        return s;
+    };
+    const moduleSpec = (m) => (m.startsWith('/') ? spec(o.root + m) : m);
+    const sinter = spec(o.declarations).replace(/\.d\.ts$/, '');
+    const decl = (name) => `import('${sinter}').${name}`;
+    line('// @ts-check');
+    line(`// Generated by \`sinter check\` from ${relative(o.root, unit.file).split('\\').join('/')}. Do not edit.`);
+    if (o.types?.names.length)
+        line(`/** @import { ${o.types.names.join(', ')} } from '${spec(o.types.file).replace(/\.(d\.)?ts$/, '')}' */`);
+    const refs = unit.exprs.flatMap((e) => [e.resultType, e.returns, e.payload?.type]);
+    const specs = new Set([
+        ...unit.resources.flatMap((r) => (r.openapi && !r.type ? [r.openapi.spec] : [])),
+        ...refs.flatMap((t) => (t?.kind === 'openapi' ? [t.spec] : [])),
+    ]);
+    for (const i of [...specs].sort())
+        line(`/** @import * as $O${i} from '${spec(o.openapi[i]).replace(/\.d\.ts$/, '')}' */`);
+    // names a page can see besides its own frames; resources first, as sinter resolves them
+    const taken = new Set(unit.resources.map((r) => r.name));
+    for (const n of ['$any', '$item', '$el', '$event', '$result', '$error', '$meta', '$url', '$now', '$locale', ...STORE_FNS])
+        taken.add(n);
+    const builtin = BUILTIN_HELPERS.filter((h) => !taken.has(h));
+    for (const h of builtin)
+        taken.add(h);
+    line(`import { ${builtin.join(', ')} } from '${sinter}';`);
+    const userHelpers = o.helpers.names.filter((h) => !taken.has(h));
+    if (o.helpers.module && userHelpers.length)
+        line(`import { ${userHelpers.join(', ')} } from '${moduleSpec(o.helpers.module)}';`);
+    for (const [ns, { module }] of Object.entries(o.helpers.namespaces)) {
+        if (!taken.has(ns))
+            line(`import * as ${ns} from '${moduleSpec(module)}';`);
+    }
+    line('const $any = /** @type {any} */ (null);');
+    const types = [];
+    for (const r of unit.resources) {
+        const t = r.type ?? 'any';
+        types.push(`${JSON.stringify(r.name)}: ${t}`);
+        if (r.type) {
+            line('/**');
+            line(' * @type {');
+            verbatim(r.type, r.loc);
+            regions[regions.length - 1].fixed = true;
+            line(' * }');
+            line(' */');
+        }
+        else if (r.openapi) {
+            const t = schemaToTs(r.openapi.schema, (n) => `$O${r.openapi.spec}.${typeName(n)}`);
+            types[types.length - 1] = `${JSON.stringify(r.name)}: ${t}`;
+            regions.push({ start: out.length + 1, lines: 1, loc: r.loc, fixed: true });
+            line(`/** @type {${t}} ${r.openapi.label.replace(/\*\//g, '')} */`);
+        }
+        else
+            line('/** @type {any} */');
+        regions.push({ start: out.length + 1, lines: 1, loc: r.nameLoc ?? r.loc, fixed: true });
+        line(`const ${r.name} = $any;`);
+    }
+    const names = unit.resources.map((r) => JSON.stringify(r.name)).join(' | ') || 'never';
+    line(`/** @type {Record<${names}, ${decl('Meta')}>} */`);
+    line('const $meta = $any;');
+    line('/** @type {Record<string, any>} */');
+    line('const $url = $any;');
+    line('/** @type {Date} */');
+    line('const $now = $any;');
+    line('/** @type {string} */');
+    line('let $locale = $any;');
+    line(`/** @type {${decl('Store')}<{ ${types.join('; ')} }>} */`);
+    line(`const { ${STORE_FNS.join(', ')} } = $any;`);
+    line(`/** @template T @param {T} list @returns {${decl('Item')}<T>} */`);
+    line('function $item(list) { return $any; }');
+    /** a JSDoc tag with a type; a type the app wrote maps its errors to where it was written */
+    const tagged = (tag, t, after = '') => {
+        if (t.kind === 'ts') {
+            line(`/** @${tag} {`);
+            verbatim(t.text, t.loc);
+            regions[regions.length - 1].fixed = true;
+            line(`} */${after}`);
+            return;
+        }
+        const text = t.kind === 'openapi'
+            ? schemaToTs(t.schema, (n) => `$O${t.spec}.${typeName(n)}`)
+            : `${t.partial ? 'Partial<' : ''}${decl('Item')}<typeof ${t.resource}>${t.partial ? '>' : ''}`;
+        line(`/** @${tag} {${text}} */${after}`);
+    };
+    /** declarations for the frames of an expression; returns the number of blocks opened */
+    const open = (frames) => {
+        for (const i of frames) {
+            const f = unit.frames[i];
+            line('{');
+            // declarations map to where the HTML writes the names, for go to definition
+            const at = (loc) => { if (loc)
+                regions.push({ start: out.length + 1, lines: 1, loc, fixed: true }); };
+            if (f.kind === 'state') {
+                line('let {');
+                f.names.forEach((n, k) => { at(f.locs?.[k]); line(`${n},`); });
+                line(`} = ${f.init === null ? '$any' : `$e${f.init}()`};`);
+            }
+            else {
+                at(f.loc);
+                line(`const ${f.item} = ${f.init === null ? '$any' : `$item($e${f.init}())`};`);
+                if (f.index) {
+                    at(f.indexLoc);
+                    line(`const ${f.index} = 0;`);
+                }
+            }
+        }
+        return frames.length;
+    };
+    // broken expressions last, so their syntax errors cannot spill into checked code
+    const order = unit.exprs.map((e, i) => [e, i]).sort(([a], [b]) => Number(!!a.broken) - Number(!!b.broken));
+    let brokenFrom = null;
+    order.forEach(([e, i]) => {
+        if (e.broken && brokenFrom === null)
+            brokenFrom = out.length + 1;
+        line('');
+        if (e.returns)
+            tagged('returns', e.returns);
+        line(`function $e${i}() {`);
+        const blocks = open(e.frames);
+        line(`/** @type {${decl(`El<${JSON.stringify(e.tag)}>`)}} */ const $el = $any;`);
+        if (e.payload) {
+            if (e.payload.type)
+                tagged('type', e.payload.type, ' const $p = $any;');
+            else
+                line('const $p = $any;');
+            // a field the payload type lacks is reported at the start of the expression
+            for (const n of e.payload.names) {
+                regions.push({ start: out.length + 1, lines: 1, loc: e.loc, fixed: true });
+                line(`const ${n} = $p.${n};`);
+            }
+        }
+        if (e.mode === 'value') {
+            // a value of the wrong type as a whole is reported on `return`
+            regions.push({ start: out.length + 1, lines: 1, loc: e.loc, fixed: true });
+            line('return (');
+            verbatim(e.src, e.loc);
+            line(');');
+        }
+        else {
+            line(`/** @type {${decl(`Ev<${JSON.stringify(e.event ?? '')}>`)}} */ const $event = $any;`);
+            if (e.result) {
+                if (e.resultType)
+                    tagged('type', e.resultType, ' const $result = $any;');
+                else
+                    line('/** @type {any} */ const $result = $any;');
+            }
+            if (e.error)
+                line(`/** @type {${decl('Err')}} */ const $error = $any;`);
+            verbatim(e.src, e.loc);
+            line(';');
+        }
+        for (let b = 0; b < blocks; b++)
+            line('}');
+        line('}');
+    });
+    return { text: out.join('\n') + '\n', regions, brokenFrom };
+}
+/** Maps a 1-based shadow position to the HTML, or null for generated lines. */
+export function mapPosition(regions, line, col) {
+    for (const r of regions) {
+        if (line < r.start || line >= r.start + r.lines)
+            continue;
+        if (r.fixed)
+            return r.loc;
+        const k = line - r.start;
+        return { ...r.loc, line: r.loc.line + k, col: k === 0 ? r.loc.col + col - 1 : col };
+    }
+    return null;
+}
+/** `sinter.d.ts`: the types the shadow files refer to. */
+export const DECLARATIONS = `// Generated by \`sinter check\`. Do not edit.
+export interface Meta {
+  loading: boolean;
+  error: Err | null;
+  loadedAt: number | null;
+  pending: number;
+  total: number | null;
+  page?: number;
+  pages?: number | null;
+  from?: number | null;
+  to?: number | null;
+  hasPrev?: boolean;
+  hasNext?: boolean;
+}
+export interface Err { status: number; body: any; message: string }
+export type Item<T> = NonNullable<T> extends readonly (infer U)[] ? U : NonNullable<T> extends Iterable<infer U> ? U : any;
+export type El<K extends string> = K extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[K] : HTMLElement;
+export type Ev<K extends string> = K extends keyof HTMLElementEventMap ? HTMLElementEventMap[K] : CustomEvent;
+export interface Store<R> {
+  refresh(name: keyof R & string): void;
+  upsert<K extends keyof R & string>(name: K, item: Item<R[K]>): void;
+  patch<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>, set: Partial<Item<R[K]>>): void;
+  remove<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>): void;
+  page(name: keyof R & string, to: 'next' | 'prev' | 'first' | 'last' | number): void;
+  close(): void;
+  reset(): void;
+  emit(event: string, detail?: unknown): void;
+}
+type Style = 'short' | 'medium' | 'long' | 'full';
+export function date(v: unknown, style?: Style): string;
+export function time(v: unknown, style?: Style): string;
+export function datetime(v: unknown, style?: Style): string;
+export function relative(v: unknown, now?: unknown): string;
+export function number(v: unknown, opts?: Intl.NumberFormatOptions): string;
+export function bytes(v: unknown): string;
+`;
+/**
+ * Maps a 1-based position in an HTML file to the shadow, or null when it is not inside an
+ * expression. `lines` are the shadow's lines.
+ */
+export function shadowPosition(regions, lines, file, line, col) {
+    for (const r of regions) {
+        if (r.fixed || r.loc.file !== file)
+            continue;
+        const k = line - r.loc.line;
+        if (k < 0 || k >= r.lines)
+            continue;
+        const text = lines[r.start - 1 + k] ?? '';
+        const c = k === 0 ? col - r.loc.col + 1 : col;
+        if (c < 1 || c > text.length + 1)
+            continue;
+        return { line: r.start + k, col: c };
+    }
+    return null;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// `sinter check [--root <dir>] [page.html …]`: compiles the pages and type-checks
+// their expressions. Without pages, it reads them and the plugin options from the
+// Vite config. `sinter lsp`: the language server for editors.
+import { readFileSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { check } from './check/index.js';
+import { compile, formatDiagnostic } from './compiler/index.js';
+import { project, viteProject } from './project.js';
+const USAGE = 'usage: sinter check [--root <dir>] [page.html …]\n       sinter lsp [--stdio]';
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === 'lsp')
+        return lsp();
+    if (command !== 'check') {
+        console.error(USAGE);
+        return 2;
+    }
+    let root = process.cwd();
+    const pages = [];
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === '--root')
+            root = resolve(rest[++i] ?? '.');
+        else
+            pages.push(rest[i]);
+    }
+    let options = {};
+    let files = pages.map((p) => resolve(root, p));
+    if (!files.length)
+        ({ pages: files, options } = await viteProject(root));
+    if (!files.length) {
+        console.error(`sinter check: no pages found; pass them as arguments\n${USAGE}`);
+        return 2;
+    }
+    const p = project(root, options);
+    const diagnostics = [...p.diagnostics];
+    const units = [];
+    for (const file of files) {
+        const out = compile(readFileSync(file, 'utf8'), { file, root, dev: false, helpers: p.helpers, config: p.config, readFile: p.readFile, check: true, openapi: p.openapi });
+        diagnostics.push(...out.diagnostics);
+        if (out.check)
+            units.push(out.check);
+    }
+    const r = check({ root, units, helpers: p.helpers, types: p.types, openapi: p.openapi });
+    diagnostics.push(...r.diagnostics);
+    for (const d of diagnostics)
+        console.log(formatDiagnostic({ ...d, file: relative(process.cwd(), d.file) || d.file }) + '\n');
+    const errors = diagnostics.filter((d) => d.severity === 'error').length;
+    const warnings = diagnostics.length - errors;
+    console.log(`sinter check: ${files.length} page(s), ${errors} error(s), ${warnings} warning(s); ${r.typed} of ${r.resources} resources typed${r.openapi ? ` (${r.openapi} via OpenAPI)` : ''}`);
+    return errors ? 1 : 0;
+}
+/** Language server over stdio; stdout carries only protocol messages. */
+async function lsp() {
+    const toStderr = (...args) => process.stderr.write(args.map(String).join(' ') + '\n');
+    console.log = console.info = console.warn = console.debug = toStderr;
+    const { startServer } = await import('./lsp/server.js');
+    return new Promise((done) => {
+        const conn = startServer(process.stdin, process.stdout, { exit: (code) => process.exit(code) });
+        const closed = conn.onClose;
+        conn.onClose = () => { closed?.(); done(0); };
+    });
+}
+main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (err) => {
+    console.error(`sinter check: ${err instanceof Error ? err.message : String(err)}`);
+    process.exitCode = 2;
+});

package/dist/compiler/check-unit.d.ts

@@ -0,0 +1,97 @@
+/** Where an expression (or a `type` attribute value) starts in its source file. */
+export interface CheckLoc {
+    file: string;
+    line: number;
+    col: number;
+    /** include chain, innermost first (`page.html:12`), for messages */
+    chain: string[];
+}
+/**
+ * A scope frame: a `data-sn-state` object or a `data-sn-for` loop. `init` is the
+ * expression that creates it (the state literal, the list), or null when that
+ * expression did not compile.
+ */
+export type CheckFrame = 
+/** `locs[i]`: where `names[i]` is written in the literal */
+{
+    kind: 'state';
+    names: string[];
+    init: number | null;
+    locs?: CheckLoc[];
+}
+/** `loc`, `indexLoc`: where the item and index names are written */
+ | {
+    kind: 'loop';
+    item: string;
+    index: string | null;
+    init: number | null;
+    loc?: CheckLoc;
+    indexLoc?: CheckLoc;
+};
+/** A type the checker writes for something other than a resource. */
+export type TypeRef = 
+/** written by the app (`type` on `<sn-event>`); errors in it point at `loc` */
+{
+    kind: 'ts';
+    text: string;
+    loc: CheckLoc;
+}
+/** a schema of OpenAPI spec number `spec` */
+ | {
+    kind: 'openapi';
+    spec: number;
+    schema: unknown;
+}
+/** an item of a resource on the page, or a partial one */
+ | {
+    kind: 'item';
+    resource: string;
+    partial?: boolean;
+};
+export interface CheckExpr {
+    src: string;
+    /** `value` returns the expression; `handler` runs it as statements */
+    mode: 'value' | 'handler';
+    loc: CheckLoc;
+    /** frames visible here, in the order sinter resolves them last: states outer to inner, then loops outer to inner */
+    frames: number[];
+    /** tag of the element the expression sits on, for `$el` */
+    tag: string;
+    /** DOM event that runs a handler, for `$event` */
+    event: string | null;
+    /** `$result` (then) or `$error` (catch) is in scope */
+    result: boolean;
+    error: boolean;
+    /** type of `$result`, when the action matched an OpenAPI operation */
+    resultType?: TypeRef;
+    /** the value must be assignable to this (`data-sn-body`, `<sn-event>` `item` and `set`) */
+    returns?: TypeRef;
+    /** payload expressions (`<sn-event>`, `cursor`): the payload fields read, and the payload's type (null: any) */
+    payload?: {
+        names: string[];
+        type: TypeRef | null;
+    };
+    /** the compiler reported an error in it (it may not even parse); kept for editor completion, never type-checked */
+    broken?: boolean;
+}
+export interface CheckResource {
+    name: string;
+    /** value of `type`, a TypeScript type; null when absent */
+    type: string | null;
+    /** start of the `type` value, or of the element when absent */
+    loc: CheckLoc;
+    /** start of the `name` value, where go to definition lands */
+    nameLoc?: CheckLoc;
+    /** without `type`: the OpenAPI operation `src` matched and the schema of what `items` selects */
+    openapi?: {
+        spec: number;
+        label: string;
+        schema: unknown;
+    };
+}
+export interface CheckUnit {
+    file: string;
+    resources: CheckResource[];
+    frames: CheckFrame[];
+    exprs: CheckExpr[];
+}

package/dist/compiler/check-unit.js

@@ -0,0 +1,3 @@
+// What `compile(…, { check: true })` hands the type checker: every expression of
+// the page with its source position and the scope frames it sees. Plain data.
+export {};

package/dist/compiler/compile.d.ts

@@ -0,0 +1,62 @@
+import { type Diagnostic } from './diagnostics.js';
+import type { CheckUnit } from './check-unit.js';
+import { type OpenApiSpec } from './openapi.js';
+import type { IR, NodeDef } from '../ir.js';
+export interface HelperManifest {
+    /** import specifier of the helpers module, or null */
+    module: string | null;
+    names: string[];
+    namespaces: Record<string, {
+        module: string;
+        members: string[];
+    }>;
+}
+export interface CompileOptions {
+    file: string;
+    root: string;
+    readFile: (path: string) => string;
+    helpers: HelperManifest;
+    dev: boolean;
+    /** URL the injected `<script type="module">` loads the page module from */
+    moduleSrc?: string;
+    /** app configuration module imported before mount (e.g. `/src/sinter.config.js`) */
+    config?: string | null;
+    /** also return a check unit for `sinter check`, and warn about resources without `type` */
+    check?: boolean;
+    /** parsed OpenAPI specs: resources without `type` are matched against them */
+    openapi?: OpenApiSpec[];
+}
+export interface CompileResult {
+    html: string;
+    module: string;
+    diagnostics: Diagnostic[];
+    files: string[];
+    /** with `check: true` */
+    check?: CheckUnit;
+}
+export interface CompiledParts {
+    html: string;
+    ir: IR;
+    fns: string[];
+    features: string[];
+    /** helper names imported from the helpers module or the core */
+    helpers: {
+        user: string[];
+        builtin: string[];
+    };
+    namespaces: Record<string, string[]>;
+    diagnostics: Diagnostic[];
+    files: string[];
+    /** with `check: true` */
+    check?: CheckUnit;
+}
+export declare function compileParts(html: string, options: CompileOptions): CompiledParts;
+export declare function normalize(p: string): string;
+export declare function dirname(p: string): string;
+export declare function basename(p: string): string;
+/**
+ * A row template's element lookup as straight-line code: each path prefix is walked once
+ * (`firstChild` / `nextSibling`), and an element whose tag does not match comes out null.
+ * The argument is the clone's first content node (the row element itself for a one-element row).
+ */
+export declare function findCode(nodes: NodeDef[]): string;