@prestack/thread 0.0.1

package/dist/knowledge/generators/docsgen.js

@@ -0,0 +1,145 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { argv, stderr, stdout } from 'node:process';
+import { exit } from "../../core/invoked.js";
+import { ROOT, descend } from "../../core/descend.js";
+import { forbids, runChecker } from "../../core/finding.js";
+const AT = 'docs.md';
+const CHECKING = argv.includes('--check');
+const SHOWING = argv.includes('--show');
+const TRIALS_AT = 'operations/_trials.json';
+function refuse(why) {
+    stderr.write(`docs: ${why}\n`);
+    exit(1);
+}
+const text = (value) => (typeof value === 'string' && value !== '' ? value : undefined);
+const said = (one) => text(one.describes) ?? '_no `describes` — this row says nothing about itself._';
+const pass = await descend();
+const stopped = [...pass.broken, ...pass.findings].filter(forbids)[0];
+if (stopped !== undefined) {
+    refuse('the descent is broken, so this would state a tree that is only partly known and read afterwards as the whole of it — ' +
+        `${stopped.detail} (${stopped.file ?? ''})`);
+}
+const PATH = resolve(ROOT, AT);
+const proven = () => {
+    const found = new Map();
+    const at = resolve(ROOT, TRIALS_AT);
+    if (!existsSync(at))
+        return found;
+    try {
+        const held = JSON.parse(readFileSync(at, 'utf8'));
+        for (const one of held) {
+            const which = text(one.operation);
+            if (which === undefined)
+                continue;
+            found.set(which, (found.get(which) ?? 0) + 1);
+        }
+    }
+    catch {
+        return found;
+    }
+    return found;
+};
+function grouped(held) {
+    const found = new Map();
+    for (const threadings of held.threaded.values()) {
+        for (const one of threadings) {
+            const kept = found.get(one.by) ?? [];
+            kept.push({ list: one.list, row: one.row });
+            found.set(one.by, kept);
+        }
+    }
+    return found;
+}
+const under = grouped(pass);
+const trials = proven();
+const named = (one) => text(one.id) ?? text(one.at) ?? '(unnamed)';
+const line = (one) => {
+    const row = one.row;
+    const where = text(row.at);
+    const by = text(row.by);
+    const runs = text(row.runs);
+    const ran = trials.get(named(row));
+    return [
+        `- **${named(row)}**${where === undefined ? '' : ` — \`${where}\``}`,
+        `  ${said(row)}`,
+        ...(by === undefined ? [] : [`  Written by \`${by}\`${runs === undefined ? '' : `, checked by \`${runs}\``}.`]),
+        ...((row.requires ?? []).length === 0 ? [] : [`  Requires ${(row.requires ?? []).map((each) => `\`${each}\``).join(', ')}.`]),
+        ...((row.takes ?? []).length === 0 ? [] : [`  Takes ${(row.takes ?? []).map((each) => `\`${each}\``).join(', ')}.`]),
+        ...(ran === undefined ? [] : [`  Proved by ${String(ran)} recorded run(s).`]),
+    ].join('\n');
+};
+const words = [...pass.coined].sort(([one], [two]) => (one < two ? -1 : 1));
+const commands = [...pass.derived.values(), ...[...under.values()].flat().map((one) => one.row)]
+    .filter((one) => text(one.by)?.startsWith('thread ') === true)
+    .reduce((found, one) => found.set(text(one.by), one), new Map());
+const sections = [...under.keys()].sort();
+const page = [
+    '<!-- GENERATED by `thread docs` from what this app declares — do not edit by hand.',
+    '     Every sentence here is the `describes` on a row. To change one, change the row. -->',
+    '',
+    '# What this app declares',
+    '',
+    `${String(pass.declarations)} declaration(s) over ${String(pass.rows)} row(s), read from the tree by the same descent`,
+    'every generator here reads. This page is rewritten whenever a package is attached and whenever a',
+    'command writes a row, so a section that is out of date is a bug rather than a chore.',
+    '',
+    '## Commands',
+    '',
+    ...(commands.size === 0
+        ? ['_nothing here declares a command yet._']
+        : [...commands.entries()]
+            .sort(([one], [two]) => (one < two ? -1 : 1))
+            .map(([word, one]) => `- \`${word}\` — ${said(one)}`)),
+    '',
+    ...sections.flatMap((node) => {
+        const own = pass.stated.get(node) ?? pass.derived.get(node);
+        const kept = under.get(node) ?? [];
+        const declares = kept.filter((one) => one.list === 'declares');
+        const derives = kept.filter((one) => one.list === 'derives');
+        const seeds = kept.filter((one) => one.list === 'seeds');
+        return [
+            `## ${node}`,
+            '',
+            ...(own === undefined ? [] : [said(own), '']),
+            ...(declares.length === 0 ? [] : ['### What it declares', '', ...declares.map(line), '']),
+            ...(derives.length === 0 ? [] : ['### What it derives', '', ...derives.map(line), '']),
+            ...(seeds.length === 0 ? [] : ['### What it seeds', '', ...seeds.map(line), '']),
+        ];
+    }),
+    '## Every word this app coins',
+    '',
+    ...(words.length === 0
+        ? ['_nothing here coins a word yet._']
+        : words.map(([word, held]) => `- **${word}** — ${held.said[0] ?? '_no meaning stated_'}`)),
+    '',
+].join('\n');
+if (SHOWING) {
+    stdout.write(page);
+    exit(0);
+}
+if (CHECKING) {
+    const findings = [];
+    const held = existsSync(PATH) ? readFileSync(PATH, 'utf8') : undefined;
+    if (held === undefined) {
+        findings.push({
+            detail: `${AT} is not there, and this app declares it`,
+            instead: `Run \`thread docs\`. Nothing writes this page by hand — it is what the tree says, read back.`,
+            file: AT,
+            severity: 'forbidden',
+        });
+    }
+    else if (held !== page) {
+        findings.push({
+            detail: `${AT} states something other than what this tree declares`,
+            instead: `Run \`thread docs\`. A sentence here is the \`describes\` on a row — to change one, change the row.`,
+            file: AT,
+            severity: 'forbidden',
+        });
+    }
+    runChecker('docs', findings, `${AT} states every row this app declares, ${String(pass.rows)} of them`);
+    exit(findings.length === 0 ? 0 : 1);
+}
+mkdirSync(dirname(PATH), { recursive: true });
+writeFileSync(PATH, page, 'utf8');
+stdout.write(`docs: wrote ${AT} — ${String(sections.length)} node(s), ${String(commands.size)} command(s), ${String(words.length)} word(s).\n`);

