@justindfuller/ban-code-comments 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Fuller
+
+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,130 @@
+# ban-code-comments
+
+`ban-code-comments` detects code comments so teams can enforce a no-comments policy locally and in CI. It is a self-contained Node.js package with no repository configuration file required.
+
+## Install
+
+Install the published package with Node.js 24 or newer:
+
+```sh
+npm install --global @justindfuller/ban-code-comments
+```
+
+The package includes the `ban-code-comments` executable and the programmatic API. It does not require Go, a native executable, or a runtime download.
+
+## Usage
+
+Run `ban-code-comments` to scan the current repository, or pass one or more files or directories:
+
+```sh
+ban-code-comments .
+ban-code-comments src scripts
+```
+
+The default output is JSON with `findings` and `summary` fields. Use `--format text` for concise path, line, column, and comment output.
+
+```sh
+ban-code-comments --format text .
+ban-code-comments --language go,python --include 'src/**' --exclude 'src/vendor/**' .
+```
+
+The practical default reports ordinary and documentation comments. Select `ordinary`, `documentation`, `header`, or `directive` categories with `--categories`; selecting categories replaces the default set. Repeat or comma-separate `--language`, `--include`, and `--exclude` values. `--debug` writes reasons for skipped files to stderr.
+
+The process exits with `0` when no selected comments are found, `1` when findings exist, and `2` for invalid options, unreadable paths, or scan failures.
+
+## Supported languages
+
+Go; JavaScript, TypeScript, JSX, and TSX; Python; Rust; Java; C, C++, and C#; Kotlin; Swift; Ruby; PHP; shell; SQL; HTML and XML; CSS and SCSS; YAML; TOML; JSONC; HCL and Terraform; Dockerfile; Makefile; and INI. Standard JSON files are recognized and scanned as comment-free JSON.
+
+The scanner ignores comment-shaped text inside strings, raw strings, templates, escaped literals, heredocs, and triple-quoted literals. Unsupported or irrelevant files are skipped; use `--debug` to inspect those decisions.
+
+## GitHub Actions
+
+The Action requires a checkout step and runs with read-only repository access. Its release contains the matching JavaScript implementation, so it does not download or cache a native CLI at runtime.
+
+```yaml
+name: Ban code comments
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  comments:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: JustinDFuller-org/ban-code-comments@v1
+        with:
+          format: text
+          languages: go,python,typescript
+          exclude: |
+            vendor/**
+            internal/scanner/testdata/fixtures/**
+```
+
+Use `@v1` to receive compatible releases automatically. For reproducible workflows, pin an exact release such as `@v1.0.0` or pin the Action to a full commit SHA. The moving `v1` tag is maintained to the latest compatible release.
+
+The Action accepts the same configuration as the CLI:
+
+| Input | Default | Description |
+| --- | --- | --- |
+| `paths` | `.` | Files or directories to scan; separate multiple values with newlines. |
+| `languages` | — | Languages to scan; separate values with commas or newlines. |
+| `categories` | — | Comment categories to report; separate values with commas. |
+| `include` | — | File globs to include; separate multiple values with newlines. |
+| `exclude` | — | File globs to exclude; separate multiple values with newlines. |
+| `format` | `json` | Output format: `json` or `text`. |
+| `debug` | `false` | Set to `true` to write skipped-file diagnostics to stderr. |
+
+The Action exits `0` for a clean scan, `1` when selected findings exist, and `2` for invalid options or scan failures. Findings and operational errors therefore fail the workflow step while remaining distinguishable in the log.
+
+For direct automation outside GitHub Actions, install the npm package and run `ban-code-comments .` as a step. The CLI and Action use the same implementation, options, reports, and exit statuses.
+
+The package also exposes plain-data operations:
+
+```js
+import { check, scanSource } from "@justindfuller/ban-code-comments";
+
+const sourceFindings = scanSource("const value = 1; // finding\n", "fixture.js", "javascript");
+const repositoryResult = await check(["."], { categories: new Set(["ordinary", "documentation"]) });
+```
+
+The API exports `scanSource`, `discover`, `check`, `runCLI`, `evaluateHook`, `renderJSON`, `renderText`, `lookup`, and the shared model and category helpers.
+
+## Codex plugins
+
+This repository provides two separately installable Codex plugins: `ban-code-comments-warn` allows supported traditional file edits and adds guidance, while `ban-code-comments-hard-block` denies supported traditional file edits that introduce findings.
+
+Review plugin source and hook commands before trusting them, then add the repository marketplace and install one variant:
+
+```sh
+codex plugin marketplace add JustinDFuller-org/ban-code-comments
+codex plugin add ban-code-comments-warn@ban-code-comments
+```
+
+Use `ban-code-comments-hard-block@ban-code-comments` instead when denial is preferred, and review the enabled hook in `/hooks` after installation. The shared scanner covers the supported source and configuration languages in the language registry; Markdown, README files, literals, directives, and unsupported paths are not code-comment findings.
+
+Pre-tool evaluation reconstructs documented file-edit payloads from `apply_patch`, `edit`, `write`, `write_file`, and `file_write`, then compares proposed findings with the file's existing findings, so unchanged legacy comments do not block unrelated edits. Bash, shell, exec, MCP, generators, redirection, and other opaque write paths are outside the plugin boundary; the repository scanner and GitHub Action enforce the final state in CI.
+
+The guidance skill directs agents to use Git history, pull-request descriptions, simplified code, nearby README files, and Markdown instead of explanatory source comments. The plugin bundles are self-contained and work offline after installation. Roll back by disabling or removing the plugin with `codex plugin remove <plugin>@ban-code-comments`.
+
+## Development
+
+Run the complete local checks with Node.js 24 or newer:
+
+```sh
+npm ci
+npm test
+npm run coverage
+npm run validate:plugins
+npm run build
+npm run build:plugins
+```
+
+## Coverage policy
+
+CI runs the Node test suite, enforces at least 90 percent aggregate JavaScript line coverage, validates both Codex plugins, rebuilds generated distributions, runs the package CLI, and validates OpenSpec.
+
+Semantic-version tags matching `vMAJOR.MINOR.PATCH` publish the corresponding npm package version. The repository tag and Action major tag remain release references; the Action and plugins use the bundled JavaScript implementation coupled to that release.

