architec 0.2.11__py3-none-any.whl

architec/__init__.py

@@ -0,0 +1,52 @@
+"""Architec analysis engine.
+
+Independent from runtime proxy internals; integrates with Hippos via
+read-only `.hippos` artifacts and writes its own outputs to `.architec`.
+"""
+
+__all__ = [
+    "run_analysis",
+    "analyze_history_and_iterate",
+    "suggest_feature_architecture",
+    "score_changed_components",
+    "load_scoring_policy",
+    "evaluate_full_score",
+    "evaluate_incremental_score",
+    "evaluate_overall_score",
+]
+
+
+def __getattr__(name: str):
+    if name == "run_analysis":
+        from .analysis.public import run_analysis
+
+        return run_analysis
+    if name == "analyze_history_and_iterate":
+        from .analysis.history_analyzer import analyze_history_and_iterate
+
+        return analyze_history_and_iterate
+    if name == "suggest_feature_architecture":
+        from .feature.feature_advisor import suggest_feature_architecture
+
+        return suggest_feature_architecture
+    if name == "score_changed_components":
+        from .scoring.component_scoring import score_changed_components
+
+        return score_changed_components
+    if name == "load_scoring_policy":
+        from .scoring.public import load_scoring_policy
+
+        return load_scoring_policy
+    if name == "evaluate_full_score":
+        from .scoring.public import evaluate_full_score
+
+        return evaluate_full_score
+    if name == "evaluate_incremental_score":
+        from .scoring.public import evaluate_incremental_score
+
+        return evaluate_incremental_score
+    if name == "evaluate_overall_score":
+        from .scoring.public import evaluate_overall_score
+
+        return evaluate_overall_score
+    raise AttributeError(f"module 'architec' has no attribute {name!r}")

architec/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

architec/_compat_reexport.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import sys
+from importlib import import_module
+from types import ModuleType
+from typing import Any
+
+
+def reexport(package_name: str, target: str, namespace: dict[str, Any]) -> ModuleType:
+    module_name = str(namespace.get("__name__", package_name) or package_name)
+    target_module = import_module(target, package_name)
+    sys.modules[module_name] = target_module
+
+    parent_name, _, child_name = module_name.rpartition(".")
+    if parent_name and child_name:
+        parent_module = sys.modules.get(parent_name)
+        if parent_module is not None:
+            setattr(parent_module, child_name, target_module)
+
+    return target_module

architec/_version.py

@@ -0,0 +1,4 @@
+from __future__ import annotations
+
+# Package-local version fallback for bundled/compiled runtime environments.
+__version__ = "0.2.11"

