hinge 0.1.0__py3-none-any.whl

hinge/dbt/models/networks/star_user_repo.sql

@@ -0,0 +1,27 @@
+{{ config(materialized='table') }}
+
+{{ assert_recipe_supported('star_user_repo') }}
+
+WITH starred_edges AS (
+    {{ slice_edges(
+        edge_types=['starred'],
+        source_types=['user'],
+        target_types=['repo']
+    ) }}
+)
+
+{{ network_edges(
+    relation='starred_edges',
+    recipe_name='star_user_repo',
+    source_node_id='source_node_id',
+    source_node_type="'user'",
+    target_node_id='target_node_id',
+    target_node_type="'repo'",
+    edge_type="'starred'",
+    directed='true',
+    weight='coalesce(weight, 1.0)',
+    weight_kind="'binary'",
+    first_seen_at='occurred_at',
+    last_seen_at='occurred_at',
+    properties="to_json({'source_record_id': source_record_id})"
+) }}

hinge/dbt/models/networks/user_mention_user.sql

@@ -0,0 +1,60 @@
+{{ config(materialized='table') }}
+
+{{ assert_recipe_supported('user_mention_user') }}
+
+WITH authored_comments AS (
+    SELECT
+        source_node_id AS author_node_id,
+        target_node_id AS comment_node_id,
+        min(occurred_at) AS first_seen_at,
+        max(occurred_at) AS last_seen_at
+    FROM {{ ref('hin_edges') }}
+    WHERE source_node_type = 'user'
+      AND target_node_type = 'artifact'
+      AND target_node_subtype IN ('comment', 'issue_comment', 'review_comment', 'commit_comment')
+      AND edge_type IN ('authored', 'commented_on', 'review_commented_on')
+    GROUP BY source_node_id, target_node_id
+),
+
+comment_mentions AS (
+    SELECT
+        source_node_id AS comment_node_id,
+        target_node_id AS mentioned_user_node_id,
+        min(occurred_at) AS first_seen_at,
+        max(occurred_at) AS last_seen_at
+    FROM {{ ref('hin_edges') }}
+    WHERE source_node_type = 'artifact'
+      AND source_node_subtype IN ('comment', 'issue_comment', 'review_comment', 'commit_comment')
+      AND target_node_type = 'user'
+      AND edge_type = 'mentions'
+    GROUP BY source_node_id, target_node_id
+),
+
+collapsed AS (
+    {{ collapse_two_hop_path(
+        first_relation='authored_comments',
+        second_relation='comment_mentions',
+        source_col='author_node_id',
+        mediator_col='comment_node_id',
+        second_source_col='comment_node_id',
+        target_col='mentioned_user_node_id',
+        directed=true
+    ) }}
+)
+
+{{ network_edges(
+    relation='collapsed',
+    recipe_name='user_mention_user',
+    source_node_id='source_node_id',
+    source_node_type="'user'",
+    target_node_id='target_node_id',
+    target_node_type="'user'",
+    edge_type="'mentions_user'",
+    directed='true',
+    weight='n_contexts',
+    weight_kind="'count'",
+    n_contexts='n_contexts',
+    first_seen_at='first_seen_at',
+    last_seen_at='last_seen_at',
+    properties="to_json({'comments': context_node_ids})"
+) }}

hinge/dbt/models/networks/watch_user_repo.sql

@@ -0,0 +1,27 @@
+{{ config(materialized='table') }}
+
+{{ assert_recipe_supported('watch_user_repo') }}
+
+WITH watch_edges AS (
+    {{ slice_edges(
+        edge_types=['watches'],
+        source_types=['user'],
+        target_types=['repo']
+    ) }}
+)
+
+{{ network_edges(
+    relation='watch_edges',
+    recipe_name='watch_user_repo',
+    source_node_id='source_node_id',
+    source_node_type="'user'",
+    target_node_id='target_node_id',
+    target_node_type="'repo'",
+    edge_type="'watches'",
+    directed='true',
+    weight='coalesce(weight, 1.0)',
+    weight_kind="'binary'",
+    first_seen_at='occurred_at',
+    last_seen_at='occurred_at',
+    properties="to_json({'source_record_id': source_record_id})"
+) }}

