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

feature_map/path_extract.py

@@ -0,0 +1,139 @@
+import re
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+import yaml
+
+from feature_map.path_normalize import normalize_path_candidate
+from feature_map.path_resolve import resolve_candidate_paths
+
+__all__ = [
+    "normalize_path_candidate",
+    "resolve_candidate_paths",
+    "extract_paths_from_map",
+    "collect_corpus_strings",
+    "check_paths",
+]
+
+
+def _extract_from_value(value) -> List[str]:
+    paths: List[str] = []
+    if isinstance(value, str):
+        candidate = normalize_path_candidate(value)
+        if candidate:
+            paths.append(candidate)
+    elif isinstance(value, list):
+        for item in value:
+            paths.extend(_extract_from_value(item))
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            if isinstance(key, str):
+                key_path = normalize_path_candidate(key)
+                if key_path:
+                    paths.append(key_path)
+            paths.extend(_extract_from_value(item))
+    return paths
+
+
+def extract_paths_from_map(data: dict) -> List[str]:
+    paths: List[str] = []
+    seen = set()
+
+    def add(path: Optional[str]):
+        if path and path not in seen:
+            seen.add(path)
+            paths.append(path)
+
+    for section in ("entry_points", "core_components"):
+        section_data = data.get(section)
+        if section_data is None:
+            continue
+        if section == "core_components" and isinstance(section_data, dict):
+            for val in section_data.values():
+                for path in _extract_from_value(val):
+                    add(path)
+        else:
+            for path in _extract_from_value(section_data):
+                add(path)
+
+    return paths
+
+
+def _text_scan_section_strings(text: str, section: str) -> List[str]:
+    """Extract list-ish string lines from a section when YAML parse fails."""
+    strings: List[str] = []
+    match = re.search(rf"^{re.escape(section)}:\s*\n", text, re.MULTILINE)
+    if not match:
+        return strings
+    start = match.end()
+    rest = text[start:]
+    end_match = re.search(r"^\w[\w_]*:\s", rest, re.MULTILINE)
+    block = rest[: end_match.start()] if end_match else rest
+    for line in block.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("- "):
+            strings.append(stripped[2:].strip().strip('"').strip("'"))
+    return strings
+
+
+def collect_corpus_strings(features_dir: Path) -> List[tuple]:
+    """Return (feature_slug, raw_string) pairs from entry_points + core_components."""
+    corpus: List[tuple] = []
+    for map_path in sorted(features_dir.glob("*.yaml")):
+        text = map_path.read_text(encoding="utf-8")
+        try:
+            data = yaml.safe_load(text) or {}
+            if isinstance(data, dict):
+                for section in ("entry_points", "core_components"):
+                    section_data = data.get(section)
+                    if section_data is None:
+                        continue
+                    for raw in _flatten_strings(section_data):
+                        corpus.append((map_path.stem, raw))
+                continue
+        except yaml.YAMLError:
+            pass
+        for section in ("entry_points", "core_components"):
+            for raw in _text_scan_section_strings(text, section):
+                corpus.append((map_path.stem, raw))
+    return corpus
+
+
+def _flatten_strings(value) -> List[str]:
+    out: List[str] = []
+    if isinstance(value, str):
+        out.append(value)
+    elif isinstance(value, list):
+        for item in value:
+            out.extend(_flatten_strings(item))
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            if isinstance(key, str):
+                out.append(key)
+            out.extend(_flatten_strings(item))
+    return out
+
+
+def check_paths(features_dir: Path, repo_root: Path, apps: List[str]) -> List[dict]:
+    issues = []
+    for map_path in sorted(features_dir.glob("*.yaml")):
+        try:
+            data = yaml.safe_load(map_path.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError:
+            continue
+        if not isinstance(data, dict):
+            continue
+        for clean_path in extract_paths_from_map(data):
+            exists = any(
+                candidate.exists()
+                for candidate in resolve_candidate_paths(clean_path, repo_root, apps)
+            )
+            if not exists:
+                issues.append(
+                    {
+                        "feature": map_path.stem,
+                        "path": clean_path,
+                        "status": "missing",
+                    }
+                )
+    return issues

feature_map/path_normalize.py

@@ -0,0 +1,100 @@
+import re
+from typing import Optional
+
+HTTP_METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS")
+PATH_EXTENSIONS = (".rb", ".js", ".erb", ".svelte", ".ts", ".tsx", ".py", ".go", ".yaml", ".yml")
+PATH_PREFIXES = ("app/", "src/", "lib/", "config/", "pkg/", "internal/", "rails/")
+EXT_PATTERN = r"\.(?:rb|js|erb|svelte|ts|tsx|py|go|yaml|yml)"
+LINE_RANGE_RE = re.compile(r":\d+(?:-\d+)?$")
+
+
+def looks_like_file_path(value: str) -> bool:
+    if not value or " " in value:
+        return False
+    if LINE_RANGE_RE.search(value):
+        return False
+    if ":" in value and not value.startswith(("rails/", "app/", "src/", "config/", "lib/")):
+        # reject stray colon annotations (e.g. line ranges not yet stripped)
+        if re.search(r":\d", value):
+            return False
+    if value.endswith(PATH_EXTENSIONS):
+        return True
+    if any(value.startswith(prefix) for prefix in PATH_PREFIXES):
+        return True
+    if "/" in value:
+        last = value.rsplit("/", 1)[-1]
+        if "." in last and not last.endswith("."):
+            return True
+    return False
+
+
+def passes_normalized_invariants(path: str) -> bool:
+    if not path or " " in path:
+        return False
+    if re.search(r":\d", path):
+        return False
+    if "—" in path or "–" in path:
+        return False
+    if "mounts" in path.lower():
+        return False
+    return looks_like_file_path(path)
+
+
+def strip_line_range(value: str) -> str:
+    return LINE_RANGE_RE.sub("", value).strip()
+
+
+def normalize_path_candidate(value: str) -> Optional[str]:
+    if not isinstance(value, str):
+        return None
+
+    value = value.strip().strip('"').strip("'")
+    if not value or value.startswith("("):
+        return None
+    if value.lower().startswith("see "):
+        return None
+    if value.startswith(HTTP_METHODS):
+        return None
+
+    if ": " in value:
+        left, _right = value.split(": ", 1)
+        left = left.strip()
+        if "/" in left or left.endswith(PATH_EXTENSIONS):
+            value = left
+
+    for sep in (" — ", " – ", " - ", " (", "("):
+        if sep in value:
+            value = value.split(sep, 1)[0].strip()
+
+    if "#" in value:
+        value = value.split("#", 1)[0].strip()
+
+    value = strip_line_range(value)
+
+    value = value.rstrip("/")
+    if not value:
+        return None
+    if value.startswith("config/") and " " in value:
+        return None
+    if "," in value:
+        return None
+
+    ext_match = re.match(rf"^(\S+{EXT_PATTERN})(?:\s|$)", value)
+    if ext_match:
+        value = ext_match.group(1)
+        value = strip_line_range(value)
+    elif " " in value:
+        first = value.split(" ", 1)[0].strip()
+        first = strip_line_range(first)
+        if looks_like_file_path(first):
+            value = first
+        else:
+            return None
+
+    value = strip_line_range(value)
+    if not looks_like_file_path(value):
+        return None
+    if re.match(r"^[A-Za-z_]+Controller$", value):
+        return None
+
+    return value

feature_map/path_resolve.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+from typing import Iterable, List
+
+PATH_EXTENSIONS = (".rb", ".js", ".erb", ".svelte", ".ts", ".tsx", ".py", ".go", ".yaml", ".yml")
+
+
+def resolve_candidate_paths(path_str: str, repo_root: Path, apps: Iterable[str]) -> List[Path]:
+    """Expand a pre-normalized path to filesystem candidates. Does not re-normalize."""
+    path_str = path_str.strip()
+    apps = [app for app in apps if isinstance(app, str) and app]
+    candidates: List[Path] = []
+    seen = set()
+
+    def add(candidate: Path):
+        key = str(candidate)
+        if key not in seen:
+            seen.add(key)
+            candidates.append(candidate)
+
+    add(repo_root / path_str)
+    for app in apps:
+        add(repo_root / app / path_str)
+        prefix = f"{app}/"
+        if path_str.startswith(prefix):
+            add(repo_root / path_str)
+            add(repo_root / path_str[len(prefix) :])
+
+    # Rails-style fallbacks when the consumer repo lists a rails app.
+    if "rails" in apps:
+        if path_str.startswith("app/"):
+            add(repo_root / "rails" / path_str)
+        if "/" not in path_str and path_str.endswith(PATH_EXTENSIONS):
+            add(repo_root / "rails" / "app" / "javascript" / "controllers" / path_str)
+            add(repo_root / "rails" / "app" / "controllers" / path_str)
+
+    return candidates

feature_map/paths.py

@@ -0,0 +1,34 @@
+"""Locate bundled schema, templates, and agent skill assets."""
+
+from pathlib import Path
+
+
+def package_dir() -> Path:
+    return Path(__file__).resolve().parent
+
+
+def source_share_dir() -> Path:
+    """Repo-root share/feature_map when running from a source checkout."""
+    return package_dir().parent.parent / "share" / "feature_map"
+
+
+def assets_root() -> Path:
+    bundled = package_dir() / "share"
+    if (bundled / "schema").is_dir() or (bundled / "templates").is_dir():
+        return bundled
+    share = source_share_dir()
+    if share.is_dir():
+        return share
+    return bundled
+
+
+def schema_path() -> Path:
+    return assets_root() / "schema" / "feature-map.schema.json"
+
+
+def template_path() -> Path:
+    return assets_root() / "templates" / "feature.yaml.tpl"
+
+
+def skill_dir() -> Path:
+    return assets_root() / "skill"

feature_map/share/schema/feature-map.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Map",
+  "type": "object",
+  "required": ["feature_name", "purpose", "entry_points"],
+  "properties": {
+    "feature_name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "purpose": {
+      "type": "string",
+      "minLength": 1
+    },
+    "entry_points": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      }
+    },
+    "apps": {
+      "type": ["array", "object"]
+    },
+    "user_flow": {
+      "type": "object"
+    },
+    "related_features": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "notes": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": true
+}

