@prestack/thread 0.0.1 → 0.0.2

package/dist/integrity/slopnators/sl_undeclared_variant.ts

@@ -0,0 +1,148 @@
+import type { Slopnator } from '../slopnator.ts'
+
+import { descend, read, reached } from '../../core/descend.ts'
+
+import { rowsIn } from './sl_unthreaded.ts'
+
+const ELEMENT = 'element'
+
+const VARIANT = 'variant'
+
+interface Worn {
+  readonly elements: ReadonlySet<string>
+  readonly variants: ReadonlyMap<string, readonly string[]>
+}
+
+function nameOf(id: string): string {
+  return id
+    .split('-')
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join('')
+}
+
+function idOf(name: string): string {
+  return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+}
+
+function memberOf(id: string): string {
+  const [first = '', ...rest] = id.split('-')
+  return first + rest.map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`).join('')
+}
+
+function declared(): Worn {
+  const elements = new Set<string>()
+  const variants = new Map<string, readonly string[]>()
+
+  descend()
+
+  for (const at of reached()) {
+    const text = read(at)
+    if (text === undefined) continue
+
+    let waiting: { readonly id: string; readonly wears?: readonly string[] }[] = []
+    for (const one of rowsIn(text)) {
+      if (one.id === undefined) continue
+      if (one.list === 'declares') {
+        waiting.push(one.wears === undefined ? { id: one.id } : { id: one.id, wears: one.wears })
+        continue
+      }
+      if (one.list !== undefined) continue
+      if (one.id === ELEMENT) for (const row of waiting) elements.add(nameOf(row.id))
+      if (one.id === VARIANT) for (const row of waiting) variants.set(row.id, row.wears ?? [])
+      waiting = []
+    }
+  }
+
+  return { elements, variants }
+}
+
+interface Tag {
+  readonly type?: string
+  readonly object?: { readonly type?: string; readonly name?: string }
+  readonly property?: { readonly type?: string; readonly name?: string }
+}
+
+export const slopnator: Slopnator = {
+  on: ['JSXOpeningElement'],
+  holds: (node) => {
+    const name = (node as { name?: Tag } | undefined)?.name
+    if (name?.type !== 'JSXMemberExpression') return false
+
+    const element = name.object?.type === 'JSXIdentifier' ? name.object.name : undefined
+    const member = name.property?.type === 'JSXIdentifier' ? name.property.name : undefined
+    if (element === undefined || member === undefined) return false
+
+    const { elements, variants } = declared()
+    if (!elements.has(element)) return false
+
+    const id = idOf(member)
+    const wears = variants.get(id)
+
+    const worn = [...variants]
+      .filter(([, all]) => all.includes(element))
+      .map(([one]) => `${element}.${memberOf(one)}`)
+      .sort()
+
+    const offered =
+      worn.length === 0
+        ? `nothing declares itself worn by \`${element}\`, so no member of it would have been accepted — a variant row has to name \`${element}\` first`
+        : `\`${element}\` wears ${worn.join(', ')}`
+
+    if (wears === undefined) {
+      return (
+        `\`${element}.${member}\` names the variant \`${id}\` and nothing declares it — so it renders carrying a class ` +
+        'the stylesheet never writes, which reads on screen as an element that lost its styling and is reported ' +
+        `nowhere. ${offered}`
+      )
+    }
+
+    if (!wears.includes(element)) {
+      return (
+        `\`${element}.${member}\` pairs \`${element}\` with the variant \`${id}\`, and that variant's row does not name ` +
+        `\`${element}\` among the elements that wear it — so the pairing is nobody's declaration. ${offered}`
+      )
+    }
+
+    return false
+  },
+  proves: {
+    wrong: [
+      {
+        files: [
+          {
+            at: 'threads/_probe_worn.ts',
+            source:
+              "export const ELEMENTS: Threaded = {\n  id: 'element',\n  declares: [\n    {\n      id: 'button',\n      at: 'app/_probe_button.tsx',\n    },\n  ],\n}\n\nexport const VARIANTS: Threaded = {\n  id: 'variant',\n  declares: [\n    {\n      id: 'button-primary',\n      at: 'app/_probe_variant.ts',\n      wears: ['Button'],\n    },\n  ],\n}\n",
+          },
+          { at: 'app/_probe_undeclared.tsx', source: 'export const HELD = <Button.primary />\n' },
+        ],
+        at: 'app/_probe_undeclared.tsx',
+      },
+      {
+        files: [
+          {
+            at: 'threads/_probe_worn.ts',
+            source:
+              "export const ELEMENTS: Threaded = {\n  id: 'element',\n  declares: [\n    {\n      id: 'button',\n      at: 'app/_probe_button.tsx',\n    },\n    {\n      id: 'badge',\n      at: 'app/_probe_badge.tsx',\n    },\n  ],\n}\n\nexport const VARIANTS: Threaded = {\n  id: 'variant',\n  declares: [\n    {\n      id: 'chip',\n      at: 'app/_probe_chip.ts',\n      wears: ['Badge'],\n    },\n  ],\n}\n",
+          },
+          { at: 'app/_probe_mispaired.tsx', source: 'export const HELD = <Button.chip />\n' },
+        ],
+        at: 'app/_probe_mispaired.tsx',
+      },
+    ],
+    right: [
+      {
+        files: [
+          {
+            at: 'threads/_probe_worn.ts',
+            source:
+              "export const ELEMENTS: Threaded = {\n  id: 'element',\n  declares: [\n    {\n      id: 'button',\n      at: 'app/_probe_button.tsx',\n    },\n  ],\n}\n\nexport const VARIANTS: Threaded = {\n  id: 'variant',\n  declares: [\n    {\n      id: 'button-primary',\n      at: 'app/_probe_variant.ts',\n      wears: ['Button'],\n    },\n  ],\n}\n",
+          },
+          { at: 'app/_probe_declared.tsx', source: 'export const HELD = <Button.buttonPrimary />\n' },
+        ],
+        at: 'app/_probe_declared.tsx',
+      },
+      '<Unknown.anything />',
+    ],
+  },
+}

