nollm 0.0.0

package/src/files.js

@@ -0,0 +1,118 @@
+import { execFile } from "node:child_process";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import ignore from "ignore";
+
+const run = promisify(execFile);
+
+const ALWAYS_SKIPPED = new Set([".git", "node_modules"]);
+
+/**
+ * Lists the files to check.
+ *
+ * Paths come back relative to cwd, with forward slashes.
+ * Files that git ignores are left out.
+ *
+ * Inside a git work tree the list comes from git itself.
+ * Elsewhere, or with git: false, the tool reads .gitignore files while it walks.
+ *
+ * The ignore option takes patterns in .gitignore syntax.
+ */
+export async function collectFiles(
+  roots,
+  { cwd = process.cwd(), git = true, ignore: patterns = [] } = {},
+) {
+  const files = git ? await fromGit(roots, cwd) : null;
+  const list = files ?? (await fromWalk(roots, cwd));
+  if (patterns.length === 0) return list;
+
+  const matcher = ignore().add(patterns);
+  return list.filter((file) => !matcher.ignores(file));
+}
+
+async function fromGit(roots, cwd) {
+  const args = [
+    "ls-files",
+    "-z",
+    "--cached",
+    "--others",
+    "--exclude-standard",
+    "--deduplicate",
+    "--",
+  ];
+  for (let i = 0; i < roots.length; i++) args.push(roots[i]);
+
+  let stdout;
+  try {
+    ({ stdout } = await run("git", args, { cwd, maxBuffer: 256 * 1024 * 1024 }));
+  } catch {
+    return null;
+  }
+
+  const files = [];
+  const parts = stdout.split("\0");
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i].length > 0) files.push(parts[i]);
+  }
+  return files;
+}
+
+async function fromWalk(roots, cwd) {
+  const files = [];
+  for (let i = 0; i < roots.length; i++) {
+    const absolute = resolve(cwd, roots[i]);
+    const info = await stat(absolute);
+    if (info.isFile()) {
+      files.push(toPosix(relative(cwd, absolute)));
+      continue;
+    }
+    await walk(absolute, cwd, [], files);
+  }
+  return files;
+}
+
+async function walk(dir, cwd, filters, files) {
+  const local = await readIgnore(dir);
+  const active = local ? filters.concat([local]) : filters;
+  const entries = await readdir(dir, { withFileTypes: true });
+
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (ALWAYS_SKIPPED.has(entry.name)) continue;
+
+    const absolute = join(dir, entry.name);
+    const isDir = entry.isDirectory();
+    if (!isDir && !entry.isFile()) continue;
+    if (isIgnored(absolute, isDir, active)) continue;
+
+    if (isDir) {
+      await walk(absolute, cwd, active, files);
+    } else {
+      files.push(toPosix(relative(cwd, absolute)));
+    }
+  }
+}
+
+async function readIgnore(dir) {
+  let content;
+  try {
+    content = await readFile(join(dir, ".gitignore"), "utf8");
+  } catch {
+    return null;
+  }
+  return { base: dir, matcher: ignore().add(content) };
+}
+
+function isIgnored(absolute, isDir, filters) {
+  for (let i = 0; i < filters.length; i++) {
+    const { base, matcher } = filters[i];
+    const rel = toPosix(relative(base, absolute)) + (isDir ? "/" : "");
+    if (matcher.ignores(rel)) return true;
+  }
+  return false;
+}
+
+function toPosix(path) {
+  return sep === "/" ? path : path.split(sep).join("/");
+}

package/src/index.d.ts

@@ -0,0 +1,88 @@
+export type Scope = "prose" | "comments" | "everywhere";
+
+export interface Rule {
+  id: string;
+  message: string;
+  pattern: RegExp;
+  scope?: Scope;
+}
+
+export interface Finding {
+  line: number;
+  column: number;
+  ruleId: string;
+  message: string;
+  text: string;
+}
+
+export interface FileResult {
+  file: string;
+  findings: Finding[];
+  skipped: string | null;
+}
+
+export interface Summary {
+  files: number;
+  checked: number;
+  findings: number;
+  filesWithFindings: number;
+}
+
+export interface Segment {
+  text: string;
+  line: number;
+  column: number;
+}
+
+export interface Language {
+  comments: [start: string, end: string][];
+  strings: string[];
+  regions: [start: string, end: string, language: Language][];
+}
+
+export interface Config {
+  path: string | null;
+  rules: Rule[];
+  ignore: string[];
+  maxBytes: number;
+}
+
+export interface RuleConfig {
+  pattern: RegExp | string;
+  flags?: string;
+  message?: string;
+  scope?: Scope;
+}
+
+export interface UserConfig {
+  ignore?: string[];
+  words?: string[];
+  maxBytes?: number;
+  rules?: Record<string, boolean | RuleConfig>;
+}
+
+export interface LintOptions {
+  roots?: string[];
+  cwd?: string;
+  configPath?: string;
+  git?: boolean;
+  jobs?: number;
+  onResult?: (result: FileResult) => void;
+}
+
+export const rules: Rule[];
+export const SEARCH_PLACES: string[];
+
+export function check(filePath: string, source: string, rules?: Rule[]): Finding[];
+export function classify(
+  filePath: string,
+): { kind: "prose" } | { kind: "code"; language: Language } | null;
+export function collectFiles(
+  roots: string[],
+  options?: { cwd?: string; git?: boolean; ignore?: string[] },
+): Promise<string[]>;
+export function extractComments(source: string, language: Language): Segment[];
+export function extractLines(source: string): Segment[];
+export function findConfig(cwd: string): Promise<string | null>;
+export function loadConfig(configPath: string | null): Promise<Config>;
+export function lint(options?: LintOptions): Promise<Summary>;

