dotless 1.0.0__py3-none-any.whl

dotless/scanner.py

@@ -0,0 +1,418 @@
+"""Find locale-dependent case conversions in source files."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+from dataclasses import asdict, dataclass
+from typing import Callable, Iterable, Iterator
+
+from . import lexer
+from .analysis import (
+    BOTH,
+    LOWER,
+    UPPER,
+    Verdict,
+    enclosing,
+    judge_call,
+    judge_literals,
+    literals_in,
+    matching_close,
+)
+from .lexer import Source
+from .rules import RULES, severity_rank
+
+EXTENSIONS = {
+    ".c": "c", ".h": "c", ".cc": "c", ".cpp": "c", ".cxx": "c", ".hh": "c", ".hpp": "c",
+    ".vala": "vala", ".gs": "vala",
+    ".py": "python",
+    ".js": "js", ".mjs": "js",
+    ".rs": "rust",
+}
+SYNTAX = {"c": lexer.C, "vala": lexer.VALA, "python": lexer.PYTHON, "js": lexer.JS, "rust": lexer.RUST}
+
+DEFAULT_EXCLUDES = (
+    ".git", ".hg", "node_modules", "_build", "build", "builddir", "target",
+    "__pycache__", ".venv", "venv", ".flatpak-builder", "subprojects", "po",
+)
+
+_SUPPRESS = re.compile(r"dotless:\s*ignore(?P<file>-file)?(?:\[(?P<ids>[A-Z0-9_,\s]+)\])?")
+
+
+@dataclass
+class Finding:
+    rule: str
+    severity: str
+    path: str
+    line: int
+    column: int
+    end_column: int
+    language: str
+    call: str
+    message: str
+    reason: str
+    fix: str
+    snippet: str
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class Match:
+    rule: str
+    start: int  # start of the reported expression
+    end: int  # end of the reported expression
+    call: str
+    kind: str
+    verdict: Verdict | None = None  # pre-decided verdict
+
+
+Matcher = Callable[[Source], Iterator[Match]]
+
+# ---------------------------------------------------------------- C / C++
+
+_C_DECL_BEFORE = re.compile(r"(?:\b(?:int|extern|static|inline|define|undef|wint_t|char)\s*\**\s*|#\s*(?:define|undef)\s+)$")
+_C_PARAMS = re.compile(r"\s*(?:(?:const|unsigned|signed|struct|volatile)\s+)*[A-Za-z_]\w*(?:\s+|\s*\*+\s*)[A-Za-z_]\w*\s*[,)]")
+_C_CTYPE = re.compile(r"(?<![\w$.>:])(?:std\s*::\s*)?(tolower|toupper|_tolower|_toupper)\s*\(")
+_C_WIDE = re.compile(r"(?<![\w$.>:])(?:std\s*::\s*)?(towlower|towupper)\s*\(")
+_C_CASECMP = re.compile(r"(?<![\w$.>:])(strcasecmp|strncasecmp|strcasestr|wcscasecmp|wcsncasecmp)\s*\(")
+_C_GLIB_DEPR = re.compile(r"(?<![\w$.>:])(g_strdown|g_strup|g_strcasecmp|g_strncasecmp)\s*\(")
+_C_GLIB_UTF8 = re.compile(r"(?<![\w$.>:])(g_utf8_strdown|g_utf8_strup)\s*\(")
+_C_CALLBACK = re.compile(r"(?<=[(,])\s*(?:\(\s*\w+\s*\)\s*)?(strcasecmp|strncasecmp|g_strcasecmp|wcscasecmp)\s*(?=[,)])")
+_LOOKUP_CALLERS = re.compile(r"^(bsearch|lfind|lsearch|g_hash_table_new\w*|g_tree_new\w*|g_\w*find_custom|g_ptr_array_find_with_equal_func|g_\w*_lookup\w*)$")
+
+
+def _kind_of(name: str) -> str:
+    n = name.lower()
+    if "casecmp" in n or "casestr" in n:
+        return BOTH
+    if "low" in n or "down" in n:
+        return LOWER
+    return UPPER
+
+
+def _calls(src: Source, pattern: re.Pattern, rule: str, decl_guard: bool = True) -> Iterator[Match]:
+    bare = src.bare
+    for m in pattern.finditer(bare):
+        if decl_guard and _C_DECL_BEFORE.search(bare, max(0, m.start() - 40), m.start()):
+            continue
+        close = matching_close(bare, m.end() - 1)
+        # Function definitions and prototypes: "name (const gchar *str, ..."
+        if decl_guard and _C_PARAMS.match(bare, m.end()):
+            continue
+        yield Match(rule, m.start(), close, re.sub(r"\s+", "", m.group(0)[:-1]), _kind_of(m.group(1)))
+
+
+def _casecmp_calls(src: Source, pattern: re.Pattern, rule: str) -> Iterator[Match]:
+    """strcasecmp-family: the comparison constant is an argument."""
+    for match in _calls(src, pattern, rule):
+        open_idx = src.bare.index("(", match.start)
+        lits = literals_in(src, open_idx, match.end)
+        verdict = judge_literals(lits, BOTH, "compares with") if lits else None
+        if verdict is not None and verdict.severity is None:
+            continue
+        match.verdict = verdict
+        yield match
+
+
+def match_c(src: Source) -> Iterator[Match]:
+    yield from _calls(src, _C_CTYPE, "DL001")
+    yield from _casecmp_calls(src, _C_CASECMP, "DL002")
+    yield from _calls(src, _C_WIDE, "DL003")
+    yield from _calls(src, _C_GLIB_UTF8, "DL004")
+    for m in _calls(src, _C_GLIB_DEPR, "DL005"):
+        if m.kind == BOTH:
+            open_idx = src.bare.index("(", m.start)
+            lits = literals_in(src, open_idx, m.end)
+            m.verdict = judge_literals(lits, BOTH, "compares with") if lits else None
+            if m.verdict is not None and m.verdict.severity is None:
+                continue
+        yield m
+    # strcasecmp passed as a callback (bsearch, g_hash_table_new, ...)
+    for m in _C_CALLBACK.finditer(src.bare):
+        enc = enclosing(src.bare, m.start(1))
+        name = enc[1] if enc else ""
+        if _LOOKUP_CALLERS.match(name):
+            v = Verdict("high", f"used as the comparison function of {name}()")
+        else:
+            v = Verdict("low", f"passed as a callback to {name or 'a function'}()")
+        rule = "DL005" if m.group(1).startswith("g_") else "DL002"
+        yield Match(rule, m.start(1), m.end(1), m.group(1), BOTH, v)
+
+
+# ------------------------------------------------------------------- Vala
+
+_VALA_CASE = re.compile(r"\.\s*(down|up)\s*\(")
+
+
+def match_vala(src: Source) -> Iterator[Match]:
+    bare = src.bare
+    for m in _VALA_CASE.finditer(bare):
+        close = matching_close(bare, m.end() - 1)
+        args = bare[m.end() : close - 1].strip()
+        if args and not re.fullmatch(r"[\w.\-+ ]+", args):
+            continue
+        # Start the expression at the receiver so comparisons in front of
+        # it ("x" == s.down ()) are seen.
+        rs = m.start()
+        recv = re.search(r"([\w.]+|\))\s*$", bare[max(0, rs - 200) : rs])
+        start = rs - len(recv.group(0)) if recv and recv.group(1) != ")" else rs
+        yield Match("DL006", start, close, m.group(1) + "()", LOWER if m.group(1) == "down" else UPPER)
+
+
+# ----------------------------------------------------------------- Python
+
+_PY_GLIB = re.compile(r"\bGLib\s*\.\s*(utf8_strdown|utf8_strup)\s*\(")
+_PY_RE_LOCALE = re.compile(r"\bre\s*\.\s*(?:L|LOCALE)\b")
+_PY_RE_ICASE = re.compile(r"\bre\s*\.\s*(?:I|IGNORECASE)\b")
+
+
+def match_python(src: Source) -> Iterator[Match]:
+    yield from _calls(src, _PY_GLIB, "DL004", decl_guard=False)
+    bare = src.bare
+    for m in _PY_RE_LOCALE.finditer(bare):
+        enc = enclosing(bare, m.start())
+        if enc is None:
+            continue
+        open_idx, name, _ = enc
+        close = matching_close(bare, open_idx)
+        call_text = bare[open_idx:close]
+        lits = literals_in(src, open_idx, close)
+        if not (_PY_RE_ICASE.search(call_text) or any(v.startswith("(?i") for v in lits)):
+            continue
+        pattern = lits[0] if lits else None
+        if pattern is None:
+            v = Verdict("low", "pattern is not a constant")
+        elif re.search(r"[iI]|a-z|A-Z", pattern):
+            v = Verdict("high", f"case-insensitive pattern {pattern!r} contains i/I or a letter range")
+        else:
+            continue
+        name_start = bare.rfind(name, 0, open_idx)
+        yield Match("DL009", name_start if name_start >= 0 else open_idx, close, f"re.{name}(..., re.LOCALE)", BOTH, v)
+
+
+# ------------------------------------------------------------- JavaScript
+
+_JS_LOCALE_CASE = re.compile(r"\.\s*(toLocaleLowerCase|toLocaleUpperCase)\s*\(")
+_JS_GLIB = re.compile(r"\bGLib\s*\.\s*(utf8_strdown|utf8_strup)\s*\(")
+_JS_LOCALE_COMPARE = re.compile(r"\.\s*localeCompare\s*\(")
+_JS_NO_LOCALE = re.compile(r"^\s*(?:undefined|null|\[\s*\])?\s*$")
+
+
+def match_js(src: Source) -> Iterator[Match]:
+    bare = src.bare
+    for m in _JS_LOCALE_CASE.finditer(bare):
+        close = matching_close(bare, m.end() - 1)
+        args = bare[m.end() : close - 1]
+        if not _JS_NO_LOCALE.match(args):
+            lits = literals_in(src, m.end(), close)
+            if lits:
+                continue  # explicit locale, e.g. 'en-US' or deliberately 'tr'
+        start = _receiver_start(bare, m.start())
+        yield Match("DL007", start, close, m.group(1) + "()", LOWER if "Lower" in m.group(1) else UPPER)
+    yield from _calls(src, _JS_GLIB, "DL004", decl_guard=False)
+    for m in _JS_LOCALE_COMPARE.finditer(bare):
+        close = matching_close(bare, m.end() - 1)
+        args_code = src.code[m.end() : close - 1]
+        if not re.search(r"sensitivity\s*:\s*['\"](base|accent)['\"]", args_code):
+            continue
+        # Explicit locale as second argument?
+        lits = literals_in(src, m.end(), close)
+        start = _receiver_start(bare, m.start())
+        cmp = re.match(r"\s*(===|!==|==|!=|<|>)\s*0\b", bare[close:])
+        if lits and re.match(r"['\"]", args_code.split(",")[1].strip() if "," in args_code else ""):
+            continue
+        receiver_lits = literals_in(src, start, m.start())
+        candidates = [v for v in lits if not re.fullmatch(r"base|accent", v)] + receiver_lits
+        if cmp and any(_has_i(v) for v in candidates):
+            v = Verdict("high", "equality check against a constant containing i/I")
+        elif cmp:
+            v = Verdict("low", "equality check with sensitivity base/accent")
+        else:
+            continue  # sorting: locale-aware order is intended
+        yield Match("DL008", start, close, "localeCompare()", BOTH, v)
+
+
+def _has_i(v: str) -> bool:
+    return v.isascii() and ("i" in v or "I" in v)
+
+
+def _receiver_start(bare: str, dot: int) -> int:
+    recv = re.search(r"([\w$.]+)\s*$", bare[max(0, dot - 200) : dot])
+    return dot - len(recv.group(0)) if recv else dot
+
+
+# ------------------------------------------------------------------- Rust
+
+_RS_LIBC_CTYPE = re.compile(r"\blibc\s*::\s*(tolower|toupper)\s*\(")
+_RS_LIBC_CASECMP = re.compile(r"\blibc\s*::\s*(strcasecmp|strncasecmp)\s*\(")
+_RS_GLIB_FFI = re.compile(r"(?<![\w$])(?:(?:glib\s*::\s*)?ffi\s*::\s*|glib_sys\s*::\s*)?(g_utf8_strdown|g_utf8_strup)\s*\(")
+
+
+def match_rust(src: Source) -> Iterator[Match]:
+    yield from _calls(src, _RS_LIBC_CTYPE, "DL001", decl_guard=False)
+    yield from _casecmp_calls(src, _RS_LIBC_CASECMP, "DL002")
+    for m in _calls(src, _RS_GLIB_FFI, "DL004", decl_guard=False):
+        if re.search(r"\bfn\s*$", src.bare[max(0, m.start - 20) : m.start]):
+            continue
+        yield m
+
+
+MATCHERS: dict[str, Matcher] = {
+    "c": match_c,
+    "vala": match_vala,
+    "python": match_python,
+    "js": match_js,
+    "rust": match_rust,
+}
+
+# Cheap prefilter: skip lexing files that cannot contain a match.
+PREFILTER = {
+    "c": re.compile(r"tolower|toupper|towlower|towupper|casecmp|casestr|g_strdown|g_strup|g_utf8_str(?:down|up)"),
+    "vala": re.compile(r"\.\s*(?:down|up)\s*\("),
+    "python": re.compile(r"utf8_str(?:down|up)|re\s*\.\s*(?:L\b|LOCALE)"),
+    "js": re.compile(r"toLocale(?:Lower|Upper)Case|utf8_str(?:down|up)|localeCompare"),
+    "rust": re.compile(r"libc\s*::\s*(?:to(?:lower|upper)|str\w*casecmp)|g_utf8_str(?:down|up)"),
+}
+
+
+def language_of(path: str) -> str | None:
+    return EXTENSIONS.get(os.path.splitext(path)[1].lower())
+
+
+def _suppressions(src: Source) -> tuple[bool, dict[int, set[str] | None]]:
+    """(whole file ignored, {line: rule ids or None for all rules})."""
+    lines: dict[int, set[str] | None] = {}
+    for line, text in src.comments:
+        for m in _SUPPRESS.finditer(text):
+            if m.group("file"):
+                return True, {}
+            ids = {i.strip() for i in m.group("ids").split(",")} if m.group("ids") else None
+            comment_line = line + text[: m.start()].count("\n")
+            targets = [comment_line]
+            if src.line_text(comment_line).strip().startswith(("//", "/*", "#", "*")):
+                targets.append(comment_line + 1)
+            for t in targets:
+                prev = lines.get(t, set())
+                lines[t] = None if ids is None or prev is None else prev | ids
+    return False, lines
+
+
+def scan_text(text: str, path: str, lang: str) -> list[Finding]:
+    if not PREFILTER[lang].search(text):
+        return []
+    src = lexer.lex(text, SYNTAX[lang])
+    ignore_file, suppressed = _suppressions(src)
+    if ignore_file:
+        return []
+    findings = []
+    seen: set[tuple[str, int]] = set()
+    for m in MATCHERS[lang](src):
+        verdict = m.verdict or judge_call(src, m.start, m.end, m.kind, lang)
+        if verdict.severity is None:
+            continue
+        line = src.line_of(m.start)
+        sup = suppressed.get(line, set())
+        if sup is None or m.rule in sup:
+            continue
+        key = (m.rule, m.start)
+        if key in seen:
+            continue
+        seen.add(key)
+        rule = RULES[m.rule]
+        col = src.col_of(m.start)
+        end_col = col + (m.end - m.start) if src.line_of(m.end) == line else len(src.line_text(line)) + 1
+        findings.append(
+            Finding(
+                rule=m.rule,
+                severity=verdict.severity,
+                path=path,
+                line=line,
+                column=col,
+                end_column=end_col,
+                language=lang,
+                call=m.call,
+                message=f"{m.call}: {rule.summary}",
+                reason=verdict.reason,
+                fix=rule.fix,
+                snippet=src.line_text(line).strip(),
+            )
+        )
+    findings.sort(key=lambda f: (f.line, f.column))
+    return findings
+
+
+def iter_files(
+    paths: Iterable[str], excludes: Iterable[str] = (), force_exclude: bool = False
+) -> Iterator[tuple[str, str]]:
+    """Source files under ``paths`` as (path, language).
+
+    Exclude patterns apply to files found while walking directories. Files
+    named explicitly are always scanned, unless ``force_exclude`` is set
+    (useful for pre-commit, which passes file names).
+    """
+    excludes = tuple(excludes)
+
+    def excluded(rel: str) -> bool:
+        rel = rel.replace(os.sep, "/")
+        return any(fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(os.path.basename(rel), pat) for pat in excludes)
+
+    for root in paths:
+        if os.path.isfile(root):
+            lang = language_of(root)
+            if lang and not (force_exclude and _explicit_excluded(root, excluded)):
+                yield root, lang
+            continue
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = sorted(
+                d for d in dirnames
+                if d not in DEFAULT_EXCLUDES and not excluded(os.path.relpath(os.path.join(dirpath, d), root))
+            )
+            for f in sorted(filenames):
+                full = os.path.join(dirpath, f)
+                lang = language_of(f)
+                if lang and not excluded(os.path.relpath(full, root)):
+                    yield full, lang
+
+
+def _explicit_excluded(path: str, excluded: Callable[[str], bool]) -> bool:
+    """Whether an explicitly named file, or one of its directories, is excluded."""
+    rel = os.path.relpath(path).replace(os.sep, "/")
+    parts = rel.split("/")
+    if any(p in DEFAULT_EXCLUDES for p in parts[:-1]):
+        return True
+    return any(excluded("/".join(parts[: i + 1])) for i in range(len(parts)))
+
+
+def scan_paths(
+    paths: Iterable[str],
+    min_severity: str = "low",
+    excludes: Iterable[str] = (),
+    disable: Iterable[str] = (),
+    force_exclude: bool = False,
+    errors: list[str] | None = None,
+) -> tuple[list[Finding], int]:
+    """Scan files and directories. Returns (findings, number of files scanned).
+
+    Files that cannot be read are skipped; their error messages are added
+    to ``errors`` when given.
+    """
+    findings: list[Finding] = []
+    count = 0
+    floor = severity_rank(min_severity)
+    disabled = set(disable)
+    for path, lang in iter_files(paths, excludes, force_exclude):
+        try:
+            with open(path, "rb") as fh:
+                text = fh.read().decode("utf-8", errors="replace")
+        except OSError as e:
+            if errors is not None:
+                errors.append(f"{path}: {e.strerror or e}")
+            continue
+        count += 1
+        for f in scan_text(text, path.replace(os.sep, "/"), lang):
+            if severity_rank(f.severity) >= floor and f.rule not in disabled:
+                findings.append(f)
+    return findings, count

dotless-1.0.0.dist-info/METADATA

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: dotless
+Version: 1.0.0
+Summary: Find Turkish and Azerbaijani dotted/dotless I bugs caused by locale-dependent case mapping in C/GLib, Vala, Python, JavaScript and Rust
+Author-email: Ramal Rahimov <jhonaluman@gmail.com>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://gitlab.com/rehimovv/dotless
+Project-URL: Source, https://gitlab.com/rehimovv/dotless
+Project-URL: Issues, https://gitlab.com/rehimovv/dotless/-/issues
+Project-URL: Changelog, https://gitlab.com/rehimovv/dotless/-/blob/main/CHANGELOG.md
+Project-URL: Mirror, https://github.com/rehimovv/dotless
+Keywords: i18n,l10n,locale,turkish,azerbaijani,gnome,glib,linter,static-analysis,dotless-i,case-mapping
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C
+Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Localization
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# dotless
+
+[![PyPI](https://img.shields.io/pypi/v/dotless)](https://pypi.org/project/dotless/)
+[![Pipeline](https://gitlab.com/rehimovv/dotless/badges/main/pipeline.svg)](https://gitlab.com/rehimovv/dotless/-/pipelines)
+[![Python versions](https://img.shields.io/pypi/pyversions/dotless)](https://pypi.org/project/dotless/)
+[![License: GPL-3.0-or-later](https://img.shields.io/badge/license-GPL--3.0--or--later-blue)](https://gitlab.com/rehimovv/dotless/-/blob/main/LICENSE)
+
+Find the Turkish and Azerbaijani "I" bug in C/GLib, Vala, Python,
+JavaScript (gjs) and Rust code.
+
+![dotless scanning evolution-data-server](https://gitlab.com/rehimovv/dotless/-/raw/main/docs/demo.svg)
+
+In Turkish and Azerbaijani, the upper-case form of `i` is `İ` and the
+lower-case form of `I` is `ı`. Code that changes case with the user's locale
+and then compares the result with an ASCII keyword breaks for everyone
+running `tr_TR` or `az_AZ`:
+
+```c
+char *t = g_utf8_strdown (type, -1);   /* "INTEGER" -> "ınteger" in tr_TR */
+if (strcmp (t, "integer") == 0)        /* never true for Turkish users   */
+  ...
+if (strcasecmp (ext, "ini") == 0)      /* "INI" != "ini" in tr_TR/az_AZ  */
+```
+
+| | Upper | Lower |
+|---|---|---|
+| English | I | i |
+| Turkish / Azerbaijani | I | ı |
+| Turkish / Azerbaijani | İ | i |
+
+## Why dotless?
+
+This bug has been found and fixed one project at a time for decades.
+Python's codec lookup failed under Turkish locales because it normalised
+names with the C library's `tolower()`
+([bpo-1813](https://bugs.python.org/issue1813), fixed 2011). LibreOffice's
+resource compiler had to be fixed to work in `tr_TR.UTF-8` because of
+`toupper()`/`tolower()`
+([commit](https://github.com/LibreOffice/core/commit/81d2967bc7be11e7efa40a296fee40210843e5e7),
+2016), and later failed to substitute configuration entries
+([tdf#125284](https://github.com/LibreOffice/core/commit/7bc3da4ff0a6fda621340a4ded79f7ed4ce31d85),
+2019). Geary did not sync mail from Gmail with `LC_CTYPE=tr_TR.UTF-8`
+([GNOME bug 795906](https://bugzilla.gnome.org/show_bug.cgi?id=795906), fixed in 0.12.3).
+dotless looks for the pattern systematically.
+
+Every rule is backed by a measurement, not by documentation alone: small
+probe programs run under `C.UTF-8`, `tr_TR.UTF-8`, `az_AZ.UTF-8` and
+`tr_TR.ISO-8859-9` in CI ([docs/research.md](https://gitlab.com/rehimovv/dotless/-/blob/main/docs/research.md)). Some
+results were not what one would guess:
+
+* glibc's `toupper('i')` in a UTF-8 Turkish locale returns `'i'`, not `İ`:
+  the answer does not fit in a byte, so the letter is left alone.
+* GLib only applies Turkic rules after the program calls `setlocale()`.
+  Every GTK application does; a plain Rust binary using `glib::ffi` does not.
+* gjs and node disagree: `toLocaleLowerCase()` without arguments follows the
+  locale in gjs but not in node 20.
+* musl (Alpine) has no Turkish case mapping at all; the bug is a glibc bug in
+  practice, which is what GNOME distributions ship.
+* Python 3's `str.lower()` is locale independent. Only `re.LOCALE` on bytes
+  is affected.
+
+## Install
+
+```bash
+pipx install dotless
+```
+
+or `pip install dotless`. dotless needs Python 3.9 or newer and has no
+dependencies. The development version installs with
+`pipx install git+https://gitlab.com/rehimovv/dotless.git`.
+
+## Usage
+
+```bash
+dotless scan path/to/project
+```
+
+| Option | |
+|---|---|
+| `--format text\|json\|sarif\|gitlab` | output format (default `text`) |
+| `--min-severity low\|high` | hide low-severity findings |
+| `--output FILE` | write the report to a file |
+| `--exclude GLOB` | skip paths (repeatable); `.git`, `build`, `subprojects`, `node_modules`, `po` ... are skipped by default |
+| `--disable RULE` | turn a rule off, e.g. `--disable DL005` (repeatable) |
+| `--color auto\|always\|never` | colour in the terminal; `auto` honours `NO_COLOR` and turns colour off when output is piped |
+| `--config FILE`, `--no-config` | read settings from another file, or ignore `pyproject.toml` |
+| `--force-exclude` | apply excludes to files named on the command line too |
+| `--exit-zero` | always exit with 0 |
+
+`dotless rules` lists the rules and `dotless --version` prints the version.
+
+**Exit status:** `0` nothing found, `1` findings reported, `2` usage or
+configuration error (unknown option or rule, missing path, invalid
+`[tool.dotless]`). Files that cannot be read are reported on stderr and
+skipped.
+
+To silence a finding, add a comment `dotless: ignore` (or
+`dotless: ignore[DL002]`) on the same line or on the line above;
+`dotless: ignore-file` skips a file.
+
+### Configuration
+
+dotless reads `[tool.dotless]` from the nearest `pyproject.toml` (in the
+current directory or a parent). Command line options take precedence.
+
+```toml
+[tool.dotless]
+exclude = ["vendor", "tests/data/*"]
+min-severity = "high"
+disable = ["DL005"]
+```
+
+Reading `pyproject.toml` needs Python 3.11 or newer (`tomllib`). On 3.9 and
+3.10 dotless prints a warning and ignores the table; command line options
+work everywhere.
+
+### pre-commit
+
+```yaml
+repos:
+  - repo: https://gitlab.com/rehimovv/dotless
+    rev: v1.0.0
+    hooks:
+      - id: dotless
+```
+
+The hook passes `--force-exclude`, so `exclude` patterns from
+`[tool.dotless]` also apply to the files pre-commit hands over.
+
+### CI
+
+GitLab — one line in `.gitlab-ci.yml`; findings show up in the merge
+request Code Quality widget:
+
+```yaml
+include: 'https://gitlab.com/rehimovv/dotless/-/raw/main/ci/dotless.gitlab-ci.yml'
+```
+
+GitHub Actions — upload SARIF to code scanning:
+
+```yaml
+- run: pipx install dotless
+- run: dotless scan . --format sarif --output dotless.sarif --exit-zero
+- uses: github/codeql-action/upload-sarif@v4
+  with:
+    sarif_file: dotless.sarif
+```
+
+### Runtime check
+
+```bash
+dotless run -- ./my-program --some-args
+```
+
+runs the command under `C.UTF-8`, then under `tr_TR.UTF-8` and
+`az_AZ.UTF-8`, and shows any difference in exit status, stdout or stderr.
+Messages stay untranslated (`LANGUAGE=en`), so differences come from the
+locale itself. Missing locales can be generated with
+`localedef -i tr_TR -f UTF-8 tr_TR.UTF-8`. Exit status: `0` same output,
+`1` differences, `2` the comparison could not run.
+
+## Severity
+
+Only I/i behaves differently, so dotless can often tell whether a call is
+actually broken. A conversion is **high** when its result is compared with
+an ASCII constant containing the affected letter (`"ini"`, `"file"`, `'I'`),
+or is looked up as a hash table key, config key, file extension, MIME type
+or protocol name. A comparison with a constant that has no i/I (`"png"`) is
+the same in every locale and is not reported. Everything else is **low**.
+Details: [docs/rules.md](https://gitlab.com/rehimovv/dotless/-/blob/main/docs/rules.md).
+
+## Languages and rules
+
+| Rule | Language | Flagged (locale-dependent) | Not flagged (measured safe) |
+|---|---|---|---|
+| DL001 | C, Rust `libc::` | `tolower`, `toupper` | `g_ascii_tolower`, `g_ascii_toupper` |
+| DL002 | C, Rust `libc::` | `strcasecmp`, `strncasecmp`, `strcasestr`, `wcscasecmp` | `g_ascii_strcasecmp`, `g_ascii_strncasecmp` |
+| DL003 | C | `towlower`, `towupper` | `g_unichar_tolower`, `g_unichar_toupper` |
+| DL004 | C, Python, gjs, Rust `glib::ffi` | `g_utf8_strdown`, `g_utf8_strup` | `g_ascii_strdown`, `g_utf8_casefold` |
+| DL005 | C | `g_strdown`, `g_strup`, `g_strcasecmp`, `g_strncasecmp` (deprecated) | |
+| DL006 | Vala | `string.down()`, `string.up()` | `ascii_down()`, `ascii_up()`, `casefold()` |
+| DL007 | JavaScript (gjs) | `toLocaleLowerCase()`, `toLocaleUpperCase()` without a locale | `toLowerCase()`, `toUpperCase()` |
+| DL008 | JavaScript | `localeCompare(..., {sensitivity: 'base'}) === 0` | `localeCompare` for sorting |
+| DL009 | Python | `re.IGNORECASE \| re.LOCALE` | `str.lower()`, `str.upper()`, `str.casefold()`, `re.IGNORECASE` |
+| — | Rust | | `to_lowercase()`, `to_uppercase()`, `to_ascii_lowercase()` |
+
+## Bugs found
+
+* evolution-data-server: IMAP `NIL` detection and the NTLM LanManager hash
+  use `toupper()`, so a lower-case `nil` is rejected and the LM response
+  differs for passwords containing `i` under `tr_TR`/`az_AZ`
+  ([#677](https://gitlab.gnome.org/GNOME/evolution-data-server/-/issues/677), reported).
+
+A scan of ten GNOME modules and the reproducers behind this report are in
+[reports/](https://gitlab.com/rehimovv/dotless/-/blob/main/reports/README.md) and [reproducers/](https://gitlab.com/rehimovv/dotless/-/tree/main/reproducers).
+
+## Contributing
+
+See [CONTRIBUTING.md](https://gitlab.com/rehimovv/dotless/-/blob/main/CONTRIBUTING.md). False positives are bugs; please
+report them with the code that triggered them.
+
+## License
+
+GPL-3.0-or-later.
+
+## Türkçe
+
+dotless, büyük/küçük harf dönüşümünü sistem diline göre yapıp sonucu ASCII
+bir anahtar kelimeyle karşılaştıran kodu bulur. Bu tür kod `tr_TR` ve
+`az_AZ` yerellerinde bozulur: `"INTEGER"` küçültülünce `"ınteger"` olur,
+`strcasecmp("INI", "ini")` eşit dönmez.
+
+```bash
+pipx install dotless
+dotless scan <dizin>
+```
+
+Ayarlar `pyproject.toml` içindeki `[tool.dotless]` tablosundan okunur
+(Python 3.11 ve üstü); pre-commit kancası ve GitLab/GitHub CI örnekleri
+yukarıdadır. Bir bulguyu susturmak için satıra `dotless: ignore` yorumu
+eklenir. Hangi fonksiyonun gerçekten yerele bağlı olduğu
+[docs/research.md](https://gitlab.com/rehimovv/dotless/-/blob/main/docs/research.md) dosyasında ölçüm sonuçlarıyla
+belgelenmiştir.
+
+## Azərbaycanca
+
+dotless böyük/kiçik hərf çevirməsini sistemin dilinə görə edib nəticəni
+ASCII açar sözlə müqayisə edən kodu tapır. Belə kod `az_AZ` və `tr_TR`
+lokallarında səhv işləyir: `"INTEGER"` kiçildiləndə `"ınteger"` olur,
+`strcasecmp("INI", "ini")` bərabər qaytarmır.
+
+```bash
+pipx install dotless
+dotless scan <qovluq>
+```
+
+Parametrlər `pyproject.toml` faylındakı `[tool.dotless]` cədvəlindən oxunur
+(Python 3.11 və daha yeni); pre-commit və GitLab/GitHub CI nümunələri
+yuxarıdadır. Tapıntını susdurmaq üçün sətrə `dotless: ignore` şərhi
+əlavə olunur. Hansı funksiyanın həqiqətən lokaldan asılı olduğu
+[docs/research.md](https://gitlab.com/rehimovv/dotless/-/blob/main/docs/research.md) faylında ölçmə nəticələri ilə
+sənədləşdirilib.