nollm 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NullVoxPopuli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# nollm
+
+Lint against LLMisms in your codebase.
+
+`nollm` reads every file that git tracks or does not ignore.
+It checks prose files line by line, and code files comment by comment.
+Each finding prints as soon as it is found.
+
+```
+npx nollm
+```
+
+## Install
+
+```
+pnpm add -D nollm
+```
+
+Add a script to `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint:prose": "nollm"
+  }
+}
+```
+
+Requires Node 22.13 or newer.
+
+## Usage
+
+```
+nollm [options] [paths...]
+```
+
+With no paths, `nollm` checks the current directory.
+Paths can be files or directories.
+
+| Option            | Effect                                                             |
+| ----------------- | ------------------------------------------------------------------ |
+| `--jobs <n>`      | Number of worker threads. Defaults to the CPU count.               |
+| `--config <path>` | Config file to use.                                                |
+| `--no-git`        | Do not ask git for the file list. Read `.gitignore` files instead. |
+| `--quiet`         | Print only the summary.                                            |
+| `--list-rules`    | Print every rule and exit.                                         |
+
+The exit code is 1 when there are findings, and 2 on a usage error.
+
+Output looks like this:
+
+```
+README.md:3:14  filler-word  Filler. Delete it or replace it: "simply"
+src/index.js:1:1  what-comment  Comment narrates what the code does. Say why, or delete it: "// This function"
+2 problems in 2 files (5 files checked, 0.07s)
+```
+
+## What gets checked
+
+Prose files: markdown, text, reStructuredText, AsciiDoc, and files named `README`, `CHANGELOG`, `LICENSE`, and similar.
+Every line is checked.
+
+Code files: JavaScript, TypeScript, Python, Ruby, Rust, Go, shell, YAML, TOML, HTML, Handlebars, `.gjs`, `.gts`, and many more.
+Only comments are checked, so identifiers and string contents do not trigger rules.
+The `error-exclamation` rule is the exception. It checks every line, because it targets error strings.
+
+Files of other types, binary files, lockfiles, minified files, and files over 2 MB are skipped.
+
+## Rules
+
+| Rule                  | Catches                                                                 |
+| --------------------- | ----------------------------------------------------------------------- |
+| `banned-word`         | genuinely, load-bearing, crutch, spearheaded, fails loudly, and friends |
+| `em-dash`             | The em dash character                                                   |
+| `bold-fragment`       | `**Bold label:** followed by plain text` in markdown                    |
+| `filler-word`         | simply, robust, leverage, utilize, in order to, keep in mind, and more  |
+| `llm-vocabulary`      | delve, tapestry, crucial, game-changer, battle-tested, and more         |
+| `chat-opener`         | Lines that start with "Great question", "Certainly", "Let me", and more |
+| `chat-closer`         | "Hope this helps", "Let me know if", "Feel free to", and more           |
+| `ai-disclosure`       | "As an AI", "my training data", and more                                |
+| `error-exclamation`   | "Oops", "Uh oh", "Something went wrong"                                 |
+| `contrast-cliche`     | "not just X, but Y" and "it's not X, it's Y"                            |
+| `rhetorical-question` | "Why? Because" and "The result?"                                        |
+| `emoji`               | Emoji                                                                   |
+| `diff-comment`        | Comments about the change: "no longer", "as discussed", "previously"    |
+| `what-comment`        | Comments that narrate the code: "This function returns", "Loop over"    |
+
+Run `nollm --list-rules` for the full list.
+
+## Configuration
+
+`nollm` finds its config with [lilconfig](https://github.com/antonk52/lilconfig).
+Put it in one of these places:
+
+- a `nollm` key in `package.json`
+- `.nollmrc` or `.nollmrc.json`
+- `.nollmrc.js`, `.nollmrc.cjs`, or `.nollmrc.mjs`
+- `nollm.config.js`, `nollm.config.cjs`, or `nollm.config.mjs`
+
+Parent directories are searched too.
+
+```js
+// nollm.config.js
+export default {
+  // .gitignore syntax
+  ignore: ["CHANGELOG.md", "tests/fixtures/"],
+
+  // extra banned words
+  words: ["synergy", "circle back"],
+
+  rules: {
+    // turn a rule off
+    "em-dash": false,
+
+    // add a rule, or replace a built in one
+    "open-todo": {
+      pattern: /\bTODO\b/,
+      message: "Open TODO",
+      scope: "comments",
+    },
+  },
+};
+```
+
+In JSON configs, write the pattern as a string and add flags in a `flags` key.
+
+`scope` is one of:
+
+- `prose`: prose files only
+- `comments`: comments in code files only
+- `everywhere`: every line of every file
+
+A rule with no scope runs in prose and in comments.
+
+To silence one line, put `nollm-ignore-next-line` on the line before it.
+To silence a whole file, put `nollm-ignore-file` anywhere in it.
+
+## API
+
+```js
+import { check, lint } from "nollm";
+
+const findings = check("README.md", "This is simply the best.");
+// [{ line: 1, column: 9, ruleId: "filler-word", message: "...", text: "simply" }]
+
+const summary = await lint({
+  roots: ["src", "docs"],
+  onResult({ file, findings }) {
+    // runs once per file, as soon as it is done
+  },
+});
+// { files: 12, checked: 10, findings: 3, filesWithFindings: 2 }
+```

package/bin/nollm.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "nollm",
+  "version": "0.0.0",
+  "description": "lint against LLMisms in your codebase",
+  "keywords": [
+    "comments",
+    "lint",
+    "llm",
+    "markdown",
+    "prose"
+  ],
+  "license": "MIT",
+  "author": "NullVoxPopuli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NullVoxPopuli/nollm.git"
+  },
+  "bin": {
+    "nollm": "bin/nollm.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "scripts": {
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint && pnpm format:check && publint && pnpm lint:prose",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "lint:prose": "node bin/nollm.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "ignore": "^7.0.9",
+    "lilconfig": "^3.1.3",
+    "tinypool": "^2.2.0"
+  },
+  "devDependencies": {
+    "@tsconfig/node-lts": "^24.0.1",
+    "oxfmt": "^0.68.0",
+    "oxlint": "^1.83.0",
+    "publint": "^0.3.24",
+    "vitest": "^5.0.1"
+  },
+  "engines": {
+    "node": ">= 22.5"
+  },
+  "packageManager": "pnpm@11.22.0"
+}

