@prestack/thread 0.0.1 → 0.0.3

package/dist/integrity/slopnators/sl_inert_slopnator.ts

@@ -0,0 +1,93 @@
+import type { Slopnator } from '../slopnator.ts'
+
+interface Node {
+  readonly type?: string
+  readonly name?: string
+  readonly key?: { readonly name?: string; readonly value?: unknown }
+  readonly value?: unknown
+  readonly body?: unknown
+  readonly properties?: readonly Node[]
+  readonly elements?: readonly unknown[]
+}
+
+const keyOf = (node: Node): string | undefined =>
+  node.key?.name ?? (typeof node.key?.value === 'string' ? node.key.value : undefined)
+
+const answersUnwritten = (held: unknown): boolean => {
+  const fn = held as { type?: string; body?: { type?: string; name?: string } } | undefined
+  if (fn?.type !== 'ArrowFunctionExpression') return false
+  return fn.body?.type === 'Identifier' && fn.body.name === 'NOT_WRITTEN'
+}
+
+const statesNothing = (held: unknown): boolean => {
+  const proves = held as Node | undefined
+  if (proves?.type !== 'ObjectExpression') return false
+  return (proves.properties ?? []).some((one) => {
+    const key = keyOf(one)
+    if (key !== 'wrong' && key !== 'right') return false
+    const list = one.value as Node | undefined
+    return list?.type === 'ArrayExpression' && (list.elements ?? []).length === 0
+  })
+}
+
+export const slopnator: Slopnator = {
+  on: ['Property'],
+  holds: (node) => {
+    const held = node as Node
+    const key = keyOf(held)
+
+    if (key === 'holds' && answersUnwritten(held.value)) {
+      return 'this is still the scaffold — it answers `NOT_WRITTEN` to everything, so the rule that names it registers, loads, reports nothing, and reads from outside exactly like a rule being obeyed'
+    }
+
+    if (key === 'on') {
+      const list = held.value as Node | undefined
+      if (list?.type === 'ArrayExpression' && (list.elements ?? []).length === 0) {
+        return 'it says it visits syntax and then names no node type, so it is handed nothing and governs nothing inside the files its rule governs'
+      }
+    }
+
+    if (key === 'proves' && statesNothing(held.value)) {
+      return 'its `proves` states nothing — with no form it refuses and none it accepts, no trial is derived from it, so nothing anywhere shows the slopnator does what its row claims'
+    }
+
+    return false
+  },
+  proves: {
+    wrong: [
+      {
+        files: [
+          {
+            at: 'packages/core/src/integrity/slopnators/sl_probe_inert.ts',
+            source: 'export const slopnator = {\n  on: [],\n  holds: () => NOT_WRITTEN,\n  proves: { wrong: [], right: [] },\n}\n',
+          },
+        ],
+        at: 'packages/core/src/integrity/slopnators/sl_probe_inert.ts',
+      },
+      {
+        files: [
+          {
+            at: 'packages/core/src/integrity/slopnators/sl_probe_inert.ts',
+            source: "export const slopnator = {\n  holds: (_node, at) => at.text.includes('nope') && 'found',\n  proves: { wrong: [], right: ['const held = 1'] },\n}\n",
+          },
+        ],
+        at: 'packages/core/src/integrity/slopnators/sl_probe_inert.ts',
+      },
+    ],
+    right: [
+      {
+        files: [
+          {
+            at: 'packages/core/src/integrity/slopnators/sl_probe_inert.ts',
+            source: "export const slopnator = {\n  holds: (_node, at) => at.text.includes('nope') && 'found',\n  proves: { wrong: ['nope'], right: ['const held = 1'] },\n}\n",
+          },
+        ],
+        at: 'packages/core/src/integrity/slopnators/sl_probe_inert.ts',
+      },
+      {
+        files: [{ at: 'packages/core/src/integrity/slopnators/sl_probe_inert.ts', source: 'export const held = 1\n' }],
+        at: 'packages/core/src/integrity/slopnators/sl_probe_inert.ts',
+      },
+    ],
+  },
+}

package/dist/integrity/slopnators/sl_missing_row.ts