feature_map/share/skill/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: feature-map
+version: 1.0.0
+description: "Research cross-app architecture via the Feature Map CLI before feature work, debugging, PRDs, or implementation plans. Run list, show, search, find, graph, validate, and check against .features/*.yaml. On existing repos with no maps, scour the code and author maps first."
+---
+
+# Feature Map
+
+Authoritative cross-app architecture lives in `.features/*.yaml`. **Always**
+use this skill before touching a feature. Do not plan, debug, or implement
+from a cold grep when a map exists — or when one should exist and does not.
+
+Maps are **fields, not a wiki**. Prefer `list` / `search` / `show --section`
+over reading a long markdown doc. That keeps token use on paths and purpose,
+not narrative. When writing or updating a map, same rule: cover every door
+and coupling; do not write narrative (`references/authoring.md`, Density).
+See the package `GUIDE.md` ("Why this, not a wiki").
+
+## When to invoke
+
+- Before feature implementation, debugging, PRDs, implementation plans, or pre-mortems
+- When unsure which feature map applies
+- After shipping changes that affect architecture (update maps, then validate)
+- When `list` is empty or `search`/`find` miss: **scour the repo and author maps** before other work (see `references/existing-repos.md`)
+
+## Research sequence
+
+```bash
+feature-map list
+feature-map search <keyword>    # when the feature name is unclear
+feature-map find <path-fragment>
+feature-map <feature-name>      # or: show <feature-name>
+feature-map graph <feature>     # cross-cutting dependencies
+```
+
+`./bin/feature-map` is a repo-local shim for the same CLI (created by `feature-map init`).
+
+Use `show <name> --section entry_points` (or `purpose`, `user_flow`, etc.) to limit token use on large maps.
+
+If the list is empty, or nothing matches the area you are about to change,
+**stop**. Follow `references/existing-repos.md`: inventory apps, cluster
+capabilities, `feature-map init <slug>`, fill real paths, `validate` + `check`.
+Then resume the research sequence.
+
+## After implementation
+
+1. Patch the fields that changed. Do not grow the map with prose.
+2. Run `feature-map validate`
+3. Run `feature-map check`
+
+## Commands
+
+See `references/commands.md` for the full CLI reference.
+
+## Authoring
+
+See `references/authoring.md` for shape, density, and conventions.
+See `references/existing-repos.md` when adopting Feature Map on a codebase that already exists.

