faf-python-sdk 1.1.2__py3-none-any.whl → 1.2.0__py3-none-any.whl

{faf_python_sdk-1.1.2.dist-info → faf_python_sdk-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: faf-python-sdk
-Version: 1.1.2
+Version: 1.2.0
 Summary: Persistent project context for Python — parse, validate, and score `.faf` files. The foundation other Python FAF tools (gemini-faf-mcp, custom MCP servers, CI validators) build on. IANA-registered application/vnd.faf+yaml.
 Project-URL: Homepage, https://faf.one
 Project-URL: Documentation, https://github.com/Wolfe-Jam/faf-python-sdk
@@ -32,17 +32,33 @@ Description-Content-Type: text/markdown
 
 # faf-python-sdk
 
-**Persistent project context for Python.** Parse, validate, and score `.faf` files — the foundation other Python FAF tools build on.
+**Persistent Project Context for Python. Parse, validate, score.**
 
-If you're building MCP servers, CI validators, or any Python tool that needs to understand project context, start here.
+**FAF defines. MD instructs. AI codes.**
 
+The foundation other Python FAF tools build on. If you're building MCP servers, CI validators, or any Python tool that needs to understand project context, start here.
+
+[![FAF](https://mcpaas.live/badge/Wolfe-Jam/faf-python-sdk.svg)](https://builder.faf.one)
 [![PyPI](https://img.shields.io/pypi/v/faf-python-sdk?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/faf-python-sdk/)
 [![Downloads](https://img.shields.io/pypi/dm/faf-python-sdk?style=for-the-badge&color=blue)](https://pypi.org/project/faf-python-sdk/)
-[![Tests](https://img.shields.io/badge/tests-175%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
+[![Tests](https://img.shields.io/badge/tests-196%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
 [![IANA](https://img.shields.io/badge/IANA-registered-informational?style=for-the-badge)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
 
 **Media Type:** `application/vnd.faf+yaml` (IANA registered)
 
+## What's New in v1.2.0 — The Dart Edition
+
+Adds `detect_dart_project()`: content-aware Dart/Flutter detection from a `pubspec.yaml` (Flutter app vs package · Dart MCP / backend / CLI / library), reproducing faf-cli's engine byte-for-byte — 20 shared fixtures, parity-tested.
+
+The SDK's first detection capability — it now reads a `pubspec.yaml` and tells you *what kind* of Dart project it is, not just parse/validate/score. The detection KNOWLEDGE is vendored byte-identical from faf-cli (the single source) and ships in the wheel:
+
+```python
+from faf_sdk import detect_dart_project
+
+d = detect_dart_project(".")
+print(d.app_type, d.framework)   # e.g. "mobile" "Flutter"
+```
+
 ## What's New in v1.1.0
 
 **Mk4 Championship Scoring Engine** — the same 33-slot scoring algorithm used by the Rust compiler and TypeScript CLI, now in Python. Same slots, same formula, same scores. Every FAF tool in every language now agrees on what 100% means.
@@ -175,6 +191,8 @@ root = find_project_root()
 | [grok-faf-mcp](https://npmjs.com/package/grok-faf-mcp) | xAI | npm |
 | [faf-cli](https://npmjs.com/package/faf-cli) | CLI | npm |
 
+If `faf-python-sdk` has been useful, consider starring the repo — it helps others find it.
+
 ## Links
 
 - **Site:** [faf.one](https://faf.one)

faf_python_sdk-1.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+faf_sdk/__init__.py,sha256=_rO6yyapx8eswbifcLkxYVOP0FCaBavvzjapi1msdkc,1611
+faf_sdk/dart_detection.json,sha256=jFtKnyyMVVFsunizteFZ2pLhYC1qC2nCIWQB9SdOqKE,1195
+faf_sdk/detect.py,sha256=GothQNKChKSEwke74MRy63VyBYLqOzN1j3yzjsSVpJA,6310
+faf_sdk/discovery.py,sha256=3Jj3lSzPAj9l0_VjJneLAwo1dMXvhneFhcVN4m2ejOw,8643
+faf_sdk/mk4.py,sha256=dA8o3YB0W19Mt_bqcR67HAw4S08zxj6IzEmubTy-pQY,5708
+faf_sdk/parser.py,sha256=lJJysj52X0Q_aGhl4PMXY2PuMqASFHdVRiSZFDdampk,4925
+faf_sdk/types.py,sha256=sm1ezSzCc-93bszr4ite31_xZRKjwqf2utlqN6_0QuM,6615
+faf_sdk/validator.py,sha256=6uneOwar4GYUF52BnAQTu159kE4mh4RWRgG6onVbiG4,5730
+faf_python_sdk-1.2.0.dist-info/METADATA,sha256=igeZU2Gia6yzOAQHAj0Xg49B6UciWl36uD6p7aR_OXk,8008
+faf_python_sdk-1.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+faf_python_sdk-1.2.0.dist-info/licenses/LICENSE,sha256=ARScF5tFhbQnYO2V5QAuCwhDHcxKdOWTOV81Pxx_j7U,1065
+faf_python_sdk-1.2.0.dist-info/RECORD,,

{faf_python_sdk-1.1.2.dist-info → faf_python_sdk-1.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.29.0
+Generator: hatchling 1.30.1
 Root-Is-Purelib: true
 Tag: py3-none-any

faf_sdk/__init__.py

@@ -24,6 +24,7 @@ from .parser import parse, parse_file, stringify, FafFile
 from .validator import validate, ValidationResult
 from .mk4 import score_faf, Mk4Result, SlotState, LicenseTier
 from .discovery import find_faf_file, find_project_root, load_fafignore
+from .detect import detect_dart_project, DartProject
 from .types import (
     FafData,
     ProjectInfo,
@@ -34,7 +35,7 @@ from .types import (
     AIScoring
 )
 
-__version__ = "1.1.2"
+__version__ = "1.2.0"
 __all__ = [
     # Parser
     "parse",
@@ -53,6 +54,9 @@ __all__ = [
     "find_faf_file",
     "find_project_root",
     "load_fafignore",
+    # Detection (Dart/Flutter — A+B hybrid, parity with faf-cli)
+    "detect_dart_project",
+    "DartProject",
     # Types
     "FafData",
     "ProjectInfo",

faf_sdk/dart_detection.json

@@ -0,0 +1,30 @@
+{
+  "version": 1,
+  "_doc": "SINGLE SOURCE of Dart/Flutter detection KNOWLEDGE (A+B hybrid, the Truth-is-faf-cli spec). faf-cli imports this directly; faf-python-sdk vendors a synced copy (phase 2); MCPs consume the SDK (phase 3). To bolster Dart/Flutter support — a new state library, server framework, MCP dep — edit THIS file and every engine inherits it. The thin per-language LOGIC (pubspec parse, app-vs-package heuristic, priority branching) lives in code, not here.",
+  "flutterDeps": ["flutter"],
+  "mcpDeps": ["dart_mcp", "mcp_server", "mcp_dart", "dart_mcp_server", "mcp"],
+  "serverFrameworks": [
+    ["serverpod", "Serverpod"],
+    ["dart_frog", "Dart Frog"],
+    ["conduit", "Conduit"],
+    ["angel3_framework", "Angel3"],
+    ["alfred", "Alfred"],
+    ["shelf", "Shelf"]
+  ],
+  "stateManagement": [
+    ["flutter_riverpod", "Riverpod"],
+    ["hooks_riverpod", "Riverpod"],
+    ["riverpod", "Riverpod"],
+    ["flutter_bloc", "Bloc"],
+    ["bloc", "Bloc"],
+    ["provider", "Provider"],
+    ["get", "GetX"],
+    ["flutter_mobx", "MobX"],
+    ["mobx", "MobX"],
+    ["signals", "Signals"]
+  ],
+  "routing": [
+    ["go_router", "go_router"],
+    ["auto_route", "auto_route"]
+  ]
+}

faf_sdk/detect.py

@@ -0,0 +1,167 @@
+"""
+Dart/Flutter detection — CONTENT-AWARE pubspec classification (Python).
+
+PARITY: this mirrors faf-cli src/detect/dart.ts EXACTLY. A pubspec.yaml alone
+does NOT mean Flutter — the same manifest backs Flutter apps, pure-Dart CLIs,
+packages, servers (Dart Frog / Shelf / Serverpod) and MCP servers
+(dart_mcp / mcp_server). We read the dependencies and branch.
+
+The detection KNOWLEDGE (which deps mean what) lives in dart_detection.json —
+a byte-identical, synced copy of faf-cli's src/detect/dart-detection.json (the
+single source, A+B hybrid). To bolster Dart support, edit the spec in faf-cli
+(the Truth) and re-run scripts/sync-dart-spec.sh. The thin per-language LOGIC
+(pubspec parse, app-vs-package heuristic, priority branching) lives here.
+
+Behavior parity with faf-cli is PROVEN by tests/test_dart_parity.py, which runs
+the SAME shared fixtures faf-cli runs in tests/detect/dart-parity.test.ts.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+_SPEC: Dict[str, Any] = json.loads(
+    (Path(__file__).parent / "dart_detection.json").read_text(encoding="utf-8")
+)
+
+# Detection KNOWLEDGE — sourced from dart_detection.json, never hand-listed here.
+FLUTTER_DEPS: List[str] = list(_SPEC["flutterDeps"])
+MCP_DEPS: List[str] = list(_SPEC["mcpDeps"])
+SERVER_FRAMEWORKS: List[List[str]] = [list(e) for e in _SPEC["serverFrameworks"]]
+STATE_MGMT: List[List[str]] = [list(e) for e in _SPEC["stateManagement"]]
+ROUTING: List[List[str]] = [list(e) for e in _SPEC["routing"]]
+
+
+@dataclass
+class DartProject:
+    """Classification of a Dart/Flutter project from its pubspec.yaml."""
+
+    app_type: str  # 'mobile' | 'mcp' | 'backend' | 'cli' | 'library'
+    is_flutter: bool
+    framework: str  # 'Flutter' | 'Dart Frog' | 'Serverpod' | 'Shelf' | ... | ''
+    state_management: str  # 'Riverpod' | 'Bloc' | 'Provider' | 'GetX' | ... | ''
+    routing: str  # 'go_router' | 'auto_route' | ''
+    testing: str  # 'flutter_test' | 'test' | ''
+    found: str  # human-readable rationale for the .faf `# found:` comment
+
+    def to_dict(self) -> Dict[str, object]:
+        """Project to the faf-cli DartProject shape (camelCase) for parity checks."""
+        return {
+            "appType": self.app_type,
+            "isFlutter": self.is_flutter,
+            "framework": self.framework,
+            "stateManagement": self.state_management,
+            "routing": self.routing,
+            "testing": self.testing,
+            "found": self.found,
+        }
+
+
+def _pubspec_deps(content: str) -> Set[str]:
+    """Collect dependency names from dependencies / dev_dependencies sections."""
+    deps: Set[str] = set()
+    in_deps = False
+    for line in content.split("\n"):
+        if re.match(r"^(dependencies|dev_dependencies|dependency_overrides):\s*$", line):
+            in_deps = True
+            continue
+        # A new top-level key (no leading whitespace) ends the dependency section.
+        if re.match(r"^\S", line):
+            in_deps = False
+        if in_deps:
+            m = re.match(r"^\s{2}([a-zA-Z0-9_]+):", line)
+            if m:
+                deps.add(m.group(1).lower())
+    return deps
+
+
+def detect_dart_project(directory: str) -> Optional[DartProject]:
+    """Classify a Dart/Flutter project from its pubspec.yaml. None if not Dart."""
+    path = Path(directory) / "pubspec.yaml"
+    if not path.exists():
+        return None
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    deps = _pubspec_deps(content)
+
+    def has(dep: str) -> bool:
+        return dep.lower() in deps
+
+    # Flutter: the `flutter` SDK dep, a top-level `flutter:` section, or `sdk: flutter`.
+    is_flutter = (
+        any(has(d) for d in FLUTTER_DEPS)
+        or re.search(r"^flutter:\s*$", content, re.MULTILINE) is not None
+        or re.search(r"\bsdk:\s*flutter\b", content) is not None
+    )
+
+    mcp_dep = next((d for d in MCP_DEPS if has(d)), None)
+    server = next((e for e in SERVER_FRAMEWORKS if has(e[0])), None)
+    state_entry = next((e for e in STATE_MGMT if has(e[0])), None)
+    state_management = state_entry[1] if state_entry else ""
+    route_entry = next((e for e in ROUTING if has(e[0])), None)
+    routing = route_entry[1] if route_entry else ""
+    testing = "flutter_test" if has("flutter_test") else ("test" if has("test") else "")
+
+    # CLI: a top-level `executables:` section, or bin/*.dart entry points.
+    has_executables = re.search(r"^executables:\s*$", content, re.MULTILINE) is not None
+    has_bin_dart = False
+    bin_dir = Path(directory) / "bin"
+    if bin_dir.is_dir():
+        try:
+            has_bin_dart = any(f.endswith(".dart") for f in os.listdir(bin_dir))
+        except OSError:
+            has_bin_dart = False
+    is_cli = has_executables or has_bin_dart
+
+    framework = ""
+    app_type: str
+    found: str
+
+    if is_flutter:
+        framework = "Flutter"
+        # App vs package: an app has lib/main.dart (the entry) or `publish_to: none`;
+        # a reusable Flutter package has neither — it's publishable, lib/ exports only.
+        is_app = (Path(directory) / "lib" / "main.dart").exists() or (
+            re.search(r"^publish_to:\s*['\"]?none\b", content, re.MULTILINE) is not None
+        )
+        if is_app:
+            app_type = "mobile"
+            found = "pubspec.yaml (Flutter app)"
+        else:
+            app_type = "library"
+            found = "pubspec.yaml (Flutter package)"
+    elif mcp_dep:
+        app_type = "mcp"
+        found = f"pubspec.yaml + {mcp_dep} (Dart MCP server)"
+    elif server:
+        app_type = "backend"
+        framework = server[1]
+        found = f"pubspec.yaml + {server[0]} (Dart backend)"
+    elif is_cli:
+        app_type = "cli"
+        found = (
+            "pubspec.yaml executables: (Dart CLI)"
+            if has_executables
+            else "pubspec.yaml + bin/*.dart (Dart CLI)"
+        )
+    else:
+        app_type = "library"
+        found = "pubspec.yaml (Dart package)"
+
+    return DartProject(
+        app_type=app_type,
+        is_flutter=is_flutter,
+        framework=framework,
+        state_management=state_management,
+        routing=routing,
+        testing=testing,
+        found=found,
+    )

faf_python_sdk-1.1.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-faf_sdk/__init__.py,sha256=mN9DPryL9_sPv-QVw-rZGS6u8dcVDvB1UNu2GGQg7Pk,1445
-faf_sdk/discovery.py,sha256=3Jj3lSzPAj9l0_VjJneLAwo1dMXvhneFhcVN4m2ejOw,8643
-faf_sdk/mk4.py,sha256=dA8o3YB0W19Mt_bqcR67HAw4S08zxj6IzEmubTy-pQY,5708
-faf_sdk/parser.py,sha256=lJJysj52X0Q_aGhl4PMXY2PuMqASFHdVRiSZFDdampk,4925
-faf_sdk/types.py,sha256=sm1ezSzCc-93bszr4ite31_xZRKjwqf2utlqN6_0QuM,6615
-faf_sdk/validator.py,sha256=6uneOwar4GYUF52BnAQTu159kE4mh4RWRgG6onVbiG4,5730
-faf_python_sdk-1.1.2.dist-info/METADATA,sha256=ReVbpyLAD3PG_vInHUbkfJTnarFcmdBrhl_zvd_t_D4,7116
-faf_python_sdk-1.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-faf_python_sdk-1.1.2.dist-info/licenses/LICENSE,sha256=ARScF5tFhbQnYO2V5QAuCwhDHcxKdOWTOV81Pxx_j7U,1065
-faf_python_sdk-1.1.2.dist-info/RECORD,,