@prestack/thread 0.0.1 → 0.0.3

package/dist/knowledge/generators/skills.ts

@@ -0,0 +1,263 @@
+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.ts'
+import { generators } from '../../core/chain.ts'
+import { TREE } from '../../core/descend.ts'
+import { LOADER, exit, invoked } from '../../core/invoked.ts'
+import { ORGANISATION, named } from '../../core/scope.ts'
+import type { Tree } from '../../core/tree.ts'
+import { findTree } from '../../core/tree.ts'
+
+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: string): string => skillOf(noun)
+
+async function offering(tree: Tree): Promise<ReadonlyMap<string, string>> {
+  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: string, at: string, noun: string): { readonly refused: string; readonly body: string } {
+  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: string, body: string): string {
+  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: readonly string[]): string {
+  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 = (): string => 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: string): ReadonlyMap<string, string> {
+  const found = new Map<string, string>()
+
+  let names: readonly string[]
+  try {
+    names = readdirSync(join(root, 'src'), { recursive: true }) as readonly string[]
+  } catch {
+    return found
+  }
+
+  for (const one of names) {
+    const path = String(one).split('\\').join('/')
+    if (!path.endsWith('attach.ts')) continue
+
+    let text: string
+    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: string): { readonly refused: string; readonly body: string } {
+  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(): Promise<number> {
+  const own = argv.includes('--own')
+  const checking = argv.includes('--check')
+
+  const root = own ? HERE() : (findTree() as Tree).at
+
+  const mine = own ? ownMakers(root) : new Map<string, string>()
+  const theirs = own ? new Map<string, string>() : await offering(findTree() as Tree)
+  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<string, string>()
+  const skipped: string[] = []
+  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<string, string>()
+  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.ts

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

package/dist/operations/access.ts

@@ -0,0 +1,88 @@
+import type { Actor } from '../core/actor.ts'
+import { mentionsActor, walkOperands, type Condition } from '../core/condition.ts'
+import type { Member } from '../core/thread.ts'
+
+export const PERMITS_AT = 'src/_generated/permits.ts'
+
+export 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[] {
+  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: string, offers: readonly string[], which: 'roles' | 'entitlements'): string | undefined {
+  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 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 function opensToEverybody(grants: readonly Grant[]): readonly Grant[] {
+  return grants.filter((one) => one.to === undefined && (one.when === undefined || !mentionsActor(one.when)))
+}
+
+export function grantedTwice(grants: readonly Grant[]): readonly string[] {
+  const seen = new Set<string>()
+  const twice = new Set<string>()
+  for (const one of grants) {
+    if (seen.has(one.id)) twice.add(one.id)
+    seen.add(one.id)
+  }
+  return [...twice].sort()
+}
+
+function operandsOf(one: Grant): readonly string[] {
+  if (one.when === undefined) return []
+  const found: string[] = []
+  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: readonly Grant[]): readonly string[] {
+  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}`]
+  })
+}
+