package/dist/integrity/slopnators/sl_undescribed.ts

@@ -0,0 +1,65 @@
+import type { Slopnator } from '../slopnator.ts'
+
+const COMMON = new Set([
+  'a', 'an', 'the', 'of', 'for', 'to', 'and', 'or', 'is', 'it', 'its', 'this', 'that',
+  'in', 'on', 'at', 'as', 'by', 'with', 'be', 'are', 'was', 'one', 'every', 'each',
+])
+
+type Node = {
+  type?: string
+  name?: string
+  key?: { type?: string; name?: string; value?: unknown }
+  value?: { type?: string; value?: unknown }
+  computed?: boolean
+  properties?: readonly Node[]
+}
+
+const keyOf = (property: Node): string | undefined => {
+  if (property.computed === true) return undefined
+  const key = property.key
+  if (key?.type === 'Identifier') return key.name
+  if (key?.type === 'Literal' && typeof key.value === 'string') return key.value
+  return undefined
+}
+
+const said = (property: Node | undefined): string | undefined => {
+  const held = property?.value
+  return held?.type === 'Literal' && typeof held.value === 'string' ? held.value : undefined
+}
+
+const words = (text: string): readonly string[] =>
+  text.toLowerCase().split(/[^a-z]+/).filter((one) => one !== '' && !COMMON.has(one))
+
+export const slopnator: Slopnator = {
+  on: ['Property'],
+  holds: (node, at) => {
+    const property = node as Node
+    const key = keyOf(property)
+    if (key !== 'describes' && key !== 'means') return false
+
+    const sentence = said(property)
+    if (sentence === undefined) return false
+    if (sentence.trim() === '') return `\`${key}\` is empty, so the word arrived and the meaning never did`
+
+    const owner = (at.ancestors() as readonly Node[]).at(-1)
+    const id = said((owner?.properties ?? []).find((one) => keyOf(one) === 'id' || keyOf(one) === 'name'))
+    if (id === undefined) return false
+
+    const own = new Set(words(id))
+    if (words(sentence).some((word) => !own.has(word))) return false
+    return `\`${key}\` says "${sentence}", which adds no word its id \`${id}\` does not already carry`
+  },
+  proves: {
+    wrong: [
+      "const M = { id: 'law', describes: 'The law.' }",
+      "const M = { id: 'law', describes: '' }",
+      "const M = { id: 'term', means: '' }",
+      "const M = { id: 'thread-check', describes: 'The thread check.' }",
+    ],
+    right: [
+      "const M = { id: 'law', describes: 'A rule that must be guaranteed to be enforced.' }",
+      "const M = { id: 'term', means: 'A word this repository coins, and what somebody reading it should understand.' }",
+      "const M = { id: 'law', at: 'packages/core/integrity/src/constraint.ts' }",
+    ],
+  },
+}