hinge/dbt/models/sources/sources.yml

@@ -0,0 +1,63 @@
+# dbt source declaration.
+#
+# DbtProjection creates dataset-scoped views before every dbt run.
+#
+# Core HIN projections should reference:
+#   {{ source('hin', 'active_hin_nodes') }}
+#   {{ source('hin', 'active_hin_edges') }}
+#
+# The legacy active_nodes / active_edges sources remain for old projections only.
+# Never reference base tables directly — they contain all datasets.
+version: 2
+
+sources:
+  - name: hin
+    schema: main
+    tables:
+      - name: active_nodes
+        description: "View over nodes filtered to the active dataset_id."
+        columns:
+          - name: type
+            description: "NodeType — 'user', 'repo', 'artifact'."
+          - name: id
+          - name: ts
+          - name: attrs
+      - name: active_edges
+        description: "View over edges filtered to the active dataset_id."
+        columns:
+          - name: type
+            description: "EdgeType — 'opened', 'reviewed', etc."
+          - name: src_id
+          - name: dst_id
+          - name: ts
+          - name: attrs
+      - name: active_contract_accounts
+        description: "Adapter contract accounts for the active dataset_id."
+      - name: active_contract_repositories
+        description: "Adapter contract repositories for the active dataset_id."
+      - name: active_contract_artifacts
+        description: "Adapter contract artifacts for the active dataset_id."
+      - name: active_contract_relations
+        description: "Adapter contract relations for the active dataset_id."
+      - name: active_contract_adapter_manifest
+        description: "Adapter manifest/capabilities for the active dataset_id."
+      - name: active_hin_nodes
+        description: "Canonical HIN node view from HIN_DBT_DESIGN.md, filtered to the active dataset_id."
+        columns:
+          - name: node_id
+          - name: node_type
+          - name: node_subtype
+          - name: natural_key
+          - name: display_name
+          - name: properties
+      - name: active_hin_edges
+        description: "Canonical HIN edge view from HIN_DBT_DESIGN.md, filtered to the active dataset_id."
+        columns:
+          - name: edge_id
+          - name: source_node_id
+          - name: source_node_type
+          - name: target_node_id
+          - name: target_node_type
+          - name: edge_type
+          - name: relation_subtype
+          - name: properties

hinge/dbt/models/staging/stg_accounts.sql

@@ -0,0 +1,4 @@
+{{ config(materialized='view') }}
+
+SELECT *
+FROM {{ source('hin', 'active_contract_accounts') }}

hinge/dbt/models/staging/stg_adapter_manifest.sql

@@ -0,0 +1,4 @@
+{{ config(materialized='view') }}
+
+SELECT *
+FROM {{ source('hin', 'active_contract_adapter_manifest') }}

hinge/dbt/models/staging/stg_artifacts.sql

@@ -0,0 +1,4 @@
+{{ config(materialized='view') }}
+
+SELECT *
+FROM {{ source('hin', 'active_contract_artifacts') }}

hinge/dbt/models/staging/stg_relations.sql

@@ -0,0 +1,4 @@
+{{ config(materialized='view') }}
+
+SELECT *
+FROM {{ source('hin', 'active_contract_relations') }}

hinge/dbt/models/staging/stg_repositories.sql

@@ -0,0 +1,4 @@
+{{ config(materialized='view') }}
+
+SELECT *
+FROM {{ source('hin', 'active_contract_repositories') }}

hinge/dbt/profiles.yml

@@ -0,0 +1,9 @@
+# The DuckDB path is injected by DbtProjection at run time via the
+# HINGE_STORE_PATH env var — do NOT hard-code a path here.
+hinge:
+  target: dev
+  outputs:
+    dev:
+      type: duckdb
+      path: "{{ env_var('HINGE_STORE_PATH') }}"
+      threads: 4