package/src/index.js

@@ -0,0 +1,7 @@
+export { check } from "./check.js";
+export { classify } from "./languages.js";
+export { collectFiles } from "./files.js";
+export { extractComments, extractLines } from "./comments.js";
+export { findConfig, loadConfig, SEARCH_PLACES } from "./config.js";
+export { lint } from "./lint.js";
+export { rules } from "./rules.js";

package/src/languages.js

@@ -0,0 +1,266 @@
+/**
+ * A language describes how to find comments in a file.
+ *
+ * comments: pairs of start and end markers.
+ *   An end of "\n" means the comment runs to the end of the line.
+ *
+ * strings: delimiters that open and close a string.
+ *   Comment markers inside a string are ignored.
+ *
+ * regions: nested languages, for example <script> inside HTML.
+ */
+
+const clike = {
+  comments: [
+    ["/*", "*/"],
+    ["//", "\n"],
+  ],
+  strings: ['"', "'", "`"],
+  regions: [],
+};
+
+const css = {
+  comments: [["/*", "*/"]],
+  strings: ['"', "'"],
+  regions: [],
+};
+
+const rust = {
+  comments: clike.comments,
+  strings: ['"'],
+  regions: [],
+};
+
+const hash = {
+  comments: [["#", "\n"]],
+  strings: ['"', "'"],
+  regions: [],
+};
+
+const python = {
+  comments: [
+    ['"""', '"""'],
+    ["'''", "'''"],
+    ["#", "\n"],
+  ],
+  strings: ['"', "'"],
+  regions: [],
+};
+
+const config = {
+  comments: [["#", "\n"]],
+  strings: ['"'],
+  regions: [],
+};
+
+const ruby = {
+  comments: [
+    ["=begin", "=end"],
+    ["#", "\n"],
+  ],
+  strings: ['"', "'"],
+  regions: [],
+};
+
+const dash = {
+  comments: [["--", "\n"]],
+  strings: ['"', "'"],
+  regions: [],
+};
+
+const lua = {
+  comments: [
+    ["--[[", "]]"],
+    ["--", "\n"],
+  ],
+  strings: ['"', "'"],
+  regions: [],
+};
+
+const lisp = {
+  comments: [[";", "\n"]],
+  strings: ['"'],
+  regions: [],
+};
+
+const glimmer = {
+  comments: [
+    ["{{!--", "--}}"],
+    ["{{!", "}}"],
+    ["<!--", "-->"],
+  ],
+  strings: [],
+  regions: [],
+};
+
+const html = {
+  comments: [["<!--", "-->"]],
+  strings: [],
+  regions: [
+    ["<script", "</script>", clike],
+    ["<style", "</style>", css],
+  ],
+};
+
+const glimmerScript = {
+  comments: clike.comments,
+  strings: clike.strings,
+  regions: [["<template", "</template>", glimmer]],
+};
+
+const byExtension = {
+  js: clike,
+  jsx: clike,
+  mjs: clike,
+  cjs: clike,
+  ts: clike,
+  tsx: clike,
+  mts: clike,
+  cts: clike,
+  jsonc: clike,
+  json5: clike,
+  java: clike,
+  kt: clike,
+  kts: clike,
+  scala: clike,
+  groovy: clike,
+  c: clike,
+  h: clike,
+  cc: clike,
+  cpp: clike,
+  cxx: clike,
+  hpp: clike,
+  hh: clike,
+  m: clike,
+  mm: clike,
+  cs: clike,
+  go: clike,
+  swift: clike,
+  dart: clike,
+  php: clike,
+  zig: clike,
+  proto: clike,
+  gradle: clike,
+  rs: rust,
+  css,
+  scss: clike,
+  sass: clike,
+  less: clike,
+  py: python,
+  pyi: python,
+  rb: ruby,
+  rake: ruby,
+  sh: hash,
+  bash: hash,
+  zsh: hash,
+  fish: hash,
+  pl: hash,
+  pm: hash,
+  r: hash,
+  ex: hash,
+  exs: hash,
+  nim: hash,
+  ps1: hash,
+  yml: config,
+  yaml: config,
+  toml: config,
+  ini: config,
+  cfg: config,
+  conf: config,
+  env: config,
+  properties: config,
+  dockerfile: config,
+  makefile: config,
+  gitignore: config,
+  sql: dash,
+  hs: dash,
+  elm: dash,
+  ada: dash,
+  lua,
+  clj: lisp,
+  cljs: lisp,
+  edn: lisp,
+  lisp,
+  el: lisp,
+  scm: lisp,
+  rkt: lisp,
+  hbs: glimmer,
+  handlebars: glimmer,
+  html: html,
+  htm: html,
+  xml: html,
+  svg: html,
+  vue: html,
+  svelte: html,
+  astro: html,
+  gjs: glimmerScript,
+  gts: glimmerScript,
+};
+
+const proseExtensions = new Set([
+  "md",
+  "mdx",
+  "markdown",
+  "txt",
+  "text",
+  "rst",
+  "adoc",
+  "asciidoc",
+  "org",
+]);
+
+const proseNames = new Set([
+  "readme",
+  "contributing",
+  "changelog",
+  "license",
+  "licence",
+  "authors",
+  "notice",
+  "todo",
+  "install",
+  "history",
+  "news",
+]);
+
+const codeNames = {
+  dockerfile: config,
+  makefile: config,
+  gnumakefile: config,
+  rakefile: ruby,
+  gemfile: ruby,
+  guardfile: ruby,
+  vagrantfile: ruby,
+  brewfile: ruby,
+  justfile: hash,
+  procfile: config,
+};
+
+/**
+ * Returns { kind: "prose" } for text files,
+ * { kind: "code", language } for source files,
+ * and null for files this tool does not read.
+ */
+export function classify(filePath) {
+  const base = filePath.slice(Math.max(filePath.lastIndexOf("/"), filePath.lastIndexOf("\\")) + 1);
+  const lower = base.toLowerCase();
+  const dot = lower.lastIndexOf(".");
+
+  if (dot === -1) {
+    if (proseNames.has(lower)) return { kind: "prose" };
+    const language = codeNames[lower];
+    return language ? { kind: "code", language } : null;
+  }
+
+  const ext = lower.slice(dot + 1);
+  const stem = lower.slice(0, dot);
+
+  if (proseExtensions.has(ext)) return { kind: "prose" };
+  if (dot === 0) {
+    const language = byExtension[ext];
+    return language ? { kind: "code", language } : null;
+  }
+
+  const language = byExtension[ext] ?? codeNames[stem];
+  return language ? { kind: "code", language } : null;
+}