package/src/check.js

@@ -0,0 +1,86 @@
+import { classify } from "./languages.js";
+import { extractComments, extractLines } from "./comments.js";
+import { rules as builtinRules } from "./rules.js";
+
+const IGNORE_FILE = "nollm-ignore-file";
+const IGNORE_NEXT = "nollm-ignore-next-line";
+
+/**
+ * Checks one file's content and returns its findings.
+ *
+ * A finding is { line, column, ruleId, message, text }.
+ * Files this tool does not read return an empty array.
+ *
+ * A line that contains nollm-ignore-next-line silences the line after it.
+ * A file that contains nollm-ignore-file returns no findings.
+ */
+export function check(filePath, source, rules = builtinRules) {
+  const kind = classify(filePath);
+  if (!kind) return [];
+  if (source.includes(IGNORE_FILE)) return [];
+
+  const findings = collect(kind, source, rules);
+  return source.includes(IGNORE_NEXT) ? withoutIgnored(findings, source) : findings;
+}
+
+function collect(kind, source, rules) {
+  const findings = [];
+
+  if (kind.kind === "prose") {
+    const lines = extractLines(source);
+    run(findings, lines, rules, "prose");
+    run(findings, lines, rules, "everywhere");
+    findings.sort(byPosition);
+    return findings;
+  }
+
+  run(findings, extractComments(source, kind.language), rules, "comments");
+  run(findings, extractLines(source), rules, "everywhere");
+  findings.sort(byPosition);
+  return findings;
+}
+
+function run(findings, segments, rules, scope) {
+  for (let r = 0; r < rules.length; r++) {
+    const rule = rules[r];
+    if (!applies(rule, scope)) continue;
+
+    for (let s = 0; s < segments.length; s++) {
+      const segment = segments[s];
+      const pattern = rule.pattern;
+      pattern.lastIndex = 0;
+
+      let match;
+      while ((match = pattern.exec(segment.text)) !== null) {
+        findings.push({
+          line: segment.line,
+          column: segment.column + match.index,
+          ruleId: rule.id,
+          message: rule.message,
+          text: match[0].trim(),
+        });
+        if (match[0].length === 0) pattern.lastIndex++;
+      }
+    }
+  }
+}
+
+function withoutIgnored(findings, source) {
+  const silenced = new Set();
+  const lines = extractLines(source);
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].text.includes(IGNORE_NEXT)) silenced.add(lines[i].line + 1);
+  }
+  return findings.filter((finding) => !silenced.has(finding.line));
+}
+
+function applies(rule, scope) {
+  const own = rule.scope ?? "text";
+  if (scope === "everywhere") return own === "everywhere";
+  if (own === "text") return true;
+  return own === scope;
+}
+
+function byPosition(a, b) {
+  return a.line - b.line || a.column - b.column;
+}

