catlint 1.0.0

package/eslint.config.ts

@@ -0,0 +1,45 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import json from '@eslint/json';
+import markdown from '@eslint/markdown';
+import css from '@eslint/css';
+import { defineConfig } from 'eslint/config';
+import eslintConfigPrettier from 'eslint-config-prettier/flat';
+
+export default defineConfig([
+	{
+		files: ['**/*.{js,mjs,cjs,ts,mts,cts}'],
+		plugins: { js },
+		extends: ['js/recommended'],
+		languageOptions: { globals: globals.browser },
+	},
+	tseslint.configs.recommended,
+	{
+		files: ['**/*.json'],
+		plugins: { json },
+		language: 'json/json',
+		extends: ['json/recommended'],
+	},
+	{
+		files: ['**/*.jsonc'],
+		plugins: { json },
+		language: 'json/jsonc',
+		extends: ['json/recommended'],
+	},
+	{
+		files: ['**/*.json5'],
+		plugins: { json },
+		language: 'json/json5',
+		extends: ['json/recommended'],
+	},
+	{
+		files: ['**/*.md'],
+		plugins: { markdown },
+		language: 'markdown/gfm',
+		extends: ['markdown/recommended'],
+	},
+	{ files: ['**/*.css'], plugins: { css }, language: 'css/css', extends: ['css/recommended'] },
+	{ ignores: ['**/dist/**', '**/legacy/**', '**/node_modules/**'] },
+	eslintConfigPrettier,
+]);

package/legacy/group/model.ts

@@ -0,0 +1,6 @@
+import type { Rule } from '@rules/$/models/rule/model';
+
+export interface Group {
+	name: string;
+	rules: Rule[];
+}

package/legacy/group/service.ts

@@ -0,0 +1,13 @@
+import type { Rule } from '@rules/$/models/rule/model';
+import type { Group } from './model';
+
+export const createGroup = (
+	name: string,
+	method: (push: (rule: Rule) => void, subgroup: (group: Group) => void) => void,
+): Group => {
+	const rules: Rule[] = [];
+	const push = (rule: Rule) => rules.push(rule);
+	const subgroup = (group: Group) => group.rules.forEach(push);
+	method(push, subgroup);
+	return { name, rules };
+};

package/legacy/index.ts

@@ -0,0 +1,72 @@
+import { lintFile } from "@core/linter";
+import type { LintResult } from "@core/models/lintResult/model";
+import type { IRFile } from "@ir/$/models/File";
+import { IRKind } from "@ir/$/models/Node";
+import { yagniRules } from "@rules/yagni";
+const file: IRFile = {
+	name: "test.ts",
+	extensions: ["ts"],
+	program: [
+		{
+			line: 1,
+			kind: IRKind.Codeline,
+			name: "test",
+			value: [
+				{
+					line: 2,
+					kind: IRKind.Function,
+					name: "test",
+					value: [
+						{
+							line: 3,
+							kind: IRKind.Variable,
+							name: "test",
+							value: [],
+						},
+					],
+				},
+			],
+		},
+		{
+			line: 4,
+			kind: IRKind.Class,
+			name: "test2",
+			value: [],
+		},
+
+		{
+			line: 5,
+			kind: IRKind.Variable,
+			name: "test9",
+			value: [],
+		},
+
+		{
+			line: 6,
+			kind: IRKind.Literal,
+			name: "test",
+			value: [],
+		},
+	],
+};
+
+const rules = [yagniRules]
+
+const lres = lintFile(file, rules);
+
+console.log(JSON.stringify(lres, null, 2));
+
+let indent = 0;
+
+const print = (result: LintResult) => {
+	const char = result.isCorrect ? "✓" : "✗";
+	console.log(`${" ".repeat(indent)}${char} ${result.name}`);
+	indent += 2;
+	result.messages.forEach((message) => {
+		console.log(`${" ".repeat(indent)}[${message.level}] Line ${message.line}: ${message.message}`);
+	});
+	result.subrules.forEach(print);
+	indent -= 2;
+}
+
+lres.forEach(print);

package/legacy/shared/yagni/index.ts

