migrolint 0.1.0__tar.gz

migrolint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 migrolint contributors
+
+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.

migrolint-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: migrolint
+Version: 0.1.0
+Summary: Framework-agnostic linter for database migration folders — catch duplicate version numbers, sequence gaps, and missing down-migrations before CI does. Zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/migrolint-py
+Project-URL: Repository, https://github.com/jjdoor/migrolint-py
+Project-URL: Issues, https://github.com/jjdoor/migrolint-py/issues
+Keywords: migration,migrations,database,linter,sql,flyway,golang-migrate,dbmate,goose,cli,pre-commit,devops
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# migrolint
+
+**A framework-agnostic linter for your database migrations folder.** It catches
+the boring, expensive mistakes that pass locally and only blow up when CI
+actually runs the migrations — duplicate version numbers, sequence gaps, and
+`up` migrations with no matching `down`. No database connection, no framework
+lock-in, **zero dependencies** (pure standard library).
+
+```bash
+pip install migrolint
+
+migrolint                      # auto-detects ./migrations, db/migrations, ...
+migrolint db/migrations --strict
+```
+
+## The problem
+
+Two developers branch off `main`, each adds `0007_add_index.sql`, both merge.
+Now your migrations folder has two migrations claiming version `0007`. Your
+runner picks one and silently skips the other — or aborts the whole deploy.
+This is a [known, recurring failure](https://github.com/golang-migrate/migrate/issues/574)
+in every sequence-numbered migration tool.
+
+The existing linters (`django-migration-linter`, Flyway's own checks) are tied
+to one framework or need a live database. If you use raw SQL with goose,
+dbmate, golang-migrate, or a hand-rolled folder, there's nothing that just
+*looks at the filenames* and tells you they're sane. That's migrolint.
+
+## What it checks
+
+| Rule | Severity | Meaning |
+|------|----------|---------|
+| `DUPE_NUM` | **error** | two migrations share a version number (the merge-collision bug) |
+| `MISSING_DOWN` | warning | an `up` migration has no matching `down` (only flagged if the project uses up/down splits) |
+| `SEQ_GAP` | warning | a hole in an integer sequence — usually a deleted or un-merged migration |
+| `BAD_FORMAT` | warning | a file whose name no known convention recognizes |
+
+## Naming conventions it understands
+
+migrolint reads version numbers out of the filename, across the conventions
+people actually use:
+
+| Convention | Example |
+|------------|---------|
+| Flyway | `V1__init.sql`, `U1__undo.sql`, `R__refresh.sql`, `V1.1__patch.sql` |
+| golang-migrate / dbmate | `0001_create_users.up.sql` + `0001_create_users.down.sql` |
+| goose / Rails | `20230101120000_create_users.sql` (timestamp prefix) |
+| minimalist | `1_init.sql`, `2-add-index.sql` |
+
+Timestamp-style versions are recognized but exempt from `SEQ_GAP` (they're not
+meant to be contiguous). Well-known non-migration files (`schema.rb`,
+`structure.sql`, `seeds.rb`, …) and any non-migration extension are skipped.
+
+## Usage
+
+```bash
+migrolint                      # scan the first migrations dir it finds
+migrolint db/migrations        # scan a specific dir
+migrolint app/migrations svc/migrations   # scan several
+migrolint --json               # machine-readable, for tooling
+migrolint --strict             # warnings become errors (exit 1) — good for CI
+migrolint --ext .sql,.py       # override which extensions count
+migrolint --ignore baseline.sql,seed.sql
+```
+
+You can also run it as a module: `python -m migrolint db/migrations`.
+
+### As a pre-commit / CI gate
+
+```yaml
+# .pre-commit-config.yaml
+- repo: local
+  hooks:
+    - id: migrolint
+      name: migrolint
+      entry: migrolint --strict
+      language: system
+      pass_filenames: false
+```
+
+```yaml
+# GitHub Actions
+- run: pipx run migrolint --strict
+```
+
+## Example output
+
+```
+migrolint db/migrations (14 files, 12 migrations)
+
+  ✗ DUPE_NUM     version 0007 used by 2 migrations:
+       0007_add_index.up.sql
+       0007_add_orders_fk.up.sql
+  ⚠ MISSING_DOWN 0009_drop_legacy.up.sql — no matching .down file
+  ⚠ SEQ_GAP      missing version(s): 5
+
+1 error, 2 warnings.
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | clean (or only warnings, without `--strict`) |
+| `1` | errors found — or warnings, when `--strict` is set |
+| `2` | usage / IO error (no migrations dir, unreadable path) |
+
+## Also available for Node
+
+Same checks, same flags: [`npx migrolint`](https://www.npmjs.com/package/migrolint)
+(source: [migrolint](https://github.com/jjdoor/migrolint)). Both ports read
+filenames identically, so a mixed-language team gets the same verdict.
+
+## License
+
+MIT

migrolint-0.1.0/README.md

@@ -0,0 +1,116 @@
+# migrolint
+
+**A framework-agnostic linter for your database migrations folder.** It catches
+the boring, expensive mistakes that pass locally and only blow up when CI
+actually runs the migrations — duplicate version numbers, sequence gaps, and
+`up` migrations with no matching `down`. No database connection, no framework
+lock-in, **zero dependencies** (pure standard library).
+
+```bash
+pip install migrolint
+
+migrolint                      # auto-detects ./migrations, db/migrations, ...
+migrolint db/migrations --strict
+```
+
+## The problem
+
+Two developers branch off `main`, each adds `0007_add_index.sql`, both merge.
+Now your migrations folder has two migrations claiming version `0007`. Your
+runner picks one and silently skips the other — or aborts the whole deploy.
+This is a [known, recurring failure](https://github.com/golang-migrate/migrate/issues/574)
+in every sequence-numbered migration tool.
+
+The existing linters (`django-migration-linter`, Flyway's own checks) are tied
+to one framework or need a live database. If you use raw SQL with goose,
+dbmate, golang-migrate, or a hand-rolled folder, there's nothing that just
+*looks at the filenames* and tells you they're sane. That's migrolint.
+
+## What it checks
+
+| Rule | Severity | Meaning |
+|------|----------|---------|
+| `DUPE_NUM` | **error** | two migrations share a version number (the merge-collision bug) |
+| `MISSING_DOWN` | warning | an `up` migration has no matching `down` (only flagged if the project uses up/down splits) |
+| `SEQ_GAP` | warning | a hole in an integer sequence — usually a deleted or un-merged migration |
+| `BAD_FORMAT` | warning | a file whose name no known convention recognizes |
+
+## Naming conventions it understands
+
+migrolint reads version numbers out of the filename, across the conventions
+people actually use:
+
+| Convention | Example |
+|------------|---------|
+| Flyway | `V1__init.sql`, `U1__undo.sql`, `R__refresh.sql`, `V1.1__patch.sql` |
+| golang-migrate / dbmate | `0001_create_users.up.sql` + `0001_create_users.down.sql` |
+| goose / Rails | `20230101120000_create_users.sql` (timestamp prefix) |
+| minimalist | `1_init.sql`, `2-add-index.sql` |
+
+Timestamp-style versions are recognized but exempt from `SEQ_GAP` (they're not
+meant to be contiguous). Well-known non-migration files (`schema.rb`,
+`structure.sql`, `seeds.rb`, …) and any non-migration extension are skipped.
+
+## Usage
+
+```bash
+migrolint                      # scan the first migrations dir it finds
+migrolint db/migrations        # scan a specific dir
+migrolint app/migrations svc/migrations   # scan several
+migrolint --json               # machine-readable, for tooling
+migrolint --strict             # warnings become errors (exit 1) — good for CI
+migrolint --ext .sql,.py       # override which extensions count
+migrolint --ignore baseline.sql,seed.sql
+```
+
+You can also run it as a module: `python -m migrolint db/migrations`.
+
+### As a pre-commit / CI gate
+
+```yaml
+# .pre-commit-config.yaml
+- repo: local
+  hooks:
+    - id: migrolint
+      name: migrolint
+      entry: migrolint --strict
+      language: system
+      pass_filenames: false
+```
+
+```yaml
+# GitHub Actions
+- run: pipx run migrolint --strict
+```
+
+## Example output
+
+```
+migrolint db/migrations (14 files, 12 migrations)
+
+  ✗ DUPE_NUM     version 0007 used by 2 migrations:
+       0007_add_index.up.sql
+       0007_add_orders_fk.up.sql
+  ⚠ MISSING_DOWN 0009_drop_legacy.up.sql — no matching .down file
+  ⚠ SEQ_GAP      missing version(s): 5
+
+1 error, 2 warnings.
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | clean (or only warnings, without `--strict`) |
+| `1` | errors found — or warnings, when `--strict` is set |
+| `2` | usage / IO error (no migrations dir, unreadable path) |
+
+## Also available for Node
+
+Same checks, same flags: [`npx migrolint`](https://www.npmjs.com/package/migrolint)
+(source: [migrolint](https://github.com/jjdoor/migrolint)). Both ports read
+filenames identically, so a mixed-language team gets the same verdict.
+
+## License
+
+MIT

migrolint-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "migrolint"
+version = "0.1.0"
+description = "Framework-agnostic linter for database migration folders — catch duplicate version numbers, sequence gaps, and missing down-migrations before CI does. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "yyfjj" }]
+keywords = ["migration", "migrations", "database", "linter", "sql", "flyway", "golang-migrate", "dbmate", "goose", "cli", "pre-commit", "devops"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Database",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/jjdoor/migrolint-py"
+Repository = "https://github.com/jjdoor/migrolint-py"
+Issues = "https://github.com/jjdoor/migrolint-py/issues"
+
+[project.scripts]
+migrolint = "migrolint.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

migrolint-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

migrolint-0.1.0/src/migrolint/__init__.py

@@ -0,0 +1,3 @@
+"""migrolint — framework-agnostic linter for database migration folders. Zero dependencies."""
+
+__version__ = "0.1.0"

migrolint-0.1.0/src/migrolint/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

migrolint-0.1.0/src/migrolint/cli.py

@@ -0,0 +1,178 @@
+"""migrolint command-line interface."""
+
+import json as _json
+import os
+import sys
+
+from . import core
+
+VERSION = "0.1.0"
+
+# ---- tiny color helpers (no dep) ----
+_COLOR = sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+
+def _c(code, s):
+    return f"\x1b[{code}m{s}\x1b[0m" if _COLOR else s
+
+
+def red(s): return _c("31", s)
+def green(s): return _c("32", s)
+def yellow(s): return _c("33", s)
+def dim(s): return _c("2", s)
+def bold(s): return _c("1", s)
+
+
+# Directories migrolint looks in when you don't name one.
+CANDIDATE_DIRS = [
+    "migrations", "db/migrations", "database/migrations", "migrate",
+    "sql/migrations", "priv/repo/migrations", "supabase/migrations",
+]
+
+HELP = f"""{bold('migrolint')} — framework-agnostic sanity check for your migrations folder.
+
+{bold('Usage')}
+  migrolint [dir...]          Scan migration dirs (auto-detects common paths)
+  migrolint --json            Machine-readable output
+  migrolint --strict          Treat warnings as errors (exit 1)
+  migrolint --ext .sql,.py    Override which extensions count as migrations
+  migrolint --ignore a,b      Extra filenames to skip
+  migrolint --version
+
+{bold('Checks')}
+  {red('DUPE_NUM')}     two migrations share a version number  {dim('(error)')}
+  {yellow('MISSING_DOWN')} an up migration with no matching .down  {dim('(warning)')}
+  {yellow('SEQ_GAP')}      a hole in an integer sequence           {dim('(warning)')}
+  {yellow('BAD_FORMAT')}   a file whose name no convention parses  {dim('(warning)')}
+
+{bold('Recognizes')}  Flyway (V1__/U1__/R__) · golang-migrate/dbmate (0001_x.up.sql) ·
+            goose/Rails timestamps · minimalist (1_x.sql)
+
+{bold('Exit')}  0 clean · 1 errors (or warnings with --strict) · 2 usage/IO error
+"""
+
+
+def die(msg):
+    sys.stderr.write(red(f"migrolint: {msg}\n"))
+    sys.exit(2)
+
+
+def parse_args(argv):
+    opts = {"dirs": [], "json": False, "strict": False, "quiet": False, "exts": None, "ignore": None}
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--json":
+            opts["json"] = True
+        elif a == "--strict":
+            opts["strict"] = True
+        elif a in ("--quiet", "-q"):
+            opts["quiet"] = True
+        elif a == "--ext":
+            i += 1
+            if i >= len(argv):
+                die("--ext needs a comma-separated list, e.g. --ext .sql,.py")
+            opts["exts"] = [e if e.startswith(".") else "." + e
+                            for e in (x.strip().lower() for x in argv[i].split(",")) if e]
+        elif a == "--ignore":
+            i += 1
+            if i >= len(argv):
+                die("--ignore needs a comma-separated list of filenames")
+            opts["ignore"] = [s.strip() for s in argv[i].split(",") if s.strip()]
+        elif a.startswith("-"):
+            die(f"unknown flag: {a} (try --help)")
+        else:
+            opts["dirs"].append(a)
+        i += 1
+    return opts
+
+
+def resolve_dirs(requested):
+    if requested:
+        return requested
+    found = [d for d in CANDIDATE_DIRS if os.path.isdir(d)]
+    if not found:
+        die("no migrations directory found (looked for: " + ", ".join(CANDIDATE_DIRS) + ").\n"
+            "  Pass a path explicitly:  migrolint path/to/migrations")
+    return [found[0]]
+
+
+def analyze_dir(directory, opts):
+    if not os.path.exists(directory):
+        die(f"cannot read {directory}: no such file or directory")
+    if not os.path.isdir(directory):
+        die(f"not a directory: {directory}")
+    try:
+        names = os.listdir(directory)
+    except OSError as e:
+        die(f"cannot read {directory}: {e}")
+    ignore = (core.DEFAULT_IGNORE | set(opts["ignore"])) if opts["ignore"] else core.DEFAULT_IGNORE
+    result = core.analyze(names, ignore=ignore, exts=opts["exts"] or core.MIGRATION_EXTS)
+    result["dir"] = directory
+    return result
+
+
+def fmt_missing(missing):
+    if len(missing) <= 15:
+        return ", ".join(str(v) for v in missing)
+    return ", ".join(str(v) for v in missing[:15]) + dim(f" (+{len(missing) - 15} more)")
+
+
+def print_human(report, opts):
+    errors, warnings, stats = report["errors"], report["warnings"], report["stats"]
+    mig = stats["migrations"]
+    if not errors and not warnings:
+        if not opts["quiet"]:
+            tail = dim("— {} migration(s), no issues".format(mig))
+            sys.stdout.write("{} {} {}\n".format(green("✓"), report["dir"], tail))
+        return
+    info = dim("({} files, {} migrations)".format(stats["scanned"], mig))
+    sys.stdout.write("{} {} {}\n\n".format(bold("migrolint"), report["dir"], info))
+    for e in errors:
+        if e["rule"] == "DUPE_NUM":
+            sys.stdout.write(f"  {red('✗ DUPE_NUM')}     version {bold(e['version'])} used by {len(e['files'])} migrations:\n")
+            for f in e["files"]:
+                sys.stdout.write(f"       {f}\n")
+    for w in warnings:
+        if w["rule"] == "MISSING_DOWN":
+            sys.stdout.write(f"  {yellow('⚠ MISSING_DOWN')} {w['file']} {dim('— no matching .down file')}\n")
+        elif w["rule"] == "SEQ_GAP":
+            sys.stdout.write(f"  {yellow('⚠ SEQ_GAP')}      missing version(s): {fmt_missing(w['missing'])}\n")
+        elif w["rule"] == "BAD_FORMAT":
+            sys.stdout.write(f"  {yellow('⚠ BAD_FORMAT')}   {w['file']} {dim('— no recognized version prefix')}\n")
+    parts = []
+    if errors:
+        parts.append(red(f"{len(errors)} error{'s' if len(errors) > 1 else ''}"))
+    if warnings:
+        parts.append(yellow(f"{len(warnings)} warning{'s' if len(warnings) > 1 else ''}"))
+    sys.stdout.write("\n" + ", ".join(parts) + ".\n")
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if "-h" in argv or "--help" in argv:
+        sys.stdout.write(HELP)
+        return 0
+    if "-v" in argv or "--version" in argv:
+        sys.stdout.write(VERSION + "\n")
+        return 0
+
+    opts = parse_args(argv)
+    dirs = resolve_dirs(opts["dirs"])
+    reports = [analyze_dir(d, opts) for d in dirs]
+
+    if opts["json"]:
+        payload = [{"dir": r["dir"], "stats": r["stats"], "errors": r["errors"], "warnings": r["warnings"]}
+                   for r in reports]
+        sys.stdout.write(_json.dumps(payload[0] if len(dirs) == 1 else payload, indent=2) + "\n")
+    else:
+        for i, r in enumerate(reports):
+            if i > 0:
+                sys.stdout.write("\n")
+            print_human(r, opts)
+
+    total_errors = sum(len(r["errors"]) for r in reports)
+    total_warnings = sum(len(r["warnings"]) for r in reports)
+    if total_errors > 0 or (opts["strict"] and total_warnings > 0):
+        return 1
+    return 0

migrolint-0.1.0/src/migrolint/core.py

@@ -0,0 +1,161 @@
+"""migrolint core — pure migration-filename analysis. No fs, no DB, no clock.
+
+Database migration folders break in three boring, expensive ways that no
+framework-agnostic tool catches before CI runs the migrations:
+
+  - DUPE_NUM     two migrations claim the same version number. The classic
+                 merge-of-two-branches collision (golang-migrate #574) — the
+                 runner picks one, silently skips the other, or aborts.
+  - MISSING_DOWN an ``up`` migration with no matching ``down`` (only flagged
+                 for projects that use up/down splits).
+  - SEQ_GAP      a hole in an integer sequence — usually a deleted/un-merged
+                 migration. Advisory.
+  - BAD_FORMAT   a file in the dir whose name no convention recognizes.
+
+The parser understands the conventions people actually use: Flyway
+(``V1__x.sql``, ``U1__x.sql``, ``R__x.sql``), golang-migrate / dbmate
+(``0001_x.up.sql`` + ``0001_x.down.sql``), goose / Rails timestamps
+(``20230101120000_x.sql``), and the minimalist ``1_x.sql``. This module mirrors
+the Node port function-for-function so both produce identical verdicts.
+"""
+
+import re
+
+# File extensions that can hold a migration body. Anything else in the folder
+# is ignored outright (READMEs, .gitkeep) rather than flagged.
+MIGRATION_EXTS = [".sql", ".py", ".rb", ".js", ".ts", ".go"]
+
+# Well-known non-migration files that legitimately live in a migrations dir.
+DEFAULT_IGNORE = {
+    "schema.rb", "structure.sql", "schema.sql", "seeds.rb", "seed.sql", "database.sql",
+}
+
+# Integer versions at or above this look like dates/timestamps, not an
+# incrementing sequence — so they're exempt from gap analysis.
+SEQ_MAX = 1_000_000
+
+_DIR_SUFFIX_RE = re.compile(r"\.(up|down)(\.(?:sql|py|rb|js|ts|go))$", re.IGNORECASE)
+_FLYWAY_RE = re.compile(r"^([VUR])(\d[\d.]*)?__(.*)$")
+_GENERIC_RE = re.compile(r"^(\d+)[_-](.*)$")
+_BARE_NUM_RE = re.compile(r"^(\d+)$")
+
+
+def ext_of(name):
+    i = name.rfind(".")
+    return name[i:].lower() if i > 0 else ""
+
+
+def parse_migration(filename):
+    """Parse a migration filename into structured fields, or ``None`` if no
+    recognized convention matches (a BAD_FORMAT candidate).
+
+    Returns a dict with: ``versionRaw`` (str|None), ``numeric`` (int|None),
+    ``direction`` ('up'|'down'|'both'), ``split`` (bool), ``repeatable`` (bool),
+    ``label`` (str).
+    """
+    # 1. Peel off an .up/.down suffix (golang-migrate / dbmate split style).
+    direction = "both"
+    split = False
+    m = _DIR_SUFFIX_RE.search(filename)
+    if m:
+        direction = m.group(1).lower()
+        split = True
+        stem = filename[: m.start()]
+    else:
+        ext = ext_of(filename)
+        stem = filename[: -len(ext)] if ext else filename
+
+    # 2. Flyway: V/U/R prefix + double-underscore description.
+    fly = _FLYWAY_RE.match(stem)
+    if fly:
+        kind = fly.group(1).upper()
+        version_raw = fly.group(2) or None
+        if kind == "R":
+            return {"versionRaw": None, "numeric": None, "direction": "both",
+                    "split": False, "repeatable": True, "label": fly.group(3)}
+        numeric = int(version_raw) if version_raw and version_raw.isdigit() else None
+        return {
+            "versionRaw": version_raw,
+            "numeric": numeric,
+            "direction": "down" if kind == "U" else (direction if split else "up"),
+            "split": split,
+            "repeatable": False,
+            "label": fly.group(3),
+        }
+
+    # 3. Generic numeric prefix: "0001_create", "20230101120000_init", "1-init".
+    gen = _GENERIC_RE.match(stem) or _BARE_NUM_RE.match(stem)
+    if gen:
+        version_raw = gen.group(1)
+        numeric = int(version_raw) if version_raw.isdigit() else None
+        label = gen.group(2) if gen.re.groups >= 2 else ""
+        return {"versionRaw": version_raw, "numeric": numeric, "direction": direction,
+                "split": split, "repeatable": False, "label": label}
+
+    return None  # unrecognized — BAD_FORMAT
+
+
+def analyze(filenames, ignore=None, exts=None):
+    """Analyze a folder's filenames. Returns ``{errors, warnings, stats}``.
+
+    Pure: give it the list of basenames, it gives you the verdict.
+    """
+    ignore = ignore if ignore is not None else DEFAULT_IGNORE
+    exts = exts if exts is not None else MIGRATION_EXTS
+
+    # Sort first so the verdict is deterministic regardless of listdir order.
+    candidates = [f for f in sorted(filenames) if ext_of(f) in exts and f not in ignore]
+    parsed = []
+    bad_format = []
+    for f in candidates:
+        m = parse_migration(f)
+        if m is None:
+            bad_format.append(f)
+        else:
+            parsed.append(dict(file=f, **m))
+
+    versioned = [p for p in parsed if not p["repeatable"] and p["versionRaw"] is not None]
+    errors = []
+    warnings = []
+
+    # DUPE_NUM — same (version, direction) used by more than one file. up & down
+    # of the same version are a legitimate pair, so they don't collide.
+    by_ver_dir = {}
+    for p in versioned:
+        by_ver_dir.setdefault((p["versionRaw"], p["direction"]), []).append(p["file"])
+    dupe_by_version = {}
+    for (version, _direction), files in by_ver_dir.items():
+        if len(files) > 1:
+            dupe_by_version.setdefault(version, []).extend(files)
+    for version, files in dupe_by_version.items():
+        errors.append({"rule": "DUPE_NUM", "version": version, "files": sorted(files)})
+
+    # MISSING_DOWN — only when the project actually uses .up/.down splits.
+    uses_split = any(p["split"] and p["direction"] == "down" for p in versioned)
+    if uses_split:
+        down_versions = {p["versionRaw"] for p in versioned if p["split"] and p["direction"] == "down"}
+        seen_up = set()
+        for p in versioned:
+            if (p["split"] and p["direction"] == "up"
+                    and p["versionRaw"] not in down_versions
+                    and p["versionRaw"] not in seen_up):
+                seen_up.add(p["versionRaw"])
+                warnings.append({"rule": "MISSING_DOWN", "version": p["versionRaw"], "file": p["file"]})
+
+    # SEQ_GAP — integer sequences only (timestamps/dotted versions skipped).
+    seq = sorted({p["numeric"] for p in versioned if p["numeric"] is not None and p["numeric"] < SEQ_MAX})
+    if len(seq) >= 2:
+        present = set(seq)
+        missing = [v for v in range(seq[0], seq[-1]) if v not in present]
+        if missing:
+            warnings.append({"rule": "SEQ_GAP", "missing": missing})
+
+    # BAD_FORMAT — recognized extension but no parseable version.
+    for f in bad_format:
+        warnings.append({"rule": "BAD_FORMAT", "file": f})
+
+    return {
+        "errors": errors,
+        "warnings": warnings,
+        "stats": {"scanned": len(filenames), "candidates": len(candidates), "migrations": len(versioned)},
+    }

migrolint-0.1.0/src/migrolint.egg-info/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: migrolint
+Version: 0.1.0
+Summary: Framework-agnostic linter for database migration folders — catch duplicate version numbers, sequence gaps, and missing down-migrations before CI does. Zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/migrolint-py
+Project-URL: Repository, https://github.com/jjdoor/migrolint-py
+Project-URL: Issues, https://github.com/jjdoor/migrolint-py/issues
+Keywords: migration,migrations,database,linter,sql,flyway,golang-migrate,dbmate,goose,cli,pre-commit,devops
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# migrolint
+
+**A framework-agnostic linter for your database migrations folder.** It catches
+the boring, expensive mistakes that pass locally and only blow up when CI
+actually runs the migrations — duplicate version numbers, sequence gaps, and
+`up` migrations with no matching `down`. No database connection, no framework
+lock-in, **zero dependencies** (pure standard library).
+
+```bash
+pip install migrolint
+
+migrolint                      # auto-detects ./migrations, db/migrations, ...
+migrolint db/migrations --strict
+```
+
+## The problem
+
+Two developers branch off `main`, each adds `0007_add_index.sql`, both merge.
+Now your migrations folder has two migrations claiming version `0007`. Your
+runner picks one and silently skips the other — or aborts the whole deploy.
+This is a [known, recurring failure](https://github.com/golang-migrate/migrate/issues/574)
+in every sequence-numbered migration tool.
+
+The existing linters (`django-migration-linter`, Flyway's own checks) are tied
+to one framework or need a live database. If you use raw SQL with goose,
+dbmate, golang-migrate, or a hand-rolled folder, there's nothing that just
+*looks at the filenames* and tells you they're sane. That's migrolint.
+
+## What it checks
+
+| Rule | Severity | Meaning |
+|------|----------|---------|
+| `DUPE_NUM` | **error** | two migrations share a version number (the merge-collision bug) |
+| `MISSING_DOWN` | warning | an `up` migration has no matching `down` (only flagged if the project uses up/down splits) |
+| `SEQ_GAP` | warning | a hole in an integer sequence — usually a deleted or un-merged migration |
+| `BAD_FORMAT` | warning | a file whose name no known convention recognizes |
+
+## Naming conventions it understands
+
+migrolint reads version numbers out of the filename, across the conventions
+people actually use:
+
+| Convention | Example |
+|------------|---------|
+| Flyway | `V1__init.sql`, `U1__undo.sql`, `R__refresh.sql`, `V1.1__patch.sql` |
+| golang-migrate / dbmate | `0001_create_users.up.sql` + `0001_create_users.down.sql` |
+| goose / Rails | `20230101120000_create_users.sql` (timestamp prefix) |
+| minimalist | `1_init.sql`, `2-add-index.sql` |
+
+Timestamp-style versions are recognized but exempt from `SEQ_GAP` (they're not
+meant to be contiguous). Well-known non-migration files (`schema.rb`,
+`structure.sql`, `seeds.rb`, …) and any non-migration extension are skipped.
+
+## Usage
+
+```bash
+migrolint                      # scan the first migrations dir it finds
+migrolint db/migrations        # scan a specific dir
+migrolint app/migrations svc/migrations   # scan several
+migrolint --json               # machine-readable, for tooling
+migrolint --strict             # warnings become errors (exit 1) — good for CI
+migrolint --ext .sql,.py       # override which extensions count
+migrolint --ignore baseline.sql,seed.sql
+```
+
+You can also run it as a module: `python -m migrolint db/migrations`.
+
+### As a pre-commit / CI gate
+
+```yaml
+# .pre-commit-config.yaml
+- repo: local
+  hooks:
+    - id: migrolint
+      name: migrolint
+      entry: migrolint --strict
+      language: system
+      pass_filenames: false
+```
+
+```yaml
+# GitHub Actions
+- run: pipx run migrolint --strict
+```
+
+## Example output
+
+```
+migrolint db/migrations (14 files, 12 migrations)
+
+  ✗ DUPE_NUM     version 0007 used by 2 migrations:
+       0007_add_index.up.sql
+       0007_add_orders_fk.up.sql
+  ⚠ MISSING_DOWN 0009_drop_legacy.up.sql — no matching .down file
+  ⚠ SEQ_GAP      missing version(s): 5
+
+1 error, 2 warnings.
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | clean (or only warnings, without `--strict`) |
+| `1` | errors found — or warnings, when `--strict` is set |
+| `2` | usage / IO error (no migrations dir, unreadable path) |
+
+## Also available for Node
+
+Same checks, same flags: [`npx migrolint`](https://www.npmjs.com/package/migrolint)
+(source: [migrolint](https://github.com/jjdoor/migrolint)). Both ports read
+filenames identically, so a mixed-language team gets the same verdict.
+
+## License
+
+MIT

migrolint-0.1.0/src/migrolint.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/migrolint/__init__.py
+src/migrolint/__main__.py
+src/migrolint/cli.py
+src/migrolint/core.py
+src/migrolint.egg-info/PKG-INFO
+src/migrolint.egg-info/SOURCES.txt
+src/migrolint.egg-info/dependency_links.txt
+src/migrolint.egg-info/entry_points.txt
+src/migrolint.egg-info/top_level.txt
+tests/test_core.py

migrolint-0.1.0/src/migrolint.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

migrolint-0.1.0/src/migrolint.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+migrolint = migrolint.cli:main

migrolint-0.1.0/src/migrolint.egg-info/top_level.txt

@@ -0,0 +1 @@
+migrolint

migrolint-0.1.0/tests/test_core.py

@@ -0,0 +1,133 @@
+from migrolint.core import parse_migration, analyze
+
+
+# ---- parse_migration: the convention zoo ----------------------------------
+
+def test_flyway_versioned_is_up():
+    assert parse_migration("V1__init.sql") == {
+        "versionRaw": "1", "numeric": 1, "direction": "up",
+        "split": False, "repeatable": False, "label": "init",
+    }
+
+
+def test_flyway_undo_is_down():
+    m = parse_migration("U1__rollback.sql")
+    assert m["direction"] == "down"
+    assert m["versionRaw"] == "1"
+
+
+def test_flyway_repeatable_has_no_version():
+    m = parse_migration("R__refresh_views.sql")
+    assert m["repeatable"] is True
+    assert m["versionRaw"] is None
+
+
+def test_flyway_dotted_version_keeps_raw_numeric_none():
+    m = parse_migration("V1.1__patch.sql")
+    assert m["versionRaw"] == "1.1"
+    assert m["numeric"] is None
+
+
+def test_golang_migrate_up_split():
+    assert parse_migration("0001_create_users.up.sql") == {
+        "versionRaw": "0001", "numeric": 1, "direction": "up",
+        "split": True, "repeatable": False, "label": "create_users",
+    }
+
+
+def test_golang_migrate_down_split():
+    m = parse_migration("0001_create_users.down.sql")
+    assert m["direction"] == "down"
+    assert m["split"] is True
+
+
+def test_goose_rails_timestamp_not_sequential():
+    m = parse_migration("20230101120000_init.rb")
+    assert m["versionRaw"] == "20230101120000"
+    assert m["numeric"] == 20230101120000
+    assert m["direction"] == "both"
+
+
+def test_minimalist_numeric_prefix():
+    assert parse_migration("1_init.sql")["numeric"] == 1
+    assert parse_migration("2-add-index.sql")["label"] == "add-index"
+
+
+def test_bare_number_no_label():
+    m = parse_migration("0005.sql")
+    assert m["versionRaw"] == "0005"
+    assert m["label"] == ""
+
+
+def test_unrecognized_returns_none():
+    assert parse_migration("create_users.sql") is None
+    assert parse_migration("notes.sql") is None
+
+
+# ---- analyze: the four rules ----------------------------------------------
+
+def test_dupe_num_two_ups_same_version_is_error():
+    r = analyze(["0001_a.up.sql", "0001_b.up.sql"])
+    assert len(r["errors"]) == 1
+    assert r["errors"][0]["rule"] == "DUPE_NUM"
+    assert r["errors"][0]["version"] == "0001"
+    assert r["errors"][0]["files"] == ["0001_a.up.sql", "0001_b.up.sql"]
+    assert len(r["warnings"]) == 0
+
+
+def test_matched_up_down_pair_is_not_duplicate():
+    r = analyze(["0001_a.up.sql", "0001_a.down.sql"])
+    assert len(r["errors"]) == 0
+    assert len(r["warnings"]) == 0
+
+
+def test_missing_down_only_when_project_uses_splits():
+    r = analyze(["0001_a.up.sql", "0001_a.down.sql", "0002_b.up.sql"])
+    assert len(r["errors"]) == 0
+    md = [w for w in r["warnings"] if w["rule"] == "MISSING_DOWN"]
+    assert len(md) == 1
+    assert md[0]["version"] == "0002"
+
+
+def test_single_file_does_not_trigger_missing_down():
+    r = analyze(["0001_a.sql", "0002_b.sql"])
+    assert [w for w in r["warnings"] if w["rule"] == "MISSING_DOWN"] == []
+
+
+def test_seq_gap_reports_hole():
+    r = analyze(["0001_a.sql", "0003_c.sql"])
+    gap = [w for w in r["warnings"] if w["rule"] == "SEQ_GAP"]
+    assert len(gap) == 1
+    assert gap[0]["missing"] == [2]
+
+
+def test_timestamps_never_produce_seq_gap():
+    r = analyze(["20230101120000_a.sql", "20230515090000_b.sql"])
+    assert [w for w in r["warnings"] if w["rule"] == "SEQ_GAP"] == []
+    assert len(r["errors"]) == 0
+
+
+def test_bad_format_flags_versionless_migration_file():
+    r = analyze(["0001_a.sql", "random.sql"])
+    bad = [w for w in r["warnings"] if w["rule"] == "BAD_FORMAT"]
+    assert len(bad) == 1
+    assert bad[0]["file"] == "random.sql"
+
+
+def test_non_migration_and_ignored_files_skipped():
+    r = analyze(["0001_a.sql", "README.md", ".gitkeep", "schema.rb", "structure.sql"])
+    assert len(r["errors"]) == 0
+    assert len(r["warnings"]) == 0
+    assert r["stats"]["migrations"] == 1
+
+
+def test_stats_count_scanned_vs_migrations():
+    r = analyze(["0001_a.up.sql", "0001_a.down.sql", "README.md"])
+    assert r["stats"]["scanned"] == 3
+    assert r["stats"]["migrations"] == 2
+
+
+def test_flyway_dir_without_downs_is_clean():
+    r = analyze(["V1__init.sql", "V2__users.sql", "R__view.sql"])
+    assert len(r["errors"]) == 0
+    assert len(r["warnings"]) == 0