@prestack/thread-ui 0.0.1 → 0.1.0

package/dist/ui/compositions.js

@@ -1,19 +1,12 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join } from 'node:path';
-import { stdout } from 'node:process';
-import { pathToFileURL } from 'node:url';
-import { wrapped } from "@prestack/thread/core/asking";
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "@prestack/thread/core/files";
+import { basename, dirname, join, relative } from 'node:path';
+import { argv, stdout } from 'node:process';
+import { TYPED, wrapped } from "@prestack/thread/core/answers";
 import { exit, invoked } from "@prestack/thread/core/invoked";
+import { valuesIn } from "@prestack/thread/core/rows";
 import { named as packageOf } from "@prestack/thread/core/scope";
 import { findTree, inTree } from "@prestack/thread/core/tree";
+import { compiled } from "./generators/react.js";
 export const TEACHES = [
     '  what the body may reach, and how a premium state is written:',
     '',
@@ -21,23 +14,27 @@ export const TEACHES = [
     '    the row that declared itself the caller — and `translate`, `clock` and `dispatch`. Name',
     '    it in the body and the import is written for you.',
     '',
-    '    A premium state is DATA, not a permission. The row says what somebody IS; a grant says',
-    '    what they may RUN; a variant says how a thing LOOKS. So a locked look is a signal set',
-    '    from a value you already have, so the hook is read where it is used:',
+    '    A premium look is not decided at the call site. A grant already says who may run an',
+    '    operation, in words your own entity declares, and a signal that names that operation',
+    '    holds for exactly the callers the grant refuses. The rule is written once, on the',
+    '    grant, and every screen follows it:',
     '',
-    '      <FeatureBox.paywalled locked={useUi().actor?.roles.includes(\'role_paid\') !== true}>',
+    '      <FeatureBox.paywalled>',
     '        <Text k=\'feature.title\' />',
     '      </FeatureBox.paywalled>',
     '',
     '    Read it in three parts, and each is its own command:',
     '',
-    '      `locked` is a boolean prop because the ELEMENT declares it raises that signal —',
-    '      `thread create element` with `raises: locked`. A signal this app declares cannot be',
-    '      raised on an element that never said it raises one, so `Box` will not take it.',
+    '      `locked` is a signal the ELEMENT declares it raises — `thread create element` with',
+    '      `raises: locked`. A signal this app declares cannot be raised on an element that',
+    '      never said it raises one, so `Box` will not take it. Nothing passes it here: it is',
+    '      set for you wherever the gate refuses the operation the signal names.',
     '      `.paywalled` is a variant worn as the TAG, never passed as a prop, and it is what',
     '      carries the look — `thread create variant` with a `state: locked` and what it sets.',
-    '      `useUi().actor` is who is asking, with the roles read off the row that declared',
-    '      itself the caller in `thread create entity`.',
+    '      Declare that state on a MATERIAL instead and every variant made of it locks the same',
+    '      way, which is how one overlay dresses a whole app from one row.',
+    '      The rule itself is `thread grant`, and the words in it are options on the value your',
+    '      entity names as saying what a caller may do — `thread create entity`.',
     '',
     '    THE MEMBER IS THE VARIANT\'S WHOLE ID, CAMELCASED — never the part after the element',
     '    name. A variant `button-fill` is worn `<Button.buttonFill>`, and `<Button.fill>` is not',
@@ -78,6 +75,22 @@ export const TEACHES = [
     '    A name no screen has and a destination not written out as a name are each refused there.',
     '    Never an `href` and never',
     '    a router: a move the map cannot see is a screen the map reads as unreachable.',
+    '',
+    '  how a screen shows data:',
+    '',
+    '    A screen NAMES the reads it binds, and never fetches. `views` takes the ids of declared',
+    '    views, the framework runs each one, and `useView` hands back what came out:',
+    '',
+    '      export const Orders = screen(\'orders\', { as: \'page\', views: [\'vw_orders\'] }, () => (',
+    '        <Each rows={useView<readonly Row[]>(\'vw_orders\') ?? []} by="id">',
+    '          {(row) => <Text k="orders.line" with={{ name: row.name }} />}',
+    '        </Each>',
+    '      ))',
+    '',
+    '    `useView` comes through the same door as `useUi`, and it refuses a name the screen did not',
+    '    bind. `thread routes` refuses a view this app declares no operation for, and writes what each',
+    '    screen shows into the map. A fetch of your own, or a hook you wrote, is how a screen ends up',
+    '    showing something nothing declared, and there is no second way in.',
 ];
 export const REACHES = /\buseUi\s*\(/;
 const here = 'thread/ui/compositions.ts';
@@ -113,29 +126,25 @@ export function nameOf(at) {
     const file = at.split('\\').join('/').split('/').at(-1) ?? at;
     return PASCAL(file.replace(/^cmp_/, '').replace(/\.[^.]+$/, ''));
 }
-async function sheetOf(tree, file, ...named) {
-    try {
-        const held = (await import(__rewriteRelativeImportExtension(pathToFileURL(inTree(tree, file)).href)));
-        for (const one of named) {
-            const found = held[one]?.declares;
-            if (found !== undefined)
-                return found;
-        }
-        return [];
-    }
-    catch {
+function sheetOf(tree, file, ...named) {
+    const at = inTree(tree, file);
+    if (!existsSync(at))
         return [];
+    const held = valuesIn(readFileSync(at));
+    for (const one of named) {
+        const found = held[one]?.declares;
+        if (found !== undefined)
+            return found;
     }
+    return [];
 }
 const camelOf = (id) => id.replace(/-([a-z0-9])/g, (_, one) => one.toUpperCase());
 const sentence = (one, pad) => String(one.describes ?? '').trim() === '' ? [] : wrapped(String(one.describes), pad);
-export async function catalogue(tree, making) {
-    const [elements, variants, compositions, screens] = await Promise.all([
-        sheetOf(tree, `elements.${'ts'}`, 'ELEMENT', 'ELEMENTS'),
-        sheetOf(tree, `variants.${'ts'}`, 'VARIANT', 'VARIANTS'),
-        sheetOf(tree, `compositions.${'ts'}`, 'COMPOSITION', 'COMPOSITIONS'),
-        making === 'screen' ? sheetOf(tree, `screens.${'ts'}`, 'SCREEN', 'SCREENS') : Promise.resolve([]),
-    ]);
+function listed(tree, making) {
+    const elements = sheetOf(tree, `elements.${'ts'}`, 'ELEMENT', 'ELEMENTS');
+    const variants = sheetOf(tree, `variants.${'ts'}`, 'VARIANT', 'VARIANTS');
+    const compositions = sheetOf(tree, `compositions.${'ts'}`, 'COMPOSITION', 'COMPOSITIONS');
+    const screens = making === 'screen' ? sheetOf(tree, `screens.${'ts'}`, 'SCREEN', 'SCREENS') : [];
     const worn = new Map();
     for (const one of variants) {
         for (const each of one.wears ?? []) {
@@ -180,16 +189,18 @@ export async function catalogue(tree, making) {
                 '',
             ]),
         '  Materials, style guide values, fonts and animations are chosen inside a VARIANT, never inside',
-        '  a body — `npx thread create variant` prints every one of them at the moment one is needed.',
+        `  a body — \`${TYPED} create variant\` prints every one of them at the moment one is needed.`,
         '',
-        '  Every element and the tags it is written as: `npx thread create element`. Every variant and',
-        '  the tag it is worn as: `npx thread create variant`. Then open the one nearest to what you are',
-        '  about to build with `npx thread read <id>` — it already answers how a body is arranged, how a',
+        `  Every element and the tags it is written as: \`${TYPED} create element\`. Every variant and`,
+        `  the tag it is worn as: \`${TYPED} create variant\`. Then open the one nearest to what you are`,
+        `  about to build with \`${TYPED} read <id>\` — it already answers how a body is arranged, how a`,
         '  variant is worn and how a control reaches an operation, and a file cannot be wrong in the way',
         '  a remembered example can.',
         '',
     ];
 }
+export const catalogue = async () => listed(findTree(), 'composition');
+export const screening = async () => listed(findTree(), 'screen');
 const TAG = /<([A-Z][A-Za-z0-9]*)/g;
 export function composed(body, rows, from, except) {
     const named = new Map();
@@ -210,8 +221,10 @@ export function composed(body, rows, from, except) {
     });
 }
 const IMPORTS = /^import\s[\s\S]*?from\s*['"]([^'"]+)['"]/gm;
-export const DOORS = new Set(['react', `${packageOf('ui')}/wrappers`, `${packageOf('ui')}/drag`]);
-const SHIPPED = new RegExp(`^${packageOf('ui')}/elements/([a-z0-9-]+)$`);
+const FRAMEWORK = 'thread/';
+export const HOME = `${packageOf('ui')}/${here.slice(FRAMEWORK.length).split('/').slice(0, -1).join('/')}`;
+export const DOORS = new Set(['react', `${HOME}/wrappers`, `${HOME}/drag`]);
+const SHIPPED = new RegExp(`^${HOME}/elements/([a-z0-9-]+)$`);
 const slashed = (path) => path.split('\\').join('/');
 export function reaching(at, text, elements, declared) {
     const here = slashed(at).split('/').slice(0, -1).join('/');
@@ -229,7 +242,192 @@ export function reaching(at, text, elements, declared) {
     }
     return [...found].sort();
 }
-export async function undeclared(tree, rows) {
+const CLAUSE = /^import\s+(?!type\s)([\s\S]*?)\s*from\s*['"][^'"]+['"]/gm;
+const WORD = /(?:^|[,{]|\s)(?:[A-Za-z_$][\w$]*\s+as\s+)?([A-Za-z_$][\w$]*)/g;
+const NOT_A_NAME = new Set(['type', 'as', 'from', 'import']);
+const KEPT = 'a composition keeps no state of its own. State belongs to the element that raises the signal, in the works file beside it';
+const RUNS = 'nothing here runs on its own. A read is bound by the screen in its own views list, and a press is answered by dispatch';
+const REFUSED = {
+    useState: KEPT,
+    useReducer: KEPT,
+    useSyncExternalStore: KEPT,
+    useEffect: RUNS,
+    useLayoutEffect: RUNS,
+    element: 'only the compiler writes an element, and a file that calls it turns off the checks that keep this one declared',
+};
+export const COMPILED = 'app/_generated/compiled';
+export function compiledAt(at) {
+    return `${COMPILED}/${slashed(at)}`;
+}
+const ENDINGS = ['.tsx', '.ts'];
+function beside(root, where, said) {
+    if (!said.startsWith(`${HOME}/`))
+        return undefined;
+    const tail = said.slice(HOME.length + 1);
+    for (const ending of ENDINGS) {
+        const at = `${COMPILED}/ui/${tail}${ending}`;
+        if (!existsSync(join(root, at)))
+            continue;
+        const out = slashed(relative(dirname(where), at));
+        return out.startsWith('.') ? out : `./${out}`;
+    }
+    return undefined;
+}
+const NAMED_IMPORT = /(['"])(@[^'"]+)\1/g;
+export function settled(root, rows, checking, by, kept) {
+    const said = [];
+    for (const row of rows) {
+        const file = join(root, row.at);
+        if (!existsSync(file))
+            continue;
+        const held = compiled(readFileSync(file, 'utf8'), row.at);
+        if (held.because !== undefined) {
+            said.push(held.because);
+            continue;
+        }
+        const where = compiledAt(row.at);
+        kept.add(where);
+        const text = (held.text ?? '').replace(NAMED_IMPORT, (whole, quote, said) => {
+            const found = beside(root, where, said);
+            return found === undefined ? whole : `${quote}${found}${quote}`;
+        });
+        const at = join(root, where);
+        if (!checking) {
+            writeFileSync(at, text, 'utf8');
+            continue;
+        }
+        if (existsSync(at) && readFileSync(at, 'utf8') === text)
+            continue;
+        said.push(`${where} is not what the compiler writes from ${row.at}. A compiled file that differs from its ` +
+            `source is a hand edit wearing a generated name. Run \`${by}\` and commit what it writes.`);
+    }
+    return said;
+}
+const ORG = packageOf('ui').split('/')[0] ?? '';
+const REACHED = /^(?:import|export)\s+(type\s+)?(?:(?:[^\n]|\n(?=[ \t}]))*?\s)?from\s*['"]([^'"]+)['"]/gm;
+export const RUNTIME = ['wrappers.tsx', 'drag.ts', 'provider.tsx', 'islands/map.ts'];
+const NODE = /^node:/;
+function installs(root) {
+    try {
+        const held = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+        return new Set([...Object.keys(held.dependencies ?? {}), ...Object.keys(held.devDependencies ?? {})]);
+    }
+    catch {
+        return new Set();
+    }
+}
+function packaging(said) {
+    return said.startsWith('@') ? said.split('/').slice(0, 2).join('/') : (said.split('/')[0] ?? said);
+}
+export function emitting(root, entries, checking, kept) {
+    const has = installs(root);
+    const from = join(root, 'node_modules', packageOf('ui'), 'dist', 'ui');
+    const said = [];
+    if (!existsSync(from)) {
+        return [
+            `this app declares an interface and ${packageOf('ui')} is not installed, so there is nothing to emit it from. ` +
+                `Install it and run \`thread attach ${packageOf('ui')}\` again.`,
+        ];
+    }
+    const seen = new Set();
+    const walk = (at) => {
+        if (seen.has(at))
+            return;
+        seen.add(at);
+        const file = join(from, at);
+        if (!existsSync(file)) {
+            said.push(`${at} is part of the interface this app emits, and the installed ${packageOf('ui')} does not hold it. ` +
+                'Upgrade the framework packages and run this again.');
+            return;
+        }
+        const text = readFileSync(file, 'utf8');
+        const where = `${COMPILED}/ui/${at}`;
+        kept.add(where);
+        const to = join(root, where);
+        if (checking) {
+            if (!existsSync(to) || readFileSync(to, 'utf8') !== text) {
+                said.push(`${where} is not what this app emits from ${packageOf('ui')}. An emitted file that differs from ` +
+                    'its source is a hand edit wearing a generated name. Run `thread compositions` and commit what it writes.');
+            }
+        }
+        else {
+            writeFileSync(to, text, 'utf8');
+        }
+        for (const one of text.matchAll(REACHED)) {
+            const named = one[2] ?? '';
+            if (named.startsWith('.')) {
+                const next = slashed(join(dirname(at), named));
+                if (next.startsWith('..')) {
+                    said.push(`${at} reaches \`${named}\`, which is outside the interface this app emits.`);
+                    continue;
+                }
+                walk(next);
+                continue;
+            }
+            if (one[1] !== undefined)
+                continue;
+            if (!named.startsWith(`${ORG}/`)) {
+                const held = packaging(named);
+                if (NODE.test(named) || has.has(held))
+                    continue;
+                said.push(`${at} reaches ${held}, and this app installs nothing by that name. An emitted interface brings ` +
+                    `what it reaches with it, so ${held} has to arrive when ` +
+                    `thread attach ${packageOf('ui')} runs.`);
+                continue;
+            }
+            said.push(`${at} reaches \`${named}\`, so emitting it would leave this app importing the framework while it runs. ` +
+                'It reaches what is emitted beside it, or nothing of this framework at all.');
+        }
+    };
+    for (const one of entries)
+        walk(one);
+    return said;
+}
+export function stale(root, kept, checking) {
+    const said = [];
+    const walk = (at) => {
+        const where = join(root, at);
+        if (!existsSync(where))
+            return;
+        for (const each of readdirSync(where, { withFileTypes: true })) {
+            const path = `${at}/${each.name}`;
+            if (each.isDirectory()) {
+                walk(path);
+                continue;
+            }
+            if (kept.has(path))
+                continue;
+            if (checking) {
+                said.push(`${path} sits under ${COMPILED} and nothing declares what it was written from any more. ` +
+                    'Run `thread compositions` and it goes.');
+                continue;
+            }
+            rmSync(join(root, path), { force: true });
+        }
+    };
+    walk(COMPILED);
+    return said;
+}
+export function handing(at, text) {
+    const found = [];
+    for (const one of text.matchAll(CLAUSE)) {
+        for (const name of (one[1] ?? '').matchAll(WORD)) {
+            const held = name[1];
+            if (held === undefined || NOT_A_NAME.has(held))
+                continue;
+            const why = REFUSED[held];
+            if (why === undefined)
+                continue;
+            found.push(`${at} imports \`${held}\`, and ${why}.`);
+        }
+    }
+    if (/\bfetch\s*\(/.test(text)) {
+        found.push(`${at} calls \`fetch\`, and nothing here reaches the network by hand. A screen names the reads it ` +
+            'binds in its own views list, and the framework runs each one.');
+    }
+    return found;
+}
+export function undeclared(tree, rows) {
     const elements = new Set();
     const declared = new Set();
     for (const [file, exported] of [
@@ -240,7 +438,7 @@ export async function undeclared(tree, rows) {
         const where = inTree(tree, file);
         if (!existsSync(where))
             continue;
-        const sheet = (await import(__rewriteRelativeImportExtension(pathToFileURL(where).href)));
+        const sheet = valuesIn(readFileSync(where));
         for (const row of sheet[exported]?.declares ?? []) {
             if (exported === 'ELEMENT')
                 elements.add(row.id);
@@ -253,7 +451,9 @@ export async function undeclared(tree, rows) {
         const file = join(tree.at, row.at);
         if (!existsSync(file))
             continue;
-        for (const one of reaching(row.at, readFileSync(file, 'utf8'), elements, declared)) {
+        const text = readFileSync(file, 'utf8');
+        found.push(...handing(row.at, text));
+        for (const one of reaching(row.at, text, elements, declared)) {
             found.push(`${row.at} imports \`${one}\`, which this app declares nothing by. A composition reaches ` +
                 'declared elements, other declared compositions, and the door — everything else is a thing ' +
                 'nothing wrote down. Declare it, or take it out and write the body through `thread create`.');
@@ -265,8 +465,8 @@ function starter(row) {
     const name = nameOf(row.at);
     return `'use client'
 
-import { Box } from './elements/box.tsx'
-import { composition } from './wrappers.tsx'
+import { Box } from '${HOME}/elements/box'
+import { composition } from '${HOME}/wrappers'
 
 export const ${name} = composition('${name}', () => <Box.card />)
 `;
@@ -274,26 +474,50 @@ export const ${name} = composition('${name}', () => <Box.card />)
 export function seeds(rows, held) {
     return rows.filter((row) => !held(row.at)).map((row) => ({ path: row.at, content: starter(row) }));
 }
-async function run() {
+function run() {
     const tree = findTree();
     const at = inTree(tree, 'compositions.ts');
     if (!existsSync(at)) {
         stdout.write(`thread: this tree has no ${tree.name}/${basename(at)}, so it declares no composition and there is nothing to seed or check.\n`);
         return 0;
     }
-    const held = (await import(__rewriteRelativeImportExtension(pathToFileURL(at).href)));
+    const held = valuesIn(readFileSync(at));
     if (held.COMPOSITION === undefined) {
         stdout.write(`thread: ${tree.name}/compositions.ts exports no \`COMPOSITION\`, so nothing declares a composition here.\n`);
         return 1;
     }
     const rows = held.COMPOSITION.declares ?? [];
+    const checking = argv.includes('--check');
     const made = seeds(rows, (where) => existsSync(join(tree.at, where)));
-    for (const one of made) {
-        mkdirSync(dirname(join(tree.at, one.path)), { recursive: true });
-        writeFileSync(join(tree.at, one.path), one.content, 'utf8');
-        stdout.write(`thread: seeded ${one.path}\n`);
+    const unseeded = made[0];
+    if (checking && unseeded !== undefined) {
+        stdout.write(`thread: ${unseeded.path} is declared and the file is not there yet. A row names a file, and ` +
+            '`--check` never writes one — run `thread compositions` and commit what it seeds.\n');
+        return 1;
+    }
+    if (!checking) {
+        for (const one of made) {
+            writeFileSync(join(tree.at, one.path), one.content, 'utf8');
+            stdout.write(`thread: seeded ${one.path}\n`);
+        }
     }
-    const loose = await undeclared(tree, rows);
+    const parts = sheetOf(tree, 'elements.ts', 'ELEMENT', 'ELEMENTS');
+    const shipped = `node_modules/${packageOf('ui')}/dist/ui/`;
+    const entries = [
+        ...RUNTIME,
+        ...parts.flatMap((one) => (one.at ?? '').startsWith(shipped) ? [(one.at ?? '').slice(shipped.length).replace(/\.js$/, '.tsx')] : []),
+    ];
+    const kept = new Set();
+    for (const one of sheetOf(tree, 'screens.ts', 'SCREEN', 'SCREENS')) {
+        if (one.at !== undefined && one.at !== '')
+            kept.add(compiledAt(one.at));
+    }
+    const found = [
+        ...undeclared(tree, rows),
+        ...emitting(tree.at, entries, checking, kept),
+        ...settled(tree.at, rows, checking, 'thread compositions', kept),
+    ];
+    const loose = [...found, ...(found.length === 0 ? stale(tree.at, kept, checking) : [])];
     for (const one of loose)
         stdout.write(`thread: ${one}\n`);
     stdout.write(`thread: ${String(rows.length)} composition(s) declared, ${String(made.length)} seeded, ` +
@@ -302,4 +526,4 @@ async function run() {
     return loose.length === 0 ? 0 : 1;
 }
 if (invoked(import.meta.url))
-    exit(await run());
+    exit(run());