feat: add cli implementation

Author: Jhonatanmizu

.changeset/add-cli-entrypoint.md

@@ -0,0 +1,5 @@
+---
+"@snutsjs/core": minor
+---
+
+Add a real CLI entrypoint so the package can be executed with `npx @snutsjs/core watch .`.

README.md

@@ -1,21 +1,21 @@
-# snuts.js-core
+# @snutsjs/core
 
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 
 ## 🎯 Goal
 
-`snuts.js-core` aims to be a robust and extensible static analysis tool designed to identify and report common "smells" or anti-patterns in JavaScript and TypeScript test files. By integrating with your development workflow, it helps maintain high-quality, readable, and effective test suites.
+`@snutsjs/core` aims to be a robust and extensible static analysis tool designed to identify and report common "smells" or anti-patterns in JavaScript and TypeScript test files. By integrating with your development workflow, it helps maintain high-quality, readable, and effective test suites.
 
 ## 📦 Installation
 
 ```bash
-npm install snuts.js-core
+npm install @snutsjs/core
 ```
 
 ## 🚀 Library Usage (Extension-Friendly)
 
 ```ts
-import { DetectorRunner, detectors } from "snuts.js-core";
+import { DetectorRunner, detectors } from "@snutsjs/core";
 
 const detectorInstances = Object.values(detectors).map((DetectorClass) => new DetectorClass());
 const runner = new DetectorRunner(detectorInstances);
@@ -29,11 +29,23 @@ console.log(smells);
 Use the runtime subpath when you want the side-effectful watcher behavior:
 
 ```ts
-import "snuts.js-core/runtime/watch";
+import "@snutsjs/core/runtime/watch";
 ```
 
 The root package import is side-effect free and safe for VS Code extension integration.
 
+## CLI Usage
+
+```bash
+npx @snutsjs/core watch .
+```
+
+You can also point to a specific directory:
+
+```bash
+npx @snutsjs/core watch src
+```
+
 ---
 
 ## 📁 Project Structure
@@ -148,7 +160,7 @@ To run this project, you will need:
     yarn start
     ```
 
-    `snuts.js-core` will automatically watch all files in the current directory and its subdirectories and report findings.
+    `@snutsjs/core` will automatically watch all files in the selected directory and its subdirectories and report findings.
 
 ### 📚 Build and Validate
 

bin/snuts.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import("../dist/bin/cli.js")
+  .then(({ runCli }) => runCli(process.argv.slice(2)))
+  .then((exitCode) => {
+    process.exitCode = exitCode;
+  })
+  .catch((error) => {
+    const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+  });

eslint.config.js

