@konvert7/klint 0.37.1 → 1.0.0

package/core/runner.ts

@@ -1,196 +0,0 @@
-import { readdirSync, readFileSync } from "node:fs";
-import { join, 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 { relativeSlashPath, toSlashPath } from "./paths";
-import type {
-  KlintConfig,
-  KlintRule,
-  RuleConfigValue,
-  Severity,
-  Violation,
-} from "./types";
-
-export type KlintDebugEvent =
-  | { type: "walk:start"; dir: string }
-  | { type: "walk:done"; dir: string; files: number }
-  | { type: "files:resolved"; files: number }
-  | { type: "rule:start"; rule: string; files: number }
-  | { type: "rule:done"; rule: string; violations: number }
-  | { type: "arch:start"; files: number }
-  | { type: "arch:done"; violations: number };
-
-export interface RunKlintOptions {
-  onDebug?: (event: KlintDebugEvent) => void;
-}
-
-function walk(dir: string, root: string, excludes: string[] = []): string[] {
-  const out: string[] = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name);
-    const rel = relativeSlashPath(root, full);
-    if (entry.isDirectory()) {
-      if (
-        excludes.some(
-          (pattern) => matchPattern(rel, pattern) || matchPattern(`${rel}/`, pattern)
-        )
-      )
-        continue;
-      out.push(...walk(full, root, excludes));
-    } else if (/\.(tsx?|jsx?|mts|cts)$/.test(entry.name)) out.push(toSlashPath(full));
-  }
-  return out;
-}
-
-function resolveFiles(
-  include: string[],
-  root: string,
-  onDebug?: (event: KlintDebugEvent) => void
-): string[] {
-  const files = new Set<string>();
-  const excludes = include.filter((p) => p.startsWith("!")).map((p) => p.slice(1));
-  for (const pattern of include) {
-    if (pattern.startsWith("!")) continue;
-    const base = pattern.split("/**")[0].split("/*")[0];
-    const dir = resolve(root, base === "**" ? "." : base);
-    try {
-      onDebug?.({ type: "walk:start", dir });
-      const before = files.size;
-      for (const file of walk(dir, root, excludes)) files.add(file);
-      onDebug?.({ type: "walk:done", dir, files: files.size - before });
-    } catch {
-      // directory doesn't exist — skip
-    }
-  }
-  return [...files].sort(byLexicographicOrder);
-}
-
-// Not localeCompare — must match the Rust engine's locale-independent Vec<PathBuf>::sort().
-function byLexicographicOrder(a: string, b: string): number {
-  if (a < b) return -1;
-  if (a > b) return 1;
-  return 0;
-}
-
-function matchPattern(relPath: string, pattern: string): boolean {
-  const norm = toSlashPath(relPath);
-  const p = toSlashPath(pattern);
-  if (p === "." || p === "**") return true;
-  if (!p.includes("*")) return norm === p || norm.startsWith(`${p}/`);
-  return globToRegExp(p).test(norm);
-}
-
-function globToRegExp(pattern: string): RegExp {
-  let source = "";
-  for (let i = 0; i < pattern.length; i++) {
-    const char = pattern[i];
-    const next = pattern[i + 1];
-
-    if (char === "*" && next === "*") {
-      const after = pattern[i + 2];
-      if (after === "/") {
-        source += "(?:.*/)?";
-        i += 2;
-      } else {
-        source += ".*";
-        i++;
-      }
-      continue;
-    }
-
-    if (char === "*") {
-      source += "[^/]*";
-      continue;
-    }
-
-    source += /[.+?^${}()|[\]\\]/.test(char) ? `\\${char}` : char;
-  }
-  return new RegExp(`^${source}$`);
-}
-
-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 = relativeSlashPath(root, file);
-    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> = {},
-  options: RunKlintOptions = {}
-): 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 = applyPatterns(
-    resolveFiles(config.include, config.root, options.onDebug),
-    config.include,
-    config.root
-  );
-  options.onDebug?.({ type: "files:resolved", files: allFiles.length });
-  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">[] = [];
-    options.onDebug?.({ type: "rule:start", rule: ruleName, files: files.length });
-    rule.check({ files, root: config.root, fileContents }, batch);
-    options.onDebug?.({ type: "rule:done", rule: ruleName, violations: batch.length });
-    for (const v of batch) violations.push({ ...v, rule: ruleName, severity });
-  }
-
-  if (config.arch) {
-    options.onDebug?.({ type: "arch:start", files: allFiles.length });
-    const archViolations = runArchRules(config.arch, allFiles, fileContents, config.root);
-    options.onDebug?.({ type: "arch:done", violations: archViolations.length });
-    violations.push(...archViolations);
-  }
-
-  return violations;
-}

