@konvert7/klint 0.1.0

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@konvert7/klint",
+  "version": "0.1.0",
+  "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
+  "type": "module",
+  "bin": {
+    "klint": "cli.ts"
+  },
+  "files": [
+    "cli.ts",
+    "core",
+    "rules",
+    "plugins",
+    "skill",
+    "tools",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "keywords": [
+    "architecture",
+    "linter",
+    "typescript",
+    "bun",
+    "agent",
+    "agentic",
+    "arch-as-code"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/konvert7/klint.git"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "bun test",
+    "check": "biome check",
+    "check-write": "biome check --write",
+    "knip": "knip-bun",
+    "klint": "bun cli.ts",
+    "lint-staged": "lint-staged",
+    "prepare": "bun .husky/install.mjs"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "bun run check"
+    ]
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.3.0",
+    "typescript": "^5.9.3",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.7",
+    "@commitlint/cli": "^20.5.3",
+    "@commitlint/config-conventional": "^20.5.3",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@types/bun": "latest",
+    "@types/node": "latest",
+    "husky": "^9.1.7",
+    "knip": "^6.9.0",
+    "lint-staged": "^15.5.2",
+    "semantic-release": "^25.0.3"
+  },
+  "directories": {
+    "test": "tests"
+  },
+  "author": "Konvert7",
+  "bugs": {
+    "url": "https://github.com/konvert7/klint/issues"
+  },
+  "homepage": "https://github.com/konvert7/klint#readme"
+}

package/plugins/index.ts

@@ -0,0 +1,6 @@
+import type { KlintPlugin } from "../core/types";
+import { sonarPlugin } from "./sonar";
+
+export const BUILT_IN_PLUGINS: Record<string, KlintPlugin> = {
+  sonar: sonarPlugin,
+};

package/plugins/sonar.ts

@@ -0,0 +1,29 @@
+import type { KlintPlugin } from "../core/types";
+import { noSingleCharClass } from "../rules/no-single-char-class";
+import { preferAt } from "../rules/prefer-at";
+import { preferNullishCoalescingAssign } from "../rules/prefer-nullish-coalescing-assign";
+import { preferStringRaw } from "../rules/prefer-string-raw";
+import { preferStringRawRegexp } from "../rules/prefer-string-raw-regexp";
+import { preferStringReplaceall } from "../rules/prefer-string-replaceall";
+
+export const sonarPlugin: KlintPlugin = {
+  name: "sonar",
+  rules: {
+    "sonar/prefer-string-replaceall": "error",
+    "sonar/prefer-string-raw-regexp": "error",
+    "sonar/prefer-string-raw": "error",
+    "sonar/prefer-nullish-coalescing-assign": "error",
+    "sonar/no-single-char-class": "error",
+    "sonar/prefer-at": "error",
+  },
+  implementations: {
+    "sonar/prefer-string-replaceall": { check: preferStringReplaceall.check },
+    "sonar/prefer-string-raw-regexp": { check: preferStringRawRegexp.check },
+    "sonar/prefer-string-raw": { check: preferStringRaw.check },
+    "sonar/prefer-nullish-coalescing-assign": {
+      check: preferNullishCoalescingAssign.check,
+    },
+    "sonar/no-single-char-class": { check: noSingleCharClass.check },
+    "sonar/prefer-at": { check: preferAt.check },
+  },
+};

package/rules/index.ts

@@ -0,0 +1,26 @@
+import type { KlintRule } from "../core/types";
+import { noAsyncPredicate } from "./no-async-predicate";
+import { noConsecutiveArrayPush } from "./no-consecutive-array-push";
+import { noDateEquality } from "./no-date-equality";
+import { noFloatingPromise } from "./no-floating-promise";
+import { noMisusedPromises } from "./no-misused-promises";
+import { noNestedTemplateLiterals } from "./no-nested-template-literals";
+import { noObjectInTemplate } from "./no-object-in-template";
+import { noOptionalChainOnNonNullable } from "./no-optional-chain-on-non-nullable";
+import { noStringMatch } from "./no-string-match";
+import { noSyncInAsync } from "./no-sync-in-async";
+import { noUnguardedJsonParse } from "./no-unguarded-json-parse";
+
+export const BUILT_IN_RULES: Record<string, KlintRule> = {
+  "no-unguarded-json-parse": noUnguardedJsonParse,
+  "no-sync-in-async": noSyncInAsync,
+  "no-floating-promise": noFloatingPromise,
+  "no-misused-promises": noMisusedPromises,
+  "no-async-predicate": noAsyncPredicate,
+  "no-date-equality": noDateEquality,
+  "no-optional-chain-on-non-nullable": noOptionalChainOnNonNullable,
+  "no-object-in-template": noObjectInTemplate,
+  "no-nested-template-literals": noNestedTemplateLiterals,
+  "no-consecutive-array-push": noConsecutiveArrayPush,
+  "no-string-match": noStringMatch,
+};

