@gost-kit/eslint-plugin 0.0.0-stage → 0.2.0

package/dist/lib/ui-handlers.js

@@ -0,0 +1,84 @@
+import { AST_NODE_TYPES, } from '@typescript-eslint/utils';
+import { findValueVariable } from './value-variable.js';
+import { inScript } from './svelte-scripts.js';
+export const createUiHandlerCollector = (source, scripts) => {
+    const handlers = new Set();
+    const resolve = (node, inline, seen) => {
+        if (node.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+            node.type === AST_NODE_TYPES.FunctionExpression ||
+            node.type === AST_NODE_TYPES.FunctionDeclaration) {
+            return inline || inScript(node, scripts) ? node : undefined;
+        }
+        if (node.type === AST_NODE_TYPES.TSSatisfiesExpression ||
+            node.type === AST_NODE_TYPES.TSAsExpression ||
+            node.type === AST_NODE_TYPES.TSTypeAssertion ||
+            node.type === AST_NODE_TYPES.TSNonNullExpression ||
+            node.type === AST_NODE_TYPES.ChainExpression) {
+            return resolve(node.expression, inline, seen);
+        }
+        if (node.type !== AST_NODE_TYPES.Identifier) {
+            return undefined;
+        }
+        const variable = findValueVariable(source.getScope(node), node.name);
+        if (!variable ||
+            seen.has(variable) ||
+            variable.references.some((reference) => {
+                return reference.isWrite() && !reference.init;
+            })) {
+            return undefined;
+        }
+        const next = new Set(seen).add(variable);
+        return variable.defs
+            .map((definition) => {
+            if (definition.type === 'FunctionName' &&
+                definition.node.type === AST_NODE_TYPES.FunctionDeclaration) {
+                return resolve(definition.node, false, next);
+            }
+            if (definition.type === 'Variable' &&
+                definition.parent.kind === 'const' &&
+                definition.node.id.type === AST_NODE_TYPES.Identifier &&
+                definition.node.init) {
+                return resolve(definition.node.init, false, next);
+            }
+            return undefined;
+        })
+            .find((handler) => {
+            return !!handler;
+        });
+    };
+    const add = (expression) => {
+        const handler = resolve(expression, true, new Set());
+        if (handler) {
+            handlers.add(handler);
+        }
+    };
+    return {
+        handlers,
+        attribute(node) {
+            // Parser-specific listeners are the only boundary for extended Svelte nodes.
+            const attribute = node;
+            if (!attribute.key.name.startsWith('on') ||
+                attribute.key.name.length <= 2) {
+                return;
+            }
+            attribute.value.forEach((value) => {
+                if (value.type === 'SvelteMustacheTag') {
+                    add(value.expression);
+                }
+            });
+        },
+        shorthand(node) {
+            const attribute = node;
+            if (attribute.key.name.startsWith('on') &&
+                attribute.key.name.length > 2) {
+                add(attribute.value);
+            }
+        },
+        directive(node) {
+            const directive = node;
+            if (directive.kind === 'EventHandler' && directive.expression) {
+                add(directive.expression);
+            }
+        },
+    };
+};

package/dist/lib/value-variable.d.ts

@@ -0,0 +1,2 @@
+import { type TSESLint } from '@typescript-eslint/utils';
+export declare const findValueVariable: (initialScope: TSESLint.Scope.Scope, name: string) => import("@typescript-eslint/scope-manager").Variable | undefined;

package/dist/lib/value-variable.js

@@ -0,0 +1,25 @@
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+// A nearer type-only declaration does not shadow a runtime value in an outer scope.
+export const findValueVariable = (initialScope, name) => {
+    for (let scope = initialScope; scope; scope = scope.upper) {
+        const variable = scope.set.get(name);
+        // Plain JavaScript parsers do not supply the TypeScript namespace flag.
+        if (variable &&
+            variable.isValueVariable !== false &&
+            (variable.defs.length === 0 ||
+                variable.defs.some((definition) => {
+                    if (definition.isVariableDefinition === false) {
+                        return false;
+                    }
+                    if (definition.type !== 'ImportBinding') {
+                        return true;
+                    }
+                    return (definition.parent.importKind !== 'type' &&
+                        !(definition.node.type === AST_NODE_TYPES.ImportSpecifier &&
+                            definition.node.importKind === 'type'));
+                }))) {
+            return variable;
+        }
+    }
+    return undefined;
+};