package/core/schema-version.ts

@@ -1,46 +0,0 @@
-import type { Violation } from "./types";
-
-const SCHEMA_VERSION_RULE = "klint/schema-version";
-
-const TAGGED_SCHEMA_URL = /\/refs\/tags\/v(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)\//;
-const UNRELEASED = "0.0.0";
-
-export function schemaUrlForVersion(version: string): string {
-  return `https://raw.githubusercontent.com/konvert7/klint/refs/tags/v${version}/klint.schema.json`;
-}
-
-export function declaredSchemaVersion(schema: string | undefined): string | undefined {
-  return schema?.match(TAGGED_SCHEMA_URL)?.[1];
-}
-
-export function schemaVersionAdvisory({
-  schema,
-  installed,
-  configFile,
-  configText,
-}: {
-  schema: string | undefined;
-  installed: string;
-  configFile: string;
-  configText: string;
-}): Array<Omit<Violation, "fix">> {
-  const declared = declaredSchemaVersion(schema);
-  if (declared === undefined || declared === installed || installed === UNRELEASED) {
-    return [];
-  }
-
-  return [
-    {
-      file: configFile,
-      line: schemaDeclarationLine(configText),
-      rule: SCHEMA_VERSION_RULE,
-      severity: "warn",
-      message: `config declares schema v${declared} but klint ${installed} is installed — update $schema to ${schemaUrlForVersion(installed)}`,
-    },
-  ];
-}
-
-function schemaDeclarationLine(configText: string): number {
-  const index = configText.split("\n").findIndex((line) => line.includes("$schema"));
-  return index === -1 ? 1 : index + 1;
-}

package/core/skill.ts

