@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/magic/magic-numbers.ts

@@ -0,0 +1,117 @@
+/**
+ * Numbers that name nothing: a literal passes as the value of a `const` (directly, or in its array, object or
+ * arithmetic), of an enum member or of a `readonly` class property; else only 0 and 1, the identity values, and a 2
+ * that scales. A schema bound, an argument of `.max(…)` and its kin on a value with a `parse` method, must be a
+ * constant imported from a constants file or package.
+ */
+import ts from "typescript";
+import { hitAt, isConstantsModule, isConstDeclaration } from "./magic-nodes.ts";
+import { MAGIC_NUMBER } from "../lint/script-rules.ts";
+import type { MagicHit } from "./magic-hit.ts";
+
+const SCHEMA_BOUNDS = ["min", "max", "length", "gt", "gte", "lt", "lte", "multipleOf", "size"];
+/** A schema is a value with this method. */
+const PARSE = "parse";
+const IDENTITIES = [0, 1];
+const SCALE = 2;
+const SCALING = [
+  ts.SyntaxKind.AsteriskToken,
+  ts.SyntaxKind.SlashToken,
+  ts.SyntaxKind.PercentToken,
+  ts.SyntaxKind.AsteriskAsteriskToken,
+];
+const ARITHMETIC = [...SCALING, ts.SyntaxKind.PlusToken, ts.SyntaxKind.MinusToken];
+/** What a literal sits in and still names what the const, enum member or readonly field around it names. */
+const CONTAINERS = [
+  ts.SyntaxKind.ParenthesizedExpression,
+  ts.SyntaxKind.AsExpression,
+  ts.SyntaxKind.SatisfiesExpression,
+  ts.SyntaxKind.ArrayLiteralExpression,
+  ts.SyntaxKind.ObjectLiteralExpression,
+  ts.SyntaxKind.PropertyAssignment,
+  ts.SyntaxKind.PrefixUnaryExpression,
+];
+
+const NAMES_NOTHING = (text: string) => `${text} names nothing; give it a named const`;
+const BOUND = (method: string, arg: ts.Node) =>
+  `.${method}(${arg.getText()}) is a schema bound; import it from a *.constants.ts file or a constants package`;
+
+const isArithmetic = (node: ts.Node) => ts.isBinaryExpression(node) && ARITHMETIC.includes(node.operatorToken.kind);
+const isScaling = (node: ts.Node) => ts.isBinaryExpression(node) && SCALING.includes(node.operatorToken.kind);
+
+/** The literal with its minus: `-1` is one value. */
+function unitOf(literal: ts.NumericLiteral): ts.Expression {
+  const { parent } = literal;
+  return ts.isPrefixUnaryExpression(parent) && parent.operator === ts.SyntaxKind.MinusToken ? parent : literal;
+}
+
+/** Whether `unit`, climbed through its containers, is what a `const`, an enum member or a readonly field holds. */
+function isNamed(unit: ts.Node): boolean {
+  let node = unit;
+  while (CONTAINERS.includes(node.parent.kind) || isArithmetic(node.parent)) node = node.parent;
+  const holder = node.parent;
+  if (ts.isVariableDeclaration(holder)) return isConstDeclaration(holder);
+  if (ts.isPropertyDeclaration(holder)) return (ts.getCombinedModifierFlags(holder) & ts.ModifierFlags.Readonly) !== 0;
+  return ts.isEnumMember(holder);
+}
+
+/** The method of a schema-bound call `node` is, like `max` in `z.string().max(2048)`; null for any other node. */
+function boundOf(node: ts.Node, checker: ts.TypeChecker): string | null {
+  if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return null;
+  const method = node.expression.name.text;
+  if (!SCHEMA_BOUNDS.includes(method)) return null;
+  const receiver = checker.getTypeAtLocation(node.expression.expression);
+  return receiver.getProperty(PARSE) === undefined ? null : method;
+}
+
+function numberHit(literal: ts.NumericLiteral, checker: ts.TypeChecker): MagicHit | null {
+  const unit = unitOf(literal);
+  if (ts.isLiteralTypeNode(unit.parent)) return null;
+  const magnitude = Number(literal.text);
+  const value = unit === literal ? magnitude : -magnitude;
+  if (IDENTITIES.includes(value)) return null;
+  if (value === SCALE && unit === literal && isScaling(unit.parent)) return null;
+  const method = boundOf(unit.parent, checker);
+  if (method !== null) return hitAt(unit, MAGIC_NUMBER, BOUND(method, unit));
+  return isNamed(unit) ? null : hitAt(unit, MAGIC_NUMBER, NAMES_NOTHING(unit.getText()));
+}
+
+/**
+ * Whether a bound argument names a local `const` or an import from a module that is not a constants file or
+ * package; a parameter, a `let` or anything computed passes, being no fixed number.
+ */
+function isLocalBound(arg: ts.Expression, checker: ts.TypeChecker): boolean {
+  let root = arg;
+  while (ts.isPropertyAccessExpression(root)) root = root.expression;
+  if (!ts.isIdentifier(root)) return false;
+  const declaration = checker.getSymbolAtLocation(root)?.declarations?.[0];
+  if (declaration === undefined) return false;
+  const imported = ts.findAncestor(declaration, ts.isImportDeclaration);
+  if (imported === undefined) return ts.isVariableDeclaration(declaration) && isConstDeclaration(declaration);
+  const specifier =
+    imported.moduleSpecifier /* an import that parses names its module in a string literal */ as ts.StringLiteral;
+  return !isConstantsModule(specifier.text);
+}
+
+function boundHits(call: ts.CallExpression, checker: ts.TypeChecker): MagicHit[] {
+  const method = boundOf(call, checker);
+  if (method === null) return [];
+  return call.arguments
+    .filter((arg) => isLocalBound(arg, checker))
+    .map((arg) => hitAt(arg, MAGIC_NUMBER, BOUND(method, arg)));
+}
+
+/** Every magic number of `file` and every schema bound not imported from a constants home, in source order. */
+export function magicNumbers(file: ts.SourceFile, checker: ts.TypeChecker): MagicHit[] {
+  const hits: MagicHit[] = [];
+  const visit = (node: ts.Node): void => {
+    if (ts.isNumericLiteral(node)) {
+      const found = numberHit(node, checker);
+      if (found !== null) hits.push(found);
+    }
+    if (ts.isCallExpression(node)) hits.push(...boundHits(node, checker));
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+  return hits;
+}

package/cli/magic/magic-strings.test.ts

@@ -0,0 +1,38 @@
+import { afterEach, expect, it } from "vitest";
+import { cleanTemps, COMPARED, COPIES, hit, magicOf, STRING } from "./fixtures/magic-repo.ts";
+
+afterEach(cleanTemps);
+
+it("refuses a string compared to string | undefined, unknown or any, from either side", () => {
+  const kinds = [
+    "export function k(a: string | undefined, b: 'a' | null, c: unknown, d: any): boolean {",
+    "  return a === 'on' || b === 'a' || 'on' !== c || d != `on`;",
+    "}",
+    "",
+  ].join("\n");
+  expect(magicOf({ "src/kinds.ts": kinds })).toEqual([
+    hit("src/kinds.ts:2:16", STRING, COMPARED("on")),
+    hit("src/kinds.ts:2:37", STRING, COMPARED("on")),
+    hit("src/kinds.ts:2:56", STRING, COMPARED("on")),
+  ]);
+});
+
+it("reports a const copy once at its declaration, through an import alias, and not one in a constants file", () => {
+  const files = {
+    "src/modes.ts": 'export const SLOW = "slow";\nexport const LAZY = ("lazy") as const;\nexport const SEP = "/";\n',
+    "src/modes.constants.ts": 'export const QUICK = "quick";\n',
+    "src/use.ts": [
+      'import { LAZY, SEP, SLOW as S } from "./modes.ts";',
+      'import { QUICK } from "./modes.constants.ts";',
+      "let late = 'x';",
+      "const N = 5;",
+      "export const is = (m: string, n: number) =>",
+      "  m === S || m == S || m === LAZY || m === QUICK || m === SEP || m === late || n === N || m === undefined;",
+      "",
+    ].join("\n"),
+  };
+  expect(magicOf(files)).toEqual([
+    hit("src/modes.ts:1:14", STRING, COPIES("SLOW", "slow")),
+    hit("src/modes.ts:2:14", STRING, COPIES("LAZY", "lazy")),
+  ]);
+});

package/cli/magic/magic-strings.ts

@@ -0,0 +1,81 @@
+/**
+ * Strings compared to a value the type checker leaves untyped: in `===` `!==` `==` `!=` or a `case`, a string literal
+ * against a `string`, `any` or `unknown` (a literal union, template literal or branded string passes), and a local
+ * `const` copy of one, reported at its declaration. An empty or punctuation-only string passes.
+ */
+import ts from "typescript";
+import { CONSTANTS_FILE, constString, hitAt, isMeaningful } from "./magic-nodes.ts";
+import { MAGIC_STRING } from "../lint/script-rules.ts";
+import type { MagicHit } from "./magic-hit.ts";
+
+/** The checker of the program, and whether a file is one the check reports in. */
+export type Context = { checker: ts.TypeChecker; owns: (fileName: string) => boolean };
+
+const EQUALITY = [
+  ts.SyntaxKind.EqualsEqualsEqualsToken,
+  ts.SyntaxKind.ExclamationEqualsEqualsToken,
+  ts.SyntaxKind.EqualsEqualsToken,
+  ts.SyntaxKind.ExclamationEqualsToken,
+];
+const NULLISH = ts.TypeFlags.Null | ts.TypeFlags.Undefined;
+const PLAIN = ts.TypeFlags.String | ts.TypeFlags.Any | ts.TypeFlags.Unknown;
+
+const COMPARED = (text: string) =>
+  `${JSON.stringify(text)} is compared to a plain string; type the value as a literal union or brand, or import the string from a *.constants.ts file`;
+const COPIES = (name: string, text: string) =>
+  `${name} copies ${JSON.stringify(text)} locally to compare to a plain string; move it to a *.constants.ts file`;
+
+/** `string`, `any` or `unknown`, alone or in a union beside `null` or `undefined`. */
+function isUntyped(type: ts.Type): boolean {
+  if (type.isUnion()) return type.types.some((member) => (member.flags & NULLISH) === 0 && isUntyped(member));
+  return (type.flags & PLAIN) !== 0;
+}
+
+/** Each side of a comparison with the side it is compared to. */
+function comparedPairs(node: ts.Node): [ts.Expression, ts.Expression][] {
+  if (ts.isBinaryExpression(node) && EQUALITY.includes(node.operatorToken.kind))
+    return [
+      [node.left, node.right],
+      [node.right, node.left],
+    ];
+  return ts.isCaseClause(node) ? [[node.expression, node.parent.parent.expression]] : [];
+}
+
+/** The declaration of the `const` an identifier names, through an import alias; null for anything else. */
+function constOf(id: ts.Identifier, checker: ts.TypeChecker): ts.VariableDeclaration | null {
+  const symbol = checker.getSymbolAtLocation(id);
+  const target =
+    symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
+  const declaration = target?.valueDeclaration;
+  return declaration !== undefined && ts.isVariableDeclaration(declaration) ? declaration : null;
+}
+
+/** The hit at a local `const` string the identifier names, outside a constants file; null when it names none. */
+function copyHit(id: ts.Identifier, { checker, owns }: Context): MagicHit | null {
+  const declaration = constOf(id, checker);
+  if (declaration === null) return null;
+  const text = constString(declaration);
+  const { fileName } = declaration.getSourceFile();
+  if (text === null || !owns(fileName) || CONSTANTS_FILE.test(fileName)) return null;
+  return hitAt(declaration.name, MAGIC_STRING, COPIES(declaration.name.getText(), text));
+}
+
+/** The hit `side` would make compared to a plain string: a literal at itself, a const copy at its declaration. */
+function sideHit(side: ts.Expression, context: Context): MagicHit | null {
+  if (isMeaningful(side)) return hitAt(side, MAGIC_STRING, COMPARED(side.text));
+  return ts.isIdentifier(side) ? copyHit(side, context) : null;
+}
+
+/** Every magic string of `file`; a copy's hit is at its declaration, which `owns` must own. */
+export function magicStrings(file: ts.SourceFile, context: Context): MagicHit[] {
+  const hits: MagicHit[] = [];
+  const visit = (node: ts.Node): void => {
+    for (const [side, other] of comparedPairs(node)) {
+      const found = sideHit(side, context);
+      if (found !== null && isUntyped(context.checker.getTypeAtLocation(other))) hits.push(found);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+  return hits;
+}