architec/advice_feedback.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+
+DEMOTE_STATUSES = {"rejected", "not_applicable", "superseded"}
+KNOWN_STATUSES = DEMOTE_STATUSES | {"accepted", "deferred"}
+KNOWN_SCOPES = {"exact_advice", "same_path_kind", "pattern"}
+
+
+class AdviceFeedbackInputError(RuntimeError):
+    """Raised when advice feedback JSON cannot be read or used."""
+
+
+def _dict(value: object) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+
+
+def _list(value: object) -> list[Any]:
+    return value if isinstance(value, list) else []
+
+
+def _clean(value: object) -> str:
+    return str(value or "").strip()
+
+
+def _norm_token(value: object) -> str:
+    return _clean(value).lower().replace("-", "_").replace(" ", "_")
+
+
+def _norm_path(value: object) -> str:
+    return _clean(value).replace("\\", "/").lstrip("./")
+
+
+def _stable_advice_id(prefix: str, payload: dict[str, Any]) -> str:
+    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+    return f"{prefix}:{hashlib.sha256(encoded.encode('utf-8')).hexdigest()[:12]}"
+
+
+def _feedback_items(feedback: dict[str, Any] | None) -> list[dict[str, Any]]:
+    if not isinstance(feedback, dict):
+        return []
+    out: list[dict[str, Any]] = []
+    for item in _list(feedback.get("items")):
+        if not isinstance(item, dict):
+            continue
+        status = _norm_token(item.get("status"))
+        if status not in KNOWN_STATUSES:
+            continue
+        scope = _norm_token(item.get("scope"))
+        if scope not in KNOWN_SCOPES:
+            if _clean(item.get("advice_id")) or _clean(item.get("concern_id")):
+                scope = "exact_advice"
+            elif _clean(item.get("path")):
+                scope = "same_path_kind"
+            elif _clean(item.get("pattern")):
+                scope = "pattern"
+            else:
+                continue
+        out.append(
+            {
+                "advice_id": _clean(item.get("advice_id")),
+                "concern_id": _clean(item.get("concern_id")),
+                "kind": _norm_token(item.get("kind")),
+                "path": _norm_path(item.get("path")),
+                "symbol": _clean(item.get("symbol")),
+                "status": status,
+                "scope": scope,
+                "pattern": _clean(item.get("pattern")).lower(),
+                "reason": _clean(item.get("reason")),
+            }
+        )
+    return out
+
+
+def load_advice_feedback(path: str | Path) -> dict[str, Any]:
+    source = Path(path)
+    try:
+        raw = source.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise AdviceFeedbackInputError(f"Advice feedback JSON not found: {source}") from exc
+    except OSError as exc:
+        raise AdviceFeedbackInputError(f"Unable to read advice feedback JSON: {source}: {exc}") from exc
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise AdviceFeedbackInputError(f"Invalid advice feedback JSON: {source}: {exc.msg}") from exc
+    if not isinstance(data, dict):
+        raise AdviceFeedbackInputError(f"Advice feedback JSON must be an object: {source}")
+    items = data.get("items")
+    if items is not None and not isinstance(items, list):
+        raise AdviceFeedbackInputError(f"Advice feedback items must be a list: {source}")
+    data = dict(data)
+    data["_source_path"] = str(source)
+    return data
+
+
+def recommendation_target(item: dict[str, Any]) -> dict[str, Any]:
+    title = _clean(item.get("title"))
+    scope = _clean(item.get("scope"))
+    why = _clean(item.get("why"))
+    priority = _clean(item.get("priority"))
+    kind = _norm_token(item.get("kind")) or "recommendation"
+    advice_id = _clean(item.get("advice_id")) or _stable_advice_id(
+        "archi-advice:recommendation",
+        {
+            "kind": kind,
+            "priority": priority,
+            "title": title,
+            "scope": scope,
+            "why": why,
+        },
+    )
+    return {
+        "advice_id": advice_id,
+        "kind": kind,
+        "path": _norm_path(item.get("path")) or _norm_path(title) or _norm_path(scope),
+        "title": title,
+        "scope": scope,
+        "why": why,
+        "text": " ".join([advice_id, kind, title, scope, why]).lower(),
+    }
+
+
+def concern_target(concern: dict[str, Any]) -> dict[str, Any]:
+    location = _dict(concern.get("location"))
+    concern_id = _clean(concern.get("concern_id"))
+    kind = _norm_token(concern.get("kind"))
+    path = _norm_path(location.get("path"))
+    symbol = _clean(location.get("symbol"))
+    return {
+        "advice_id": "",
+        "concern_id": concern_id,
+        "kind": kind,
+        "path": path,
+        "symbol": symbol,
+        "title": "",
+        "scope": path,
+        "why": "",
+        "text": " ".join([concern_id, kind, path, symbol]).lower(),
+    }
+
+
+def _path_matches(entry_path: str, target: dict[str, Any]) -> bool:
+    if not entry_path:
+        return False
+    target_path = _norm_path(target.get("path"))
+    if target_path == entry_path:
+        return True
+    haystack = " ".join(
+        [
+            _norm_path(target.get("path")),
+            _clean(target.get("title")),
+            _clean(target.get("scope")),
+            _clean(target.get("text")),
+        ]
+    ).lower()
+    return entry_path.lower() in haystack
+
+
+def _kind_matches(entry_kind: str, target: dict[str, Any]) -> bool:
+    if not entry_kind:
+        return True
+    target_kind = _norm_token(target.get("kind"))
+    if target_kind == entry_kind:
+        return True
+    return entry_kind in _clean(target.get("text")).lower()
+
+
+def demoting_feedback_for_target(
+    target: dict[str, Any],
+    feedback: dict[str, Any] | None,
+) -> dict[str, Any]:
+    target_advice_id = _clean(target.get("advice_id"))
+    target_concern_id = _clean(target.get("concern_id"))
+    target_text = _clean(target.get("text")).lower()
+    for item in _feedback_items(feedback):
+        if item["status"] not in DEMOTE_STATUSES:
+            continue
+        if item["scope"] == "exact_advice":
+            if item["advice_id"] and item["advice_id"] == target_advice_id:
+                return item
+            if item["concern_id"] and item["concern_id"] == target_concern_id:
+                return item
+            continue
+        if item["scope"] == "same_path_kind":
+            if _path_matches(item["path"], target) and _kind_matches(item["kind"], target):
+                return item
+            continue
+        if item["scope"] == "pattern":
+            pattern = item["pattern"]
+            if pattern and pattern in target_text and _kind_matches(item["kind"], target):
+                return item
+    return {}
+
+
+def apply_feedback_to_recommendations(
+    recommendations: list[dict[str, Any]],
+    feedback: dict[str, Any] | None,
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    items = _feedback_items(feedback)
+    if not items:
+        return recommendations, {}
+    kept: list[dict[str, Any]] = []
+    demoted: list[dict[str, Any]] = []
+    for index, item in enumerate(recommendations):
+        if not isinstance(item, dict):
+            continue
+        target = recommendation_target(item)
+        enriched = dict(item)
+        enriched.setdefault("advice_id", target["advice_id"])
+        match = demoting_feedback_for_target(target, feedback)
+        if match:
+            demoted.append(
+                {
+                    "advice_id": target["advice_id"],
+                    "kind": target["kind"],
+                    "title": target["title"],
+                    "scope": target["scope"],
+                    "status": match["status"],
+                    "feedback_scope": match["scope"],
+                    "reason": match["reason"],
+                    "position": index,
+                }
+            )
+            continue
+        kept.append(enriched)
+    return kept, {
+        "input_path": _clean(_dict(feedback).get("_source_path")),
+        "item_total": len(items),
+        "demoted_recommendation_total": len(demoted),
+        "demoted_recommendations": demoted,
+    }
+
+
+def feedback_summary_for_concern(
+    concern: dict[str, Any],
+    feedback: dict[str, Any] | None,
+) -> dict[str, Any]:
+    target = concern_target(concern)
+    match = demoting_feedback_for_target(target, feedback)
+    if not match:
+        return {}
+    return {
+        "concern_id": target["concern_id"],
+        "kind": target["kind"],
+        "path": target["path"],
+        "symbol": target["symbol"],
+        "status": match["status"],
+        "feedback_scope": match["scope"],
+        "reason": match["reason"],
+    }
+
+
+__all__ = [
+    "AdviceFeedbackInputError",
+    "apply_feedback_to_recommendations",
+    "feedback_summary_for_concern",
+    "load_advice_feedback",
+]

architec/analysis/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .public import run_analysis
+
+__all__ = ["run_analysis"]

architec/analysis/analysis_cache.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from architec.support.io_utils import read_json, utc_now_iso, write_json
+from architec.integration.paths import ANALYSIS_CACHE_DIR
+
+
+CACHE_DIR = ANALYSIS_CACHE_DIR
+
+
+def _stable_json(value: object) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(',', ':'))
+
+
+def fingerprint_payload(payload: object) -> str:
+    return hashlib.sha256(_stable_json(payload).encode('utf-8')).hexdigest()
+
+
+def _cache_path(root: Path, namespace: str) -> Path:
+    safe = ''.join(ch if ch.isalnum() or ch in {'-', '_'} else '_' for ch in namespace)
+    return root / CACHE_DIR / f'{safe}.json'
+
+
+def load_cached_analysis(root: Path, *, namespace: str, payload: object) -> dict[str, Any] | None:
+    path = _cache_path(root, namespace)
+    data = read_json(path, default={})
+    if not isinstance(data, dict):
+        return None
+    if str(data.get('fingerprint', '') or '') != fingerprint_payload(payload):
+        return None
+    result = data.get('result')
+    if not isinstance(result, dict):
+        return None
+    cached = dict(result)
+    cached['_cache_hit'] = True
+    cached['_cache_namespace'] = namespace
+    return cached
+
+
+def save_cached_analysis(
+    root: Path,
+    *,
+    namespace: str,
+    payload: object,
+    result: dict[str, Any],
+) -> None:
+    path = _cache_path(root, namespace)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_json(
+        path,
+        {
+            'generated_at': utc_now_iso(),
+            'namespace': namespace,
+            'fingerprint': fingerprint_payload(payload),
+            'result': result,
+        },
+    )
+
+
+def run_cached_analysis(
+    root: Path,
+    *,
+    namespace: str,
+    payload: object,
+    runner,
+) -> tuple[dict[str, Any] | None, bool]:
+    cached = load_cached_analysis(root, namespace=namespace, payload=payload)
+    if cached is not None:
+        return cached, True
+    result = runner()
+    if isinstance(result, dict):
+        save_cached_analysis(root, namespace=namespace, payload=payload, result=result)
+    return result, False