package/src/cli.js

@@ -0,0 +1,114 @@
+import { createRequire } from "node:module";
+import { parseArgs, styleText } from "node:util";
+import { lint } from "./lint.js";
+import { rules } from "./rules.js";
+
+const HELP = `Usage: nollm [options] [paths...]
+
+Checks files for LLMisms and prints each finding as soon as it is found.
+Files that git ignores are skipped.
+
+Options:
+  --jobs, -j <n>     Number of worker threads (default: cpu count)
+  --config <path>    Config file (default: nollm.config.js in the current directory)
+  --no-git           Do not ask git for the file list. Read .gitignore files instead
+  --quiet, -q        Print only the summary
+  --list-rules       Print every rule and exit
+  --version, -v      Print the version and exit
+  --help, -h         Print this help and exit
+
+Exit code 1 when there are findings. Exit code 2 on a usage error.
+`;
+
+export async function main(
+  argv,
+  { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd() } = {},
+) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      allowNegative: true,
+      options: {
+        jobs: { type: "string", short: "j" },
+        config: { type: "string" },
+        git: { type: "boolean", default: true },
+        quiet: { type: "boolean", short: "q", default: false },
+        "list-rules": { type: "boolean", default: false },
+        version: { type: "boolean", short: "v", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+    });
+  } catch (error) {
+    stderr.write(`${error.message}\n\n${HELP}`);
+    return 2;
+  }
+
+  const { values, positionals } = parsed;
+
+  if (values.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+
+  if (values.version) {
+    const require = createRequire(import.meta.url);
+    stdout.write(`${require("../package.json").version}\n`);
+    return 0;
+  }
+
+  if (values["list-rules"]) {
+    for (let i = 0; i < rules.length; i++) {
+      stdout.write(`${rules[i].id.padEnd(20)} ${rules[i].message}\n`);
+    }
+    return 0;
+  }
+
+  let jobs;
+  if (values.jobs !== undefined) {
+    jobs = Number(values.jobs);
+    if (!Number.isInteger(jobs) || jobs < 1) {
+      stderr.write(`--jobs needs a positive integer, got "${values.jobs}"\n`);
+      return 2;
+    }
+  }
+
+  const paint = (style, text) => styleText(style, text, { stream: stdout });
+  const started = performance.now();
+
+  let summary;
+  try {
+    summary = await lint({
+      roots: positionals.length > 0 ? positionals : ["."],
+      cwd,
+      configPath: values.config,
+      git: values.git,
+      jobs,
+      onResult(result) {
+        if (values.quiet) return;
+        const findings = result.findings;
+        for (let i = 0; i < findings.length; i++) {
+          stdout.write(formatFinding(result.file, findings[i], paint));
+        }
+      },
+    });
+  } catch (error) {
+    stderr.write(`${error.message}\n`);
+    return 2;
+  }
+
+  const seconds = ((performance.now() - started) / 1000).toFixed(2);
+  const problems = summary.findings === 1 ? "1 problem" : `${summary.findings} problems`;
+  const files = summary.filesWithFindings === 1 ? "1 file" : `${summary.filesWithFindings} files`;
+  const line = `${problems} in ${files} (${summary.checked} files checked, ${seconds}s)\n`;
+
+  stdout.write(summary.findings > 0 ? paint("red", line) : paint("green", line));
+  return summary.findings > 0 ? 1 : 0;
+}
+
+function formatFinding(file, finding, paint) {
+  const where = paint("dim", `${file}:${finding.line}:${finding.column}`);
+  const rule = paint("yellow", finding.ruleId);
+  return `${where}  ${rule}  ${finding.message}: ${JSON.stringify(finding.text)}\n`;
+}