package/dist/integrity/slopnators/sl_ungoverned_island.ts

@@ -0,0 +1,61 @@
+import type { Slopnator } from '../slopnator.ts'
+import { here, islandsDeclared } from './sl_unthreaded.ts'
+import { findTree } from '../../core/tree.ts'
+
+const TREE = `${findTree().name}/`
+const GOVERNS = /^\s*governs:\s*'([^']+)'/gm
+
+export const slopnator: Slopnator = {
+  holds: (_node, at) => {
+    const path = here(at.filename)
+    if (!path.startsWith(TREE)) return false
+
+    let islands: readonly string[]
+    try {
+      islands = islandsDeclared().map((one) => one.id)
+    } catch {
+      return 'this file cannot be parsed, so the islands the tree declares were never read and nothing a law threaded to govern was measured'
+    }
+
+    for (const match of at.text.matchAll(GOVERNS)) {
+      const governed = match[1] ?? ''
+      if (islands.includes(governed)) continue
+      return `a law governs "${governed}" and the tree declares no island by that name, so the rule reads as coverage of a kind nobody can declare`
+    }
+
+    return false
+  },
+  proves: {
+    wrong: [
+      {
+        files: [
+          {
+            at: 'threads/_governed_probe.ts',
+            source: "export const L: Constraint = {\n  id: 'a-law',\n  governs: 'no-island-by-this-name',\n}\n",
+          },
+        ],
+        at: 'threads/_governed_probe.ts',
+      },
+    ],
+    right: [
+      {
+        files: [
+          {
+            at: 'threads/_governed_probe.ts',
+            source: "export const L: Constraint = {\n  id: 'a-law',\n  governs: 'entities',\n}\n",
+          },
+        ],
+        at: 'threads/_governed_probe.ts',
+      },
+      {
+        files: [
+          {
+            at: 'threads/_governed_probe.ts',
+            source: "export const M: Islanding = {\n  declares: [\n    { id: 'events', at: 'packages/core/spec/src/islands/events.ts', governs: ['app/_declare/events.ts'] },\n  ],\n}\n",
+          },
+        ],
+        at: 'threads/_governed_probe.ts',
+      },
+    ],
+  },
+}

package/dist/integrity/slopnators/sl_unkept_rows.ts