@@ -41,16 +41,20 @@ export default tseslint.config(
       "eslint.config.js",
       "prettier.config.js",
       "vite.config.ts",
-      "dist",
-      "node_modules",
-      "coverage",
-      "bin/",
+      "dist/**",
+      "node_modules/**",
+      "coverage/**",
+      "bin/**",
+      "dumb/**",
     ],
   },
   {
     files: ["**/*.js"], // Apply this configuration to all .js files
     languageOptions: {
       parser: babelParser, // Use the imported babel parser
+      globals: {
+        process: "readonly",
+      },
       parserOptions: {
         requireConfigFile: false, // Allow parsing without a Babel config file
         babelOptions: {

lib/bin/cli-args.ts

@@ -0,0 +1,43 @@
+export type ParsedCommand =
+  | {
+      type: "help";
+    }
+  | {
+      type: "watch";
+      paths: string[];
+    }
+  | {
+      type: "error";
+      message: string;
+    };
+
+export function usageText(): string {
+  return [
+    "Usage:",
+    "  snuts watch [path]",
+    "",
+    "Examples:",
+    "  npx @snutsjs/core watch .",
+    "  npx @snutsjs/core watch src",
+  ].join("\n");
+}
+
+export function parseCliArgs(argv: string[]): ParsedCommand {
+  const [command, ...rest] = argv;
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    return { type: "help" };
+  }
+
+  if (command === "watch") {
+    return {
+      type: "watch",
+      paths: rest.length > 0 ? rest : ["."],
+    };
+  }
+
+  return {
+    type: "error",
+    message: `Unknown command: ${command}`,
+  };
+}

lib/bin/cli.test.ts

@@ -0,0 +1,32 @@
+import { parseCliArgs } from "./cli-args";
+
+describe("parseCliArgs", () => {
+  it("returns help when no arguments are provided", () => {
+    expect(parseCliArgs([])).toEqual({ type: "help" });
+  });
+
+  it("returns help when help flag is provided", () => {
+    expect(parseCliArgs(["--help"])).toEqual({ type: "help" });
+  });
+
+  it("parses watch command with explicit paths", () => {
+    expect(parseCliArgs(["watch", ".", "src"])).toEqual({
+      type: "watch",
+      paths: [".", "src"],
+    });
+  });
+
+  it("defaults watch command to current directory", () => {
+    expect(parseCliArgs(["watch"])).toEqual({
+      type: "watch",
+      paths: ["."],
+    });
+  });
+
+  it("returns an error for unknown commands", () => {
+    expect(parseCliArgs(["scan"])).toEqual({
+      type: "error",
+      message: "Unknown command: scan",
+    });
+  });
+});

lib/bin/cli.ts

@@ -0,0 +1,54 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { parseCliArgs, usageText } from "./cli-args";
+
+import { startWatch } from "@/runtime/watch-runner";
+
+function writeOutput(message: string, target: "stdout" | "stderr"): void {
+  const content = `${message}\n`;
+
+  if (target === "stderr") {
+    process.stderr.write(content);
+    return;
+  }
+
+  process.stdout.write(content);
+}
+
+export async function runCli(argv: string[]): Promise<number> {
+  const parsedCommand = parseCliArgs(argv);
+
+  if (parsedCommand.type === "help") {
+    writeOutput(usageText(), "stdout");
+    return 0;
+  }
+
+  if (parsedCommand.type === "error") {
+    writeOutput(parsedCommand.message, "stderr");
+    writeOutput(usageText(), "stderr");
+    return 1;
+  }
+
+  const resolvedPaths = parsedCommand.paths.map((targetPath) =>
+    path.resolve(process.cwd(), targetPath),
+  );
+
+  await startWatch(resolvedPaths);
+  return 0;
+}
+
+const executedFileUrl = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+
+if (import.meta.url === executedFileUrl) {
+  void runCli(process.argv.slice(2)).then(
+    (exitCode) => {
+      process.exitCode = exitCode;
+    },
+    (error: unknown) => {
+      const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+      process.stderr.write(`${message}\n`);
+      process.exitCode = 1;
+    },
+  );
+}

lib/runtime/watch-runner.ts

@@ -0,0 +1,21 @@
+import type { Detector } from "../core/detector.interface";
+import { Watcher } from "../core/watcher";
+import * as detectorModule from "../detectors";
+
+interface DetectorConstructor {
+  new (): Detector;
+}
+
+export function createDetectorInstances(): Detector[] {
+  const detectorEntries = Object.values(detectorModule) as DetectorConstructor[];
+  return detectorEntries.map((DetectorClass) => new DetectorClass());
+}
+
+export async function startWatch(paths: string[]): Promise<void> {
+  const watcher = new Watcher({
+    paths,
+    detectors: createDetectorInstances(),
+  });
+
+  await watcher.watch();
+}

lib/runtime/watch.ts

@@ -1,17 +1,3 @@
-import type { Detector } from "../core/detector.interface";
-import { Watcher } from "../core/watcher";
-import * as detectorModule from "../detectors";
+import { startWatch } from "./watch-runner";
 
-interface DetectorConstructor {
-  new (): Detector;
-}
-
-const detectorEntries = Object.values(detectorModule) as DetectorConstructor[];
-const detectors = detectorEntries.map((DetectorClass) => new DetectorClass());
-
-const watcher = new Watcher({
-  paths: [process.cwd()],
-  detectors,
-});
-
-void watcher.watch();
+void startWatch([process.cwd()]);

package.json

@@ -6,6 +6,9 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "snuts": "./bin/snuts.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -22,6 +25,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "bin",
     "dist",
     "README.md",
     "LICENSE"
@@ -44,7 +48,7 @@
     "access": "public"
   },
   "scripts": {
-    "start": "tsx lib/runtime/watch.ts",
+    "start": "tsx lib/bin/cli.ts watch .",
     "clean": "rimraf dist",
     "build": "tsup --config tsup.config.ts",
     "typecheck": "tsc --noEmit -p tsconfig.build.json",