package/src/comments.js

@@ -0,0 +1,156 @@
+/**
+ * Scans a source file and returns its comments as segments.
+ *
+ * A segment is one physical line of one comment:
+ *   { text, line, column }
+ *
+ * line and column are 1-based.
+ * Block comments produce one segment per line.
+ * Comment markers stay in the text.
+ */
+export function extractComments(source, language) {
+  const segments = [];
+  const stack = [{ language, end: null }];
+  let index = 0;
+  let line = 1;
+  let lineStart = 0;
+
+  while (index < source.length) {
+    const frame = stack[stack.length - 1];
+    const current = frame.language;
+
+    if (frame.end && startsWith(source, index, frame.end)) {
+      index += frame.end.length;
+      stack.pop();
+      continue;
+    }
+
+    const region = findRegion(source, index, current.regions);
+    if (region) {
+      index += region[0].length;
+      stack.push({ language: region[2], end: region[1] });
+      continue;
+    }
+
+    const comment = findMarker(source, index, current.comments);
+    if (comment) {
+      const [start, end] = comment;
+      const closeAt =
+        end === "\n" ? source.indexOf("\n", index) : source.indexOf(end, index + start.length);
+      const stop = closeAt === -1 ? source.length : end === "\n" ? closeAt : closeAt + end.length;
+
+      pushLines(segments, source, index, stop, line, lineStart);
+
+      for (let i = index; i < stop; i++) {
+        if (source.charCodeAt(i) === 10) {
+          line++;
+          lineStart = i + 1;
+        }
+      }
+      index = stop;
+      continue;
+    }
+
+    const quote = findString(source, index, current.strings);
+    if (quote) {
+      index += quote.length;
+      while (index < source.length) {
+        const code = source.charCodeAt(index);
+        if (code === 92) {
+          if (source.charCodeAt(index + 1) === 10) {
+            line++;
+            lineStart = index + 2;
+          }
+          index += 2;
+          continue;
+        }
+        if (code === 10) {
+          if (quote !== "`") break;
+          line++;
+          lineStart = index + 1;
+        }
+        if (startsWith(source, index, quote)) {
+          index += quote.length;
+          break;
+        }
+        index++;
+      }
+      continue;
+    }
+
+    if (source.charCodeAt(index) === 10) {
+      line++;
+      lineStart = index + 1;
+    }
+    index++;
+  }
+
+  return segments;
+}
+
+/**
+ * Every line of a prose file is a segment.
+ */
+export function extractLines(source) {
+  const segments = [];
+  let line = 1;
+  let start = 0;
+
+  while (start <= source.length) {
+    let end = source.indexOf("\n", start);
+    if (end === -1) end = source.length;
+    if (end > start) {
+      segments.push({ text: source.slice(start, end), line, column: 1 });
+    }
+    line++;
+    start = end + 1;
+  }
+
+  return segments;
+}
+
+function pushLines(segments, source, from, to, line, lineStart) {
+  let start = from;
+  let currentLine = line;
+  let currentLineStart = lineStart;
+
+  while (start < to) {
+    let end = source.indexOf("\n", start);
+    if (end === -1 || end > to) end = to;
+    if (end > start) {
+      segments.push({
+        text: source.slice(start, end),
+        line: currentLine,
+        column: start - currentLineStart + 1,
+      });
+    }
+    currentLine++;
+    currentLineStart = end + 1;
+    start = end + 1;
+  }
+}
+
+function startsWith(source, index, marker) {
+  return source.startsWith(marker, index);
+}
+
+function findMarker(source, index, markers) {
+  for (let i = 0; i < markers.length; i++) {
+    if (startsWith(source, index, markers[i][0])) return markers[i];
+  }
+  return null;
+}
+
+function findRegion(source, index, regions) {
+  for (let i = 0; i < regions.length; i++) {
+    if (startsWith(source, index, regions[i][0])) return regions[i];
+  }
+  return null;
+}
+
+function findString(source, index, quotes) {
+  for (let i = 0; i < quotes.length; i++) {
+    if (startsWith(source, index, quotes[i])) return quotes[i];
+  }
+  return null;
+}

