@prestack/thread 0.0.1

package/dist/integrity/lint.js

@@ -0,0 +1,161 @@
+import { execFileSync } from 'node:child_process';
+import { Linter } from 'eslint';
+import tseslint from 'typescript-eslint';
+import { THING } from "../core/scope.js";
+import { CONSTRAINTS } from "./constraint.js";
+import { NOT_WRITTEN, governs, reads, visits, load, ROOT, rules as appRules, slopnatorName, } from "./slopnator.js";
+const PROBE = {
+    filename: 'probe.ts',
+    text: '',
+    ancestors: () => [],
+    comments: () => [],
+};
+export function ruleMessage(rule) {
+    const cites = (rule.cites ?? []).map((cite) => `${cite.on} — ${cite.said}`).join(' · ');
+    return cites === '' ? `${rule.bans} — ${rule.because}. Instead: ${rule.instead}.` : `${rule.bans} — ${rule.because}. Instead: ${rule.instead}. (${cites})`;
+}
+const oneLine = (text) => text.replace(/\s*\n\s*/g, ' ').trim();
+export function agentInstructions() {
+    return [...CONSTRAINTS]
+        .sort((one, two) => (one.id < two.id ? -1 : one.id > two.id ? 1 : 0))
+        .map((rule) => `${oneLine(rule.instead)} — never ${oneLine(rule.bans)}. Wrong: \`${oneLine(rule.wrong)}\`. Right: \`${oneLine(rule.right)}\`. [${rule.id}]`);
+}
+export function defineRule(rule, slopnators) {
+    const expected = slopnatorName(rule.id);
+    if (rule.where.paths.length === 0) {
+        throw new Error(`rule "${rule.id}" names no path, so it governs nothing. A rule that cannot fire is indistinguishable from a rule being obeyed.`);
+    }
+    const found = slopnators.get(expected);
+    if (found === undefined) {
+        throw new Error(`"${rule.id}" names "${expected}", and no such file is beside the tree or shipped with the package. ` +
+            'One that cannot run reads as enforced, reports nothing, and is indistinguishable from one being obeyed. ' +
+            'Seed it.');
+    }
+    return rule;
+}
+export function defineRules(slopnators) {
+    const seen = new Set();
+    for (const rule of GOVERNING) {
+        if (seen.has(rule.id))
+            throw new Error(`rule "${rule.id}" is declared twice in packages/core/src/integrity/constraint.ts`);
+        seen.add(rule.id);
+        defineRule(rule, slopnators);
+    }
+    return GOVERNING;
+}
+export function ruleRule(rule, slopnators) {
+    const slopnator = slopnators.get(slopnatorName(rule.id));
+    return {
+        meta: {
+            type: 'problem',
+            docs: { description: rule.bans },
+            schema: [],
+            ...(slopnator !== undefined && reads(slopnator) && slopnator.fixes !== undefined ? { fixable: 'code' } : {}),
+            messages: { broken: `${ruleMessage(rule)} Found: {{found}}.` },
+        },
+        create(context) {
+            if (!governs(rule, context.filename))
+                return {};
+            const found = slopnator;
+            if (found === undefined || !visits(found))
+                return {};
+            const visit = (node) => {
+                const at = {
+                    filename: context.filename,
+                    text: context.sourceCode.getText(),
+                    ancestors: () => context.sourceCode.getAncestors(node),
+                    comments: () => context.sourceCode.getAllComments().map((comment) => ({
+                        value: comment.value,
+                        range: (comment.range ?? [0, 0]),
+                    })),
+                };
+                const held = found.holds(node, at);
+                if (held === false || held === NOT_WRITTEN)
+                    return;
+                const mend = found.fixes;
+                const mended = mend === undefined ? undefined : mend(node, at);
+                context.report({
+                    node: node,
+                    messageId: 'broken',
+                    data: { found: typeof held === 'string' ? held : slopnatorName(rule.id) },
+                    ...(mended === undefined ? {} : { fix: (fixer) => fixer.replaceTextRange([0, at.text.length], mended) }),
+                });
+            };
+            return Object.fromEntries(found.on.map((type) => [type, visit]));
+        },
+    };
+}
+export function ruleRules(slopnators) {
+    return Object.fromEntries(GOVERNING.map((rule) => [rule.id, ruleRule(rule, slopnators)]));
+}
+export function ruleSeverities() {
+    return Object.fromEntries(GOVERNING.map((rule) => [`lint/${rule.id}`, rule.severity === 'warning' ? 'warn' : 'error']));
+}
+const GOVERNING = [...CONSTRAINTS, ...((await appRules()) ?? [])];
+const SLOPNATORS = await load(ROOT, GOVERNING);
+defineRules(SLOPNATORS);
+export const plugin = { rules: ruleRules(SLOPNATORS) };
+export default plugin;
+function ignored() {
+    try {
+        return execFileSync('git', ['ls-files', '--others', '--ignored', '--exclude-standard', '--directory'], {
+            cwd: ROOT,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .split('\n')
+            .filter(Boolean)
+            .map((one) => (one.endsWith('/') ? one + '**' : one));
+    }
+    catch {
+        return [];
+    }
+}
+export const rules = {
+    files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.mjs', '**/*.js'],
+    ignores: ignored(),
+    languageOptions: {
+        parser: tseslint.parser,
+        parserOptions: { ecmaVersion: 'latest', sourceType: 'module', ecmaFeatures: { jsx: true } },
+    },
+    plugins: { lint: plugin },
+    rules: ruleSeverities(),
+};
+export function ruleDeclarations() {
+    return [...CONSTRAINTS]
+        .sort((one, two) => (one.id < two.id ? -1 : one.id > two.id ? 1 : 0))
+        .map((rule) => ({ ...rule, name: rule.id }));
+}
+export function theRules() {
+    const linter = new Linter();
+    const declared = new Map(ruleDeclarations().map((one) => [one.name, one]));
+    const config = [
+        {
+            files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'],
+            linterOptions: { noInlineConfig: true },
+            languageOptions: {
+                parser: tseslint.parser,
+                parserOptions: { ecmaVersion: 'latest', sourceType: 'module', ecmaFeatures: { jsx: true } },
+            },
+            plugins: { [`@${THING}`]: plugin },
+            rules: Object.fromEntries(GOVERNING.map((rule) => [`@${THING}/${rule.id}`, rule.severity === 'warning' ? 'warn' : 'error'])),
+        },
+    ];
+    return (file, source) => linter
+        .verify(source, config, file)
+        .filter((message) => message.ruleId != null)
+        .map((message) => {
+        const rule = String(message.ruleId).replace(`@${THING}/`, '');
+        const found = declared.get(rule);
+        return {
+            file,
+            line: message.line,
+            column: message.column,
+            rule,
+            message: message.message,
+            ...(found === undefined
+                ? {}
+                : { bans: found.bans, instead: found.instead, wrong: found.wrong, right: found.right }),
+        };
+    });
+}

package/dist/integrity/lsp/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/integrity/lsp/bin.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { cwd, exit, stderr, stdin, stdout } from 'node:process';
+import { repoSource } from "./diagnostics.js";
+import { encode, MessageBuffer } from "./protocol.js";
+import { LspServer } from "./server.js";
+const server = new LspServer({
+    root: cwd(),
+    sourceFor: repoSource,
+    send: (message) => stdout.write(encode(message)),
+});
+const buffer = new MessageBuffer();
+let queue = Promise.resolve();
+const fatal = (error) => {
+    stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    exit(1);
+};
+stdin.on('data', (chunk) => {
+    let messages;
+    try {
+        messages = buffer.push(chunk);
+    }
+    catch (error) {
+        fatal(error);
+        return;
+    }
+    for (const message of messages) {
+        queue = queue.then(async () => {
+            await server.handle(message);
+            if (server.exited)
+                exit(server.exitCode);
+        });
+        queue.catch(fatal);
+    }
+});
+stdin.on('end', () => exit(server.exitCode));

package/dist/integrity/lsp/diagnostics.d.ts

@@ -0,0 +1,25 @@
+import { type Finding } from './findings.ts';
+export interface DiagnosticSource {
+    lint(relative: string, text: string): Promise<readonly Finding[]>;
+    read(relative: string): string | null;
+}
+export declare function repoSource(root: string): DiagnosticSource;
+export declare const ERROR = 1;
+export declare const WARNING = 2;
+export interface Position {
+    readonly line: number;
+    readonly character: number;
+}
+export interface Diagnostic {
+    readonly range: {
+        readonly start: Position;
+        readonly end: Position;
+    };
+    readonly severity: typeof ERROR | typeof WARNING;
+    readonly source: string;
+    readonly code: string;
+    readonly message: string;
+}
+export declare const SOURCE_NAME = "thread";
+export declare function toDiagnostic(finding: Finding, text: string): Diagnostic;
+export declare function report(source: DiagnosticSource, open: ReadonlyMap<string, string>, previous?: ReadonlySet<string>): Promise<ReadonlyMap<string, readonly Diagnostic[]>>;

package/dist/integrity/lsp/diagnostics.js

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { detailOf, rangeOf } from "./findings.js";
+import { lintFindings } from "./lint.js";
+export function repoSource(root) {
+    return {
+        lint: (relative, text) => lintFindings(root, relative, text),
+        read: (relative) => {
+            try {
+                return readFileSync(join(root, relative), 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+export const ERROR = 1;
+export const WARNING = 2;
+export const SOURCE_NAME = 'thread';
+export function toDiagnostic(finding, text) {
+    const at = rangeOf(finding, text);
+    return {
+        range: {
+            start: { line: at.line - 1, character: at.column - 1 },
+            end: { line: (at.endLine ?? at.line) - 1, character: (at.endColumn ?? at.column) - 1 },
+        },
+        severity: finding.severity === 'error' ? ERROR : WARNING,
+        source: SOURCE_NAME,
+        code: finding.check,
+        message: detailOf(finding),
+    };
+}
+export async function report(source, open, previous = new Set()) {
+    const findings = [];
+    for (const [relative, text] of open) {
+        findings.push(...(await source.lint(relative, text)));
+    }
+    const byFile = new Map();
+    for (const finding of findings) {
+        const bucket = byFile.get(finding.file);
+        if (bucket === undefined)
+            byFile.set(finding.file, [finding]);
+        else
+            bucket.push(finding);
+    }
+    const published = new Map();
+    for (const [relative, group] of byFile) {
+        const text = open.get(relative) ?? source.read(relative) ?? '';
+        published.set(relative, group.map((finding) => toDiagnostic(finding, text)));
+    }
+    for (const relative of [...previous, ...open.keys()]) {
+        if (!published.has(relative))
+            published.set(relative, []);
+    }
+    return published;
+}

package/dist/integrity/lsp/findings.d.ts

@@ -0,0 +1,20 @@
+export interface At {
+    readonly line: number;
+    readonly column: number;
+    readonly endLine?: number;
+    readonly endColumn?: number;
+}
+export interface Finding {
+    readonly severity: 'error' | 'warning';
+    readonly check: string;
+    readonly detail: string;
+    readonly file: string;
+    readonly at?: At;
+    readonly anchor?: string;
+    readonly suggestions?: readonly string[];
+}
+export declare function detailOf(finding: Finding): string;
+export declare function anchorIn(detail: string): string | undefined;
+export declare function locate(text: string, anchor: string): At | undefined;
+export declare function headOf(text: string): At;
+export declare function rangeOf(finding: Finding, text: string): At;

package/dist/integrity/lsp/findings.js

@@ -0,0 +1,39 @@
+export function detailOf(finding) {
+    const offered = finding.suggestions ?? [];
+    return offered.length === 0 ? finding.detail : `${finding.detail} ${offered.join(' ')}`;
+}
+const DECLARED_ID = /\b[a-z]{2,6}_[a-z][a-z0-9_]*\b/g;
+export function anchorIn(detail) {
+    const candidates = [
+        ...(detail.match(DECLARED_ID) ?? []),
+        ...[...detail.matchAll(/"([a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_*]+)+)"/g)].map((m) => m[1]),
+    ];
+    if (candidates.length === 0)
+        return undefined;
+    return candidates.reduce((longest, one) => (one.length > longest.length ? one : longest));
+}
+export function locate(text, anchor) {
+    const lines = text.split('\n');
+    for (const [index, line] of lines.entries()) {
+        const column = line.indexOf(anchor);
+        if (column === -1)
+            continue;
+        return {
+            line: index + 1,
+            column: column + 1,
+            endLine: index + 1,
+            endColumn: column + 1 + anchor.length,
+        };
+    }
+    return undefined;
+}
+export function headOf(text) {
+    const first = text.split('\n')[0] ?? '';
+    return { line: 1, column: 1, endLine: 1, endColumn: Math.max(first.length, 1) + 1 };
+}
+export function rangeOf(finding, text) {
+    if (finding.at !== undefined)
+        return finding.at;
+    const anchor = finding.anchor ?? anchorIn(finding.detail);
+    return (anchor === undefined ? undefined : locate(text, anchor)) ?? headOf(text);
+}

package/dist/integrity/lsp/lint.d.ts

@@ -0,0 +1,7 @@
+import type { Finding } from './findings.ts';
+export declare const isLintable: (relative: string) => boolean;
+export declare const LINT_CONFIG = "eslint.config.js";
+export declare class LintUnavailableError extends Error {
+    constructor(detail: string);
+}
+export declare function lintFindings(root: string, relative: string, text: string): Promise<readonly Finding[]>;

package/dist/integrity/lsp/lint.js

@@ -0,0 +1,95 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { theRules } from "../lint.js";
+const LINTABLE = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs', '.jsx']);
+export const isLintable = (relative) => LINTABLE.has(extname(relative));
+export const LINT_CONFIG = 'eslint.config.js';
+export class LintUnavailableError extends Error {
+    constructor(detail) {
+        super(`ESLint could not be run over this repository: ${detail}. This server reports what the build ` +
+            'computes, so a lint pass that answered "no problems" because it never ran would be ' +
+            'indistinguishable from a clean file — which is the one thing it must never be.');
+        this.name = 'LintUnavailableError';
+    }
+}
+function binaryIn(root) {
+    const local = join(root, 'node_modules', '.bin', 'eslint');
+    return existsSync(local) ? local : undefined;
+}
+async function ruleFindings(relative, text) {
+    const rules = theRules();
+    return rules(relative, text).map((violation) => ({
+        severity: 'error',
+        check: violation.rule,
+        detail: violation.bans ?? violation.message,
+        file: relative,
+        at: { line: violation.line, column: violation.column },
+        suggestions: [
+            ...(violation.instead === undefined ? [] : [violation.instead]),
+            ...(violation.right === undefined ? [] : [`Write: ${violation.right}`]),
+        ],
+    }));
+}
+const suggestionsOf = (message) => (message.suggestions ?? []).map((one) => one.desc).filter((desc) => desc !== undefined);
+export async function lintFindings(root, relative, text) {
+    if (!isLintable(relative))
+        return [];
+    if (!existsSync(join(root, LINT_CONFIG)))
+        return await ruleFindings(relative, text);
+    const binary = binaryIn(root);
+    if (binary === undefined) {
+        return [
+            {
+                severity: 'error',
+                check: 'lint:unavailable',
+                detail: `${LINT_CONFIG} is here and node_modules/.bin/eslint is not, so none of this repository's ` +
+                    'rules are being checked while you type. Install the dev dependencies.',
+                file: LINT_CONFIG,
+            },
+        ];
+    }
+    const report = await runEslint(binary, root, relative, text);
+    return report.flatMap((file) => (file.messages ?? []).map((message) => ({
+        severity: message.severity === 2 ? 'error' : 'warning',
+        check: message.ruleId ?? 'lint',
+        detail: message.message,
+        file: relative,
+        at: {
+            line: message.line ?? 1,
+            column: message.column ?? 1,
+            ...(message.endLine === undefined ? {} : { endLine: message.endLine }),
+            ...(message.endColumn === undefined ? {} : { endColumn: message.endColumn }),
+        },
+        ...(suggestionsOf(message).length === 0 ? {} : { suggestions: suggestionsOf(message) }),
+    })));
+}
+function runEslint(binary, root, relative, text) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(binary, ['--format', 'json', '--no-warn-ignored', '--stdin', '--stdin-filename', relative], {
+            cwd: root,
+            shell: false,
+        });
+        let out = '';
+        let err = '';
+        child.stdout.on('data', (chunk) => (out += chunk.toString()));
+        child.stderr.on('data', (chunk) => (err += chunk.toString()));
+        child.on('error', (error) => reject(new LintUnavailableError(error.message)));
+        child.on('close', () => {
+            let parsed;
+            try {
+                parsed = JSON.parse(out);
+            }
+            catch {
+                reject(new LintUnavailableError(err.trim() === '' ? `it wrote ${out.length} bytes of non-JSON` : err.trim()));
+                return;
+            }
+            if (!Array.isArray(parsed)) {
+                reject(new LintUnavailableError('its JSON report was not an array of files'));
+                return;
+            }
+            resolve(parsed);
+        });
+        child.stdin.end(text);
+    });
+}

package/dist/integrity/lsp/protocol.d.ts

@@ -0,0 +1,20 @@
+export interface RpcMessage {
+    readonly jsonrpc: '2.0';
+    readonly id?: number | string | null;
+    readonly method?: string;
+    readonly params?: unknown;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: number;
+        readonly message: string;
+    };
+}
+export declare const METHOD_NOT_FOUND = -32601;
+export declare function encode(message: RpcMessage): Buffer;
+export declare class MalformedMessageError extends Error {
+    constructor(detail: string);
+}
+export declare class MessageBuffer {
+    #private;
+    push(chunk: Buffer): readonly RpcMessage[];
+}

package/dist/integrity/lsp/protocol.js

@@ -0,0 +1,57 @@
+const HEADER_END = '\r\n\r\n';
+export const METHOD_NOT_FOUND = -32601;
+export function encode(message) {
+    const body = Buffer.from(JSON.stringify(message), 'utf8');
+    return Buffer.concat([Buffer.from(`Content-Length: ${body.length}${HEADER_END}`, 'ascii'), body]);
+}
+export class MalformedMessageError extends Error {
+    constructor(detail) {
+        super(`the editor sent something this server cannot parse: ${detail}. ` +
+            'A language server that skipped it would answer the next request against a stream it no ' +
+            'longer understands, which reads as a file with no problems.');
+        this.name = 'MalformedMessageError';
+    }
+}
+export class MessageBuffer {
+    #pending = Buffer.alloc(0);
+    push(chunk) {
+        this.#pending = Buffer.concat([this.#pending, chunk]);
+        const found = [];
+        for (;;) {
+            const split = this.#pending.indexOf(HEADER_END, 0, 'ascii');
+            if (split === -1)
+                return found;
+            const header = this.#pending.subarray(0, split).toString('ascii');
+            const length = contentLength(header);
+            const start = split + HEADER_END.length;
+            if (this.#pending.length < start + length)
+                return found;
+            const body = this.#pending.subarray(start, start + length).toString('utf8');
+            this.#pending = this.#pending.subarray(start + length);
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                throw new MalformedMessageError(`a ${length}-byte body that is not JSON`);
+            }
+            if (typeof parsed !== 'object' || parsed === null) {
+                throw new MalformedMessageError(`a ${length}-byte body that is not a JSON object`);
+            }
+            found.push(parsed);
+        }
+    }
+}
+function contentLength(header) {
+    for (const line of header.split('\r\n')) {
+        const [name, value] = line.split(':', 2);
+        if (name?.trim().toLowerCase() !== 'content-length')
+            continue;
+        const length = Number.parseInt((value ?? '').trim(), 10);
+        if (!Number.isInteger(length) || length < 0) {
+            throw new MalformedMessageError(`Content-Length: ${(value ?? '').trim()}`);
+        }
+        return length;
+    }
+    throw new MalformedMessageError(`a header block with no Content-Length: ${JSON.stringify(header)}`);
+}

package/dist/integrity/lsp/server.d.ts

@@ -0,0 +1,15 @@
+import { type DiagnosticSource } from './diagnostics.ts';
+import { type RpcMessage } from './protocol.ts';
+export interface ServerOptions {
+    readonly root: string;
+    readonly sourceFor: (root: string) => DiagnosticSource;
+    send(message: RpcMessage): void;
+    settle?(): Promise<void>;
+}
+export declare class LspServer {
+    #private;
+    constructor(options: ServerOptions);
+    get exited(): boolean;
+    get exitCode(): number;
+    handle(message: RpcMessage): Promise<void>;
+}