@@ -0,0 +1,111 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import type { Slopnator } from '../slopnator.ts'
+
+const STORES = 'src/stores'
+
+/* What hands an operation its seams, seeded once and then the app's own. */
+const SEAMS = 'src/seams.ts'
+
+/* What the declarations settle, which the seams file is expected to hand on. */
+const DECLARED = 'DECLARED'
+
+/*
+ * WHAT THIS READS, AND WHY IT READS THAT RATHER THAN THE TARGETS SHEET.
+ *
+ * A target that keeps entities derives a store of its own, written by `thread schema` into
+ * `src/stores/<target>.ts`. So one of those files existing IS the fact that this app declares
+ * somewhere to keep rows — already resolved, by the command that resolved it, with no second reading
+ * of what a reach can hold and no chance of the two disagreeing about it.
+ *
+ * Where rows go is settled in `src/_generated/seams.ts`, which `thread capabilities` writes from those
+ * stores and refuses when it drifts. The one place it can still go wrong is `src/seams.ts`, which is
+ * the app's own: an app that stops handing on what was settled there hands its operations a store
+ * that keeps nothing, while the tables are written, the migrations are written, and the gate is green.
+ */
+function held(root: string, at: string): string {
+  const path = resolve(root, at)
+  try {
+    return existsSync(path) ? readFileSync(path, 'utf8') : ''
+  } catch {
+    return ''
+  }
+}
+
+function derived(root: string): readonly string[] {
+  const at = resolve(root, STORES)
+  try {
+    return existsSync(at) ? readdirSync(at).filter((one) => one.endsWith('.ts')) : []
+  } catch {
+    return []
+  }
+}
+
+export const slopnator: Slopnator = {
+  checks: (root) => {
+    const stores = derived(root)
+    if (stores.length === 0) return []
+
+    /*
+     * AN APP WITH NOTHING THAT HANDS A STORE TO AN OPERATION IS NOT KEEPING ROWS THROUGH ONE, SO
+     * THERE IS NOTHING TO REFUSE.
+     *
+     * The seams file is seeded by `thread capabilities`, which ships in the operations package — so
+     * an app that attached data and integrity and nothing else has no seams and no command that
+     * seeds one. Its absence means rows go nowhere yet, which is a state to pass rather than refuse:
+     * nothing is being lost, because nothing is being kept.
+     */
+    const where = held(root, SEAMS)
+    if (where === '') return []
+
+    if (where.includes(DECLARED)) return []
+
+    return [
+      `${STORES} holds ${stores.join(', ')} and ${SEAMS} no longer hands on ${DECLARED}, so every row this app keeps goes ` +
+        'somewhere that is gone the moment it stops. The tables are written, the migrations are written, the gate is ' +
+        `green, and the database is never opened. Spread ${DECLARED} back into SEAMS, or name its store there`,
+    ]
+  },
+  proves: {
+    wrong: [
+      {
+        files: [
+          { at: 'src/stores/pl_probe.ts', source: 'export const store = {}\n' },
+          {
+            at: 'src/seams.ts',
+            source: "import { inMemorySeams } from '../../operations/memory.ts'\n\nexport const SEAMS = inMemorySeams().seams\n",
+          },
+        ],
+        at: 'src/seams.ts',
+      },
+    ],
+    right: [
+      {
+        files: [
+          { at: 'src/stores/pl_probe.ts', source: 'export const store = {}\n' },
+          {
+            at: 'src/seams.ts',
+            source: "import { DECLARED } from './_generated/seams.ts'\n\nexport const SEAMS = { ...DECLARED }\n",
+          },
+        ],
+        at: 'src/seams.ts',
+      },
+
+      /* An app that derived a store and has nothing handing one to an operation — data attached, operations not. */
+      {
+        files: [{ at: 'src/stores/pl_probe.ts', source: 'export const store = {}\n' }],
+        at: 'src/seams.ts',
+      },
+      {
+        files: [
+          {
+            at: 'src/seams.ts',
+            source: "import { inMemorySeams } from '../../operations/memory.ts'\n\nexport const SEAMS = inMemorySeams().seams\n",
+          },
+        ],
+        at: 'src/seams.ts',
+      },
+    ],
+  },
+}

package/dist/integrity/slopnators/sl_unnamed_island.ts

@@ -0,0 +1,41 @@
+import type { Slopnator } from '../slopnator.ts'
+import { declaresIsland, here, islandsDeclared } from './sl_unthreaded.ts'
+
+export const slopnator: Slopnator = {
+  holds: (_node, at) => {
+    const schema = declaresIsland(at.text)
+    if (schema === undefined) return false
+
+    const path = here(at.filename)
+    if (islandsDeclared().some((island) => island.at === path)) return false
+
+    return (
+      `${schema}IslandSchema is an island and no row in the tree names it, so nothing states what it governs and ` +
+      'no law can reach it — the kind is declarable and every rule about where it may be declared is absent'
+    )
+  },
+  proves: {
+    wrong: [
+      {
+        files: [
+          {
+            at: 'packages/core/spec/src/islands/_unnamed_probe.ts',
+            source: 'export const ThingIslandSchema = z.strictObject({\n  specVersion: z.literal(1),\n})\n',
+          },
+        ],
+        at: 'packages/core/spec/src/islands/_unnamed_probe.ts',
+      },
+    ],
+    right: [
+      {
+        files: [
+          {
+            at: 'packages/core/spec/src/islands/_unnamed_probe.ts',
+            source: 'export const ThingSchema = z.strictObject({\n  name: z.string(),\n})\n',
+          },
+        ],
+        at: 'packages/core/spec/src/islands/_unnamed_probe.ts',
+      },
+    ],
+  },
+}

