FWD » Build and Source Control

#!/usr/bin/env python3

"""FWD Algorithmic Code-Style Checker.

Algorithmic code-style checker for FWD code reviews. Parses a bzr unified

diff, reads the new-version sources from the working copy, and emits

Textile-formatted style findings derived from the gcd-code-style skill.

Supplement to the LLM review; all findings reference line numbers in the

new version of each source file.

Usage:

    fwd-style-check.py [-h] [--workdir PATH] [--out PATH]

                       [--list-rules] [--enable PATTERNS]

                       [--disable PATTERNS] [DIFF]

Positional arguments:

    DIFF               Path to a bzr unified diff file. Omit (or pass '-')

                       to read the diff from stdin. Default: stdin.

Options:

    -h, --help         Show this help message and exit.

    --workdir PATH     Working-copy directory containing the NEW version

                       of each changed file. Must match the '+++ new/...'

                       side of the diff. Default: current directory.

    --out PATH         Where to write the Textile report. Default: a

                       timestamped name in the current directory (e.g.

                       style-check_20260420-143022.textile). Parent

                       directories are created on demand.

    --list-rules       Print all registered rule IDs (with languages and

                       AST requirement) and exit.

    --enable PATTERNS  Comma-separated fnmatch patterns; only matching

                       rules run. Applied before --disable.

    --disable PATTERNS Comma-separated fnmatch patterns; matching rules

                       are skipped. Applied after --enable.

Examples:

    bzr diff | fwd-style-check.py

    fwd-style-check.py branch.diff

    fwd-style-check.py --workdir ./src --out review.textile branch.diff

    fwd-style-check.py --list-rules

    fwd-style-check.py --disable style.line-length,style.blank-* branch.diff

    fwd-style-check.py --enable 'style.hard-tab,style.cr-endings' branch.diff

Languages: .java, .js/.mjs, .ts/.tsx, .c, .cpp/.cc/.cxx, .h/.hpp/.hh/.hxx.

AST-driven rules require tree-sitter. Install with:

    pip install tree-sitter tree-sitter-language-pack

Without it, the checker runs in regex-only mode and notes it in the

report header.

Version: 2026-04-21

"""

import argparse

import fnmatch

import re

import sys

from collections import defaultdict, namedtuple

from datetime import date, datetime

from pathlib import Path

# ---- AST backend (optional) ----

_AST_PARSERS = None

_AST_ERROR = None

def _load_parsers():

   """Lazy-load tree-sitter parsers. Returns dict[language_name -> parser]

   or None if unavailable.

   """

   global _AST_PARSERS, _AST_ERROR

   if _AST_PARSERS is not None or _AST_ERROR is not None:

      return _AST_PARSERS

   try:

      from tree_sitter_language_pack import get_parser as _get

   except ImportError:

      try:

         from tree_sitter_languages import get_parser as _get

      except ImportError as e:

         _AST_ERROR = (

            "tree-sitter bundle not installed - AST-driven rules skipped. "

            "Install with: pip install tree-sitter tree-sitter-language-pack"

         )

         return None

   parsers = {}

   for lang_key in ("java", "javascript", "typescript", "c", "cpp"):

      try:

         parsers[lang_key] = _get(lang_key)

      except Exception as e:

         _AST_ERROR = f"tree-sitter parser for {lang_key} failed to load: {e}"

         return None

   _AST_PARSERS = parsers

   return _AST_PARSERS

# ---- Finding model ----

Finding = namedtuple("Finding", "file line severity rule_id message")

MAJOR_RULES = frozenset([

   "style.hard-tab",

   "style.cr-endings",

   "style.copyright-year",

   "style.file-history-sequence",

   "style.block-delimiter-required",

])

def _severity(rule_id):

   return "MAJOR" if rule_id in MAJOR_RULES else "MINOR"

# ---- Language dispatch ----

