maylang-cli 0.1.0__py3-none-any.whl

maylang_cli/__init__.py

@@ -0,0 +1,9 @@
+"""MayLang CLI – Explainable Change Standard toolkit.
+
+Provides the ``may`` CLI plus helpers to create and validate
+MayLang Change Packages (``*.may.md``).
+
+The importable package is ``maylang_cli`` (underscore) to avoid
+namespace conflicts with any other installed ``maylang`` package.
+The PyPI distribution name remains ``maylang-cli``.
+"""

maylang_cli/_version.py

@@ -0,0 +1,15 @@
+"""Version helper – single source of truth via ``importlib.metadata``.
+
+Usage::
+
+    from maylang_cli._version import __version__
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__: str = version("maylang-cli")
+except PackageNotFoundError:  # pragma: no cover – editable / dev installs
+    __version__ = "0.0.0-dev"

maylang_cli/bumper.py

@@ -0,0 +1,66 @@
+"""Version bump helper for ``may version --bump``."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+_VERSION_RE = re.compile(r'^(version\s*=\s*")(\d+\.\d+\.\d+)(")', re.MULTILINE)
+
+
+def _find_pyproject(start: Path | None = None) -> Path | None:
+    """Walk up from *start* (default: cwd) to find ``pyproject.toml``."""
+    current = (start or Path.cwd()).resolve()
+    for parent in [current, *current.parents]:
+        candidate = parent / "pyproject.toml"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def bump(part: str, *, pyproject_path: Path | None = None) -> int:
+    """Bump the version in ``pyproject.toml``.
+
+    Parameters
+    ----------
+    part : str
+        One of ``"patch"``, ``"minor"``, ``"major"``.
+    pyproject_path : Path | None
+        Explicit path; if *None* we search upward from cwd.
+
+    Returns
+    -------
+    int
+        Exit code (0 = success, 1 = error).
+    """
+    path = pyproject_path or _find_pyproject()
+    if path is None or not path.is_file():
+        print("ERROR: Could not find pyproject.toml.", file=sys.stderr)
+        return 1
+
+    text = path.read_text(encoding="utf-8")
+    match = _VERSION_RE.search(text)
+    if not match:
+        print("ERROR: No version = \"x.y.z\" found in pyproject.toml.", file=sys.stderr)
+        return 1
+
+    old_version = match.group(2)
+    parts = [int(x) for x in old_version.split(".")]
+
+    if part == "major":
+        parts = [parts[0] + 1, 0, 0]
+    elif part == "minor":
+        parts = [parts[0], parts[1] + 1, 0]
+    elif part == "patch":
+        parts = [parts[0], parts[1], parts[2] + 1]
+    else:
+        print(f"ERROR: Unknown bump part '{part}'. Use patch, minor, or major.", file=sys.stderr)
+        return 1
+
+    new_version = ".".join(str(p) for p in parts)
+    new_text = _VERSION_RE.sub(rf"\g<1>{new_version}\3", text, count=1)
+    path.write_text(new_text, encoding="utf-8")
+
+    print(f"Bumped version: {old_version} → {new_version}  ({path})")
+    return 0

maylang_cli/checker.py

@@ -0,0 +1,213 @@
+"""High-level checker logic for ``may check``.
+
+Orchestrates file discovery, git-diff integration, and per-file validation.
+Provides structured, grouped error output.
+"""
+
+from __future__ import annotations
+
+import glob
+import subprocess
+import sys
+from collections import defaultdict
+from collections.abc import Sequence
+from pathlib import Path
+
+from maylang_cli.parser import ParseResult, ValidationError, parse_file
+
+# ── Exit codes ───────────────────────────────────────────────────────────────
+
+EXIT_OK = 0
+EXIT_MISSING = 2
+EXIT_INVALID = 3
+
+
+# ── Git helpers ──────────────────────────────────────────────────────────────
+
+
+def _git_changed_files(base: str) -> tuple[list[str] | None, str | None]:
+    """Return list of changed file paths relative to repo root.
+
+    Uses ``git diff --name-only <base>...HEAD``.  Returns a tuple of
+    ``(file_list, warning_message)``.  *file_list* is ``None`` when git
+    is not available or the command fails; *warning_message* explains why.
+    """
+    # First, try the three-dot merge-base diff (works on branches).
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", f"{base}...HEAD"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return (
+            [line.strip() for line in result.stdout.splitlines() if line.strip()],
+            None,
+        )
+    except FileNotFoundError:
+        return None, "git is not installed or not on PATH."
+    except subprocess.CalledProcessError as exc:
+        # Detached HEAD or missing ref – fall back to two-dot diff.
+        try:
+            result = subprocess.run(
+                ["git", "diff", "--name-only", base, "HEAD"],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            return (
+                [line.strip() for line in result.stdout.splitlines() if line.strip()],
+                None,
+            )
+        except subprocess.CalledProcessError:
+            stderr = exc.stderr.strip() if exc.stderr else "unknown error"
+            return None, f"git diff failed: {stderr}"
+
+
+# ── Discovery ────────────────────────────────────────────────────────────────
+
+
+def discover_maylang_files(root: str = ".") -> list[str]:
+    """Glob for ``maylang/*.may.md`` under *root*."""
+    pattern = str(Path(root) / "maylang" / "*.may.md")
+    return sorted(glob.glob(pattern))
+
+
+def _paths_match(changed_files: list[str], path_prefixes: list[str]) -> bool:
+    """Return True if any changed file starts with one of *path_prefixes*.
+
+    Files inside ``maylang/`` are excluded from matching.
+    """
+    for cf in changed_files:
+        if cf.startswith("maylang/"):
+            continue
+        for prefix in path_prefixes:
+            if cf.startswith(prefix):
+                return True
+    return False
+
+
+# ── Pretty error output ─────────────────────────────────────────────────────
+
+
+def _print_errors(all_errors: list[ValidationError]) -> None:
+    """Print validation errors grouped by file with structured formatting."""
+    grouped: dict[str, list[ValidationError]] = defaultdict(list)
+    for err in all_errors:
+        grouped[err.file].append(err)
+
+    total = len(all_errors)
+    file_count = len(grouped)
+    print(
+        f"\n✗ Validation failed: {total} error(s) in {file_count} file(s)\n",
+        file=sys.stderr,
+    )
+
+    for filepath, errors in grouped.items():
+        print(f"  ── {filepath} ──", file=sys.stderr)
+
+        # Sub-group by category for readability
+        by_cat: dict[str, list[ValidationError]] = defaultdict(list)
+        for e in errors:
+            by_cat[e.category].append(e)
+
+        for cat, errs in by_cat.items():
+            label = cat.capitalize()
+            for e in errs:
+                print(f"    ✗ [{label}] {e.message}", file=sys.stderr)
+
+        print(file=sys.stderr)
+
+
+# ── Main check routine ──────────────────────────────────────────────────────
+
+
+def run_check(
+    *,
+    require: str = "always",
+    base: str | None = None,
+    paths: Sequence[str] | None = None,
+    root: str = ".",
+    enforce_diff: bool = False,
+) -> int:
+    """Execute the full ``may check`` pipeline.
+
+    Parameters
+    ----------
+    require : str
+        ``"always"`` – at least one ``.may.md`` must exist.
+        ``"changed"`` – only require when relevant files changed.
+    base : str | None
+        Git ref to diff against (e.g. ``origin/main``).
+    paths : sequence of str | None
+        Path prefixes that trigger the requirement (used with
+        ``--require=changed``).
+    root : str
+        Working directory / repo root.
+    enforce_diff : bool
+        When *True*, require a ``diff`` fenced block in the Patch section.
+
+    Returns
+    -------
+    int
+        Exit code: 0 = ok, 2 = missing required, 3 = validation failure.
+    """
+    maylang_files = discover_maylang_files(root)
+
+    # ── Decide whether MayLang files are required ────────────────────────
+    need_maylang = False
+
+    if require == "always":
+        need_maylang = True
+    elif require == "changed":
+        if base is not None:
+            changed, warning = _git_changed_files(base)
+            if changed is not None:
+                prefixes = list(paths) if paths else []
+                if prefixes:
+                    need_maylang = _paths_match(changed, prefixes)
+                else:
+                    # No path filter → any non-maylang change triggers
+                    non_ml = [f for f in changed if not f.startswith("maylang/")]
+                    need_maylang = len(non_ml) > 0
+            else:
+                # git unavailable – warn and fall back to requiring
+                print(
+                    f"WARNING: Could not detect changed files ({warning}). "
+                    "Falling back to requiring MayLang change packages.",
+                    file=sys.stderr,
+                )
+                need_maylang = True
+        else:
+            # No base ref – cannot determine changes; require if files exist
+            need_maylang = len(maylang_files) > 0
+
+    # ── Check existence ──────────────────────────────────────────────────
+    if need_maylang and not maylang_files:
+        print(
+            "\n✗ No MayLang change packages found in maylang/*.may.md.\n"
+            "\n"
+            "  Create one with:\n"
+            "    may new --id MC-0001 --slug my-change "
+            "--scope backend --risk low --owner 'your-team'\n",
+            file=sys.stderr,
+        )
+        return EXIT_MISSING
+
+    if not maylang_files:
+        # Nothing to validate and not required.
+        print("No MayLang files to validate – skipping.")
+        return EXIT_OK
+
+    # ── Validate each file ───────────────────────────────────────────────
+    all_errors: list[ValidationError] = []
+    for fpath in maylang_files:
+        result: ParseResult = parse_file(fpath, enforce_diff=enforce_diff)
+        all_errors.extend(result.errors)
+
+    if all_errors:
+        _print_errors(all_errors)
+        return EXIT_INVALID
+
+    print(f"✓ {len(maylang_files)} MayLang change package(s) validated successfully.")
+    return EXIT_OK

maylang_cli/cli.py

@@ -0,0 +1,169 @@
+"""Command-line interface for MayLang (``may`` command).
+
+Usage examples::
+
+    may new --id MC-0001 --slug auth-sessions --scope fullstack --risk low --owner "team"
+    may check --require always
+    may check --require changed --base origin/main --paths auth/,payments/
+    may version --bump patch
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from maylang_cli._version import __version__
+from maylang_cli.bumper import bump
+from maylang_cli.checker import run_check
+from maylang_cli.template import render
+
+# ── Subcommand handlers ─────────────────────────────────────────────────────
+
+
+def _handle_new(args: argparse.Namespace) -> int:
+    """Create a new MayLang Change Package file."""
+    filename = f"{args.id}-{args.slug}.may.md"
+    target_dir = Path("maylang")
+    target_dir.mkdir(exist_ok=True)
+    target = target_dir / filename
+
+    if target.exists():
+        print(f"ERROR: {target} already exists.", file=sys.stderr)
+        return 1
+
+    rollback = args.rollback or "revert_commit"
+
+    content = render(
+        id=args.id,
+        slug=args.slug,
+        scope=args.scope,
+        risk=args.risk,
+        owner=args.owner,
+        rollback=rollback,
+    )
+
+    target.write_text(content, encoding="utf-8")
+    print(f"Created {target}")
+    return 0
+
+
+def _handle_check(args: argparse.Namespace) -> int:
+    """Validate MayLang Change Package(s)."""
+    paths = None
+    if args.paths:
+        paths = [p.strip() for p in args.paths.split(",") if p.strip()]
+
+    return run_check(
+        require=args.require,
+        base=args.base,
+        paths=paths,
+        enforce_diff=args.enforce_diff,
+    )
+
+
+def _handle_version_bump(args: argparse.Namespace) -> int:
+    """Bump version in pyproject.toml."""
+    return bump(args.bump)
+
+
+# ── Argument parser ─────────────────────────────────────────────────────────
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="may",
+        description=f"MayLang – Explainable Change Standard CLI (v{__version__})",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # ── may new ──────────────────────────────────────────────────────────
+    new_parser = subparsers.add_parser(
+        "new",
+        help="Create a new MayLang Change Package (.may.md)",
+    )
+    new_parser.add_argument("--id", required=True, help='Change ID, e.g. "MC-0001"')
+    new_parser.add_argument("--slug", required=True, help='Short slug, e.g. "auth-sessions"')
+    new_parser.add_argument(
+        "--scope",
+        required=True,
+        help='Scope of the change, e.g. "backend", "fullstack"',
+    )
+    new_parser.add_argument(
+        "--risk",
+        required=True,
+        choices=["low", "medium", "high", "critical"],
+        help="Risk level",
+    )
+    new_parser.add_argument("--owner", required=True, help="Team or person responsible")
+    new_parser.add_argument(
+        "--rollback",
+        default=None,
+        help='Rollback strategy (default: "revert_commit")',
+    )
+    new_parser.set_defaults(func=_handle_new)
+
+    # ── may check ────────────────────────────────────────────────────────
+    check_parser = subparsers.add_parser(
+        "check",
+        help="Validate MayLang Change Packages",
+    )
+    check_parser.add_argument(
+        "--require",
+        choices=["always", "changed"],
+        default="always",
+        help='When to require MayLang files (default: "always")',
+    )
+    check_parser.add_argument(
+        "--base",
+        default=None,
+        help="Git base ref for change detection, e.g. origin/main",
+    )
+    check_parser.add_argument(
+        "--paths",
+        default=None,
+        help="Comma-separated path prefixes that trigger the requirement",
+    )
+    check_parser.add_argument(
+        "--enforce-diff",
+        action="store_true",
+        default=False,
+        help="Require a ```diff fenced block in the Patch section",
+    )
+    check_parser.set_defaults(func=_handle_check)
+
+    # ── may version ──────────────────────────────────────────────────────
+    version_parser = subparsers.add_parser(
+        "version",
+        help="Manage project version",
+    )
+    version_parser.add_argument(
+        "--bump",
+        required=True,
+        choices=["patch", "minor", "major"],
+        help="Bump the version in pyproject.toml (patch, minor, or major)",
+    )
+    version_parser.set_defaults(func=_handle_version_bump)
+
+    return parser
+
+
+# ── Entrypoint ───────────────────────────────────────────────────────────────
+
+
+def main(argv: list[str] | None = None) -> None:
+    """CLI entrypoint (installed as ``may``)."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    exit_code = args.func(args)
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

maylang_cli/parser.py

@@ -0,0 +1,239 @@
+"""Parse and validate MayLang Change Package (.may.md) files.
+
+Responsibilities
+----------------
+* Extract YAML frontmatter.
+* Extract Markdown headings in document order.
+* Validate required frontmatter keys.
+* Validate required headings and their order.
+* Validate that the Verification section contains at least one runnable
+  command line.
+* Optionally enforce a ``diff`` fenced block in the Patch section.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+# ── Constants ────────────────────────────────────────────────────────────────
+
+REQUIRED_FRONTMATTER_KEYS = frozenset(
+    {"id", "type", "scope", "risk", "owner", "rollback", "ai_used"}
+)
+
+REQUIRED_HEADINGS = [
+    "Intent",
+    "Contract",
+    "Invariants",
+    "Patch",
+    "Verification",
+    "Debug Map",
+]
+
+# Regex helpers
+_FRONTMATTER_RE = re.compile(r"\A---\s*\n(.*?)\n---", re.DOTALL)
+_HEADING_RE = re.compile(r"^#\s+(.+)$", re.MULTILINE)
+# A "runnable command" is either a `- ` list item containing a backtick
+# command, or any fenced code line.  We keep it deliberately simple.
+_RUNNABLE_CMD_RE = re.compile(
+    r"(^- `.+`$)|(^- .+$)|(^```)",
+    re.MULTILINE,
+)
+# Matches a ```diff fenced block or a "Link:" line in the Patch section.
+_DIFF_BLOCK_RE = re.compile(r"(^```diff)|(^Link:)", re.MULTILINE)
+
+
+# ── Data classes ─────────────────────────────────────────────────────────────
+
+
+@dataclass
+class ValidationError:
+    """A single validation failure."""
+
+    file: str
+    message: str
+    category: str = "general"
+
+    def __str__(self) -> str:
+        return f"{self.file}: {self.message}"
+
+
+@dataclass
+class ParseResult:
+    """Result of parsing a single .may.md file."""
+
+    path: str
+    frontmatter: dict = field(default_factory=dict)
+    headings: list[str] = field(default_factory=list)
+    body: str = ""
+    errors: list[ValidationError] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return len(self.errors) == 0
+
+
+# ── Parsing helpers ──────────────────────────────────────────────────────────
+
+
+def _extract_frontmatter(text: str, path: str) -> tuple[dict | None, list[ValidationError]]:
+    """Return parsed YAML frontmatter dict and any errors."""
+    errors: list[ValidationError] = []
+    match = _FRONTMATTER_RE.search(text)
+    if not match:
+        errors.append(
+            ValidationError(path, "Missing YAML frontmatter (--- delimiters).", "frontmatter")
+        )
+        return None, errors
+    try:
+        data = yaml.safe_load(match.group(1))
+    except yaml.YAMLError as exc:
+        errors.append(
+            ValidationError(path, f"Invalid YAML in frontmatter: {exc}", "frontmatter")
+        )
+        return None, errors
+    if not isinstance(data, dict):
+        errors.append(
+            ValidationError(path, "Frontmatter must be a YAML mapping.", "frontmatter")
+        )
+        return None, errors
+    return data, errors
+
+
+def _validate_frontmatter_keys(data: dict, path: str) -> list[ValidationError]:
+    """Ensure all required keys are present."""
+    missing = sorted(REQUIRED_FRONTMATTER_KEYS - set(data.keys()))
+    if missing:
+        return [
+            ValidationError(
+                path,
+                f"Missing required frontmatter key: {key}",
+                "frontmatter",
+            )
+            for key in missing
+        ]
+    return []
+
+
+def _extract_headings(text: str) -> list[str]:
+    """Return top-level (``# …``) headings in document order."""
+    return _HEADING_RE.findall(text)
+
+
+def _validate_headings(headings: list[str], path: str) -> list[ValidationError]:
+    """Validate required headings exist and appear in the correct order."""
+    errors: list[ValidationError] = []
+    remaining = list(REQUIRED_HEADINGS)
+    for heading in headings:
+        if remaining and heading.strip() == remaining[0]:
+            remaining.pop(0)
+    if remaining:
+        for h in remaining:
+            errors.append(
+                ValidationError(
+                    path,
+                    f"Missing or out-of-order heading: '# {h}'",
+                    "heading",
+                )
+            )
+    return errors
+
+
+def _section_text(body: str, heading: str) -> str:
+    """Return the text between ``# <heading>`` and the next ``# `` heading."""
+    pattern = re.compile(
+        rf"^#\s+{re.escape(heading)}\s*\n(.*?)(?=^#\s+|\Z)",
+        re.DOTALL | re.MULTILINE,
+    )
+    match = pattern.search(body)
+    return match.group(1) if match else ""
+
+
+def _validate_verification(body: str, path: str) -> list[ValidationError]:
+    """Ensure the Verification section has at least one runnable command."""
+    section = _section_text(body, "Verification")
+    if not section.strip():
+        return [ValidationError(path, "Verification section is empty.", "verification")]
+    if not _RUNNABLE_CMD_RE.search(section):
+        return [
+            ValidationError(
+                path,
+                "Verification section must contain at least one runnable command "
+                "(a list item starting with '- ' or a fenced code block).",
+                "verification",
+            )
+        ]
+    return []
+
+
+def _validate_patch_diff(body: str, path: str) -> list[ValidationError]:
+    """Ensure the Patch section contains a ```diff block or a Link: line."""
+    section = _section_text(body, "Patch")
+    if not section.strip():
+        return [ValidationError(path, "Patch section is empty.", "patch")]
+    if not _DIFF_BLOCK_RE.search(section):
+        return [
+            ValidationError(
+                path,
+                "Patch section must contain a ```diff fenced block or a 'Link:' reference "
+                "(enable with --enforce-diff).",
+                "patch",
+            )
+        ]
+    return []
+
+
+# ── Public API ───────────────────────────────────────────────────────────────
+
+
+def parse_file(
+    filepath: str | Path,
+    *,
+    enforce_diff: bool = False,
+) -> ParseResult:
+    """Parse and validate a single ``.may.md`` file.
+
+    Parameters
+    ----------
+    filepath : str | Path
+        Path to the ``.may.md`` file.
+    enforce_diff : bool
+        When *True*, require a ``diff`` fenced block in the Patch section.
+
+    Returns a ``ParseResult`` with any validation errors collected in
+    ``result.errors``.
+    """
+    filepath = Path(filepath)
+    result = ParseResult(path=str(filepath))
+
+    try:
+        text = filepath.read_text(encoding="utf-8")
+    except OSError as exc:
+        result.errors.append(ValidationError(str(filepath), f"Cannot read file: {exc}"))
+        return result
+
+    result.body = text
+
+    # 1. Frontmatter
+    fm, fm_errors = _extract_frontmatter(text, str(filepath))
+    result.errors.extend(fm_errors)
+    if fm is not None:
+        result.frontmatter = fm
+        result.errors.extend(_validate_frontmatter_keys(fm, str(filepath)))
+
+    # 2. Headings
+    result.headings = _extract_headings(text)
+    result.errors.extend(_validate_headings(result.headings, str(filepath)))
+
+    # 3. Verification section
+    result.errors.extend(_validate_verification(text, str(filepath)))
+
+    # 4. Patch diff (optional enforcement)
+    if enforce_diff:
+        result.errors.extend(_validate_patch_diff(text, str(filepath)))
+
+    return result

maylang_cli/template.py

@@ -0,0 +1,76 @@
+"""Internal template for MayLang Change Package (.may.md) files.
+
+Part of the ``maylang_cli`` package (PyPI: maylang-cli).
+"""
+
+from __future__ import annotations
+
+TEMPLATE = """\
+---
+id: "{id}"
+type: change
+scope: "{scope}"
+risk: "{risk}"
+owner: "{owner}"
+rollback: "{rollback}"
+ai_used: false
+---
+
+# Intent
+
+_Describe **why** this change exists in one or two sentences._
+
+# Contract
+
+_What does this change promise to the rest of the system?_
+
+- Input: …
+- Output: …
+- Side-effects: …
+
+# Invariants
+
+_List properties that must remain true before **and** after this change._
+
+1. …
+
+# Patch
+
+```diff
+# Paste or link your diff here
+```
+
+# Verification
+
+_At least one runnable command that proves correctness._
+
+- `pytest tests/`
+
+# Debug Map
+
+_If something breaks, where should an engineer look first?_
+
+| Symptom | Likely cause | First file to check |
+|---------|-------------|---------------------|
+| …       | …           | …                   |
+"""
+
+
+def render(
+    *,
+    id: str,
+    slug: str,
+    scope: str,
+    risk: str,
+    owner: str,
+    rollback: str,
+) -> str:
+    """Return a fully-rendered MayLang Change Package as a string."""
+    return TEMPLATE.format(
+        id=id,
+        slug=slug,
+        scope=scope,
+        risk=risk,
+        owner=owner,
+        rollback=rollback,
+    )

maylang_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,344 @@
+Metadata-Version: 2.4
+Name: maylang-cli
+Version: 0.1.0
+Summary: MayLang – Explainable Change Standard CLI for reducing AI tech debt.
+Author: MayLang Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/mayankkatulkar/maylang-cli
+Project-URL: Repository, https://github.com/mayankkatulkar/maylang-cli
+Project-URL: Issues, https://github.com/mayankkatulkar/maylang-cli/issues
+Keywords: maylang,change-management,explainability,ai-tech-debt,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# MayLang CLI
+
+**Explainable Change Standard** — a minimal, universal spec that reduces AI tech debt across ANY language or repo.
+
+MayLang is a lightweight convention: every meaningful change ships with a **Change Package** (`.may.md` file) that documents *intent*, *contract*, *invariants*, *patch*, *verification*, and *debug map* in a single, machine-readable Markdown file with YAML frontmatter.
+
+`maylang-cli` is the tiny Python CLI that creates and validates these packages.
+
+> **Import note:** The Python package is `maylang_cli` (underscore) to avoid namespace conflicts. The PyPI name is `maylang-cli`. The CLI command is `may`.
+
+[![CI](https://github.com/mayankkatulkar/maylang-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/mayankkatulkar/maylang-cli/actions)
+[![PyPI](https://img.shields.io/pypi/v/maylang-cli)](https://pypi.org/project/maylang-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## What Is a MayLang Change Package?
+
+A `.may.md` file lives at `maylang/MC-<id>-<slug>.may.md` and contains:
+
+```markdown
+---
+id: "MC-0001"
+type: change
+scope: fullstack
+risk: low
+owner: "team-alpha"
+rollback: revert_commit
+ai_used: false
+---
+
+# Intent
+
+Add session caching to reduce auth latency by 40%.
+
+# Contract
+
+- Input: session token (JWT)
+- Output: cached session object
+- Side-effects: writes to Redis
+
+# Invariants
+
+1. Tokens are never stored in plain text.
+2. Cache TTL ≤ session expiry.
+
+# Patch
+
+```diff
+--- a/auth/sessions.py
++++ b/auth/sessions.py
+@@ -12,6 +12,9 @@
+ def get_session(token: str) -> Session:
+-    return db.query(Session).filter_by(token=token).first()
++    cached = redis.get(f"sess:{token}")
++    if cached:
++        return Session.from_cache(cached)
++    session = db.query(Session).filter_by(token=token).first()
++    redis.setex(f"sess:{token}", session.ttl, session.to_cache())
++    return session
+```
+
+# Verification
+
+- `pytest tests/test_sessions.py`
+- `curl -H "Authorization: Bearer $TOKEN" localhost:8000/me`
+
+# Debug Map
+
+| Symptom | Likely cause | First file to check |
+|---------|-------------|---------------------|
+| 401 after deploy | Cache not warmed | auth/sessions.py |
+| Stale session data | TTL mismatch | config/redis.yml |
+```
+
+### Required Frontmatter Keys
+
+`id`, `type`, `scope`, `risk`, `owner`, `rollback`, `ai_used`
+
+### Required Headings (in order)
+
+1. `# Intent`
+2. `# Contract`
+3. `# Invariants`
+4. `# Patch`
+5. `# Verification` — must contain at least one runnable command
+6. `# Debug Map`
+
+---
+
+## Installation
+
+```bash
+# Recommended (isolated install)
+pipx install maylang-cli
+
+# Or with pip
+pip install maylang-cli
+```
+
+For development:
+
+```bash
+git clone https://github.com/mayankkatulkar/maylang-cli.git
+cd maylang-cli
+pip install -e ".[dev]"
+```
+
+---
+
+## Usage
+
+### Create a New Change Package
+
+```bash
+may new \
+  --id MC-0001 \
+  --slug auth-sessions \
+  --scope fullstack \
+  --risk low \
+  --owner "team-alpha" \
+  --rollback revert_commit
+```
+
+This creates `maylang/MC-0001-auth-sessions.may.md` from the built-in template.
+
+### Validate Change Packages
+
+```bash
+# Always require at least one .may.md
+may check
+
+# Same as above (explicit)
+may check --require always
+
+# Only require when files in specific paths changed
+may check --require changed --base origin/main --paths auth/,payments/,db/migrations/
+```
+
+#### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | All checks passed |
+| `2`  | Missing required MayLang file |
+| `3`  | Validation error (bad frontmatter, wrong headings, etc.) |
+
+#### Enforce Diff Block
+
+By default, the Patch section is not strictly validated for a `diff` block. To require one:
+
+```bash
+may check --enforce-diff
+```
+
+### Bump Version
+
+```bash
+# Bump patch version (0.1.0 → 0.1.1)
+may version --bump patch
+
+# Bump minor version (0.1.0 → 0.2.0)
+may version --bump minor
+
+# Bump major version (0.1.0 → 1.0.0)
+may version --bump major
+```
+
+This updates the `version` field in your `pyproject.toml`.
+
+---
+
+## Project Structure
+
+```
+maylang-cli/
+├── maylang_cli/
+│   ├── __init__.py      # Package marker
+│   ├── _version.py      # Version via importlib.metadata
+│   ├── bumper.py        # Version bump helper
+│   ├── cli.py           # Argparse CLI (entrypoint: may)
+│   ├── checker.py       # High-level check orchestration
+│   ├── parser.py        # .may.md parsing & validation
+│   └── template.py      # Built-in template for `may new`
+├── tests/
+│   ├── test_check_required.py
+│   ├── test_frontmatter.py
+│   ├── test_headings_order.py
+│   ├── test_verification.py
+│   ├── test_enforce_diff.py
+│   └── test_version_bump.py
+├── .github/workflows/ci.yml
+├── .gitignore
+├── LICENSE
+├── README.md
+└── pyproject.toml
+```
+
+---
+
+## Company Adoption Guide
+
+### Why Adopt MayLang?
+
+- **AI Accountability** — Every AI-assisted change has a human-readable spec.
+- **Cross-team Clarity** — Backend, frontend, and infra teams share one format.
+- **Audit Trail** — Change packages live in git; they're versioned and reviewable.
+- **CI-enforceable** — Block PRs that lack proper documentation.
+
+### Step-by-Step
+
+1. **Install:** `pip install maylang-cli` in your CI environment.
+2. **Create a change package** for every meaningful PR:
+   ```bash
+   may new --id MC-0001 --slug add-rate-limiter --scope backend --risk medium --owner "platform-team"
+   ```
+3. **Fill in the template** — document intent, contract, invariants, patch, verification steps, and debug map.
+4. **Add CI enforcement** (see below).
+5. **Review `.may.md` files in PR reviews** just like code.
+
+### Suggested Team Conventions
+
+| Decision | Recommendation |
+|----------|---------------|
+| When to require | Use `--require changed --paths` for gradual adoption |
+| ID format | `MC-NNNN` (monotonically increasing) |
+| Who writes it | The PR author, reviewed by the team |
+| AI changes | Set `ai_used: true` in frontmatter |
+| Rollback | Always specify a concrete rollback strategy |
+
+---
+
+## Company Adoption: CI Snippet
+
+```bash
+# In your CI pipeline:
+pipx install maylang-cli
+may check --require changed --base origin/main --paths auth/,payments/,db/migrations/
+```
+
+Or as a GitHub Actions step:
+
+```yaml
+name: MayLang Check
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  maylang:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install maylang-cli
+
+      - name: Validate MayLang Change Packages
+        run: may check --require changed --base origin/main --paths auth/,payments/,db/migrations/
+```
+
+For repos that want to enforce MayLang on **every** PR:
+
+```yaml
+      - run: may check --require always
+```
+
+To also enforce diff blocks in the Patch section:
+
+```yaml
+      - run: may check --require always --enforce-diff
+```
+
+---
+
+## Manual PyPI Release (Option A)
+
+```bash
+# 1. Install build tools
+python -m pip install -U build twine
+
+# 2. Build wheel + sdist
+python -m build
+
+# 3. Upload to TestPyPI first
+python -m twine upload --repository testpypi dist/*
+
+# 4. Verify in a fresh venv
+python -m venv /tmp/test-maylang && . /tmp/test-maylang/bin/activate
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ maylang-cli
+may --version
+deactivate && rm -rf /tmp/test-maylang
+
+# 5. Upload to production PyPI
+python -m twine upload dist/*
+
+# 6. Install from PyPI
+pipx install maylang-cli
+```
+
+See [docs/RELEASING.md](docs/RELEASING.md) for the full release checklist.
+
+---
+
+## License
+
+[MIT](LICENSE)

maylang_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+maylang_cli/__init__.py,sha256=3dAgj38_TBZPezu79rqCPyJ3obbMwuGKkJ0p6PjEMjU,345
+maylang_cli/_version.py,sha256=DWFENj7HATk3tfp1uh80xuNPIYRUqR2mhblARRiuQIE,393
+maylang_cli/bumper.py,sha256=l9GjJ2tMOhl8H8UPv4nU6sPfI9DCs2v5fhesuHtUFh4,2030
+maylang_cli/checker.py,sha256=em5kgPc6wq3mgi5Onoyj85WTLgflsWufgYAoBMBkSRE,8025
+maylang_cli/cli.py,sha256=8uv_QwlbkJzgltOOY3HAeikFNk4C1bXrpQ1SUh0JjI0,5651
+maylang_cli/parser.py,sha256=e3XnpPCpPfymkQaWhkLifak8hjQAdktMCDQ37yPEmRw,7783
+maylang_cli/template.py,sha256=qjzj8v3ghlnpwagQHq1mcoBEP-UOchWPp7WG4QI_8YY,1317
+maylang_cli-0.1.0.dist-info/licenses/LICENSE,sha256=7QBhFPRuRfeN7wcL2o1SFA_vDN3zn7znw3niZDy2L7Y,1077
+maylang_cli-0.1.0.dist-info/METADATA,sha256=Ur_V1uTSaPIIdEe9gCVePar2M5PSEgN4RxdzWtI0Ioc,9015
+maylang_cli-0.1.0.dist-info/WHEEL,sha256=YLJXdYXQ2FQ0Uqn2J-6iEIC-3iOey8lH3xCtvFLkd8Q,91
+maylang_cli-0.1.0.dist-info/entry_points.txt,sha256=WJihHnYhmGhrOsZK39uJX5_ZQQfv5VC1UsbKZvb1HKg,45
+maylang_cli-0.1.0.dist-info/top_level.txt,sha256=6ErCndgEwQbMjJyGkhw7airAFtx1ClLKb5dZramRy3g,12
+maylang_cli-0.1.0.dist-info/RECORD,,

maylang_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (81.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

maylang_cli-0.1.0.dist-info/entry_points.txt

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

maylang_cli-0.1.0.dist-info/licenses/LICENSE

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

maylang_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+maylang_cli