feature-map-cli 1.0.0__py3-none-any.whl

feature_map/validate.py

@@ -0,0 +1,148 @@
+import json
+import re
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+import yaml
+
+from feature_map.loader import extract_related_slug, normalize_slug
+from feature_map.paths import schema_path
+
+REQUIRED_KEYS = ["feature_name", "purpose", "entry_points"]
+RECOMMENDED_KEYS = ["apps", "user_flow", "related_features"]
+
+_SCHEMA_CACHE = None
+
+
+def load_schema() -> dict:
+    global _SCHEMA_CACHE
+    if _SCHEMA_CACHE is None:
+        _SCHEMA_CACHE = json.loads(schema_path().read_text(encoding="utf-8"))
+    return _SCHEMA_CACHE
+
+
+def _matches_schema_type(value, types: List[str]) -> bool:
+    if "string" in types and isinstance(value, str):
+        return True
+    if "array" in types and isinstance(value, list):
+        return True
+    if "object" in types and isinstance(value, dict):
+        return True
+    if "null" in types and value is None:
+        return True
+    return False
+
+
+def validate_against_schema(data: dict) -> List[str]:
+    schema = load_schema()
+    errors: List[str] = []
+
+    for key in schema.get("required", []):
+        if key not in data or data[key] in (None, "", []):
+            errors.append(f"missing required key '{key}' (schema)")
+
+    properties = schema.get("properties", {})
+    for key, spec in properties.items():
+        if key not in data:
+            continue
+        value = data[key]
+        expected = spec.get("type")
+        if not expected:
+            continue
+        if isinstance(expected, str):
+            expected = [expected]
+        if not _matches_schema_type(value, expected):
+            errors.append(f"'{key}' has invalid type per schema")
+            continue
+        if key == "entry_points" and isinstance(value, list):
+            min_items = spec.get("minItems", 0)
+            if len(value) < min_items:
+                errors.append(f"'entry_points' must have at least {min_items} item(s) (schema)")
+        if isinstance(value, str) and spec.get("minLength"):
+            if len(value) < spec["minLength"]:
+                errors.append(f"'{key}' is too short per schema")
+
+    return errors
+
+
+def _extract_field_from_text(text: str, key: str) -> Optional[str]:
+    match = re.search(rf"^{re.escape(key)}:\s*(.+)$", text, re.MULTILINE)
+    if not match:
+        return None
+    return match.group(1).strip().strip('"').strip("'")
+
+
+def validate_map_file(
+    path: Path,
+    all_slugs: set,
+    strict: bool = False,
+) -> Tuple[List[str], List[str]]:
+    errors: List[str] = []
+    warnings: List[str] = []
+    text = path.read_text(encoding="utf-8")
+    data = None
+
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        parse_error = str(exc)
+        if strict:
+            errors.append(f"{path.name}: YAML parse error: {parse_error}")
+        else:
+            warnings.append(
+                f"{path.name}: YAML parse error (skipped structural checks): {parse_error}"
+            )
+
+    stem = path.stem
+    if data is not None:
+        if not isinstance(data, dict):
+            errors.append(f"{path.name}: root must be a mapping")
+            return errors, warnings
+
+        schema_errors = validate_against_schema(data)
+        for msg in schema_errors:
+            full = f"{path.name}: {msg}"
+            if strict:
+                errors.append(full)
+            else:
+                warnings.append(full)
+
+        feature_name = data.get("feature_name")
+        if feature_name:
+            normalized = normalize_slug(str(feature_name))
+            if normalized != normalize_slug(stem):
+                warnings.append(
+                    f"{path.name}: feature_name '{feature_name}' "
+                    f"does not match filename stem '{stem}'"
+                )
+
+        for key in RECOMMENDED_KEYS:
+            if key not in data or data[key] in (None, "", []):
+                warnings.append(f"{path.name}: missing recommended key '{key}'")
+
+        related = data.get("related_features") or []
+        if isinstance(related, list):
+            for entry in related:
+                slug = extract_related_slug(entry)
+                if slug and slug not in all_slugs:
+                    warnings.append(
+                        f"{path.name}: related_features entry '{entry}' "
+                        f"does not resolve to an existing map (slug: {slug})"
+                    )
+    else:
+        schema = load_schema()
+        for key in schema.get("required", REQUIRED_KEYS):
+            if not _extract_field_from_text(text, key):
+                msg = f"{path.name}: missing required key '{key}' (text scan)"
+                if strict:
+                    errors.append(msg)
+                else:
+                    warnings.append(msg)
+        feature_name = _extract_field_from_text(text, "feature_name")
+        if feature_name and normalize_slug(feature_name) != normalize_slug(stem):
+            warnings.append(
+                f"{path.name}: feature_name '{feature_name}' "
+                f"does not match filename stem '{stem}' (text scan)"
+            )
+
+    return errors, warnings

