@prestack/thread 0.0.1 → 0.0.3

package/dist/core/chain.ts

@@ -0,0 +1,148 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { execPath } from 'node:process'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+import type { Row } from './descend.ts'
+import { findTree, type Tree } from './tree.ts'
+
+const STATING = 'derivation.ts'
+
+export async function generators(tree: Tree = findTree()): Promise<readonly Row[]> {
+  if (!existsSync(tree.dir)) return []
+
+  const sheets = readdirSync(tree.dir)
+    .filter((one) => one.endsWith('.ts'))
+    .sort((one, two) => (one === STATING ? -1 : two === STATING ? 1 : one < two ? -1 : one > two ? 1 : 0))
+
+  const found: Row[] = []
+  for (const name of sheets) {
+    const sheet = join(tree.dir, name)
+    try {
+      const held = (await import(pathToFileURL(sheet).href)) as { GENERATORS?: readonly Row[] }
+      found.push(...(held.GENERATORS ?? []))
+    } catch (thrown) {
+      throw new Error(
+        `${sheet} is one of the sheets where this tree states the commands it offers, and reading it threw: ` +
+          `${thrown instanceof Error ? thrown.message : String(thrown)}. A tree whose generators cannot be read ` +
+          'offers exactly what a tree declaring none offers, so everything derived from your declarations would be ' +
+          'left stale by a command reporting that it had finished. Fix that file.',
+      )
+    }
+  }
+  return found
+}
+
+export const offers = (all: readonly Row[]): ReadonlySet<string> =>
+  new Set(all.map((one) => (typeof one.by === 'string' ? one.by : '')).filter((one) => one !== ''))
+
+const ROUNDS = 4
+
+const word = (held: unknown): string => (typeof held === 'string' ? held.trim() : '')
+
+const FROM_SOURCE = import.meta.url.endsWith('.ts')
+
+const RUNNER = fileURLToPath(new URL(FROM_SOURCE ? './round.ts' : './round.js', import.meta.url))
+
+const LOADER: readonly string[] = FROM_SOURCE ? ['--import', 'tsx'] : []
+
+export const RAN = 'round: ran'
+export const REFUSED_BY = 'round: refused'
+
+export function batched(
+  at: string,
+  commands: readonly string[],
+  within?: number,
+): readonly { readonly command: string; readonly ok: boolean; readonly said: string }[] {
+  if (commands.length === 0) return []
+
+  const out = spawnSync(execPath, [...LOADER, RUNNER, ...new Set(commands)], {
+    cwd: at,
+    encoding: 'utf8',
+    ...(within === undefined ? {} : { timeout: within, killSignal: 'SIGKILL' as const }),
+  })
+  const lines = `${out.stdout ?? ''}${out.stderr ?? ''}`.split('\n')
+
+  const found = new Map<string, { readonly command: string; readonly ok: boolean; readonly said: string }>()
+  let held: string[] = []
+  for (const line of lines) {
+    const mark = line.startsWith(RAN) ? RAN : line.startsWith(REFUSED_BY) ? REFUSED_BY : undefined
+    if (mark === undefined) {
+      held.push(line)
+      continue
+    }
+    const command = line.slice(mark.length).trim()
+    found.set(command, { command, ok: mark === RAN, said: held.join('\n').trim() })
+    held = []
+  }
+
+  const orphaned = held.join('\n').trim()
+  const died =
+    out.error !== undefined
+      ? ` The runner itself failed to start or was stopped: ${out.error.message}.`
+      : out.signal !== null && out.signal !== undefined
+        ? ` The runner was killed by ${out.signal}, so everything after the command it was running is unreported rather than refused.`
+        : found.size === 0 && out.status !== 0
+          ? ` The runner exited ${String(out.status)} having reported nothing, so it died before the first command finished.`
+          : ''
+  let firstUnreached = true
+  return commands.map((one) => {
+    const has = found.get(one)
+    if (has !== undefined) return has
+    const why = `settle: the runner never reported on \`${one}\`, so it was not run and is not settled.${died}`
+    const said = firstUnreached && orphaned !== '' ? `${orphaned}\n${why}` : why
+    firstUnreached = false
+    return { command: one, ok: false, said }
+  })
+}
+
+const WITHIN = 300_000
+
+function batch(
+  at: string,
+  commands: readonly string[],
+): { readonly said: readonly string[]; readonly refused: readonly string[] } {
+  const all = batched(at, commands, WITHIN)
+  return {
+    said: all.map((one) => one.said).filter((one) => one !== ''),
+    refused: all.filter((one) => !one.ok).map((one) => one.command),
+  }
+}
+
+export function settling(
+  at: string,
+  all: readonly Row[],
+  skip: readonly string[] = [],
+): { readonly ran: readonly string[]; readonly unsettled: readonly string[]; readonly rounds: number } {
+  const mine = all
+    .filter((one) => word(one.by) !== '' && word(one.runs) !== '' && word(one.by) !== word(one.runs) && !skip.includes(word(one.by)))
+    .filter((one, order, every) => every.findIndex((each) => word(each.by) === word(one.by)) === order)
+
+  const ran: string[] = []
+  let round = 0
+  let before: readonly string[] | undefined
+
+  while (round < ROUNDS) {
+    round += 1
+
+    const asking = round === 1 ? mine.map((one) => word(one.runs)) : batch(at, mine.map((one) => word(one.runs))).refused
+    const unhappy = mine.filter((one) => asking.includes(word(one.runs)))
+    if (unhappy.length === 0) return { ran, unsettled: [], rounds: round }
+
+    const still = unhappy.map((one) => word(one.runs))
+    const seen = before
+    if (seen !== undefined && still.length === seen.length && still.every((one) => seen.includes(one))) {
+      return { ran, unsettled: still, rounds: round }
+    }
+    before = still
+
+    const writing = batch(at, unhappy.map((one) => word(one.by)))
+    for (const said of writing.said) ran.push(said)
+    const refused = unhappy.filter((one) => writing.refused.includes(word(one.by))).map((one) => word(one.runs))
+
+    if (refused.length === unhappy.length) return { ran, unsettled: refused, rounds: round }
+  }
+
+  return { ran, unsettled: batch(at, mine.map((one) => word(one.runs))).refused, rounds: round }
+}