package/dist/rules/no-component-state.d.ts

@@ -0,0 +1,2 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const noComponentState: ESLintUtils.RuleModule<"componentState", [], unknown, ESLintUtils.RuleListener>;

package/dist/rules/no-component-state.js

@@ -0,0 +1,46 @@
+import { AST_NODE_TYPES, ESLintUtils, } from '@typescript-eslint/utils';
+import { runeCallee } from '../lib/rune-callee.js';
+import { createComponentRefCheck } from '../lib/component-refs.js';
+export const noComponentState = ESLintUtils.RuleCreator.withoutDocs({
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow component-owned logical state in explicitly selected files.',
+        },
+        schema: [],
+        messages: {
+            componentState: '{{rune}} creates component-owned state. Move logical state to root/feature state and use intent actions, or exclude this independent UI component from the rule scope.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const source = context.sourceCode;
+        const refs = createComponentRefCheck(source);
+        const calls = [];
+        return {
+            SvelteDirective: refs.recordBinding,
+            CallExpression(node) {
+                const callee = node.callee;
+                const identifier = runeCallee(callee, source, '$state', 'raw') ??
+                    runeCallee(callee, source, '$bindable');
+                if (!identifier) {
+                    return;
+                }
+                calls.push({
+                    node,
+                    rune: callee.type === AST_NODE_TYPES.MemberExpression
+                        ? '$state.raw'
+                        : identifier.name,
+                });
+            },
+            'Program:exit'() {
+                calls.forEach(({ node, rune }) => {
+                    if (rune !== '$bindable' && refs.allows(node)) {
+                        return;
+                    }
+                    context.report({ node, messageId: 'componentState', data: { rune } });
+                });
+            },
+        };
+    },
+});

package/dist/rules/ready-boolean-condition.d.ts

@@ -0,0 +1,2 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const readyBooleanCondition: ESLintUtils.RuleModule<"readyBoolean", [], unknown, ESLintUtils.RuleListener>;

package/dist/rules/ready-boolean-condition.js

@@ -0,0 +1,49 @@
+import { AST_NODE_TYPES, ESLintUtils, } from '@typescript-eslint/utils';
+import { readyBooleanExpression } from '../lib/ready-boolean-expression.js';
+import { booleanType } from '../lib/boolean-type.js';
+export const readyBooleanCondition = ESLintUtils.RuleCreator.withoutDocs({
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Require ready boolean reads in Svelte if/else-if conditions.',
+        },
+        schema: [],
+        messages: {
+            readyBoolean: 'Prepare a named boolean in a presenter and read it here instead of computing a condition or using truthiness.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        if (!context.filename.endsWith('.svelte')) {
+            return {};
+        }
+        let checkType;
+        return {
+            SvelteIfBlock(node) {
+                const expression = node.expression;
+                if (expression.type === AST_NODE_TYPES.Literal &&
+                    (expression.value === true || expression.value === false)) {
+                    return;
+                }
+                if (!readyBooleanExpression(expression)) {
+                    context.report({ node: expression, messageId: 'readyBoolean' });
+                    return;
+                }
+                if (!checkType) {
+                    const services = ESLintUtils.getParserServices(context);
+                    const options = services.program.getCompilerOptions();
+                    if (!(options.strictNullChecks ?? options.strict ?? false)) {
+                        throw new Error('gost/ready-boolean-condition requires strictNullChecks (or strict) for typed conditions.');
+                    }
+                    const checker = services.program.getTypeChecker();
+                    checkType = (condition) => {
+                        return booleanType(checker, services.getTypeAtLocation(condition));
+                    };
+                }
+                if (!checkType(expression)) {
+                    context.report({ node: expression, messageId: 'readyBoolean' });
+                }
+            },
+        };
+    },
+});