EXT_TO_LANG = {

   ".java": "java",

   ".js": "javascript",

   ".mjs": "javascript",

   ".ts": "typescript",

   ".tsx": "typescript",

   ".c": "c",

   ".cpp": "cpp",

   ".cc": "cpp",

   ".cxx": "cpp",

   ".h": "cpp",

   ".hpp": "cpp",

   ".hh": "cpp",

   ".hxx": "cpp",

}

def language_of(path):

   return EXT_TO_LANG.get(Path(path).suffix.lower())

# ---- Diff parsing ----

_RE_FILE_MARK = re.compile(

   r"^=== (modified|added|renamed) file '([^']+)'(?: => '([^']+)')?$"

)

_RE_HUNK = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@")

def parse_unified_diff(lines_iter):

   """Parse a bzr unified diff from an iterable of lines.

   Accepts any iterable yielding strings (e.g. an open text-mode file,

   sys.stdin, or a pre-split list). Each yielded line may or may not

   include a trailing newline.

   Returns dict[path -> dict]:

      {

         "added_linenos": set[int],   # 1-based new-file line numbers

         "added_ranges":  list[(start,end)],  # merged contiguous runs

      }

   """

   files = {}

   current_file = None

   current_line = 0

   in_hunk = False

   for raw in lines_iter:

      line = raw.rstrip("\n")

      m = _RE_FILE_MARK.match(line)

      if m:

         kind, first, second = m.group(1), m.group(2), m.group(3)

         path = second if kind == "renamed" and second else first

         current_file = path

         files.setdefault(path, {"added_linenos": set(), "added_ranges": []})

         in_hunk = False

         continue

      if line.startswith("--- ") or line.startswith("+++ "):

         in_hunk = False

         continue

      m = _RE_HUNK.match(line)

      if m and current_file is not None:

         current_line = int(m.group(1))

         in_hunk = True

         continue

      if not in_hunk or current_file is None:

         continue

      if line.startswith("+"):

         files[current_file]["added_linenos"].add(current_line)

         current_line += 1

      elif line.startswith("-"):

         pass  # deleted line; does not advance new-file counter

      elif line.startswith(" "):

         current_line += 1

      elif line.startswith("\\"):

         pass  # "\ No newline at end of file"

      else:

         # Blank line inside a hunk can still be a context line

         current_line += 1

   # Build merged ranges per file.

   for info in files.values():

      if not info["added_linenos"]:

         info["added_ranges"] = []

         continue

      sorted_lns = sorted(info["added_linenos"])

      ranges = []

      start = prev = sorted_lns[0]

      for ln in sorted_lns[1:]:

         if ln == prev + 1:

            prev = ln

         else:

            ranges.append((start, prev))

            start = prev = ln

      ranges.append((start, prev))

      info["added_ranges"] = ranges

   return files

def node_touches_diff(node, added_ranges):

   """True if node's line range overlaps any added range."""

   start = node.start_point[0] + 1

   end = node.end_point[0] + 1

   for s, e in added_ranges:

      if not (end < s or start > e):

         return True

   return False

# ---- Comment / string stripping (regex-based, language-agnostic enough) ----

def strip_code(source):

   """Return a same-length 'code skeleton' with string literals and

   comments replaced by spaces. Preserves positions so column numbers

   remain aligned with the original.

   Handles Java/JS/TS/C/C++ lexical elements: // comments, /* */ comments,

   " strings, ' chars, JS template literals (`...`). Not perfect (escapes

   and nested template substitutions), but adequate for line-local regex

   rules.

   """

   out = []

   i = 0

   n = len(source)

   state = "code"  # code | line_comment | block_comment | dstr | sstr | tstr

   while i < n:

      c = source[i]

      nxt = source[i + 1] if i + 1 < n else ""

      if state == "code":

         if c == "/" and nxt == "/":

            state = "line_comment"

            out.append("  ")

            i += 2

            continue

         if c == "/" and nxt == "*":

            state = "block_comment"

            out.append("  ")

            i += 2

            continue

         if c == '"':

            state = "dstr"

            out.append('"')

            i += 1

            continue

         if c == "'":

            state = "sstr"

            out.append("'")

            i += 1

            continue

         if c == "`":

            state = "tstr"

            out.append("`")

            i += 1

            continue

         out.append(c)

         i += 1

         continue

      if state == "line_comment":

         if c == "\n":

            state = "code"

            out.append("\n")

         else:

            out.append(" ")

         i += 1

         continue

      if state == "block_comment":

         if c == "*" and nxt == "/":

            state = "code"

            out.append("  ")

            i += 2

            continue

         out.append("\n" if c == "\n" else " ")

         i += 1

         continue

      if state in ("dstr", "sstr", "tstr"):

         quote = {"dstr": '"', "sstr": "'", "tstr": "`"}[state]

         if c == "\\" and nxt:

            out.append("  ")

            i += 2

            continue

         if c == quote:

            state = "code"

            out.append(quote)

            i += 1

            continue

         # Preserve newlines inside template literals; strings in Java/C

         # shouldn't span lines but be tolerant.

         out.append("\n" if c == "\n" else " ")

         i += 1

         continue

   return "".join(out)