package/bin/ban-code-comments.js

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

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@justindfuller/ban-code-comments",
+  "version": "1.0.2",
+  "type": "module",
+  "description": "Detect and ban code comments across source and configuration files",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": "./bin/ban-code-comments.js",
+  "exports": {
+    ".": "./src/api.js",
+    "./model": "./src/model.js",
+    "./languages": "./src/languages.js",
+    "./cli": "./src/cli.js",
+    "./hook": "./src/hook.js"
+  },
+  "main": "src/api.js",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "ncc build src/index.js --minify --source-map --license licenses.txt -o dist",
+    "build:plugins": "node scripts/build-plugins.mjs",
+    "smoke:codex": "node scripts/codex-smoke.mjs",
+    "validate:plugins": "node scripts/validate-plugins.mjs",
+    "test": "node --test test/*.test.js",
+    "coverage": "c8 --all --include=src/**/*.js --exclude=src/../dist/** --reporter=text --reporter=cobertura --check-coverage --lines=90 node --test test/*.test.js",
+    "check": "npm test && npm run validate:plugins && npm run build && git diff --exit-code -- dist licenses.txt"
+  },
+  "dependencies": {
+    "@actions/core": "3.0.1"
+  },
+  "devDependencies": {
+    "@vercel/ncc": "0.45.0",
+    "c8": "10.1.3"
+  }
+}

package/src/api.js

@@ -0,0 +1,9 @@
+export { CATEGORIES, DEFAULT_CATEGORIES, exitCode, finding, position, result, sourceRange } from "./model.js";
+export { extensions, languageAliases, lookup, parseSelection, supported } from "./languages.js";
+export { exitStatus, parseArgs } from "./cli.js";
+export { scanSource } from "./scanner.js";
+export { renderJSON, renderText } from "./report.js";
+export { discover } from "./discovery.js";
+export { check } from "./check.js";
+export { runCLI } from "./cli-runner.js";
+export { evaluateHook, runHook } from "./hook.js";

package/src/check.js

@@ -0,0 +1,17 @@
+import { promises as fs } from "node:fs";
+import { discover } from "./discovery.js";
+import { result } from "./model.js";
+import { scanSource } from "./scanner.js";
+
+export async function check(inputPaths = [], options = {}) {
+  const discovered = await discover(inputPaths, options);
+  if (options.onDiagnostic) for (const diagnostic of discovered.diagnostics) options.onDiagnostic(diagnostic);
+  const findings = [];
+  for (const candidate of discovered.candidates) {
+    let source;
+    try { source = await fs.readFile(candidate.path, "utf8"); }
+    catch (error) { throw new Error(`${candidate.relative}: ${error.message}`); }
+    findings.push(...scanSource(source, candidate.relative, candidate.language, options.categories));
+  }
+  return result(findings, { files_scanned: discovered.candidates.length, files_skipped: discovered.skipped, findings: findings.length });
+}

package/src/cli-runner.js

@@ -0,0 +1,21 @@
+import { check } from "./check.js";
+import { exitStatus, parseArgs } from "./cli.js";
+import { renderJSON, renderText } from "./report.js";
+import { CLI_VERSION } from "./version.js";
+
+export async function runCLI(args = [], streams = {}) {
+  const output = streams.stdout || process.stdout;
+  const errors = streams.stderr || process.stderr;
+  try {
+    const options = parseArgs(args);
+    if (options.help) { output.write("Usage: ban-code-comments [options] [path ...]\n"); return 0; }
+    if (options.version) { output.write(`${CLI_VERSION}\n`); return 0; }
+    const value = await check(options.paths, { ...options, cwd: streams.cwd, onDiagnostic: options.debug ? (item) => errors.write(`debug: ${item.path}: ${item.reason}\n`) : undefined });
+    output.write(options.format === "text" ? renderText(value) : renderJSON(value));
+    if (options.debug) errors.write(`scanned ${value.summary.files_scanned} source(s), skipped ${value.summary.files_skipped} path(s)\n`);
+    return exitStatus(value.findings);
+  } catch (error) {
+    errors.write(`${error.message}\n`);
+    return 2;
+  }
+}

package/src/cli.js

@@ -0,0 +1,44 @@
+import { DEFAULT_CATEGORIES, CATEGORIES } from "./model.js";
+import { parseSelection } from "./languages.js";
+
+const categoryNames = new Set(Object.values(CATEGORIES));
+
+function valuesFor(args, index, option) {
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith("-")) throw new Error(`${option} requires a value`);
+  return [value, index + 1];
+}
+
+export function parseArgs(args = []) {
+  const languageValues = [];
+  const categoryValues = [];
+  const includes = [];
+  const excludes = [];
+  const paths = [];
+  let format = "json";
+  let debug = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === "--debug") debug = true;
+    else if (argument === "--help" || argument === "-h") return { help: true };
+    else if (argument === "--version" || argument === "-v") return { version: true };
+    else if (["--language", "--languages"].includes(argument)) {
+      const [value, next] = valuesFor(args, index, argument); languageValues.push(value); index = next;
+    } else if (argument === "--categories") {
+      const [value, next] = valuesFor(args, index, argument); categoryValues.push(value); index = next;
+    } else if (["--include", "--exclude"].includes(argument)) {
+      const [value, next] = valuesFor(args, index, argument); (argument === "--include" ? includes : excludes).push(value); index = next;
+    } else if (argument === "--format") {
+      const [value, next] = valuesFor(args, index, argument); format = value.toLowerCase(); index = next;
+    } else if (argument.startsWith("-")) throw new Error(`unknown option ${argument}`);
+    else paths.push(argument);
+  }
+  if (!["json", "text"].includes(format)) throw new Error(`unsupported format ${JSON.stringify(format)}`);
+  const categories = categoryValues.flatMap((value) => String(value).split(",").map((item) => item.trim().toLowerCase())).filter(Boolean);
+  for (const category of categories) if (!categoryNames.has(category)) throw new Error(`unsupported category ${JSON.stringify(category)}`);
+  return { paths: paths.length ? paths : ["."], languages: parseSelection(languageValues), categories: new Set(categories.length ? categories : DEFAULT_CATEGORIES), includes, excludes, format, debug };
+}
+
+export function exitStatus(findings, error = null) {
+  return error ? 2 : findings.length ? 1 : 0;
+}

