@commonplaces/oxlint-plugin 0.0.0-stage → 0.1.1

package/dist/anti-slop/rules/no-unknown-type-aliases.js

@@ -0,0 +1,58 @@
+import { Array, HashMap, Option } from "effect";
+import { createTypeEnvironment } from "../shared/dictionary-types.js";
+import { defineRule } from "@oxlint/plugins";
+function referencedAliasName(type) {
+    if (type.type === "TSParenthesizedType")
+        return referencedAliasName(type.typeAnnotation);
+    if (type.type !== "TSTypeReference" || type.typeName.type !== "Identifier")
+        return null;
+    return type.typeArguments === null ||
+        type.typeArguments === undefined ||
+        type.typeArguments.params.length === 0
+        ? type.typeName.name
+        : null;
+}
+/** Ban named aliases that merely conceal TypeScript's unknown top type. */
+export const noUnknownTypeAliasesRule = defineRule({
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Disallow type aliases whose resolved type is unknown; unknown must remain visible at an allowed boundary.",
+        },
+        messages: {
+            unknownAlias: "Type alias `{{alias}}` hides `unknown`. Keep `unknown` explicit at the parsing boundary or on an allowed `cause` field; otherwise use the parsed owner type.",
+        },
+    },
+    create(context) {
+        const aliases = createTypeEnvironment(context.sourceCode.ast).aliases;
+        const resolvesToUnknown = (type, visited = []) => {
+            if (type.type === "TSUnknownKeyword")
+                return true;
+            if (type.type === "TSParenthesizedType")
+                return resolvesToUnknown(type.typeAnnotation, visited);
+            const name = referencedAliasName(type);
+            if (name === null || Array.contains(visited, name))
+                return false;
+            const alias = Option.getOrUndefined(HashMap.get(aliases, name));
+            if (alias === undefined ||
+                (alias.typeParameters !== null && alias.typeParameters !== undefined)) {
+                return false;
+            }
+            const nextVisited = [...visited, name];
+            return resolvesToUnknown(alias.typeAnnotation, nextVisited);
+        };
+        return {
+            Program() {
+                Array.forEach(HashMap.values(aliases), (alias) => {
+                    if (!resolvesToUnknown(alias.typeAnnotation, [alias.id.name]))
+                        return;
+                    context.report({
+                        node: alias.id,
+                        messageId: "unknownAlias",
+                        data: { alias: alias.id.name },
+                    });
+                });
+            },
+        };
+    },
+});

package/dist/anti-slop/rules/no-unsafe-dictionary-type.d.ts

@@ -0,0 +1,2 @@
+/** Disallow object-dictionary contracts whose direct value type is an unsafe escape hatch. */
+export declare const noUnsafeDictionaryTypeRule: import("@oxlint/plugins").Rule;

package/dist/anti-slop/rules/no-unsafe-dictionary-type.js

