graphcheck 0.1.0__tar.gz

graphcheck-0.1.0/.gitattributes

@@ -0,0 +1 @@
+*.sh text eol=lf

graphcheck-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+*                             @ezhilvendhan
+/docs/specs/                  @ghilda-graphora @kev-graphora
+/src/graphcheck/contracts/    @ghilda-graphora @kev-graphora
+/tests/contracts/             @ghilda-graphora @kev-graphora
+/tests/fixtures/              @jayachandra-bit @jananik-graphora

graphcheck-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Something isn't working as expected
+labels: [bug]
+---
+
+**Describe the bug**
+
+
+**Steps to reproduce**
+
+1.
+2.
+3.
+
+**Expected behavior**
+
+
+**Actual behavior**
+
+
+**Environment**
+
+- GraphCheck version:
+- Python version:
+- OS:
+
+## Decision rights
+
+Owner decides libraries within the component; the named reviewer approves. Cross-contract changes escalate to Ezhil (§13).

graphcheck-0.1.0/.github/ISSUE_TEMPLATE/deliverable.md

@@ -0,0 +1,15 @@
+---
+name: Week deliverable
+about: A scoped deliverable with acceptance criteria
+labels: []
+---
+
+**Owner:**
+**Milestone:**
+
+## Acceptance criteria
+
+
+## Decision rights
+
+Owner decides libraries within the component; the named reviewer approves. Cross-contract changes escalate to Ezhil (§13).

graphcheck-0.1.0/.github/ISSUE_TEMPLATE/docs.md

@@ -0,0 +1,19 @@
+---
+name: Docs
+about: Missing, unclear, or incorrect documentation
+labels: [documentation]
+---
+
+**Where**
+
+(file/page/section)
+
+**What's wrong or missing**
+
+
+**Suggested fix**
+
+
+## Decision rights
+
+Owner decides libraries within the component; the named reviewer approves. Cross-contract changes escalate to Ezhil (§13).

graphcheck-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Propose a new capability or enhancement
+labels: [enhancement]
+---
+
+**What problem does this solve?**
+
+
+**Proposed solution**
+
+
+**Alternatives considered**
+
+
+## Decision rights
+
+Owner decides libraries within the component; the named reviewer approves. Cross-contract changes escalate to Ezhil (§13).

graphcheck-0.1.0/.github/actions/graphcheck-action/README.md

@@ -0,0 +1,94 @@
+# GraphCheck Action
+
+Run GraphCheck checks against your graph on every pull request, and get
+a pass/fail summary posted straight to the PR's checks tab.
+
+This is a thin wrapper around the GraphCheck CLI (graphcheck run) - it
+adds no new checking behaviour of its own.
+
+Not yet published to the GitHub Marketplace. Use the in-repo path shown
+below; switch to graphora/graphcheck-action@v1 once it is extracted and
+tagged.
+
+## Usage
+
+### Within this repository
+
+    - uses: ./.github/actions/graphcheck-action
+      with:
+        profile: ci
+        uri: bolt://localhost:7687
+        user: neo4j
+        database: neo4j
+        fail-fast: false
+        version: 0.1.0
+      env:
+        NEO4J_PASSWORD: ${{ secrets.NEO4J_PASSWORD }}
+
+### From another repository
+
+Not yet extracted to its own repo, so pin to a commit SHA on this one:
+
+    - uses: graphora/graphcheck/.github/actions/graphcheck-action@COMMIT_SHA
+      with:
+        profile: ci
+        uri: bolt://localhost:7687
+        user: neo4j
+        database: neo4j
+        fail-fast: false
+        version: 0.1.0
+      env:
+        NEO4J_PASSWORD: ${{ secrets.NEO4J_PASSWORD }}
+
+Switch to `graphora/graphcheck-action@v1` once this Action is extracted and tagged.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|---|---|---|---|
+| profile | no | ci | Profile name to generate and use, if profiles.yml does not already exist |
+| uri | yes | - | Neo4j Bolt URI |
+| user | yes | - | Neo4j username |
+| database | no | neo4j | Neo4j database name |
+| fail-fast | no | false | Stop after the first error-severity failure |
+| suite | no | - | Suite name to run via --suite; skipped if empty |
+| version | no | 0.1.0 | Exact GraphCheck version to install from PyPI |
+
+## What it does
+
+1. Installs the pinned GraphCheck version from PyPI.
+2. Resolves the artifacts directory from graphcheck.yml (defaults to
+   .graphcheck if not configured or the file is absent).
+3. If profiles.yml does not already exist, generates one using the
+   uri/user/database inputs. Only password_env: NEO4J_PASSWORD is
+   written - the real password is never in the generated file.
+4. Runs graphcheck run using the given profile. The Neo4j password is
+   read from the NEO4J_PASSWORD environment variable at runtime - set
+   it via a repo secret, never a plaintext input.
+5. Removes the generated profiles.yml (only if this Action created it).
+6. Captures the run's exit code. The job's final status matches this
+   exit code exactly (0 green; 1/2/3 red) - this is preserved even
+   though later steps always run.
+7. Uploads results.json and the HTML report as build artifacts, from
+   the resolved artifacts directory, whenever they were produced. If
+   an early failure produced none, the summary says so explicitly.
+8. Writes a pass/fail/errored/warn breakdown, read directly from
+   results.json (not inferred from the exit code), to the GitHub
+   Step Summary, including one evidence line per failing check.
+
+## Exit codes
+
+| Exit | Meaning |
+|---|---|
+| 0 | Run completed, all checks passed or were skipped |
+| 1 | A check failed, or an error-severity check errored |
+| 2 | Incomplete coverage, or a warning |
+| 3 | The run could not execute (bad config, no connection, setup failure) |
+
+## Notes
+
+- This Action requires a graph reachable from the CI runner. Spinning
+  up a disposable Neo4j service for self-contained demo runs is not
+  yet supported.
+- Not yet released: graphcheck itself is not published to PyPI, so the
+  install step will fail until [Release] ships it.

