fmstyle 0.2.0__py3-none-any.whl

fmstyle/__init__.py

@@ -0,0 +1,68 @@
+"""fmstyle - deterministic formatter + style engine for FileMaker calculations.
+
+Public API:
+
+    format_calc(source, style)  -> formatted text (token-preservation verified)
+    lint_calc(source, style)    -> [(rule_id, message), ...]
+    Style                       -> configuration (an org's mechanical rules)
+"""
+
+from __future__ import annotations
+
+from .config import Style
+from .lexer import LexError, tokenize
+from .parser import ParseError, Parser
+from .printer import Printer
+from .rules import lint as _lint
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "format_calc",
+    "lint_calc",
+    "Style",
+    "LexError",
+    "ParseError",
+    "FormatSafetyError",
+]
+
+
+class FormatSafetyError(RuntimeError):
+    """Formatting would have changed the token stream - refused."""
+
+
+def _signature(source: str):
+    code = []
+    comments = []
+    for tok in tokenize(source):
+        comments.extend(c.text for c in tok.pre_comments)
+        if tok.kind != "EOF":
+            text = tok.text.lower() if tok.kind == "OP" else tok.text
+            code.append((tok.kind, text))
+    return code, comments
+
+
+def format_calc(source: str, style: Style | None = None) -> str:
+    """Format a FileMaker calculation. Guaranteed semantics-preserving: the
+    output must re-tokenize to the exact same code tokens and comments as the
+    input, otherwise FormatSafetyError is raised and nothing is changed."""
+    style = style or Style()
+    tokens = tokenize(source)
+    if len(tokens) == 1:  # comments only (e.g. a commented-out calc) - keep as is
+        return source
+    node = Parser(tokens).parse()
+    out = Printer(style).format(node)
+    if _signature(source) != _signature(out):
+        raise FormatSafetyError(
+            "formatting would alter the token stream; refusing (please report this input)"
+        )
+    return out
+
+
+def lint_calc(source: str, style: Style | None = None):
+    """Run guideline lint rules over a calculation."""
+    style = style or Style()
+    tokens = tokenize(source)
+    if len(tokens) == 1:  # comments only - nothing to lint
+        return []
+    return _lint(Parser(tokens).parse(), style)

fmstyle/cli.py

