feat(automation): transform repo into self-maintaining ecosystem

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @NITISH-R-G

.github/ISSUE_TEMPLATE/issue.yml

@@ -0,0 +1,24 @@
+name: Standard Issue
+description: Report a bug or request a feature
+title: "[Issue]: "
+labels: ["triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this issue report!
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of what the issue or feature request is.
+      placeholder: Tell us what you see, what you expect to see, or what you'd like to see added.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps To Reproduce (if bug)
+      description: Steps to reproduce the behavior.
+    validations:
+      required: false

.github/labeler.yml

@@ -0,0 +1,15 @@
+python:
+  - all:
+    - changed-files:
+      - any-glob-to-any-file: '**/*.py'
+
+documentation:
+  - all:
+    - changed-files:
+      - any-glob-to-any-file: '**/*.md'
+      - any-glob-to-any-file: 'docs/**/*'
+
+frontend:
+  - all:
+    - changed-files:
+      - any-glob-to-any-file: 'web/**/*'

.github/workflows/ai-insights.yml → .github/workflows/ai-review.yml

@@ -3,22 +3,20 @@ name: AI PR Agent
 on:
   pull_request:
     types: [opened, synchronize, reopened]
-  issue_comment:
+  pull_request_review_comment:
     types: [created]
 
+permissions:
+  contents: read
+  pull-requests: write
+
 jobs:
   pr_agent:
     runs-on: ubuntu-latest
-    permissions:
-      issues: write
-      pull-requests: write
-      contents: write
     name: Run PR Agent
     if: ${{ github.event.sender.type != 'Bot' }}
     steps:
-      - name: PR Agent action step
-        id: pragent
-        uses: Codium-ai/pr-agent@main
+      - uses: Codium-ai/pr-agent@main
         env:
           OPENAI_KEY: ${{ secrets.OPENAI_API_KEY }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/codeql.yml

@@ -0,0 +1,38 @@
+name: "CodeQL Analysis"
+
+on:
+  push:
+    branches: [ "main", "master" ]
+  pull_request:
+    branches: [ "main", "master" ]
+  schedule:
+    - cron: '0 0 * * 0' # Weekly
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python', 'javascript' ]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v3
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3

.github/workflows/greetings.yml

@@ -0,0 +1,20 @@
+name: Greetings
+
+on:
+  pull_request:
+    types: [opened]
+  issues:
+    types: [opened]
+
+jobs:
+  greeting:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/first-interaction@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          issue-message: "Welcome to our repository! Thank you for raising an issue. A maintainer will check it out shortly."
+          pr-message: "Welcome to our repository! Thank you for your first pull request. Please make sure all checks pass and `./validate-submission.sh` was successful locally."

.github/workflows/health-dashboard.yml

@@ -45,10 +45,3 @@ jobs:
         with:
           name: health-dashboard
           path: dashboard_output/
-
-      - name: Deploy to GitHub Pages
-        if: github.ref == 'refs/heads/main'
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./dashboard_output

.github/workflows/labeler.yml

@@ -0,0 +1,16 @@
+name: "Pull Request Labeler"
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  triage:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/labeler@v5
+      with:
+        repo-token: "${{ secrets.GITHUB_TOKEN }}"
+        sync-labels: true

.github/workflows/pages.yml

@@ -0,0 +1,33 @@
+name: Deploy GitHub Pages
+
+on:
+  workflow_run:
+    workflows: ["Repository Health Dashboard"]
+    types:
+      - completed
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download Dashboard Artifact
+        uses: dawidd6/action-download-artifact@v3
+        with:
+          workflow: health-dashboard.yml
+          name: health-dashboard
+          path: ./dashboard_output
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./dashboard_output

.github/workflows/repo-maintenance.yml

@@ -0,0 +1,63 @@
+name: Repository Maintenance
+
+on:
+  push:
+    branches: [ "main", "master" ]
+  schedule:
+    - cron: '0 0 * * *' # Daily at midnight UTC
+
+permissions:
+  contents: write
+
+jobs:
+  maintenance:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' || github.event_name == 'schedule' || github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.head_ref || github.ref }}
+          lfs: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: |
+          uv pip install --system -e ".[dev,demo]"
+          uv pip install --system cyclonedx-bom
+
+      - name: Generate Knowledge Graph
+        run: |
+          mkdir -p artifacts
+          python tools/generate_knowledge_graph.py || echo "Knowledge graph generation failed, skipping."
+
+      - name: Sync Documentation
+        run: |
+          mkdir -p docs
+          python tools/docs_sync.py || echo "Docs sync failed, skipping."
+
+      - name: Generate Architecture Diagrams
+        run: |
+          mkdir -p artifacts
+          python tools/generate_architecture_diagrams.py || echo "Architecture diagram generation failed, skipping."
+
+      - name: Generate SBOM
+        run: |
+          mkdir -p artifacts
+          cyclonedx-py environment -o artifacts/bom.json || echo "SBOM generation failed, skipping."
+
+      - name: Commit and Push Changes
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+          git add -A
+          git diff-index --quiet HEAD || git commit -m "chore(maintenance): automated repository updates"
+          git push

.github/workflows/stale.yml

@@ -0,0 +1,20 @@
+name: Close Stale Issues
+
+on:
+  schedule:
+    - cron: '30 1 * * *'
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          stale-issue-message: 'This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.'
+          stale-pr-message: 'This PR is stale because it has been open 45 days with no activity. Remove stale label or comment or this will be closed in 14 days.'
+          days-before-stale: 30
+          days-before-close: 7

.gitignore

@@ -31,3 +31,6 @@ ev_grid_oracle.egg-info/
 .coverage
 dashboard_output/
 build/
+
+.mypy_cache/
+.ruff_cache/

CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.

CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing to the Repository
+
+First off, thank you for considering contributing to this repository. It's people like you that make open source such a great community.
+
+## 1. Where do I go from here?
+
+If you've noticed a bug or have a feature request, make one! It's generally best if you get confirmation of your bug or approval for your feature request this way before starting to code.
+
+## 2. Fork & create a branch
+
+If this is something you think you can fix, then fork and create a branch with a descriptive name.
+
+## 3. Implementation Guidelines
+
+- Strictly follow an Agile Scrum continuous improvement methodology.
+- Maintain strong coding standards (SOLID, DRY).
+- We use `ruff` for linting/formatting and `mypy` for 100% type-safety.
+- Run local validation tools via `./validate-submission.sh`. No code is merged unless it passes formatting, type checking, and test suites.
+
+## 4. Make a Pull Request
+
+At this point, you should switch back to your master branch and make sure it's up to date with the main repository's master branch.
+Then push your feature branch and create a Pull Request.
+
+Please describe what you did and why, and link to the relevant issue.

ev_grid_oracle/bescom_feed.py

@@ -85,7 +85,7 @@ def snapshot(
         return out
 
     def _stable_seed(self, *, seed: int, scenario: str, tick: int) -> int:
-        s = f"{seed}:{scenario}:{tick}".encode("utf-8")
+        s = f"{seed}:{scenario}:{tick}".encode()
         h = sha1(s, usedforsecurity=False).hexdigest()[:8]
         return int(h, 16)
 

ev_grid_oracle/city_graph.py

@@ -2,7 +2,6 @@
 
 from dataclasses import dataclass
 from math import asin, cos, radians, sin, sqrt
-from typing import Optional
 
 import networkx as nx
 
@@ -255,7 +254,7 @@
 
     if not nx.is_connected(g):
         # Fail fast: graph must be connected for routing to work.
         comps = [sorted(list(c)) for c in nx.connected_components(g)]
         raise RuntimeError(f"city graph not connected, components={comps}")
 
     return g
@@ -266,7 +265,7 @@
     from_station_id: str,
     to_station_id: str,
     *,
-    default_if_missing: Optional[float] = None,
+    default_if_missing: float | None = None,
 ) -> float:
     if from_station_id == to_station_id:
         return 0.0