ai-deslop 0.2.0 → 0.2.2

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

@@ -0,0 +1,270 @@
+import { defineRule } from "@oxlint/plugins";
+const functionBoundaryTypes = new Set([
+    "ArrowFunctionExpression",
+    "FunctionDeclaration",
+    "FunctionExpression",
+    "TSDeclareFunction",
+    "TSEmptyBodyFunctionExpression",
+]);
+function unwrapExpressionParentheses(expression) {
+    let current = expression;
+    while (current.type === "ParenthesizedExpression")
+        current = current.expression;
+    return current;
+}
+function unwrapTypeParentheses(type) {
+    let current = type;
+    while (current.type === "TSParenthesizedType")
+        current = current.typeAnnotation;
+    return current;
+}
+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 unwrapped.types.every(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 ?? [];
+        return (parameters.length === 2 &&
+            parameters[0] !== undefined &&
+            parameters[1] !== undefined &&
+            isBroadRecordKeyType(parameters[0]) &&
+            isUnknownOrAnyType(parameters[1]));
+    }
+    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);
+    switch (unwrapped.type) {
+        case "TSArrayType":
+        case "TSConstructorType":
+        case "TSFunctionType":
+        case "TSMappedType":
+        case "TSObjectKeyword":
+        case "TSTupleType":
+            return true;
+        case "TSTypeLiteral":
+            return unwrapped.members.length > 0;
+        case "TSIntersectionType":
+            return unwrapped.types.every(isDefinitelyObjectType);
+        case "TSTypeOperator":
+            return unwrapped.operator === "readonly" && isDefinitelyObjectType(unwrapped.typeAnnotation);
+        default:
+            return false;
+    }
+}
+function isDefinitelyNarrowerRecordType(type) {
+    const unwrapped = unwrapTypeParentheses(type);
+    if (unwrapped.type === "TSTypeLiteral") {
+        return unwrapped.members.some((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 ?? [];
+    return (parameters.length === 2 && parameters[1] !== undefined && !isUnknownOrAnyType(parameters[1]));
+}
+function functionBoundary(node) {
+    let current = node.parent;
+    while (current !== null && current.type !== "Program") {
+        if (functionBoundaryTypes.has(current.type))
+            return current;
+        current = current.parent;
+    }
+    return null;
+}
+function resolvedVariableForIdentifier(scopes, identifier) {
+    for (const scope of scopes) {
+        const reference = scope.references.find((candidate) => candidate.identifier.start === identifier.start &&
+            candidate.identifier.end === identifier.end);
+        if (reference !== undefined)
+            return reference.resolved;
+    }
+    return null;
+}
+function variableDeclarator(variable) {
+    for (const definition of variable.defs) {
+        if (definition.type === "Variable" && definition.node.type === "VariableDeclarator") {
+            return definition.node;
+        }
+    }
+    return null;
+}
+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 || visitedVariables.has(variable))
+        return null;
+    const annotatedIdentifier = variable.identifiers.find((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 ||
+        variable.references.some((reference) => reference.isWrite() && !reference.init) ||
+        functionBoundary(declarator) !== boundary) {
+        return null;
+    }
+    return knownValueEvidence(declarator.init, scopes, boundary, new Set([...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 ||
+        variable.references.some((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, new Set([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.',
+        },
+    },
+    createOnce(context) {
+        let 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 {
+            Program() {
+                scopes = context.sourceCode.scopeManager.scopes;
+            },
+            TSAsExpression: checkAssertion,
+            TSTypeAssertion: checkAssertion,
+        };
+    },
+});

package/dist/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/rules/require-safety-comment-for-type-assertion.js

@@ -0,0 +1,100 @@
+import { defineRule } from "@oxlint/plugins";
+const DEFAULT_SAFETY_MARKERS = ["SAFETY"];
+const commentOwnerKinds = new Set([
+    "ExpressionStatement",
+    "PropertyDefinition",
+    "ReturnStatement",
+    "ThrowStatement",
+    "VariableDeclaration",
+]);
+function isConstAssertion(node) {
+    return (node.typeAnnotation.type === "TSTypeReference" &&
+        node.typeAnnotation.typeName.type === "Identifier" &&
+        node.typeAnnotation.typeName.name === "const");
+}
+function configuredSafetyMarkers(option) {
+    if (typeof option !== "object" || option === null || !("markers" in option)) {
+        return DEFAULT_SAFETY_MARKERS;
+    }
+    const configured = option.markers;
+    if (!Array.isArray(configured))
+        return DEFAULT_SAFETY_MARKERS;
+    const markers = configured.flatMap((marker) => typeof marker === "string" && marker.trim().length > 0 ? [marker.trim()] : []);
+    return markers.length > 0 ? markers : DEFAULT_SAFETY_MARKERS;
+}
+function markerPattern(markers) {
+    const alternation = markers
+        .map((marker) => marker.replaceAll(/[.*+?^${}()|[\]\\]/gu, String.raw `\$&`))
+        .join("|");
+    return new RegExp(String.raw `(?:^|[^\p{L}\p{N}_])(?:${alternation})\s*:\s*\S`, "u");
+}
+function hasSafetyJustificationBefore(sourceCode, owner, assertion, pattern) {
+    return sourceCode
+        .getCommentsBefore(owner)
+        .some((comment) => comment.end <= assertion.start && pattern.test(comment.value));
+}
+function hasSafetyComment(sourceCode, node, pattern) {
+    let current = node;
+    while (true) {
+        if (hasSafetyJustificationBefore(sourceCode, current, node, pattern))
+            return true;
+        if (commentOwnerKinds.has(current.type)) {
+            const exportDeclaration = current.parent;
+            return (exportDeclaration.type === "ExportNamedDeclaration" &&
+                exportDeclaration.declaration === current &&
+                hasSafetyJustificationBefore(sourceCode, exportDeclaration, node, pattern));
+        }
+        if (current.parent.type === "Program")
+            return false;
+        current = 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 `{{marker}}:` justification. State the checked invariant immediately before the assertion or its containing statement.",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    markers: {
+                        type: "array",
+                        items: { type: "string", minLength: 1 },
+                        minItems: 1,
+                        uniqueItems: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        defaultOptions: [{ markers: ["SAFETY"] }],
+    },
+    createOnce(context) {
+        const patterns = new Map();
+        const checkAssertion = (node) => {
+            if (isConstAssertion(node))
+                return;
+            const markers = configuredSafetyMarkers(context.options?.[0]);
+            const patternKey = markers.join("\u0000");
+            const pattern = patterns.get(patternKey) ?? markerPattern(markers);
+            patterns.set(patternKey, pattern);
+            if (hasSafetyComment(context.sourceCode, node, pattern))
+                return;
+            context.report({
+                node,
+                messageId: "missingSafetyComment",
+                data: { marker: markers[0] ?? DEFAULT_SAFETY_MARKERS[0] },
+            });
+        };
+        return {
+            TSAsExpression: checkAssertion,
+            TSTypeAssertion: checkAssertion,
+        };
+    },
+});

package/dist/shared/array-method.d.ts

@@ -0,0 +1,12 @@
+import type { ESTree, SourceCode, Variable } from "@oxlint/plugins";
+/** Unwrap syntax-only wrappers when inspecting array methods and accumulator references. */
+export declare function unwrapArrayExpression(node: ESTree.Node): ESTree.Node;
+/** Resolve a local binding by scope, not by identifier spelling. */
+export declare function resolveArrayBinding(sourceCode: SourceCode, node: ESTree.Node): Variable | null;
+/** Read static method names, including computed string literals, without evaluating expressions. */
+export declare function arrayMethodTarget(node: ESTree.Node): {
+    readonly name: string;
+    readonly object: ESTree.Node;
+} | null;
+/** Recognize local array evidence; unknown receivers and iterator pipelines are deliberately excluded. */
+export declare function isKnownArrayExpression(sourceCode: SourceCode, node: ESTree.Node, visited?: Set<Variable>): boolean;

package/dist/shared/array-method.js

@@ -0,0 +1,84 @@
+/** Unwrap syntax-only wrappers when inspecting array methods and accumulator references. */
+export function unwrapArrayExpression(node) {
+    while (node.type === "ParenthesizedExpression" ||
+        node.type === "ChainExpression" ||
+        node.type === "TSAsExpression" ||
+        node.type === "TSTypeAssertion" ||
+        node.type === "TSNonNullExpression" ||
+        node.type === "TSSatisfiesExpression") {
+        node = node.expression;
+    }
+    return node;
+}
+/** Resolve a local binding by scope, not by identifier spelling. */
+export function resolveArrayBinding(sourceCode, node) {
+    node = unwrapArrayExpression(node);
+    if (node.type !== "Identifier")
+        return null;
+    let scope = sourceCode.getScope(node);
+    while (scope !== null) {
+        const variable = scope.set.get(node.name);
+        if (variable !== undefined)
+            return variable;
+        scope = scope.upper;
+    }
+    return null;
+}
+/** Read static method names, including computed string literals, without evaluating expressions. */
+export function arrayMethodTarget(node) {
+    node = unwrapArrayExpression(node);
+    if (node.type !== "MemberExpression")
+        return null;
+    const property = node.property;
+    if (!node.computed && property.type === "Identifier") {
+        return { name: property.name, object: node.object };
+    }
+    if (node.computed && property.type === "Literal" && typeof property.value === "string") {
+        return { name: property.value, object: node.object };
+    }
+    return null;
+}
+function isArrayAnnotation(type) {
+    if (type.type === "TSArrayType" || type.type === "TSTupleType")
+        return true;
+    if (type.type === "TSParenthesizedType")
+        return isArrayAnnotation(type.typeAnnotation);
+    if (type.type === "TSTypeOperator" && type.operator === "readonly") {
+        return isArrayAnnotation(type.typeAnnotation);
+    }
+    return (type.type === "TSTypeReference" && type.typeName.type === "Identifier" &&
+        (type.typeName.name === "Array" || type.typeName.name === "ReadonlyArray"));
+}
+/** Recognize local array evidence; unknown receivers and iterator pipelines are deliberately excluded. */
+export function isKnownArrayExpression(sourceCode, node, visited = new Set()) {
+    node = unwrapArrayExpression(node);
+    if (node.type === "ArrayExpression")
+        return true;
+    if (node.type === "CallExpression") {
+        const method = arrayMethodTarget(node.callee);
+        return (method !== null &&
+            ["map", "filter", "flatMap", "slice", "concat", "toSorted", "toReversed", "toSpliced"].includes(method.name) &&
+            isKnownArrayExpression(sourceCode, method.object, visited));
+    }
+    if (node.type !== "Identifier")
+        return false;
+    const variable = resolveArrayBinding(sourceCode, node);
+    if (variable === null || visited.has(variable))
+        return false;
+    visited.add(variable);
+    if (variable.references.some(reference => reference.isWrite() && !reference.init))
+        return false;
+    for (const identifier of variable.identifiers) {
+        const annotation = identifier.typeAnnotation?.typeAnnotation;
+        if (annotation !== undefined)
+            return isArrayAnnotation(annotation);
+    }
+    for (const definition of variable.defs) {
+        if (definition.type === "Variable" && definition.node.type === "VariableDeclarator" &&
+            definition.node.id.type === "Identifier" && definition.node.init !== null &&
+            definition.node.parent.type === "VariableDeclaration" && definition.node.parent.kind === "const") {
+            return isKnownArrayExpression(sourceCode, definition.node.init, visited);
+        }
+    }
+    return false;
+}

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

@@ -0,0 +1,20 @@
+import type { ESTree } from "@oxlint/plugins";
+import { type TypeAliasEnvironment as LexicalTypeAliasEnvironment } from "./type-alias-resolution.ts";
+export type UnsafeDictionary = {
+    readonly kind: "unsafe-dictionary";
+    readonly unsafeValue: "any" | "empty-object" | "object" | "union" | "unknown";
+};
+export type WideningTargetKind = "anonymous object" | "generic container" | "object" | "open dictionary" | "unknown";
+export type WideningTarget = {
+    readonly kind: WideningTargetKind;
+};
+export type TypeEnvironment = {
+    readonly interfaces: ReadonlyMap<string, readonly ESTree.TSInterfaceDeclaration[]>;
+    readonly typeAliases: LexicalTypeAliasEnvironment;
+};
+export declare function createTypeEnvironment(program: ESTree.Program, visitorKeys: Readonly<Record<string, readonly string[]>>): 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 isPopulatedObjectExpression(expression: ESTree.Expression): boolean;
+export declare function isKnownEvidenceExpression(expression: ESTree.Expression): boolean;