feature_map/share/skill/references/authoring.md

@@ -0,0 +1,37 @@
+# Authoring Feature Maps
+
+Feature maps live in `.features/<slug>.yaml` at the repo root.
+
+## Required sections
+
+- `feature_name` — must match the filename stem (normalized)
+- `purpose` — one sentence: what it does. Skip motivation unless it changes where you look.
+- `entry_points` — primary doors only (routes, screens, jobs, CLIs); real paths
+- `apps` — app names as a list, not descriptions (recommended; warning if missing)
+
+## Recommended sections
+
+- `user_flow` — one line per distinct path: `Actor → step → result`. Add `alt`/`error` only if code diverges.
+- `related_features` — `slug (coupling)`; parenthetical is a phrase
+
+## Optional
+
+- `notes` — caveats and unknowns only; omit the key if none. Never history, README, or process tips. `validate` does not warn when this key is absent.
+
+## Density
+
+Index, not essay. Completeness is doors, apps, and couplings. Delete a sentence if it would not change which file the next agent opens. Do not drop a real door, app, or related slug to stay short. Do not add narrative keys (`overview`, `history`, `architecture`, `background`). `core_components` is the only extra path group `check` understands.
+
+## Conventions
+
+- Use underscores in filenames: `user_signup.yaml`
+- `related_features` entries should start with a resolvable slug
+- Run `feature-map validate` and `feature-map check` after edits
+- Scaffold new maps: `feature-map init <name>`
+- Bootstrap a new repo: `feature-map init`
+- Existing repo with no maps: scour the code first (`existing-repos.md`); do not skip maps because the codebase predates Feature Map
+- Patch fields in place when the architecture changes; do not append prose
+
+## Schema
+
+JSON Schema ships with the package at `share/feature_map/schema/feature-map.schema.json`.

