codd-dev 1.9.2__tar.gz → 1.11.0__tar.gz

{codd_dev-1.9.2 → codd_dev-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 1.9.2
+Version: 1.11.0
 Summary: CoDD: Coherence-Driven Development — cross-artifact change impact analysis
 Project-URL: Homepage, https://github.com/yohey-w/codd-dev
 Project-URL: Repository, https://github.com/yohey-w/codd-dev
@@ -60,6 +60,19 @@ Description-Content-Type: text/markdown
 pip install codd-dev
 ```
 
+## 🆕 v1.11.0 — Filesystem-Routing Aware Drift Detection
+
+CoDD now understands filesystem-routing frameworks (Next.js, SvelteKit, Nuxt, Astro, Remix) and can detect URL drift between your design docs and actual implementation.
+
+- 📐 `FileSystemRouteExtractor` — endpoint nodes from directory structure
+- 🔗 `DocumentUrlLinker` — auto-link design doc URLs to endpoints
+- 🔍 `codd drift` — find URL gaps between design and implementation
+- 🎨 `codd extract --layer routes` — reverse-engineer screen-flow diagrams
+
+See [Filesystem Routing Adapter Recipes](#filesystem-routing-adapter-recipes) for setup.
+
+---
+
 **v1.9.0** — `codd implement` now supports **multi-AI engine** (Claude stdout + Codex file-writing) and **automatic parallel execution** within phases via git worktree isolation. Phase milestone format (`#### M1.1`) supported. AI command timeout extended to 1 hour for heavy reasoning models. SWE-bench Verified: **73/73 = 100%** resolved.
 
 ---
@@ -325,6 +338,133 @@ codd init --config-dir .codd --project-name "my-project" --language "python"
 
 All other commands (`scan`, `impact`, `generate`, etc.) automatically discover whichever config directory exists — `codd/` first, then `.codd/`. No extra flags needed.
 
+## Filesystem Routing Adapter Recipes
+
+CoDD detects URL drift between your design documents and implementation
+using framework conventions declared in `codd.yaml`.
+These recipes cover the five major filesystem-routing frameworks.
+
+| Framework              | Base dir      | Page glob        | API glob                  | Dynamic segment       |
+|------------------------|---------------|------------------|---------------------------|-----------------------|
+| Next.js (App Router)   | `app/`        | `page.{tsx,jsx}` | `route.{ts,js}`           | `[param]` → `:param`  |
+| Next.js (Pages Router) | `pages/`      | `*.{tsx,jsx}`    | `api/**/*.{ts,js}`        | `[param]` → `:param`  |
+| SvelteKit              | `src/routes/` | `+page.svelte`   | `+server.{ts,js}`         | `[param]` → `:param`  |
+| Nuxt 3                 | `pages/`      | `*.vue`          | `server/api/**/*.{ts,js}` | `[param]` → `:param`  |
+| Astro                  | `src/pages/`  | `*.astro`        | `*.{ts,js}` (in pages)    | `[...slug]` → `:slug` |
+| Remix                  | `app/routes/` | `*.{tsx,jsx}`    | `*.{ts,js}`               | `$param` → `:param`   |
+
+### Next.js (App Router)
+
+```yaml
+filesystem_routes:
+  - base_dir: app/
+    page_pattern: "page.{tsx,jsx,ts,js}"
+    api_pattern: "route.{ts,js}"
+    url_template: "/{relative_dir}"
+    dynamic_segment: { from: "\\[(.+)\\]", to: ":$1" }
+    ignore_segment: ["\\(.*\\)", "@.*"]
+    base_url: ""
+```
+
+### Next.js (Pages Router)
+
+```yaml
+filesystem_routes:
+  - base_dir: pages/
+    page_pattern: "*.{tsx,jsx,ts,js}"
+    api_pattern: ""
+    url_template: "/{relative_dir}/{stem}"
+    dynamic_segment: { from: "\\[(.+)\\]", to: ":$1" }
+    ignore_segment: ["^_.*"]
+    base_url: ""
+  - base_dir: pages/api/
+    page_pattern: ""
+    api_pattern: "*.{ts,js}"
+    url_template: "/api/{relative_dir}/{stem}"
+    dynamic_segment: { from: "\\[(.+)\\]", to: ":$1" }
+    ignore_segment: []
+    base_url: ""
+```
+
+### SvelteKit
+
+```yaml
+filesystem_routes:
+  - base_dir: src/routes/
+    page_pattern: "+page.svelte"
+    api_pattern: "+server.{ts,js}"
+    url_template: "/{relative_dir}"
+    dynamic_segment: { from: "\\[(.+)\\]", to: ":$1" }
+    ignore_segment: ["\\(.*\\)"]
+    base_url: ""
+```
+
+### Nuxt 3
+
+```yaml
+filesystem_routes:
+  - base_dir: pages/
+    page_pattern: "*.vue"
+    api_pattern: ""
+    url_template: "/{relative_dir}/{stem}"
+    dynamic_segment: { from: "\\[(.+)\\]", to: ":$1" }
+    ignore_segment: []
+    base_url: ""
+  - base_dir: server/api/
+    page_pattern: ""
+    api_pattern: "*.{ts,js}"
+    url_template: "/api/{relative_dir}/{stem}"
+    dynamic_segment: { from: "\\[(.+)\\]", to: ":$1" }
+    ignore_segment: []
+    base_url: ""
+```
+
+### Astro
+
+```yaml
+filesystem_routes:
+  - base_dir: src/pages/
+    page_pattern: "*.astro"
+    api_pattern: "*.{ts,js}"
+    url_template: "/{relative_dir}/{stem}"
+    dynamic_segment: { from: "\\[\\.\\.\\.(\\w+)\\]", to: ":$1" }
+    ignore_segment: []
+    base_url: ""
+```
+
+### Remix
+
+```yaml
+filesystem_routes:
+  - base_dir: app/routes/
+    page_pattern: "*.{tsx,jsx}"
+    api_pattern: "*.{ts,js}"
+    url_template: "/{segments}"
+    dynamic_segment: { from: "\\$(\\w+)", to: ":$1" }
+    ignore_segment: ["^_.*"]
+    base_url: ""
+```
+
+### Enable URL Drift Detection
+
+Add to `codd.yaml` to automatically link design doc URLs to endpoints:
+
+```yaml
+document_url_linking:
+  enabled: true
+  applies_to: [design, requirement]
+  url_pattern: "(?:^|[\\s`(\\[])(/[a-z0-9][a-z0-9/\\-:_\\[\\]]*)"
+  edge_type: references
+```
+
+Then run:
+
+```bash
+codd drift          # detect URL drift between design docs and implementation
+codd drift --format json  # machine-readable output
+codd extract --layer routes --format mermaid  # generate screen-flow diagram
+```
+
 ## Brownfield? Start Here
 
 Already have a codebase? CoDD provides a full brownfield workflow — from code extraction to design doc reconstruction.

{codd_dev-1.9.2 → codd_dev-1.11.0}/README.md

@@ -22,6 +22,19 @@
 pip install codd-dev
 ```
 
+## 🆕 v1.11.0 — Filesystem-Routing Aware Drift Detection
+
+CoDD now understands filesystem-routing frameworks (Next.js, SvelteKit, Nuxt, Astro, Remix) and can detect URL drift between your design docs and actual implementation.
+
+- 📐 `FileSystemRouteExtractor` — endpoint nodes from directory structure
+- 🔗 `DocumentUrlLinker` — auto-link design doc URLs to endpoints
+- 🔍 `codd drift` — find URL gaps between design and implementation
+- 🎨 `codd extract --layer routes` — reverse-engineer screen-flow diagrams
+
+See [Filesystem Routing Adapter Recipes](#filesystem-routing-adapter-recipes) for setup.
+
+---
+
 **v1.9.0** — `codd implement` now supports **multi-AI engine** (Claude stdout + Codex file-writing) and **automatic parallel execution** within phases via git worktree isolation. Phase milestone format (`#### M1.1`) supported. AI command timeout extended to 1 hour for heavy reasoning models. SWE-bench Verified: **73/73 = 100%** resolved.
 
 ---
@@ -287,6 +300,133 @@ codd init --config-dir .codd --project-name "my-project" --language "python"
 
 All other commands (`scan`, `impact`, `generate`, etc.) automatically discover whichever config directory exists — `codd/` first, then `.codd/`. No extra flags needed.
 
+## Filesystem Routing Adapter Recipes
+
+CoDD detects URL drift between your design documents and implementation
+using framework conventions declared in `codd.yaml`.
+These recipes cover the five major filesystem-routing frameworks.
+
+| Framework              | Base dir      | Page glob        | API glob                  | Dynamic segment       |
+|------------------------|---------------|------------------|---------------------------|-----------------------|
+| Next.js (App Router)   | `app/`        | `page.{tsx,jsx}` | `route.{ts,js}`           | `[param]` → `:param`  |
+| Next.js (Pages Router) | `pages/`      | `*.{tsx,jsx}`    | `api/**/*.{ts,js}`        | `[param]` → `:param`  |
+| SvelteKit              | `src/routes/` | `+page.svelte`   | `+server.{ts,js}`         | `[param]` → `:param`  |
+| Nuxt 3                 | `pages/`      | `*.vue`          | `server/api/**/*.{ts,js}` | `[param]` → `:param`  |
+| Astro                  | `src/pages/`  | `*.astro`        | `*.{ts,js}` (in pages)    | `[...slug]` → `:slug` |
+| Remix                  | `app/routes/` | `*.{tsx,jsx}`    | `*.{ts,js}`               | `$param` → `:param`   |
+
+### Next.js (App Router)
+
+```yaml
+filesystem_routes:
+  - base_dir: app/
+    page_pattern: "page.{tsx,jsx,ts,js}"
+    api_pattern: "route.{ts,js}"
+    url_template: "/{relative_dir}"
+    dynamic_segment: { from: "\\[(.+)\\]", to: ":$1" }
+    ignore_segment: ["\\(.*\\)", "@.*"]
+    base_url: ""
+```
+
+### Next.js (Pages Router)
+
+```yaml
+filesystem_routes:
+  - base_dir: pages/
+    page_pattern: "*.{tsx,jsx,ts,js}"
+    api_pattern: ""
+    url_template: "/{relative_dir}/{stem}"
+    dynamic_segment: { from: "\\[(.+)\\]", to: ":$1" }
+    ignore_segment: ["^_.*"]
+    base_url: ""
+  - base_dir: pages/api/
+    page_pattern: ""
+    api_pattern: "*.{ts,js}"
+    url_template: "/api/{relative_dir}/{stem}"
+    dynamic_segment: { from: "\\[(.+)\\]", to: ":$1" }
+    ignore_segment: []
+    base_url: ""
+```
+
+### SvelteKit
+
+```yaml
+filesystem_routes:
+  - base_dir: src/routes/
+    page_pattern: "+page.svelte"
+    api_pattern: "+server.{ts,js}"
+    url_template: "/{relative_dir}"
+    dynamic_segment: { from: "\\[(.+)\\]", to: ":$1" }
+    ignore_segment: ["\\(.*\\)"]
+    base_url: ""
+```
+
+### Nuxt 3
+
+```yaml
+filesystem_routes:
+  - base_dir: pages/
+    page_pattern: "*.vue"
+    api_pattern: ""
+    url_template: "/{relative_dir}/{stem}"
+    dynamic_segment: { from: "\\[(.+)\\]", to: ":$1" }
+    ignore_segment: []
+    base_url: ""
+  - base_dir: server/api/
+    page_pattern: ""
+    api_pattern: "*.{ts,js}"
+    url_template: "/api/{relative_dir}/{stem}"
+    dynamic_segment: { from: "\\[(.+)\\]", to: ":$1" }
+    ignore_segment: []
+    base_url: ""
+```
+
+### Astro
+
+```yaml
+filesystem_routes:
+  - base_dir: src/pages/
+    page_pattern: "*.astro"
+    api_pattern: "*.{ts,js}"
+    url_template: "/{relative_dir}/{stem}"
+    dynamic_segment: { from: "\\[\\.\\.\\.(\\w+)\\]", to: ":$1" }
+    ignore_segment: []
+    base_url: ""
+```
+
+### Remix
+
+```yaml
+filesystem_routes:
+  - base_dir: app/routes/
+    page_pattern: "*.{tsx,jsx}"
+    api_pattern: "*.{ts,js}"
+    url_template: "/{segments}"
+    dynamic_segment: { from: "\\$(\\w+)", to: ":$1" }
+    ignore_segment: ["^_.*"]
+    base_url: ""
+```
+
+### Enable URL Drift Detection
+
+Add to `codd.yaml` to automatically link design doc URLs to endpoints:
+
+```yaml
+document_url_linking:
+  enabled: true
+  applies_to: [design, requirement]
+  url_pattern: "(?:^|[\\s`(\\[])(/[a-z0-9][a-z0-9/\\-:_\\[\\]]*)"
+  edge_type: references
+```
+
+Then run:
+
+```bash
+codd drift          # detect URL drift between design docs and implementation
+codd drift --format json  # machine-readable output
+codd extract --layer routes --format mermaid  # generate screen-flow diagram
+```
+
 ## Brownfield? Start Here
 
 Already have a codebase? CoDD provides a full brownfield workflow — from code extraction to design doc reconstruction.

{codd_dev-1.9.2 → codd_dev-1.11.0}/codd/cli.py

@@ -589,13 +589,38 @@ def verify(path: str, sprint: int | None, e2e: bool, deploy: bool, base_url: str
     default=None,
     help="Override AI CLI command (default: codd.yaml ai_command or claude --print)",
 )
-@click.option(
-    "--prompt-file",
-    default=None,
-    type=click.Path(exists=True),
-    help="Custom extraction prompt file (overrides built-in baseline preset)",
-)
-def extract(path: str, language: str | None, source_dirs: str | None, output: str | None, ai: bool, ai_cmd: str | None, prompt_file: str | None):
+@click.option(
+    "--prompt-file",
+    default=None,
+    type=click.Path(exists=True),
+    help="Custom extraction prompt file (overrides built-in baseline preset)",
+)
+@click.option(
+    "--layer",
+    default=None,
+    type=click.Choice(["routes"]),
+    help="Extract specific layer (routes: filesystem routes as Mermaid diagram)",
+)
+@click.option(
+    "--format",
+    "output_format",
+    default="mermaid",
+    type=click.Choice(["mermaid"]),
+    help="Output format for --layer extraction",
+)
+@click.option("--output-file", default=None, help="Output file for --layer routes (default: stdout)")
+def extract(
+    path: str,
+    language: str | None,
+    source_dirs: str | None,
+    output: str | None,
+    ai: bool,
+    ai_cmd: str | None,
+    prompt_file: str | None,
+    layer: str | None,
+    output_format: str,
+    output_file: str | None,
+):
     """Extract design documents from existing codebase (brownfield bootstrap).
 
     Default mode: static analysis (no AI, pure structural facts).
@@ -604,16 +629,33 @@ def extract(path: str, language: str | None, source_dirs: str | None, output: st
     Output goes to the discovered CoDD config dir as draft documents
     (`codd/extracted/` or `.codd/extracted/`). Review and promote
     confirmed docs when ready.
-    """
-    project_root = Path(path).resolve()
-    bootstrap_codd_dir = _resolve_bootstrap_codd_dir(project_root)
-    dirs = [d.strip() for d in source_dirs.split(",") if d.strip()] if source_dirs else None
-    output_path = Path(output) if output else bootstrap_codd_dir / "extracted"
-
-    if ai:
-        from codd.extract_ai import run_extract_ai
-        from codd.extractor import extract_facts
-        from codd.config import load_project_config
+    """
+    project_root = Path(path).resolve()
+    bootstrap_codd_dir = _resolve_bootstrap_codd_dir(project_root)
+    dirs = [d.strip() for d in source_dirs.split(",") if d.strip()] if source_dirs else None
+    output_path = Path(output) if output else bootstrap_codd_dir / "extracted"
+
+    if layer == "routes":
+        from codd.config import load_project_config
+        from codd.routes_extractor import generate_mermaid_screen_flow
+
+        config = load_project_config(project_root)
+        route_configs = config.get("filesystem_routes", [])
+        result = generate_mermaid_screen_flow(project_root, route_configs)
+        content = f"```{output_format}\n{result.mermaid}\n```\n"
+        if output_file:
+            destination = Path(output_file)
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            destination.write_text(content, encoding="utf-8")
+            click.echo(f"Extracted {result.route_count} routes -> {output_file}")
+        else:
+            click.echo(content)
+        return
+
+    if ai:
+        from codd.extract_ai import run_extract_ai
+        from codd.extractor import extract_facts
+        from codd.config import load_project_config
 
         # Resolve AI command
         if ai_cmd is None:
@@ -909,6 +951,60 @@ def policy(path: str):
     raise SystemExit(0 if result.pass_ else 1)
 
 
+@main.command("drift")
+@click.option("--path", default=".", help="Project root directory")
+@click.option(
+    "--format",
+    "output_format",
+    default="text",
+    type=click.Choice(["text", "json"]),
+    help="Output format",
+)
+def drift(path: str, output_format: str):
+    """Detect drift between design-referenced URLs and implementation endpoints.
+
+    Exit code 0 = no drift. Exit code 1 = drift detected (use in CI).
+    """
+    from codd.drift import run_drift
+
+    project_root = Path(path).resolve()
+    codd_dir = _require_codd_dir(project_root)
+    result = run_drift(project_root, codd_dir)
+
+    if output_format == "json":
+        click.echo(
+            json.dumps(
+                {
+                    "design_urls": result.design_urls,
+                    "impl_urls": result.impl_urls,
+                    "drift": [
+                        {
+                            "kind": entry.kind,
+                            "url": entry.url,
+                            "source": entry.source,
+                            "closest_match": entry.closest_match,
+                        }
+                        for entry in result.drift
+                    ],
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+    else:
+        for entry in result.drift:
+            label = f"[drift {entry.kind}]"
+            closest = f"  (closest: {entry.closest_match})" if entry.closest_match else ""
+            source = f"  in {entry.source}" if entry.source else ""
+            click.echo(f"{label} {entry.url}{source}{closest}")
+        if not result.drift:
+            click.echo("No drift detected.")
+        else:
+            click.echo(f"\n{len(result.drift)} drift(s) found.")
+
+    raise SystemExit(result.exit_code)
+
+
 @main.command()
 @click.option("--path", default=".", help="Project root directory")
 @click.option("--json", "as_json", is_flag=True, help="Output plan as JSON")

codd_dev-1.11.0/codd/drift.py

@@ -0,0 +1,157 @@
+"""codd drift - Detect design-to-implementation URL drift."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Sequence
+
+
+@dataclass
+class DriftEntry:
+    kind: str
+    url: str
+    source: str
+    closest_match: str
+
+
+@dataclass
+class DriftResult:
+    design_urls: list[str]
+    impl_urls: list[str]
+    drift: list[DriftEntry] = field(default_factory=list)
+    exit_code: int = 0
+
+
+def compute_drift(
+    design_urls: Sequence[str],
+    impl_urls: Sequence[str],
+    design_sources: dict[str, str] | None = None,
+) -> DriftResult:
+    """Compute drift between design-referenced URLs and implementation endpoints."""
+    design_sources = design_sources or {}
+    normalized_design_urls = _unique_urls(design_urls)
+    normalized_impl_urls = _unique_urls(impl_urls)
+    design_set = set(normalized_design_urls)
+    impl_set = set(normalized_impl_urls)
+
+    drift: list[DriftEntry] = []
+    for url in normalized_design_urls:
+        if url not in impl_set:
+            drift.append(
+                DriftEntry(
+                    kind="design-only",
+                    url=url,
+                    source=design_sources.get(url, ""),
+                    closest_match=_find_closest(url, normalized_impl_urls),
+                )
+            )
+
+    for url in normalized_impl_urls:
+        if url not in design_set:
+            drift.append(
+                DriftEntry(
+                    kind="impl-only",
+                    url=url,
+                    source="implementation",
+                    closest_match=_find_closest(url, normalized_design_urls),
+                )
+            )
+
+    return DriftResult(
+        design_urls=normalized_design_urls,
+        impl_urls=normalized_impl_urls,
+        drift=drift,
+        exit_code=1 if drift else 0,
+    )
+
+
+def _find_closest(url: str, candidates: list[str]) -> str:
+    """Find closest URL from candidates using common-prefix heuristic."""
+    if not candidates:
+        return ""
+
+    def score(candidate: str) -> int:
+        prefix = 0
+        for left, right in zip(url, candidate):
+            if left != right:
+                break
+            prefix += 1
+        return prefix
+
+    return max(candidates, key=score)
+
+
+def run_drift(project_root: Path, codd_dir: Path) -> DriftResult:
+    """Full drift run: read codd.yaml, extract URLs, and compute drift."""
+    import yaml
+
+    config_path = codd_dir / "codd.yaml"
+    config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+
+    impl_urls = _extract_impl_urls(project_root, config)
+    design_urls, design_sources = _extract_design_urls(project_root, config)
+
+    return compute_drift(design_urls, impl_urls, design_sources)
+
+
+def _extract_impl_urls(project_root: Path, config: dict[str, Any]) -> list[str]:
+    fs_route_configs = config.get("filesystem_routes", [])
+    if not fs_route_configs:
+        return []
+
+    try:
+        from codd.parsing import FileSystemRouteExtractor
+    except ImportError:
+        return []
+
+    extractor = FileSystemRouteExtractor()
+    route_info = extractor.extract_routes(project_root, fs_route_configs)
+    return [_route_url(route) for route in getattr(route_info, "routes", []) if _route_url(route)]
+
+
+def _extract_design_urls(project_root: Path, config: dict[str, Any]) -> tuple[list[str], dict[str, str]]:
+    doc_link_config = config.get("document_url_linking", {})
+    if not doc_link_config.get("enabled", False):
+        return [], {}
+
+    try:
+        from codd.extractor import DocumentUrlLinker
+    except ImportError:
+        return [], {}
+
+    linker = DocumentUrlLinker(doc_link_config)
+    design_urls: list[str] = []
+    design_sources: dict[str, str] = {}
+    doc_dirs = config.get("scan", {}).get("doc_dirs", [])
+
+    for doc_dir in doc_dirs:
+        full_dir = project_root / doc_dir
+        if not full_dir.exists():
+            continue
+        for md_file in full_dir.rglob("*.md"):
+            text = md_file.read_text(encoding="utf-8", errors="ignore")
+            rel_path = md_file.relative_to(project_root).as_posix()
+            result = linker.extract_urls(text, rel_path)
+            for url in getattr(result, "urls", []):
+                design_urls.append(url)
+                design_sources.setdefault(url, getattr(result, "node_id", rel_path))
+
+    return design_urls, design_sources
+
+
+def _unique_urls(urls: Sequence[str]) -> list[str]:
+    seen: set[str] = set()
+    unique: list[str] = []
+    for url in urls:
+        if url in seen:
+            continue
+        seen.add(url)
+        unique.append(url)
+    return unique
+
+
+def _route_url(route: Any) -> str:
+    if isinstance(route, dict):
+        return str(route.get("url", ""))
+    return str(getattr(route, "url", ""))

{codd_dev-1.9.2 → codd_dev-1.11.0}/codd/extractor.py

@@ -1018,3 +1018,44 @@ def run_extract(project_root: Path, language: str | None = None,
 def _match_glob(path: str, pattern: str) -> bool:
     import fnmatch
     return fnmatch.fnmatch(path, pattern)
+
+
+@dataclass
+class DocumentUrlLinkInfo:
+    """URLs extracted from a document node."""
+    node_id: str
+    urls: list[str]
+
+
+class DocumentUrlLinker:
+    """Scan design/requirement document text for URL patterns.
+
+    Extracts URL strings referenced in documents (Mermaid diagrams, prose,
+    code blocks) and returns them for downstream drift analysis.
+    FW-agnostic: pattern driven by codd.yaml document_url_linking config.
+    """
+
+    DEFAULT_URL_PATTERN = r"(?:^|[\s`(\[])(/(?:[a-z0-9][a-z0-9/\-:_\[\]]*)?)"
+    DEFAULT_EDGE_TYPE = "references"
+
+    def __init__(self, config: dict | None = None):
+        cfg = config or {}
+        self._pattern = re.compile(
+            cfg.get("url_pattern", self.DEFAULT_URL_PATTERN),
+            re.MULTILINE,
+        )
+        self.edge_type = cfg.get("edge_type", self.DEFAULT_EDGE_TYPE)
+
+    def extract_urls(self, text: str, node_id: str = "") -> DocumentUrlLinkInfo:
+        """Extract and normalize URLs from document text."""
+        raw = self._pattern.findall(text)
+        normalized = sorted(set(self._normalize_url(url) for url in raw if url))
+        return DocumentUrlLinkInfo(node_id=node_id, urls=normalized)
+
+    def _normalize_url(self, url: str) -> str:
+        url = url.strip()
+        while url.endswith("]") and url.count("]") > url.count("["):
+            url = url[:-1]
+        if url != "/" and url.endswith("/"):
+            url = url.rstrip("/")
+        return url