package/src/discovery.js

@@ -0,0 +1,96 @@
+import { promises as fs } from "node:fs";
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { lookup } from "./languages.js";
+
+const execFileAsync = promisify(execFile);
+const skippedDirectories = new Set([".git", "node_modules", "vendor", "dist", "build", "coverage"]);
+
+export function normalizePath(value) { return String(value).replaceAll("\\", "/"); }
+
+export function globToRegExp(pattern) {
+  let expression = "^";
+  const normalized = normalizePath(pattern);
+  for (let index = 0; index < normalized.length; index += 1) {
+    const character = normalized[index];
+    if (character === "*" && normalized[index + 1] === "*") {
+      if (normalized[index + 2] === "/") { expression += "(?:.*/)?"; index += 2; }
+      else { expression += ".*"; index += 1; }
+    } else if (character === "*") expression += "[^/]*";
+    else if (character === "?") expression += "[^/]";
+    else expression += /[.+^${}()|[\]\\]/.test(character) ? `\\${character}` : character;
+  }
+  return new RegExp(`${expression}$`);
+}
+
+function matches(relativePath, patterns) { return patterns.length === 0 || patterns.some((pattern) => globToRegExp(pattern).test(relativePath)); }
+function excluded(relativePath, patterns) { return patterns.some((pattern) => globToRegExp(pattern).test(relativePath)); }
+function display(filePath, cwd) { return normalizePath(path.relative(cwd, filePath) || path.basename(filePath)); }
+
+async function walk(directory, cwd, options, diagnostics) {
+  const entries = await fs.readdir(directory, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = path.join(directory, entry.name);
+    const relative = display(fullPath, cwd);
+    if (entry.isSymbolicLink()) { diagnostics.push({ path: relative, reason: "symbolic link" }); continue; }
+    if (entry.isDirectory()) {
+      if (skippedDirectories.has(entry.name)) diagnostics.push({ path: relative, reason: "fixed directory exclusion" });
+      else files.push(...await walk(fullPath, cwd, options, diagnostics));
+      continue;
+    }
+    const language = lookup(fullPath);
+    if (!entry.isFile() || !language) { if (entry.isFile()) diagnostics.push({ path: relative, reason: "unsupported file" }); continue; }
+    if (!matches(relative, options.includes || [])) { diagnostics.push({ path: relative, reason: "not included" }); continue; }
+    if (excluded(relative, options.excludes || [])) { diagnostics.push({ path: relative, reason: "excluded" }); continue; }
+    if (options.languages?.size && !options.languages.has(language)) { diagnostics.push({ path: relative, reason: "language filter" }); continue; }
+    files.push({ path: fullPath, relative, language });
+  }
+  return files;
+}
+
+async function tracked(cwd) {
+  const { stdout: rootOutput } = await execFileAsync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  const repositoryRoot = path.resolve(rootOutput.trim());
+  const { stdout } = await execFileAsync("git", ["-C", repositoryRoot, "ls-files", "--cached", "--others", "--exclude-standard", "-z"], { encoding: "utf8" });
+  return stdout.split("\0").filter(Boolean).map((file) => path.resolve(repositoryRoot, file));
+}
+
+export async function discover(inputPaths = [], options = {}) {
+  const cwd = await fs.realpath(path.resolve(options.cwd || process.cwd()));
+  const diagnostics = [];
+  const candidates = [];
+  const paths = inputPaths.length ? inputPaths : null;
+  if (!paths) {
+    try {
+      for (const fullPath of await tracked(cwd)) {
+        const language = lookup(fullPath); const relative = display(fullPath, cwd);
+        if (!language || relative.split("/").some((part) => skippedDirectories.has(part))) continue;
+        if (matches(relative, options.includes || []) && !excluded(relative, options.excludes || []) && (!options.languages?.size || options.languages.has(language))) candidates.push({ path: fullPath, relative, language });
+        else diagnostics.push({ path: relative, reason: "selection filter" });
+      }
+    } catch { candidates.push(...await walk(cwd, cwd, options, diagnostics)); }
+  } else {
+    for (const input of paths) {
+      const fullPath = path.resolve(cwd, input);
+      try {
+        const stats = await fs.lstat(fullPath);
+        if (stats.isDirectory()) candidates.push(...await walk(fullPath, cwd, options, diagnostics));
+        else if (stats.isFile()) {
+          const language = lookup(fullPath); const relative = display(fullPath, cwd);
+          if (!language) diagnostics.push({ path: relative, reason: "unsupported file" });
+          else if (!matches(relative, options.includes || [])) diagnostics.push({ path: relative, reason: "not included" });
+          else if (excluded(relative, options.excludes || [])) diagnostics.push({ path: relative, reason: "excluded" });
+          else if (options.languages?.size && !options.languages.has(language)) diagnostics.push({ path: relative, reason: "language filter" });
+          else candidates.push({ path: fullPath, relative, language });
+        }
+      } catch (error) { throw new Error(`${input}: ${error.message}`); }
+    }
+  }
+  const unique = [...new Map(candidates.map((candidate) => [path.resolve(candidate.path), candidate])).values()];
+  unique.sort((left, right) => left.relative.localeCompare(right.relative));
+  return { candidates: unique, diagnostics, skipped: diagnostics.length };
+}
+
+export { skippedDirectories };

package/src/hook-launcher.js