feature_map_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: feature-map-cli
+Version: 1.0.0
+Summary: Cross-app architecture research CLI driven by .features/*.yaml maps
+Project-URL: Homepage, https://github.com/markschellhas/feature-map
+Project-URL: Repository, https://github.com/markschellhas/feature-map
+Author: Taptics
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,architecture,cli,feature-map
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.8
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Feature Map
+
+Cross-app architecture research CLI. Agents and engineers keep authoritative
+feature maps in `.features/*.yaml`; `feature-map` lists, searches, validates,
+and graphs them.
+
+A wiki stores architecture as prose — agents re-read a whole page to find three
+files. Feature Map stores **fields** (`purpose`, `entry_points`, `apps`) and a
+CLI that returns **names and sections**, so lookup is cheap and `check` can
+prove paths still exist.
+
+## Install
+
+```bash
+pip install -e .
+# pip install feature-map-cli
+# brew install feature-map
+```
+
+Requires Python 3.8+ and PyYAML. The CLI is `feature-map`. Install from PyPI as
+`feature-map-cli` — `pip install featuremap` is a different (biology) project,
+and `feature-map` is blocked on PyPI as too similar to that name.
+
+## Usage
+
+```bash
+cd my-repo
+feature-map init
+feature-map init auth          # scaffold .features/auth.yaml
+feature-map list
+feature-map search billing
+feature-map validate
+```
+
+`feature-map init` is idempotent. It:
+
+1. Creates `.features/`
+2. Copies the agent skill to `.agents/skills/feature-map/` (or `.grok/skills/` if that tree already exists)
+3. Writes `.feature-map.yaml` defaults when missing
+4. Appends an `AGENTS.md` block (skip with `--no-agents`)
+5. Writes `bin/feature-map` as a repo-local shim (skip with `--no-shim`)
+
+Refresh the skill after upgrading the package:
+
+```bash
+feature-map init --upgrade-skill
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `list` | All feature slugs |
+| `show <name>` / `<name>` | Print a map (or `--section`) |
+| `search <query>` | Full-text search |
+| `find <path>` | Reverse lookup by path fragment |
+| `graph [name]` | `related_features` graph (`mermaid`, `json`, `dot`) |
+| `validate [--strict]` | Structural checks |
+| `check` | Stale `entry_points` / `core_components` paths |
+| `impact <file>` | Which maps reference a file |
+| `stats` | Coverage summary |
+| `init` / `init <name>` | Bootstrap repo or scaffold a map |
+| `install` | Setup status |
+| `--json` / `--version` | Machine output / version |
+
+Exit codes: `0` ok, `1` user error, `2` validation failure (`--strict`).
+
+## Per-repo config
+
+`.feature-map.yaml` at the git root:
+
+```yaml
+features_dir: .features
+apps:
+  - api
+  - web
+required_sections:
+  - purpose
+  - entry_points
+min_cli_version: "1.0.0"
+```
+
+`apps` prefixes are used by `check` when resolving paths.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+python -m pytest -q
+```
+
+## License
+
+MIT

feature_map_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,40 @@
+feature_map/__init__.py,sha256=7R2sGclRtd0nksKa47lnjtXvJglHAmAMtTMbjGY6QrY,72
+feature_map/__main__.py,sha256=ihpYQS0sITrj2CLf0pAJE2PdMkBm3sggCwVwbrD9uew,59
+feature_map/_version.py,sha256=Aj77VL1d5Mdku7sgCgKQmPuYavPpAHuZuJcy6bygQZE,21
+feature_map/bootstrap.py,sha256=T0xCn6h4SwZD_2ufmwgDXNTn7DtTDY3scyGmb_G1F_Y,5958
+feature_map/cli.py,sha256=PPoM_uzyRsSzK61tLOyC1cVOV00jBqtKUpYlJvXa2pM,8469
+feature_map/config.py,sha256=YVjjRt8YI5ZqhxF8efdS6UbOwezrD116OfKoBXF6QpA,728
+feature_map/discover.py,sha256=Sc4mi8Qz5bBPwrJseJTe3mLISlGScqpF9PbpV9Ksu-c,1480
+feature_map/errors.py,sha256=-DFSBcqH4hDdJ_H2DpBIKJ-EvT8Mp-PS-d9l8J7Lx0U,633
+feature_map/graph.py,sha256=CCq2jvqQqA8x9oDeU1HSOk4fNZg9yDctXI0HX2-6MPA,2178
+feature_map/loader.py,sha256=iKPo0G4cOvGzVuX2EBrhLUdOoiUs_QsGs27LHqvsQGQ,1679
+feature_map/output.py,sha256=l5opHNvMgP6WjmC41gi0f8RK1xTVnR3xjlfDvL_GoGo,1545
+feature_map/path_extract.py,sha256=0vxAqlbam2pxw7DhLy0sM5f5XDQFc5MylUMJJgDskP8,4650
+feature_map/path_normalize.py,sha256=kPm97cFWYgaAVHxkHkZ7XNo1nMIubL6Jtik3fhwmq9g,3002
+feature_map/path_resolve.py,sha256=XkoJ7XP3xQMbDLn_HS5TnNV5_zMjpmYBnL4w2SdomR4,1331
+feature_map/paths.py,sha256=uStjrRgLq-yXLYE1VM_mgi7FZm-R_RE9IMhB5kcrAGQ,840
+feature_map/text_index.py,sha256=aSjQjNtClGYTWbb8gGEbD-Atap6wnYB8Z4Y4fU5oM2c,1471
+feature_map/validate.py,sha256=HGipWF54wWX-0C_VkUhEmlUCQtMnqyypMNp2uvXzKZU,5045
+feature_map/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+feature_map/commands/check_cmd.py,sha256=0jZMUsPniUWI6XGa4lAz-S4-qbyfzAie58b7cSbhgl4,549
+feature_map/commands/find_cmd.py,sha256=TJmzwteLZMQi2qmq05ut20tGiFGx40zc8Lkaah3DSnw,1014
+feature_map/commands/graph_cmd.py,sha256=Kd4vCSJgyym7zQ8Q5dB3Y_sOVoUhBYS_gxHycPExuHo,513
+feature_map/commands/impact_cmd.py,sha256=fzMUUUDo2-7p2VUiQJ0m7XPGNkEvAMyvpOwDiDOek5A,1395
+feature_map/commands/init_cmd.py,sha256=OyMgkpCzMyNQwunogzEHJFLK-IlQowL6U61rT2TCUj0,2199
+feature_map/commands/install_cmd.py,sha256=EyYh4lPtAFvqtvgALaMXu3WYpvnX4IdUeIBDEanlhQY,2230
+feature_map/commands/list_cmd.py,sha256=3bdus0wN-5tvY_WlhxoJ-4omuQREAGaYL8nCI5heUiY,1151
+feature_map/commands/search_cmd.py,sha256=au8K8lRGQmnAsWp1s5e2bLl7PLnHfBSGyEssKcc6xd4,570
+feature_map/commands/show_cmd.py,sha256=LXqk_JS72rvrxEPKMlxS1wKJ7iMr6DI3gnGKeEYChfo,1187
+feature_map/commands/stats_cmd.py,sha256=QEia1g-4-VmKtlVdvF1x01kqiw7pAV3w1CeL1xUTdqg,2656
+feature_map/commands/validate_cmd.py,sha256=BxKaHC0H-RK8uVeOgnhHRJbH-hio9pvkJt0T7G1LeCc,1815
+feature_map/share/schema/feature-map.schema.json,sha256=FvsBJHUqYN-fS6eoYBMOoeIZgL3iaPpxeE2nQMCJkcU,738
+feature_map/share/skill/SKILL.md,sha256=krgCWNB8sZkwmAqnXXWKnv29c2vWpBb8mOB6l2n7U2U,2431
+feature_map/share/skill/references/authoring.md,sha256=MG1x1XqlO9bBLZjDMeFmvAq7Ppy8qTO3mhhXbulVZ_0,1772
+feature_map/share/skill/references/commands.md,sha256=x8y0m30umCpfzOEBy5bF8bG-ATh78JE5xoNhuSjZutg,1605
+feature_map/share/skill/references/existing-repos.md,sha256=TFO_OmeoJ_4ykL8PXpOf65Q5e2uYyVaxcCZE5Fpj07g,1917
+feature_map/share/templates/feature.yaml.tpl,sha256=jI7vR3aD5KtpO7iH-IXNU5gQkxCCXEMKOboQPbCOn7g,349
+feature_map_cli-1.0.0.dist-info/METADATA,sha256=Hi6yxAZHE5pcPC_Y8M1RnVi_MJFJsDwoqvXbKWwrQ_c,3529
+feature_map_cli-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+feature_map_cli-1.0.0.dist-info/entry_points.txt,sha256=r5crp3ooQAmyCHdhZhQ7WWv8hwdrD-7RQAm7s2iZNis,53
+feature_map_cli-1.0.0.dist-info/licenses/LICENSE,sha256=H-CvmWwZCsQxUa5fWXoYmOTLK5DyLvPkxdjt6ZxppdE,1064
+feature_map_cli-1.0.0.dist-info/RECORD,,

feature_map_cli-1.0.0.dist-info/WHEEL

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

feature_map_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+feature-map = feature_map.cli:main

feature_map_cli-1.0.0.dist-info/licenses/LICENSE

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