@@ -0,0 +1,111 @@
+import { Array, HashMap } from "effect";
+import { defineRule } from "@oxlint/plugins";
+import { classifyUnsafeDictionary, classifyUnsafeDictionaryValue, createTypeEnvironment, } from "../shared/dictionary-types.js";
+const typeNodeKinds = [
+    "JSDocNonNullableType",
+    "JSDocNullableType",
+    "JSDocUnknownType",
+    "TSAnyKeyword",
+    "TSArrayType",
+    "TSBigIntKeyword",
+    "TSBooleanKeyword",
+    "TSConditionalType",
+    "TSConstructorType",
+    "TSFunctionType",
+    "TSImportType",
+    "TSIndexedAccessType",
+    "TSInferType",
+    "TSIntersectionType",
+    "TSIntrinsicKeyword",
+    "TSLiteralType",
+    "TSMappedType",
+    "TSNamedTupleMember",
+    "TSNeverKeyword",
+    "TSNullKeyword",
+    "TSNumberKeyword",
+    "TSObjectKeyword",
+    "TSParenthesizedType",
+    "TSStringKeyword",
+    "TSSymbolKeyword",
+    "TSTemplateLiteralType",
+    "TSThisType",
+    "TSTupleType",
+    "TSTypeLiteral",
+    "TSTypeOperator",
+    "TSTypePredicate",
+    "TSTypeQuery",
+    "TSTypeReference",
+    "TSUndefinedKeyword",
+    "TSUnionType",
+    "TSUnknownKeyword",
+    "TSVoidKeyword",
+];
+function isTypeNode(node) {
+    return Array.contains(typeNodeKinds, node.type);
+}
+function typeReferenceName(type) {
+    return type.typeName.type === "Identifier" ? type.typeName.name : null;
+}
+function isInsideTypeAliasDeclaration(node) {
+    const current = node.parent;
+    return (current !== null &&
+        current.type !== "Program" &&
+        (current.type === "TSTypeAliasDeclaration" || isInsideTypeAliasDeclaration(current)));
+}
+function isPlainAliasConsumerUse(node, environment) {
+    if (node.type !== "TSTypeReference" || node.typeArguments?.params.length)
+        return false;
+    const name = typeReferenceName(node);
+    return (name !== null && HashMap.has(environment.aliases, name) && !isInsideTypeAliasDeclaration(node));
+}
+function hasUnsafeParent(node, environment) {
+    return (node !== null &&
+        node.type !== "Program" &&
+        ((isTypeNode(node) && classifyUnsafeDictionary(node, environment) !== null) ||
+            hasUnsafeParent(node.parent, environment)));
+}
+function shouldReportType(node, environment) {
+    if (isPlainAliasConsumerUse(node, environment))
+        return false;
+    if (classifyUnsafeDictionary(node, environment) === null)
+        return false;
+    return !hasUnsafeParent(node.parent, environment);
+}
+/** Disallow object-dictionary contracts whose direct value type is an unsafe escape hatch. */
+export const noUnsafeDictionaryTypeRule = defineRule({
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Disallow object-dictionary contracts whose direct value type is unknown, any, object, {}, or a union/alias containing one of those escape hatches.",
+        },
+        messages: {
+            unsafeDictionary: "This dictionary's {{value}} value type gives callers no concrete value contract. Use an owner/schema-derived value type; parse external payloads before insertion.",
+        },
+    },
+    create(context) {
+        const environment = createTypeEnvironment(context.sourceCode.ast);
+        const report = (node, value) => {
+            context.report({ node, messageId: "unsafeDictionary", data: { value } });
+        };
+        const reportIfUnsafe = (node) => {
+            if (!shouldReportType(node, environment))
+                return;
+            const unsafe = classifyUnsafeDictionary(node, environment);
+            if (unsafe === null)
+                return;
+            report(node, unsafe.unsafeValue);
+        };
+        return {
+            TSTypeReference: reportIfUnsafe,
+            TSTypeLiteral: reportIfUnsafe,
+            TSMappedType: reportIfUnsafe,
+            TSIndexSignature(node) {
+                if (node.typeAnnotation === null || node.parent.type === "TSTypeLiteral")
+                    return;
+                const unsafe = classifyUnsafeDictionaryValue(node.typeAnnotation.typeAnnotation, environment);
+                if (unsafe !== null)
+                    report(node, unsafe.unsafeValue);
+            },
+        };
+    },
+});

package/dist/anti-slop/rules/no-widen-then-assert.d.ts

@@ -0,0 +1,2 @@
+/** Detect immutable local bindings that erase a known type and are later asserted back to a narrower type. */
+export declare const noWidenThenAssertRule: import("@oxlint/plugins").Rule;

package/dist/anti-slop/rules/no-widen-then-assert.js