# ---- Context passed to rules ----

class FileContext:

   def __init__(self, rel_path, full_path, source_bytes, language,

                added_linenos, added_ranges, tree, parse_errors):

      self.rel_path = rel_path

      self.full_path = full_path

      self.source_bytes = source_bytes

      self.source_text = source_bytes.decode("utf-8", errors="replace")

      self.source_lines = self.source_text.splitlines()

      self.code_text = strip_code(self.source_text)

      self.code_lines = self.code_text.splitlines()

      self.language = language

      self.added_linenos = added_linenos

      self.added_ranges = added_ranges

      self.tree = tree

      self.parse_errors = parse_errors

      self.today_year = date.today().year

# ---- Rule utilities ----

def code_line(ctx, lineno):

   """1-based code-skeleton line access; empty string on out-of-range."""

   idx = lineno - 1

   if 0 <= idx < len(ctx.code_lines):

      return ctx.code_lines[idx]

   return ""

def source_line(ctx, lineno):

   idx = lineno - 1

   if 0 <= idx < len(ctx.source_lines):

      return ctx.source_lines[idx]

   return ""

def visual_len(s):

   """Expand tabs to 3-space stops (project convention)."""

   out = 0

   for ch in s:

      if ch == "\t":

         out += 3 - (out % 3)

      else:

         out += 1

   return out

JAVA_KEYWORDS = frozenset([

   "abstract", "assert", "boolean", "break", "byte", "case", "catch",

   "char", "class", "const", "continue", "default", "do", "double",

   "else", "enum", "extends", "final", "finally", "float", "for", "goto",

   "if", "implements", "import", "instanceof", "int", "interface", "long",

   "native", "new", "package", "private", "protected", "public", "return",

   "short", "static", "strictfp", "super", "switch", "synchronized", "this",

   "throw", "throws", "transient", "try", "void", "volatile", "while",

   "yield", "var", "record", "sealed", "permits", "non-sealed",

])

JS_KEYWORDS = frozenset([

   "async", "await", "break", "case", "catch", "class", "const", "continue",

   "debugger", "default", "delete", "do", "else", "enum", "export", "extends",

   "false", "finally", "for", "function", "if", "import", "in", "instanceof",

   "let", "new", "null", "of", "return", "super", "switch", "this", "throw",

   "true", "try", "typeof", "var", "void", "while", "with", "yield",

   "interface", "public", "private", "protected", "static", "type",

])

C_KEYWORDS = frozenset([

   "auto", "break", "case", "char", "const", "continue", "default", "do",

   "double", "else", "enum", "extern", "float", "for", "goto", "if", "inline",

   "int", "long", "register", "restrict", "return", "short", "signed",

   "sizeof", "static", "struct", "switch", "typedef", "union", "unsigned",

   "void", "volatile", "while", "_Bool", "_Complex", "_Atomic",

   # C++ additions

   "class", "namespace", "template", "typename", "new", "delete", "this",

   "throw", "try", "catch", "public", "private", "protected", "virtual",

   "override", "final", "friend", "using", "operator", "explicit", "mutable",

   "nullptr", "bool", "true", "false", "constexpr", "decltype",

])