@@ -0,0 +1,182 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { Slopnator } from '../slopnator.ts'
+import { ORGANISATION, ours } from '../../core/scope.ts'
+import { findTree } from '../../core/tree.ts'
+
+/**
+ * A row the package still ships and the tree no longer holds.
+ *
+ * Read as TEXT, deliberately. Eight laws were once added whose walks imported a workspace package,
+ * plain Node could not resolve it, `load()` swallowed the failure, and all eight read from every
+ * caller exactly like laws finding nothing. Nothing here imports anything but node builtins.
+ */
+
+const ROOT = findTree().at
+
+/** A node: a const annotated `Threaded`. */
+const NODE = /export\s+const\s+[A-Za-z_$][\w$]*\s*:\s*Threaded\b/
+
+/**
+ * Where a node's rows are written.
+ *
+ * A node may open the list inline, or name a `declares` array declared beside it and reference it by
+ * shorthand. Only the first was read, so `@thread/ui`'s tokens and signals nodes — 107 of its 178
+ * shipped rows — reported as shipping nothing, and every one of them could be deleted in silence.
+ */
+const SHAPES = [/declares:\s*\[/g, /export\s+const\s+declares\b[^\n]*?=\s*\[/g]
+
+/**
+ * How a row states its id.
+ *
+ * A row may be an object literal, or a call to a factory declared beside the list that takes the id
+ * first. Only the literal was read, which is the other half of why tokens and signals were invisible.
+ */
+const ID = /\bid:\s*'([^']+)'/g
+const CALLED = /(?:^|[\s,[(])[a-zA-Z_$][\w$]*\(\s*'([^']+)'/g
+
+/** Strings out first, so a fixture that PRINTS a declaration is not read as being one. */
+const QUOTED = /"(?:[^"\\\n]|\\.)*"|`(?:[^`\\]|\\.)*`/g
+
+function closes(code: string, from: number): number {
+  let depth = 0
+  for (let at = from; at < code.length; at += 1) {
+    if (code[at] === '[') depth += 1
+    else if (code[at] === ']') {
+      depth -= 1
+      if (depth === 0) return at
+    }
+  }
+  return -1
+}
+
+/**
+ * What a package SHIPS: only the ids inside a `declares` list.
+ *
+ * It was every id anywhere in a file that held one such list, which read an `Appending`'s own `id`
+ * as a shipped row — `@thread/operations` was reported as shipping `seed-generator`, the name of a
+ * row it asks an app to APPEND into another list, not one it declares.
+ */
+function shippedIn(text: string): ReadonlySet<string> {
+  const code = text.replace(QUOTED, '""')
+  if (!NODE.test(code)) return new Set()
+  const found = new Set<string>()
+  for (const shape of SHAPES) {
+    for (const one of code.matchAll(shape)) {
+      const opens = (one.index ?? 0) + one[0].length - 1
+      const shut = closes(code, opens)
+      if (shut === -1) continue
+      const rows = code.slice(opens, shut)
+      for (const held of rows.matchAll(ID)) found.add(held[1] ?? '')
+      for (const held of rows.matchAll(CALLED)) found.add(held[1] ?? '')
+    }
+  }
+  return found
+}
+
+/**
+ * What a tree HOLDS: every id in it, whichever list it sits in.
+ *
+ * Gating this on `declares` made every row in `derivation.ts` invisible, because its node states no
+ * `declares` at all and its rows live in `GENERATORS`. A row plainly on disk read as missing, and
+ * running the command this law recommends would not have cleared the finding.
+ */
+function heldIn(text: string): ReadonlySet<string> {
+  const code = text.replace(QUOTED, '""')
+  const found = new Set<string>()
+  for (const one of code.matchAll(ID)) found.add(one[1] ?? '')
+  for (const one of code.matchAll(CALLED)) found.add(one[1] ?? '')
+  return found
+}
+
+function filesIn(dir: string): readonly string[] {
+  try {
+    return readdirSync(dir).filter((one) => one.endsWith('.ts')).map((one) => join(dir, one))
+  } catch {
+    return []
+  }
+}
+
+/** Every installed thread package that ships nodes of its own. */
+function installed(): readonly { readonly name: string; readonly src: string }[] {
+  const at = join(ROOT, 'node_modules', ORGANISATION)
+  const found: { name: string; src: string }[] = []
+  for (const one of safely(at)) {
+    const name = `${ORGANISATION}/${one}`
+    if (!ours(name)) continue
+    const src = join(at, one, 'dist')
+    if (existsSync(src) && statSync(src).isDirectory()) found.push({ name, src })
+  }
+  return found
+}
+
+function safely(dir: string): readonly string[] {
+  try {
+    return readdirSync(dir)
+  } catch {
+    return []
+  }
+}
+
+function read(path: string): string {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+export const slopnator: Slopnator = {
+  checks: () => {
+    const tree = findTree()
+
+    /* Every id the tree holds, across every node in it. */
+    const held = new Set<string>()
+    for (const path of filesIn(tree.dir)) for (const one of heldIn(read(path))) held.add(one)
+
+    /*
+     * Only packages this tree ATTACHED, not every one installed.
+     *
+     * Measured by running it: the first version named `@thread/knowledge`, which the audit app has
+     * in `node_modules` and never attached — so the law demanded rows for a package nobody had
+     * asked for. A package is attached when the tree names a file inside it; one nothing points at
+     * is a dependency, and a dependency ships nothing this tree promised to hold.
+     */
+    const wired = new Set<string>()
+    for (const path of filesIn(tree.dir)) {
+      for (const one of read(path).matchAll(/node_modules\/(@[\w.-]+\/[\w.-]+)\//g)) wired.add(one[1] ?? '')
+    }
+
+    const found: string[] = []
+    for (const pkg of installed()) {
+      if (!wired.has(pkg.name)) continue
+      for (const path of filesIn(pkg.src)) {
+        const shipped = shippedIn(read(path))
+        if (shipped.size === 0) continue
+        for (const id of [...shipped].sort()) {
+          /* The node's own id names the list, not a row in it. */
+          if (held.has(id)) continue
+          found.push(
+            `${pkg.name} ships \`${id}\` and this tree does not hold it — run \`thread attach ${pkg.name}\` to put it back`,
+          )
+        }
+      }
+    }
+    return found
+  },
+  proves: {
+    wrong: [
+      {
+        files: [{ at: '_threads/_probe_missing.ts', source: "import type { Threaded } from '../../core/thread.ts'\n\nexport const M: Threaded = {\n  declares: [],\n}\n" }],
+        at: '_threads/_probe_missing.ts',
+      },
+    ],
+    right: [
+      {
+        files: [{ at: '_threads/_probe_missing.ts', source: "import type { Threaded } from '../../core/thread.ts'\n\nexport const M: Threaded = {\n  declares: [\n    {\n      id: 'colour',\n    },\n  ],\n}\n" }],
+        at: '_threads/_probe_missing.ts',
+      },
+    ],
+  },
+}

package/dist/integrity/slopnators/sl_no_barrel.ts

@@ -0,0 +1,48 @@
+import type { Slopnator } from '../slopnator.ts'
+import { here } from './sl_unthreaded.ts'
+
+const BARREL_NAME = /(^|\/)index\.(ts|tsx|mts|cts|js|mjs|cjs)$/
+const CODE = /\.(ts|tsx|mts|cts|js|mjs|cjs)$/
+
+const SAYS = "can't do barrels lazy ass"
+
+function reExportsOnly(text: string): boolean {
+  const lines = text
+    .split('\n')
+    .map((one) => one.trim())
+    .filter((one) => one !== '')
+
+  if (lines.length === 0) return false
+  return lines.every((one) => one.startsWith('export *') || one.startsWith('export {') || one.startsWith('}') || one.startsWith('} from') || /^[A-Za-z_$][\w$]*,?$/.test(one) || /^type [A-Za-z_$][\w$]*,?$/.test(one))
+}
+
+export const slopnator: Slopnator = {
+  holds: (_node, at) => {
+    const path = here(at.filename)
+    if (!CODE.test(path)) return false
+
+    if (BARREL_NAME.test(path)) {
+      return `${SAYS} — this file is named for the folder it sits in, so it exists to list what the folder holds, and the tree already says that`
+    }
+
+    if (reExportsOnly(at.text)) {
+      return `${SAYS} — every line of this file is a re-export, so it holds no thing of its own and names nothing the tree has not already named`
+    }
+
+    return false
+  },
+  proves: {
+    wrong: [
+      {
+        files: [{ at: 'packages/_probe_barrel/index.ts', source: "export const held = 1\n" }],
+        at: 'packages/_probe_barrel/index.ts',
+      },
+    ],
+    right: [
+      {
+        files: [{ at: 'packages/_probe_barrel/held.ts', source: "export const held = 1\n" }],
+        at: 'packages/_probe_barrel/held.ts',
+      },
+    ],
+  },
+}

package/dist/integrity/slopnators/sl_no_child_process.ts

@@ -0,0 +1,74 @@
+import type { Slopnator } from '../slopnator.ts'
+
+const STARTS_A_PROCESS = new Set(['node:child_process', 'child_process'])
+
+interface Node {
+  readonly type?: string
+  readonly source?: { readonly type?: string; readonly value?: unknown }
+  readonly callee?: { readonly type?: string; readonly name?: string }
+  readonly arguments?: readonly { readonly type?: string; readonly value?: unknown }[]
+}
+
+const named = (held: unknown): string | undefined => {
+  const one = held as { type?: string; value?: unknown } | undefined
+  return one?.type === 'Literal' && typeof one.value === 'string' ? one.value : undefined
+}
+
+export const slopnator: Slopnator = {
+  on: ['ImportDeclaration', 'ImportExpression', 'CallExpression'],
+  holds: (node) => {
+    const held = node as Node
+    const from =
+      held.type === 'ImportDeclaration' || held.type === 'ImportExpression'
+        ? (named(held.source) ?? named(held.arguments?.[0]))
+        : held.callee?.name === 'require'
+          ? named(held.arguments?.[0])
+          : undefined
+
+    if (from === undefined || !STARTS_A_PROCESS.has(from)) return false
+
+    return `it imports \`${from}\`, so this slopnator can start a process — and whatever it starts can reach back into the enforcement that called it`
+  },
+  proves: {
+    wrong: [
+      {
+        files: [
+          {
+            at: 'packages/core/src/integrity/slopnators/sl_probe_spawn.ts',
+            source: "import { spawnSync } from 'node:child_process'\nexport const slopnator = { holds: () => false, proves: { wrong: ['a'], right: ['b'] } }\n",
+          },
+        ],
+        at: 'packages/core/src/integrity/slopnators/sl_probe_spawn.ts',
+      },
+      {
+        files: [
+          {
+            at: 'packages/core/src/integrity/slopnators/sl_probe_spawn.ts',
+            source: "const held = await import('child_process')\nexport const slopnator = { holds: () => false, proves: { wrong: ['a'], right: ['b'] } }\n",
+          },
+        ],
+        at: 'packages/core/src/integrity/slopnators/sl_probe_spawn.ts',
+      },
+    ],
+    right: [
+      {
+        files: [
+          {
+            at: 'packages/core/src/integrity/slopnators/sl_probe_spawn.ts',
+            source: "import { readFileSync } from 'node:fs'\nexport const slopnator = { holds: () => false, proves: { wrong: ['a'], right: ['b'] } }\n",
+          },
+        ],
+        at: 'packages/core/src/integrity/slopnators/sl_probe_spawn.ts',
+      },
+      {
+        files: [
+          {
+            at: 'packages/core/src/integrity/slopnators/sl_probe_spawn.ts',
+            source: "export const slopnator = { holds: () => false, proves: { wrong: ['a'], right: ['b'] } }\n",
+          },
+        ],
+        at: 'packages/core/src/integrity/slopnators/sl_probe_spawn.ts',
+      },
+    ],
+  },
+}

package/dist/integrity/slopnators/sl_no_comment.ts

@@ -0,0 +1,43 @@
+import type { Slopnator, Spoken } from '../slopnator.ts'
+
+const shebang = (text: string): string | undefined => (text.startsWith('#!') ? text.slice(2, text.indexOf('\n')) : undefined)
+
+const spoken = (text: string, all: readonly Spoken[]): readonly Spoken[] => {
+  const line = shebang(text)
+  return all.filter((one, index) => !(index === 0 && one.value === line))
+}
+
+export const slopnator: Slopnator = {
+  on: ['Program'],
+  holds: (_node, at) => {
+    const all = spoken(at.text, at.comments())
+    if (all.length === 0) return false
+    const first = (all[0]?.value ?? '')
+      .split('\n')
+      .map((line) => line.trim().replace(/^\*+\s?/, ''))
+      .find((line) => line !== '') ?? ''
+    return `${String(all.length)} comment(s), the first saying "${first.slice(0, 60)}"`
+  },
+  fixes: (_node, at) => {
+    const all = spoken(at.text, at.comments())
+    if (all.length === 0) return undefined
+    let out = at.text
+    for (const one of [...all].sort((a, b) => b.range[0] - a.range[0])) {
+      out = out.slice(0, one.range[0]) + out.slice(one.range[1])
+    }
+    return out.replace(/[ \t]+$/gm, '').replace(/\n{3,}/g, '\n\n')
+  },
+  proves: {
+    wrong: [
+      'const a = 1 // a line comment',
+      '/* a block comment */\nconst a = 1',
+      '/** JSDoc on the export */\nexport const a = 1',
+    ],
+    right: [
+      'const a = "// not a comment"',
+      'const url = "https://example.com/docs"',
+      'const a = 1',
+      '#!/usr/bin/env node\nconst a = 1',
+    ],
+  },
+}