Merge pull request 'Release v0.9.1' (#302) from jgstern-agent/release/0.9.1 into main

Reviewed-on: https://codeberg.org/iterabloom/hypergumbo/pulls/302

Author: jgstern

CHANGELOG.md

@@ -2,14 +2,28 @@
 
 All notable changes to hypergumbo are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-- Released **tool** is at: v0.9.0
+- Released **tool** is at: v0.9.1
 - Released **schema** is at: v0.2.0
 
 This changelog tracks the **tool version** (package releases). The **schema version** (output format) is tracked separately in `schema.py` as `SCHEMA_VERSION`. The schema version only changes when the JSON output format has breaking changes.
 
 ## [Unreleased]
 
-## [0.9.0] - 2026-01-09
+## [0.9.1] - 2026-01-09
+
+### Fixed
+- **Incomplete v0.9.0 release:** The v0.9.0 release was accidentally built from the wrong branch
+  and did not include the ADR-0003 implementation (framework patterns, `--frameworks` flag,
+  semantic entry detection, etc.). This release includes all the features described in the
+  v0.9.0 changelog. Users should upgrade from v0.9.0 to v0.9.1.
+
+### Added
+- Regenerated `docs/ARCHITECTURE.md` with current codebase metrics.
+
+## [0.9.0] - 2026-01-09 (INCOMPLETE RELEASE)
+
+> **Warning:** This release was built from the wrong branch and is missing most features
+> described below. Please use v0.9.1 instead.
 
 ### Changed (Breaking)
 - **Schema version 0.2.0:** The output schema version bumped from 0.1.0 to 0.2.0.

docs/ARCHITECTURE.md

@@ -5,25 +5,25 @@
 
 <!--
 GENERATION METADATA (for drift detection):
-  commit: 7adfcdc07367
-  hypergumbo: 0.6.0
+  commit: 83810f78db4d
+  hypergumbo: 0.9.0
   python: 3.12.3
 -->
 
 ## Self-Analysis Summary
 
 hypergumbo analyzed its own source code and found:
-- **105** Python modules (68 analyzers, 14 linkers)
-- **1638** symbols (functions, classes, methods)
-- **5966** edges (calls, imports, instantiates)
+- **107** Python modules (68 analyzers, 14 linkers)
+- **1688** symbols (functions, classes, methods)
+- **6143** edges (calls, imports, instantiates)
 
 ## Sketch (hypergumbo on hypergumbo)
 
 ```markdown
 # src
 
 ## Overview
-Python (100%) · 109 files · ~45,031 LOC
+Python (98%), Yaml (2%) · 126 files · ~48,452 LOC
 
 ## Structure
 
@@ -46,10 +46,12 @@ Python (100%) · 109 files · ~45,031 LOC
 - `hypergumbo/cli.py`
 - `hypergumbo/metrics.py`
 - `hypergumbo/compact.py`
+- `hypergumbo/framework_patterns.py`
 - `hypergumbo/slice.py`
 - `hypergumbo/entrypoints.py`
 - `hypergumbo/build_grammars.py`
 - `hypergumbo/__main__.py`
+- `hypergumbo/sketch_embeddings.py`
 - `hypergumbo/llm_assist.py`
 - `hypergumbo/profile.py`
 - `hypergumbo/plan.py`
@@ -63,9 +65,7 @@ Python (100%) · 109 files · ~45,031 LOC
 - `hypergumbo/analyze/sql.py`
 - `hypergumbo/analyze/capnp.py`
 - `hypergumbo/analyze/groovy.py`
-- `hypergumbo/analyze/registry.py`
-- `hypergumbo/analyze/xml_config.py`
-- ... and 79 more files
+- ... and 81 more files
 
 ## Entry Points
 
@@ -81,23 +81,24 @@ Python (100%) · 109 files · ~45,031 LOC
 - `Edge` (class) — A relationship between two symbols (e.g., function calls).
 
 ### `hypergumbo/analyze/base.py`
+- `node_text(node: 'tree_sitter.Node', source: bytes) -> str` (function) ★ — Extract text content for a tree-sitter node.
 - `iter_tree(root: 'tree_sitter.Node') -> Iterator['tree_sitter.Node']` (function) — Iterate over all nodes in a tree-sitter tree without recursion.
-- `node_text(node: 'tree_sitter.Node', source: bytes) -> str` (function) — Extract text content for a tree-sitter node.
 
 ### `hypergumbo/discovery.py`
 - `find_files(repo_root: Path, patterns: list[str], excludes: list[str] …` (function) — Find files matching patterns while respecting exclude rules.
 
 ### `hypergumbo/catalog.py`
 - `Pass` (class) — An analysis pass that can be applied to source code.
 
-### `hypergumbo/analyze/julia.py`
-- `_find_child_by_type(node: 'tree_sitter.Node', type_name: str) -> Optional['tre…` (function) — Find first child of given type.
-- `_node_text(node: 'tree_sitter.Node', source: bytes) -> str` (function) — Extract text for a tree-sitter node.
-
 ### `hypergumbo/entrypoints.py`
 - `Entrypoint` (class) — A detected entrypoint in the codebase.
+- `_emit_path_deprecation_warning(framework: str) -> None` (function) — Emit a deprecation warning for path-based entrypoint detection.
 - `_get_filename(path: str) -> str` (function) — Extract filename from path.
 
+### `hypergumbo/analyze/julia.py`
+- `_find_child_by_type(node: 'tree_sitter.Node', type_name: str) -> Optional['tre…` (function) — Find first child of given type.
+- `_node_text(node: 'tree_sitter.Node', source: bytes) -> str` (function) — Extract text for a tree-sitter node.
+
 ### `hypergumbo/analyze/rust.py`
 - `_find_child_by_field(node: 'tree_sitter.Node', field_name: str) -> Optional['tr…` (function) — Find child by field name.
 
@@ -107,10 +108,13 @@ Python (100%) · 109 files · ~45,031 LOC
 ### `hypergumbo/linkers/registry.py`
 - `LinkerResult` (class) — Result from running a linker.
 
-(... and 1499 more symbols across 87 other files)
+### `hypergumbo/analyze/py.py`
+- `_format_annotation(node: ast.expr) -> str` (function) — Format a type annotation node to a readable string.
+
+(... and 1554 more symbols across 89 other files)
 
 The following symbols, for brevity shown only once above, would have appeared multiple times:
-- `_node_text` - we omitted 8 appearances of `_node_text`
+- `_node_text` - we omitted 6 appearances of `_node_text`
 - `_find_child_by_type` - we omitted 5 appearances
 
 ## All Files
@@ -167,13 +171,7 @@ The following symbols, for brevity shown only once above, would have appeared mu
 - `hypergumbo/analyze/php.py`
 - `hypergumbo/analyze/powershell.py`
 - `hypergumbo/analyze/proto.py`
-- `hypergumbo/analyze/py.py`
-- `hypergumbo/analyze/r_lang.py`
-- `hypergumbo/analyze/registry.py`
-- `hypergumbo/analyze/ruby.py`
-- `hypergumbo/analyze/rust.py`
-- `hypergumbo/analyze/scala.py`
-- ... and 51 more files
+- ... and 74 more files
 ```
 
 ## Data Flow
@@ -188,7 +186,7 @@ Source Files
      │                    │
      ▼                    ▼
 ┌─────────────┐     ┌─────────────┐
-│  analyzers  │────▶│     IR      │  1638 Symbols + 5966 Edges
+│  analyzers  │────▶│     IR      │  1688 Symbols + 6143 Edges
 └─────────────┘     └─────────────┘
      │                    │
      ▼                    ▼
@@ -210,12 +208,12 @@ These symbols have the highest in-degree (most referenced by other symbols):
 
 | Symbol | Kind | In-Degree | Location |
 |--------|------|-----------|----------|
-| `Symbol` | class | 333 | ir.py |
+| `Symbol` | class | 334 | ir.py |
 | `Span` | class | 322 | ir.py |
 | `iter_tree` | function | 160 | base.py |
 | `find_files` | function | 147 | discovery.py |
+| `node_text` | function | 131 | base.py |
 | `Edge` | class | 127 | ir.py |
-| `node_text` | function | 98 | base.py |
 | `AnalysisRun` | class | 92 | ir.py |
 | `Pass` | class | 66 | catalog.py |
 | `_find_child_by_type` | function | 30 | julia.py |
@@ -229,6 +227,7 @@ These symbols have the highest in-degree (most referenced by other symbols):
 - **`compact`**: Compact output mode with coverage-based truncation and residual sum...
 - **`discovery`**: File discovery with exclude patterns.
 - **`entrypoints`**: Entrypoint detection heuristics for code analysis.
+- **`framework_patterns`**: Framework pattern matching for symbol enrichment (ADR-0003 v0.8.x).
 - **`ir`**: Internal Representation (IR) for code analysis.
 - **`limits`**: Limits tracking for behavior map output.
 - **`llm_assist`**: LLM-assisted capsule plan generation.
@@ -238,6 +237,7 @@ These symbols have the highest in-degree (most referenced by other symbols):
 - **`selection.filters`**: Path classification and symbol kind filtering for selection.
 - **`selection.language_proportional`**: Language-proportional symbol selection utilities.
 - **`selection.token_budget`**: Token estimation and budget management for LLM-aware output.
+- **`sketch_embeddings`**: Embedding-based config extraction for sketch generation.
 - **`slice`**: Graph slicing for LLM context extraction.
 - **`supply_chain`**: Supply chain classification for code analysis.
 - **`user_config`**: User configuration management for hypergumbo.
@@ -383,6 +383,74 @@ Provenance tracking for reproducibility:
 4. Create cross-language edges
 5. Add tests in `tests/test_<name>_linker.py`
 
+## Framework Patterns Architecture (ADR-0003)
+
+> **Note:** This section is manually maintained. See `docs/adr/0003-architectural-analysis-and-revision-plan.md` for the full design rationale.
+
+ADR-0003 introduced a layered architecture for framework-aware analysis:
+
+```
+Source Files
+     │
+     ▼
+┌─────────────────┐
+│    Analyzers    │  Extract language-level metadata only
+│   (py.py, etc.) │  - Decorators, annotations, base classes
+└─────────────────┘  - No framework-specific interpretation
+     │
+     ▼
+┌─────────────────────────┐
+│  FRAMEWORK_PATTERNS     │  Data-driven symbol enrichment
+│  (framework_patterns.py)│  - YAML pattern files define framework patterns
+└─────────────────────────┘  - Symbols enriched with concept metadata
+     │
+     ▼
+┌─────────────────┐
+│    Linkers      │  Cross-language edge creation
+│   (http.py, etc)│  - Use concept metadata for matching
+└─────────────────┘  - Fall back to legacy meta.route_path
+```
+
+### Key Components
+
+- **`framework_patterns.py`**: Loads and applies YAML pattern files
+- **`frameworks/*.yaml`**: Pattern definitions for each framework
+- **`meta.concepts`**: List of matched concepts on enriched symbols
+- **`meta.annotations`/`meta.decorators`**: Raw metadata for pattern matching
+
+### Adding a New Framework Pattern
+
+1. Create `src/hypergumbo/frameworks/<framework>.yaml`
+2. Define patterns matching decorator/annotation names
+3. Specify concept types (route, model, task, etc.)
+4. Add extraction methods for path/method if needed
+5. Add tests in `tests/test_framework_patterns.py`
+
+Example pattern:
+```yaml
+id: myframework
+language: python
+
+patterns:
+  - concept: route
+    decorator: "^myapp\\.(get|post|put|delete)$"
+    extract_path: "args[0]"
+    extract_method: "decorator_suffix"
+```
+
+### Migration Status (v1.0.x)
+
+Analyzer-level route detection is deprecated. Deprecation warnings fire when:
+- Spring Boot/JAX-RS routes detected in Java
+- Django URL patterns detected in Python
+- ASP.NET Core routes detected in C#
+- Axum/Actix routes detected in Rust
+- Rails routes detected in Ruby
+- Laravel routes detected in PHP
+- Express routes detected in JavaScript/TypeScript
+
+Use `--frameworks` flag with YAML patterns instead.
+
 ---
 
 *Generated by `./scripts/generate-architecture` using hypergumbo self-analysis.*

docs/RELEASE_SOP.md

@@ -214,9 +214,11 @@ This script:
 
 #### Step 3: Human Creates Signed Tag
 
+**Before running:** Have both your Codeberg SSH key passphrase and GPG signing key passphrase ready. The script makes multiple SSH connections and a GPG signing operation in quick succession, and passphrase timeouts between steps can cause the push to fail.
+
 ```bash
 # Human runs this after merging the PR
-./scripts/tag-release 0.8.0
+./scripts/tag-release 0.9.1
 ```
 
 This script:

docs/hypergumbo-spec.md

@@ -1636,13 +1636,31 @@ This prefers well-connected entries, producing richer slices.
 
 See [ADR-0003 §5.2](adr/0003-architectural-analysis-and-revision-plan.md#52-migration-path) for the authoritative migration plan.
 
-| Version | Focus | Entry Detection Impact |
-|---------|-------|------------------------|
-| **v0.6.x** | Path heuristics + exclusions | Current state |
-| **v0.7.x** | Foundation: metadata enrichment, `--frameworks` flag | Analyzers capture richer metadata |
-| **v0.8.x** | FRAMEWORK_PATTERNS phase (YAML-driven) | Symbols enriched with concept metadata |
-| **v0.9.x** | Semantic entry detection | `entrypoints.py` queries enriched metadata; path heuristics deprecated (retained only for `main()` fallback) |
-| **v1.0.x** | Complete extraction | All frameworks as YAML; all analyzers pure |
+| Version | Focus | Entry Detection Impact | Status |
+|---------|-------|------------------------|--------|
+| **v0.6.x** | Path heuristics + exclusions | Current state | 🟩 |
+| **v0.7.x** | Foundation: metadata enrichment, `--frameworks` flag | Analyzers capture richer metadata | 🟩 |
+| **v0.8.x** | FRAMEWORK_PATTERNS phase (YAML-driven) | Symbols enriched with concept metadata | 🟩 |
+| **v0.9.x** | Semantic entry detection | `entrypoints.py` queries enriched metadata; path heuristics deprecated (retained only for `main()` fallback) | 🟩 |
+| **v1.0.x** | Complete extraction | All frameworks as YAML; all analyzers pure | 🟨 |
+
+**v0.8.x (complete):**
+- 🟩 `framework_patterns.py` module with YAML-driven pattern matching
+- 🟩 FastAPI patterns YAML (`fastapi.yaml`)
+- 🟩 `enrich_symbols()` called in CLI pipeline after analyzers
+- 🟩 Linkers respect activation conditions (conditional execution)
+- 🟩 Flask, NestJS, Spring Boot, Django, Express, Celery, Rails, Phoenix, Laravel, Go Web patterns
+- 🟩 HTTP linker supports concept metadata from FRAMEWORK_PATTERNS phase
+
+**v0.9.x (complete):**
+- 🟩 Semantic entry detection via `_detect_from_concepts()` in entrypoints.py
+- 🟩 Path heuristics deprecated with warnings
+- 🟩 CLI `main()` detection retained as non-deprecated fallback
+- 🟩 ASP.NET Core, Rust web (Actix, Axum, Rocket, Diesel, SeaORM), Hapi, Koa patterns
+
+**v1.0.x (in progress):**
+- 🟩 Deprecation warnings added to all analyzer-level route detection
+- 🟧 Remaining: purify analyzers by removing framework logic entirely (post-deprecation)
 
 ## 9) Testing & quality bar
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypergumbo"
-version = "0.9.0"
+version = "0.9.1"
 description = "Local-first repo behavior map generator (MVP)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -99,6 +99,15 @@ filterwarnings = [
     "ignore:.*analysis skipped.*requires tree-sitter:UserWarning",
     # tree-sitter deprecation warnings (older grammar packages)
     "ignore:int argument support is deprecated:DeprecationWarning",
+    # Pack deprecation warnings (ADR-0003)
+    "ignore:Packs are deprecated:DeprecationWarning",
+    "ignore:PackConfig is deprecated:DeprecationWarning",
+]
+
+[tool.coverage.run]
+# Omit optional modules that require extra dependencies
+omit = [
+    "*/sketch_embeddings.py",  # Requires sentence-transformers
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -131,8 +140,8 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
-# Tests can use assert, hardcoded values, subprocess, temp paths
-"tests/**/*.py" = ["S101", "S105", "S106", "S603", "S108", "E741", "F841", "RUF005"]
+# Tests can use assert, hardcoded values, subprocess, temp paths, side-effect imports
+"tests/**/*.py" = ["S101", "S105", "S106", "S603", "S108", "E741", "F401", "F841", "RUF005"]
 # Conditional imports for optional tree-sitter deps
 "src/hypergumbo/analyze/*.py" = ["E402"]