architec/analysis/analysis_runner_flow.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from architec.analysis.analysis_runner_llm import (
+    llm_summary,
+    run_diff_analysis,
+    run_goal_analysis,
+)
+from architec.analysis.governance_dimensions import governance_dimensions
+from architec.analysis.analysis_runner_recommendations import (
+    recommendations,
+    topology_recommendations,
+)
+from architec.support.io_utils import clamp
+
+
+def score_from_keywords(
+    source: dict[str, Any],
+    keywords: tuple[str, ...],
+    factor: float,
+) -> float:
+    total = 0.0
+    for key, value in source.items():
+        if any(word in str(key).lower() for word in keywords):
+            total += float(value or 0.0)
+    return total * factor
+
+
+def _count(source: dict[str, Any], key: str) -> float:
+    return float(source.get(key, 0.0) or 0.0)
+
+
+def _excess_penalty(
+    count: float,
+    *,
+    grace: float,
+    factor: float,
+    cap: float,
+) -> float:
+    if count <= grace:
+        return 0.0
+    return min(cap, (count - grace) * factor)
+
+
+def _file_modularity_penalty(by_metric: dict[str, Any]) -> float:
+    return (
+        _excess_penalty(_count(by_metric, 'module_lines'), grace=10.0, factor=1.4, cap=24.0)
+        + _excess_penalty(
+            _count(by_metric, 'class_public_methods'),
+            grace=4.0,
+            factor=1.2,
+            cap=8.0,
+        )
+        + _excess_penalty(
+            _count(by_metric, 'class_instance_attributes'),
+            grace=4.0,
+            factor=1.0,
+            cap=6.0,
+        )
+    )
+
+
+def _maintainability_penalty(
+    by_metric: dict[str, Any],
+    by_severity: dict[str, Any],
+) -> float:
+    complexity = _excess_penalty(
+        _count(by_metric, 'cyclomatic_complexity'),
+        grace=32.0,
+        factor=0.45,
+        cap=18.0,
+    )
+    line_soft = _excess_penalty(
+        _count(by_metric, 'line_length_soft_hits'),
+        grace=55.0,
+        factor=0.06,
+        cap=6.0,
+    )
+    line_hard = _excess_penalty(
+        _count(by_metric, 'line_length_hard_hits'),
+        grace=16.0,
+        factor=0.22,
+        cap=8.0,
+    )
+    critical = _excess_penalty(
+        _count(by_severity, 'critical'),
+        grace=6.0,
+        factor=0.55,
+        cap=10.0,
+    )
+    return complexity + line_soft + line_hard + critical
+
+
+def _topology_dimension(topology: dict[str, Any]) -> float:
+    if not isinstance(topology, dict) or not topology:
+        return 70.0
+
+    flat_file_total = int(topology.get('flat_file_total', 0) or 0)
+    subpackage_total = int(topology.get('subpackage_total', 0) or 0)
+    compat_wrapper_total = int(topology.get('compat_wrapper_total', 0) or 0)
+    placement_review = (
+        topology.get('root_placement_review', {})
+        if isinstance(topology.get('root_placement_review', {}), dict)
+        else {}
+    )
+    misplaced_root_total = len(placement_review.get('misplaced_root_files', []))
+    review_root_total = len(placement_review.get('review_root_files', []))
+    retained_root_total = len(placement_review.get('allowed_root_files', []))
+
+    score = 100.0
+    if flat_file_total > 8:
+        score -= min(34.0, (flat_file_total - 8) * 1.25)
+    if misplaced_root_total:
+        score -= min(26.0, misplaced_root_total * 1.15)
+    if review_root_total:
+        score -= min(12.0, review_root_total * 1.4)
+    if retained_root_total > 8:
+        score -= min(8.0, (retained_root_total - 8) * 1.6)
+
+    if subpackage_total >= 6:
+        score += 8.0
+    elif subpackage_total >= 3:
+        score += 5.0
+    elif subpackage_total > 0:
+        score += 2.5
+
+    if (
+        not bool(topology.get('needs_folder_management', False))
+        and flat_file_total <= 28
+        and misplaced_root_total <= 18
+    ):
+        score += 4.0
+    if compat_wrapper_total and misplaced_root_total == 0:
+        score += min(4.0, compat_wrapper_total * 0.8)
+
+    return round(clamp(score, 0.0, 100.0), 2)
+
+
+def structure_dimensions(
+    history: dict[str, Any],
+    topology: dict[str, Any] | None = None,
+    *,
+    hotspot_digest: dict[str, Any] | None = None,
+    components: list[dict[str, Any]] | None = None,
+    cleanup: dict[str, Any] | None = None,
+    archive_candidates: dict[str, Any] | None = None,
+    semantic_judge: dict[str, Any] | None = None,
+) -> dict[str, float]:
+    summary = history.get('summary', {}) if isinstance(history.get('summary'), dict) else {}
+    by_metric = summary.get('by_metric', {}) if isinstance(summary.get('by_metric'), dict) else {}
+    by_dimension = (
+        summary.get('by_dimension', {})
+        if isinstance(summary.get('by_dimension'), dict)
+        else {}
+    )
+    by_severity = (
+        summary.get('by_severity', {})
+        if isinstance(summary.get('by_severity'), dict)
+        else {}
+    )
+
+    file_modularity = 100.0 - min(36.0, _file_modularity_penalty(by_metric))
+    boundary_clarity = 100.0 - min(
+        40.0,
+        score_from_keywords(by_dimension, ('boundary', 'layer', 'ownership', 'component'), 2.0),
+    )
+    coupling = 100.0 - min(
+        35.0,
+        score_from_keywords(by_dimension, ('coupling', 'dependency'), 2.4),
+    )
+    maintainability = 100.0 - min(
+        36.0,
+        _maintainability_penalty(by_metric, by_severity),
+    )
+    dimensions = {
+        'file_modularity': round(max(0.0, file_modularity), 2),
+        'boundary_clarity': round(max(0.0, boundary_clarity), 2),
+        'coupling_control': round(max(0.0, coupling), 2),
+        'maintainability': round(max(0.0, maintainability), 2),
+    }
+    if topology is not None:
+        dimensions['package_topology'] = _topology_dimension(topology)
+    dimensions.update(
+        governance_dimensions(
+            hotspot_digest=hotspot_digest,
+            components=components,
+            cleanup=cleanup,
+            archive_candidates=archive_candidates,
+            semantic_judge=semantic_judge,
+        )
+    )
+    return dimensions
+
+
+def structure_score(full_score: dict[str, Any], dimensions: dict[str, float]) -> float:
+    base = float(full_score.get('score', 0.0) or 0.0)
+    if not dimensions:
+        return round(base, 2)
+    avg = sum(float(v or 0.0) for v in dimensions.values()) / max(1, len(dimensions))
+    return round((base * 0.3) + (avg * 0.7), 2)
+
+
+def incremental_score(score: dict[str, Any], *, diff: bool) -> dict[str, Any]:
+    if diff and isinstance(score.get('incremental_score'), dict):
+        return score['incremental_score']
+    return {'mode': 'not_applicable', 'score': 0.0, 'recommendation': 'n/a', 'signals': {}}