graphcheck-0.1.0/.github/actions/graphcheck-action/action.yml

@@ -0,0 +1,127 @@
+name: 'GraphCheck'
+description: 'Run GraphCheck checks against your graph and report results in the PR.'
+
+inputs:
+  profile:
+    description: 'Profile name to generate and use, if profiles.yml does not already exist'
+    required: false
+    default: 'ci'
+  uri:
+    description: 'Neo4j Bolt URI (e.g. bolt://localhost:7687)'
+    required: true
+  user:
+    description: 'Neo4j username'
+    required: true
+  database:
+    description: 'Neo4j database name'
+    required: false
+    default: 'neo4j'
+  fail-fast:
+    description: 'Stop on the first failing check'
+    required: false
+    default: 'false'
+  suite:
+    description: 'Run only this suite id (optional; runs all suites if not set)'
+    required: false
+    default: ''
+  version:
+    description: 'Exact GraphCheck version to install (e.g. 0.1.0)'
+    required: false
+    default: '0.1.0'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python
+      if: inputs.version != ''
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install GraphCheck
+      shell: bash
+      env:
+        GC_VERSION: ${{ inputs.version }}
+      run: |
+        if [ -z "$GC_VERSION" ]; then
+          echo "version empty — using pre-installed graphcheck"
+        else
+          pip install "graphcheck==$GC_VERSION"
+        fi
+
+    - name: Resolve artifacts directory
+      shell: bash
+      run: |
+        if [ -f graphcheck.yml ]; then
+          dir=$(python -c "import yaml,sys; d=yaml.safe_load(open('graphcheck.yml')); print(d.get('artifacts','.graphcheck'))" 2>/dev/null || echo ".graphcheck")
+        else
+          dir=".graphcheck"
+        fi
+        if [[ "$dir" == *$'\n'* || "$dir" == *$'\r'* ]]; then
+          echo "::error::artifacts directory value from graphcheck.yml contains a line break; refusing to export it"
+          exit 1
+        fi
+        echo "GRAPHCHECK_ARTIFACTS_DIR=$dir" >> "$GITHUB_ENV"
+
+    - name: Generate profiles.yml
+      id: generate_profile
+      shell: bash
+      env:
+        GC_PROFILE: ${{ inputs.profile }}
+        GC_URI: ${{ inputs.uri }}
+        GC_USER: ${{ inputs.user }}
+        GC_DATABASE: ${{ inputs.database }}
+      run: python "${{ github.action_path }}/generate_profile.py"
+
+    - name: Run GraphCheck
+      shell: bash
+      id: graphcheck_run
+      env:
+        GC_PROFILE: ${{ inputs.profile }}
+        GC_FAIL_FAST: ${{ inputs.fail-fast }}
+        GC_SUITE: ${{ inputs.suite }}
+      run: |
+        set +e
+        args=(--profile "$GC_PROFILE")
+        [ -n "$GC_SUITE" ] && args+=(--suite "$GC_SUITE")
+        [ "$GC_FAIL_FAST" = "true" ] && args+=(--fail-fast)
+        graphcheck run "${args[@]}"
+        code=$?
+        echo "exit_code=$code" >> "$GITHUB_OUTPUT"
+        exit 0
+
+    - name: Clean up generated profiles.yml
+      if: always()
+      continue-on-error: true
+      shell: bash
+      env:
+        GENERATED_PROFILES: ${{ steps.generate_profile.outputs.generated_profiles }}
+      run: |
+        if [ "$GENERATED_PROFILES" = "true" ]; then
+          rm -f profiles.yml
+          echo "Removed generated profiles.yml"
+        fi
+
+    - name: Upload results
+      if: always()
+      continue-on-error: true
+      uses: actions/upload-artifact@v4
+      with:
+        name: graphcheck-results
+        path: |
+          ${{ env.GRAPHCHECK_ARTIFACTS_DIR }}/runs/latest/results.json
+          ${{ env.GRAPHCHECK_ARTIFACTS_DIR }}/runs/latest/report.html
+        if-no-files-found: ignore
+
+    - name: Write summary
+      if: always()
+      continue-on-error: true
+      shell: bash
+      run: python "${{ github.action_path }}/write_summary.py"
+      env:
+        GRAPHCHECK_ARTIFACTS_DIR: ${{ env.GRAPHCHECK_ARTIFACTS_DIR }}
+
+    - name: Set final job status
+      if: always()
+      shell: bash
+      run: exit ${{ steps.graphcheck_run.outputs.exit_code || 3 }}