@@ -0,0 +1,18 @@
+import { runHook as evaluateHookInput } from "./hook.js";
+
+async function runHook(mode, options = {}) {
+  return evaluateHookInput(options.input || process.stdin, mode, options.output || process.stdout);
+}
+
+async function main(modeOverride) {
+  const modeArgumentIndex = process.argv.indexOf("--mode");
+  const requestedMode = modeArgumentIndex >= 0 ? process.argv[modeArgumentIndex + 1] : process.argv[2];
+  const mode = modeOverride || requestedMode || "hard";
+  if (mode !== "hard" && mode !== "warn") {
+    process.stdout.write(JSON.stringify({ decision: "block", reason: `ban-code-comments hook launcher failed: unsupported hook mode ${mode}` }) + "\n");
+    return 0;
+  }
+  return runHook(mode);
+}
+
+export { main, runHook };

package/src/hook.js

@@ -0,0 +1,149 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { lookup } from "./languages.js";
+import { CATEGORIES } from "./model.js";
+import { scanSource } from "./scanner.js";
+
+const tools = new Set(["apply_patch", "edit", "write", "write_file", "file_write"]);
+const selected = new Set([CATEGORIES.ORDINARY, CATEGORIES.DOCUMENTATION]);
+
+function errorResponse(mode, code, message) {
+  const text = `ban-code-comments hook operational error (${code}): ${message}`;
+  return mode === "hard" ? { decision: "block", reason: text } : { systemMessage: text };
+}
+
+function resolve(root, name) {
+  const normalized = String(name || "").trim().replaceAll("\\", "/").replace(new RegExp("^(?:a|b)/"), "");
+  if (!normalized) throw new Error(`invalid proposed path ${JSON.stringify(name || "")}`);
+  const target = path.isAbsolute(normalized) ? path.normalize(normalized) : path.resolve(root, normalized);
+  const relative = path.relative(root, target);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`proposed path escapes workspace: ${JSON.stringify(name)}`);
+  return target;
+}
+
+function display(root, name) { return path.relative(root, resolve(root, name)).replaceAll(path.sep, "/"); }
+
+function stringValue(input, ...keys) { for (const key of keys) if (typeof input?.[key] === "string") return input[key]; return ""; }
+
+function parsePatch(patch) {
+  const lines = String(patch).replaceAll("\r\n", "\n").split("\n");
+  let index = lines[0]?.trim() === "*** Begin Patch" ? 1 : 0;
+  const changes = [];
+  while (index < lines.length) {
+    const line = lines[index];
+    if (!line || line.trim() === "*** End Patch") { index += 1; continue; }
+    if (line.startsWith("*** Add File: ")) {
+      const body = collectBody(lines, index + 1); changes.push({ path: line.slice(14), source: body.lines.filter((item) => item.startsWith("+")).map((item) => item.slice(1)).join("\n") }); index = body.next; continue;
+    }
+    if (line.startsWith("*** Delete File: ")) { changes.push({ path: line.slice(17), delete: true }); index += 1; continue; }
+    if (line.startsWith("*** Update File: ")) {
+      const body = collectBody(lines, index + 1); let newPath = ""; let patchLines = body.lines;
+      if (patchLines[0]?.startsWith("*** Move to: ")) { newPath = patchLines[0].slice(13); patchLines = patchLines.slice(1); }
+      changes.push({ path: line.slice(17), newPath, patchLines }); index = body.next; continue;
+    }
+    throw new Error(`unsupported patch line ${JSON.stringify(line)}`);
+  }
+  return changes;
+}
+
+function collectBody(lines, start) {
+  let next = start;
+  while (next < lines.length && !/^(?:\*\*\* (?:Add|Delete|Update) File:|\*\*\* End Patch)/.test(lines[next])) next += 1;
+  return { lines: lines.slice(start, next), next };
+}
+
+function reconstruct(raw) {
+  if (raw === undefined || raw === null) throw new Error("hook event has no tool input");
+  if (typeof raw === "string") return parsePatch(raw);
+  if (typeof raw !== "object" || Array.isArray(raw)) throw new Error("tool input is not an object");
+  const patch = stringValue(raw, "patch", "input", "command");
+  if (patch.trimStart().startsWith("*** Begin Patch")) return parsePatch(patch);
+  const filePath = stringValue(raw, "path", "file_path", "filePath", "filename");
+  if (!filePath) throw new Error("tool input does not identify a file");
+  for (const key of ["content", "new_content", "newContent"]) if (typeof raw[key] === "string") return [{ path: filePath, source: raw[key] }];
+  const oldText = stringValue(raw, "old_string", "oldString");
+  const newText = stringValue(raw, "new_string", "newString");
+  if (Object.hasOwn(raw, "old_string") || Object.hasOwn(raw, "oldString")) return [{ path: filePath, oldText, newText }];
+  throw new Error("tool input does not contain proposed file content");
+}
+
+function applyPatch(source, patchLines) {
+  const finalNewline = source.endsWith("\n");
+  const oldLines = source.replace(/\n$/, "").split("\n");
+  if (oldLines.length === 1 && oldLines[0] === "") oldLines.length = 0;
+  const output = []; let cursor = 0; let changed = false; let hunk = [];
+  const flush = () => {
+    const operations = hunk.filter((line) => line && !line.startsWith("@@") && line !== "\");
+    if (!operations.length) return;
+    const oldBlock = operations.filter((line) => line[0] === " " || line[0] === "-").map((line) => line.slice(1));
+    const newBlock = operations.filter((line) => line[0] === " " || line[0] === "+").map((line) => line.slice(1));
+    if (operations.some((line) => ![" ", "+", "-"].includes(line[0]))) throw new Error(`unsupported hunk line ${JSON.stringify(operations.find((line) => ![" ", "+", "-"].includes(line[0])))}`);
+    let match = -1;
+    for (let candidate = cursor; candidate + oldBlock.length <= oldLines.length; candidate += 1) if (oldLines.slice(candidate, candidate + oldBlock.length).every((line, i) => line === oldBlock[i])) { match = candidate; break; }
+    if (match < 0) throw new Error("hunk context was not found");
+    output.push(...oldLines.slice(cursor, match), ...newBlock); cursor = match + oldBlock.length; changed = true;
+  };
+  for (const line of patchLines) { if (line.startsWith("@@")) { flush(); hunk = []; } hunk.push(line); }
+  flush();
+  if (!changed) throw new Error("patch contains no file operations");
+  output.push(...oldLines.slice(cursor));
+  return output.join("\n") + (finalNewline ? "\n" : "");
+}
+
+function difference(before, after) {
+  const counts = new Map();
+  for (const item of before) { const key = `${item.language}\0${item.category}\0${item.text}`; counts.set(key, (counts.get(key) || 0) + 1); }
+  return after.filter((item) => { const key = `${item.language}\0${item.category}\0${item.text}`; const count = counts.get(key) || 0; if (count) { counts.set(key, count - 1); return false; } return true; });
+}
+
+async function findingsFor(root, filePath, source) {
+  const language = lookup(filePath);
+  return language ? scanSource(source, display(root, filePath), language, selected) : [];
+}
+
+async function evaluate(root, changes) {
+  const findings = [];
+  for (const change of changes) {
+    const oldPath = resolve(root, change.path);
+    let oldSource = "";
+    try { oldSource = await fs.readFile(oldPath, "utf8"); } catch (error) { if (error.code !== "ENOENT") throw error; }
+    let newSource = change.source;
+    if (change.oldText !== undefined) { if (!oldSource.includes(change.oldText)) throw new Error(`proposed edit could not find old text in ${change.path}`); newSource = oldSource.replace(change.oldText, change.newText); }
+    if (change.patchLines?.length) newSource = applyPatch(oldSource, change.patchLines);
+    if (change.delete) newSource = "";
+    const newPath = change.newPath ? resolve(root, change.newPath) && change.newPath : change.path;
+    findings.push(...difference(await findingsFor(root, change.path, oldSource), await findingsFor(root, newPath, newSource)));
+  }
+  return findings;
+}
+
+function formatFindings(findings) {
+  return `ban-code-comments found newly introduced comments: ${[...findings].sort((a, b) => a.path.localeCompare(b.path) || a.range.start.line - b.range.start.line || a.range.start.column - b.range.start.column).map((item) => `${item.path}:${item.range.start.line}:${item.range.start.column} [${item.category}] ${item.text.trim()}`).join("; ")}`;
+}
+
+function findingResponse(mode, findings) {
+  if (!findings.length) return {};
+  const reason = formatFindings(findings);
+  if (mode === "hard") return { decision: "block", reason };
+  const guidance = `${reason} Use Git history for history, pull-request descriptions for rationale, simplified code or a nearby README for complexity, and Markdown for general documentation.`;
+  return { systemMessage: guidance, hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: guidance } };
+}
+
+export async function evaluateHook(event, mode = "hard") {
+  if (mode !== "hard" && mode !== "warn") return errorResponse(mode, "invalid_mode", `unsupported hook mode ${JSON.stringify(mode)}`);
+  const eventName = String(event?.hook_event_name || "").trim().toLowerCase().replaceAll("_", "");
+  const toolName = String(event?.tool_name || "").trim().toLowerCase();
+  if (eventName !== "pretooluse" || !tools.has(toolName)) return {};
+  const root = path.resolve(event.cwd || process.cwd());
+  try { return findingResponse(mode, await evaluate(root, reconstruct(event.tool_input))); }
+  catch (error) { return errorResponse(mode, "proposal_unreadable", error.message); }
+}
+
+export async function runHook(input, mode = "hard", output = process.stdout) {
+  let event;
+  try { event = JSON.parse(input); } catch (error) { output.write(`${JSON.stringify(errorResponse(mode, "invalid_event", `could not decode hook event: ${error.message}`))}\n`); return 0; }
+  output.write(`${JSON.stringify(await evaluateHook(event, mode))}\n`);
+  return 0;
+}
+
+export { applyPatch, formatFindings, parsePatch, reconstruct, resolve };