architec/analysis/analysis_runner_llm.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from architec.analysis.analysis_cache import run_cached_analysis
+from architec.backend_llm import complete_json
+from architec.support.llm_guard import guard_llm_result
+
+
+def llm_summary(root: Path, *, payload: dict[str, Any]) -> dict[str, Any] | None:
+    prompt = f"Input:\n{payload}"
+    result, cache_hit = run_cached_analysis(
+        root,
+        namespace="architec_summary",
+        payload=payload,
+        runner=lambda: guard_llm_result(
+            root,
+            task="architec_summary",
+            runner=lambda: complete_json(
+                root,
+                task="architec_summary",
+                tier="strong",
+                prompt=prompt,
+                timeout_sec=30.0,
+                max_tokens=900,
+                required=True,
+            ),
+        ),
+    )
+    if not isinstance(result, dict):
+        return None
+    out = dict(result)
+    out["_cache_hit"] = bool(cache_hit)
+    return out
+
+
+def run_diff_analysis(root: Path, *, diff: bool, base: str, head: str, runner) -> dict[str, Any]:
+    if not diff:
+        return {}
+    return runner(root, base=base or None, head=head or None, llm_enabled=True)
+
+
+def run_goal_analysis(root: Path, *, goal: str, runner) -> dict[str, Any]:
+    if not goal:
+        return {}
+    return runner(root, goal=goal, llm_enabled=True)