@@ -0,0 +1,255 @@
+import { Array, Option } from "effect";
+import { defineRule } from "@oxlint/plugins";
+const functionBoundaryTypes = [
+    "ArrowFunctionExpression",
+    "FunctionDeclaration",
+    "FunctionExpression",
+    "TSDeclareFunction",
+    "TSEmptyBodyFunctionExpression",
+];
+function unwrapExpressionParentheses(expression) {
+    return expression.type === "ParenthesizedExpression"
+        ? unwrapExpressionParentheses(expression.expression)
+        : expression;
+}
+function unwrapTypeParentheses(type) {
+    return type.type === "TSParenthesizedType" ? unwrapTypeParentheses(type.typeAnnotation) : type;
+}
+function typeReferenceName(type) {
+    return type.typeName.type === "Identifier" ? type.typeName.name : null;
+}
+function isUnknownOrAnyType(type) {
+    const unwrapped = unwrapTypeParentheses(type);
+    return unwrapped.type === "TSUnknownKeyword" || unwrapped.type === "TSAnyKeyword";
+}
+function isBroadRecordKeyType(type) {
+    const unwrapped = unwrapTypeParentheses(type);
+    if (unwrapped.type === "TSStringKeyword" ||
+        unwrapped.type === "TSNumberKeyword" ||
+        unwrapped.type === "TSSymbolKeyword") {
+        return true;
+    }
+    if (unwrapped.type === "TSUnionType")
+        return Array.every(unwrapped.types, isBroadRecordKeyType);
+    return unwrapped.type === "TSTypeReference" && typeReferenceName(unwrapped) === "PropertyKey";
+}
+function isBroadRecordType(type) {
+    const unwrapped = unwrapTypeParentheses(type);
+    if (unwrapped.type === "TSTypeReference") {
+        if (typeReferenceName(unwrapped) === "Readonly") {
+            const [inner] = unwrapped.typeArguments?.params ?? [];
+            return inner !== undefined && isBroadRecordType(inner);
+        }
+        if (typeReferenceName(unwrapped) !== "Record")
+            return false;
+        const parameters = unwrapped.typeArguments?.params ?? [];
+        const [key, value] = parameters;
+        return (parameters.length === 2 &&
+            key !== undefined &&
+            value !== undefined &&
+            isBroadRecordKeyType(key) &&
+            isUnknownOrAnyType(value));
+    }
+    if (unwrapped.type !== "TSTypeLiteral" || unwrapped.members.length !== 1)
+        return false;
+    const [member] = unwrapped.members;
+    const [parameter] = member?.type === "TSIndexSignature" ? member.parameters : [];
+    return (member?.type === "TSIndexSignature" &&
+        member.parameters.length === 1 &&
+        parameter !== undefined &&
+        isBroadRecordKeyType(parameter.typeAnnotation.typeAnnotation) &&
+        isUnknownOrAnyType(member.typeAnnotation.typeAnnotation));
+}
+function broadTypeKind(type) {
+    const unwrapped = unwrapTypeParentheses(type);
+    if (unwrapped.type === "TSUnknownKeyword" || unwrapped.type === "TSAnyKeyword")
+        return "top";
+    if (unwrapped.type === "TSObjectKeyword")
+        return "object";
+    return isBroadRecordType(unwrapped) ? "record" : null;
+}
+function assertedExpression(node) {
+    return unwrapExpressionParentheses(node.expression);
+}
+function assertionFromExpression(expression) {
+    const unwrapped = unwrapExpressionParentheses(expression);
+    return unwrapped.type === "TSAsExpression" || unwrapped.type === "TSTypeAssertion"
+        ? unwrapped
+        : null;
+}
+function normalizedTypeText(sourceText, type) {
+    return sourceText.slice(type.start, type.end).replaceAll(/\s+/gu, "");
+}
+function typesHaveSameSyntax(sourceText, left, right) {
+    return (left !== null &&
+        normalizedTypeText(sourceText, unwrapTypeParentheses(left)) ===
+            normalizedTypeText(sourceText, unwrapTypeParentheses(right)));
+}
+function isDefinitelyObjectType(type) {
+    const unwrapped = unwrapTypeParentheses(type);
+    if (Array.contains([
+        "TSArrayType",
+        "TSConstructorType",
+        "TSFunctionType",
+        "TSMappedType",
+        "TSObjectKeyword",
+        "TSTupleType",
+    ], unwrapped.type))
+        return true;
+    if (unwrapped.type === "TSTypeLiteral")
+        return unwrapped.members.length > 0;
+    if (unwrapped.type === "TSIntersectionType")
+        return Array.every(unwrapped.types, isDefinitelyObjectType);
+    return (unwrapped.type === "TSTypeOperator" &&
+        unwrapped.operator === "readonly" &&
+        isDefinitelyObjectType(unwrapped.typeAnnotation));
+}
+function isDefinitelyNarrowerRecordType(type) {
+    const unwrapped = unwrapTypeParentheses(type);
+    if (unwrapped.type === "TSTypeLiteral") {
+        return Array.some(unwrapped.members, (member) => member.type !== "TSIndexSignature");
+    }
+    if (unwrapped.type !== "TSTypeReference")
+        return false;
+    if (typeReferenceName(unwrapped) === "Readonly") {
+        const [inner] = unwrapped.typeArguments?.params ?? [];
+        return inner !== undefined && isDefinitelyNarrowerRecordType(inner);
+    }
+    if (typeReferenceName(unwrapped) !== "Record")
+        return false;
+    const parameters = unwrapped.typeArguments?.params ?? [];
+    const [, value] = parameters;
+    return parameters.length === 2 && value !== undefined && !isUnknownOrAnyType(value);
+}
+function functionBoundary(node) {
+    const current = node.parent;
+    if (current === null || current.type === "Program")
+        return null;
+    return Array.contains(functionBoundaryTypes, current.type) ? current : functionBoundary(current);
+}
+function resolvedVariableForIdentifier(scopes, identifier) {
+    return Option.getOrNull(Array.findFirst(scopes, (scope) => Array.some(scope.references, (candidate) => candidate.identifier.start === identifier.start &&
+        candidate.identifier.end === identifier.end)).pipe(Option.flatMap((scope) => Array.findFirst(scope.references, (candidate) => candidate.identifier.start === identifier.start &&
+        candidate.identifier.end === identifier.end)), Option.flatMap((reference) => Option.fromNullishOr(reference.resolved))));
+}
+function variableDeclarator(variable) {
+    return Option.getOrNull(Array.findFirst(variable.defs, (definition) => definition.type === "Variable" && definition.node.type === "VariableDeclarator").pipe(Option.flatMap((definition) => definition.node.type === "VariableDeclarator"
+        ? Option.some(definition.node)
+        : Option.none())));
+}
+function knownValueEvidence(expression, scopes, boundary, visitedVariables) {
+    const unwrapped = unwrapExpressionParentheses(expression);
+    if (unwrapped.type === "TSAsExpression" || unwrapped.type === "TSTypeAssertion") {
+        if (broadTypeKind(unwrapped.typeAnnotation) !== null)
+            return null;
+        return { type: unwrapped.typeAnnotation };
+    }
+    if (unwrapped.type === "Literal" || unwrapped.type === "TemplateLiteral") {
+        return { type: null };
+    }
+    if (unwrapped.type === "ArrayExpression" ||
+        unwrapped.type === "ArrowFunctionExpression" ||
+        unwrapped.type === "ClassExpression" ||
+        unwrapped.type === "FunctionExpression" ||
+        unwrapped.type === "NewExpression" ||
+        unwrapped.type === "ObjectExpression") {
+        return { type: null };
+    }
+    if (unwrapped.type !== "Identifier")
+        return null;
+    const variable = resolvedVariableForIdentifier(scopes, unwrapped);
+    if (variable === null || Array.some(visitedVariables, (previous) => previous === variable))
+        return null;
+    const annotatedIdentifier = Option.getOrUndefined(Array.findFirst(variable.identifiers, (identifier) => identifier.typeAnnotation !== null && identifier.typeAnnotation !== undefined));
+    const annotation = annotatedIdentifier?.typeAnnotation?.typeAnnotation;
+    if (annotation !== undefined && annotatedIdentifier !== undefined) {
+        if (functionBoundary(annotatedIdentifier) !== boundary || broadTypeKind(annotation) !== null) {
+            return null;
+        }
+        return { type: annotation };
+    }
+    const declarator = variableDeclarator(variable);
+    if (declarator === null ||
+        declarator.parent.type !== "VariableDeclaration" ||
+        declarator.parent.kind !== "const" ||
+        declarator.init === null ||
+        Array.some(variable.references, (reference) => reference.isWrite() && !reference.init) ||
+        functionBoundary(declarator) !== boundary) {
+        return null;
+    }
+    return knownValueEvidence(declarator.init, scopes, boundary, [...visitedVariables, variable]);
+}
+function widenedBinding(variable, scopes) {
+    const declarator = variableDeclarator(variable);
+    if (declarator === null ||
+        declarator.parent.type !== "VariableDeclaration" ||
+        declarator.parent.kind !== "const" ||
+        declarator.id.type !== "Identifier" ||
+        declarator.init === null ||
+        Array.some(variable.references, (reference) => reference.isWrite() && !reference.init)) {
+        return null;
+    }
+    const boundary = functionBoundary(declarator);
+    const declaredType = declarator.id.typeAnnotation?.typeAnnotation;
+    const initializerAssertion = assertionFromExpression(declarator.init);
+    const initializerBroadKind = initializerAssertion === null ? null : broadTypeKind(initializerAssertion.typeAnnotation);
+    const declaredBroadKind = declaredType === undefined ? null : broadTypeKind(declaredType);
+    const broadKind = declaredBroadKind ?? initializerBroadKind;
+    if (broadKind === null)
+        return null;
+    const originalExpression = initializerAssertion !== null && initializerBroadKind !== null
+        ? assertedExpression(initializerAssertion)
+        : declarator.init;
+    const evidence = knownValueEvidence(originalExpression, scopes, boundary, [variable]);
+    return evidence === null ? null : { broadKind, evidence, declaredAt: declarator.end, boundary };
+}
+function assertionIsNarrower(sourceText, broadKind, evidence, assertedType) {
+    if (broadTypeKind(assertedType) !== null)
+        return false;
+    if (broadKind === "top")
+        return true;
+    if (typesHaveSameSyntax(sourceText, evidence.type, assertedType))
+        return true;
+    if (broadKind === "object")
+        return isDefinitelyObjectType(assertedType);
+    return isDefinitelyNarrowerRecordType(assertedType);
+}
+/** Detect immutable local bindings that erase a known type and are later asserted back to a narrower type. */
+export const noWidenThenAssertRule = defineRule({
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Disallow local const flows that explicitly widen a known value before asserting the widened binding to a narrower type.",
+        },
+        messages: {
+            widenThenAssert: 'Binding "{{name}}" discards type evidence and later recreates it with an assertion. Keep the precise type from initialization through use; parse boundary input once.',
+        },
+    },
+    create(context) {
+        const scopes = context.sourceCode.scopeManager.scopes;
+        const checkAssertion = (node) => {
+            const expression = assertedExpression(node);
+            if (expression.type !== "Identifier")
+                return;
+            const variable = resolvedVariableForIdentifier(scopes, expression);
+            if (variable === null)
+                return;
+            const widened = widenedBinding(variable, scopes);
+            if (widened === null ||
+                node.start <= widened.declaredAt ||
+                functionBoundary(node) !== widened.boundary ||
+                !assertionIsNarrower(context.sourceCode.text, widened.broadKind, widened.evidence, node.typeAnnotation)) {
+                return;
+            }
+            context.report({
+                node,
+                messageId: "widenThenAssert",
+                data: { name: expression.name },
+            });
+        };
+        return {
+            TSAsExpression: checkAssertion,
+            TSTypeAssertion: checkAssertion,
+        };
+    },
+});

