@konvert7/klint 0.1.0

package/core/arch.ts

@@ -0,0 +1,238 @@
+import { dirname, relative, resolve } from "node:path";
+import ts from "typescript";
+import { walkAst } from "./ast";
+import type { ArchConfig, Severity, Violation } from "./types";
+
+interface AliasEntry {
+  /** The prefix to match (pattern with `/*` stripped, e.g. `"@"` from `"@/*"`). */
+  prefix: string;
+  /** Resolved absolute base directory (target with `/*` stripped). */
+  base: string;
+  isWildcard: boolean;
+}
+
+function loadPathAliases(root: string): AliasEntry[] {
+  const tsconfigPath = resolve(root, "tsconfig.json");
+  const parsed = ts.getParsedCommandLineOfConfigFile(tsconfigPath, undefined, {
+    ...ts.sys,
+    onUnRecoverableConfigFileDiagnostic: () => {},
+  });
+  if (!parsed) return [];
+  const { paths, baseUrl } = parsed.options;
+  if (!paths) return [];
+  // baseUrl is absolute when set; fall back to tsconfig dir for TS 5+ pathless baseUrl
+  const base = baseUrl ?? root;
+  const entries: AliasEntry[] = [];
+  for (const [pattern, targets] of Object.entries(paths)) {
+    if (targets.length === 0) continue;
+    const isWildcard = pattern.endsWith("/*");
+    const prefix = isWildcard ? pattern.slice(0, -2) : pattern;
+    const targetStr = targets[0];
+    const targetBase = targetStr.endsWith("/*") ? targetStr.slice(0, -2) : targetStr;
+    entries.push({ prefix, base: resolve(base, targetBase), isWildcard });
+  }
+  return entries;
+}
+
+function resolveAlias(importPath: string, aliases: AliasEntry[]): string | undefined {
+  for (const alias of aliases) {
+    if (alias.isWildcard) {
+      const matchPrefix = `${alias.prefix}/`;
+      if (importPath.startsWith(matchPrefix)) {
+        return resolve(alias.base, importPath.slice(matchPrefix.length));
+      }
+    } else if (importPath === alias.prefix) {
+      return alias.base;
+    }
+  }
+  return undefined;
+}
+
+interface ImportRecord {
+  path: string;
+  resolved: string;
+  isTypeOnly: boolean;
+  line: number;
+}
+
+function isBareSpecifier(path: string): boolean {
+  return !path.startsWith(".") && !path.startsWith("/");
+}
+
+function globToPrefix(glob: string, root: string): string {
+  return resolve(root, glob.split("/**")[0].split("/*")[0].split("*")[0]);
+}
+
+function resolveGlobs(
+  ref: string | string[],
+  layers: Record<string, string[]> | undefined
+): string[] {
+  const items = Array.isArray(ref) ? ref : [ref];
+  return items.flatMap((item) => layers?.[item] ?? [item]);
+}
+
+function resolveLayerPrefixes(
+  ref: string | string[],
+  layers: Record<string, string[]> | undefined,
+  root: string
+): string[] {
+  return resolveGlobs(ref, layers).map((g) => globToPrefix(g, root));
+}
+
+function resolveLayerFiles(
+  ref: string | string[],
+  layers: Record<string, string[]> | undefined,
+  root: string,
+  allFiles: string[]
+): string[] {
+  const prefixes = resolveLayerPrefixes(ref, layers, root);
+  return allFiles.filter((f) => prefixes.some((p) => f === p || f.startsWith(`${p}/`)));
+}
+
+function inPrefixes(absPath: string, prefixes: string[]): boolean {
+  return prefixes.some((p) => absPath === p || absPath.startsWith(`${p}/`));
+}
+
+function scanImports(
+  file: string,
+  content: string,
+  aliases: AliasEntry[]
+): ImportRecord[] {
+  const records: ImportRecord[] = [];
+  const fileDir = dirname(file);
+
+  walkAst(file, content, (node, src) => {
+    let specifierNode: ts.StringLiteral | undefined;
+    let isTypeOnly = false;
+
+    if (ts.isImportDeclaration(node)) {
+      if (ts.isStringLiteral(node.moduleSpecifier)) {
+        specifierNode = node.moduleSpecifier;
+        isTypeOnly = node.importClause?.isTypeOnly ?? false;
+      }
+    } else if (
+      ts.isCallExpression(node) &&
+      node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+      node.arguments.length >= 1 &&
+      ts.isStringLiteral(node.arguments[0])
+    ) {
+      specifierNode = node.arguments[0] as ts.StringLiteral;
+    }
+
+    if (!specifierNode) return;
+
+    const path = specifierNode.text;
+    let resolved: string;
+    if (isBareSpecifier(path)) {
+      resolved = resolveAlias(path, aliases) ?? path;
+    } else {
+      resolved = resolve(fileDir, path);
+    }
+    const { line } = src.getLineAndCharacterOfPosition(specifierNode.getStart());
+    records.push({ path, resolved, isTypeOnly, line: line + 1 });
+  });
+
+  return records;
+}
+
+export function runArchRules(
+  arch: ArchConfig,
+  allFiles: string[],
+  fileContents: Map<string, string>,
+  root: string
+): Violation[] {
+  const violations: Violation[] = [];
+  const layers = arch.layers;
+  const aliases = loadPathAliases(root);
+
+  for (const rule of arch.imports ?? []) {
+    const severity: Severity = rule.severity ?? "error";
+    const fromFiles = resolveLayerFiles(rule.from, layers, root, allFiles);
+
+    for (const file of fromFiles) {
+      const content = fileContents.get(file);
+      if (!content) continue;
+
+      for (const imp of scanImports(file, content, aliases)) {
+        if (isBareSpecifier(imp.resolved)) continue;
+        if (rule["type-only"] === "allow" && imp.isTypeOnly) continue;
+
+        const relFile = relative(root, file).replaceAll("\\", "/");
+
+        if (rule.deny !== undefined) {
+          const denyPrefixes = resolveLayerPrefixes(rule.deny, layers, root);
+          if (inPrefixes(imp.resolved, denyPrefixes)) {
+            violations.push({
+              file: relFile,
+              line: imp.line,
+              message: rule.message ?? "Import crosses a denied boundary",
+              rule: "arch/imports",
+              severity,
+            });
+          }
+        } else if (rule.allow !== undefined) {
+          const allowPrefixes = resolveLayerPrefixes(rule.allow, layers, root);
+          if (!inPrefixes(imp.resolved, allowPrefixes)) {
+            violations.push({
+              file: relFile,
+              line: imp.line,
+              message: rule.message ?? "Import is not in the allowed list",
+              rule: "arch/imports",
+              severity,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  for (const rule of arch.forbidden ?? []) {
+    const severity: Severity = rule.severity ?? "error";
+    const inFiles = resolveLayerFiles(rule.in, layers, root, allFiles);
+
+    for (const file of inFiles) {
+      const content = fileContents.get(file);
+      if (!content) continue;
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes(rule.pattern)) {
+          violations.push({
+            file: relative(root, file).replaceAll("\\", "/"),
+            line: i + 1,
+            message: rule.message,
+            rule: "arch/forbidden",
+            severity,
+          });
+        }
+      }
+    }
+  }
+
+  for (const rule of arch.singleton ?? []) {
+    const severity: Severity = rule.severity ?? "error";
+    const onlyFile = resolve(root, rule.only);
+    const inFiles = rule.in
+      ? resolveLayerFiles(rule.in, layers, root, allFiles)
+      : allFiles;
+    const scope = inFiles.filter((f) => f !== onlyFile);
+
+    for (const file of scope) {
+      const content = fileContents.get(file);
+      if (!content) continue;
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes(rule.pattern)) {
+          violations.push({
+            file: relative(root, file).replaceAll("\\", "/"),
+            line: i + 1,
+            message: rule.message,
+            rule: "arch/singleton",
+            severity,
+          });
+        }
+      }
+    }
+  }
+
+  return violations;
+}

package/core/ast.ts

@@ -0,0 +1,63 @@
+import ts from "typescript";
+
+let _program: { key: string; program: ts.Program } | undefined;
+let _sourceFiles: Map<string, ts.SourceFile> = new Map();
+
+export function clearAstCache(): void {
+  _program = undefined;
+  _sourceFiles = new Map();
+}
+
+export function createProgram(files: string[], root: string): ts.Program {
+  const key = `${root}\0${[...files].sort().join("\0")}`;
+  if (_program?.key === key) return _program.program;
+  const configPath = ts.findConfigFile(root, ts.sys.fileExists);
+  let options: ts.CompilerOptions = { target: ts.ScriptTarget.Latest, strict: true };
+  if (configPath) {
+    const { config } = ts.readConfigFile(configPath, ts.sys.readFile);
+    options = ts.parseJsonConfigFileContent(config, ts.sys, root).options;
+  }
+  const program = ts.createProgram(files, options);
+  _program = { key, program };
+  return program;
+}
+
+export function nearestFunctionIsAsync(node: ts.Node): boolean {
+  let cur: ts.Node | undefined = node.parent;
+  while (cur) {
+    if (
+      ts.isFunctionDeclaration(cur) ||
+      ts.isFunctionExpression(cur) ||
+      ts.isArrowFunction(cur)
+    ) {
+      return cur.modifiers?.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword) ?? false;
+    }
+    cur = cur.parent;
+  }
+  return false;
+}
+
+export function isInsideTry(node: ts.Node): boolean {
+  let cur: ts.Node | undefined = node.parent;
+  while (cur) {
+    if (ts.isTryStatement(cur)) return true;
+    cur = cur.parent;
+  }
+  return false;
+}
+
+export function walkAst(
+  filePath: string,
+  content: string,
+  visitor: (node: ts.Node, src: ts.SourceFile) => void
+): void {
+  const cached = _sourceFiles.get(filePath);
+  const src =
+    cached ?? ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+  if (!cached) _sourceFiles.set(filePath, src);
+  function recurse(node: ts.Node): void {
+    visitor(node, src);
+    ts.forEachChild(node, recurse);
+  }
+  recurse(src);
+}

package/core/config.schema.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { BUILT_IN_PLUGINS } from "../plugins/index";
+import { BUILT_IN_RULES } from "../rules/index";
+
+const builtInRuleNames = Object.keys(BUILT_IN_RULES) as [string, ...string[]];
+const builtInPluginNames = Object.keys(BUILT_IN_PLUGINS) as [string, ...string[]];
+const pluginRuleNames = [
+  ...new Set(Object.values(BUILT_IN_PLUGINS).flatMap((p) => Object.keys(p.rules))),
+] as [string, ...string[]];
+const allKnownRuleNames = [...new Set([...builtInRuleNames, ...pluginRuleNames])] as [
+  string,
+  ...string[],
+];
+
+const SeveritySchema = z
+  .enum(["error", "warn", "off"])
+  .describe(
+    'Rule severity. "error" exits with code 2; "warn" reports but exits 0; "off" silences.'
+  );
+
+const RuleNameSchema = z
+  .union([z.enum(allKnownRuleNames), z.string()])
+  .describe(
+    "Built-in or plugin rule name (with autocomplete) or a custom rule name defined in klint.rules.ts."
+  );
+
+const RuleOptionsSchema = z
+  .object({
+    severity: SeveritySchema.optional(),
+    include: z
+      .array(z.string())
+      .optional()
+      .describe(
+        'Glob patterns scoping this rule to a subset of files. Prefix with ! to exclude. Example: ["src/hooks/**", "!src/hooks/scripts/**"]'
+      ),
+  })
+  .strict()
+  .describe(
+    'Rule options object. Omit severity to default to "error". Add include to scope the rule to specific files.'
+  );
+
+export const KlintConfigSchema = z
+  .object({
+    $schema: z
+      .string()
+      .optional()
+      .describe(
+        "JSON Schema reference. Use ./klint.schema.json for local validation or https://klint.dev/schema.json for the published schema."
+      ),
+    root: z
+      .string()
+      .optional()
+      .describe(
+        "Root directory used to resolve include paths and report relative file names. Defaults to the directory containing klint.config.json."
+      ),
+    include: z
+      .array(z.string())
+      .optional()
+      .describe(
+        'Glob patterns selecting which TypeScript files to lint. Prefix with ! to exclude. Defaults to ["."] which lints all .ts files under root. Example: ["src", "klint", "!**/node_modules/**"]'
+      ),
+    plugins: z
+      .array(z.enum(builtInPluginNames))
+      .optional()
+      .describe(
+        'Named rule bundles to enable. Each plugin applies a default set of rules at "error" severity. Individual rules from the bundle can be overridden or silenced via the rules map. Available: "sonar".'
+      ),
+    rules: z
+      .record(RuleNameSchema, z.union([SeveritySchema, RuleOptionsSchema]))
+      .optional()
+      .describe(
+        'Map of rule name → severity or options. Example: { "no-floating-promise": "error", "no-sync-in-async": { "severity": "warn", "include": ["src/hooks/**"] } }. Run `klint --help` for the full rule list.'
+      ),
+    arch: z
+      .unknown()
+      .optional()
+      .describe(
+        "Architecture as Code constraints — layers, import boundaries, forbidden patterns, singleton locations. Parsed by the arch engine (Phase 2)."
+      ),
+  })
+  .strict()
+  .describe(
+    "klint configuration. Lives at klint.yaml (or klint.config.json) next to biome.json and knip.json."
+  );
+
+/** @lintignore */
+export type KlintConfigFile = z.infer<typeof KlintConfigSchema>;

package/core/fixer.ts

@@ -0,0 +1,44 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Violation } from "./types";
+
+/**
+ * Applies all fixable violations to their source files.
+ * Fixes are applied bottom-to-top within each file to preserve line offsets.
+ * Returns the number of fixes applied.
+ */
+export function applyFixes(violations: Violation[], root: string): number {
+  const byFile = new Map<string, Violation[]>();
+  for (const v of violations) {
+    if (!v.fix) continue;
+    const abs = resolve(root, v.file);
+    const existing = byFile.get(abs) ?? [];
+    existing.push(v);
+    byFile.set(abs, existing);
+  }
+
+  let applied = 0;
+  for (const [absPath, fileViolations] of byFile) {
+    const lines = readFileSync(absPath, "utf-8").split("\n");
+    // Sort by endLine descending so the largest-range fix at any position wins.
+    // This handles bottom-to-top ordering (higher lines first) AND ensures outer
+    // fixes beat inner/overlapping fixes when chained calls share a start position.
+    const sorted = [...fileViolations].sort(
+      (a, b) => (b.fix?.endLine ?? 0) - (a.fix?.endLine ?? 0)
+    );
+
+    const used: Array<{ start: number; end: number }> = [];
+    for (const v of sorted) {
+      if (!v.fix) continue;
+      const { startLine, endLine, replacement } = v.fix;
+      if (used.some((r) => startLine <= r.end && endLine >= r.start)) continue;
+      lines.splice(startLine - 1, endLine - startLine + 1, ...replacement.split("\n"));
+      used.push({ start: startLine, end: endLine });
+      applied++;
+    }
+
+    writeFileSync(absPath, lines.join("\n"), "utf-8");
+  }
+
+  return applied;
+}

package/core/runner.ts

@@ -0,0 +1,119 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { BUILT_IN_PLUGINS } from "../plugins/index";
+import { BUILT_IN_RULES } from "../rules/index";
+import { runArchRules } from "./arch";
+import { clearAstCache } from "./ast";
+import type {
+  KlintConfig,
+  KlintRule,
+  RuleConfigValue,
+  Severity,
+  Violation,
+} from "./types";
+
+function walk(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === "node_modules") continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walk(full));
+    else if (entry.name.endsWith(".ts")) out.push(full.replaceAll("\\", "/"));
+  }
+  return out;
+}
+
+function resolveFiles(include: string[], root: string): string[] {
+  const files = new Set<string>();
+  for (const pattern of include) {
+    const dir = resolve(root, pattern.split("/**")[0].split("/*")[0]);
+    try {
+      for (const file of walk(dir)) files.add(file);
+    } catch {
+      // directory doesn't exist — skip
+    }
+  }
+  return [...files];
+}
+
+function matchPattern(relPath: string, pattern: string): boolean {
+  const norm = relPath.replaceAll("\\", "/");
+  const p = pattern.replaceAll("\\", "/");
+  if (p.endsWith("/**")) return norm.startsWith(`${p.slice(0, -3)}/`);
+  if (p.startsWith("**/")) return norm.endsWith(p.slice(2));
+  return norm === p || norm.startsWith(`${p}/`);
+}
+
+function applyPatterns(files: string[], patterns: string[], root: string): string[] {
+  const includes = patterns.filter((p) => !p.startsWith("!"));
+  const excludes = patterns.filter((p) => p.startsWith("!")).map((p) => p.slice(1));
+  return files.filter((file) => {
+    const rel = relative(root, file).replaceAll("\\", "/");
+    const included = includes.length === 0 || includes.some((p) => matchPattern(rel, p));
+    const excluded = excludes.some((p) => matchPattern(rel, p));
+    return included && !excluded;
+  });
+}
+
+function resolveSeverity(value: RuleConfigValue): Severity {
+  return typeof value === "string" ? value : (value.severity ?? "error");
+}
+
+function resolveInclude(value: RuleConfigValue): string[] | undefined {
+  return typeof value === "object" ? value.include : undefined;
+}
+
+export function runKlint(
+  config: KlintConfig,
+  customRules: Record<string, KlintRule> = {}
+): Violation[] {
+  clearAstCache();
+
+  // All plugin implementations are always available by their prefixed names
+  const pluginImpls: Record<string, KlintRule> = Object.assign(
+    {},
+    ...Object.values(BUILT_IN_PLUGINS).map((p) => p.implementations)
+  );
+  const registry: Record<string, KlintRule> = {
+    ...BUILT_IN_RULES,
+    ...pluginImpls,
+    ...customRules,
+  };
+
+  // Plugin defaults applied first; explicit rules take precedence
+  const pluginDefaults: Record<string, RuleConfigValue> = {};
+  for (const pluginName of config.plugins ?? []) {
+    const plugin = BUILT_IN_PLUGINS[pluginName];
+    if (!plugin) throw new Error(`Unknown klint plugin: "${pluginName}"`);
+    Object.assign(pluginDefaults, plugin.rules);
+  }
+  const effectiveRules: Record<string, RuleConfigValue> = {
+    ...pluginDefaults,
+    ...config.rules,
+  };
+
+  const allFiles = resolveFiles(config.include, config.root);
+  const fileContents = new Map(allFiles.map((f) => [f, readFileSync(f, "utf-8")]));
+  const violations: Violation[] = [];
+
+  for (const [ruleName, configValue] of Object.entries(effectiveRules)) {
+    const severity = resolveSeverity(configValue);
+    if (severity === "off") continue;
+
+    const rule = registry[ruleName];
+    if (!rule) throw new Error(`Unknown klint rule: "${ruleName}"`);
+
+    const include = resolveInclude(configValue);
+    const files = include ? applyPatterns(allFiles, include, config.root) : allFiles;
+
+    const batch: Omit<Violation, "severity">[] = [];
+    rule.check({ files, root: config.root, fileContents }, batch);
+    for (const v of batch) violations.push({ ...v, rule: ruleName, severity });
+  }
+
+  if (config.arch) {
+    violations.push(...runArchRules(config.arch, allFiles, fileContents, config.root));
+  }
+
+  return violations;
+}