@@ -0,0 +1,4 @@
+import { createRule } from '@rules/models/rule/service';
+import { noUnusedFeatures } from './noUnusedFeatures';
+
+export const yagniRules = createRule('YAGNI', () => [], [noUnusedFeatures]);

package/legacy/shared/yagni/noUnusedFeatures/index.ts

@@ -0,0 +1,4 @@
+export * from './noUnusedClasses';
+export * from './noUnusedFunctions';
+export * from './noUnusedVariables';
+export * from './main';

package/legacy/shared/yagni/noUnusedFeatures/main.ts

@@ -0,0 +1,10 @@
+import { noUnusedClasses } from './noUnusedClasses';
+import { noUnusedFunctions } from './noUnusedFunctions';
+import { noUnusedVariables } from './noUnusedVariables';
+import { createRule } from '@rules/models/rule/service';
+
+export const noUnusedFeatures = createRule('No unused features', () => [], [
+	noUnusedVariables,
+	noUnusedFunctions,
+	noUnusedClasses,
+]);

package/legacy/shared/yagni/noUnusedFeatures/noUnusedClasses.ts

@@ -0,0 +1,26 @@
+import { IRKind } from '@ir/models/Node';
+import { Level, type Message } from '@rules/models/message/model';
+import type { Rule } from '@rules/models/rule/model';
+import { flattenNodes } from '../utils';
+import { createRule } from '@rules/models/rule/service';
+
+export const noUnusedClasses: Rule = createRule('No unused classes', (file) => {
+	const messages: Message[] = [];
+	const allNodes = flattenNodes(file.program);
+	const declaredClasses = allNodes.filter((n) => n.kind === IRKind.Class);
+	const referencedNames = new Set(
+		allNodes.filter((n) => n.kind !== IRKind.Class).map((n) => n.name),
+	);
+
+	for (const cls of declaredClasses) {
+		if (!referencedNames.has(cls.name)) {
+			messages.push({
+				message: `Class '${cls.name}' is declared but never used.`,
+				line: cls.line,
+				level: Level.Error,
+			});
+		}
+	}
+
+	return messages;
+});

package/legacy/shared/yagni/noUnusedFeatures/noUnusedFunctions.ts

@@ -0,0 +1,26 @@
+import { IRKind } from '@ir/models/Node';
+import { Level, type Message } from '@rules/models/message/model';
+import type { Rule } from '@rules/models/rule/model';
+import { flattenNodes } from '../utils';
+import { createRule } from '@rules/models/rule/service';
+
+export const noUnusedFunctions: Rule = createRule('No unused functions', (file) => {
+	const messages: Message[] = [];
+	const allNodes = flattenNodes(file.program);
+	const declaredFunctions = allNodes.filter((n) => n.kind === IRKind.Function);
+	const referencedNames = new Set(
+		allNodes.filter((n) => n.kind !== IRKind.Function).map((n) => n.name),
+	);
+
+	for (const fn of declaredFunctions) {
+		if (!referencedNames.has(fn.name)) {
+			messages.push({
+				message: `Function '${fn.name}' is declared but never called.`,
+				line: fn.line,
+				level: Level.Error,
+			});
+		}
+	}
+
+	return messages;
+});

package/legacy/shared/yagni/noUnusedFeatures/noUnusedVariables.ts

@@ -0,0 +1,26 @@
+import { IRKind } from '@ir/models/Node';
+import { Level, type Message } from '@rules/models/message/model';
+import type { Rule } from '@rules/models/rule/model';
+import { flattenNodes } from '../utils';
+import { createRule } from '@rules/models/rule/service';
+
+export const noUnusedVariables: Rule = createRule('No unused variables', (file) => {
+	const messages: Message[] = [];
+	const allNodes = flattenNodes(file.program);
+	const declaredVariables = allNodes.filter((n) => n.kind === IRKind.Variable);
+	const referencedNames = new Set(
+		allNodes.filter((n) => n.kind !== IRKind.Variable).map((n) => n.name),
+	);
+
+	for (const variable of declaredVariables) {
+		if (!referencedNames.has(variable.name)) {
+			messages.push({
+				message: `Variable '${variable.name}' is declared but never used.`,
+				line: variable.line,
+				level: Level.Error,
+			});
+		}
+	}
+
+	return messages;
+});

package/legacy/shared/yagni/utils.ts