feature_map/share/skill/references/commands.md

@@ -0,0 +1,47 @@
+# Feature Map CLI Reference
+
+Invocation: `feature-map` (on PATH) or `./bin/feature-map` (repo-local shim).
+
+Global flags: `--json`, `--version`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `list [--json]` | All feature slugs; JSON includes mtime and app count |
+| `show <name> [--section <key>] [--json]` | Full map or one top-level section |
+| `<name>` | Alias for `show <name>` |
+| `search <query> [--json]` | Full-text search across all maps |
+| `find <path-fragment> [--json]` | Reverse lookup by path string |
+| `graph [name] [--format mermaid\|json\|dot]` | `related_features` graph |
+| `validate [--strict] [--json]` | Structural validation |
+| `check [--json]` | Staleness check for entry-point paths |
+| `impact <file> [--transitive] [--json]` | Features referencing a file |
+| `stats [--json]` | Coverage statistics |
+| `init` | Bootstrap `.features/`, agent skill, config, AGENTS.md, shim |
+| `init <name> [--force]` | Scaffold `.features/<name>.yaml` |
+| `init --upgrade-skill` | Refresh the agent skill from the installed package |
+| `install [--json]` | Verify install and repo setup |
+
+## Examples
+
+```bash
+feature-map list
+feature-map auth
+feature-map show auth --section entry_points
+feature-map search billing
+feature-map find src/app.py
+feature-map graph auth --format mermaid
+feature-map validate
+feature-map check --json
+feature-map impact src/app.py
+feature-map stats --json
+feature-map init
+feature-map init billing --force
+```
+
+## Exit codes
+
+- `0` — success
+- `1` — user error (e.g. feature not found)
+- `2` — validation failure (`validate --strict`)