package/core/types.ts

@@ -0,0 +1,92 @@
+interface ViolationFix {
+  startLine: number;
+  endLine: number;
+  replacement: string;
+}
+
+export type Severity = "error" | "warn" | "off";
+
+/** @lintignore */
+export interface RuleOptions {
+  severity?: Severity;
+  include?: string[];
+}
+
+export type RuleConfigValue = Severity | RuleOptions;
+
+export interface Violation {
+  file: string;
+  line: number;
+  rule: string;
+  message: string;
+  severity: Severity;
+  fix?: ViolationFix;
+}
+
+/** @lintignore */
+export interface RuleContext {
+  files: string[];
+  root: string;
+  fileContents: Map<string, string>;
+}
+
+/** Violation as emitted by a rule — rule name and severity are stamped by the runner. */
+export type RawViolation = Omit<Violation, "rule" | "severity">;
+
+export interface KlintRule {
+  check: (ctx: RuleContext, violations: RawViolation[]) => void;
+}
+
+/** A named bundle of rules with their default severities and implementations. */
+export interface KlintPlugin {
+  name: string;
+  /** Default severity for each rule. Keys use the prefixed form e.g. "sonar/rule-name". */
+  rules: Record<string, RuleConfigValue>;
+  /** Rule implementations keyed by the same prefixed names. */
+  implementations: Record<string, KlintRule>;
+}
+
+interface ArchImportRule {
+  from: string | string[];
+  deny?: string | string[];
+  allow?: string | string[];
+  "type-only"?: "allow";
+  message?: string;
+  severity?: Exclude<Severity, "off">;
+}
+
+interface ArchForbiddenRule {
+  pattern: string;
+  in: string | string[];
+  message: string;
+  severity?: Exclude<Severity, "off">;
+}
+
+interface ArchSingletonRule {
+  pattern: string;
+  only: string;
+  message: string;
+  /** Limit scan to these files/layers. Defaults to all files. */
+  in?: string | string[];
+  severity?: Exclude<Severity, "off">;
+}
+
+export interface ArchConfig {
+  layers?: Record<string, string[]>;
+  imports?: ArchImportRule[];
+  forbidden?: ArchForbiddenRule[];
+  singleton?: ArchSingletonRule[];
+}
+
+export interface KlintConfig {
+  root: string;
+  include: string[];
+  plugins?: string[];
+  rules: Record<string, RuleConfigValue>;
+  arch?: ArchConfig;
+}
+
+export const defineRule = (r: KlintRule): KlintRule => r;
+
+/** @lintignore */
+export const defineConfig = (c: KlintConfig): KlintConfig => c;