def keywords_for(language):

   if language == "java":

      return JAVA_KEYWORDS

   if language in ("javascript", "typescript"):

      return JS_KEYWORDS

   return C_KEYWORDS

# ---- RULES ----

# Each rule function signature:

#     def check_xxx(ctx) -> list[Finding]

# Rules decide their own added-line scoping.

_RULE_REGISTRY = []

def rule(rule_id, languages, requires_ast=False):

   """Register a rule function and attach metadata."""

   def decorator(fn):

      fn.rule_id = rule_id

      fn.languages = frozenset(languages)

      fn.requires_ast = requires_ast

      _RULE_REGISTRY.append(fn)

      return fn

   return decorator

def _split_patterns(value):

   """Split a comma/whitespace separated pattern list; ignore empties."""

   if not value:

      return []

   parts = re.split(r"[,\s]+", value.strip())

   return [p for p in parts if p]

def _match_any(rule_id, patterns):

   return any(fnmatch.fnmatchcase(rule_id, p) for p in patterns)

def select_rules(enable_patterns, disable_patterns):

   """Return (selected_rules, unknown_patterns).

   `enable_patterns` narrows the registry to matching rules (empty list

   means keep all). `disable_patterns` removes matches from that set.

   Patterns that match no known rule are returned as `unknown_patterns`

   so the caller can warn.

   """

   all_ids = [fn.rule_id for fn in _RULE_REGISTRY]

   unknown = []

   for p in enable_patterns:

      if not any(fnmatch.fnmatchcase(rid, p) for rid in all_ids):

         unknown.append(p)

   for p in disable_patterns:

      if not any(fnmatch.fnmatchcase(rid, p) for rid in all_ids):

         unknown.append(p)

   selected = []

   for fn in _RULE_REGISTRY:

      if enable_patterns and not _match_any(fn.rule_id, enable_patterns):

         continue

      if disable_patterns and _match_any(fn.rule_id, disable_patterns):

         continue

      selected.append(fn)

   return selected, unknown

ALL_LANGS = ["java", "javascript", "typescript", "c", "cpp"]

# ---------- Line-local rules ----------

@rule("style.hard-tab", ALL_LANGS)

def check_hard_tab(ctx):

   out = []

   for ln in sorted(ctx.added_linenos):

      if "\t" in source_line(ctx, ln):

         out.append(Finding(ctx.rel_path, ln, _severity("style.hard-tab"),

                            "style.hard-tab", "hard tab character"))

   return out

@rule("style.cr-endings", ALL_LANGS)

def check_cr_endings(ctx):

   # File-level: any CR anywhere means wrong line endings.

   if b"\r" not in ctx.source_bytes:

      return []

   # Report at line 1 to keep the finding actionable.

   return [Finding(ctx.rel_path, 1, _severity("style.cr-endings"),

                   "style.cr-endings",

                   "file contains CR (\\r) characters; must be LF only")]

@rule("style.line-length", ALL_LANGS)

def check_line_length(ctx):

   out = []

   for ln in sorted(ctx.added_linenos):

      s = source_line(ctx, ln)

      if visual_len(s) > 110:

         out.append(Finding(ctx.rel_path, ln, _severity("style.line-length"),

                            "style.line-length",

                            f"line length {visual_len(s)} > 110"))

   return out

_RE_COMMA_NOSPACE = re.compile(r",([^\s,)\]}])")

@rule("style.comma-space", ALL_LANGS)

def check_comma_space(ctx):

   out = []

   for ln in sorted(ctx.added_linenos):

      s = code_line(ctx, ln)

      if _RE_COMMA_NOSPACE.search(s):

         out.append(Finding(ctx.rel_path, ln, _severity("style.comma-space"),

                            "style.comma-space", "missing space after comma"))

   return out

_RE_PAREN_OPEN_SPACE = re.compile(r"\(\s+[^\s)]")

_RE_PAREN_CLOSE_SPACE = re.compile(r"[^\s(]\s+\)")