package/dist/core/cli.js

@@ -59,13 +59,48 @@ const commanded = (word, one) => {
     const opens = `Declares ${/^[aeiou]/.test(word) ? 'an' : 'a'} ${word}`;
     return meaning === '' ? `${opens}.` : `${opens} — ${meaning.slice(0, 1).toLowerCase()}${meaning.slice(1)}.`;
 };
+const fielded = (word, one) => {
+    if (one === undefined || one.fields.length === 0)
+        return [];
+    const room = Math.max(...one.fields.map((each) => each.name.length));
+    const kind = (each) => each.list ? 'a list' : each.map ? 'a table' : each.boolean ? 'yes or no' : each.worded ? 'a word' : 'a value';
+    const base = ['id', 'at', 'describes', 'version'];
+    const order = (each) => {
+        const held = base.indexOf(each.name);
+        return held === -1 ? (each.required ? 100 : 200) : held;
+    };
+    return [
+        '',
+        `every ${word} row states these:`,
+        '',
+        ...[...one.fields].sort((a, b) => order(a) - order(b) || (a.name < b.name ? -1 : 1)).flatMap((each) => columned(each.name, `${each.required ? '' : 'optional, '}${kind(each)}${each.guide === '' ? '' : `. ${each.guide}`}`, room + 2)),
+    ];
+};
+const doing = (word, holds, answers, at) => {
+    const held = [
+        ...(holds === undefined
+            ? []
+            : [
+                ...columned(`${TYPED} create ${word}`, 'What it asks for, and everything already declared.', 34),
+                ...columned(`${TYPED} create ${word} read <mark>`, 'One of them in full. It writes nothing.', 34),
+            ]),
+        ...(answers?.by === undefined
+            ? []
+            : [
+                ...columned(answers.by, first(answers.describes ?? ''), 34),
+                ...(answers.runs === undefined ? [] : columned(answers.runs, 'Proves it is still what its command writes.', 34)),
+            ]),
+        ...(at === undefined ? [] : columned(`${TYPED} read ${at}`, 'Prints the file itself.', 34)),
+    ];
+    return held.length === 0 ? [] : ['', 'to do something with it:', ...held];
+};
 const OWN = [
     {
         said: 'read <path>',
         describes: 'Print any file with line numbers, or list a directory. `--find <text>` searches every file in this tree. Reach for this first; `inspect <word>` reads rows instead, which is a different question.',
     },
-    { said: 'init', describes: 'Write the tree this app is declared in, and its manifest.' },
-    { said: 'attach <package>', describes: 'Take on what a package declares, and settle what that derives.' },
+    { said: 'init' },
+    { said: 'attach <package>' },
     { said: 'detach <package>', describes: 'Give a package back, withdrawing every row it put here.' },
     { said: 'create <noun>', describes: 'Declare a thing. Run it with no noun to see what this tree makes.' },
     { said: 'run <noun>', describes: 'Run a thing that was declared.' },
@@ -86,6 +121,54 @@ const OWN = [
         describes: 'Writes every derived file again from the rows, running each generator until a full pass changes nothing, and touches nothing you wrote. Run it when the package manifests fell out of step with the rows and pnpm refuses to start: it needs no pnpm in front of it, so `npx thread repair` in an app and `node --import tsx thread/core/cli.ts repair` in the framework repository both reach it.',
     },
 ];