package/dist/integrity/slopnators/sl_unpaired_member.ts

@@ -0,0 +1,131 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import type { Slopnator } from '../slopnator.ts'
+import { foldersGoverned, here, islandsDeclared, rowsIn, type Declared } from './sl_unthreaded.ts'
+import { findTree } from '../../core/tree.ts'
+
+const ROOT = findTree().at
+const TREE = `${findTree().name}/`
+
+interface Seeding {
+  readonly island: string
+  readonly folder: string
+  readonly tree: string
+  readonly member: string
+}
+
+const seeding = (one: Declared): Seeding | undefined => {
+  const folder = foldersGoverned(one.governs)[0]
+  if (folder === undefined || one.tree === undefined || one.member === undefined) return undefined
+  return { island: one.id, folder, tree: one.tree, member: one.member }
+}
+
+const islandsSeeding = (): readonly Seeding[] =>
+  islandsDeclared().flatMap((one) => {
+    const held = seeding(one)
+    return held === undefined ? [] : [held]
+  })
+
+const declares = (island: string): RegExp => new RegExp(`^export const ${island.toUpperCase()}\\b`, 'm')
+
+const exports = (member: string): RegExp => new RegExp(`^export const ${member}\\b`, 'm')
+
+function seededNames(text: string): readonly string[] {
+  const found: string[] = []
+  for (const row of rowsIn(text)) {
+    if (row.list !== undefined || row.id === undefined) continue
+    found.push(`${row.id}.ts`)
+  }
+  return found
+}
+
+function onDisk(folder: string): readonly string[] {
+  const dir = resolve(ROOT, folder)
+  if (!existsSync(dir)) return []
+  try {
+    return readdirSync(dir).filter((name) => name.endsWith('.ts'))
+  } catch {
+    return []
+  }
+}
+
+function declaredNames(one: Seeding): readonly string[] {
+  const path = resolve(ROOT, one.tree)
+  if (!existsSync(path)) return []
+  try {
+    return seededNames(readFileSync(path, 'utf8'))
+  } catch {
+    return []
+  }
+}
+
+export const slopnator: Slopnator = {
+  holds: (_node, at) => {
+    const path = here(at.filename)
+
+    for (const one of islandsSeeding()) {
+      if (path.startsWith(TREE)) {
+        if (!declares(one.island).test(at.text)) continue
+
+        let wanted: readonly string[]
+        try {
+          wanted = seededNames(at.text)
+        } catch {
+          return 'this file cannot be parsed, so the members it declares were never read and no file was measured against them'
+        }
+
+        const found = onDisk(one.folder)
+        for (const name of wanted) {
+          if (found.includes(name)) continue
+          return `a row here declares ${one.member} \`${name.replace(/\.ts$/, '')}\` and ${one.folder}${name} is not on disk, so the row brings nothing into existence — run \`pnpm member:seed\``
+        }
+
+        return false
+      }
+
+      if (!path.startsWith(one.folder)) continue
+      const name = path.slice(one.folder.length)
+      if (!name.endsWith('.ts') || name.includes('/')) continue
+
+      if (!declaredNames(one).includes(name)) {
+        return `${one.folder} holds ${one.member} \`${name.replace(/\.ts$/, '')}\` and no row in ${one.tree} declares it, so it can act while nothing brought it into existence — declare the row first and let \`pnpm member:seed\` write the file, or delete it`
+      }
+
+      if (!exports(one.member).test(at.text)) {
+        return `${name} is declared and exports no \`${one.member}\`, so the row and the file both exist and the ${one.member} still loads as nothing — write it into the template the seeder left`
+      }
+
+      return false
+    }
+
+    return false
+  },
+  proves: {
+    wrong: [
+      {
+        files: [
+          {
+            at: 'threads/_member_probe.ts',
+            source: "export const OPERATIONS: readonly Member[] = [\n  {\n    id: 'wf_unseeded_probe',\n    at: 'threads/operations.ts',\n  },\n]\n",
+          },
+        ],
+        at: 'threads/_member_probe.ts',
+      },
+      {
+        files: [{ at: 'operations/wf_undeclared_probe.ts', source: 'export const operation = { id: 1 }\n' }],
+        at: 'operations/wf_undeclared_probe.ts',
+      },
+    ],
+    right: [
+      {
+        files: [{ at: 'threads/_member_probe.ts', source: 'export const OPERATIONS: readonly Member[] = []\n' }],
+        at: 'threads/_member_probe.ts',
+      },
+      {
+        files: [{ at: 'threads/_member_quiet.ts', source: 'export const NOTHING = []\n' }],
+        at: 'threads/_member_quiet.ts',
+      },
+    ],
+  },
+}