graphcheck-0.1.0/.github/actions/graphcheck-action/generate_profile.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Safely generates a minimal profiles.yml for CI use, via yaml.safe_dump
+rather than hand-built shell text. Only writes if profiles.yml does not
+already exist; the real password is never written, only the name of the
+environment variable to read it from.
+"""
+
+import os
+import sys
+
+try:
+    import yaml
+except ImportError:
+    print("PyYAML is required to generate profiles.yml", file=sys.stderr)
+    sys.exit(1)
+
+
+def main():
+    if os.path.exists("profiles.yml"):
+        print("profiles.yml already exists, using it as-is.")
+        return
+
+    profile = os.environ["GC_PROFILE"]
+    uri = os.environ["GC_URI"]
+    user = os.environ["GC_USER"]
+    database = os.environ["GC_DATABASE"]
+
+    data = {
+        "default": profile,
+        "profiles": {
+            profile: {
+                "uri": uri,
+                "user": user,
+                "password": None,
+                "password_env": "NEO4J_PASSWORD",
+                "database": database,
+            }
+        },
+    }
+
+    with open("profiles.yml", "w", encoding="utf-8") as f:
+        yaml.safe_dump(data, f, default_flow_style=False, sort_keys=False)
+
+    github_output = os.environ.get("GITHUB_OUTPUT")
+    if github_output:
+        with open(github_output, "a", encoding="utf-8") as f:
+            f.write("generated_profiles=true\n")
+
+    print("Generated profiles.yml")
+
+
+if __name__ == "__main__":
+    main()

graphcheck-0.1.0/.github/actions/graphcheck-action/write_summary.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Reads GraphCheck's results.json and writes a pass/fail/error rollup
+to the GitHub Step Summary. Never raises: if results.json is missing or
+unreadable, it writes a clear "no results" message instead.
+"""
+
+import json
+import os
+
+ARTIFACTS_DIR = os.environ.get("GRAPHCHECK_ARTIFACTS_DIR", ".graphcheck")
+RESULTS_PATH = f"{ARTIFACTS_DIR}/runs/latest/results.json"
+
+
+def main():
+    summary_path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if not summary_path:
+        print("GITHUB_STEP_SUMMARY not set; nothing to write.")
+        return
+
+    lines = []
+
+    if not os.path.exists(RESULTS_PATH):
+        lines.append("## GraphCheck results\n")
+        lines.append(
+            "No results were produced. The run likely failed before it "
+            "could execute any checks (bad config, connection failure, "
+            "or setup/artifact error).\n"
+        )
+        _write(summary_path, lines)
+        return
+
+    try:
+        with open(RESULTS_PATH, encoding="utf-8") as f:
+            data = json.load(f)
+    except Exception as exc:
+        lines.append("## GraphCheck results\n")
+        lines.append(f"results.json exists but could not be read: {exc}\n")
+        _write(summary_path, lines)
+        return
+
+    totals = data.get("totals", {})
+    suites = data.get("suites", [])
+    checks = data.get("checks", [])
+    run = data.get("run", {})
+    score = data.get("score") or {}
+
+    lines.append("## GraphCheck results\n")
+    lines.append(
+        f"**Run status:** `{run.get('status', 'unknown')}` "
+        f" |  **Exit code:** `{run.get('exit_code', 'unknown')}` "
+        f" |  **Score:** {score.get('value', 'n/a')}\n"
+    )
+
+    lines.append(
+        f"**Totals:** {totals.get('checks', 0)} checks — "
+        f"{totals.get('pass', 0)} passed, "
+        f"{totals.get('fail', 0)} failed, "
+        f"{totals.get('errored', 0)} errored, "
+        f"{totals.get('warn', 0)} warned, "
+        f"{totals.get('skipped', 0)} skipped\n"
+    )
+
+    if suites:
+        lines.append("| Suite | Score | Pass | Fail | Errored | Warn | Skipped |")
+        lines.append("|---|---|---|---|---|---|---|")
+        for suite in suites:
+            t = suite.get("totals", {})
+            lines.append(
+                f"| {suite.get('id', '?')} | {suite.get('score', '?')} | "
+                f"{t.get('pass', 0)} | {t.get('fail', 0)} | "
+                f"{t.get('errored', 0)} | {t.get('warn', 0)} | "
+                f"{t.get('skipped', 0)} |"
+            )
+        lines.append("")
+
+    failing = [c for c in checks if c.get("verdict") in ("fail", "errored")]
+    if failing:
+        lines.append("### Failing / errored checks\n")
+        for c in failing:
+            evidence_msg = None
+            if c.get("evidence"):
+                evidence_msg = c["evidence"].get("message")
+            elif c.get("error"):
+                evidence_msg = c["error"].get("message")
+            evidence_msg = evidence_msg or "(no evidence message provided)"
+            lines.append(
+                f"- **{c.get('name', c.get('id', '?'))}** "
+                f"(`{c.get('suite_id', '?')}`, verdict: `{c.get('verdict')}`) "
+                f"— {evidence_msg}"
+            )
+        lines.append("")
+
+    _write(summary_path, lines)
+
+
+def _write(path, lines):
+    with open(path, "a", encoding="utf-8") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+if __name__ == "__main__":
+    main()