hinge/dbt/seeds/ref_recipe_requirements.csv

@@ -0,0 +1,35 @@
+recipe_name,required_capability
+artifact_reference,has_artifact_refs
+co_commit_user_user,has_commits
+co_edit_file_user_user,has_commits
+co_edit_file_user_user,has_file_touches
+co_edit_line_user_user,has_commits
+co_edit_line_user_user,has_line_touches
+dev_interaction,has_pull_requests
+dev_interaction,has_pr_reviews
+dev_interaction,has_issues
+dev_interaction,has_comments
+developer_repo_affiliation,has_pull_requests
+developer_repo_affiliation,has_pr_reviews
+developer_repo_affiliation,has_issues
+developer_repo_affiliation,has_comments
+follow_user_user,has_follows
+fork_repo_repo,has_forks
+issue_co_participation,has_issues
+issue_co_participation,has_comments
+issue_participation,has_issues
+issue_participation,has_comments
+pr_author_reviewer,has_pull_requests
+pr_author_reviewer,has_pr_reviews
+pr_participation,has_pull_requests
+pr_participation,has_pr_reviews
+pr_reviewer_coreview,has_pull_requests
+pr_reviewer_coreview,has_pr_reviews
+repo_shared_contributors,has_pull_requests
+repo_shared_contributors,has_pr_reviews
+repo_shared_contributors,has_issues
+repo_shared_contributors,has_comments
+star_user_repo,has_stars
+user_mention_user,has_mentions
+user_mention_user,has_comments
+watch_user_repo,has_watches

hinge/frontends/cli/__init__.py

@@ -0,0 +1,3 @@
+from hinge.frontends.cli.app import app
+
+__all__ = ["app"]

hinge/frontends/cli/app.py