package/dist/knowledge/generators/glossary.d.ts

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

package/dist/knowledge/generators/glossary.js

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { argv, stderr, stdout } from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { exit } from "../../core/invoked.js";
+import { ROOT, descend } from "../../core/descend.js";
+import { forbids, runChecker } from "../../core/finding.js";
+function refuse(why) {
+    stderr.write(`glossary: ${why}\n`);
+    exit(1);
+}
+function text(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function quote(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n')}'`;
+}
+const pass = await descend();
+const stopped = [...pass.broken, ...pass.findings].filter(forbids)[0];
+if (stopped !== undefined) {
+    refuse(`the descent is broken, so the harvest is short and writing it would delete words that exist — ${stopped.detail} (${stopped.file ?? ''})`);
+}
+const SELF = pass.derived.get('glossary');
+if (SELF === undefined) {
+    refuse('nothing in the tree derives `glossary`, so this script has no declaration saying what it writes or where');
+}
+const AT = text(SELF.at) ?? refuse('the `glossary` row names no `at`, so where the glossary lands is unstated');
+const PATH = resolve(ROOT, AT);
+const toward = relative(dirname(PATH), fileURLToPath(new URL('../glossary.ts', import.meta.url))).split('\\').join('/');
+const shape = toward.startsWith('.') ? toward : `./${toward}`;
+const words = [...pass.coined];
+function row([word, held]) {
+    const from = held.from.map(quote).join(', ');
+    return `  { id: ${quote(word)}, under: ${quote(held.under)}, from: [${from}], means: ${quote(held.said[0] ?? '')} },`;
+}
+const content = `import type { Glossary } from '${shape}'
+
+export const GLOSSARY: Glossary[] = [
+${words.map(row).join('\n')}
+]
+`;
+if (argv.includes('--check')) {
+    const findings = [];
+    const current = existsSync(PATH) ? readFileSync(PATH, 'utf8') : '';
+    if (current !== content) {
+        findings.push({
+            file: AT,
+            detail: 'is not what the slopnator from the root derives',
+            instead: `run \`${text(SELF.by) ?? 'thread glossary'}\` and commit what it writes. Never edit this file — a meaning lives on the row that coins the word, and an edit here is a change to that row somebody skipped`,
+        });
+    }
+    runChecker('glossary', findings, `${String(words.length)} word(s) coined over ${String(pass.declarations)} declaration(s)`);
+    exit(findings.length === 0 ? 0 : 1);
+}
+writeFileSync(PATH, content);
+stdout.write(`glossary: wrote ${AT} — ${String(words.length)} word(s).\n`);