package/dist/rules/require-feature-state-selector.d.ts

@@ -0,0 +1,2 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const requireFeatureStateSelector: ESLintUtils.RuleModule<"selectFeature", [], unknown, ESLintUtils.RuleListener>;

package/dist/rules/require-feature-state-selector.js

@@ -0,0 +1,58 @@
+import { svelteScripts, scriptHasAttribute, inScript, } from '../lib/svelte-scripts.js';
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils';
+import { memberKey } from '../lib/member-key.js';
+import { createStoreStateCheck } from '../lib/store-state.js';
+import { reactiveContext } from '../lib/reactive-context.js';
+import { createRawStateCheck } from '../lib/raw-state.js';
+import { selectorFix } from '../lib/selector-fix.js';
+export const requireFeatureStateSelector = ESLintUtils.RuleCreator.withoutDocs({
+    meta: {
+        type: 'suggestion',
+        docs: { description: 'Select Store state before reactive calls.' },
+        schema: [],
+        fixable: 'code',
+        messages: {
+            selectFeature: 'Select the feature with a separate $derived before computing its presentation: const user = $derived(store.state.user); const view = $derived(presenter(user)); This skips downstream updates when the feature reference is unchanged.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const typedScripts = svelteScripts(context.sourceCode)?.filter((script) => {
+            return scriptHasAttribute(script, 'lang', 'ts');
+        });
+        if (typedScripts?.length === 0) {
+            return {};
+        }
+        const services = ESLintUtils.getParserServices(context);
+        const isStore = createStoreStateCheck(services);
+        const isRawState = createRawStateCheck(context.sourceCode);
+        return {
+            MemberExpression(node) {
+                if (typedScripts && !inScript(node, typedScripts)) {
+                    return;
+                }
+                const storeState = memberKey(node) === 'state' && isStore(node.object);
+                if (!storeState && !isRawState(node.object)) {
+                    return;
+                }
+                const reactive = reactiveContext(node, context.sourceCode);
+                if (!reactive) {
+                    return;
+                }
+                const parent = node.parent;
+                const location = storeState &&
+                    parent.type === AST_NODE_TYPES.MemberExpression &&
+                    parent.object === node
+                    ? parent
+                    : node;
+                context.report({
+                    node: location,
+                    messageId: 'selectFeature',
+                    fix: reactive.call.type === AST_NODE_TYPES.CallExpression
+                        ? selectorFix(storeState ? node : node.object, reactive.derived, reactive.call, context.sourceCode)
+                        : undefined,
+                });
+            },
+        };
+    },
+});

package/dist/rules/single-intent-dispatch.d.ts

@@ -0,0 +1,2 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const singleIntentDispatch: ESLintUtils.RuleModule<"multipleDispatch" | "conditionalDispatch", [], unknown, ESLintUtils.RuleListener>;

package/dist/rules/single-intent-dispatch.js