@rule("style.paren-inner-space", ALL_LANGS)

def check_paren_inner_space(ctx):

   out = []

   for ln in sorted(ctx.added_linenos):

      s = code_line(ctx, ln)

      stripped = s.rstrip()

      fired = False

      # Opening: exclude the case where `(` is the last non-whitespace on

      # the line (line-wrap: `method(\n   arg,`).

      m = _RE_PAREN_OPEN_SPACE.search(s)

      if m and s.rstrip().endswith("("):

         # `(` is at the end; skip - this is a line wrap.

         m = None

      if m:

         out.append(Finding(ctx.rel_path, ln,

                            _severity("style.paren-inner-space"),

                            "style.paren-inner-space",

                            "unexpected whitespace after '('"))

         fired = True

      m = _RE_PAREN_CLOSE_SPACE.search(s)

      if m:

         # Allow `\n   )` where the ) is the first non-whitespace on line.

         # (That's the closing of a wrapped call, not this rule's concern.)

         if not fired:

            out.append(Finding(ctx.rel_path, ln,

                               _severity("style.paren-inner-space"),

                               "style.paren-inner-space",

                               "unexpected whitespace before ')'"))

   return out

_RE_KEYWORD_PAREN_JAVA = re.compile(

   r"\b(if|while|for|switch|catch|synchronized|return|throw)\("

)

_RE_KEYWORD_PAREN_C = re.compile(

   r"\b(if|while|for|switch|return|sizeof)\("

)

_RE_KEYWORD_PAREN_JS = re.compile(

   r"\b(if|while|for|switch|catch|return|throw)\("

)

@rule("style.keyword-paren", ALL_LANGS)

def check_keyword_paren(ctx):

   if ctx.language == "java":

      pat = _RE_KEYWORD_PAREN_JAVA

   elif ctx.language in ("javascript", "typescript"):

      pat = _RE_KEYWORD_PAREN_JS

   else:

      pat = _RE_KEYWORD_PAREN_C

   out = []

   for ln in sorted(ctx.added_linenos):

      s = code_line(ctx, ln)

      m = pat.search(s)

      if m:

         out.append(Finding(ctx.rel_path, ln, _severity("style.keyword-paren"),

                            "style.keyword-paren",

                            f"missing space between '{m.group(1)}' and '('"))

   return out

_RE_IDENT_SPACE_PAREN = re.compile(r"\b([A-Za-z_]\w*)\s+\(")

@rule("style.funcname-paren", ALL_LANGS)

def check_funcname_paren(ctx):

   """Flag 'foo (' where foo is not a keyword.

   Heuristic: skip lines that look like control-flow keywords or

   declarations (handled by style.keyword-paren), and skip identifiers

   that are in the language keyword set. Also skip when the identifier

   directly precedes an operator on the left (e.g. cast: `(int) (x+1)`

   hits `) (` which is not \\w+\\s+\\().

   """

   kws = keywords_for(ctx.language)

   out = []

   for ln in sorted(ctx.added_linenos):

      s = code_line(ctx, ln)

      for m in _RE_IDENT_SPACE_PAREN.finditer(s):

         name = m.group(1)

         if name in kws:

            continue

         # Skip annotations / decorators: `@SomeAnnotation (...)`.

         start = m.start()

         if start > 0 and s[start - 1] == "@":

            continue

         out.append(Finding(ctx.rel_path, ln, _severity("style.funcname-paren"),

                            "style.funcname-paren",

                            f"space between identifier '{name}' and '('"))

   return out

# Unspaced binary operators. Conservative set.

_RE_BIN_OP = re.compile(

   r"""(?x)

   (?<![<>!=+\-*/%&|^~])    # not already part of an op

   (?P<op>==|!=|<=|>=|&&|\|\||\+=|-=|\*=|/=|%=)

   (?![<>!=+\-*/%&|^~])

   """

)

_RE_BIN_OP_ASSIGN = re.compile(r"(?<![<>!=+\-*/%&|^~])=(?![=])")