@@ -1,164 +0,0 @@
-import { createHash } from "node:crypto";
-import { lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
-import { join } from "node:path";
-import type { Violation } from "./types";
-
-export const AGENT_SKILL_DIRS = {
-  claude: ".claude/skills",
-  codex: ".agents/skills",
-  copilot: ".agents/skills",
-  cursor: ".cursor/skills",
-  opencode: ".agents/skills",
-} as const;
-
-export type AgentKey = keyof typeof AGENT_SKILL_DIRS;
-
-export const CANONICAL_SKILL_DIR = ".agents/skills";
-export const SKILL_DIR_NAME = "klint-rules";
-export const SKILL_FILE_NAME = "SKILL.md";
-export const RECEIPT_FILE_NAME = ".klint-skill.json";
-
-const STALE_RULE = "klint/skill-stale";
-const LEGACY_RULE = "klint/skill-legacy-link";
-const LEGACY_TARGET = "node_modules";
-
-export interface SkillReceipt {
-  version: string;
-  sha256: string;
-}
-
-export function skillHash(contents: Buffer | string): string {
-  return createHash("sha256").update(contents).digest("hex");
-}
-
-export function agentSkillDirs(agents?: readonly AgentKey[]): string[] {
-  const selected = (agents ?? (Object.keys(AGENT_SKILL_DIRS) as AgentKey[])).map(
-    (agent) => AGENT_SKILL_DIRS[agent]
-  );
-  return [...new Set(selected)];
-}
-
-export function skillAdvisories({
-  configDir,
-  installed,
-  shippedSkillPath,
-}: {
-  configDir: string;
-  installed: string;
-  shippedSkillPath: string;
-}): Array<Omit<Violation, "fix">> {
-  return [
-    ...legacyLinkAdvisories(configDir),
-    ...stalenessAdvisories({ configDir, installed, shippedSkillPath }),
-  ];
-}
-
-function legacyLinkAdvisories(configDir: string): Array<Omit<Violation, "fix">> {
-  return agentSkillDirs().flatMap((dir) => {
-    const target = symlinkTarget(join(configDir, dir, SKILL_DIR_NAME));
-    if (target === undefined || !target.includes(LEGACY_TARGET)) return [];
-    return [
-      {
-        file: `${dir}/${SKILL_DIR_NAME}`,
-        line: 1,
-        rule: LEGACY_RULE,
-        severity: "warn",
-        message: `this skill is a symlink into ${LEGACY_TARGET} (${target}), which breaks as soon as dependencies are reinstalled — run: klint install-skill`,
-      },
-    ];
-  });
-}
-
-function stalenessAdvisories({
-  configDir,
-  installed,
-  shippedSkillPath,
-}: {
-  configDir: string;
-  installed: string;
-  shippedSkillPath: string;
-}): Array<Omit<Violation, "fix">> {
-  const shipped = readShippedHash(shippedSkillPath);
-  if (shipped === undefined) return [];
-
-  const reported = new Set<string>();
-  return realSkillDirsFirst(configDir).flatMap((dir) => {
-    const skillDir = join(configDir, dir, SKILL_DIR_NAME);
-    const canonical = resolveSkillDir(skillDir);
-    if (canonical === undefined || reported.has(canonical)) return [];
-
-    const receipt = readReceipt(join(skillDir, RECEIPT_FILE_NAME));
-    if (receipt === undefined || receipt.sha256 === shipped) return [];
-
-    reported.add(canonical);
-    return [staleAdvisory(dir, receipt.version, installed)];
-  });
-}
-
-function staleAdvisory(
-  dir: string,
-  installedFrom: string,
-  installed: string
-): Omit<Violation, "fix"> {
-  return {
-    file: `${dir}/${SKILL_DIR_NAME}/${SKILL_FILE_NAME}`,
-    line: 1,
-    rule: STALE_RULE,
-    severity: "warn",
-    message: `this klint-rules skill was installed from klint ${installedFrom} and no longer matches klint ${installed} — reinstall it with: klint install-skill`,
-  };
-}
-
-function realSkillDirsFirst(configDir: string): string[] {
-  const dirs = agentSkillDirs();
-  const linked = new Set(
-    dirs.filter(
-      (dir) => symlinkTarget(join(configDir, dir, SKILL_DIR_NAME)) !== undefined
-    )
-  );
-  return [...dirs.filter((dir) => !linked.has(dir)), ...linked];
-}
-
-function symlinkTarget(path: string): string | undefined {
-  try {
-    if (!lstatSync(path).isSymbolicLink()) return undefined;
-    return readlinkSync(path);
-  } catch {
-    return undefined;
-  }
-}
-
-function resolveSkillDir(path: string): string | undefined {
-  try {
-    return realpathSync(path);
-  } catch {
-    return undefined;
-  }
-}
-
-function readShippedHash(shippedSkillPath: string): string | undefined {
-  try {
-    return skillHash(readFileSync(shippedSkillPath));
-  } catch {
-    return undefined;
-  }
-}
-
-function readReceipt(path: string): SkillReceipt | undefined {
-  let text: string;
-  try {
-    text = readFileSync(path, "utf-8");
-  } catch {
-    return undefined;
-  }
-
-  try {
-    const parsed = JSON.parse(text) as Partial<SkillReceipt>;
-    if (typeof parsed.version !== "string" || typeof parsed.sha256 !== "string") {
-      return undefined;
-    }
-    return { version: parsed.version, sha256: parsed.sha256 };
-  } catch {
-    return undefined;
-  }
-}

package/core/stats.ts

@@ -1,160 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import type { Violation } from "./types";
-
-export const STATS_DIR = ".klint";
-export const STATS_FILE = "stats.json";
-const SELF_IGNORE = "# Created by klint automatically.\n*\n";
-const STATS_VERSION = 1;
-const KLINT_ADVISORY_PREFIX = "klint/";
-
-export type RunSource = "hook" | "direct";
-
-type CountedViolation = Pick<Violation, "file" | "rule" | "message" | "severity">;
-
-export type RunRecorder = (violations: readonly CountedViolation[]) => void;
-
-interface OpenError {
-  rule: string;
-  file: string;
-  message: string;
-  caughtBy: RunSource;
-}
-
-export interface KlintStats {
-  version: typeof STATS_VERSION;
-  runs: Record<RunSource, number>;
-  reported: RuleCounts;
-  prevented: RuleCounts;
-  open: OpenError[];
-}
-
-interface RuleCounts {
-  byRule: Record<string, number>;
-  bySource: Record<RunSource, number>;
-}
-
-function emptyCounts(): RuleCounts {
-  return { byRule: {}, bySource: { hook: 0, direct: 0 } };
-}
-
-function bump(counts: RuleCounts, rule: string, source: RunSource): void {
-  counts.byRule[rule] = (counts.byRule[rule] ?? 0) + 1;
-  counts.bySource[source] += 1;
-}
-
-export function emptyStats(): KlintStats {
-  return {
-    version: STATS_VERSION,
-    runs: { hook: 0, direct: 0 },
-    reported: emptyCounts(),
-    prevented: emptyCounts(),
-    open: [],
-  };
-}
-
-function sameError(a: Omit<OpenError, "caughtBy">, b: Omit<OpenError, "caughtBy">) {
-  return a.rule === b.rule && a.file === b.file && a.message === b.message;
-}
-
-function isCodeViolation(violation: CountedViolation): boolean {
-  return !violation.rule.startsWith(KLINT_ADVISORY_PREFIX);
-}
-
-function errorsOf(
-  violations: readonly CountedViolation[]
-): Omit<OpenError, "caughtBy">[] {
-  return violations
-    .filter((v) => v.severity === "error")
-    .map(({ rule, file, message }) => ({ rule, file, message }));
-}
-
-export function nextStats(
-  previous: KlintStats,
-  violations: readonly CountedViolation[],
-  source: RunSource
-): KlintStats {
-  const stats = structuredClone(previous);
-  stats.runs[source] += 1;
-  for (const violation of violations.filter(isCodeViolation)) {
-    bump(stats.reported, violation.rule, source);
-  }
-
-  const unmatched = errorsOf(violations);
-  const stillOpen: OpenError[] = [];
-  for (const error of previous.open) {
-    const match = unmatched.findIndex((current) => sameError(current, error));
-    if (match === -1) {
-      bump(stats.prevented, error.rule, error.caughtBy);
-      continue;
-    }
-    unmatched.splice(match, 1);
-    stillOpen.push(error);
-  }
-  stats.open = [
-    ...stillOpen,
-    ...unmatched.map((error) => ({ ...error, caughtBy: source })),
-  ];
-  return stats;
-}
-
-function isRuleCounts(value: unknown): value is RuleCounts {
-  const candidate = value as Partial<RuleCounts> | undefined;
-  return (
-    typeof candidate?.byRule === "object" &&
-    typeof candidate.bySource?.hook === "number" &&
-    typeof candidate.bySource.direct === "number"
-  );
-}
-
-function isStats(value: unknown): value is KlintStats {
-  if (!value || typeof value !== "object") return false;
-  const candidate = value as Partial<KlintStats>;
-  return (
-    candidate.version === STATS_VERSION &&
-    typeof candidate.runs?.hook === "number" &&
-    typeof candidate.runs.direct === "number" &&
-    isRuleCounts(candidate.prevented) &&
-    (candidate.reported === undefined || isRuleCounts(candidate.reported)) &&
-    Array.isArray(candidate.open)
-  );
-}
-
-function withReportedCounts(stats: KlintStats): KlintStats {
-  return { ...stats, reported: stats.reported ?? emptyCounts() };
-}
-
-export function readStats(configDir: string): KlintStats {
-  try {
-    const parsed: unknown = JSON.parse(
-      readFileSync(join(configDir, STATS_DIR, STATS_FILE), "utf-8")
-    );
-    return isStats(parsed) ? withReportedCounts(parsed) : emptyStats();
-  } catch {
-    return emptyStats();
-  }
-}
-
-function writeStats(configDir: string, stats: KlintStats): void {
-  const dir = join(configDir, STATS_DIR);
-  mkdirSync(dir, { recursive: true });
-  const ignoreFile = join(dir, ".gitignore");
-  if (!existsSync(ignoreFile)) writeFileSync(ignoreFile, SELF_IGNORE);
-  const target = join(dir, STATS_FILE);
-  const staging = `${target}.${process.pid}.tmp`;
-  writeFileSync(staging, `${JSON.stringify(stats, null, 2)}\n`);
-  renameSync(staging, target);
-}
-
-function statsDisabled(): boolean {
-  return Boolean(process.env.KLINT_NO_STATS);
-}
-
-export function runRecorder(configDir: string, source: RunSource): RunRecorder {
-  return (violations) => {
-    if (statsDisabled()) return;
-    try {
-      writeStats(configDir, nextStats(readStats(configDir), violations, source));
-    } catch {}
-  };
-}

package/core/types.ts

@@ -1,146 +0,0 @@
-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 RuleMeta {
-  /** One- or two-line description of what the rule catches. */
-  description: string;
-  /** Concrete YAML config snippets showing usage. Rendered as code blocks in docs. */
-  examples?: string[];
-}
-
-export interface KlintRule {
-  check: (ctx: RuleContext, violations: RawViolation[]) => void;
-  meta?: RuleMeta;
-}
-
-/** 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[];
-  "deny-packages"?: string | string[];
-  "type-only"?: "allow";
-  message?: string;
-  severity?: Exclude<Severity, "off">;
-}
-
-interface ArchForbiddenRuleBase {
-  in: string | string[];
-  message: string;
-  severity?: Exclude<Severity, "off">;
-}
-
-interface ArchForbiddenPatternRule extends ArchForbiddenRuleBase {
-  pattern: string;
-}
-
-interface ArchForbiddenJsxRule extends ArchForbiddenRuleBase {
-  "jsx-element": string | string[];
-}
-
-type ArchForbiddenRule = ArchForbiddenPatternRule | ArchForbiddenJsxRule;
-
-interface ArchSingletonRuleBase {
-  only: string;
-  message: string;
-  /** Limit scan to these files/layers. Defaults to all files. */
-  in?: string | string[];
-  severity?: Exclude<Severity, "off">;
-}
-
-interface ArchSingletonPatternRule extends ArchSingletonRuleBase {
-  pattern: string;
-}
-
-interface ArchSingletonJsxRule extends ArchSingletonRuleBase {
-  "jsx-element": string | string[];
-}
-
-type ArchSingletonRule = ArchSingletonPatternRule | ArchSingletonJsxRule;
-
-interface ArchMaxLinesRule {
-  limit: number;
-  in: string | string[];
-  message?: string;
-  severity?: Exclude<Severity, "off">;
-}
-
-interface ArchCommentRuleBase {
-  limit: number;
-  in: string | string[];
-  /** Count doc-comments (`/** *​/` JSDoc, Swift `///`, Rust `///` and `//!`) toward the limit. Defaults to false. No effect on Python, whose docstrings are never counted. */
-  countDocComments?: boolean;
-  /** Comment lines matching these patterns count toward neither limit. Literal substring, or `re:` for a regex. */
-  ignore?: string | string[];
-  message?: string;
-  severity?: Exclude<Severity, "off">;
-}
-
-/** Caps the share of a file's physical lines that are non-doc comments. */
-interface ArchMaxCommentDensityRule extends ArchCommentRuleBase {}
-
-/** Caps how many consecutive comment lines may stack into a single block. */
-interface ArchMaxCommentBlockRule extends ArchCommentRuleBase {}
-
-export interface ArchConfig {
-  layers?: Record<string, string[]>;
-  imports?: ArchImportRule[];
-  forbidden?: ArchForbiddenRule[];
-  singleton?: ArchSingletonRule[];
-  maxLines?: ArchMaxLinesRule[];
-  maxCommentDensity?: ArchMaxCommentDensityRule[];
-  maxCommentBlock?: ArchMaxCommentBlockRule[];
-}
-
-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;