atomadic-forge 0.75.2__tar.gz → 0.75.3__tar.gz

{atomadic_forge-0.75.2 → atomadic_forge-0.75.3}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## v0.75.3 — 2026-05-08
+
+### Changed
+
+- d4b631b feat(metrics): sync tagged repo metrics surfaces (GP Lane C W6)
+
+
 ## v0.75.2 — 2026-05-08
 
 ### Changed

{atomadic_forge-0.75.2/src/atomadic_forge.egg-info → atomadic_forge-0.75.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.75.2
+Version: 0.75.3
 Summary: Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code.
 Author: Atomadic
 License-Expression: BUSL-1.1

atomadic_forge-0.75.3/docs/commands/metrics.md

@@ -0,0 +1,91 @@
+# `atomadic-forge metrics`
+
+_Emit forge_metrics.json — canonical metrics for README/CHANGELOG/welcome/worker._
+
+- **Module**: `atomadic_forge.commands.metrics`
+- **Surface**: `typer_app`
+- **Source root**: `atomadic_forge_seed`
+- **Hidden**: `False`
+
+## Forge metrics
+
+Use the top-level command when updating Forge's own public counters.
+
+```bash
+forge metrics
+forge metrics --apply
+forge metrics --json
+```
+
+`--apply` rewrites `forge_metrics.json`. This artifact is Forge-specific:
+README badges, release automation, and Worker metadata read from it.
+
+## Product repo metrics
+
+Use the `repo` subcommand when updating any product repository's own public
+surface.
+
+```bash
+forge metrics repo --project /path/to/product
+forge metrics repo --project /path/to/product --apply
+forge metrics repo --project /path/to/product --json
+forge metrics repo --project /path/to/product --init-config --apply
+forge metrics repo --project /path/to/product --apply --commit --push
+```
+
+The repo sync is intentionally separate from Forge metrics. It computes the
+target repo's source files, source lines, test files, languages, name, and
+version, then plans these bounded writes:
+
+| File | Update |
+|------|--------|
+| `repo_metrics.json` | Canonical product metrics artifact |
+| `README.md` | Metrics copy block between `<!-- forge:metrics:start -->` markers |
+| `server.json` | MCP registry version and description, when present |
+
+Dry-run is the default. Passing `--apply` writes the product surface and does
+not mutate `forge_metrics.json`.
+
+### Config and live external surfaces
+
+Repos can opt into a custom metrics surface with
+`.atomadic-forge/repo-metrics.config.json`:
+
+```json
+{
+  "schema_version": "atomadic-forge.repo_metrics_config/v1",
+  "artifact_path": "public/metrics.json",
+  "document_globs": ["README.md", "docs/**/*.md", "website/**/*.mdx"],
+  "readme_block": true,
+  "sync_server_json": true,
+  "extra_metrics": {
+    "customer_count": 42
+  },
+  "aliases": {
+    "customers": "customer_count"
+  }
+}
+```
+
+`artifact_path` is the JSON file your site or Worker can serve. For example,
+set it to `public/metrics.json`, deploy that folder, and the website can fetch
+the same live repo metrics as ordinary JSON.
+
+Any configured document can contain inline metric markers:
+
+```md
+Source files: <!-- forge:metric key=source_file_count format=comma -->0<!-- /forge:metric -->
+Customers: <!-- forge:metric customers -->0<!-- /forge:metric -->
+Languages: <!-- forge:metric languages -->unknown<!-- /forge:metric -->
+```
+
+On `forge metrics repo --apply`, Forge scans the configured document globs,
+updates every marker it finds, writes the metrics artifact, and leaves
+unmarked prose alone. Supported marker formats are `plain`, `comma`,
+`compact`, and `json`. Markers inside fenced code blocks are treated as
+examples and are not updated.
+
+For release automation, pass `--commit` to stage and commit only the files
+Forge planned to write. Pass `--push` to commit if needed and push the current
+branch after the metrics surface is refreshed.
+

{atomadic_forge-0.75.2 → atomadic_forge-0.75.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atomadic-forge"
-version = "0.75.2"
+version = "0.75.3"
 description = "Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code."
 readme = "README.md"
 requires-python = ">=3.10"

{atomadic_forge-0.75.2 → atomadic_forge-0.75.3}/src/atomadic_forge/a1_at_functions/repo_public_surface.py

@@ -12,6 +12,8 @@ import re
 from typing import Any
 
 SCHEMA_VERSION_REPO_METRICS_V1 = "atomadic-forge.repo_metrics/v1"
+SCHEMA_VERSION_REPO_METRICS_CONFIG_V1 = "atomadic-forge.repo_metrics_config/v1"
+DEFAULT_REPO_METRICS_CONFIG_PATH = ".atomadic-forge/repo-metrics.config.json"
 
 _SOURCE_EXTS = {
     ".py": "Python",
@@ -44,6 +46,32 @@ _SKIP_PARTS = {
 _TEST_NAME_RE = re.compile(r"(^test_|_test\.|\.test\.|\.spec\.)")
 _PYPROJECT_VERSION_RE = re.compile(r'(?m)^version\s*=\s*"([^"]+)"')
 _PYPROJECT_NAME_RE = re.compile(r'(?m)^name\s*=\s*"([^"]+)"')
+_METRIC_MARKER_RE = re.compile(
+    r"(?P<open><!--\s*forge:metric(?P<attrs>[^>]*)-->)"
+    r"(?P<body>.*?)"
+    r"(?P<close><!--\s*/forge:metric\s*-->)",
+    re.DOTALL,
+)
+_FENCED_CODE_RE = re.compile(r"(```.*?```)", re.DOTALL)
+_ATTR_RE = re.compile(r"\b(?P<key>[a-zA-Z_][a-zA-Z0-9_-]*)\s*=\s*"
+                      r"(?P<quote>['\"]?)(?P<value>[^'\"\s]+)(?P=quote)")
+
+DEFAULT_REPO_METRICS_CONFIG: dict[str, Any] = {
+    "schema_version": SCHEMA_VERSION_REPO_METRICS_CONFIG_V1,
+    "artifact_path": "repo_metrics.json",
+    "document_globs": [
+        "README.md",
+        "docs/**/*.md",
+        "site/**/*.md",
+        "website/**/*.md",
+        "app/**/*.mdx",
+        "src/**/*.mdx",
+    ],
+    "readme_block": True,
+    "sync_server_json": True,
+    "extra_metrics": {},
+    "aliases": {},
+}
 
 
 def should_skip_public_metric_path(path_parts: tuple[str, ...]) -> bool:
@@ -117,6 +145,40 @@ def compute_repo_public_metrics_from_records(
     }
 
 
+def normalize_repo_metrics_config(raw: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Return a forward-compatible repo metrics config."""
+    config = dict(DEFAULT_REPO_METRICS_CONFIG)
+    incoming = raw or {}
+    for key, value in incoming.items():
+        if key in {"document_globs"} and isinstance(value, list):
+            config[key] = [str(item) for item in value if str(item).strip()]
+        elif key in {"readme_block", "sync_server_json"}:
+            config[key] = bool(value)
+        elif key in {"extra_metrics", "aliases"} and isinstance(value, dict):
+            config[key] = dict(value)
+        elif key == "artifact_path" and str(value).strip():
+            config[key] = str(value)
+        elif key == "schema_version":
+            config[key] = str(value)
+    if not config["document_globs"]:
+        config["document_globs"] = list(DEFAULT_REPO_METRICS_CONFIG["document_globs"])
+    return config
+
+
+def render_repo_metrics_config_json(config: dict[str, Any] | None = None) -> str:
+    """Stable starter config for any repo using ``forge metrics repo``."""
+    return json.dumps(normalize_repo_metrics_config(config), indent=2, sort_keys=True) + "\n"
+
+
+def metrics_with_config(metrics: dict[str, Any], config: dict[str, Any]) -> dict[str, Any]:
+    """Overlay configured customer metrics onto computed repo metrics."""
+    combined = dict(metrics)
+    extra = config.get("extra_metrics", {})
+    if isinstance(extra, dict):
+        combined.update(extra)
+    return combined
+
+
 def render_repo_metrics_json(metrics: dict[str, Any]) -> str:
     """Stable JSON for ``repo_metrics.json``."""
     return json.dumps(metrics, indent=2, sort_keys=True) + "\n"
@@ -160,6 +222,72 @@ def render_readme_with_metrics(readme_text: str, metrics: dict[str, Any]) -> str
     return readme_text.rstrip() + "\n\n" + block
 
 
+def _parse_marker_attrs(attrs: str) -> dict[str, str]:
+    parsed = {m.group("key"): m.group("value") for m in _ATTR_RE.finditer(attrs)}
+    if "key" not in parsed:
+        for token in attrs.strip().split():
+            if "=" not in token:
+                parsed["key"] = token.strip()
+                break
+    return parsed
+
+
+def _resolve_metric_value(metrics: dict[str, Any], aliases: dict[str, Any], key: str) -> Any:
+    target = aliases.get(key, key)
+    current: Any = metrics
+    for part in str(target).split("."):
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return None
+    return current
+
+
+def format_metric_value(value: Any, fmt: str = "plain") -> str:
+    """Render a metric value for inline docs/site markers."""
+    if fmt == "json":
+        return json.dumps(value, sort_keys=True)
+    if isinstance(value, list):
+        value = ", ".join(str(item) for item in value)
+    if fmt == "comma" and isinstance(value, int):
+        return f"{value:,}"
+    if fmt == "compact" and isinstance(value, int):
+        if abs(value) >= 1_000_000:
+            return f"{value / 1_000_000:.1f}M".replace(".0M", "M")
+        if abs(value) >= 1_000:
+            return f"{value / 1_000:.0f}K"
+    return str(value)
+
+
+def render_text_with_metric_markers(
+    text: str,
+    metrics: dict[str, Any],
+    config: dict[str, Any] | None = None,
+) -> str:
+    """Refresh inline ``forge:metric`` markers in arbitrary text."""
+    normalized = normalize_repo_metrics_config(config)
+    aliases = normalized.get("aliases", {})
+    if not isinstance(aliases, dict):
+        aliases = {}
+
+    def replace(match: re.Match[str]) -> str:
+        attrs = _parse_marker_attrs(match.group("attrs"))
+        key = attrs.get("key")
+        if not key:
+            return match.group(0)
+        value = _resolve_metric_value(metrics, aliases, key)
+        if value is None:
+            return match.group(0)
+        rendered = format_metric_value(value, attrs.get("format", "plain"))
+        return f"{match.group('open')}{rendered}{match.group('close')}"
+
+    parts = _FENCED_CODE_RE.split(text)
+    for idx, part in enumerate(parts):
+        if idx % 2 == 0:
+            parts[idx] = _METRIC_MARKER_RE.sub(replace, part)
+    return "".join(parts)
+
+
 def render_server_json_with_metrics(server_text: str, metrics: dict[str, Any]) -> str:
     """Update MCP registry/server metadata from repo metrics."""
     data = json.loads(server_text)
@@ -184,32 +312,53 @@ def plan_repo_public_surface_from_inputs(
     metrics: dict[str, Any],
     readme_text: str | None = None,
     server_text: str | None = None,
+    documents: dict[str, str] | None = None,
+    config: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Return planned public-surface writes from already-loaded inputs."""
+    normalized = normalize_repo_metrics_config(config)
+    rendered_metrics = metrics_with_config(metrics, normalized)
     writes: list[dict[str, str]] = [{
-        "path": "repo_metrics.json",
+        "path": str(normalized.get("artifact_path") or "repo_metrics.json"),
         "reason": "canonical product metrics",
-        "content": render_repo_metrics_json(metrics),
+        "content": render_repo_metrics_json(rendered_metrics),
     }]
-    if readme_text is not None:
+    document_texts = dict(documents or {})
+    if readme_text is not None and "README.md" not in document_texts:
+        document_texts["README.md"] = readme_text
+    for path, text in sorted(document_texts.items()):
+        if path == "README.md" and normalized.get("readme_block", True):
+            continue
+        updated = render_text_with_metric_markers(text, rendered_metrics, normalized)
+        if updated != text:
+            writes.append({
+                "path": path,
+                "reason": "Forge metric markers",
+                "content": updated,
+            })
+    if readme_text is not None and normalized.get("readme_block", True):
+        marked_readme = render_text_with_metric_markers(
+            readme_text, rendered_metrics, normalized
+        )
         writes.append({
             "path": "README.md",
             "reason": "Forge-managed public metrics copy block",
-            "content": render_readme_with_metrics(readme_text, metrics),
+            "content": render_readme_with_metrics(marked_readme, rendered_metrics),
         })
-    if server_text is not None:
+    if server_text is not None and normalized.get("sync_server_json", True):
         try:
             writes.append({
                 "path": "server.json",
                 "reason": "MCP registry metadata version/description sync",
-                "content": render_server_json_with_metrics(server_text, metrics),
+                "content": render_server_json_with_metrics(server_text, rendered_metrics),
             })
         except json.JSONDecodeError:
             pass
     return {
         "schema_version": "atomadic-forge.repo_public_surface_plan/v1",
         "project_root": project_root,
-        "metrics": metrics,
+        "config": normalized,
+        "metrics": rendered_metrics,
         "writes": writes,
         "write_count": len(writes),
     }
@@ -217,12 +366,19 @@ def plan_repo_public_surface_from_inputs(
 
 __all__ = [
     "SCHEMA_VERSION_REPO_METRICS_V1",
+    "SCHEMA_VERSION_REPO_METRICS_CONFIG_V1",
+    "DEFAULT_REPO_METRICS_CONFIG_PATH",
     "compute_repo_public_metrics_from_records",
+    "format_metric_value",
     "infer_project_identity_from_metadata",
+    "metrics_with_config",
+    "normalize_repo_metrics_config",
     "plan_repo_public_surface_from_inputs",
     "render_readme_metrics_block",
     "render_readme_with_metrics",
+    "render_repo_metrics_config_json",
     "render_repo_metrics_json",
     "render_server_json_with_metrics",
+    "render_text_with_metric_markers",
     "should_skip_public_metric_path",
 ]

{atomadic_forge-0.75.2 → atomadic_forge-0.75.3}/src/atomadic_forge/a2_mo_composites/repo_public_surface_sync.py

@@ -6,13 +6,17 @@ metric computation/rendering to ``a1_at_functions/repo_public_surface.py``.
 """
 from __future__ import annotations
 
+import json
 from pathlib import Path
 from typing import Any
 
 from atomadic_forge.a1_at_functions.repo_public_surface import (
+    DEFAULT_REPO_METRICS_CONFIG_PATH,
     compute_repo_public_metrics_from_records,
     infer_project_identity_from_metadata,
+    normalize_repo_metrics_config,
     plan_repo_public_surface_from_inputs,
+    render_repo_metrics_config_json,
     should_skip_public_metric_path,
 )
 
@@ -34,6 +38,38 @@ def _identity_for_root(root: Path) -> dict[str, str]:
     )
 
 
+def _safe_relative_path(path_text: str, fallback: str) -> str:
+    path = Path(path_text)
+    if path.is_absolute() or ".." in path.parts:
+        return fallback
+    return path.as_posix()
+
+
+def load_repo_metrics_config(
+    project_root: Path | str,
+    config_path: Path | str | None = None,
+) -> dict[str, Any]:
+    """Load optional repo metrics config, falling back to defaults."""
+    root = Path(project_root).resolve()
+    path = Path(config_path) if config_path else root / DEFAULT_REPO_METRICS_CONFIG_PATH
+    if not path.is_absolute():
+        path = root / path
+    raw: dict[str, Any] = {}
+    if path.exists():
+        try:
+            loaded = json.loads(_read_text(path))
+            if isinstance(loaded, dict):
+                raw = loaded
+        except json.JSONDecodeError:
+            raw = {}
+    config = normalize_repo_metrics_config(raw)
+    config["artifact_path"] = _safe_relative_path(
+        str(config.get("artifact_path") or "repo_metrics.json"),
+        "repo_metrics.json",
+    )
+    return config
+
+
 def compute_repo_public_metrics(project_root: Path | str) -> dict[str, Any]:
     """Compute product-facing metrics for any source repository."""
     root = Path(project_root).resolve()
@@ -52,9 +88,31 @@ def compute_repo_public_metrics(project_root: Path | str) -> dict[str, Any]:
     return compute_repo_public_metrics_from_records(_identity_for_root(root), records)
 
 
-def plan_repo_public_surface_sync(project_root: Path | str) -> dict[str, Any]:
+def _configured_documents(root: Path, config: dict[str, Any]) -> dict[str, str]:
+    documents: dict[str, str] = {}
+    for pattern in config.get("document_globs") or []:
+        pattern_text = str(pattern)
+        if not pattern_text or Path(pattern_text).is_absolute():
+            continue
+        for path in root.glob(pattern_text):
+            if not path.is_file():
+                continue
+            rel_path = path.relative_to(root)
+            if should_skip_public_metric_path(tuple(rel_path.parts)):
+                continue
+            if path.suffix.lower() not in {".md", ".mdx", ".html", ".htm"}:
+                continue
+            documents[rel_path.as_posix()] = _read_text(path)
+    return documents
+
+
+def plan_repo_public_surface_sync(
+    project_root: Path | str,
+    config_path: Path | str | None = None,
+) -> dict[str, Any]:
     """Return planned public-surface writes for any product repo."""
     root = Path(project_root).resolve()
+    config = load_repo_metrics_config(root, config_path=config_path)
     readme = root / "README.md"
     server = root / "server.json"
     return plan_repo_public_surface_from_inputs(
@@ -62,10 +120,14 @@ def plan_repo_public_surface_sync(project_root: Path | str) -> dict[str, Any]:
         metrics=compute_repo_public_metrics(root),
         readme_text=_read_text(readme) if readme.exists() else None,
         server_text=_read_text(server) if server.exists() else None,
+        documents=_configured_documents(root, config),
+        config=config,
     )
 
 
 __all__ = [
     "compute_repo_public_metrics",
+    "load_repo_metrics_config",
     "plan_repo_public_surface_sync",
+    "render_repo_metrics_config_json",
 ]

{atomadic_forge-0.75.2 → atomadic_forge-0.75.3}/src/atomadic_forge/commands/metrics.py

@@ -18,13 +18,16 @@ Usage::
 from __future__ import annotations
 
 import json
+import subprocess
 from pathlib import Path
 from typing import Annotated
 
 import typer
 
 from atomadic_forge.a2_mo_composites.repo_public_surface_sync import (
+    DEFAULT_REPO_METRICS_CONFIG_PATH,
     plan_repo_public_surface_sync,
+    render_repo_metrics_config_json,
 )
 from atomadic_forge.a3_og_features.forge_metrics_feature import emit_forge_metrics
 
@@ -140,6 +143,30 @@ def repo_cmd(
         "--json",
         help="Emit the plan as JSON.",
     )] = False,
+    config: Annotated[Path | None, typer.Option(
+        "--config",
+        help="Optional repo metrics config JSON path.",
+        exists=False,
+        file_okay=True,
+        dir_okay=False,
+        resolve_path=False,
+    )] = None,
+    init_config: Annotated[bool, typer.Option(
+        "--init-config",
+        help="Create a starter .atomadic-forge/repo-metrics.config.json.",
+    )] = False,
+    commit: Annotated[bool, typer.Option(
+        "--commit",
+        help="After --apply, commit the repo metrics surface changes.",
+    )] = False,
+    push: Annotated[bool, typer.Option(
+        "--push",
+        help="After --apply, commit if needed and push the current branch.",
+    )] = False,
+    message: Annotated[str, typer.Option(
+        "--message",
+        help="Commit message used with --commit/--push.",
+    )] = "docs(metrics): sync repo public metrics",
 ) -> None:
     """Update a product repo's own public metrics and copy surface.
 
@@ -148,7 +175,29 @@ def repo_cmd(
     README block between ``<!-- forge:metrics:start -->`` markers, and
     syncs MCP ``server.json`` version/description when present.
     """
-    plan = plan_repo_public_surface_sync(project)
+    root = project.resolve()
+    if init_config:
+        target = config if config is not None else Path(DEFAULT_REPO_METRICS_CONFIG_PATH)
+        target_path = target if target.is_absolute() else root / target
+        content = render_repo_metrics_config_json()
+        if json_out:
+            typer.echo(json.dumps({
+                "schema_version": "atomadic-forge.repo_metrics_config_plan/v1",
+                "path": str(target_path),
+                "content": content,
+                "would_write": not apply,
+            }, indent=2, sort_keys=True))
+            return
+        if apply:
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            target_path.write_text(content, encoding="utf-8")
+            typer.echo(f"wrote {target_path}")
+        else:
+            typer.echo(f"would write {target_path}")
+            typer.echo("\n(dry-run; pass --apply to create the config)")
+        return
+
+    plan = plan_repo_public_surface_sync(root, config_path=config)
     if json_out:
         typer.echo(json.dumps(plan, indent=2, sort_keys=True))
         return
@@ -167,12 +216,45 @@ def repo_cmd(
         "  languages             : "
         + ", ".join(plan["metrics"].get("languages") or ["unknown"])
     )
+    written_paths: list[str] = []
     for write in plan["writes"]:
-        target = project / write["path"]
+        target = (root / write["path"]).resolve()
+        try:
+            target.relative_to(root)
+        except ValueError:
+            typer.echo(f"  skipped {write['path']} — outside project root", err=True)
+            continue
         if apply:
+            target.parent.mkdir(parents=True, exist_ok=True)
             target.write_text(write["content"], encoding="utf-8")
+            written_paths.append(write["path"])
             typer.echo(f"  wrote {write['path']} — {write['reason']}")
         else:
             typer.echo(f"  would write {write['path']} — {write['reason']}")
     if not apply:
         typer.echo("\n(dry-run; pass --apply to update the product surface)")
+        return
+    if (commit or push) and written_paths:
+        subprocess.run(["git", "add", *written_paths], cwd=str(root), check=True)
+        diff = subprocess.run(
+            ["git", "diff", "--cached", "--quiet"],
+            cwd=str(root),
+        )
+        if diff.returncode == 0:
+            typer.echo("  no metric changes to commit")
+        else:
+            subprocess.run(["git", "commit", "-m", message], cwd=str(root), check=True)
+            typer.echo(f"  committed — {message}")
+    if push:
+        branch = subprocess.run(
+            ["git", "branch", "--show-current"],
+            cwd=str(root),
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+        if not branch:
+            typer.echo("  push skipped — detached HEAD", err=True)
+            return
+        subprocess.run(["git", "push", "-u", "origin", branch], cwd=str(root), check=True)
+        typer.echo(f"  pushed origin/{branch}")

{atomadic_forge-0.75.2 → atomadic_forge-0.75.3/src/atomadic_forge.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomadic-forge
-Version: 0.75.2
+Version: 0.75.3
 Summary: Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Rust · Go · Swift · Kotlin) architecture guardian for AI-generated code.
 Author: Atomadic
 License-Expression: BUSL-1.1