@rule("style.binary-op-space", ALL_LANGS)

def check_binary_op_space(ctx):

   out = []

   for ln in sorted(ctx.added_linenos):

      s = code_line(ctx, ln)

      # Skip annotation lines (`@Foo(bar=baz)` uses `=` as assign-arg).

      if s.lstrip().startswith("@"):

         continue

      # Run compound ops first.

      seen_cols = set()

      for m in _RE_BIN_OP.finditer(s):

         start = m.start("op")

         end = m.end("op")

         before = s[start - 1] if start > 0 else " "

         after = s[end] if end < len(s) else " "

         if not before.isspace() or not after.isspace():

            out.append(Finding(

               ctx.rel_path, ln, _severity("style.binary-op-space"),

               "style.binary-op-space",

               f"binary operator '{m.group('op')}' lacks surrounding spaces"))

            seen_cols.add(start)

      # Plain '=' assignment.

      for m in _RE_BIN_OP_ASSIGN.finditer(s):

         start = m.start()

         if start in seen_cols:

            continue

         before = s[start - 1] if start > 0 else " "

         after = s[start + 1] if start + 1 < len(s) else " "

         if not before.isspace() or not after.isspace():

            out.append(Finding(

               ctx.rel_path, ln, _severity("style.binary-op-space"),

               "style.binary-op-space",

               "assignment '=' lacks surrounding spaces"))

   return out

_RE_UNARY_SPACED = re.compile(r"(?:\w\s+(\+\+|--))|(?:(\+\+|--)\s+\w)")

@rule("style.unary-tight", ALL_LANGS)

def check_unary_tight(ctx):

   out = []

   for ln in sorted(ctx.added_linenos):

      s = code_line(ctx, ln)

      m = _RE_UNARY_SPACED.search(s)

      if m:

         out.append(Finding(ctx.rel_path, ln, _severity("style.unary-tight"),

                            "style.unary-tight",

                            "unary '++' / '--' must be tight against operand"))

   return out

_CONTINUATION_ENDERS = (",", "(", "+", "-", "*", "/", "%", "?", ":",

                        "&&", "||", "[", "{", "=", "&", "|", "^", "<", ">")

def _is_continuation(ctx, ln):

   """True if line `ln` is a continuation of a previous logical line."""

   prev = ln - 1

   while prev >= 1:

      s = code_line(ctx, prev).rstrip()

      if s:

         break

      prev -= 1

   if prev < 1:

      return False

   s = code_line(ctx, prev).rstrip()

   if not s:

      return False

   for ender in ("&&", "||"):

      if s.endswith(ender):

         return True

   return s[-1] in (",", "(", "+", "-", "*", "/", "%", "?", ":", "[",

                    "=", "&", "|", "^", "<", ">")

_RE_LEADING_WS = re.compile(r"^([ \t]*)")

@rule("style.indent-multiple-of-3", ALL_LANGS)

def check_indent_mult_3(ctx):

   """Report only the first line of each consecutive run sharing the same

   bad indent. A run breaks when the previous line is not an added line,

   or when the indent width changes.

   """

   out = []

   prev_flagged_indent = None

   for ln in sorted(ctx.added_linenos):

      s = source_line(ctx, ln)

      if not s.strip():

         prev_flagged_indent = None

         continue

      lead = _RE_LEADING_WS.match(s).group(1)

      if "\t" in lead:

         prev_flagged_indent = None

         continue  # hard-tab rule already covered it

      if _is_continuation(ctx, ln):

         prev_flagged_indent = None

         continue

      indent = len(lead)

      if indent % 3 != 0:

         prev_in_diff = (ln - 1) in ctx.added_linenos

         if prev_in_diff and prev_flagged_indent == indent:

            # Continuation of the same bad-indent run; don't re-report.

            continue

         out.append(Finding(ctx.rel_path, ln,

                            _severity("style.indent-multiple-of-3"),

                            "style.indent-multiple-of-3",

                            f"indent {indent} spaces is not a multiple of 3"))

         prev_flagged_indent = indent

      else:

         prev_flagged_indent = None

   return out