@@ -0,0 +1,5 @@
+import type { IRNode } from '@ir/$/models/Node';
+
+export function flattenNodes(nodes: IRNode[]): IRNode[] {
+	return nodes.flatMap((node) => [node, ...flattenNodes(node.value)]);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "catlint",
+	"module": "src/index.ts",
+	"version": "1.0.0",
+	"type": "module",
+	"scripts": {
+		"lint": "eslint src --ext .ts",
+		"format": "prettier --write src",
+		"check": "bun run lint && bun run format",
+		"test": "vitest",
+		"prepare": "husky"
+	},
+	"engines": {
+		"node": "^5.3.0"
+	},
+	"devDependencies": {
+		"@eslint/css": "^1.0.0",
+		"@eslint/js": "^10.0.1",
+		"@eslint/json": "^1.2.0",
+		"@eslint/markdown": "^8.0.0",
+		"@types/bun": "latest",
+		"@types/node": "^25.5.0",
+		"@typescript-eslint/eslint-plugin": "^8.57.2",
+		"@typescript-eslint/parser": "^8.57.2",
+		"eslint": "^10.1.0",
+		"eslint-config-prettier": "^10.1.8",
+		"globals": "^17.4.0",
+		"husky": "^9.1.7",
+		"prettier": "3.8.1",
+		"typescript-eslint": "^8.57.2",
+		"vitest": "^4.1.1"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"lint-staged": {
+		"*.{ts,js}": [
+			"eslint --fix",
+			"prettier --write"
+		]
+	},
+	"dependencies": {
+		"catlint": ".",
+		"chalk": "^5.6.2",
+		"commander": "^14.0.3",
+		"glob": "^13.0.6",
+		"inquirer": "^13.3.2",
+		"jiti": "^2.6.1",
+		"minimatch": "^10.2.5"
+	}
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,23 @@
+import inquirer from 'inquirer';
+import fs from 'fs';
+import { defaultConfig } from '@config/index';
+import { inspect } from 'util';
+
+export const init = async () => {
+	const { useTypescript } = await inquirer.prompt([
+		{
+			type: 'confirm',
+			name: 'useTypescript',
+			message: 'Do you want to use typescript?',
+			default: true,
+		},
+	]);
+
+	fs.writeFileSync(
+		`catlint.config.${useTypescript ? 'ts' : 'js'}`,
+		`import { defineConfig } from 'catlint/config';
+
+export default defineConfig(${inspect(defaultConfig)});
+`,
+	);
+};

package/src/cli/commands/lint.ts

@@ -0,0 +1,7 @@
+import { defaultConfig, loadConfig } from '@config/index';
+import { lintProject } from '@core/api/lintProject';
+
+export const lint = async () => {
+	const config = (await loadConfig('.')) ?? defaultConfig;
+	lintProject(config, '.');
+};

package/src/cli/index.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { init } from './commands/init';
+import { lint } from './commands/lint';
+
+const program = new Command();
+
+program.name('catlint').description('A linter for detecting code bad practices').version('0.0.1');
+
+program
+	.command('init')
+	.description('Inits CatLint in your current project folder')
+	.action(async () => await init());
+
+program
+	.command('lint')
+	.description('Lints the current project')
+	.action(async () => await lint());
+
+program.parse();

package/src/config/api/defineConfig.ts

@@ -0,0 +1,10 @@
+import type { Config, NormalizedConfig } from '@config/types/config';
+import { defaultAdapter } from '@rules/helpers/defaultAdapter';
+
+export function defineConfig(config: Config): NormalizedConfig {
+	const normalizedConfig: NormalizedConfig = {
+		...config,
+		rules: config.rules.map((rule) => defaultAdapter(rule)),
+	};
+	return normalizedConfig;
+}

package/src/config/api/loadConfig.ts

@@ -0,0 +1,27 @@
+import type { NormalizedConfig } from '@config/types/config';
+import { adaptConfig } from '@config/types/configAdapter';
+import path from 'path';
+import { pathToFileURL } from 'url';
+
+export const loadConfigFromFile = async (filePath: string): Promise<NormalizedConfig | null> => {
+	try {
+		const config = await import(pathToFileURL(filePath).href);
+		return adaptConfig(config.default);
+	} catch {
+		console.log(`No config file found at ${filePath}`);
+		return null;
+	}
+};
+
+export const loadConfig = async (projectPath: string): Promise<NormalizedConfig> => {
+	const configPath = path.join(process.cwd(), projectPath) + '/catlint.config';
+
+	const config =
+		(await loadConfigFromFile(configPath + '.js')) ??
+		(await loadConfigFromFile(configPath + '.ts'));
+	if (!config) {
+		throw new Error('No config file found');
+	}
+
+	return config;
+};

package/src/config/index.ts

@@ -0,0 +1,3 @@
+export * from './types/config';
+export * from './api/defineConfig';
+export * from './api/loadConfig';

package/src/config/types/config.ts

@@ -0,0 +1,27 @@
+import type { IRParser } from '@ir/models/IRParser';
+import type { AdaptedRule, Rule } from '@rules/models/rule/model';
+
+export interface Config {
+	lint: {
+		includes: string[];
+		excludes: string[];
+	};
+	parsers: {
+		pattern: string;
+		parser: IRParser;
+	}[];
+	rules: Rule[];
+}
+
+export interface NormalizedConfig extends Config {
+	rules: AdaptedRule[];
+}
+
+export const defaultConfig: NormalizedConfig = {
+	lint: {
+		includes: ['**/*.ts'],
+		excludes: ['node_modules/**'],
+	},
+	parsers: [],
+	rules: [],
+};

package/src/config/types/configAdapter.ts

@@ -0,0 +1,10 @@
+import { defaultAdapter } from '@rules/helpers/defaultAdapter';
+import type { Config, NormalizedConfig } from './config';
+
+export const adaptConfig: (c: Config) => NormalizedConfig = (config: Config) => {
+	const normalizedConfig: NormalizedConfig = {
+		...config,
+		rules: config.rules.map((rule) => defaultAdapter(rule)),
+	};
+	return normalizedConfig;
+};

package/src/core/api/lintProject.ts

@@ -0,0 +1,20 @@
+import type { NormalizedConfig } from '@config/types/config';
+import { loadFiles } from 'src/shared/pattern/loadFiles';
+import { lintFile } from './linter';
+import type { IRFile } from '@ir/models/File';
+import fs from 'fs';
+import { Minimatch } from 'minimatch';
+
+export const lintProject = async (config: NormalizedConfig, projectDir: string) => {
+	const files = await loadFiles(projectDir, config.lint.includes, config.lint.excludes);
+	return files
+		.map((filePath: string) => {
+			const fileContent = fs.readFileSync(filePath, 'utf-8');
+			const parser = config.parsers.find((parser) =>
+				new Minimatch(parser.pattern).match(filePath),
+			);
+			if (!parser) console.error(`No parser found for file ${filePath}`);
+			return parser?.parser(fileContent, filePath) ?? ({} as IRFile);
+		})
+		.map((file: IRFile) => lintFile(file, config.rules));
+};

package/src/core/api/linter.ts

@@ -0,0 +1,22 @@
+import type { LintResult } from '@core/models/lintResult/model';
+import type { IRFile } from '@ir/models/File';
+import type { AdaptedRule } from '@rules/models/rule/model';
+
+export function travelFile(file: IRFile) {
+	const travelRule: (rule: AdaptedRule) => LintResult = (rule) => {
+		return {
+			name: rule.name,
+			messages: rule.fn(file),
+			subrules: rule.subrules.map(travelRule),
+			isCorrect:
+				rule.fn(file).length === 0 && rule.subrules.every((r) => travelRule(r).isCorrect),
+		};
+	};
+	return travelRule;
+}
+
+export function lintFile(file: IRFile, rules: AdaptedRule[]): LintResult[] {
+	const results: LintResult[] = rules.map((rule) => travelFile(file)(rule));
+
+	return results;
+}

package/src/core/models/lintResult/model.ts

@@ -0,0 +1,8 @@
+import type { Message } from '@rules/models/message/model';
+
+export type LintResult = {
+	name: string;
+	messages: Message[];
+	subrules: LintResult[];
+	isCorrect: boolean;
+};

package/src/ir/models/File.ts

@@ -0,0 +1,7 @@
+import type { IRNode } from './Node';
+
+export interface IRFile {
+	name: string;
+	extensions: string[];
+	program: IRNode[];
+}

package/src/ir/models/IRParser.ts

@@ -0,0 +1,3 @@
+import type { IRFile } from './File';
+
+export type IRParser = (filename: string, content: string) => IRFile;

package/src/ir/models/Node.ts

@@ -0,0 +1,14 @@
+export enum IRKind {
+	Codeline,
+	Literal,
+	Function,
+	Class,
+	Variable,
+}
+
+export interface IRNode {
+	line: number;
+	kind: IRKind;
+	name: string;
+	value: IRNode[];
+}

package/src/rules/helpers/defaultAdapter.ts

@@ -0,0 +1,20 @@
+import type { AdaptedRule, Rule } from '@rules/models/rule/model';
+
+const EMPTY_FN = () => [];
+
+/**
+ * @function defaultAdapter recursively adapts a Rule to an AdaptedRule by providing default values for undefined/null fields.
+ *
+ * @param rule the rule to adapt
+ * @returns a AdaptedRule without undefined/null fields
+ *
+ */
+export const defaultAdapter = (rule: Rule): AdaptedRule => {
+	const { name, fn = EMPTY_FN, subrules = [] } = rule;
+
+	return {
+		name,
+		fn,
+		subrules: subrules.map(defaultAdapter),
+	};
+};

package/src/rules/models/message/model.ts

@@ -0,0 +1,11 @@
+export enum Level {
+	Error = 'ERROR',
+	Warning = 'WARNING',
+	Info = 'INFO',
+}
+
+export interface Message {
+	message: string;
+	line: number;
+	level: Level;
+}

package/src/rules/models/rule/model.ts

@@ -0,0 +1,15 @@
+import type { IRFile } from '@ir/models/File';
+import type { Message } from '@rules/models/message/model';
+
+export type RuleFn = (file: IRFile) => Message[];
+
+export interface Rule {
+	name: string;
+	fn?: RuleFn;
+	subrules?: Rule[];
+}
+
+export interface AdaptedRule extends Rule {
+	fn: RuleFn;
+	subrules: AdaptedRule[];
+}

package/src/rules/models/rule/service.ts

@@ -0,0 +1,14 @@
+import type { Rule, RuleFn } from './model';
+
+export const createRule = (
+	name: string,
+	fn: (subrule: (subrule: Rule) => void) => RuleFn,
+): Rule => {
+	const subrules: Rule[] = [];
+	const ruleFn: RuleFn = fn((subrule: Rule) => subrules.push(subrule));
+	return {
+		name,
+		fn: ruleFn,
+		subrules,
+	};
+};

package/src/shared/pattern/loadFiles.ts

@@ -0,0 +1,17 @@
+import { glob } from 'glob';
+
+export const loadFiles = async (baseDir: string, includes: string[], excludes: string[] = []) => {
+	const included = (
+		await Promise.all(
+			includes.map((pattern) => glob(pattern, { cwd: baseDir, absolute: true })),
+		)
+	).flat();
+
+	const excluded = (
+		await Promise.all(
+			excludes.map((pattern) => glob(pattern, { cwd: baseDir, absolute: true })),
+		)
+	).flat();
+
+	return included.filter((file) => !excluded.includes(file));
+};

package/tests/basic.test.ts

@@ -0,0 +1,8 @@
+import { expect, it, describe } from 'vitest';
+
+// Basic and useless test
+describe('basic', () => {
+	it('should work', () => {
+		expect(true).toBe(true);
+	});
+});

package/tsconfig.json

@@ -0,0 +1,32 @@
+{
+	"compilerOptions": {
+		"baseUrl": ".",
+		"lib": ["ESNext"],
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+
+		"paths": {
+			"@core/*": ["./src/core/*"],
+			"@rules/*": ["./src/rules/*"],
+			"@ir/*": ["./src/ir/*"],
+			"@config/*": ["./src/config/*"]
+		}
+	}
+}

package/vitest.config.ts

@@ -0,0 +1,12 @@
+/// <reference types="vitest" />
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+	test: {
+		globals: true,
+		environment: 'node',
+		coverage: {
+			reporter: ['text', 'lcov'],
+		},
+	},
+});