semlint-cli 0.1.1 → 0.1.3

package/README.md

@@ -115,11 +115,11 @@ This creates `./semlint.json` and auto-detects installed coding agent CLIs in th
 
 If no known CLI is detected, Semlint falls back to `cursor-cli` + executable `cursor`.
 
-Use `semlint init --force` to overwrite an existing config file.
+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,6 +1,10 @@
 #!/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 = [
@@ -11,7 +15,7 @@ const HELP_TEXT = [
     "",
     "Commands:",
     "  check   Run semantic lint rules against your git diff",
-    "  init    Create semlint.json with auto-detected agent backend",
+    "  init    Create semlint.json, .semlint/rules/, and an example rule to edit",
     "",
     "Options:",
     "  -h, --help   Show this help text"
@@ -122,8 +126,14 @@ async function main() {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        process.stderr.write(`${message}\n`);
-        process.exitCode = error instanceof HelpRequestedError ? 0 : 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/git.js

@@ -36,29 +36,6 @@ async function getGitDiff(base, head) {
     const result = await runGitCommand(["diff", base, head]);
     return result.stdout;
 }
-function isMissingRefError(message) {
-    return /(not a valid object name|unknown revision|bad revision|no upstream configured|no upstream branch)/i.test(message);
-}
-async function resolveLocalComparisonBase() {
-    const candidates = ["@{upstream}", "origin/main", "main"];
-    for (const candidate of candidates) {
-        try {
-            const result = await runGitCommand(["merge-base", "HEAD", candidate]);
-            const mergeBase = result.stdout.trim();
-            if (mergeBase !== "") {
-                return mergeBase;
-            }
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            if (!isMissingRefError(message)) {
-                throw error;
-            }
-            continue;
-        }
-    }
-    return "HEAD";
-}
 async function getUntrackedFiles() {
     const result = await runGitCommand(["ls-files", "--others", "--exclude-standard"]);
     return result.stdout
@@ -70,9 +47,16 @@ async function getNoIndexDiffForFile(filePath) {
     const result = await runGitCommand(["diff", "--no-index", "--", node_os_1.devNull, filePath], [0, 1]);
     return result.stdout;
 }
+/**
+ * Returns the diff for the current branch limited to:
+ * - Staged changes (--cached: index vs HEAD)
+ * - Unstaged changes (working tree vs index)
+ * - Untracked files (as full-file diffs)
+ * Does not include already-committed changes on the branch.
+ */
 async function getLocalBranchDiff() {
-    const base = await resolveLocalComparisonBase();
-    const trackedDiff = await runGitCommand(["diff", base]);
+    const stagedResult = await runGitCommand(["diff", "--cached"]);
+    const unstagedResult = await runGitCommand(["diff"]);
     const untrackedFiles = await getUntrackedFiles();
     const untrackedDiffChunks = [];
     for (const filePath of untrackedFiles) {
@@ -81,5 +65,7 @@ async function getLocalBranchDiff() {
             untrackedDiffChunks.push(fileDiff);
         }
     }
-    return [trackedDiff.stdout, ...untrackedDiffChunks].filter((chunk) => chunk !== "").join("\n");
+    return [stagedResult.stdout, unstagedResult.stdout, ...untrackedDiffChunks]
+        .filter((chunk) => chunk !== "")
+        .join("\n");
 }

package/dist/init.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (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");
@@ -72,7 +73,23 @@ function scaffoldConfig(force = false) {
         }
     };
     node_fs_1.default.writeFileSync(targetPath, `${JSON.stringify(scaffold, null, 2)}\n`, "utf8");
-    process.stdout.write(`Created ${targetPath}\n`);
-    process.stdout.write(`Backend setup: ${detected.backend} (${detected.reason})\n`);
+    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(", ")}`);
@@ -65,7 +91,7 @@ async function runSemlint(options) {
         const diff = await timedAsync(config.debug, "Computed git diff", () => useLocalBranchDiff ? (0, git_1.getLocalBranchDiff)() : (0, git_1.getGitDiff)(config.base, config.head));
         const changedFiles = timed(config.debug, "Parsed changed files from diff", () => (0, filter_1.extractChangedFilesFromDiff)(diff));
         debugLog(config.debug, useLocalBranchDiff
-            ? "Using local branch diff (tracked + staged + unstaged + untracked)"
+            ? "Using local branch diff (staged + unstaged + untracked only)"
             : `Using explicit ref diff (${config.base}..${config.head})`);
         debugLog(config.debug, `Detected ${changedFiles.length} changed file(s)`);
         const backend = timed(config.debug, "Initialized backend runner", () => (0, backend_1.createBackendRunner)(config));
@@ -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,6 +1,6 @@
 {
   "name": "semlint-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Semantic lint CLI — runs LLM-backed rules on your git diff and returns CI-friendly exit codes",
   "type": "commonjs",
   "main": "dist/main.js",
@@ -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."
-}