# ---------- File-level rules ----------

_RE_COPYRIGHT = re.compile(

   r"Copyright\s*\(c\)\s*(\d{4})(?:\s*-\s*(\d{4}))?,?\s*Golden",

   re.IGNORECASE,

)

@rule("style.copyright-year", ALL_LANGS)

def check_copyright_year(ctx):

   """Scan first 60 lines for a copyright header; verify latest year."""

   out = []

   for ln in range(1, min(60, len(ctx.source_lines)) + 1):

      s = source_line(ctx, ln)

      m = _RE_COPYRIGHT.search(s)

      if not m:

         continue

      latest = int(m.group(2)) if m.group(2) else int(m.group(1))

      if latest < ctx.today_year:

         out.append(Finding(

            ctx.rel_path, ln, _severity("style.copyright-year"),

            "style.copyright-year",

            f"copyright latest year {latest} "

            f"does not match current year {ctx.today_year}"))

      break  # Only the first copyright line is reported.

   return out

# ---------- Regex-based file-history rule ----------

_RE_HISTORY = re.compile(

   r"^\*\* (?P<id>\d{3,4}|\s{3,4}) (?P<init>[A-Z]{2,3} ?) (?P<date>\d{8}) "

)

_RE_HISTORY_LOOSE = re.compile(r"^\*\*\s+(\d{1,5}|\s+)\s+[A-Z].*\d{8}\b")

@rule("style.file-history-sequence", ALL_LANGS)

def check_file_history(ctx):

   """Validate newly added file-history entries.

   Pre-existing malformed or out-of-order entries are NOT flagged.

   """

   out = []

   # Collect all history-ish lines with their sequence IDs (if numeric).

   history_lines = []

   for idx, s in enumerate(ctx.source_lines, start=1):

      if _RE_HISTORY_LOOSE.match(s):

         history_lines.append(idx)

   if not history_lines:

      return out

   # Existing strict (pre-edit) max sequence: max of numeric IDs that are

   # NOT in added_linenos (those are unchanged pre-existing entries).

   existing_ids = []

   for ln in history_lines:

      if ln in ctx.added_linenos:

         continue

      m = _RE_HISTORY.match(source_line(ctx, ln))

      if m:

         token = m.group("id").strip()

         if token.isdigit():

            existing_ids.append(int(token))

   max_existing = max(existing_ids) if existing_ids else 0

   added_entries = [ln for ln in history_lines if ln in ctx.added_linenos]

   expected = max_existing + 1

   for ln in added_entries:

      s = source_line(ctx, ln)

      m = _RE_HISTORY.match(s)

      if not m:

         # The line looks like a history entry but does not match the

         # strict format - flag format.

         out.append(Finding(

            ctx.rel_path, ln, _severity("style.file-history-sequence"),

            "style.file-history-sequence",

            "history entry does not match '** NNN INIT YYYYMMDD '"))

         continue

      token = m.group("id").strip()

      if not token:

         # Continuation line (same author, different action): allowed.

         continue

      seq = int(token)

      if seq != expected:

         out.append(Finding(

            ctx.rel_path, ln, _severity("style.file-history-sequence"),

            "style.file-history-sequence",

            f"history sequence ID {seq} does not follow max existing "

            f"ID {max_existing} (expected {expected})"))

      expected = max(expected, seq + 1)

   return out

# ---------- Import wildcard suggestion (Java regex) ----------

_RE_IMPORT_EXPLICIT = re.compile(

   r"^\s*import\s+((?:[a-z]\w*\.)+)([A-Z]\w*)\s*;"

)

_RE_IMPORT_WILDCARD = re.compile(r"^\s*import\s+((?:[a-z]\w*\.)+)\*\s*;")

@rule("style.import-wildcard-suggestion", ["java"])

