semlint-cli 0.1.0 → 0.1.2

package/README.md

@@ -21,6 +21,12 @@ pnpm build
 semlint check
 ```
 
+Scaffold a project config with automatic coding agent CLI detection:
+
+```bash
+semlint init
+```
+
 If running from source:
 
 ```bash
@@ -38,6 +44,7 @@ pnpm check
 - `--fail-on <error|warn|never>`: failure threshold (default `error`)
 - `--batch`: run all selected rules in one backend call
 - `--debug`: enable debug logs to stderr
+- `init --force`: overwrite an existing `semlint.json`
 
 Default diff behavior (without `--base`/`--head`) uses your local branch state:
 
@@ -92,9 +99,27 @@ Unknown fields are ignored.
 }
 ```
 
+## Config scaffolding and auto-detection
+
+Run:
+
+```bash
+semlint init
+```
+
+This creates `./semlint.json` and auto-detects installed coding agent CLIs in this priority order:
+
+1. `cursor` -> backend `cursor-cli`
+2. `claude` -> backend `claude-code`
+3. `codex` -> backend `codex-cli`
+
+If no known CLI is detected, Semlint falls back to `cursor-cli` + executable `cursor`.
+
+Use `semlint init --force` to overwrite an existing config file. Init also creates `.semlint/rules/` and a starter rule `SEMLINT_EXAMPLE_001.json` (with a placeholder title and prompt) if they do not exist.
+
 ## Rule files
 
-Rule JSON files are loaded from `rules/`.
+Rule JSON files are loaded from `.semlint/rules/`. Run `semlint init` to create this folder and an example rule you can edit.
 
 Required fields:
 

package/dist/cli.js

@@ -1,7 +1,30 @@
 #!/usr/bin/env node
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const picocolors_1 = __importDefault(require("picocolors"));
+const init_1 = require("./init");
 const main_1 = require("./main");
+const HELP_TEXT = [
+    "Usage:",
+    "  semlint check [--backend <name>] [--model <name>] [--config <path>] [--format <text|json>] [--base <ref>] [--head <ref>] [--fail-on <error|warn|never>] [--batch] [--debug]",
+    "  semlint init [--force]",
+    "  semlint --help",
+    "",
+    "Commands:",
+    "  check   Run semantic lint rules against your git diff",
+    "  init    Create semlint.json, .semlint/rules/, and an example rule to edit",
+    "",
+    "Options:",
+    "  -h, --help   Show this help text"
+].join("\n");
+class HelpRequestedError extends Error {
+    constructor() {
+        super(HELP_TEXT);
+    }
+}
 const FLAGS_WITH_VALUES = new Set([
     "--backend",
     "--model",
@@ -18,9 +41,26 @@ function isFailOn(value) {
     return value === "error" || value === "warn" || value === "never";
 }
 function parseArgs(argv) {
+    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+        throw new HelpRequestedError();
+    }
     const [command, ...rest] = argv;
-    if (!command || command !== "check") {
-        throw new Error("Usage: semlint check [--backend <name>] [--model <name>] [--config <path>] [--format <text|json>] [--base <ref>] [--head <ref>] [--fail-on <error|warn|never>] [--batch] [--debug]");
+    if (!command || (command !== "check" && command !== "init")) {
+        throw new Error(HELP_TEXT);
+    }
+    if (command === "init") {
+        const options = {
+            command: "init",
+            debug: false
+        };
+        for (const token of rest) {
+            if (token === "--force") {
+                options.force = true;
+                continue;
+            }
+            throw new Error(`Unknown flag for init: ${token}`);
+        }
+        return options;
     }
     const options = {
         command: "check",
@@ -81,13 +121,19 @@ function parseArgs(argv) {
 async function main() {
     try {
         const options = parseArgs(process.argv.slice(2));
-        const exitCode = await (0, main_1.runSemlint)(options);
+        const exitCode = options.command === "init" ? (0, init_1.scaffoldConfig)(options.force) : await (0, main_1.runSemlint)(options);
         process.exitCode = exitCode;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        process.stderr.write(`${message}\n`);
-        process.exitCode = 2;
+        if (error instanceof HelpRequestedError) {
+            process.stderr.write(`${message}\n`);
+            process.exitCode = 0;
+        }
+        else {
+            process.stderr.write(picocolors_1.default.red(`Error: ${message}\n`));
+            process.exitCode = 2;
+        }
     }
 }
 void main();

package/dist/filter.js

@@ -131,14 +131,40 @@ function buildScopedDiff(rule, fullDiff, changedFiles) {
 }
 function buildRulePrompt(rule, diff) {
     return [
+        "You are Semlint, an expert semantic code reviewer.",
+        "Analyze ONLY the modified code present in the DIFF below.",
+        "Return JSON only (no markdown, no prose, no code fences).",
+        "Output schema:",
+        "{",
+        "  \"diagnostics\": [",
+        "    {",
+        "      \"rule_id\": string,",
+        "      \"severity\": \"error\" | \"warn\" | \"info\",",
+        "      \"message\": string,",
+        "      \"file\": string,",
+        "      \"line\": number,",
+        "      \"column\"?: number,",
+        "      \"end_line\"?: number,",
+        "      \"end_column\"?: number,",
+        "      \"evidence\"?: string,",
+        "      \"confidence\"?: number",
+        "    }",
+        "  ]",
+        "}",
+        "Rules:",
+        "- If there are no findings, return {\"diagnostics\":[]}.",
+        "- Each diagnostic must reference a changed file from the DIFF.",
+        "- Use the provided RULE_ID exactly in every diagnostic.",
+        "- Keep messages concise and actionable.",
+        "",
         `RULE_ID: ${rule.id}`,
         `RULE_TITLE: ${rule.title}`,
         `SEVERITY_DEFAULT: ${rule.effectiveSeverity}`,
         "",
-        "DIFF:",
-        diff,
-        "",
         "INSTRUCTIONS:",
-        rule.prompt
+        rule.prompt,
+        "",
+        "DIFF:",
+        diff
     ].join("\n");
 }

package/dist/init.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scaffoldConfig = scaffoldConfig;
+const picocolors_1 = __importDefault(require("picocolors"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+function commandExists(command) {
+    const result = (0, node_child_process_1.spawnSync)(command, ["--version"], {
+        stdio: "ignore"
+    });
+    return result.status === 0 || result.status === 1;
+}
+function detectBackend() {
+    const candidates = [
+        {
+            executable: "cursor",
+            backend: "cursor-cli",
+            reason: "detected Cursor CLI"
+        },
+        {
+            executable: "claude",
+            backend: "claude-code",
+            reason: "detected Claude Code CLI"
+        },
+        {
+            executable: "codex",
+            backend: "codex-cli",
+            reason: "detected Codex CLI"
+        }
+    ];
+    for (const candidate of candidates) {
+        if (commandExists(candidate.executable)) {
+            return candidate;
+        }
+    }
+    return {
+        backend: "cursor-cli",
+        executable: "cursor",
+        reason: "no known agent CLI detected, using default Cursor setup"
+    };
+}
+function scaffoldConfig(force = false) {
+    const targetPath = node_path_1.default.join(process.cwd(), "semlint.json");
+    if (node_fs_1.default.existsSync(targetPath) && !force) {
+        process.stderr.write(`Refusing to overwrite existing ${targetPath}. Re-run with "semlint init --force" to replace it.\n`);
+        return 2;
+    }
+    const detected = detectBackend();
+    const scaffold = {
+        backend: detected.backend,
+        model: "auto",
+        budgets: {
+            timeout_ms: 120000
+        },
+        output: {
+            format: "text"
+        },
+        execution: {
+            batch: false
+        },
+        rules: {
+            disable: [],
+            severity_overrides: {}
+        },
+        backends: {
+            [detected.backend]: {
+                executable: detected.executable
+            }
+        }
+    };
+    node_fs_1.default.writeFileSync(targetPath, `${JSON.stringify(scaffold, null, 2)}\n`, "utf8");
+    process.stdout.write(picocolors_1.default.green(`Created ${targetPath}\n`));
+    process.stdout.write(picocolors_1.default.cyan(`Backend setup: ${detected.backend} (${detected.reason})\n`));
+    const rulesDir = node_path_1.default.join(process.cwd(), ".semlint", "rules");
+    if (!node_fs_1.default.existsSync(rulesDir)) {
+        node_fs_1.default.mkdirSync(rulesDir, { recursive: true });
+        process.stdout.write(picocolors_1.default.green(`Created ${node_path_1.default.join(".semlint", "rules")}/\n`));
+    }
+    const exampleRulePath = node_path_1.default.join(rulesDir, "SEMLINT_EXAMPLE_001.json");
+    if (!node_fs_1.default.existsSync(exampleRulePath)) {
+        const exampleRule = {
+            id: "SEMLINT_EXAMPLE_001",
+            title: "My first rule",
+            severity_default: "warn",
+            prompt: "Describe what the agent should check in the changed code. Example: flag when new functions lack JSDoc, or when error handling is missing."
+        };
+        node_fs_1.default.writeFileSync(exampleRulePath, `${JSON.stringify(exampleRule, null, 2)}\n`, "utf8");
+        process.stdout.write(picocolors_1.default.green(`Created ${node_path_1.default.join(".semlint", "rules", "SEMLINT_EXAMPLE_001.json")} `) + picocolors_1.default.dim(`(edit the title and prompt to define your rule)\n`));
+    }
+    return 0;
+}

package/dist/main.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runSemlint = runSemlint;
+const picocolors_1 = __importDefault(require("picocolors"));
+const nanospinner_1 = require("nanospinner");
 const node_path_1 = __importDefault(require("node:path"));
 const backend_1 = require("./backend");
 const config_1 = require("./config");
@@ -15,7 +17,7 @@ const rules_1 = require("./rules");
 const VERSION = "0.1.0";
 function debugLog(enabled, message) {
     if (enabled) {
-        process.stderr.write(`[debug] ${message}\n`);
+        process.stderr.write(`${picocolors_1.default.gray(`[debug] ${message}`)}\n`);
     }
 }
 function timed(enabled, label, action) {
@@ -41,10 +43,33 @@ function buildBatchPrompt(rules, diff) {
     ].join("\n"))
         .join("\n\n---\n\n");
     return [
+        "You are Semlint, an expert semantic code reviewer.",
         "BATCH_MODE: true",
         "Evaluate all rules below against the DIFF in one pass.",
-        "Return valid JSON only with shape {\"diagnostics\":[...]}",
-        "Each diagnostic must include: rule_id, severity, message, file, line.",
+        "Analyze ONLY the modified code present in the DIFF below.",
+        "Return JSON only (no markdown, no prose, no code fences).",
+        "Output schema:",
+        "{",
+        "  \"diagnostics\": [",
+        "    {",
+        "      \"rule_id\": string,",
+        "      \"severity\": \"error\" | \"warn\" | \"info\",",
+        "      \"message\": string,",
+        "      \"file\": string,",
+        "      \"line\": number,",
+        "      \"column\"?: number,",
+        "      \"end_line\"?: number,",
+        "      \"end_column\"?: number,",
+        "      \"evidence\"?: string,",
+        "      \"confidence\"?: number",
+        "    }",
+        "  ]",
+        "}",
+        "Rules:",
+        "- If there are no findings, return {\"diagnostics\":[]}.",
+        "- Each diagnostic must reference a changed file from the DIFF.",
+        "- rule_id must match one of the RULE_ID values listed below.",
+        "- Keep messages concise and actionable.",
         "",
         "RULES:",
         ruleBlocks,
@@ -55,9 +80,10 @@ function buildBatchPrompt(rules, diff) {
 }
 async function runSemlint(options) {
     const startedAt = Date.now();
+    let spinner = null;
     try {
         const config = timed(options.debug, "Loaded effective config", () => (0, config_1.loadEffectiveConfig)(options));
-        const rulesDir = node_path_1.default.join(process.cwd(), "rules");
+        const rulesDir = node_path_1.default.join(process.cwd(), ".semlint", "rules");
         const rules = timed(config.debug, "Loaded and validated rules", () => (0, rules_1.loadRules)(rulesDir, config.rulesDisable, config.severityOverrides));
         debugLog(config.debug, `Loaded ${rules.length} rule(s)`);
         debugLog(config.debug, `Rule IDs: ${rules.map((rule) => rule.id).join(", ")}`);
@@ -82,6 +108,17 @@ async function runSemlint(options) {
         const diagnostics = [];
         const rulesRun = runnableRules.length;
         let backendErrors = 0;
+        if (config.format !== "json" && rulesRun > 0) {
+            process.stdout.write(`${picocolors_1.default.bold("Running rules:")}\n`);
+            for (const rule of runnableRules) {
+                process.stdout.write(`  ${picocolors_1.default.cyan(rule.id)} ${picocolors_1.default.dim(rule.title)}\n`);
+            }
+            process.stdout.write("\n");
+        }
+        spinner =
+            config.format !== "json" && rulesRun > 0
+                ? (0, nanospinner_1.createSpinner)(`Analyzing ${changedFiles.length} file${changedFiles.length === 1 ? "" : "s"} with ${config.backend} in ${config.batchMode ? "batch" : "parallel"} mode...`).start()
+                : null;
         if (config.batchMode && runnableRules.length > 0) {
             debugLog(config.debug, `Running ${runnableRules.length} rule(s) in batch mode`);
             const combinedDiff = timed(config.debug, "Batch: combined scoped diff build", () => runnableRules
@@ -161,12 +198,20 @@ async function runSemlint(options) {
         }
         const sorted = timed(config.debug, "Sorted diagnostics", () => (0, diagnostics_1.sortDiagnostics)(diagnostics));
         const durationMs = Date.now() - startedAt;
+        if (spinner) {
+            if (backendErrors > 0) {
+                spinner.error({ text: "Analysis completed with backend errors" });
+            }
+            else {
+                spinner.success({ text: "Analysis complete" });
+            }
+        }
         const outputStartedAt = Date.now();
         if (config.format === "json") {
             process.stdout.write(`${(0, reporter_1.formatJsonOutput)(VERSION, sorted, { rulesRun, durationMs, backendErrors })}\n`);
         }
         else {
-            process.stdout.write(`${(0, reporter_1.formatTextOutput)(sorted)}\n`);
+            process.stdout.write(`${(0, reporter_1.formatTextOutput)(sorted, { rulesRun, durationMs, backendErrors })}\n`);
         }
         debugLog(config.debug, `Rendered output in ${Date.now() - outputStartedAt}ms`);
         debugLog(config.debug, `Total run duration ${durationMs}ms`);
@@ -179,6 +224,9 @@ async function runSemlint(options) {
         return 0;
     }
     catch (error) {
+        if (spinner) {
+            spinner.error({ text: "Analysis failed" });
+        }
         const message = error instanceof Error ? error.message : String(error);
         process.stderr.write(`${message}\n`);
         return 2;

package/dist/reporter.js

@@ -1,7 +1,20 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatJsonOutput = formatJsonOutput;
 exports.formatTextOutput = formatTextOutput;
+const picocolors_1 = __importDefault(require("picocolors"));
+function formatSeverity(severity) {
+    if (severity === "error")
+        return picocolors_1.default.red(severity);
+    if (severity === "warn")
+        return picocolors_1.default.yellow(severity);
+    if (severity === "info")
+        return picocolors_1.default.cyan(severity);
+    return severity;
+}
 function formatJsonOutput(version, diagnostics, stats) {
     const payload = {
         tool: {
@@ -17,7 +30,7 @@ function formatJsonOutput(version, diagnostics, stats) {
     };
     return JSON.stringify(payload, null, 2);
 }
-function formatTextOutput(diagnostics) {
+function formatTextOutput(diagnostics, stats) {
     const lines = [];
     let currentFile = "";
     for (const diagnostic of diagnostics) {
@@ -26,10 +39,10 @@ function formatTextOutput(diagnostics) {
                 lines.push("");
             }
             currentFile = diagnostic.file;
-            lines.push(currentFile);
+            lines.push(picocolors_1.default.underline(currentFile));
         }
         const column = diagnostic.column ?? 1;
-        lines.push(`  ${diagnostic.line}:${column}  ${diagnostic.severity}  ${diagnostic.rule_id}  ${diagnostic.message}`);
+        lines.push(`  ${picocolors_1.default.dim(`${diagnostic.line}:${column}`)}  ${formatSeverity(diagnostic.severity)}  ${picocolors_1.default.gray(diagnostic.rule_id)}  ${diagnostic.message}`);
     }
     const errors = diagnostics.filter((d) => d.severity === "error").length;
     const warnings = diagnostics.filter((d) => d.severity === "warn").length;
@@ -37,6 +50,24 @@ function formatTextOutput(diagnostics) {
     if (lines.length > 0) {
         lines.push("");
     }
-    lines.push(`✖ ${problems} problems (${errors} errors, ${warnings} warnings)`);
+    const summary = `✖ ${problems} problems (${errors} errors, ${warnings} warnings)`;
+    const timeInfo = ` in ${(stats.durationMs / 1000).toFixed(1)}s`;
+    if (problems === 0) {
+        if (stats.rulesRun === 0) {
+            lines.push(picocolors_1.default.green(`✔ 0 problems (no rules matched changed files)`));
+        }
+        else {
+            lines.push(picocolors_1.default.green(`✔ 0 problems (0 errors, 0 warnings)`));
+        }
+    }
+    else if (errors > 0) {
+        lines.push(picocolors_1.default.red(summary) + picocolors_1.default.gray(timeInfo));
+    }
+    else {
+        lines.push(picocolors_1.default.yellow(summary) + picocolors_1.default.gray(timeInfo));
+    }
+    if (problems === 0 && stats.durationMs > 0) {
+        lines[lines.length - 1] += picocolors_1.default.gray(timeInfo);
+    }
     return lines.join("\n");
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "semlint-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Semantic lint CLI — runs LLM-backed rules on your git diff and returns CI-friendly exit codes",
   "type": "commonjs",
   "main": "dist/main.js",
   "bin": {
-    "semlint": "dist/cli.js"
+    "semlint-cli": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -40,6 +40,8 @@
   },
   "packageManager": "pnpm@10.29.2",
   "dependencies": {
+    "nanospinner": "^1.2.2",
+    "picocolors": "^1.1.1",
     "picomatch": "^4.0.3"
   },
   "devDependencies": {

package/rules/SEMLINT_NAMING_001.json

@@ -1,12 +0,0 @@
-{
-  "id": "SEMLINT_NAMING_001",
-  "title": "Ambient naming convention consistency",
-  "severity_default": "warn",
-  "include_globs": ["src/**/*.ts"],
-  "exclude_globs": ["**/*.test.ts", "**/*.spec.ts"],
-  "diff_regex": [
-    "^[+-].*\\b(const|let|var|function|class|interface|type|enum)\\b",
-    "^[+-].*\\b[A-Za-z_][A-Za-z0-9_]*\\b"
-  ],
-  "prompt": "You are Semlint. Review ONLY the modified code in the provided DIFF and verify naming is consistent with the ambient naming conventions already used in surrounding code. Focus on identifier styles such as camelCase for variables/functions, PascalCase for classes/types/interfaces, and ALL_CAPS for constants where that convention is clearly established nearby. Flag only clear inconsistencies in newly added or renamed identifiers. Ignore untouched legacy naming unless directly impacted by the change. Return valid JSON only with shape {\"diagnostics\":[...]} and each diagnostic must include: rule_id, severity, message, file, line."
-}

package/rules/SEMLINT_PATTERN_002.json

@@ -1,12 +0,0 @@
-{
-  "id": "SEMLINT_PATTERN_002",
-  "title": "Ambient pattern is respected",
-  "severity_default": "warn",
-  "include_globs": ["src/**/*.ts"],
-  "exclude_globs": ["**/*.test.ts", "**/*.spec.ts"],
-  "diff_regex": [
-    "^[+-].*\\b(async|await|Promise|try|catch|throw|switch|map|filter|reduce|forEach)\\b",
-    "^[+-].*\\b(import|export|class|interface|type|function|return)\\b"
-  ],
-  "prompt": "You are Semlint. Review ONLY the modified code in the provided DIFF and check whether ambient implementation patterns are respected. Compare new or changed code against nearby established patterns for control flow, async handling, error propagation, data transformation, module boundaries, and function/class structure. Flag clear regressions where the proposed change deviates from consistent local patterns without obvious justification. Ignore untouched legacy code and acceptable intentional improvements. Return valid JSON only with shape {\"diagnostics\":[...]} and each diagnostic must include: rule_id, severity, message, file, line."
-}

package/rules/SEMLINT_SWE_003.json

@@ -1,12 +0,0 @@
-{
-  "id": "SEMLINT_SWE_003",
-  "title": "Obvious SWE mistakes",
-  "severity_default": "warn",
-  "include_globs": ["src/**/*.ts"],
-  "exclude_globs": ["**/*.test.ts", "**/*.spec.ts"],
-  "diff_regex": [
-    "^[+-].*\\b(any|as\\s+any|TODO|FIXME|console\\.log|@ts-ignore|throw\\s+new\\s+Error|catch\\s*\\()\\b",
-    "^[+-].*\\b(if|else|switch|return|await|Promise|map|forEach|reduce)\\b"
-  ],
-  "prompt": "You are Semlint. Review ONLY the modified code in the DIFF and find obvious software-engineering mistakes in the proposed change. Focus on clear issues such as dead code, side-effect misuse, swallowed errors, unsafe any-casts, accidental debug leftovers, contradictory conditions, and obvious maintainability hazards that are likely unintended (these are only examples, there are many more). Do not nitpick style or architecture unless the issue is clearly harmful. Report only high-signal findings tied to changed lines. Return valid JSON only with shape {\"diagnostics\":[...]} and each diagnostic must include: rule_id, severity, message, file, line."
-}