package/src/index.js

@@ -0,0 +1,33 @@
+import * as core from "@actions/core";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { cliArguments } from "./inputs.js";
+import { runCLI } from "./cli-runner.js";
+
+async function main(dependencies = {}) {
+  const coreAPI = dependencies.core || core;
+  const execute = dependencies.run || ((args, options) => runCLI(args, options));
+  const inputs = {
+    paths: coreAPI.getInput("paths"),
+    languages: coreAPI.getInput("languages"),
+    categories: coreAPI.getInput("categories"),
+    include: coreAPI.getInput("include"),
+    exclude: coreAPI.getInput("exclude"),
+    format: coreAPI.getInput("format") || "json",
+    debug: coreAPI.getInput("debug") || "false",
+  };
+  return execute(cliArguments(inputs), { cwd: process.env.GITHUB_WORKSPACE || process.cwd() });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  main()
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((error) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 2;
+    });
+}
+
+export { main };

package/src/inputs.js

@@ -0,0 +1,36 @@
+function nonEmptyLines(value) {
+  return String(value || "")
+    .split(/\r?\n/)
+    .filter((line) => line.length > 0);
+}
+
+function addRepeated(args, flag, value) {
+  for (const item of nonEmptyLines(value)) {
+    args.push(flag, item);
+  }
+}
+
+function parseBoolean(value) {
+  const normalized = String(value || "false").toLowerCase();
+  if (normalized === "true") return true;
+  if (normalized === "false" || normalized === "") return false;
+  throw new Error(`invalid boolean input for debug: ${value}`);
+}
+
+function cliArguments(inputs) {
+  const args = [];
+  const paths = nonEmptyLines(inputs.paths);
+  addRepeated(args, "--languages", inputs.languages);
+  if (inputs.categories) {
+    const categories = nonEmptyLines(inputs.categories).join(",");
+    if (categories) args.push("--categories", categories);
+  }
+  addRepeated(args, "--include", inputs.include);
+  addRepeated(args, "--exclude", inputs.exclude);
+  args.push("--format", inputs.format || "json");
+  if (parseBoolean(inputs.debug)) args.push("--debug");
+  args.push(...(paths.length > 0 ? paths : ["."]));
+  return args;
+}
+
+export { cliArguments, nonEmptyLines, parseBoolean };