feature_map/share/skill/references/existing-repos.md

@@ -0,0 +1,43 @@
+# Bootstrapping maps on an existing repository
+
+`feature-map init` creates the workflow. It does **not** invent maps from
+source. On a repo that already has code, you must **scour the tree and
+author** `.features/*.yaml` before doing feature work.
+
+## When this applies
+
+- `feature-map list` is empty
+- `search` / `find` miss the area you are about to change
+- `.feature-map.yaml` `apps` is `[]` but the repo has multiple packages
+
+Do not skip this and "just grep". Author maps first, then implement.
+
+## Playbook
+
+1. **Inventory apps** — top-level directories and manifests (`Gemfile`,
+   `package.json`, `pyproject.toml`, `go.mod`, `pubspec.yaml`, `apps/`,
+   `packages/`). Write them under `apps:` in `.feature-map.yaml`.
+2. **Find seams** — routes, app shells, domain models, jobs, CLIs, docs,
+   and test names. These are where features show up.
+3. **Cluster** — one map per user-visible capability or subsystem, not
+   per file. Cross-app journeys are one map with several `apps` and
+   `entry_points`.
+4. **Scaffold + fill** — `feature-map init <slug>`, then replace
+   placeholders with real paths and a one-sentence `purpose` you
+   verified in code (`authoring.md`, Density).
+5. **Verify** — `feature-map validate` and `feature-map check`. Prefer
+   paths that exist on disk. Record uncertainty in `notes`.
+6. **Stop the first pass** when every listed app appears on at least one
+   map and the README's product nouns `search` successfully.
+
+Full narrative: the package `GUIDE.md` §3.4 (existing repos).
+
+## Anti-patterns
+
+- One map per source file
+- Invented `entry_points` that `check` would mark missing
+- `entry_points` as a file inventory (doors only)
+- Essays in `purpose`, `user_flow`, or `notes`
+- Extra narrative keys (`overview`, `history`, `architecture`)
+- `related_features` that do not start with a real slug
+- Planning or coding a feature that has no map "because the repo is old"

feature_map/share/templates/feature.yaml.tpl

@@ -0,0 +1,17 @@
+feature_name: {{feature_name}}
+purpose: "One sentence: what {{FEATURE_TITLE}} does."
+
+entry_points:
+  - path/to/primary/entry_point
+  - path/to/secondary/surface
+
+apps:
+  - app_name
+
+user_flow:
+  primary: "Actor → action → result."
+
+related_features:
+  - related_feature_slug (coupling)
+
+# notes: caveats/unknowns only — omit this key if none

feature_map/text_index.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+from typing import Dict, List
+
+import yaml
+
+from feature_map.loader import list_map_files
+
+
+def _flatten(value, prefix="") -> List[str]:
+    lines = []
+    if isinstance(value, dict):
+        for key, item in value.items():
+            lines.extend(_flatten(item, f"{prefix}{key}."))
+    elif isinstance(value, list):
+        for item in value:
+            lines.extend(_flatten(item, prefix))
+    elif value is not None:
+        lines.append(f"{prefix}{value}")
+    return lines
+
+
+def build_text_index(features_dir: Path) -> Dict[str, str]:
+    index = {}
+    for path in list_map_files(features_dir):
+        text = path.read_text(encoding="utf-8")
+        index[path.stem] = text
+        try:
+            data = yaml.safe_load(text) or {}
+            if isinstance(data, dict):
+                index[path.stem] = "\n".join(_flatten(data))
+        except yaml.YAMLError:
+            pass
+    return index
+
+
+def search_maps(features_dir: Path, query: str) -> List[dict]:
+    query_lower = query.lower()
+    results = []
+    for slug, text in build_text_index(features_dir).items():
+        if query_lower not in text.lower():
+            continue
+        snippets = []
+        for line in text.splitlines():
+            if query_lower in line.lower():
+                snippets.append(line.strip())
+                if len(snippets) >= 3:
+                    break
+        results.append({"feature": slug, "snippets": snippets})
+    return results