@prestack/thread 0.0.1 → 0.0.3

package/dist/integrity/attach.ts

@@ -0,0 +1,234 @@
+import type { Attaching } from '../core/attach.ts'
+import { named } from '../core/scope.ts'
+
+import { quoted } from '../core/rows.ts'
+
+const DESCRIBES =
+  'What this app refuses, and the checks that make each refusal actually happen. Every check has one owner, so none of them can be switched off somewhere nobody is looking.'
+
+const CONSTRAINT =
+  'The rules the framework enforces on every app that installs it. They are read from the installed package rather than from this tree, so there is nothing here to weaken.'
+
+const RULES =
+  'What this app refuses on top of what the framework already does. `thread create rule` asks what to ban, where it applies and what to do instead, then writes the row and the check beside it.'
+
+const HOME = `node_modules/${named('integrity')}/dist`
+
+const GATE =
+  'Every surface that can refuse, each naming where it lives and the command that runs it, so the gate is derived from what this system declares rather than kept as a string beside it.'
+
+const COMPILER =
+  'The compiler run over the files this app declares and no others. A type error is the plainest kind of broken build, so it is refused here rather than found by whoever runs the app next.'
+
+const INTEGRITY_SOURCE = `import type { Threaded } from '../core/thread.ts'
+
+export const INTEGRITY: Threaded = {
+  id: 'integrity',
+  at: '_threads/integrity.ts',
+  describes: ${quoted(DESCRIBES)},
+  version: 1,
+  declares: [
+    {
+      id: 'compiler',
+      at: 'tsconfig.json',
+      describes: ${quoted(COMPILER)},
+      version: 1,
+      by: 'thread compiler',
+    },
+    {
+      id: 'constraint',
+      at: '${HOME}/constraint.js',
+      describes: ${quoted(CONSTRAINT)},
+      version: 1,
+    },
+    {
+      id: 'rules',
+      at: '_threads/rules.ts',
+      describes: ${quoted(RULES)},
+      version: 1,
+    },
+    {
+      id: 'gate',
+      at: '_threads/gate.ts',
+      describes: ${quoted(GATE)},
+      version: 1,
+    },
+  ],
+}
+`
+
+const RULES_SOURCE = `import type { Constraint } from './constraint.ts'
+
+export const RULES: readonly Constraint[] = []
+`
+
+const GATE_SOURCE = `import type { Threaded } from '../core/thread.ts'
+
+export const GATE: Threaded = {
+  id: 'gate',
+  at: '_threads/gate.ts',
+  describes: ${quoted(GATE)},
+  version: 1,
+  declares: [],
+}
+`
+
+const SEEDED = {
+  attaches: ['@prestack/thread/derivation/attach'] as const,
+  id: 'integrity',
+  declares: [
+    '    {',
+    '      id: \'integrity\',',
+    '      at: \'_threads/integrity.ts\',',
+    '      describes: \'What this app refuses, and the checks that make each refusal actually happen. Every check has one owner, so none of them can be switched off somewhere nobody is looking.\',',
+    '      version: 1,',
+    '    },',
+  ].join('\n'),
+}
+
+const SHIPPED: readonly { readonly into: string; readonly list: string; readonly id: string; readonly source: string }[] = [
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'gate-generator',
+    source: "  {\n    id: 'gate-generator',\n    at: 'node_modules/@prestack/thread/dist/integrity/generators/gate.js',\n    describes: 'The generator of the gate chain — it reads every row that names a command and refuses one naming none, rather than writing a shorter gate.',\n    version: 1,\n    by: 'thread gate',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'compiler-generator',
+    source: "  {\n    id: 'compiler-generator',\n    at: 'node_modules/@prestack/thread/dist/integrity/generators/compiler.js',\n    describes: 'The generator of the compiler config — it walks this tree, leaves out every directory with nothing declared beneath it, and writes that list into the config as what the compiler may not read. It checks the same list before letting the compiler run, because a compile that was pointed at the wrong code is not a compile that passed.',\n    version: 1,\n    by: 'thread compiler',\n    runs: 'thread compiler --check',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'descent-runner',
+    source: "  {\n    id: 'descent-runner',\n    at: 'node_modules/@prestack/thread/dist/integrity/check-threads.js',\n    describes: 'The walk over everything this app tracks, refusing any file no row names. It runs before anything is built, so a file nothing declares stops the build rather than reaching a person.',\n    version: 1,\n    by: 'thread descent',\n    runs: 'thread descent',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'sweep-runner',
+    source: "  {\n    id: 'sweep-runner',\n    at: 'node_modules/@prestack/thread/dist/integrity/sweep.js',\n    describes: 'Every rule — the framework\\'s and this app\\'s own — run over the files it governs. A rule that could not run is named rather than counted as one that passed.',\n    version: 1,\n    by: 'thread sweep',\n    runs: 'thread sweep',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'issues-reader',
+    source: "  {\n    id: 'issues-reader',\n    at: 'node_modules/@prestack/thread/dist/integrity/generators/issues.js',\n    describes: 'Everything wrong with this tree in one listing: files no row declares, files that will not compile, and what the rules refuse. It only reports, so it answers even when every other check has stopped.',\n    version: 1,\n    by: 'thread issues',\n    runs: 'thread issues --check',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'publish-runner',
+    source: "  {\n    id: 'publish-runner',\n    at: 'node_modules/@prestack/thread/dist/integrity/generators/publish.js',\n    describes: 'Sends this repository\\'s packages to a registry. It derives what each package says about itself first, then builds, then refuses to send anything until the gate, the typecheck, the lint and the seal have each passed, and commits what it derived once the packages are out. The seal is checked rather than regenerated, because a release that rewrites its own seal can never fail it.',\n    version: 1,\n    by: 'thread publish',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'rule-noun',
+    source: "  {\n    id: 'rule-noun',\n    at: 'node_modules/@prestack/thread/dist/integrity/generators/rule.js',\n    describes: 'Declares a rule this app holds itself to. `thread create rule` writes the row and seeds the check beside it, so a new rule goes through the same wizard as everything else rather than being written by hand.',\n    version: 1,\n    by: 'thread create rule',\n  },",
+  },
+  {
+    into: 'derivation.ts',
+    list: 'GENERATORS',
+    id: 'seal-generator',
+    source: "  {\n    id: 'seal-generator',\n    at: 'node_modules/@prestack/thread/dist/integrity/generators/seal.js',\n    describes: 'Writes the seal: a hash of every built file the integrity package ships, so an installed copy can prove it is the one that went out. With --check it writes nothing and refuses a seal that no longer matches the built files.',\n    version: 1,\n    by: 'thread seal',\n    runs: 'thread seal --check',\n  },",
+  },
+]
+export const ATTACH: Attaching = {
+  attaches: SEEDED.attaches,
+  id: SEEDED.id,
+  declares: SEEDED.declares,
+  writes: [
+    { file: 'integrity.ts', source: INTEGRITY_SOURCE },
+    { file: 'rules.ts', source: RULES_SOURCE },
+    { file: 'gate.ts', source: GATE_SOURCE },
+  ],
+
+  retires: [
+    {
+      into: 'gate.ts',
+      list: 'declares',
+      id: 'compiler',
+      why: 'moved into `GENERATORS` beside the generator that writes it, which is what makes `tsconfig.json` settle when declarations move. Left here it would be a second gate step running the same command, which the gate refuses.',
+    },
+    {
+      into: 'gate.ts',
+      list: 'declares',
+      id: 'descent',
+      why: 'its step now comes from the `descent-runner` row this package ships into `GENERATORS`, which states `runs` beside `by`. Left here it would be a second gate step running the same command, which the gate refuses.',
+    },
+    {
+      into: 'gate.ts',
+      list: 'declares',
+      id: 'sweep',
+      why: 'its step now comes from the `sweep-runner` row this package ships into `GENERATORS`, which states `runs` beside `by`. Left here it would be a second gate step running the same command, which the gate refuses.',
+    },
+    {
+      into: 'constraint.ts',
+      list: 'GENERATORS',
+      id: 'sql-duplicate-id',
+      why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+    },
+    {
+      into: 'constraint.ts',
+      list: 'GENERATORS',
+      id: 'sql-name-collision',
+      why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+    },
+    {
+      into: 'constraint.ts',
+      list: 'GENERATORS',
+      id: 'sql-duplicate-parameter',
+      why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+    },
+    {
+      into: 'constraint.ts',
+      list: 'GENERATORS',
+      id: 'sql-unwritable-parameter-type',
+      why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+    },
+    {
+      into: 'constraint.ts',
+      list: 'GENERATORS',
+      id: 'sql-duplicate-returned-column',
+      why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+    },
+    {
+      into: 'constraint.ts',
+      list: 'GENERATORS',
+      id: 'sql-unwritable-return-type',
+      why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+    },
+    {
+      into: 'constraint.ts',
+      list: 'GENERATORS',
+      id: 'sql-unknown-write-target',
+      why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+    },
+    {
+      into: 'constraint.ts',
+      list: 'GENERATORS',
+      id: 'sql-multi-statement',
+      why: 'its check imported a package this framework no longer ships and read a folder no app has, so it could never refuse anything. A rule that cannot fire reads as coverage while enforcing nothing.',
+    },
+  ],
+
+  ignores: ['.thread/', '.next/', 'node_modules/', 'tsconfig.tsbuildinfo'],
+  scripts: {
+    gate: 'thread gate',
+    predev: 'thread gate',
+    dev: 'next dev',
+    prebuild: 'thread gate',
+    build: 'next build',
+    prestart: 'thread gate',
+    start: 'next start',
+  },
+
+  needs: {
+    '@types/node': '^24.0.0',
+    typescript: '^6.0.0',
+  },
+  rows: SHIPPED,
+}