package/dist/anti-slop/rules/require-safety-comment-for-type-assertion.d.ts

@@ -0,0 +1,2 @@
+/** Require every non-const type assertion to state the invariant TypeScript cannot express. */
+export declare const requireSafetyCommentForTypeAssertionRule: import("@oxlint/plugins").Rule;

package/dist/anti-slop/rules/require-safety-comment-for-type-assertion.js

@@ -0,0 +1,51 @@
+import { Array } from "effect";
+import { defineRule } from "@oxlint/plugins";
+const commentOwnerKinds = [
+    "ExportNamedDeclaration",
+    "ExportDefaultDeclaration",
+    "ExpressionStatement",
+    "PropertyDefinition",
+    "ReturnStatement",
+    "ThrowStatement",
+    "VariableDeclaration",
+];
+function isConstAssertion(node) {
+    return (node.typeAnnotation.type === "TSTypeReference" &&
+        node.typeAnnotation.typeName.type === "Identifier" &&
+        node.typeAnnotation.typeName.name === "const");
+}
+function hasSafetyComment(sourceCode, node, current = node) {
+    if (Array.some(sourceCode.getCommentsBefore(current), (comment) => comment.end <= node.start && /\bSAFETY\s*:/u.test(comment.value)))
+        return true;
+    const parent = current.parent;
+    if (parent === null || parent.type === "Program")
+        return false;
+    if (Array.contains(commentOwnerKinds, current.type) &&
+        parent.type !== "ExportNamedDeclaration" &&
+        parent.type !== "ExportDefaultDeclaration")
+        return false;
+    return hasSafetyComment(sourceCode, node, current.parent);
+}
+/** Require every non-const type assertion to state the invariant TypeScript cannot express. */
+export const requireSafetyCommentForTypeAssertionRule = defineRule({
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require a nearby SAFETY comment for every TypeScript type assertion except const assertions.",
+        },
+        messages: {
+            missingSafetyComment: "This type assertion has no `SAFETY:` justification. State the checked invariant immediately before the assertion or its containing statement.",
+        },
+    },
+    createOnce(context) {
+        const checkAssertion = (node) => {
+            if (isConstAssertion(node) || hasSafetyComment(context.sourceCode, node))
+                return;
+            context.report({ node, messageId: "missingSafetyComment" });
+        };
+        return {
+            TSAsExpression: checkAssertion,
+            TSTypeAssertion: checkAssertion,
+        };
+    },
+});