@@ -0,0 +1,163 @@
+"""fmstyle CLI - format / lint FileMaker calculations.
+
+Exit codes: 0 ok, 1 check/lint findings, 2 input could not be parsed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import json
+
+from . import FormatSafetyError, LexError, ParseError, __version__, format_calc, lint_calc
+from .config import Style
+from .presets import PRESETS, preset_dict, preset_names
+
+SKILL_RAW_URL = (
+    "https://raw.githubusercontent.com/oogi-io/fm-code-formatter/main/fmstyle/skill/SKILL.md"
+)
+
+
+def cmd_install_skill(args) -> int:
+    """Install the fmstyle Claude Code skill, or check its freshness.
+
+    --check   compare the installed skill against the one shipped with this
+              fmstyle version (offline). 0 = up to date, 1 = differs, 2 = absent.
+    --remote  compare against GitHub main instead (network).
+    Neither flag: (re)install the packaged skill.
+    """
+    import hashlib
+    import shutil
+
+    src = Path(__file__).resolve().parent / "skill" / "SKILL.md"
+    dest_dir = Path("~/.claude/skills/fmstyle").expanduser()
+    dest = dest_dir / "SKILL.md"
+
+    def digest(b: bytes) -> str:
+        return hashlib.sha256(b).hexdigest()[:12]
+
+    if args.check or args.remote:
+        if not dest.exists():
+            print(f"fmstyle skill is not installed ({dest} missing). Run: fmstyle install-skill")
+            return 2
+        installed = dest.read_bytes()
+        if args.remote:
+            import urllib.request
+
+            try:
+                ref = urllib.request.urlopen(SKILL_RAW_URL, timeout=10).read()
+            except Exception as exc:  # noqa: BLE001 - offline is fine, just report
+                print(f"Could not fetch {SKILL_RAW_URL}: {exc}")
+                return 2
+            ref_label = "GitHub main"
+            hint = "pipx upgrade fmstyle (or git pull), then: fmstyle install-skill"
+        else:
+            ref = src.read_bytes()
+            ref_label = f"the skill shipped with fmstyle {__version__}"
+            hint = "run: fmstyle install-skill"
+        if digest(installed) == digest(ref):
+            print(f"fmstyle skill is up to date with {ref_label}.")
+            return 0
+        print(
+            f"fmstyle skill DIFFERS from {ref_label} "
+            f"(installed {digest(installed)}, reference {digest(ref)}). To update: {hint}"
+        )
+        return 1
+
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    shutil.copy(src, dest)
+    print(f"Installed the 'fmstyle' skill (fmstyle {__version__}) -> {dest_dir}")
+    print("Claude Code can now format FileMaker calculations from any directory -")
+    print("just write or paste a calc, or ask to format one.")
+    print("Freshness check anytime: fmstyle install-skill --check (or --remote for GitHub main)")
+    return 0
+
+
+def _load_style(config: str | None, preset: str | None) -> Style:
+    base = dict(preset_dict(preset)) if preset else {}
+    path = Path(config) if config else Path("fmstyle.json")
+    if config or (not preset and path.exists()):
+        data = json.loads(path.read_text(encoding="utf-8"))
+        functions = {**base.get("functions", {}), **data.get("functions", {})}
+        base.update(data)
+        if functions:
+            base["functions"] = functions
+    return Style.from_dict(base) if base else Style()
+
+
+def _read_sources(paths: list[str]) -> list[tuple[str, str]]:
+    if not paths or paths == ["-"]:
+        return [("<stdin>", sys.stdin.read())]
+    return [(p, Path(p).read_text(encoding="utf-8")) for p in paths]
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="fmstyle",
+        description="Deterministic formatter and style checker for FileMaker calculations.",
+    )
+    ap.add_argument("--version", action="version", version=f"fmstyle {__version__}")
+    ap.add_argument("--config", help="path to fmstyle.json (default: ./fmstyle.json if present)")
+    ap.add_argument("--preset", help="named style pack (see `fmstyle presets`); --config keys override it")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("presets", help="list available style presets")
+
+    fmt = sub.add_parser("format", help="format calculation(s) (stdin by default)")
+    fmt.add_argument("paths", nargs="*", help="files to format, '-' or empty for stdin")
+    fmt.add_argument("-w", "--write", action="store_true", help="rewrite files in place")
+    fmt.add_argument("--check", action="store_true", help="exit 1 if any file would change")
+
+    ln = sub.add_parser("lint", help="run guideline rules over calculation(s)")
+    ln.add_argument("paths", nargs="*", help="files to lint, '-' or empty for stdin")
+
+    ins = sub.add_parser("install-skill", help="install the Claude Code skill globally (~/.claude/skills)")
+    ins.add_argument("--check", action="store_true", help="compare installed skill vs this version's")
+    ins.add_argument("--remote", action="store_true", help="compare installed skill vs GitHub main")
+
+    args = ap.parse_args(argv)
+
+    if args.command == "presets":
+        for name in preset_names():
+            print(f"{name:10s} {PRESETS[name]['description']}")
+        return 0
+
+    if args.command == "install-skill":
+        return cmd_install_skill(args)
+
+    try:
+        style = _load_style(args.config, args.preset)
+    except KeyError as exc:
+        print(f"error: {exc.args[0]}", file=sys.stderr)
+        return 2
+    rc = 0
+
+    for name, text in _read_sources(args.paths):
+        try:
+            if args.command == "format":
+                out = format_calc(text, style)
+                if args.check:
+                    if out != text:
+                        print(f"would reformat {name}")
+                        rc = max(rc, 1)
+                elif args.write and name != "<stdin>":
+                    if out != text:
+                        Path(name).write_text(out, encoding="utf-8")
+                        print(f"reformatted {name}")
+                else:
+                    sys.stdout.write(out)
+            else:
+                for rule, message in lint_calc(text, style):
+                    print(f"{name}: {rule}: {message}")
+                    rc = max(rc, 1)
+        except (LexError, ParseError, FormatSafetyError) as exc:
+            print(f"{name}: error: {exc}", file=sys.stderr)
+            rc = 2
+
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main())

fmstyle/config.py

@@ -0,0 +1,105 @@
+"""Style configuration - the machine-readable half of an organisation's
+FileMaker guidelines. Defaults implement the Thomas DS style guide
+(filemaker_development_style_guide.md, sections 3-4).
+
+Per-function rules: every FileMaker (or custom) function name can get its own
+entry under "functions", controlling how that call is laid out:
+
+    "functions": {
+        "let":   { "layout": "let",   "multiline": "always" },
+        "while": { "layout": "while", "multiline": "always" },
+        "case":  { "layout": "pairs" },
+        "if":    { "multiline": "always" }
+    }
+
+layout:    "args"  - one argument per line (default for any function)
+           "pairs" - condition ; result pairs per line (Case-style)
+           "let"   - the mandatory Let block shape
+           "while" - the mandatory While block shape
+           "auto"  - same as "args"
+multiline: "auto"   - explode only when the call exceeds the line width
+           "always" - always explode, even when it would fit
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+
+_SIMPLE_KEYS = (
+    "width",
+    "let_blank_lines",
+    "lowercase_keywords",
+    "space_before_semicolon",
+    "result_name",
+    "local_variable_pattern",
+)
+
+VALID_LAYOUTS = {"auto", "args", "pairs", "let", "while", "leading"}
+VALID_MULTILINE = {"auto", "always"}
+
+DEFAULT_FUNCTIONS = {
+    "let": {"layout": "let", "multiline": "always"},
+    "while": {"layout": "while", "multiline": "always"},
+    "case": {"layout": "pairs"},
+}
+
+
+def _default_functions() -> dict:
+    return {name: dict(rule) for name, rule in DEFAULT_FUNCTIONS.items()}
+
+
+@dataclass
+class Style:
+    indent: str = "    "
+    width: int = 96
+    let_blank_lines: bool = True
+    lowercase_keywords: bool = True
+    space_before_semicolon: bool = True
+    result_name: str = "result"
+    local_variable_pattern: str = r"^[_a-z][A-Za-z0-9]*$"
+    functions: dict = field(default_factory=_default_functions)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Style":
+        known = {f.name for f in fields(cls)} | {"force_multiline", "indent"}
+        unknown = set(data) - known
+        if unknown:
+            raise ValueError(f"unknown style option(s): {', '.join(sorted(unknown))}")
+
+        kwargs = {k: data[k] for k in _SIMPLE_KEYS if k in data}
+        if "indent" in data:
+            v = data["indent"]
+            if v == "tab":
+                kwargs["indent"] = "\t"
+            elif isinstance(v, int):
+                kwargs["indent"] = " " * v
+            else:
+                kwargs["indent"] = v
+
+        functions = _default_functions()
+        if "force_multiline" in data:  # legacy shorthand for multiline: always
+            for rule in functions.values():
+                rule.pop("multiline", None)
+            for name in data["force_multiline"]:
+                functions.setdefault(name.lower(), {})["multiline"] = "always"
+        if "functions" in data:
+            for name, rule in data["functions"].items():
+                if not isinstance(rule, dict):
+                    raise ValueError(f"functions.{name} must be an object")
+                bad = set(rule) - {"layout", "multiline"}
+                if bad:
+                    raise ValueError(f"functions.{name}: unknown key(s) {', '.join(sorted(bad))}")
+                if "layout" in rule and rule["layout"] not in VALID_LAYOUTS:
+                    raise ValueError(f"functions.{name}.layout must be one of {sorted(VALID_LAYOUTS)}")
+                if "multiline" in rule and rule["multiline"] not in VALID_MULTILINE:
+                    raise ValueError(f"functions.{name}.multiline must be one of {sorted(VALID_MULTILINE)}")
+                functions.setdefault(name.lower(), {}).update(rule)
+        kwargs["functions"] = functions
+
+        return cls(**kwargs)
+
+    @classmethod
+    def load(cls, path: str | Path) -> "Style":
+        return cls.from_dict(json.loads(Path(path).read_text(encoding="utf-8")))