@@ -0,0 +1,189 @@
+"""Typer-based CLI entry point.
+
+Usage:
+
+    hinge ingest path/to/events.jsonl --reader numfocus
+    hinge export --dataset <id> --projection dev-interaction --format gml -o out.gml
+    hinge list datasets
+    hinge list projections
+    hinge list readers
+    hinge list exporters
+"""
+
+from __future__ import annotations
+
+import subprocess
+from contextlib import suppress
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from hinge.config.logging_setup import setup_logging
+from hinge.frontends import lib
+
+setup_logging()
+
+app = typer.Typer(help="hinge — Heterogeneous Information Network tool", no_args_is_help=True)
+list_app = typer.Typer(help="List available resources", no_args_is_help=True)
+app.add_typer(list_app, name="list")
+
+console = Console()
+
+
+@app.command()
+def ingest(
+    path: Path = typer.Argument(..., exists=True, readable=True, help="Dataset file."),
+    reader: str = typer.Option(..., "--reader", "-r", help="Reader name (e.g. numfocus)."),
+) -> None:
+    """Read a dataset file, extract typed nodes/edges, persist to the DuckDB store."""
+    report = lib.ingest(path, reader=reader)
+    console.print(
+        f"[green]ingested[/green] {report.elements_read:,} elements "
+        f"→ {report.nodes_upserted:,} nodes, {report.edges_upserted:,} edges "
+        f"({report.violation_count} violations)\n"
+        f"[bold]Dataset ID:[/bold] {report.dataset_id}"
+    )
+
+
+@app.command()
+def export(
+    dataset: str = typer.Option(..., "--dataset", "-d", help="Dataset ID from a previous ingest."),
+    projection: str = typer.Option(..., "--projection", "-p", help="Projection name."),
+    format_: str = typer.Option(..., "--format", "-f", help="Exporter name (e.g. gml)."),
+    output: Path = typer.Option(..., "--output", "-o", help="Output file."),
+) -> None:
+    """Run a projection over a specific dataset and export the result."""
+    output.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with output.open("wb") as sink:
+            receipt = lib.export(
+                projection_name=projection, dataset_id=dataset, fmt=format_, sink=sink
+            )
+    except subprocess.CalledProcessError as exc:
+        _remove_empty_output(output)
+        _print_process_error(exc)
+        raise typer.Exit(code=1) from None
+    console.print(
+        f"[green]exported[/green] {receipt.node_count:,} nodes, "
+        f"{receipt.edge_count:,} edges → {output} "
+        f"(snapshot {receipt.snapshot_id[:12] if receipt.snapshot_id else '—'})"
+    )
+
+
+@app.command("export-sql")
+def export_sql(
+    sql: Path = typer.Argument(..., exists=True, readable=True, help="Custom dbt model SQL file."),
+    dataset: str = typer.Option(..., "--dataset", "-d", help="Dataset ID from a previous ingest."),
+    format_: str = typer.Option(..., "--format", "-f", help="Exporter name (e.g. gml)."),
+    output: Path = typer.Option(..., "--output", "-o", help="Output file."),
+    name: str | None = typer.Option(None, "--name", help="dbt model name; defaults to SQL stem."),
+) -> None:
+    """Run a local SQL projection that can use the built-in dbt HIN macros."""
+    output.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with output.open("wb") as sink:
+            receipt = lib.export_sql_projection(
+                sql_path=sql, dataset_id=dataset, fmt=format_, sink=sink, name=name
+            )
+    except subprocess.CalledProcessError as exc:
+        _remove_empty_output(output)
+        _print_process_error(exc)
+        raise typer.Exit(code=1) from None
+    console.print(
+        f"[green]exported[/green] {receipt.node_count:,} nodes, "
+        f"{receipt.edge_count:,} edges → {output} "
+        f"(snapshot {receipt.snapshot_id[:12] if receipt.snapshot_id else '—'})"
+    )
+
+
+def _print_process_error(exc: subprocess.CalledProcessError) -> None:
+    console.print(f"[red]error:[/red] {_process_error_message(exc)}")
+
+
+def _process_error_message(exc: subprocess.CalledProcessError) -> str:
+    text = f"{_process_text(exc.output)}\n{_process_text(exc.stderr)}"
+    capability_failure = _extract_capability_failure(text)
+    if capability_failure:
+        return capability_failure
+    return f"dbt failed with exit code {exc.returncode}. Set HINGE_LOG_LEVEL=DEBUG for details."
+
+
+def _process_text(value: object) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bytes):
+        return value.decode(errors="replace")
+    if isinstance(value, str):
+        return value
+    return str(value)
+
+
+def _extract_capability_failure(text: str) -> str | None:
+    for line in text.splitlines():
+        if "Cannot build `" not in line or "Missing capabilities:" not in line:
+            continue
+        message = line.strip()
+        prefix_index = message.find("Cannot build `")
+        if prefix_index >= 0:
+            message = message[prefix_index:]
+        return message.replace(". Missing capabilities:", ".\nMissing capabilities:")
+    return None
+
+
+def _remove_empty_output(path: Path) -> None:
+    with suppress(OSError):
+        if path.exists() and path.stat().st_size == 0:
+            path.unlink()
+
+
+@list_app.command("datasets")
+def list_datasets() -> None:
+    """Show all ingested datasets stored in the DuckDB file."""
+    datasets = lib.list_datasets()
+    if not datasets:
+        console.print("[yellow]No datasets ingested yet.[/yellow]")
+        return
+    table = Table("dataset_id", "reader", "path", "ingested_at", "nodes", "edges")
+    for d in datasets:
+        table.add_row(
+            d.dataset_id,
+            d.reader,
+            d.path,
+            d.ingested_at.strftime("%Y-%m-%d %H:%M:%S"),
+            str(d.node_count) if d.node_count is not None else "—",
+            str(d.edge_count) if d.edge_count is not None else "—",
+        )
+    console.print(table)
+
+
+@list_app.command("projections")
+def list_projections() -> None:
+    """List all registered projection names (pass to --projection on export)."""
+    table = Table("name")
+    for name in lib.list_projections():
+        table.add_row(name)
+    console.print(table)
+
+
+@list_app.command("exporters")
+def list_exporters() -> None:
+    """List all registered exporter names (pass to --format on export)."""
+    table = Table("name")
+    for name in lib.list_exporters():
+        table.add_row(name)
+    console.print(table)
+
+
+@list_app.command("readers")
+def list_readers() -> None:
+    """List all registered reader names (pass to --reader on ingest)."""
+    table = Table("name")
+    for name in lib.list_readers():
+        table.add_row(name)
+    console.print(table)
+
+
+if __name__ == "__main__":
+    app()