package/dist/anti-slop/shared/dictionary-types.d.ts

@@ -0,0 +1,21 @@
+import { HashMap, HashSet } from "effect";
+import type { ESTree } from "@oxlint/plugins";
+export type UnsafeDictionary = {
+    readonly kind: "unsafe-dictionary";
+    readonly unsafeValue: "any" | "empty-object" | "object" | "union" | "unknown";
+};
+type WideningTargetKind = "anonymous object" | "generic container" | "object" | "open dictionary" | "unknown";
+export type WideningTarget = {
+    readonly kind: WideningTargetKind;
+};
+export type TypeEnvironment = {
+    readonly aliases: HashMap.HashMap<string, ESTree.TSTypeAliasDeclaration>;
+    readonly interfaces: HashMap.HashMap<string, readonly ESTree.TSInterfaceDeclaration[]>;
+    readonly shadowedBuiltIns: HashSet.HashSet<string>;
+};
+export declare function createTypeEnvironment(program: ESTree.Program): TypeEnvironment;
+export declare function classifyUnsafeDictionaryValue(valueType: ESTree.TSType, environment: TypeEnvironment): UnsafeDictionary | null;
+export declare function classifyUnsafeDictionary(type: ESTree.TSType, environment: TypeEnvironment): UnsafeDictionary | null;
+export declare function classifyWideningTarget(type: ESTree.TSType, environment: TypeEnvironment): WideningTarget | null;
+export declare function isKnownEvidenceExpression(expression: ESTree.Expression): boolean;
+export {};