@prestack/thread 0.0.1 → 0.0.3

package/dist/integrity/slopnators/sl_untranslated_key.ts

@@ -0,0 +1,164 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { Slopnator } from '../slopnator.ts'
+import { named as packageOf } from '../../core/scope.ts'
+
+/*
+ * A KEY THE INTERFACE NAMES AND A LANGUAGE DOES NOT ANSWER.
+ *
+ *   "i18n keys must be translated OR ITS AN ERROR ... a new constraint.ts row and slopnator that
+ *    checks i18n entries against the keys in the UI and if there's anything missing in whatever
+ *    file, it's a build error, compile error, gate error, everything. Cannot be allowed."
+ *                                                            — founder, 2026-08-29
+ *
+ * The generator already writes a line into every language file for every key it finds, so a key is
+ * never structurally absent — what it cannot do is invent the sentence. This is the half that
+ * refuses: a line holding nothing is a key nobody has answered, and an app that ships one shows a
+ * person an empty button.
+ *
+ * Deliberately independent of the generator rather than calling it. A check that runs the thing it
+ * is checking passes whenever that thing passes, which is no check at all — this reads the files
+ * that are actually on disk and compares them to the markup that is actually there.
+ */
+
+const SKIP = new Set(['node_modules', '.next', '.git', 'dist', '_generated'])
+
+const CODE = /\.(tsx?|jsx?)$/
+
+/*
+ * Which props carry a key, read off the installed package's own declarations.
+ *
+ * A list written here would go stale the first time an element gained a prop — silently, by finding
+ * fewer keys than there are, which is the failure this whole law exists to prevent.
+ */
+const TYPED = /readonly\s+([A-Za-z][A-Za-z0-9]*)\??\s*:\s*MessageKey\b/g
+
+function walk(at: string, found: string[] = []): readonly string[] {
+  let entries: readonly { name: string; isDirectory: () => boolean }[]
+  try {
+    entries = readdirSync(at, { withFileTypes: true })
+  } catch {
+    return found
+  }
+  for (const entry of entries) {
+    if (SKIP.has(entry.name)) continue
+    const path = join(at, entry.name)
+    if (entry.isDirectory()) walk(path, found)
+    else if (CODE.test(entry.name)) found.push(path)
+  }
+  return found
+}
+
+function keyProps(root: string): readonly string[] {
+  const found = new Set<string>()
+  const home = join(root, 'node_modules', packageOf('ui'))
+  if (!existsSync(home)) return []
+  for (const file of walk(home)) {
+    for (const one of readFileSync(file, 'utf8').matchAll(TYPED)) found.add(one[1] ?? '')
+  }
+  return [...found].sort()
+}
+
+function languagesIn(root: string): { readonly held: readonly string[]; readonly source: string | undefined } {
+  const at = join(root, '_threads', 'localizations.ts')
+  if (!existsSync(at)) return { held: [], source: undefined }
+  const text = readFileSync(at, 'utf8')
+  const held: string[] = []
+  let source: string | undefined
+  for (const one of text.matchAll(/id:\s*(?:SOURCE_ROW|'([^']+)')\s*,[\s\S]{0,200}?is:\s*'([^']*)'/g)) {
+    const id = one[1]
+    if (id === undefined || id === 'source') {
+      source = one[2]
+      continue
+    }
+    held.push(id)
+  }
+  return { held, source }
+}
+
+export const slopnator: Slopnator = {
+  checks: (root) => {
+    const { held } = languagesIn(root)
+    if (held.length === 0) return []
+
+    const props = keyProps(root)
+    if (props.length === 0) return []
+
+    const named = new RegExp(`\\b(?:${props.join('|')})\\s*=\\s*"([^"]+)"`, 'g')
+
+    const used = new Map<string, string>()
+    for (const file of walk(root)) {
+      const text = readFileSync(file, 'utf8')
+      for (const one of text.matchAll(named)) {
+        const key = one[1] ?? ''
+        if (!used.has(key)) used.set(key, file.slice(root.length).replace(/^\/+/, ''))
+      }
+    }
+    if (used.size === 0) return []
+
+    const findings: string[] = []
+    for (const language of held) {
+      const at = join(root, 'i18n', `${language}.json`)
+      if (!existsSync(at)) {
+        findings.push(
+          `i18n/${language}.json is not there and \`${language}\` is a declared language, so every key this ` +
+            'interface names goes unanswered in it — run `thread i18n`',
+        )
+        continue
+      }
+      let wording: Readonly<Record<string, unknown>>
+      try {
+        wording = JSON.parse(readFileSync(at, 'utf8')) as Readonly<Record<string, unknown>>
+      } catch {
+        findings.push(
+          `i18n/${language}.json will not parse, so what this app says in \`${language}\` cannot be known — ` +
+            'a reader that cannot read is not a reader that found nothing',
+        )
+        continue
+      }
+      for (const [key, where] of [...used].sort()) {
+        const said = wording[key]
+        if (typeof said === 'string' && said !== '') continue
+        findings.push(
+          `\`${key}\` is named by ${where} and says nothing in \`${language}\` — an untranslated key is a ` +
+            'blank on the screen, and it is an error rather than a word that comes out in the wrong language',
+        )
+      }
+    }
+    return findings
+  },
+  proves: {
+    wrong: [
+      {
+        files: [
+          { at: '_threads/localizations.ts', source: "export const LOCALIZATION = {\n  holds: [\n    { id: 'source', is: 'en' },\n    { id: 'en', is: 'English' },\n  ],\n}\n" },
+          { at: `node_modules/${packageOf('ui')}/probe.ts`, source: 'export interface P {\n  readonly label: MessageKey\n}\n' },
+          { at: 'compositions/cmp_probe.tsx', source: 'export const P = () => <Button label="probe.blank" />\n' },
+          { at: 'i18n/en.json', source: '{\n  "probe.blank": ""\n}\n' },
+        ],
+        at: 'compositions/cmp_probe.tsx',
+      },
+      {
+        files: [
+          { at: '_threads/localizations.ts', source: "export const LOCALIZATION = {\n  holds: [\n    { id: 'source', is: 'en' },\n    { id: 'en', is: 'English' },\n  ],\n}\n" },
+          { at: `node_modules/${packageOf('ui')}/probe.ts`, source: 'export interface P {\n  readonly label: MessageKey\n}\n' },
+          { at: 'compositions/cmp_probe.tsx', source: 'export const P = () => <Button label="probe.missing" />\n' },
+          { at: 'i18n/en.json', source: '{\n  "probe.other": "Something"\n}\n' },
+        ],
+        at: 'compositions/cmp_probe.tsx',
+      },
+    ],
+    right: [
+      {
+        files: [
+          { at: '_threads/localizations.ts', source: "export const LOCALIZATION = {\n  holds: [\n    { id: 'source', is: 'en' },\n    { id: 'en', is: 'English' },\n  ],\n}\n" },
+          { at: `node_modules/${packageOf('ui')}/probe.ts`, source: 'export interface P {\n  readonly label: MessageKey\n}\n' },
+          { at: 'compositions/cmp_probe.tsx', source: 'export const P = () => <Button label="probe.answered" />\n' },
+          { at: 'i18n/en.json', source: '{\n  "probe.answered": "Answered"\n}\n' },
+        ],
+        at: 'compositions/cmp_probe.tsx',
+      },
+    ],
+  },
+}

package/dist/integrity/slopnators/sl_unversioned.ts

@@ -0,0 +1,36 @@
+import type { Slopnator } from '../slopnator.ts'
+import { here, parses, rowsIn } from './sl_unthreaded.ts'
+
+export const slopnator: Slopnator = {
+  holds: (_node, at) => {
+    const path = here(at.filename)
+
+    if (!parses(path)) return false
+
+    let governing: readonly { readonly list?: string; readonly id?: string; readonly version?: number }[]
+    try {
+      governing = rowsIn(at.text)
+    } catch {
+      return 'this file cannot be parsed, so the declarations it governs with were never read and nothing about their versions was measured'
+    }
+
+    for (const node of governing) {
+      if (node.list !== undefined || node.version !== undefined) continue
+      return (
+        `"${node.id ?? ''}" is annotated with the interface that makes other things conform to it and states no \`version\`, ` +
+        'so a change to what it governs is a diff nobody downstream can detect and nothing can be carried forward from the shape it used to have'
+      )
+    }
+
+    return false
+  },
+  proves: {
+    wrong: [
+      "export const L: Constraint = {\n  id: 'a-law',\n  at: 'packages/core/integrity/src/constraint.ts',\n  describes: 'A rule that must be enforced.',\n}",
+    ],
+    right: [
+      "export const L: Constraint = {\n  id: 'a-law',\n  at: 'packages/core/integrity/src/constraint.ts',\n  describes: 'A rule that must be enforced.',\n  version: 3,\n}",
+      "export const HELPER = {\n  id: 'a-helper',\n  at: 'threads/meta.ts',\n  describes: 'Nothing conforms to this.',\n}",
+    ],
+  },
+}

package/dist/integrity/sweep.ts

@@ -0,0 +1,307 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { stdout } from 'node:process'
+import { pathToFileURL } from 'node:url'
+
+import { descend } from '../core/descend.ts'
+import { runChecker, type Finding } from '../core/finding.ts'
+import { exit, invoked } from '../core/invoked.ts'
+
+import { parser } from 'typescript-eslint'
+
+import { CONSTRAINTS, type Constraint } from './constraint.ts'
+import { NOT_WRITTEN, ROOT, governs, load, reads, rules, slopnatorName, sweeps, visits, type Reading, type Slopnator, type Spoken, type Visiting } from './slopnator.ts'
+import { ruleMessage } from './lint.ts'
+
+const PARSEABLE = /\.(ts|tsx|mts|cts|mjs|cjs|js|jsx)$/
+
+interface Node {
+  readonly type?: string
+  readonly comments?: readonly Spoken[]
+  readonly [key: string]: unknown
+}
+
+function tree(text: string): Node | undefined {
+  const read = (jsx: boolean): { ast: Node } =>
+    (parser.parseForESLint as (t: string, o: unknown) => { ast: Node })(text, {
+      range: true,
+      loc: true,
+      comment: true,
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      ecmaFeatures: { jsx },
+    })
+  try {
+    return read(true).ast
+  } catch {
+    try {
+      return read(false).ast
+    } catch {
+      return undefined
+    }
+  }
+}
+
+export function visit(root: Node, on: ReadonlySet<string>, each: (node: Node, ancestors: readonly Node[]) => void): void {
+  const stack: Node[] = []
+  const step = (held: unknown): void => {
+    if (held === null || typeof held !== 'object') return
+    if (Array.isArray(held)) {
+      for (const one of held) step(one)
+      return
+    }
+    const node = held as Node
+    const named = typeof node.type === 'string'
+    if (named && on.has(node.type as string)) each(node, [...stack])
+    if (named) stack.push(node)
+    for (const key of Object.keys(node)) {
+      if (key === 'parent') continue
+      step((node as Record<string, unknown>)[key])
+    }
+    if (named) stack.pop()
+  }
+  step(root)
+}
+
+export interface Caught {
+  readonly rule: string
+  readonly file: string
+  readonly found: string
+}
+
+const ELSEWHERE = new Set(['node_modules', '.git'])
+
+function ignoredIn(root: string): ReadonlySet<string> {
+  const at = join(root, '.gitignore')
+  if (!existsSync(at)) return new Set()
+  return new Set(
+    readFileSync(at, 'utf8')
+      .split('\n')
+      .map((line) => line.trim().replace(/^\//, '').replace(/\/$/, ''))
+      .filter((line) => line !== '' && !line.startsWith('#') && !line.includes('*') && !line.startsWith('!')),
+  )
+}
+
+function authored(): ReadonlySet<string> {
+  const found = new Set<string>()
+  try {
+    for (const [at, threadings] of descend().threaded) {
+      if (threadings.some((one) => one.list === 'derives' && (one.row.by ?? one.row.runs) !== undefined)) found.add(at)
+    }
+  } catch {
+
+  }
+  return found
+}
+
+export function tracked(root: string): readonly string[] {
+  const derived = authored()
+  const mine = (one: string): boolean => !derived.has(one)
+
+  try {
+
+    const listed = execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard'], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .split('\n')
+      .filter(Boolean)
+    if (listed.length > 0) {
+      return [...new Set(listed)].filter((one) => existsSync(join(root, one)) && mine(one)).sort()
+    }
+  } catch {
+
+  }
+
+  const found: string[] = []
+  const ignored = ignoredIn(root)
+
+  const walk = (at: string, under: string): void => {
+    for (const one of readdirSync(at, { withFileTypes: true })) {
+      if (one.name.startsWith('.')) continue
+      if (ELSEWHERE.has(one.name) || ignored.has(one.name) || ignored.has(under === '' ? one.name : `${under}/${one.name}`)) continue
+      const here = under === '' ? one.name : `${under}/${one.name}`
+      if (one.isDirectory()) walk(join(at, one.name), here)
+      else if (mine(here)) found.push(here)
+    }
+  }
+
+  walk(root, '')
+  return found.sort()
+}
+
+export function sweep(
+  root: string,
+  all: readonly Constraint[],
+  slopnators: ReadonlyMap<string, Slopnator>,
+  files: readonly string[],
+): {
+  readonly findings: readonly Caught[]
+  readonly swept: number
+  readonly tracked: number
+  readonly rules: number
+  readonly unrun: readonly string[]
+  readonly unmet: readonly string[]
+  readonly linted: readonly string[]
+} {
+  const readers = all
+    .map((rule) => ({ rule, slopnator: slopnators.get(slopnatorName(rule.id)) }))
+    .filter((one): one is { rule: Constraint; slopnator: Reading } => one.slopnator !== undefined && sweeps(one.slopnator))
+
+  const walkers = all
+    .map((rule) => ({ rule, slopnator: slopnators.get(slopnatorName(rule.id)) }))
+    .filter((one): one is { rule: Constraint; slopnator: Visiting } => one.slopnator !== undefined && visits(one.slopnator))
+
+  const findings: Caught[] = []
+  let swept = 0
+
+  const met = new Set<string>()
+
+  for (const file of files) {
+    const reading = readers.filter((one) => governs(one.rule, file))
+    const walking = walkers.filter((one) => governs(one.rule, file))
+    for (const one of reading) met.add(one.rule.id)
+    for (const one of walking) met.add(one.rule.id)
+    if (reading.length === 0 && walking.length === 0) continue
+
+    let text: string
+    try {
+      text = readFileSync(join(root, file), 'utf8')
+    } catch {
+      continue
+    }
+    swept += 1
+
+    for (const { rule, slopnator } of reading) {
+      const held = slopnator.holds(undefined, {
+        filename: file,
+        text,
+        ancestors: () => [],
+        comments: () => [],
+      })
+      if (held === false || held === NOT_WRITTEN) continue
+      findings.push({ rule: rule.id, file, found: typeof held === 'string' ? held : slopnatorName(rule.id) })
+    }
+
+    if (walking.length === 0 || !PARSEABLE.test(file)) continue
+
+    const ast = tree(text)
+    if (ast === undefined) {
+      for (const { rule } of walking) {
+        findings.push({
+          rule: rule.id,
+          file,
+          found:
+            'this file could not be parsed, so nothing about its structure was measured — ' +
+            'a green result here says nothing about this rule on this file',
+        })
+      }
+      continue
+    }
+
+    const comments = ast.comments ?? []
+    for (const { rule, slopnator } of walking) {
+      const on = new Set(slopnator.on)
+      if (on.size === 0) {
+        findings.push({
+          rule: rule.id,
+          file,
+          found: 'its slopnator visits no node type, so it measured nothing here rather than finding nothing',
+        })
+        continue
+      }
+      visit(ast, on, (node, ancestors) => {
+        const held = slopnator.holds(node, {
+          filename: file,
+          text,
+          ancestors: () => ancestors,
+          comments: () => comments,
+        })
+        if (held === false || held === NOT_WRITTEN) return
+        findings.push({ rule: rule.id, file, found: typeof held === 'string' ? held : slopnatorName(rule.id) })
+      })
+    }
+  }
+
+  for (const rule of all) {
+    const slopnator = slopnators.get(slopnatorName(rule.id))
+    if (slopnator === undefined || reads(slopnator)) continue
+    for (const found of slopnator.checks(root)) findings.push({ rule: rule.id, file: '', found })
+  }
+
+  const unrun = all.filter((rule) => slopnators.get(slopnatorName(rule.id)) === undefined).map((rule) => rule.id)
+  const linted = walkers.map((one) => one.rule.id)
+  const unmet = [...new Set([...readers, ...walkers].map((one) => one.rule.id))].filter((id) => !met.has(id)).sort()
+
+  return {
+    findings,
+    swept,
+    tracked: files.length,
+    unrun,
+    unmet,
+    linted,
+    rules:
+      readers.length +
+      walkers.length +
+      all.filter((rule) => {
+        const slopnator = slopnators.get(slopnatorName(rule.id))
+        return slopnator !== undefined && !reads(slopnator)
+      }).length,
+  }
+}
+
+if (invoked(import.meta.url)) {
+  const governing = [...CONSTRAINTS, ...((await rules()) ?? [])]
+  const slopnators = await load(ROOT, governing)
+  const named = new Map(governing.map((rule) => [rule.id, rule]))
+  const run = sweep(ROOT, governing, slopnators, tracked(ROOT))
+
+  const warned = new Set<string>()
+  const grouped = new Map<string, string[]>()
+  const files = new Map<string, Set<string>>()
+  for (const finding of run.findings) {
+    if (named.get(finding.rule)?.severity === 'warning') warned.add(finding.rule)
+    const held = grouped.get(finding.rule) ?? []
+    held.push(finding.file === '' ? `      ${finding.found}` : `      ${finding.file} — ${finding.found}`)
+    grouped.set(finding.rule, held)
+    const where = files.get(finding.rule) ?? new Set<string>()
+    where.add(finding.file)
+    files.set(finding.rule, where)
+  }
+  const refused = new Set(run.findings.map((one) => one.file).filter((one) => one !== ''))
+
+  const findings: Finding[] = [
+    ...[...grouped.entries()].map(([id, where]): Finding => {
+      const rule = named.get(id)
+      const count = files.get(id)?.size ?? 0
+      const said = where.length === count ? `${String(count)} file(s)` : `${String(where.length)} finding(s) in ${String(count)} file(s)`
+      return {
+        detail: `${id} — ${rule?.bans ?? 'refused'}. ${said}:\n${where.sort().join('\n')}`,
+        instead: rule?.instead ?? `read what ${id} refuses and stop writing it`,
+        ...(rule?.severity === 'warning' ? { severity: 'warning' as const } : {}),
+      }
+    }),
+    ...run.unrun.map((rule): Finding => ({
+      detail: `${rule} DID NOT RUN — no slopnator is on disk for it, so this sweep measured nothing for that rule and a green result here says nothing about it`,
+      instead: 'write the walk the rule names, or delete the rule and its row together — half a rule reads as a whole one from every direction',
+    })),
+  ]
+
+  runChecker(
+    'sweep',
+    findings,
+    `each naming one rule and the files it refuses — ${String(run.findings.length)} refusal(s) across ${String(refused.size)} file(s), ` +
+      `over ${String(run.rules)} rule(s) run across ${String(run.swept)} of ${String(run.tracked)} file(s) in this tree, ` +
+      `${String(run.linted.length)} of them reading a syntax tree` +
+      `${run.unrun.length === 0 ? '' : `, ${String(run.unrun.length)} that DID NOT RUN AT ALL`}` +
+      `${run.unmet.length === 0 ? '' : `, and ${String(run.unmet.length)} that governed no file here and so measured nothing: ${run.unmet.join(', ')}`}`,
+  )
+  const forbidding = findings.length - run.findings.filter((one) => named.get(one.rule)?.severity === 'warning').length
+  if (forbidding > 0) exit(1)
+  if (warned.size > 0) {
+    stdout.write(`sweep: every finding above is a warning — ${[...warned].sort().join(', ')} state \`severity: 'warning'\`, so the gate does not stop here.\n`)
+  }
+  exit(0)
+}