hinge/frontends/lib.py

@@ -0,0 +1,148 @@
+"""Public library facade.
+
+``import hinge`` and you get these functions. Each one assembles the pipeline
+through the registry and hands it to the runner — frontends do not import
+concrete stage classes.
+
+The three-phase export dance (scope → dbt → fingerprint) is explicit here so
+the DuckDB single-writer lock is released between phases. The store is a
+context manager; the surrounding ``with`` blocks make ownership obvious.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, BinaryIO, cast
+
+from hinge.config.settings import types_yaml_path
+from hinge.kernel import registry, runner
+from hinge.kernel.projection.projection_spec import ProjectionSpec
+from hinge.kernel.protocols.store_stage import DatasetMeta
+from hinge.kernel.runner import IngestReport
+from hinge.kernel.schema.hin_schema import HINSchema
+
+
+def ingest(path: str | Path, reader: str) -> IngestReport:
+    rdr = registry.get_reader(reader, path=path)
+    schema = HINSchema.from_yaml(types_yaml_path())
+    with registry.get_store() as store:
+        return runner.run_ingest(rdr, store, schema)
+
+
+def export(
+    projection_name: str,
+    dataset_id: str,
+    fmt: str,
+    sink: BinaryIO,
+    **params: Any,
+) -> Any:
+    schema = HINSchema.from_yaml(types_yaml_path())
+    proj_stage = registry.get_projection("dbt")
+    spec = registry.get_projection_spec(projection_name)
+    exporter = registry.get_exporter(fmt)
+
+    # Phase 1: writable store creates dataset-scoped views, then releases the
+    # file lock so the dbt subprocess can acquire it.
+    with registry.get_store() as store:
+        view = store.scope_to_dataset(dataset_id)
+
+    # Phase 2: dbt subprocess materialises the projection.
+    handle = runner.run_projection(proj_stage, spec, view, params)
+
+    # Phase 3: read-only store for fingerprinting.
+    with registry.get_store(read_only=True) as store:
+        return runner.run_export(
+            handle,
+            exporter,
+            sink,
+            store=store,
+            projection=proj_stage,
+            schema=schema,
+            dataset_id=dataset_id,
+        )
+
+
+def export_sql_projection(
+    sql_path: str | Path,
+    dataset_id: str,
+    fmt: str,
+    sink: BinaryIO,
+    *,
+    name: str | None = None,
+    **params: Any,
+) -> Any:
+    sql_path = Path(sql_path)
+    model_name = name or sql_path.stem
+    schema = HINSchema.from_yaml(types_yaml_path())
+    proj_stage = registry.get_projection(
+        "dbt", custom_model_path=sql_path, custom_model_name=model_name
+    )
+    spec = ProjectionSpec(
+        name=model_name,
+        description=f"Custom SQL projection from {sql_path}",
+        model_name=model_name,
+        output_node_types=[],
+        output_edge_types=[],
+    )
+    exporter = registry.get_exporter(fmt)
+
+    with registry.get_store() as store:
+        view = store.scope_to_dataset(dataset_id)
+
+    handle = runner.run_projection(proj_stage, spec, view, params)
+
+    with registry.get_store(read_only=True) as store:
+        return runner.run_export(
+            handle,
+            exporter,
+            sink,
+            store=store,
+            projection=proj_stage,
+            schema=schema,
+            dataset_id=dataset_id,
+        )
+
+
+def project(name: str, dataset_id: str, **params: Any) -> Any:
+    proj_stage = registry.get_projection("dbt")
+    spec = registry.get_projection_spec(name)
+    with registry.get_store() as store:
+        view = store.scope_to_dataset(dataset_id)
+    return runner.run_projection(proj_stage, spec, view, params)
+
+
+def project_sql(
+    sql_path: str | Path, dataset_id: str, *, name: str | None = None, **params: Any
+) -> Any:
+    sql_path = Path(sql_path)
+    model_name = name or sql_path.stem
+    proj_stage = registry.get_projection(
+        "dbt", custom_model_path=sql_path, custom_model_name=model_name
+    )
+    spec = ProjectionSpec(
+        name=model_name,
+        description=f"Custom SQL projection from {sql_path}",
+        model_name=model_name,
+        output_node_types=[],
+        output_edge_types=[],
+    )
+    with registry.get_store() as store:
+        view = store.scope_to_dataset(dataset_id)
+    return runner.run_projection(proj_stage, spec, view, params)
+
+
+def list_datasets() -> list[DatasetMeta]:
+    with registry.get_store(read_only=True) as store:
+        return cast(list[DatasetMeta], store.list_datasets())
+
+
+def list_projections() -> list[str]:
+    return registry.list_registered("projection_spec")
+
+
+def list_exporters() -> list[str]:
+    return registry.list_registered("exporter")
+
+
+def list_readers() -> list[str]:
+    return registry.list_registered("reader")

hinge/frontends/tui/__init__.py

@@ -0,0 +1,7 @@
+"""Textual TUI — stub.
+
+Plan: a single-screen app that lists registered sources, projections and
+exporters; lets the user pick one of each; runs the pipeline; streams progress.
+The frontend must compose stages via registry + runner only — no direct
+imports from hinge.stages.
+"""

hinge/frontends/web/__init__.py

@@ -0,0 +1,6 @@
+"""FastAPI web frontend — stub.
+
+Plan: REST endpoints POST /ingest, POST /export, GET /projections, with an
+SSE channel for progress events. Same composition rule as the CLI:
+registry + runner only.
+"""

hinge/kernel/projection/__init__.py

@@ -0,0 +1,9 @@
+from hinge.kernel.projection.projected_graph import ProjectedGraph, ProjectedGraphHandle
+from hinge.kernel.projection.projection_spec import ProjectionParams, ProjectionSpec
+
+__all__ = [
+    "ProjectedGraph",
+    "ProjectedGraphHandle",
+    "ProjectionParams",
+    "ProjectionSpec",
+]

hinge/kernel/projection/projected_graph.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Protocol
+
+from hinge.kernel.schema.typed_edge import TypedEdge
+from hinge.kernel.schema.typed_node import TypedNode
+
+
+class ProjectedGraphHandle(Protocol):
+    """Lazy cursor over a materialised projection.
+
+    Implementations stream rows from the result table — exporters must not
+    assume the full graph fits in memory.
+    """
+
+    def iter_nodes(self) -> Iterator[TypedNode]: ...
+    def iter_edges(self) -> Iterator[TypedEdge]: ...
+
+
+class ProjectedGraph:
+    """Concrete, in-memory ProjectedGraphHandle. Useful for tests."""
+
+    def __init__(self, nodes: list[TypedNode], edges: list[TypedEdge]) -> None:
+        self._nodes = nodes
+        self._edges = edges
+
+    def iter_nodes(self) -> Iterator[TypedNode]:
+        return iter(self._nodes)
+
+    def iter_edges(self) -> Iterator[TypedEdge]:
+        return iter(self._edges)