@prestack/thread 0.0.1

package/dist/integrity/slopnators/sl_unthreaded.js

@@ -0,0 +1,352 @@
+import { parser } from 'typescript-eslint';
+import { descend, forget as forgetDescent, read, reached as fromThread, threading } from "../../core/descend.js";
+import { findTree } from "../../core/tree.js";
+const TREE_AT = findTree();
+const ROOT = `${TREE_AT.at.split('\\').join('/')}/`;
+const TREE = TREE_AT.name;
+const THREAD_AT = `${TREE_AT.name}/thread.ts`;
+const FOLLOWABLE = /\.(ts|tsx|mts|cts|mjs|cjs|js)$/;
+const LISTS = new Set(['declares', 'derives', 'seeds']);
+let threaders;
+let tree;
+const parsed = new Map();
+const broke = new Map();
+const SAID = new Set(['at', 'id', 'describes']);
+const keyOf = (property) => {
+    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;
+};
+function annotated(node) {
+    let held = node.id?.typeAnnotation?.typeAnnotation;
+    while (held !== undefined && (held.type === 'TSArrayType' || held.type === 'TSTypeOperator')) {
+        held = held.elementType ?? held.typeAnnotation;
+    }
+    return held?.typeName?.name;
+}
+export const here = (filename) => {
+    const path = filename.split('\\').join('/');
+    return path.startsWith(ROOT) ? path.slice(ROOT.length) : path;
+};
+function rows(node, list, found, hoisted) {
+    for (const one of node.elements ?? []) {
+        const element = one?.type === 'Identifier' && one.name !== undefined ? hoisted.get(one.name) : one;
+        if (element === null || element === undefined || element.type !== 'ObjectExpression')
+            continue;
+        const said = {};
+        for (const property of element.properties ?? []) {
+            const key = keyOf(property);
+            const held = property.value;
+            if (key !== undefined && SAID.has(key) && held?.type === 'Literal' && typeof held.value === 'string') {
+                said[key] = held.value;
+            }
+            if ((key === 'governs' || key === 'wears') && held?.type === 'ArrayExpression') {
+                said[key] = (held.elements ?? [])
+                    .map((one) => (one?.type === 'Literal' && typeof one.value === 'string' ? one.value : undefined))
+                    .filter((one) => one !== undefined);
+            }
+            if (key !== undefined && LISTS.has(key) && held?.type === 'ArrayExpression')
+                rows(held, key, found, hoisted);
+        }
+        if (said.at !== undefined || said.id !== undefined)
+            found.push({ list, ...said });
+    }
+}
+function reaching(text) {
+    const already = parsed.get(text);
+    if (already !== undefined)
+        return already;
+    const types = threading();
+    const found = [];
+    const parse = (jsx) => parser.parseForESLint(text, {
+        range: true,
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        ecmaFeatures: { jsx },
+    });
+    const read = (() => {
+        try {
+            return parse(true);
+        }
+        catch {
+            try {
+                return parse(false);
+            }
+            catch (error) {
+                broke.set(text, error instanceof Error ? (error.message.split('\n')[0] ?? error.message) : String(error));
+                return undefined;
+            }
+        }
+    })();
+    if (read === undefined) {
+        parsed.set(text, found);
+        return found;
+    }
+    const body = read.ast.body ?? [];
+    const hoisted = new Map();
+    for (const statement of body) {
+        const held = statement.declaration ?? statement;
+        if (held.type !== 'VariableDeclaration')
+            continue;
+        for (const one of held.declarations ?? []) {
+            const name = one.id?.name;
+            if (name !== undefined && one.init?.type === 'ObjectExpression')
+                hoisted.set(name, one.init);
+        }
+    }
+    for (const statement of body) {
+        const held = statement.declaration ?? statement;
+        if (held.type !== 'VariableDeclaration' || held.kind !== 'const')
+            continue;
+        for (const one of held.declarations ?? []) {
+            if (!types.has(annotated(one) ?? ''))
+                continue;
+            const init = one.init;
+            for (const node of init?.type === 'ArrayExpression' ? (init.elements ?? []) : [init]) {
+                if (node === null || node === undefined || node.type !== 'ObjectExpression')
+                    continue;
+                const said = {};
+                for (const property of node.properties ?? []) {
+                    const key = keyOf(property);
+                    const value = property.value;
+                    if ((key === 'id' || key === 'describes') && value?.type === 'Literal' && typeof value.value === 'string')
+                        said[key] = value.value;
+                    if (key === 'version' && value?.type === 'Literal' && typeof value.value === 'number')
+                        said.version = value.value;
+                    if (key !== undefined && LISTS.has(key) && value?.type === 'ArrayExpression')
+                        rows(value, key, found, hoisted);
+                }
+                if (said.id !== undefined)
+                    found.push({ ...said });
+            }
+        }
+    }
+    parsed.set(text, found);
+    return found;
+}
+export function atsIn(text, only) {
+    const found = [];
+    for (const one of reaching(text)) {
+        if (only !== undefined && (one.list === undefined || !only.has(one.list)))
+            continue;
+        if (one.at !== undefined)
+            found.push(one.at);
+    }
+    return found;
+}
+export const rowsIn = (text) => reaching(text);
+const SCHEMA = /^export const ([A-Za-z]+)IslandSchema\b/m;
+const DEFINE = /^export function (define[A-Za-z]+)\s*\(/m;
+export function governedBy(one) {
+    if (one.includes('*')) {
+        const cut = one.lastIndexOf('/', one.indexOf('*'));
+        return { kind: 'pattern', matching: one, under: cut === -1 ? '' : one.slice(0, cut + 1) };
+    }
+    if (one.endsWith('/'))
+        return { kind: 'folder', under: one };
+    return { kind: 'file', at: one };
+}
+export const filesGoverned = (all) => all.map(governedBy).flatMap((one) => (one.kind === 'file' ? [one.at] : []));
+export const foldersGoverned = (all) => all.map(governedBy).flatMap((one) => (one.kind === 'file' ? [] : [one.under]));
+export function governs(all, path) {
+    return all.map(governedBy).some((one) => {
+        if (one.kind === 'file')
+            return path === one.at;
+        if (one.kind === 'folder')
+            return path.startsWith(one.under);
+        const tail = one.matching.slice(one.under.length).split('*').filter(Boolean);
+        const rest = path.startsWith(one.under) ? path.slice(one.under.length) : undefined;
+        return rest !== undefined && tail.every((part) => rest.includes(part));
+    });
+}
+export function islandsDeclared() {
+    const found = [];
+    const seen = new Set();
+    const all = [];
+    for (const at of fromThread()) {
+        const held = read(at);
+        if (held === undefined)
+            continue;
+        if (unreadable(at, held) !== undefined)
+            continue;
+        all.push(...reaching(held));
+    }
+    for (const row of all) {
+        if (row.id === undefined || row.at === undefined || seen.has(row.at))
+            continue;
+        const source = read(row.at);
+        if (source === undefined || !SCHEMA.test(source))
+            continue;
+        seen.add(row.at);
+        const tree = `${TREE}/${row.id}.ts`;
+        const named = all.find((one) => one.at === tree)?.id;
+        found.push({
+            id: row.id,
+            at: row.at,
+            describes: row.describes ?? '',
+            governs: row.governs ?? [],
+            define: DEFINE.exec(source)?.[1],
+            ...(named === undefined ? {} : { tree, member: named }),
+        });
+    }
+    return found;
+}
+export const declaresIsland = (text) => SCHEMA.exec(text)?.[1];
+export function meaningsIn(text) {
+    const found = [];
+    for (const one of reaching(text)) {
+        if (one.id === undefined)
+            continue;
+        found.push({ id: one.id, describes: one.describes ?? '' });
+    }
+    return found;
+}
+function descended() {
+    const pass = descend();
+    const reached = new Set([THREAD_AT, ...pass.threaded.keys()]);
+    const declared = new Map();
+    for (const [at, held] of pass.threaded)
+        declared.set(at, held.filter((one) => one.list === 'declares').length);
+    const meanings = new Map();
+    for (const [word, held] of pass.coined)
+        meanings.set(word, new Set(held.said));
+    return { reached, declared, meanings };
+}
+export function index() {
+    tree ??= descended();
+    return tree;
+}
+export function forget() {
+    parsed.clear();
+    broke.clear();
+    threaders = undefined;
+    tree = undefined;
+    forgetDescent();
+}
+export const threaded = () => index().reached;
+export const parses = (path) => FOLLOWABLE.test(path);
+export function unreadable(path, text) {
+    if (!parses(path))
+        return undefined;
+    atsIn(text);
+    const said = broke.get(text);
+    if (said === undefined)
+        return undefined;
+    return `this file cannot be parsed, so no law that reads its structure measured anything on it — ${said}`;
+}
+export const names = (path, text) => (parses(path) ? atsIn(text) : []);
+export const slopnator = {
+    holds: (_node, at) => {
+        const path = here(at.filename);
+        if (path === THREAD_AT)
+            return false;
+        const why = unreadable(path, at.text);
+        if (why !== undefined)
+            return why;
+        const pass = descend();
+        if (pass.threaded.has(path))
+            return false;
+        if (names(path, at.text).length > 0)
+            return false;
+        const by = pass.mentioned.get(path) ?? [];
+        const cut = by.filter((one) => one !== THREAD_AT && !pass.threaded.has(one));
+        if (cut.length > 0) {
+            return `broken thread — ${cut.join(' and ')} names ${path}, and nothing declares ${cut.length === 1 ? 'it' : 'them'}, so the descent from ${THREAD_AT} never arrives`;
+        }
+        if (by.length > 0) {
+            return `broken thread — ${by.join(' and ')} names ${path} and is itself declared, and the descent still never arrived, so the row was read and never walked`;
+        }
+        return `nothing that traces back to ${TREE}/ names ${path}, so the descent from ${THREAD_AT} never reaches it`;
+    },
+    proves: {
+        wrong: [
+            'export const ORPHAN = 2',
+            'export const LOOSE = { id: 2 }',
+            {
+                files: [
+                    { at: 'threads/_names_it.ts', source: "export const OWNER = {\n  declares: [\n    {\n      at: 'scripts/_probe_bare.ts',\n    },\n  ],\n}\n" },
+                    { at: 'scripts/_probe_bare.ts', source: 'export const CHILD = 1\n' },
+                ],
+                at: 'scripts/_probe_bare.ts',
+            },
+            {
+                files: [
+                    {
+                        at: 'threads/_names_it.ts',
+                        source: "export const REAL: Threaded = {\n  declares: [\n    {\n      at: 'threads/_names_it.ts',\n    },\n  ],\n}\n\nexport const BARE = {\n  declares: [\n    {\n      at: 'scripts/_probe_after.ts',\n    },\n  ],\n}\n",
+                    },
+                    { at: 'scripts/_probe_after.ts', source: 'export const CHILD = 1\n' },
+                ],
+                at: 'scripts/_probe_after.ts',
+            },
+            {
+                files: [
+                    { at: 'threads/_names_it.ts', source: "export let LOOSE = {\n  declares: [\n    {\n      at: 'scripts/_probe_let.ts',\n    },\n  ],\n}\n" },
+                    { at: 'scripts/_probe_let.ts', source: 'export const CHILD = 1\n' },
+                ],
+                at: 'scripts/_probe_let.ts',
+            },
+            {
+                files: [
+                    { at: 'threads/_names_it.ts', source: "export var LOOSE = {\n  declares: [\n    {\n      at: 'scripts/_probe_var.ts',\n    },\n  ],\n}\n" },
+                    { at: 'scripts/_probe_var.ts', source: 'export const CHILD = 1\n' },
+                ],
+                at: 'scripts/_probe_var.ts',
+            },
+            {
+                files: [
+                    { at: 'threads/_names_it.ts', source: "export default {\n  declares: [\n    {\n      at: 'scripts/_probe_default.ts',\n    },\n  ],\n}\n" },
+                    { at: 'scripts/_probe_default.ts', source: 'export const CHILD = 1\n' },
+                ],
+                at: 'scripts/_probe_default.ts',
+            },
+            {
+                files: [
+                    { at: 'threads/_names_it.ts', source: "export function held() {\n  return {\n    declares: [\n      {\n        at: 'scripts/_probe_fn.ts',\n      },\n    ],\n  }\n}\n" },
+                    { at: 'scripts/_probe_fn.ts', source: 'export const CHILD = 1\n' },
+                ],
+                at: 'scripts/_probe_fn.ts',
+            },
+            {
+                files: [
+                    { at: 'threads/_names_it.ts', source: "export class Held {\n  held = {\n    declares: [\n      {\n        at: 'scripts/_probe_class.ts',\n      },\n    ],\n  }\n}\n" },
+                    { at: 'scripts/_probe_class.ts', source: 'export const CHILD = 1\n' },
+                ],
+                at: 'scripts/_probe_class.ts',
+            },
+            {
+                files: [
+                    {
+                        at: 'threads/_names_it.ts',
+                        source: "interface Held { declares: unknown[] }\nexport const FAKE: Held = {\n  declares: [\n    {\n      at: 'scripts/_probe_fake.ts',\n    },\n  ],\n}\n",
+                    },
+                    { at: 'scripts/_probe_fake.ts', source: 'export const CHILD = 1\n' },
+                ],
+                at: 'scripts/_probe_fake.ts',
+            },
+        ],
+        right: [
+            "export const HELD: Threaded = {\n  declares: [\n    {\n      at: 'threads/probe.tsx',\n    },\n  ],\n}",
+            {
+                files: [
+                    { at: 'threads/_names_it.ts', source: "export const OWNER: Threaded = {\n  declares: [\n    {\n      at: 'scripts/_probe_child.ts',\n    },\n  ],\n}\n" },
+                    { at: 'scripts/_probe_child.ts', source: 'export const CHILD = 1\n' },
+                ],
+                at: 'scripts/_probe_child.ts',
+            },
+            {
+                files: [
+                    { at: 'threads/_names_it.ts', source: "export const OWNER: Threaded = {\n  declares: [\n    {\n      at: 'scripts/_probe_parent.ts',\n    },\n  ],\n}\n" },
+                    { at: 'scripts/_probe_parent.ts', source: "export const MID: Threaded = {\n  declares: [\n    {\n      at: 'scripts/_probe_leaf.ts',\n    },\n  ],\n}\n" },
+                    { at: 'scripts/_probe_leaf.ts', source: 'export const LEAF = 1\n' },
+                ],
+                at: 'scripts/_probe_leaf.ts',
+            },
+        ],
+    },
+};

package/dist/integrity/slopnators/sl_untranslated_key.d.ts

@@ -0,0 +1,2 @@
+import type { Slopnator } from '../slopnator.ts';
+export declare const slopnator: Slopnator;

package/dist/integrity/slopnators/sl_untranslated_key.js

@@ -0,0 +1,157 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { named as packageOf } from "../../core/scope.js";
+/*
+ * 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, found = []) {
+    let entries;
+    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) {
+    const found = new Set();
+    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) {
+    const at = join(root, '_threads', 'localizations.ts');
+    if (!existsSync(at))
+        return { held: [], source: undefined };
+    const text = readFileSync(at, 'utf8');
+    const held = [];
+    let source;
+    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 = {
+    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();
+        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 = [];
+        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;
+            try {
+                wording = JSON.parse(readFileSync(at, 'utf8'));
+            }
+            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.d.ts

@@ -0,0 +1,2 @@
+import type { Slopnator } from '../slopnator.ts';
+export declare const slopnator: Slopnator;

package/dist/integrity/slopnators/sl_unversioned.js

@@ -0,0 +1,31 @@
+import { here, parses, rowsIn } from "./sl_unthreaded.js";
+export const slopnator = {
+    holds: (_node, at) => {
+        const path = here(at.filename);
+        if (!parses(path))
+            return false;
+        let governing;
+        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.d.ts

@@ -0,0 +1,24 @@
+import { type Constraint } from './constraint.ts';
+import { type Slopnator, type Spoken } from './slopnator.ts';
+interface Node {
+    readonly type?: string;
+    readonly comments?: readonly Spoken[];
+    readonly [key: string]: unknown;
+}
+export declare function visit(root: Node, on: ReadonlySet<string>, each: (node: Node, ancestors: readonly Node[]) => void): void;
+export interface Caught {
+    readonly rule: string;
+    readonly file: string;
+    readonly found: string;
+}
+export declare function tracked(root: string): readonly string[];
+export declare 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[];
+};
+export {};