package/dist/knowledge/generators/skills.d.ts

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

package/dist/knowledge/generators/skills.js

@@ -0,0 +1,222 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { argv, cwd, env, execPath, stdout } from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { SKILLS_AT, declared, nouns, skillOf } from "../../core/asking.js";
+import { generators } from "../../core/chain.js";
+import { TREE } from "../../core/descend.js";
+import { LOADER, exit, invoked } from "../../core/invoked.js";
+import { ORGANISATION, named } from "../../core/scope.js";
+import { findTree } from "../../core/tree.js";
+const WHERE = SKILLS_AT;
+const RECEIPT_LINE = /^[a-z]+: receipt .*$/gm;
+const NONCE = /--receipt [0-9a-f]{6,}/g;
+const CRLF = /\r\n/g;
+const META = fileURLToPath(new URL('../../core/generators/meta.ts', import.meta.url));
+const fileFor = (noun) => skillOf(noun);
+async function offering(tree) {
+    const answers = relative(tree.at, META).split('\\').join('/');
+    const found = new Map(nouns(await generators(tree)));
+    found.set('meta', answers);
+    for (const noun of (await declared(tree)).keys())
+        if (!found.has(noun))
+            found.set(noun, answers);
+    return found;
+}
+function printed(root, at, noun) {
+    if (at === '')
+        return { refused: `nothing in this tree is written by \`thread create ${noun}\``, body: '' };
+    const ran = spawnSync(execPath, [...LOADER, join(root, at)], {
+        cwd: root,
+        encoding: 'utf8',
+        env: { ...env, THREAD_NOUN: noun },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const body = String(ran.stdout ?? '').replace(CRLF, '\n').replace(RECEIPT_LINE, '').trimEnd();
+    const said = String(ran.stderr ?? '').replace(CRLF, '\n').trim().split('\n')[0] ?? '';
+    return { refused: body === '' ? said || 'it printed nothing' : '', body };
+}
+function skill(noun, body) {
+    return [
+        `# ${noun}`,
+        '',
+        `Everything \`npx thread create ${noun}\` knows, written out by \`npx thread skills\`.`,
+        '',
+        '**Do not edit this file.** It is derived from the tree, so an edit here is reverted the next',
+        'time the command runs, and `npx thread skills --check` fails until it is. If something below is',
+        'wrong or missing, the command that printed it is what to change.',
+        '',
+        `**Read this before you declare a ${noun}.** What follows is what already exists. The reason it`,
+        'exists is that things get built twice by people who did not look — thirteen elements were once',
+        'declared in one app that every one of them already shipped, and the cost was two days of fixes',
+        'landing on a page nobody was looking at. Open what it names before you add to it.',
+        '',
+        'When you are ready to write, run the command yourself for a live receipt. The one printed here',
+        'has been removed on purpose: a receipt is spent by one run and goes stale the moment its sheet',
+        'changes, so a copy kept in a file is always the wrong one.',
+        '',
+        '```',
+        body.replace(NONCE, '--receipt <receipt>'),
+        '```',
+        '',
+    ].join('\n');
+}
+const SHEET = `${TREE}_generated/skills.ts`;
+function sheet(files) {
+    const rows = files.map((at) => {
+        const noun = at.slice(WHERE.length + 1, -'.md'.length);
+        return [
+            '    {',
+            `      id: 'skill-${noun}',`,
+            `      at: '${at}',`,
+            `      describes: 'What \`thread create ${noun}\` teaches: the ${noun}s this tree already has, with the sentence each one states, and the rules for declaring another. Written from what that command prints about itself, so the skill and the command cannot disagree.',`,
+            '      version: 1,',
+            "      by: 'thread skills',",
+            "      runs: 'thread skills --check',",
+            '    },',
+        ].join('\n');
+    });
+    return [
+        "import type { Threaded } from '../../thread/core/thread.ts'",
+        '',
+        'export const SKILLS: Threaded = {',
+        "  id: 'skills',",
+        `  at: '${SHEET}',`,
+        "  describes: 'One row per skill `thread skills` writes, so every `skills/<noun>.md` is declared by the command that wrote it instead of being refused as a file nothing named. It sits beside the files it names because the nouns are not known until the tree is read, and a list somebody keeps by hand would go stale the first time a package brings a new maker.',",
+        '  version: 1,',
+        '  derives: [',
+        ...rows,
+        '  ],',
+        '}',
+        '',
+    ].join('\n');
+}
+const HERE = () => cwd();
+const COINS = /by:\s*'thread create ([a-z][a-z0-9-]*)'/g;
+const ANSWERS_AT = new RegExp(`at:\\s*'node_modules/${ORGANISATION}/[^/]+/(dist/[^']+)'`, 'g');
+function ownMakers(root) {
+    const found = new Map();
+    let names;
+    try {
+        names = readdirSync(join(root, 'src'), { recursive: true });
+    }
+    catch {
+        return found;
+    }
+    for (const one of names) {
+        const path = String(one).split('\\').join('/');
+        if (!path.endsWith('attach.ts'))
+            continue;
+        let text;
+        try {
+            text = readFileSync(join(root, 'src', String(one)), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const row of text.split(/\{\s*$/m)) {
+            const noun = [...row.matchAll(COINS)].at(0)?.[1];
+            const at = [...row.matchAll(ANSWERS_AT)].at(-1)?.[1];
+            if (noun === undefined || at === undefined || found.has(noun))
+                continue;
+            found.set(noun, join(root, at));
+        }
+    }
+    return found;
+}
+function printedOwn(at) {
+    const ran = spawnSync(execPath, ['--experimental-strip-types', at, '--own'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const body = String(ran.stdout ?? '').replace(CRLF, '\n').replace(RECEIPT_LINE, '').trimEnd();
+    const said = String(ran.stderr ?? '').replace(CRLF, '\n').trim().split('\n')[0] ?? '';
+    return { refused: ran.status === 0 && body !== '' ? '' : said || 'it printed nothing', body };
+}
+async function run() {
+    const own = argv.includes('--own');
+    const checking = argv.includes('--check');
+    const root = own ? HERE() : findTree().at;
+    const mine = own ? ownMakers(root) : new Map();
+    const theirs = own ? new Map() : await offering(findTree());
+    const known = [...(own ? mine : theirs).keys()].sort();
+    if (known.length === 0) {
+        stdout.write(own
+            ? 'skills: this package ships no maker, so it coins no noun and has no skill to write.\n'
+            : 'skills: this tree declares no `create` command yet, so there is no method to write down. ' +
+                `Attach a package that brings one — \`npx thread attach ${named('ui')}\` — and run this again.\n`);
+        return 0;
+    }
+    const wanted = new Map();
+    const skipped = [];
+    for (const noun of known) {
+        const { refused, body } = own ? printedOwn(mine.get(noun) ?? '') : printed(root, theirs.get(noun) ?? '', noun);
+        if (refused !== '') {
+            skipped.push(`  ${noun} — ${refused}`);
+            continue;
+        }
+        wanted.set(fileFor(noun), skill(noun, body));
+    }
+    if (wanted.size === 0) {
+        stdout.write(`skills: every \`create\` this tree declares refused, so there is no method to write down yet:\n${skipped.join('\n')}\n`);
+        return 1;
+    }
+    const made = wanted.size;
+    const sheetAt = own ? '' : SHEET;
+    if (sheetAt !== '')
+        wanted.set(sheetAt, sheet([...wanted.keys()].sort()));
+    const held = new Map();
+    try {
+        for (const name of readdirSync(join(root, WHERE))) {
+            if (!name.endsWith('.md'))
+                continue;
+            held.set(join(WHERE, name), readFileSync(join(root, WHERE, name), 'utf8').replace(CRLF, '\n'));
+        }
+    }
+    catch {
+    }
+    if (sheetAt !== '') {
+        try {
+            held.set(sheetAt, readFileSync(join(root, sheetAt), 'utf8').replace(CRLF, '\n'));
+        }
+        catch {
+        }
+    }
+    const stale = [...held.keys()].filter((one) => !wanted.has(one)).sort();
+    const differs = [...wanted.entries()].filter(([one, text]) => held.get(one) !== text).map(([one]) => one).sort();
+    if (checking) {
+        if (stale.length === 0 && differs.length === 0) {
+            stdout.write(`skills: ${String(made)} skill(s), each matching what its own command prints` +
+                (sheetAt === '' ? '' : `, and each declared by a row in ${sheetAt}`) +
+                '.\n');
+            return 0;
+        }
+        for (const one of differs) {
+            stdout.write(`skills: ${one} is not what \`npx thread skills\` writes. A skill is derived from the command ` +
+                'it describes, so an edit here is a second statement of the method and will drift from the ' +
+                'first. Change the command, then run `npx thread skills`.\n');
+        }
+        for (const one of stale) {
+            stdout.write(`skills: ${one} names a \`create\` this tree no longer declares, so it teaches a command that ` +
+                'will refuse. Run `npx thread skills`.\n');
+        }
+        return 1;
+    }
+    for (const [one, text] of wanted) {
+        mkdirSync(dirname(join(root, one)), { recursive: true });
+        writeFileSync(join(root, one), text, 'utf8');
+    }
+    for (const one of stale)
+        rmSync(join(root, one), { force: true });
+    stdout.write(`skills: wrote ${String(made)} skill(s) into ${WHERE}/` +
+        (sheetAt === '' ? '' : `, and the ${String(made)} row(s) declaring them into ${sheetAt}`) +
+        (stale.length === 0
+            ? ''
+            : `, and removed ${String(stale.length)} naming a command this tree no longer has`) +
+        '.\n' +
+        (skipped.length === 0 ? '' : `skills: no method to keep yet for:\n${skipped.join('\n')}\n`));
+    return 0;
+}
+if (invoked(import.meta.url))
+    exit(await run());

package/dist/knowledge/glossary.d.ts

@@ -0,0 +1,6 @@
+export interface Glossary {
+    readonly id: string;
+    readonly under: string;
+    readonly from: readonly string[];
+    readonly means: string;
+}

package/dist/knowledge/glossary.js

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

package/dist/operations/access.d.ts

@@ -0,0 +1,27 @@
+import type { Actor } from '../core/actor.ts';
+import { type Condition } from '../core/condition.ts';
+import type { Member } from '../core/thread.ts';
+export declare const PERMITS_AT = "src/_generated/permits.ts";
+export declare function declaredWords(entities: readonly {
+    readonly holds: readonly {
+        readonly id: string;
+        readonly options?: readonly string[];
+    }[];
+    readonly actor?: {
+        readonly roles: string;
+        readonly entitlements?: string;
+    };
+}[], which: 'roles' | 'entitlements', everybody: string): readonly string[];
+export declare function undeclared(answered: string, offers: readonly string[], which: 'roles' | 'entitlements'): string | undefined;
+export interface Grant extends Member {
+    readonly may: readonly string[];
+    readonly on?: string;
+    readonly to?: {
+        readonly roles?: Actor['roles'];
+        readonly entitlements?: Actor['entitlements'];
+    };
+    readonly when?: Condition;
+}
+export declare function opensToEverybody(grants: readonly Grant[]): readonly Grant[];
+export declare function grantedTwice(grants: readonly Grant[]): readonly string[];
+export declare function unanswerable(grants: readonly Grant[]): readonly string[];

package/dist/operations/access.js

@@ -0,0 +1,61 @@
+import { mentionsActor, walkOperands } from "../core/condition.js";
+export const PERMITS_AT = 'src/_generated/permits.ts';
+export function declaredWords(entities, which, everybody) {
+    const found = entities.flatMap((one) => {
+        const at = one.actor?.[which];
+        return at === undefined ? [] : (one.holds.find((each) => each.id === at)?.options ?? []);
+    });
+    return [...new Set(which === 'roles' ? [everybody, ...found] : found)];
+}
+export function undeclared(answered, offers, which) {
+    const stray = answered
+        .split(',')
+        .map((one) => one.trim())
+        .filter((one) => one !== '' && !offers.includes(one));
+    if (stray.length === 0)
+        return undefined;
+    return (`this app declares no ${which === 'roles' ? 'role' : 'entitlement'} called ${stray.map((one) => `\`${one}\``).join(', ')} — ` +
+        (offers.length === 0
+            ? `it declares none at all. A ${which === 'roles' ? 'role' : 'entitlement'} is one of the words the value an ` +
+                'entity names as saying what a caller may do is held to. Declare them with `thread create entity edit` — ' +
+                'name that value, give it the `choice` format, and state its options'
+            : `it declares ${offers.map((one) => `\`${one}\``).join(', ')}`));
+}
+export function opensToEverybody(grants) {
+    return grants.filter((one) => one.to === undefined && (one.when === undefined || !mentionsActor(one.when)));
+}
+export function grantedTwice(grants) {
+    const seen = new Set();
+    const twice = new Set();
+    for (const one of grants) {
+        if (seen.has(one.id))
+            twice.add(one.id);
+        seen.add(one.id);
+    }
+    return [...twice].sort();
+}
+function operandsOf(one) {
+    if (one.when === undefined)
+        return [];
+    const found = [];
+    walkOperands(one.when, (each) => {
+        if ('agg' in each)
+            found.push('agg');
+        if ('was' in each)
+            found.push('was');
+        if ('outer' in each)
+            found.push('outer');
+    });
+    return found;
+}
+export function unanswerable(grants) {
+    return grants.flatMap((one) => {
+        const held = [...new Set(operandsOf(one))];
+        if (held.length === 0)
+            return [];
+        const why = held.includes('agg')
+            ? 'it counts other rows, and a gate is asked about the one in front of it. Put the aggregate in an invariant on the entity, where it runs against the rows themselves'
+            : 'it reads a value as it was before the write, and at the moment this is asked the write has not happened. Only an invariant, which runs on the write itself, can see a before';
+        return [`\`${one.id}\` states a condition this gate cannot answer — ${why}`];
+    });
+}

package/dist/operations/attach.d.ts

@@ -0,0 +1,6 @@
+import type { Attaching } from '../core/attach.ts';
+import type { Threaded } from '../core/thread.ts';
+export declare const TAKES = "What one operation needs before it will run: the shape of its input, what it is expected to cost, and who is allowed to ask for it. Written once when the operation is created, then yours to change.";
+export declare const WOVEN = "The operation written out as one function. `thread compile` builds it from the steps declared for it, so nothing here is edited by hand \u2014 anything added here is gone the next time it is compiled.";
+export declare const said: (one: Threaded, pad: string) => string;
+export declare const ATTACH: Attaching;