package/rules/no-async-predicate.ts

@@ -0,0 +1,72 @@
+import { relative } from "node:path";
+import ts from "typescript";
+import { createProgram } from "../core/ast";
+import type { RawViolation } from "../core/types";
+import { defineRule } from "../core/types";
+
+const PREDICATE_METHODS = new Set(["filter", "some", "every", "find", "findIndex"]);
+
+export const noAsyncPredicate = defineRule({
+  check({ files, root }, violations) {
+    const program = createProgram(files, root);
+    const checker = program.getTypeChecker();
+    const fileSet = new Set(files);
+
+    for (const sourceFile of program.getSourceFiles()) {
+      if (!fileSet.has(sourceFile.fileName) || sourceFile.isDeclarationFile) continue;
+      visitFile(sourceFile, checker, root, violations);
+    }
+  },
+});
+
+function visitFile(
+  sourceFile: ts.SourceFile,
+  checker: ts.TypeChecker,
+  root: string,
+  violations: RawViolation[]
+): void {
+  function visit(node: ts.Node): void {
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      PREDICATE_METHODS.has(node.expression.name.text) &&
+      node.arguments.length > 0
+    ) {
+      const receiverType = checker.getTypeAtLocation(node.expression.expression);
+      if (isArrayLike(receiverType, checker) && isAsyncFunction(node.arguments[0])) {
+        const method = node.expression.name.text;
+        const { line } = sourceFile.getLineAndCharacterOfPosition(
+          node.arguments[0].getStart()
+        );
+        violations.push({
+          file: relative(root, sourceFile.fileName),
+          line: line + 1,
+          message: `Async callback passed to .${method}() — the returned Promise is always truthy, so the predicate never filters correctly. The array method cannot await it.`,
+        });
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+}
+
+function isArrayLike(type: ts.Type, checker: ts.TypeChecker): boolean {
+  if (type.isUnion()) return type.types.some((t) => isArrayLike(t, checker));
+  const sym = type.getSymbol();
+  if (sym?.name === "Array" || sym?.name === "ReadonlyArray") return true;
+  const ref = type as ts.TypeReference;
+  if (ref.target) {
+    const targetSym = ref.target.getSymbol();
+    if (targetSym?.name === "Array" || targetSym?.name === "ReadonlyArray") return true;
+  }
+  return false;
+}
+
+function isAsyncFunction(
+  node: ts.Node
+): node is ts.ArrowFunction | ts.FunctionExpression {
+  return (
+    (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
+    (node.modifiers?.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword) ?? false)
+  );
+}

package/rules/no-consecutive-array-push.ts

@@ -0,0 +1,56 @@
+import { relative } from "node:path";
+import ts from "typescript";
+import { walkAst } from "../core/ast";
+import type { KlintRule } from "../core/types";
+
+export const noConsecutiveArrayPush: KlintRule = {
+  check({ files, root, fileContents }, violations) {
+    for (const file of files) {
+      const content = fileContents.get(file) ?? "";
+      walkAst(file, content, (node, src) => {
+        const statements =
+          ts.isBlock(node) || ts.isSourceFile(node) ? node.statements : null;
+        if (!statements) return;
+
+        let runStart = -1;
+        let runReceiver = "";
+
+        const flush = (upTo: number) => {
+          if (runStart !== -1 && upTo - runStart >= 2) {
+            const { line } = src.getLineAndCharacterOfPosition(
+              statements[runStart].getStart()
+            );
+            violations.push({
+              file: relative(root, file),
+              line: line + 1,
+              message: `${upTo - runStart} consecutive .push() calls on \`${runReceiver}\` — combine into a single .push(a, b, …) call.`,
+            });
+          }
+          runStart = -1;
+          runReceiver = "";
+        };
+
+        for (let i = 0; i < statements.length; i++) {
+          const receiver = getPushReceiver(statements[i], src);
+          if (receiver && receiver === runReceiver) {
+            // continue the run
+          } else {
+            flush(i);
+            runStart = receiver ? i : -1;
+            runReceiver = receiver ?? "";
+          }
+        }
+        flush(statements.length);
+      });
+    }
+  },
+};
+
+function getPushReceiver(node: ts.Statement, src: ts.SourceFile): string | null {
+  if (!ts.isExpressionStatement(node)) return null;
+  const expr = node.expression;
+  if (!ts.isCallExpression(expr)) return null;
+  if (!ts.isPropertyAccessExpression(expr.expression)) return null;
+  if (expr.expression.name.text !== "push") return null;
+  return expr.expression.expression.getText(src);
+}

package/rules/no-date-equality.ts

@@ -0,0 +1,55 @@
+import { relative } from "node:path";
+import ts from "typescript";
+import { createProgram } from "../core/ast";
+import type { RawViolation } from "../core/types";
+import { defineRule } from "../core/types";
+
+export const noDateEquality = defineRule({
+  check({ files, root }, violations) {
+    const program = createProgram(files, root);
+    const checker = program.getTypeChecker();
+    const fileSet = new Set(files);
+
+    for (const sourceFile of program.getSourceFiles()) {
+      if (!fileSet.has(sourceFile.fileName) || sourceFile.isDeclarationFile) continue;
+      visitFile(sourceFile, checker, root, violations);
+    }
+  },
+});
+
+function visitFile(
+  sourceFile: ts.SourceFile,
+  checker: ts.TypeChecker,
+  root: string,
+  violations: RawViolation[]
+): void {
+  function visit(node: ts.Node): void {
+    if (ts.isBinaryExpression(node)) {
+      const { kind } = node.operatorToken;
+      if (
+        kind === ts.SyntaxKind.EqualsEqualsEqualsToken ||
+        kind === ts.SyntaxKind.ExclamationEqualsEqualsToken
+      ) {
+        const leftType = checker.getTypeAtLocation(node.left);
+        const rightType = checker.getTypeAtLocation(node.right);
+        if (isDateType(leftType) && isDateType(rightType)) {
+          const op = node.operatorToken.getText(sourceFile);
+          const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+          violations.push({
+            file: relative(root, sourceFile.fileName),
+            line: line + 1,
+            message: `Date values compared with ${op} — this compares object references, not time values. Use .getTime() or .valueOf() instead.`,
+          });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+}
+
+function isDateType(type: ts.Type): boolean {
+  if (type.getSymbol()?.name === "Date") return true;
+  if (type.isUnion()) return type.types.some(isDateType);
+  return false;
+}

package/rules/no-floating-promise.ts

@@ -0,0 +1,58 @@
+import { relative } from "node:path";
+import ts from "typescript";
+import { createProgram } from "../core/ast";
+import type { RawViolation } from "../core/types";
+import { defineRule } from "../core/types";
+
+export const noFloatingPromise = defineRule({
+  check({ files, root }, violations) {
+    const program = createProgram(files, root);
+    const checker = program.getTypeChecker();
+    const fileSet = new Set(files);
+
+    for (const sourceFile of program.getSourceFiles()) {
+      if (!fileSet.has(sourceFile.fileName) || sourceFile.isDeclarationFile) continue;
+      visitFile(sourceFile, checker, root, violations);
+    }
+  },
+});
+
+function visitFile(
+  sourceFile: ts.SourceFile,
+  checker: ts.TypeChecker,
+  root: string,
+  violations: RawViolation[]
+): void {
+  function visit(node: ts.Node): void {
+    if (
+      ts.isExpressionStatement(node) &&
+      ts.isCallExpression(node.expression) &&
+      !isHandled(node.expression)
+    ) {
+      const type = checker.getTypeAtLocation(node.expression);
+      if (isPromiseLike(type)) {
+        const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+        violations.push({
+          file: relative(root, sourceFile.fileName),
+          line: line + 1,
+          message:
+            "Promise-returning call is not awaited — errors will be silently discarded and execution order is unpredictable. Use await, void, or .catch().",
+        });
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+}
+
+function isHandled(node: ts.CallExpression): boolean {
+  if (!ts.isPropertyAccessExpression(node.expression)) return false;
+  const name = node.expression.name.text;
+  return name === "catch" || name === "finally";
+}
+
+function isPromiseLike(type: ts.Type): boolean {
+  if (type.getSymbol()?.name === "Promise") return true;
+  if (type.isUnion()) return type.types.some(isPromiseLike);
+  return false;
+}

package/rules/no-misused-promises.ts

@@ -0,0 +1,82 @@
+import { relative } from "node:path";
+import ts from "typescript";
+import { createProgram } from "../core/ast";
+import type { RawViolation } from "../core/types";
+import { defineRule } from "../core/types";
+
+export const noMisusedPromises = defineRule({
+  check({ files, root }, violations) {
+    const program = createProgram(files, root);
+    const checker = program.getTypeChecker();
+    const fileSet = new Set(files);
+
+    for (const sourceFile of program.getSourceFiles()) {
+      if (!fileSet.has(sourceFile.fileName) || sourceFile.isDeclarationFile) continue;
+      visitFile(sourceFile, checker, root, violations);
+    }
+  },
+});
+
+function visitFile(
+  sourceFile: ts.SourceFile,
+  checker: ts.TypeChecker,
+  root: string,
+  violations: RawViolation[]
+): void {
+  function visit(node: ts.Node): void {
+    if (ts.isCallExpression(node)) {
+      const sig = checker.getResolvedSignature(node);
+      if (sig) {
+        const params = sig.getParameters();
+        for (let i = 0; i < node.arguments.length; i++) {
+          const arg = node.arguments[i];
+          if (!isAsyncFunction(arg)) continue;
+
+          const param = params[Math.min(i, params.length - 1)];
+          if (!param) continue;
+
+          const paramType = checker.getTypeOfSymbolAtLocation(param, node);
+          if (expectsSyncCallback(paramType, checker)) {
+            const { line } = sourceFile.getLineAndCharacterOfPosition(arg.getStart());
+            violations.push({
+              file: relative(root, sourceFile.fileName),
+              line: line + 1,
+              message:
+                "Async function passed where a sync callback is expected — the caller cannot await it and errors will be silently lost.",
+            });
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+}
+
+function isAsyncFunction(
+  node: ts.Node
+): node is ts.ArrowFunction | ts.FunctionExpression {
+  return (
+    (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
+    (node.modifiers?.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword) ?? false)
+  );
+}
+
+function expectsSyncCallback(type: ts.Type, checker: ts.TypeChecker): boolean {
+  if (type.isUnion()) {
+    const callable = type.types.filter(
+      (t) => !(t.flags & ts.TypeFlags.Undefined) && !(t.flags & ts.TypeFlags.Null)
+    );
+    return callable.length > 0 && callable.every((t) => expectsSyncCallback(t, checker));
+  }
+  const sigs = type.getCallSignatures();
+  if (sigs.length === 0) return false;
+  return sigs.every((sig) => !returnsPromise(checker.getReturnTypeOfSignature(sig)));
+}
+
+function returnsPromise(type: ts.Type): boolean {
+  const name = type.getSymbol()?.name;
+  if (name === "Promise" || name === "PromiseLike") return true;
+  if (type.isUnion()) return type.types.some(returnsPromise);
+  return false;
+}

package/rules/no-nested-template-literals.ts

@@ -0,0 +1,42 @@
+import { relative } from "node:path";
+import ts from "typescript";
+import { walkAst } from "../core/ast";
+import type { KlintRule } from "../core/types";
+
+export const noNestedTemplateLiterals: KlintRule = {
+  check({ files, root, fileContents }, violations) {
+    for (const file of files) {
+      const content = fileContents.get(file) ?? "";
+      walkAst(file, content, (node, src) => {
+        if (!ts.isTemplateExpression(node)) return;
+        for (const span of node.templateSpans) {
+          findNestedTemplate(span.expression, src, file, root, violations);
+        }
+      });
+    }
+  },
+};
+
+function findNestedTemplate(
+  node: ts.Node,
+  src: ts.SourceFile,
+  file: string,
+  root: string,
+  violations: ReturnType<typeof Array.prototype.slice>
+): void {
+  if (ts.isTemplateExpression(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    const { line } = src.getLineAndCharacterOfPosition(node.getStart());
+    violations.push({
+      file: relative(root, file),
+      line: line + 1,
+      message:
+        "Nested template literal — extract the inner template to a variable to improve readability.",
+    });
+    return;
+  }
+  // Don't descend into tagged templates — they are a single semantic unit
+  if (ts.isTaggedTemplateExpression(node)) return;
+  ts.forEachChild(node, (child) =>
+    findNestedTemplate(child, src, file, root, violations)
+  );
+}

package/rules/no-object-in-template.ts

@@ -0,0 +1,119 @@
+import { relative } from "node:path";
+import ts from "typescript";
+import { createProgram } from "../core/ast";
+import type { RawViolation } from "../core/types";
+import { defineRule } from "../core/types";
+
+// Builtins with a meaningful toString() that isn't [object Object]
+const SAFE_SYMBOL_NAMES = new Set([
+  "Date",
+  "RegExp",
+  "Error",
+  "TypeError",
+  "RangeError",
+  "SyntaxError",
+  "ReferenceError",
+  "Array",
+  "Map",
+  "Set",
+  "URL",
+  "URLSearchParams",
+  "Symbol",
+]);
+
+export const noObjectInTemplate = defineRule({
+  check({ files, root }, violations) {
+    const program = createProgram(files, root);
+    const checker = program.getTypeChecker();
+    const fileSet = new Set(files);
+
+    for (const sourceFile of program.getSourceFiles()) {
+      if (!fileSet.has(sourceFile.fileName) || sourceFile.isDeclarationFile) continue;
+      visitFile(sourceFile, checker, root, violations);
+    }
+  },
+});
+
+function visitFile(
+  sourceFile: ts.SourceFile,
+  checker: ts.TypeChecker,
+  root: string,
+  violations: RawViolation[]
+): void {
+  function visit(node: ts.Node): void {
+    if (ts.isTemplateExpression(node)) {
+      for (const span of node.templateSpans) {
+        const type = checker.getTypeAtLocation(span.expression);
+        if (wouldRenderAsObjectObject(type, checker)) {
+          const { line } = sourceFile.getLineAndCharacterOfPosition(
+            span.expression.getStart()
+          );
+          violations.push({
+            file: relative(root, sourceFile.fileName),
+            line: line + 1,
+            message:
+              "Object interpolated in template literal has no custom toString() — it will render as [object Object]. Access a specific property or implement toString().",
+          });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+}
+
+function wouldRenderAsObjectObject(type: ts.Type, checker: ts.TypeChecker): boolean {
+  const primitiveFlags =
+    ts.TypeFlags.String |
+    ts.TypeFlags.Number |
+    ts.TypeFlags.Boolean |
+    ts.TypeFlags.BigInt |
+    ts.TypeFlags.Null |
+    ts.TypeFlags.Undefined |
+    ts.TypeFlags.StringLiteral |
+    ts.TypeFlags.NumberLiteral |
+    ts.TypeFlags.BooleanLiteral |
+    ts.TypeFlags.BigIntLiteral |
+    ts.TypeFlags.Any |
+    ts.TypeFlags.Unknown |
+    ts.TypeFlags.Never |
+    ts.TypeFlags.Void |
+    ts.TypeFlags.ESSymbol |
+    ts.TypeFlags.UniqueESSymbol |
+    ts.TypeFlags.Enum |
+    ts.TypeFlags.EnumLiteral;
+
+  if (type.flags & primitiveFlags) return false;
+
+  if (type.isUnion()) {
+    const meaningful = type.types.filter(
+      (t) => !(t.flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined))
+    );
+    return (
+      meaningful.length > 0 &&
+      meaningful.every((t) => wouldRenderAsObjectObject(t, checker))
+    );
+  }
+
+  // Functions coerce to their source string — unusual but not [object Object]
+  if (type.getCallSignatures().length > 0) return false;
+
+  // Known builtins with meaningful toString
+  const sym = type.getSymbol();
+  if (sym && SAFE_SYMBOL_NAMES.has(sym.name)) return false;
+
+  // Check for a custom toString not originating from TypeScript's built-in lib
+  const toStringProp = checker.getPropertyOfType(type, "toString");
+  if (!toStringProp) return true;
+
+  const decls = toStringProp.getDeclarations() ?? [];
+  const hasCustomToString = decls.some((d) => {
+    const fileName = d.getSourceFile().fileName;
+    return (
+      !fileName.includes("/typescript/lib/lib") &&
+      !fileName.includes("\\typescript\\lib\\lib")
+    );
+  });
+
+  return !hasCustomToString;
+}