package/dist/integrity/slopnators/sl_unpaired_slopnator.ts

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import { SEEDED, SHIPPED, slopnatorName, type Slopnator } from '../slopnator.ts'
+import { here } from './sl_unthreaded.ts'
+import { findTree } from '../../core/tree.ts'
+
+const ROOT = findTree().at
+const TREE = `${findTree().name}/`
+const ID = /^ {4}id:\s*'([^']+)'/gm
+const DECLARES = /^(?:export )?const (CONSTRAINTS|RULES)\b/m
+
+const idsIn = (text: string): readonly string[] => [...text.matchAll(ID)].map((one) => one[1] ?? '')
+
+export const slopnator: Slopnator = {
+  holds: (_node, at) => {
+    const path = here(at.filename)
+
+    if (path.startsWith(TREE) && DECLARES.test(at.text)) {
+      for (const id of idsIn(at.text)) {
+        const name = `${slopnatorName(id)}.ts`
+        if ([SHIPPED, resolve(ROOT, SEEDED)].some((dir) => existsSync(join(dir, name)))) continue
+        return `"${id}" names "${slopnatorName(id)}", and no such file is in ${SEEDED}/ or shipped with the package — one that cannot run registers, reports nothing, and is indistinguishable from one being obeyed. Seed it`
+      }
+      return false
+    }
+
+    const home = [SEEDED].find((dir) => path.startsWith(`${dir}/`))
+    if (home === undefined) return false
+    const file = path.slice(home.length + 1)
+    if (!file.startsWith('sl_') || !file.endsWith('.ts')) return false
+
+    const declared = [join(SHIPPED, '..', 'constraint.ts'), resolve(ROOT, `${TREE}rules.ts`)]
+      .map((one) => { try { return readFileSync(one, 'utf8') } catch { return '' } })
+      .join('\n')
+    const named = new Set(idsIn(declared).map((id) => slopnatorName(id)))
+    if (named.has(file.replace(/\.ts$/, ''))) return false
+    return `${path} is named by no law, so it governs nothing while looking like enforcement to anybody reading the directory — delete it, or declare the law that needs it. A law renamed makes this a \`git mv\`, not a second file`
+  },
+  proves: {
+    wrong: [
+      "const CONSTRAINTS = [\n  {\n    id: 'nothing-names-this-slopnator',\n  },\n]",
+      {
+        files: [{ at: 'threads/slopnators/sl_no_law_names_this.ts', source: "export const slopnator = { on: [], holds: () => false }\n" }],
+        at: 'threads/slopnators/sl_no_law_names_this.ts',
+      },
+    ],
+    right: [
+      "const CONSTRAINTS = [\n  {\n    id: 'no-comment',\n  },\n]",
+      "const CONSTRAINTS = [\n  {\n    id: 'no-comment',\n  },\n  {\n    id: 'unthreaded',\n  },\n]",
+      'export const PLAIN = 1',
+      {
+        files: [{ at: 'threads/slopnators/not_a_walk.ts', source: 'export const HELPER = 1\n' }],
+        at: 'threads/slopnators/not_a_walk.ts',
+      },
+    ],
+  },
+}