package/src/lint.js

@@ -0,0 +1,51 @@
+import { resolve } from "node:path";
+import { Tinypool } from "tinypool";
+import { findConfig, loadConfig } from "./config.js";
+import { collectFiles } from "./files.js";
+
+/**
+ * Checks every file under the given roots.
+ *
+ * onResult runs once per file, as soon as that file is done.
+ * The returned promise resolves after the last file.
+ */
+export async function lint({
+  roots = ["."],
+  cwd = process.cwd(),
+  configPath,
+  git = true,
+  jobs,
+  onResult = () => {},
+} = {}) {
+  const resolvedConfig = configPath ? resolve(cwd, configPath) : await findConfig(cwd);
+  const config = await loadConfig(resolvedConfig);
+  const files = await collectFiles(roots, { cwd, git, ignore: config.ignore });
+
+  const pool = new Tinypool({
+    filename: new URL("./worker.js", import.meta.url).href,
+    workerData: { configPath: resolvedConfig, cwd },
+    maxThreads: jobs,
+  });
+
+  const summary = { files: files.length, checked: 0, findings: 0, filesWithFindings: 0 };
+
+  try {
+    const pending = [];
+    for (let i = 0; i < files.length; i++) {
+      const done = pool.run(files[i]).then((result) => {
+        if (!result.skipped) summary.checked++;
+        if (result.findings.length > 0) {
+          summary.findings += result.findings.length;
+          summary.filesWithFindings++;
+        }
+        onResult(result);
+      });
+      pending.push(done);
+    }
+    await Promise.all(pending);
+  } finally {
+    await pool.destroy();
+  }
+
+  return summary;
+}