@@ -0,0 +1,89 @@
+import { AST_NODE_TYPES, ESLintUtils, } from '@typescript-eslint/utils';
+import { isOptionalCall } from '../lib/optional-call.js';
+import { createDispatchCheck } from '../lib/dispatch-type.js';
+import { createUiHandlerCollector } from '../lib/ui-handlers.js';
+import { visitHandlerBody } from '../lib/handler-body.js';
+import { scriptHasAttribute, svelteScripts } from '../lib/svelte-scripts.js';
+export const singleIntentDispatch = ESLintUtils.RuleCreator.withoutDocs({
+    meta: {
+        type: 'suggestion',
+        docs: { description: 'Forward one intent in business UI callbacks.' },
+        schema: [],
+        messages: {
+            multipleDispatch: 'Forward one intent action; move business transitions to the reducer.',
+            conditionalDispatch: 'Move business decisions to the reducer and browser event handling to a UI-Kit component.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const source = context.sourceCode;
+        const scripts = svelteScripts(source)?.filter((script) => {
+            return (scriptHasAttribute(script, 'lang', 'ts') &&
+                !scriptHasAttribute(script, 'module') &&
+                !scriptHasAttribute(script, 'context', 'module'));
+        });
+        if (!scripts?.length) {
+            return {};
+        }
+        const isDispatch = createDispatchCheck(ESLintUtils.getParserServices(context));
+        const collector = createUiHandlerCollector(source, scripts);
+        return {
+            SvelteAttribute: collector.attribute,
+            SvelteShorthandAttribute: collector.shorthand,
+            SvelteDirective: collector.directive,
+            'Program:exit'() {
+                collector.handlers.forEach((handler) => {
+                    let calls = 0;
+                    let condition;
+                    if (!handler.body) {
+                        return;
+                    }
+                    const inspect = (node) => {
+                        if (node.type === AST_NODE_TYPES.CallExpression &&
+                            isDispatch(node.callee)) {
+                            calls += 1;
+                            if (isOptionalCall(node)) {
+                                condition ??= node;
+                            }
+                            // A Dispatch default argument runs conditionally at invocation,
+                            // even though its AssignmentPattern is not a logical expression.
+                            condition ??= source.getAncestors(node).find((ancestor) => {
+                                return (ancestor.type === AST_NODE_TYPES.AssignmentPattern &&
+                                    handler.params.some((parameter) => {
+                                        return (ancestor.range[0] >= parameter.range[0] &&
+                                            ancestor.range[1] <= parameter.range[1]);
+                                    }));
+                            });
+                        }
+                        if (node.type === AST_NODE_TYPES.IfStatement ||
+                            node.type === AST_NODE_TYPES.SwitchStatement ||
+                            node.type === AST_NODE_TYPES.ForStatement ||
+                            node.type === AST_NODE_TYPES.ForInStatement ||
+                            node.type === AST_NODE_TYPES.ForOfStatement ||
+                            node.type === AST_NODE_TYPES.WhileStatement ||
+                            node.type === AST_NODE_TYPES.DoWhileStatement ||
+                            node.type === AST_NODE_TYPES.ConditionalExpression ||
+                            node.type === AST_NODE_TYPES.LogicalExpression ||
+                            (node.type === AST_NODE_TYPES.AssignmentExpression &&
+                                ['??=', '&&=', '||='].includes(node.operator))) {
+                            condition ??= node;
+                        }
+                    };
+                    handler.params.forEach((parameter) => {
+                        visitHandlerBody(parameter, source, inspect);
+                    });
+                    visitHandlerBody(handler.body, source, inspect);
+                    if (calls > 1) {
+                        context.report({ node: handler, messageId: 'multipleDispatch' });
+                    }
+                    else if (calls === 1 && condition) {
+                        context.report({
+                            node: condition,
+                            messageId: 'conditionalDispatch',
+                        });
+                    }
+                });
+            },
+        };
+    },
+});

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@gost-kit/eslint-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "GOST architecture rules for agent-assisted frontend development.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": "^26.0.0"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "RULES.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepack": "npm run build",
+    "clean": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true });\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/antonsmolko/gost-kit.git",
+    "directory": "packages/eslint-plugin"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.5",
+    "typescript": "5.9.3",
+    "tsc-alias": "1.9.9",
+    "vitest": "5.0.5",
+    "eslint": "10.14.0",
+    "svelte-eslint-parser": "1.10.1",
+    "typescript-eslint": "8.72.1",
+    "svelte": "5.57.2",
+    "@gost-kit/common": "0.3.0",
+    "@gost-kit/svelte": "0.2.0",
+    "@typescript-eslint/rule-tester": "8.72.1"
+  },
+  "dependencies": {
+    "@typescript-eslint/utils": "8.72.1"
+  },
+  "peerDependencies": {
+    "eslint": "^10.14.0",
+    "typescript": "^5.9.3"
+  }
+}