package/dist/integrity/check-threads.js

@@ -1,35 +1,11 @@
-import { spawnSync } from 'node:child_process';
-import { readFileSync, readdirSync } from 'node:fs';
+import { readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { argv, stdout } from 'node:process';
 import { exit, invoked } from "../core/invoked.js";
-import { ROOT, THREAD_AT, TREE, configured, descend } from "../core/descend.js";
+import { ROOT, THREAD_AT, TREE, configured, descend, unkept } from "../core/descend.js";
 import { runChecker } from "../core/finding.js";
 export { ROOT, THREAD_AT, TREE, descend };
 const ELSEWHERE = new Set(['node_modules', '.git']);
-const OWN_IGNORES = (() => {
-    if (spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: ROOT, stdio: 'ignore' }).status === 0) {
-        return undefined;
-    }
-    try {
-        return readFileSync(join(ROOT, '.gitignore'), 'utf8')
-            .split('\n')
-            .map((one) => one.trim())
-            .filter((one) => one !== '' && !one.startsWith('#') && !one.startsWith('!'))
-            .map((one) => one.replace(/^\/+|\/+$/g, ''))
-            .filter((one) => one !== '' && !one.includes('*'));
-    }
-    catch {
-        return [];
-    }
-})();
-function unkept(at) {
-    if (OWN_IGNORES === undefined) {
-        const out = spawnSync('git', ['check-ignore', '-q', '--', at], { cwd: ROOT, stdio: 'ignore' });
-        return out.status === 0;
-    }
-    return OWN_IGNORES.some((one) => at === one || at.startsWith(`${one}/`) || at.split('/').includes(one));
-}
 export function trackedFiles() {
     const found = [];
     const walk = (at, under) => {

package/dist/integrity/check-threads.ts

@@ -0,0 +1,166 @@
+import { readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { argv, stdout } from 'node:process'
+
+import { exit, invoked } from '../core/invoked.ts'
+
+import { ROOT, THREAD_AT, TREE, configured, descend, unkept, type Finding, type Pass } from '../core/descend.ts'
+import { runChecker } from '../core/finding.ts'
+
+export { ROOT, THREAD_AT, TREE, descend }
+export type { Finding, Pass }
+
+const ELSEWHERE = new Set(['node_modules', '.git'])
+
+export function trackedFiles(): readonly string[] {
+  const found: string[] = []
+
+  const walk = (at: string, under: string): void => {
+    for (const one of readdirSync(at, { withFileTypes: true })) {
+      if (ELSEWHERE.has(one.name)) continue
+      const here = under === '' ? one.name : `${under}/${one.name}`
+      if (one.isDirectory()) {
+        if (unkept(here)) continue
+        walk(join(at, one.name), here)
+        continue
+      }
+      if (unkept(here)) continue
+      found.push(here)
+    }
+  }
+
+  walk(ROOT, '')
+  return found.sort()
+}
+
+export function unthreaded(pass: Pass, files: readonly string[]): readonly string[] {
+  return files.filter((one) => one !== THREAD_AT && !pass.threaded.has(one))
+}
+
+export function twiceParented(pass: Pass): readonly { readonly at: string; readonly parents: readonly string[] }[] {
+  const found: { at: string; parents: readonly string[] }[] = []
+  for (const [at, held] of pass.threaded) {
+    const parents = held.filter((one) => one.list === 'declares').map((one) => one.by)
+    if (parents.length > 1) found.push({ at, parents })
+  }
+  return found
+}
+
+export function refusals(pass: Pass, files: readonly string[]): readonly Finding[] {
+  const found: Finding[] = [...pass.broken, ...pass.findings]
+
+  const held = configured()
+  if (held.trouble !== undefined) {
+    found.push({
+      file: held.trouble.split(' ')[0] ?? 'tsconfig.json',
+      detail: `the gate fell back to its own compiler options because ${held.trouble}`,
+      instead:
+        'fix the config, or point the gate at one it can read. Falling back silently means declarations are judged by options nobody chose, and the run says none was found when one was',
+    })
+  }
+
+  return withFiles(found, pass, files)
+}
+
+function withFiles(found: Finding[], pass: Pass, files: readonly string[]): readonly Finding[] {
+
+  for (const one of unthreaded(pass, files)) {
+    const by = pass.mentioned.get(one) ?? []
+    if (by.length === 0) {
+      found.push({
+        file: one,
+        detail: 'nothing declares this — the descent from the root never reaches it, so it is not wired',
+        instead:
+          'add a row naming this path to the node that owns it, with all four fields, or delete the file. A file that nothing names is either somebody\'s child nobody wrote down, or it is nobody\'s',
+      })
+      continue
+    }
+    const cut = by.filter((one) => one !== THREAD_AT && !pass.threaded.has(one))
+    if (cut.length > 0) {
+      found.push({
+        file: one,
+        detail: `broken thread — ${cut.join(' and ')} names this, and nothing declares ${cut.length === 1 ? 'it' : 'them'}, so the descent never arrives`,
+        instead:
+          'thread the parent. The row is written and the file is where it says, but the line back to the root is cut above it, and nothing below the cut is reached',
+      })
+      continue
+    }
+    found.push({
+      file: one,
+      detail: `broken thread — ${by.join(' and ')} names this and is itself declared, and the descent still never arrived, so the row was read and never walked`,
+      instead:
+        'the cut is inside the parent, not above it. Its node answered its own parent with a shape that row does not state, so the descent refused it and stopped there — fix the shape the parent states, and everything under it joins up',
+    })
+  }
+
+  for (const one of twiceParented(pass)) {
+    found.push({
+      file: one.at,
+      detail: `declared by ${one.parents.join(' and ')} — declares is exactly one parent ever, so its owner, its shape and its origin each have two answers and the tree gives none`,
+      instead:
+        'keep the row that owns it and delete the other. If both are true, one of them is a `derives` or a `seeds`, which may have many parents because neither of them owns the child',
+    })
+  }
+
+  return found
+}
+
+if (invoked(import.meta.url)) {
+  const pass = await descend()
+  const tracked = trackedFiles()
+  const findings = refusals(pass, tracked)
+
+  if (argv.includes('--json')) {
+    stdout.write(`${JSON.stringify(findings)}\n`)
+    exit(0)
+  }
+
+  const fixed = [...pass.threaded.keys()]
+  const reach = new Map<string, number>()
+  for (const one of fixed) reach.set(dirname(one), (reach.get(dirname(one)) ?? 0) + 1)
+
+  const held = configured()
+  stdout.write(
+    `threads: descended ${String(pass.declarations)} declaration(s) over ${String(pass.rows)} row(s), naming ${String(fixed.length)} file(s) and coining ${String(pass.coined.size)} word(s).\n`,
+  )
+  stdout.write(
+    held.trouble !== undefined
+      ? `threads:   compiler options fallen back to — ${held.trouble}\n`
+      : held.from === ''
+        ? 'threads:   compiler options fallen back to — nothing at the root states a tsconfig, so what the build compiles with may differ from what judged this\n'
+        : `threads:   compiler options taken from ${held.from} at the root — what a package builds with may still differ from this\n`,
+  )
+  const here = new Set(tracked)
+  for (const [dir, held] of [...reach].sort()) {
+    const present = tracked.filter((one) => dirname(one) === dir).length
+    const mine = [...pass.threaded.keys()].filter((one) => dirname(one) === dir && here.has(one)).length
+    stdout.write(
+      present === 0
+        ? `threads:   ${dir} — ${String(held)} file(s) named, none of them tracked here\n`
+        : `threads:   ${dir} — ${String(mine)} of ${String(present)} tracked file(s) named\n`,
+    )
+  }
+
+  const named = [...pass.threaded.keys()].filter((one) => here.has(one)).length
+
+  runChecker(
+    'threads',
+    findings,
+    `${String(pass.declarations)} declaration(s), ${String(pass.rows)} row(s), ${String(named)} of ${String(tracked.length)} tracked file(s) named`,
+  )
+
+  const warned = findings.filter((one) => one.severity === 'warning')
+  const refused = findings.filter((one) => one.severity !== 'warning')
+
+  if (warned.length > 0) {
+    stdout.write(
+      `threads: ${String(warned.length)} of these is a derivation nothing has produced yet — the row states what a ` +
+        'generator would write and no file is there. A generator that refuses to write an empty file is doing its ' +
+        'job, so this is said rather than refused. A derived file that is there and differs from what its generator ' +
+        'writes is the other case, and that one fails.\n',
+    )
+  }
+
+  if (refused.length > 0) exit(1)
+  exit(0)
+}