+let COINED;
+const coining = () => {
+    const found = new Map();
+    try {
+        const pass = descend();
+        for (const [, threadings] of pass.threaded) {
+            for (const one of threadings) {
+                const id = one.row.id;
+                const says = one.row.describes;
+                if (typeof id === 'string' && typeof says === 'string' && says !== '' && !found.has(id))
+                    found.set(id, says);
+            }
+        }
+        for (const [id, row] of pass.stated) {
+            const says = row.describes;
+            if (typeof says === 'string' && says !== '' && !found.has(id))
+                found.set(id, says);
+        }
+    }
+    catch {
+        return found;
+    }
+    return found;
+};
+const coined = () => (COINED ??= coining());
+const verb = (one) => one.said.split(' ')[0] ?? one.said;
+const framework = () => OWN.map((one) => ({ said: one.said, describes: coined().get(verb(one)) ?? one.describes ?? '' }));
+const WORKS = [
+    'Everything this app is, it DECLARES — in `_threads/`, one row per thing. You never write those rows',
+    'by hand: `npx thread create <noun>` asks what it needs and writes one. Everything else is DERIVED',
+    'from them — the schema, the migrations, the routes, the docs — by generators that re-run themselves',
+    'whenever a row changes, so nothing has to be kept in step. `npx thread gate` refuses the tree if any',
+    'of it has drifted, and a build reads that refusal.',
+];
+const heading = (short) => [
+    ...framework().flatMap((one) => columned(one.said, short ? opening(one.describes) : one.describes)),
+    ...untold(),
+];
+const untold = () => {
+    const held = OWN.map(verb).filter((one) => !coined().has(one));
+    if (held.length === 0)
+        return [];
+    return [
+        '',
+        ...over(`${held.join(', ')} — no row coins these, so the sentence beside each is typed into this command rather ` +
+            `than read from the tree. \`${TYPED} create concept\` declares one, and this page reads it from there.`, '', 88),
+    ];
+};
 const WITHIN = '--in';
 function within(root, path) {
     const held = resolve(root, path);
@@ -464,9 +547,11 @@ async function listing() {
     stdout.write([
         `${TYPED} list`,
         '',
+        ...WORKS,
+        '',
         `every command this tree answers. These ${String(OWN.length)} are this framework's own and are here in every tree:`,
         '',
-        ...OWN.flatMap((one) => columned(one.said, one.describes)),
+        ...heading(false),
         ...(broke === ''
             ? []
             : [
@@ -540,7 +625,7 @@ async function helping(word) {
         outright = undefined;
         unread = thrown instanceof Error ? thrown.message : String(thrown);
     }
-    const own = OWN.find((one) => (one.said.split(' ')[0] ?? '') === word);
+    const own = framework().find((one) => verb(one) === word);
     const holds = told.get(word);
     const named = every.filter((one) => one.row.id === word);
     const answers = rows.find((one) => one.by === `thread ${word}` || one.by === `thread create ${word}` || one.by === `thread run ${word}`);
@@ -577,17 +662,9 @@ async function helping(word) {
                 holds.holds === 0
                     ? `  nothing is declared as one yet. They are listed in ${holds.at}`
                     : `  ${String(holds.holds)} ${holds.holds === 1 ? 'is' : 'are'} declared, listed in ${holds.at}`,
-                ...(holds.shape === undefined ? [] : [`  every ${word} states the same things, and this asks for each of them`]),
             ]),
-        '',
-        'to do something with it:',
-        ...(holds === undefined
-            ? []
-            : columned(`${TYPED} create ${word}`, 'What it asks for, and everything already declared.', 34).concat(columned(`${TYPED} create ${word} read <mark>`, 'One of them in full. It writes nothing.', 34))),
-        ...(answers?.by === undefined
-            ? []
-            : columned(answers.by, 'Runs it.', 34).concat(answers.runs === undefined ? [] : columned(answers.runs, 'Proves it is still what its command writes.', 34))),
-        ...(named.length === 0 ? [] : columned(`${TYPED} read ${named[0]?.at ?? ''}`, 'Prints the file itself.', 34)),
+        ...fielded(word, holds),
+        ...doing(word, holds, answers, named[0]?.at),
         '',
     ].join('\n'));
     return 0;
@@ -678,7 +755,7 @@ async function offered() {
         exit(1);
     }
 }
-const MINE = 'packages';
+const MINE = 'thread';
 const UNDER = 'generators';
 const MAKING = 'makers';
 function own(name, under = UNDER) {
@@ -687,7 +764,7 @@ function own(name, under = UNDER) {
         for (const entry of readdirSync(at, { withFileTypes: true })) {
             if (!entry.isDirectory() || entry.name === 'node_modules')
                 continue;
-            const made = join(at, entry.name, 'src', under, `${name}.ts`);
+            const made = join(at, entry.name, under, `${name}.ts`);
             try {
                 readFileSync(made);
                 found = made;
@@ -1345,7 +1422,7 @@ async function attachable(verb) {
         return verb === 'attach'
             ? [
                 `nothing to attach — no \`${named('*')}\` package is installed here beyond the CLI itself.`,
-                `Install one with \`npm install ${named('<name>')}\` and run this again to see it listed.`,
+                `Install one with \`npm install -D ${named('<name>')}\` — this framework is scaffolding, so it goes in \`devDependencies\` and a host installs none of it — then run this again to see it listed.`,
             ]
             : [
                 'nothing to detach — this tree has taken on no package yet.',
@@ -1453,9 +1530,11 @@ async function run(name) {
         stderr.write([
             `${TYPED} <command>`,
             '',
+            ...WORKS,
+            '',
             `a tree is made, attached to, and then declared into. These ${String(OWN.length)} are this framework's own:`,
             '',
-            ...OWN.flatMap((one) => columned(one.said, opening(one.describes))),
+            ...heading(true),
             ...(unread === ''
                 ? []
                 : [