package/src/languages.js

@@ -0,0 +1,47 @@
+const extensionLanguages = new Map([
+  [".go", "go"], [".js", "javascript"], [".jsx", "javascript"], [".mjs", "javascript"], [".cjs", "javascript"],
+  [".ts", "typescript"], [".tsx", "typescript"], [".mts", "typescript"], [".cts", "typescript"],
+  [".py", "python"], [".pyw", "python"], [".rs", "rust"], [".java", "java"],
+  [".c", "c"], [".h", "c"], [".cc", "cpp"], [".cpp", "cpp"], [".cxx", "cpp"], [".hh", "cpp"], [".hpp", "cpp"], [".hxx", "cpp"],
+  [".cs", "csharp"], [".kt", "kotlin"], [".kts", "kotlin"], [".swift", "swift"], [".rb", "ruby"], [".rake", "ruby"], [".php", "php"],
+  [".sh", "shell"], [".bash", "shell"], [".zsh", "shell"], [".fish", "shell"], [".ksh", "shell"], [".csh", "shell"], [".sql", "sql"],
+  [".html", "html"], [".htm", "html"], [".xhtml", "html"], [".xml", "xml"], [".svg", "xml"], [".css", "css"], [".scss", "scss"], [".sass", "scss"],
+  [".yaml", "yaml"], [".yml", "yaml"], [".toml", "toml"], [".json", "json"], [".jsonc", "jsonc"], [".hcl", "hcl"], [".tf", "terraform"], [".tfvars", "terraform"],
+  [".mk", "makefile"], [".mak", "makefile"], [".ini", "ini"], [".cfg", "ini"], [".conf", "ini"],
+]);
+
+const specialLanguages = new Map([["dockerfile", "dockerfile"], ["makefile", "makefile"]]);
+
+const aliases = new Map([
+  ["c++", "cpp"], ["c#", "csharp"], ["cs", "csharp"], ["js", "javascript"], ["jsx", "javascript"], ["ts", "typescript"], ["tsx", "typescript"],
+  ["sh", "shell"], ["bash", "shell"], ["hcl", "hcl"], ["tf", "terraform"],
+]);
+
+export function lookup(filePath) {
+  const normalized = String(filePath).replaceAll("\\", "/").toLowerCase();
+  const base = normalized.slice(normalized.lastIndexOf("/") + 1);
+  if (specialLanguages.has(base)) return specialLanguages.get(base);
+  const dot = base.lastIndexOf(".");
+  return extensionLanguages.get(dot < 0 ? "" : base.slice(dot)) || null;
+}
+
+export function supported() {
+  return [...new Set([...extensionLanguages.values(), ...specialLanguages.values()])].sort();
+}
+
+export function parseSelection(values = []) {
+  const selection = new Set();
+  for (const value of values) {
+    for (const raw of String(value).split(",")) {
+      const name = raw.trim().toLowerCase();
+      if (!name) continue;
+      const language = aliases.get(name) || name;
+      if (!supported().includes(language)) throw new Error(`unsupported language ${JSON.stringify(raw.trim())}`);
+      selection.add(language);
+    }
+  }
+  return selection;
+}
+
+export const extensions = Object.freeze(Object.fromEntries(extensionLanguages));
+export const languageAliases = Object.freeze(Object.fromEntries(aliases));

package/src/launcher-entry.js

@@ -0,0 +1,9 @@
+import { main } from "./hook-launcher.js";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  main().then((code) => {
+    process.exitCode = code;
+  });
+}

package/src/model.js

@@ -0,0 +1,39 @@
+export const CATEGORIES = Object.freeze({
+  ORDINARY: "ordinary",
+  DOCUMENTATION: "documentation",
+  HEADER: "header",
+  DIRECTIVE: "directive",
+});
+
+export const DEFAULT_CATEGORIES = Object.freeze([
+  CATEGORIES.ORDINARY,
+  CATEGORIES.DOCUMENTATION,
+]);
+
+export function position(line, column) {
+  return { line, column };
+}
+
+export function sourceRange(start, end) {
+  return { start, end };
+}
+
+export function finding(path, language, category, range, text) {
+  return { path, language, category, range, text };
+}
+
+export function result(findings = [], summary = {}) {
+  return {
+    findings,
+    summary: {
+      files_scanned: summary.files_scanned ?? 0,
+      files_skipped: summary.files_skipped ?? 0,
+      findings: summary.findings ?? findings.length,
+    },
+  };
+}
+
+export function exitCode(findings = [], error = null) {
+  if (error) return 2;
+  return findings.length > 0 ? 1 : 0;
+}

package/src/report.js

@@ -0,0 +1,7 @@
+export function renderJSON(result) {
+  return `${JSON.stringify(result)}\n`;
+}
+
+export function renderText(result) {
+  return result.findings.map((item) => `${item.path}:${item.range.start.line}:${item.range.start.column}: ${item.text}`).join("\n") + (result.findings.length ? "\n" : "");
+}

package/src/scanner.js

