Feature Flags skill for Claude Code

#!/usr/bin/env python3
"""Audit feature flag usage in source code against a flag registry.

Usage:
  python3 scripts/flag_audit.py --src src [--src web] [--registry flags.json]
                                [--pattern REGEX] [--today 2026-10-19] [--json]

Finds flag keys referenced in code (default pattern matches common SDK calls such as
isEnabled("key"), getBooleanValue('key', ...), variation("key", ...), useFlag("key"),
is_enabled("key")). Supply --pattern with exactly one capture group for the key to match
a project-specific helper.

Registry file (optional): JSON list of objects like
  {"key": "checkout.new-form", "type": "release", "owner": "team-payments",
   "created": "2026-05-02", "expires": "2026-07-01"}
type is one of release | experiment | ops | permission. ops and permission flags are
long-lived and exempt from expiry checks.

Reports: references per flag, flags used in code but missing from the registry,
registry flags with no code references (candidates to delete in the provider),
release/experiment flags past their expiry date, and missing owner/expiry metadata.

Exit codes: 0 = clean, 1 = problems found, 2 = bad arguments or registry.
"""
import argparse
import datetime as dt
import json
import os
import re
import sys
from collections import defaultdict

DEFAULT_PATTERN = (
    r"""(?:isEnabled|isFeatureEnabled|getBooleanValue|getStringValue|getNumberValue|getObjectValue|"""
    r"""getBooleanDetails|boolVariation|stringVariation|variation|useFlag|useFeatureFlag|useBooleanFlagValue|"""
    r"""is_enabled|get_boolean_value|get_string_value|feature_enabled)\s*\(\s*['"]([A-Za-z0-9_.:\-/]+)['"]"""
)
EXTS = {".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".rb", ".go", ".java", ".kt",
        ".cs", ".php", ".swift", ".vue", ".svelte"}
SKIP_DIRS = {"node_modules", ".git", "dist", "build", "vendor", ".next", "coverage", "__pycache__", ".venv"}
LONG_LIVED = {"ops", "permission"}


def scan(paths, pattern):
    refs = defaultdict(list)
    rx = re.compile(pattern)
    for base in paths:
        for root, dirs, files in os.walk(base):
            dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
            for f in files:
                if os.path.splitext(f)[1] not in EXTS:
                    continue
                path = os.path.join(root, f)
                try:
                    with open(path, encoding="utf-8", errors="ignore") as fh:
                        for lineno, line in enumerate(fh, 1):
                            for m in rx.finditer(line):
                                refs[m.group(1)].append(f"{path}:{lineno}")
                except OSError:
                    continue
    return refs


def load_registry(path):
    try:
        with open(path, encoding="utf-8") as fh:
            data = json.load(fh)
    except (OSError, json.JSONDecodeError) as exc:
        print(f"error: cannot read registry {path}: {exc}", file=sys.stderr)
        sys.exit(2)
    if isinstance(data, dict) and "flags" in data:
        data = data["flags"]
    if not isinstance(data, list):
        print("error: registry must be a JSON list of flag objects (or {\"flags\": [...]})", file=sys.stderr)
        sys.exit(2)
    return {item["key"]: item for item in data if isinstance(item, dict) and "key" in item}


def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--src", action="append", required=True, help="source directory (repeatable)")
    ap.add_argument("--registry")
    ap.add_argument("--pattern", default=DEFAULT_PATTERN)
    ap.add_argument("--today", default=dt.date.today().isoformat())
    ap.add_argument("--json", action="store_true")
    args = ap.parse_args()

    try:
        if re.compile(args.pattern).groups != 1:
            raise ValueError("pattern must have exactly one capture group")
        today = dt.date.fromisoformat(args.today)
    except (re.error, ValueError) as exc:
        print(f"error: {exc}", file=sys.stderr)
        sys.exit(2)

    refs = scan(args.src, args.pattern)
    report = {"references": {k: v for k, v in sorted(refs.items())},
              "unregistered": [], "unreferenced": [], "expired": [], "missing_metadata": []}

    if args.registry:
        reg = load_registry(args.registry)
        report["unregistered"] = sorted(k for k in refs if k not in reg)
        report["unreferenced"] = sorted(k for k in reg if k not in refs)
        for key, meta in sorted(reg.items()):
            ftype = meta.get("type", "release")
            missing = [f for f in ("owner", "type") if not meta.get(f)]
            if ftype not in LONG_LIVED and not meta.get("expires"):
                missing.append("expires")
            if missing:
                report["missing_metadata"].append({"key": key, "missing": missing})
            exp = meta.get("expires")
            if ftype not in LONG_LIVED and exp:
                try:
                    if dt.date.fromisoformat(exp) < today:
                        report["expired"].append({"key": key, "expires": exp, "owner": meta.get("owner"),
                                                  "still_referenced": key in refs})
                except ValueError:
                    report["missing_metadata"].append({"key": key, "missing": [f"valid expires (got {exp!r})"]})

    problems = (len(report["unregistered"]) + len(report["expired"]) + len(report["missing_metadata"]))

    if args.json:
        print(json.dumps(report, indent=2))
    else:
        print(f"Flags referenced in code: {len(refs)}")
        for key, locs in sorted(refs.items(), key=lambda kv: -len(kv[1])):
            print(f"  {len(locs):4}  {key}   e.g. {locs[0]}")
        if args.registry:
            def section(title, items, fmt):
                print(f"\n{title} ({len(items)})")
                for it in items:
                    print("  " + fmt(it))
            section("EXPIRED release/experiment flags", report["expired"],
                    lambda e: f"{e['key']} expired {e['expires']} owner={e['owner']} "
                              f"{'(still in code: remove)' if e['still_referenced'] else '(code gone: delete in provider)'}")
            section("UNREGISTERED flags used in code", report["unregistered"], str)
            section("MISSING metadata", report["missing_metadata"],
                    lambda m: f"{m['key']}: missing {', '.join(m['missing'])}")
            section("Registry flags with no code references (delete in provider after deploy)",
                    report["unreferenced"], str)
        print(f"\nRESULT: {'PROBLEMS FOUND' if problems else 'clean'}")
    sys.exit(1 if problems else 0)


if __name__ == "__main__":
    main()