def check_import_wildcard(ctx):

   out = []

   per_pkg = defaultdict(list)  # pkg -> [(lineno, classname)]

   wildcard_pkgs = set()

   for ln, s in enumerate(ctx.source_lines, start=1):

      m = _RE_IMPORT_EXPLICIT.match(s)

      if m:

         pkg = m.group(1).rstrip(".")

         per_pkg[pkg].append((ln, m.group(2)))

         continue

      m = _RE_IMPORT_WILDCARD.match(s)

      if m:

         wildcard_pkgs.add(m.group(1).rstrip("."))

   for pkg, entries in per_pkg.items():

      if pkg in wildcard_pkgs:

         continue

      if len(entries) < 2:

         continue

      # Flag the entries whose line is in added_linenos.

      for ln, cls in entries:

         if ln in ctx.added_linenos:

            out.append(Finding(

               ctx.rel_path, ln,

               _severity("style.import-wildcard-suggestion"),

               "style.import-wildcard-suggestion",

               f"{len(entries)} explicit imports from {pkg} "

               f"- consider consolidating to 'import {pkg}.*;'"))

   return out

# ---------- Regex-based pointer asterisk (C/C++) ----------

_RE_PTR_TYPE_STAR = re.compile(

   r"\b([A-Za-z_]\w*)(\s*\*\s+|\*\s*)([A-Za-z_]\w*)\b"

)

_C_BUILTIN_TYPES = frozenset([

   "void", "char", "short", "int", "long", "signed", "unsigned", "float",

   "double", "bool", "size_t", "ssize_t", "uint8_t", "uint16_t", "uint32_t",

   "uint64_t", "int8_t", "int16_t", "int32_t", "int64_t", "FILE", "wchar_t",

   "jint", "jlong", "jbyte", "jshort", "jchar", "jboolean", "jfloat",

   "jdouble", "jobject", "jstring", "jclass", "jthrowable", "jarray",

   "JNIEnv", "jsize",

])

@rule("style.pointer-asterisk-with-name", ["c", "cpp"])

def check_pointer_asterisk(ctx):

   """Required form: `type *name`. Flag `type* name` and `type * name`."""

   out = []

   for ln in sorted(ctx.added_linenos):

      s = code_line(ctx, ln)

      src = source_line(ctx, ln)

      stripped = s.strip()

      # Ignore obvious non-declaration lines: control flow, comments, etc.

      if not stripped or stripped.startswith(("#", "//", "*", "/*")):

         continue

      # Skip lines that are clearly expressions: `x = *p;`, `*p = ...`

      # Heuristic: require declaration-looking pattern anchored at start.

      for m in _RE_PTR_TYPE_STAR.finditer(s):

         type_name = m.group(1)

         middle = m.group(2)

         # Skip: not a plausible type. Must be a known type or end with

         # _t or have uppercase (type-like identifier).

         if (type_name not in _C_BUILTIN_TYPES

               and not type_name.endswith("_t")

               and not type_name[0].isupper()):

            continue

         # Correct form is `type *name`: middle is exactly ' *' (one or

         # more spaces, then *, with no trailing space).

         if middle.endswith(" ") and "*" in middle:

            # `type * name` or `type *name` depending. Correct form has

            # space before '*' and no space after. Actually required

            # form per skill is `char *str` which is space-before,

            # no-space-after. Let me re-check:

            # `char *str` means middle is ` *`. That matches

            # middle.startswith(" ") and middle.endswith("*") not "* ".

            # Actually middle here captures either `\s*\*\s+` or `\*\s*`.

            # We need to detect: is the `*` adjacent to the name?

            pass

         # Simpler test: does the substring between type and name contain

         # '*', and what is the whitespace pattern?

         raw = m.group(0)

         # Extract the slice between type_name end and name start.

         t_end = m.start(2)

         n_start = m.end(2)

         between = s[t_end:n_start]

         # Required form `type *name`: exactly one or more spaces,

         # then '*', then no space before the name.

         if re.fullmatch(r" +\*", between):

            continue  # correct

         out.append(Finding(

            ctx.rel_path, ln,

            _severity("style.pointer-asterisk-with-name"),

            "style.pointer-asterisk-with-name",

            f"pointer asterisk must stick to variable name "