@@ -0,0 +1,241 @@
+import { CATEGORIES, finding, position, sourceRange } from "./model.js";
+
+const syntax = {
+  c: { line: ["//"], block: [["/*", "*/"]] }, cpp: { line: ["//"], block: [["/*", "*/"]] }, csharp: { line: ["//"], block: [["/*", "*/"]] },
+  go: { line: ["//"], block: [["/*", "*/"]] }, java: { line: ["//"], block: [["/*", "*/"]] }, javascript: { line: ["//"], block: [["/*", "*/"]] },
+  jsonc: { line: ["//"], block: [["/*", "*/"]] }, kotlin: { line: ["//"], block: [["/*", "*/"]] }, rust: { line: ["//"], block: [["/*", "*/"]] }, swift: { line: ["//"], block: [["/*", "*/"]] },
+  typescript: { line: ["//"], block: [["/*", "*/"]] }, php: { line: ["//", "#"], block: [["/*", "*/"]] },
+  python: { line: ["#"] }, ruby: { line: ["#"] }, shell: { line: ["#"] }, yaml: { line: ["#"] }, toml: { line: ["#"] }, dockerfile: { line: ["#"] }, makefile: { line: ["#"] },
+  ini: { line: ["#", ";"] }, sql: { line: ["--", "#"], block: [["/*", "*/"]] }, html: { block: [["<!--", "-->"]] }, xml: { block: [["<!--", "-->"]] },
+  css: { block: [["/*", "*/"]] }, scss: { line: ["//"], block: [["/*", "*/"]] }, hcl: { line: ["#", "//"], block: [["/*", "*/"]] }, terraform: { line: ["#", "//"], block: [["/*", "*/"]] },
+  json: { line: [], block: [] },
+};
+
+function lineColumn(source, offset) {
+  const prefix = source.slice(0, offset);
+  const line = (prefix.match(/\n/g) || []).length + 1;
+  const lastBreak = Math.max(prefix.lastIndexOf("\n"), prefix.lastIndexOf("\r"));
+  return position(line, offset - lastBreak);
+}
+
+function escaped(source, offset) {
+  let count = 0;
+  for (let index = offset - 1; index >= 0 && source[index] === "\\"; index -= 1) count += 1;
+  return count % 2 === 1;
+}
+
+function classify(text) {
+  const trimmed = text.trim();
+  const lower = trimmed.toLowerCase();
+  if (trimmed.startsWith("///") || trimmed.startsWith("//!") || trimmed.startsWith("/**") || trimmed.startsWith("<!---")) return CATEGORIES.DOCUMENTATION;
+  if (trimmed.startsWith("#!") || lower.startsWith("# syntax=") || lower.startsWith("# escape=")) return CATEGORIES.DIRECTIVE;
+  if (["go:", "cgo", "eslint", "ts-ignore", "ts-expect-error", "prettier-ignore", "nolint", "noinspection", "shellcheck", "yamllint", "yaml-language-server", "coding:", "type: ignore", "swift-tools-version", "region", "endregion"].some((marker) => lower.includes(marker))) return CATEGORIES.DIRECTIVE;
+  if (["copyright", "spdx-license", "licensed", "license", "generated by", "code generated", "auto-generated"].some((marker) => lower.includes(marker))) return CATEGORIES.HEADER;
+  return CATEGORIES.ORDINARY;
+}
+
+function addFinding(findings, source, filePath, language, start, end, categories) {
+  const text = source.slice(start, end).replace(/[\r\n]+$/, "");
+  if (!text) return;
+  const category = classify(text);
+  if (!categories.has(category)) return;
+  findings.push(finding(filePath, language, category, sourceRange(lineColumn(source, start), lineColumn(source, start + text.length)), text));
+}
+
+function skipQuoted(source, index, quote) {
+  for (let cursor = index + quote.length; cursor < source.length; cursor += 1) {
+    if (source.startsWith(quote, cursor) && !escaped(source, cursor)) return cursor + quote.length;
+    if (source[cursor] === "\n" && quote !== "`" && quote !== "'''" && quote !== '"""') return cursor;
+  }
+  return source.length;
+}
+
+function skipDelimited(source, index, opener, closer, nested = false) {
+  let depth = 1;
+  for (let cursor = index + opener.length; cursor < source.length;) {
+    if (nested && source.startsWith(opener, cursor)) { depth += 1; cursor += opener.length; continue; }
+    if (source.startsWith(closer, cursor)) { depth -= 1; cursor += closer.length; if (depth === 0) return cursor; continue; }
+    cursor += 1;
+  }
+  return source.length;
+}
+
+function skipRawString(source, index, language) {
+  if (language === "cpp" && source[index] === "R" && source[index + 1] === '"') {
+    const open = source.indexOf("(", index + 2);
+    if (open >= 0 && open - index <= 16) {
+      const delimiter = source.slice(index + 2, open);
+      if (!/[\s()\\]/.test(delimiter)) {
+        const close = source.indexOf(`)${delimiter}"`, open + 1);
+        return close < 0 ? source.length : close + delimiter.length + 2;
+      }
+    }
+  }
+  if (language !== "rust" || !/[rR]/.test(source[index] || "")) return null;
+  const match = source.slice(index).match(/^[rR](#+)"/);
+  if (!match) return null;
+  const close = source.indexOf(`"${match[1]}`, index + match[0].length);
+  return close < 0 ? source.length : close + match[1].length + 1;
+}
+
+function skipHashString(source, index, language) {
+  if (language !== "swift" || source[index] !== "#") return null;
+  const hashes = source.slice(index).match(/^#+(?=")/)?.[0];
+  if (!hashes) return null;
+  const opening = `${hashes}"`;
+  const close = source.indexOf(`"${hashes}`, index + opening.length);
+  return close < 0 ? source.length : close + hashes.length + 1;
+}
+
+function skipCSharpRawString(source, index, language) {
+  if (language !== "csharp" || source[index] !== '"') return null;
+  const opening = source.slice(index).match(/^"{3,}/)?.[0];
+  if (!opening) return null;
+  const close = source.slice(index + opening.length).match(/"+/g);
+  if (!close) return source.length;
+  let cursor = index + opening.length;
+  for (const run of close) {
+    cursor = source.indexOf(run, cursor);
+    if (run.length >= opening.length) return cursor + run.length;
+    cursor += run.length;
+  }
+  return source.length;
+}
+
+function stringAt(source, index, language) {
+  const raw = skipRawString(source, index, language) ?? skipHashString(source, index, language) ?? skipCSharpRawString(source, index, language);
+  if (raw !== null) return raw;
+  for (const quote of ["'''", '"""']) if (source.startsWith(quote, index)) return skipQuoted(source, index, quote);
+  if (language === "csharp" && (source.startsWith('@"', index) || source.startsWith('$@"', index) || source.startsWith('@$"', index))) return skipQuoted(source, index + (source[index] === "$" ? 2 : 1), '"');
+  if (language === "javascript" || language === "typescript") {
+    if (source[index] === "`" || source[index] === '"' || source[index] === "'") return skipQuoted(source, index, source[index]);
+  }
+  if (source[index] === '"' || source[index] === "'") return skipQuoted(source, index, source[index]);
+  return null;
+}
+
+function lineEnd(source, index) {
+  const end = source.slice(index).search(/[\r\n]/);
+  return end < 0 ? source.length : index + end;
+}
+
+function lineStart(source, index) { return index === 0 || source[index - 1] === "\n" || source[index - 1] === "\r"; }
+
+function heredocEnd(source, index, marker, stripTabs = false) {
+  let cursor = lineEnd(source, index);
+  while (cursor < source.length) {
+    cursor += 1;
+    const end = lineEnd(source, cursor);
+    let value = source.slice(cursor, end).replace(/\r$/, "");
+    if (stripTabs) value = value.replace(/^\t+/, "");
+    if (value === marker) return end < source.length ? end + 1 : end;
+    cursor = end;
+  }
+  return source.length;
+}
+
+function skipShellHeredocs(source, index) {
+  const line = source.slice(index, lineEnd(source, index));
+  const markers = [];
+  for (let cursor = 0; cursor < line.length; cursor += 1) {
+    if (line[cursor] === "\\") { cursor += 1; continue; }
+    if (line[cursor] === "'" || line[cursor] === '"') {
+      const quote = line[cursor]; cursor += 1;
+      while (cursor < line.length && line[cursor] !== quote) { if (line[cursor] === "\\" && quote === '"') cursor += 1; cursor += 1; }
+      continue;
+    }
+    if (!line.startsWith("<<", cursor)) continue;
+    cursor += 2;
+    const stripTabs = line[cursor] === "-";
+    if (stripTabs) cursor += 1;
+    while (/\s/.test(line[cursor] || "")) cursor += 1;
+    let marker = "";
+    if (line[cursor] === "'" || line[cursor] === '"') {
+      const quote = line[cursor++];
+      while (cursor < line.length && line[cursor] !== quote) marker += line[cursor++];
+      cursor += 1;
+    } else {
+      while (cursor < line.length && !/[\s;|&<>]/.test(line[cursor])) marker += line[cursor++];
+    }
+    if (marker) markers.push({ marker: marker.replaceAll("\\", ""), stripTabs });
+  }
+  if (!markers.length) return null;
+  let cursor = index;
+  for (const item of markers) cursor = heredocEnd(source, cursor, item.marker, item.stripTabs);
+  return cursor;
+}
+
+function skipYamlBlock(source, index) {
+  const line = source.slice(index, lineEnd(source, index));
+  if (!/[:]\s*[|>][-+]?\s*(?:#.*)?$/.test(line)) return null;
+  const indent = (line.match(/^ */) || [""])[0].length;
+  let cursor = lineEnd(source, index);
+  while (cursor < source.length) {
+    cursor += 1;
+    const end = lineEnd(source, cursor);
+    const candidate = source.slice(cursor, end);
+    if (candidate.trim() && (candidate.match(/^ */) || [""])[0].length <= indent) return cursor;
+    cursor = end;
+  }
+  return source.length;
+}
+
+function skipPhpHeredoc(source, index) {
+  const match = source.slice(index).match(/^<<<\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/);
+  if (!match) return null;
+  let cursor = lineEnd(source, index);
+  while (cursor < source.length) {
+    cursor += 1;
+    const end = lineEnd(source, cursor);
+    const value = source.slice(cursor, end).trim().replace(/;$/, "");
+    if (value === match[2]) return end < source.length ? end + 1 : end;
+    cursor = end;
+  }
+  return source.length;
+}
+
+export function scanSource(source, filePath = "<text>", language, categories = new Set([CATEGORIES.ORDINARY, CATEGORIES.DOCUMENTATION])) {
+  const spec = syntax[language];
+  if (!spec) return [];
+  const findings = [];
+  let index = 0;
+  while (index < source.length) {
+    if (lineStart(source, index)) {
+      if (language === "shell") { const end = skipShellHeredocs(source, index); if (end !== null) { index = end; continue; } }
+      if (language === "yaml") {
+        const end = skipYamlBlock(source, index);
+        if (end !== null) {
+          const currentEnd = lineEnd(source, index);
+          const indicator = source.slice(index, currentEnd);
+          const comment = indicator.indexOf("#");
+          if (comment >= 0) addFinding(findings, source, filePath, language, index + comment, currentEnd, categories);
+          index = end;
+          continue;
+        }
+      }
+      if (language === "ruby" && source.startsWith("=begin", index)) { const end = source.indexOf("\n=end", index + 6); addFinding(findings, source, filePath, language, index, end < 0 ? source.length : end + 6, categories); index = end < 0 ? source.length : end + 6; continue; }
+    }
+    if (language === "php") { const end = skipPhpHeredoc(source, index); if (end !== null) { index = end; continue; } }
+    const stringEnd = stringAt(source, index, language);
+    if (stringEnd !== null) { index = stringEnd; continue; }
+    let matched = false;
+    for (const [start, endMarker] of spec.block || []) if (source.startsWith(start, index)) {
+      const end = skipDelimited(source, index, start, endMarker, language === "rust");
+      addFinding(findings, source, filePath, language, index, end, categories);
+      index = end; matched = true; break;
+    }
+    if (matched) continue;
+    for (const marker of spec.line || []) if (source.startsWith(marker, index)) {
+      const previous = source[index - 1];
+      if ((language === "shell" || language === "yaml") && marker === "#" && previous && !/[\s;]/.test(previous)) continue;
+      if (language === "sql" && marker === "#" && ([">", "<", "-"].includes(previous) || [">", "<"].includes(source[index + 1]))) continue;
+      const newline = source.slice(index).search(/[\r\n]/);
+      addFinding(findings, source, filePath, language, index, newline < 0 ? source.length : index + newline, categories);
+      index = newline < 0 ? source.length : index + newline; matched = true; break;
+    }
+    if (!matched) index += 1;
+  }
+  return findings;
+}
+
+export { classify, lineColumn, syntax };

package/src/version.js

@@ -0,0 +1 @@
+export const CLI_VERSION = "1.0.2";