package/src/config.js

@@ -0,0 +1,110 @@
+import { lilconfig } from "lilconfig";
+import { rules as builtinRules } from "./rules.js";
+
+const SKIPPED = [
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "yarn.lock",
+  "*.min.js",
+  "*.min.css",
+  "*.map",
+];
+
+export const SEARCH_PLACES = [
+  "package.json",
+  ".nollmrc",
+  ".nollmrc.json",
+  ".nollmrc.js",
+  ".nollmrc.cjs",
+  ".nollmrc.mjs",
+  "nollm.config.js",
+  "nollm.config.cjs",
+  "nollm.config.mjs",
+];
+
+const explorer = lilconfig("nollm", { searchPlaces: SEARCH_PLACES });
+
+/**
+ * Finds the config for a directory with lilconfig.
+ * Parent directories are searched too.
+ *
+ * Returns the path of the config file, or null.
+ */
+export async function findConfig(cwd) {
+  const result = await explorer.search(cwd);
+  return result?.filepath ?? null;
+}
+
+/**
+ * Loads a config file and merges it with the defaults.
+ *
+ * The result has:
+ *   rules  → the rules to run
+ *   ignore → patterns of files to skip, in .gitignore syntax
+ */
+export async function loadConfig(configPath) {
+  let user = {};
+  if (configPath) {
+    const result = await explorer.load(configPath);
+    user = result?.config ?? {};
+  }
+
+  return {
+    path: configPath,
+    rules: resolveRules(user.rules, user.words),
+    ignore: SKIPPED.concat(user.ignore ?? []),
+    maxBytes: user.maxBytes ?? 2 * 1024 * 1024,
+  };
+}
+
+function resolveRules(overrides = {}, words = []) {
+  const rules = [];
+
+  for (let i = 0; i < builtinRules.length; i++) {
+    const rule = builtinRules[i];
+    const override = overrides[rule.id];
+    if (override === false) continue;
+    rules.push(isObject(override) ? customRule(rule.id, override) : rule);
+  }
+
+  for (const id in overrides) {
+    const override = overrides[id];
+    if (!isObject(override)) continue;
+    if (builtinRules.some((rule) => rule.id === id)) continue;
+    rules.push(customRule(id, override));
+  }
+
+  if (words.length > 0) {
+    const escaped = words.map((word) => word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    rules.push({
+      id: "custom-word",
+      message: "Banned word (nollm config)",
+      pattern: new RegExp(String.raw`\b(?:${escaped.join("|")})\b`, "gi"),
+    });
+  }
+
+  return rules;
+}
+
+function customRule(id, override) {
+  return {
+    id,
+    message: override.message ?? id,
+    pattern: toGlobal(id, override.pattern, override.flags),
+    scope: override.scope,
+  };
+}
+
+function toGlobal(id, pattern, flags = "") {
+  if (typeof pattern === "string") {
+    return new RegExp(pattern, flags.includes("g") ? flags : flags + "g");
+  }
+  if (pattern instanceof RegExp) {
+    return pattern.global ? pattern : new RegExp(pattern.source, pattern.flags + "g");
+  }
+  throw new Error(`Rule "${id}" needs a pattern: a RegExp, or a string with optional flags`);
+}
+
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}