fmstyle/lexer.py

@@ -0,0 +1,272 @@
+"""Tokenizer for FileMaker calculation expressions.
+
+Design rules:
+
+- Verbatim tokens: a token's text is the exact source slice (field names keep
+  their original interior spacing), so the printer can never alter a name.
+- Comments ride on the next code token (`pre_comments`); the formatter's safety
+  check compares code tokens and comment texts of input vs output, so nothing
+  can be dropped silently.
+- Anything we do not understand raises LexError - the formatter then leaves the
+  source untouched instead of guessing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+KEYWORD_OPS = {"and", "or", "xor", "not"}
+TWO_CHAR_OPS = ("<>", "<=", ">=")
+SINGLE_CHAR_OPS = set("&+-*/^=<>≠≤≥")  # incl. != / <= / >= unicode forms
+
+
+class LexError(ValueError):
+    pass
+
+
+@dataclass
+class Comment:
+    text: str
+    own_line: bool  # True when only whitespace precedes it on its line
+
+
+@dataclass
+class Token:
+    kind: str  # NAME NUMBER STRING OP LPAREN RPAREN LBRACKET RBRACKET SEMI EOF
+    text: str
+    line: int
+    pre_comments: list = field(default_factory=list)
+
+
+UNICODE_OPS = "≠≤≥¶"
+
+
+def _is_name_char(ch: str) -> bool:
+    # ~ # . appear in real-world FileMaker names: $$~DISABLETRIGGERS,
+    # #ScriptResultJSON, Triggers.Disable, $sub.errorCode, Field~extra.
+    # Any non-ASCII char that is not an operator is a name char too
+    # (field names like "Rep 5¢ Commission" exist in the wild).
+    if ch.isalnum() or ch in "_~#.":
+        return True
+    return ord(ch) > 127 and ch not in UNICODE_OPS
+
+
+def _is_name_start(ch: str) -> bool:
+    if ch.isalpha() or ch in "_~#":
+        return True
+    return ord(ch) > 127 and ch not in UNICODE_OPS
+
+
+def _extend_name_run(s: str, end: int) -> int:
+    """Merge following space-separated words into one name (FileMaker field
+    names may contain spaces). Stops at keywords, operators, newlines, and
+    words that start a function call."""
+    n = len(s)
+    while True:
+        k = end
+        while k < n and s[k] in " \t":
+            k += 1
+        if k == end or k >= n or not _is_name_char(s[k]):
+            break
+        j = k
+        while j < n and _is_name_char(s[j]):
+            j += 1
+        if s[k:j].lower() in KEYWORD_OPS:
+            break
+        m = j
+        while m < n and s[m] in " \t":
+            m += 1
+        if m < n and s[m] == "(":  # that word is a function name
+            break
+        end = j
+    return end
+
+
+def _qualify(s: str, end: int, line: int) -> int:
+    """Extend a name across a `::` field qualifier if present."""
+    n = len(s)
+    m = end
+    while m < n and s[m] in " \t":
+        m += 1
+    if not s.startswith("::", m):
+        return end
+    m += 2
+    while m < n and s[m] in " \t":
+        m += 1
+    if s.startswith("${", m):
+        k = s.find("}", m)
+        if k == -1:
+            raise LexError(f"unterminated ${{...}} name (line {line})")
+        return k + 1
+    if m < n and _is_name_char(s[m]):
+        j = m
+        while j < n and _is_name_char(s[j]):
+            j += 1
+        return _extend_name_run(s, j)
+    raise LexError(f"expected a field name after '::' (line {line})")
+
+
+def tokenize(source: str) -> list[Token]:
+    n = len(source)
+    i = 0
+    line = 1
+    fresh = True  # only whitespace so far on the current line
+    pending: list[Comment] = []
+    tokens: list[Token] = []
+
+    def add(kind: str, text: str) -> None:
+        nonlocal pending, fresh
+        tokens.append(Token(kind, text, line, pending))
+        pending = []
+        fresh = False
+
+    while i < n:
+        ch = source[i]
+
+        if ch == "\n":
+            line += 1
+            i += 1
+            fresh = True
+            continue
+        if ch in " \t\r":
+            i += 1
+            continue
+
+        if source.startswith("//", i):
+            j = source.find("\n", i)
+            j = n if j == -1 else j
+            pending.append(Comment(source[i:j].rstrip(), fresh))
+            fresh = False
+            i = j
+            continue
+
+        if source.startswith("/*", i):
+            depth = 1
+            j = i + 2
+            while j < n and depth:
+                if source.startswith("/*", j):
+                    depth += 1
+                    j += 2
+                elif source.startswith("*/", j):
+                    depth -= 1
+                    j += 2
+                else:
+                    if source[j] == "\n":
+                        line += 1
+                    j += 1
+            if depth:
+                raise LexError(f"unterminated block comment (line {line})")
+            pending.append(Comment(source[i:j], fresh))
+            fresh = False
+            i = j
+            continue
+
+        if ch == '"':
+            j = i + 1
+            while j < n:
+                if source[j] == "\\":
+                    j += 2
+                    continue
+                if source[j] == '"':
+                    break
+                if source[j] == "\n":
+                    line += 1
+                j += 1
+            if j >= n:
+                raise LexError(f"unterminated string (line {line})")
+            add("STRING", source[i : j + 1])
+            i = j + 1
+            continue
+
+        if ch.isdigit() or (ch == "." and i + 1 < n and source[i + 1].isdigit()):
+            j = i
+            seen_dot = False
+            while j < n and (source[j].isdigit() or (source[j] == "." and not seen_dot)):
+                if source[j] == ".":
+                    seen_dot = True
+                j += 1
+            add("NUMBER", source[i:j])
+            i = j
+            continue
+
+        if ch == "$":
+            j = i
+            while j < n and source[j] == "$":
+                j += 1
+            if j - i > 2:
+                raise LexError(f"too many '$' (line {line})")
+            if j < n and source[j] == "{":
+                k = source.find("}", j)
+                if k == -1:
+                    raise LexError(f"unterminated ${{...}} name (line {line})")
+                end = _qualify(source, k + 1, line)
+                add("NAME", source[i:end])
+                i = end
+                continue
+            if j < n and _is_name_char(source[j]):
+                k = j
+                while k < n and _is_name_char(source[k]):
+                    k += 1
+                add("NAME", source[i:k])
+                i = k
+                continue
+            raise LexError(f"bare '$' (line {line})")
+
+        if ch == "¶":  # pilcrow literal
+            add("NAME", ch)
+            i += 1
+            continue
+
+        if _is_name_start(ch):
+            j = i
+            while j < n and _is_name_char(source[j]):
+                j += 1
+            if source[i:j].lower() in KEYWORD_OPS:
+                add("OP", source[i:j])
+                i = j
+                continue
+            end = _extend_name_run(source, j)
+            end = _qualify(source, end, line)
+            add("NAME", source[i:end])
+            i = end
+            continue
+
+        matched = False
+        for two in TWO_CHAR_OPS:
+            if source.startswith(two, i):
+                add("OP", two)
+                i += 2
+                matched = True
+                break
+        if matched:
+            continue
+
+        if ch in SINGLE_CHAR_OPS:
+            add("OP", ch)
+            i += 1
+            continue
+        if ch == "(":
+            add("LPAREN", ch)
+            i += 1
+            continue
+        if ch == ")":
+            add("RPAREN", ch)
+            i += 1
+            continue
+        if ch == "[":
+            add("LBRACKET", ch)
+            i += 1
+            continue
+        if ch == "]":
+            add("RBRACKET", ch)
+            i += 1
+            continue
+        if ch == ";":
+            add("SEMI", ch)
+            i += 1
+            continue
+
+        raise LexError(f"unexpected character {ch!r} (line {line})")
+
+    tokens.append(Token("EOF", "", line, pending))
+    return tokens