graphcheck-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## What this changes
+
+
+## Definition of done
+
+- [ ] Reviewed by the named CODEOWNER
+- [ ] Unit tests written and passing locally + CI
+- [ ] Integration tests pass against the fixture graph (where applicable)
+- [ ] Coverage ≥ 80% on owned code
+- [ ] No `print` / `console.log`; structured logger only
+- [ ] No swallowed exceptions (`except: pass`)
+- [ ] No un-issued TODOs
+- [ ] Design detailed in `docs/specs/<name>.md` (where applicable)
+- [ ] CHANGELOG.md entry
+- [ ] No new third-party dependency without team review
+- [ ] No agent meta-commentary or AI attribution anywhere

graphcheck-0.1.0/.github/scripts/first-run.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+: "${GRAPHCHECK_BIN:?Set GRAPHCHECK_BIN to the isolated graphcheck executable}"
+: "${GRAPHCHECK_PYTHON:?Set GRAPHCHECK_PYTHON to its Python executable}"
+
+FIRST_RUN_DIR="${FIRST_RUN_DIR:-${RUNNER_TEMP:-/tmp}/graphcheck-first-run}"
+mkdir -p "$FIRST_RUN_DIR"
+
+ready=0
+for ((attempt = 0; attempt < 60; attempt++)); do
+  if "$GRAPHCHECK_PYTHON" -c "from neo4j import GraphDatabase; d=GraphDatabase.driver('bolt://localhost:7687', auth=('neo4j', 'graphora'), connection_timeout=1); d.verify_connectivity(); d.close()" >/dev/null 2>&1; then
+    ready=1
+    break
+  fi
+  sleep 2
+done
+test "$ready" -eq 1
+
+"$GRAPHCHECK_PYTHON" -c "from neo4j import GraphDatabase; d=GraphDatabase.driver('bolt://localhost:7687', auth=('neo4j', 'graphora')); d.execute_query(\"MERGE (:Customer {name: 'Ada'})\", database_='neo4j'); d.close()"
+
+project="$FIRST_RUN_DIR/project"
+mkdir -p "$project"
+cd "$project"
+started=$("$GRAPHCHECK_PYTHON" -c "import time; print(time.monotonic())")
+"$GRAPHCHECK_BIN" init | tee init.log
+"$GRAPHCHECK_BIN" profile | tee profile.log
+"$GRAPHCHECK_BIN" run | tee run.log
+elapsed=$("$GRAPHCHECK_PYTHON" -c "import time; print(time.monotonic() - $started)")
+
+grep -q "Detected Neo4j" init.log
+test -f graphcheck.yml
+test -f profiles.yml
+test -f checks/example.yml
+baseline_found=0
+for baseline in .graphcheck/baselines/*.json; do
+  test -f "$baseline" && baseline_found=1 && break
+done
+test "$baseline_found" -eq 1
+test -f .graphcheck/runs/latest/results.json
+test -f .graphcheck/runs/latest/report.html
+"$GRAPHCHECK_PYTHON" -c "import json, pathlib; p=json.loads(pathlib.Path('.graphcheck/runs/latest/results.json').read_text()); assert p['run']['status']=='complete', p['run']; assert p['run']['exit_code']==0, p['run']; assert 0 <= float('$elapsed') < 600, 'first-run flow took $elapsed seconds'"
+printf 'init -> profile -> run completed in %.3f seconds (budget: <600 seconds)\n' "$elapsed" | tee timing.txt