{"id":51699123,"url":"https://github.com/edycutjong/docdrift","last_synced_at":"2026-07-16T08:33:49.504Z","repository":{"id":366427800,"uuid":"1276252963","full_name":"edycutjong/docdrift","owner":"edycutjong","description":"🔍 AI-powered Code↔Docs Drift Detector and Security-first Auditing Pipeline built for the Anna Hackathon","archived":false,"fork":false,"pushed_at":"2026-06-28T03:12:29.000Z","size":13223,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-16T08:33:45.811Z","etag":null,"topics":["anna-app","documentation-drift","hackathon","security"],"latest_commit_sha":null,"homepage":"https://edycutjong.github.io/docdrift/public/pitch.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edycutjong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-21T18:30:32.000Z","updated_at":"2026-06-23T00:06:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/edycutjong/docdrift","commit_stats":null,"previous_names":["edycutjong/docdrift"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/edycutjong/docdrift","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fdocdrift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fdocdrift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fdocdrift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fdocdrift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edycutjong","download_url":"https://codeload.github.com/edycutjong/docdrift/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fdocdrift/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35537751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anna-app","documentation-drift","hackathon","security"],"created_at":"2026-07-16T08:33:48.178Z","updated_at":"2026-07-16T08:33:49.499Z","avatar_url":"https://github.com/edycutjong.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/icon.svg\" alt=\"DocDrift Icon\" width=\"140\"\u003e\n  \u003ch1\u003eDocDrift 🔍\u003c/h1\u003e\n  \u003cp\u003e\u003cem\u003eAI-powered Code↔Docs Drift Detector and Security-first Auditing Pipeline\u003c/em\u003e\u003c/p\u003e\n  \u003cimg src=\"public/readme-hero.svg\" alt=\"DocDrift Hero Banner\" width=\"100%\"\u003e\n\n  \u003cbr/\u003e\n\n  [![Live Demo](https://img.shields.io/badge/🚀_Live-Demo-06b6d4?style=for-the-badge)](https://github.com/edycutjong/docdrift)\n  [![Pitch Video](https://img.shields.io/badge/🎬_Pitch-Video-ef4444?style=for-the-badge)](https://youtu.be/J8bCZnAEpNI)\n  [![Pitch Deck](https://img.shields.io/badge/📊_Pitch-Deck-f59e0b?style=for-the-badge)](https://edycutjong.github.io/docdrift/public/pitch.html)\n  [![Built for Anna AI-Native Hackathon](https://img.shields.io/badge/DoraHacks-Anna_Hackathon-8b5cf6?style=for-the-badge)](https://dorahacks.io/hackathon/2204)\n\n  \u003cbr/\u003e\n\n  ![Python 3.11](https://img.shields.io/badge/Python_3.11-3776AB?style=flat\u0026logo=python\u0026logoColor=white)\n  ![Node.js 22](https://img.shields.io/badge/Node.js_22-339933?style=flat\u0026logo=nodedotjs\u0026logoColor=white)\n  ![AES-GCM-256](https://img.shields.io/badge/Crypto-AES--GCM--256-blue?style=flat)\n  ![Anna Storage](https://img.shields.io/badge/Anna-APS_KV_Storage-10b981?style=flat)\n  ![R2 Upload](https://img.shields.io/badge/Anna-R2_Object_Upload-f59e0b?style=flat)\n  [![CI/CD Pipeline](https://github.com/edycutjong/docdrift/actions/workflows/ci.yml/badge.svg)](https://github.com/edycutjong/docdrift/actions)\n\n\u003c/div\u003e\n\n---\n\n## 📸 See it in Action\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003eInteractive Audit Walkthrough\u003c/h3\u003e\n  \n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd width=\"50%\"\u003e\n        \u003cp align=\"center\"\u003e\u003cb\u003e1. Workspace Config \u0026 Setup\u003c/b\u003e\u003c/p\u003e\n        \u003cimg src=\"docs/screenshots/recording_step1_setup.png\" alt=\"1. Setup\" width=\"100%\"\u003e\n      \u003c/td\u003e\n      \u003ctd width=\"50%\"\u003e\n        \u003cp align=\"center\"\u003e\u003cb\u003e2. Analysis Dashboard\u003c/b\u003e\u003c/p\u003e\n        \u003cimg src=\"docs/screenshots/recording_step2_dashboard.png\" alt=\"2. Dashboard\" width=\"100%\"\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd width=\"50%\"\u003e\n        \u003cp align=\"center\"\u003e\u003cb\u003e3. Side-by-Side Drift Viewer\u003c/b\u003e\u003c/p\u003e\n        \u003cimg src=\"docs/screenshots/recording_step3_viewer.png\" alt=\"3. Drift Viewer\" width=\"100%\"\u003e\n      \u003c/td\u003e\n      \u003ctd width=\"50%\"\u003e\n        \u003cp align=\"center\"\u003e\u003cb\u003e4. AI Auditor Chat\u003c/b\u003e\u003c/p\u003e\n        \u003cimg src=\"docs/screenshots/recording_step4_chat.png\" alt=\"4. AI Chat\" width=\"100%\"\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd width=\"50%\"\u003e\n        \u003cp align=\"center\"\u003e\u003cb\u003e5. Accepted Fix Status\u003c/b\u003e\u003c/p\u003e\n        \u003cimg src=\"docs/screenshots/recording_step5_accepted.png\" alt=\"5. Accepted\" width=\"100%\"\u003e\n      \u003c/td\u003e\n      \u003ctd width=\"50%\"\u003e\n        \u003cp align=\"center\"\u003e\u003cb\u003e6. Exported R2 Signed Bundle\u003c/b\u003e\u003c/p\u003e\n        \u003cimg src=\"docs/screenshots/recording_step6_exported.png\" alt=\"6. Export\" width=\"100%\"\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\n\u003e **The Audit Lifecycle**: 1. Scans repository exports -\u003e 2. Checks document mentions -\u003e 3. Classifies drift \u0026 suggests corrections -\u003e 4. Persists scan history to Anna KV -\u003e 5. Exports signed `.patch` bundles to Cloudflare R2.\n\n---\n\n## 💡 The Problem \u0026 Solution\n\nDocumentation rots silently. As APIs evolve, README guides and comment blocks drift, leading to onboarding failures and broken integrations. \n\n**DocDrift** solves this by walking local codebases inside a secure sandbox to parse symbols (functions, classes, endpoints), hashing signatures via SHA-256, and cross-referencing them against Markdown files. Sensitive code snippets are encrypted under **AES-GCM-256** prior to LLM drift classification.\n\n### Key Features:\n- ⚡ **Local Walkers**: Lightweight Python Executa process directory scans in \u003c10ms.\n- 🔒 **IP Protection**: Ephemeral local AES keys encrypt snippets in transit and KV storage.\n- 🤖 **Auditor Agent**: Interactive `agent.session.*` chatbot to explain and review signature drift.\n- 📦 **R2 Export**: Generates unified `.patch` bundles and uploads to R2 via `host/uploadFile` reverse-RPC.\n- 💾 **Persistent History**: Scan history persisted to Anna Persistent Storage (APS KV) via `storage/set` — no external database needed.\n\n---\n\n## 🏗️ Architecture \u0026 Tech Stack\n\n```mermaid\ngraph TD\n    UI[HTML/CSS/JS Iframe] --\u003e|window.open_view| DV[Drift Viewer View]\n    UI --\u003e|tools.invoke| EX[Python Executa Process]\n    EX --\u003e|SHA-256| HASH[Symbol Hash Verification]\n    EX --\u003e|AES-GCM-256| CRYP[Local Snippet Encryptor]\n    CRYP --\u003e|sampling/createMessage| LLM[Host LLM Reverse-RPC]\n    EX --\u003e|host/uploadFile| R2[Anna R2 Object Storage]\n    EX --\u003e|storage/set + storage/get| APS[Anna Persistent Storage KV]\n    UI --\u003e|storage.set/get| APS\n```\n\n---\n\n## 🔌 Anna Platform Integration\n\nDocDrift exercises the full Anna SDK capability surface:\n\n### Reverse-RPC Methods (Plugin → Host)\n\n| Method | Purpose | Implementation |\n|---|---|---|\n| `sampling/createMessage` | LLM inference for drift classification | `_sample()` in plugin.py |\n| `storage/get` | Read persistent scan history from APS KV | `_storage_get()` in plugin.py |\n| `storage/set` | Write scan history entries to APS KV | `_storage_set()` in plugin.py |\n| `storage/delete` | Remove scan entries from APS KV | `_storage_delete()` in plugin.py |\n| `storage/list` | List all past scan keys in APS KV | `_storage_list()` in plugin.py |\n| `host/uploadFile` (inline) | Upload generated `.diff` patches to R2 | `_host_upload_inline()` in plugin.py |\n| `host/uploadFile` (negotiate+confirm) | Stream large reports to R2 | `_host_upload_negotiate()` and `_host_upload_confirm()` |\n| `embeddings/create` | Compute dense vectors for code and docs | `_embed()` in plugin.py |\n| `image/generate` | Generate visual architecture illustrations | `_image_generate()` in plugin.py |\n| `files/upload_begin + complete` | Durable artifact uploads (2-phase) | `_files_upload()` in plugin.py |\n| `files/download_url` | Mint presigned links for archived reports | `_files_download_url()` in plugin.py |\n| `files/list` | List archived report files | `_files_list()` in plugin.py |\n| `files/delete` | Purge archived files | `_files_delete()` in plugin.py |\n| `agent/complete` | Stateless L1 completion | `_agent_complete()` in plugin.py |\n| `agent/session.create + run + history + cancel + delete` | Stateful L2 multi-turn agent sessions | `_agent_session_create()`, `_agent_session_run()`, etc. |\n\n### Host Capabilities Declared\n\n| Capability | Usage |\n|---|---|\n| `llm.sample` | Host-brokered LLM for drift classification \u0026 stateless completion |\n| `llm.embed` | Vector embedding compute for semantic search |\n| `llm.image` | DALL-E visual diagram generation |\n| `llm.agent.auto` | Stateful multi-turn L2 agent sessions |\n| `aps.kv` | Persistent scan history (last 50 scans) |\n| `host.upload` | R2 artifact upload for generated patches |\n\n### Manifest Features (Schema 2)\n\n| Feature | Status |\n|---|---|\n| `schema: 2` | ✅ |\n| `host_capabilities` | ✅ `llm.sample`, `llm.embed`, `llm.image`, `llm.agent.auto`, `host.upload` |\n| `user_message_prefix_template` | ✅ |\n| `system_prompt_addendum` | ✅ |\n| `optional_executas` | ✅ |\n| `csp_overrides` | ✅ |\n| `state_merge` | ✅ |\n| `dev.fixtures` | ✅ |\n| `dev.seed_storage` | ✅ |\n| `host_api.upload` (negotiate + confirm) | ✅ |\n| `host_api.chat` (write_message + append_artifact) | ✅ |\n| `host_api.storage` (get/set/delete/list) | ✅ |\n| `host_api.window` (set_title/open_view/close) | ✅ |\n| `host_api.llm` (complete/embed) | ✅ |\n| `host_api.image` (generate) | ✅ |\n| `host_api.agent` (session) | ✅ |\n| Multiple views with `min_size`/`max_size` | ✅ 2 views |\n| Developer Console | ✅ Interactive SDK playground \u0026 live log console |\n| `tags` | ✅ |\n\n### Cryptographic Security\n\n| Layer | Algorithm |\n|---|---|\n| Snippet encryption | AES-GCM-256 (ephemeral session keys) |\n| Symbol hashing | SHA-256 |\n\n---\n\n## 🏆 Sponsor Tracks Targeted\n- **Winner Takes All — $300**: Deep, *real* Anna integration — host LLM `sampling/createMessage`, APS KV storage (`get`/`set`/`list`/`delete`), durable APS Files, R2 uploads, `embeddings/create` semantic search, and `image/generate` diagrams — all driven through real Executa tools, a multi-view UI (`main` + `drift_viewer`), and `chat.append_artifact` cards, with local AES-GCM-256 cryptography. A sandboxed Developer Console lets you exercise the Host-API surface live (calls return labeled mock responses when run outside the Anna host).\n\n\n---\n\n## 📁 Project Structure\n\n```\ndorahacks-anna-docdrift/\n├── app.json                    # App listing metadata\n├── manifest.json               # Anna App manifest (schema: 2)\n├── LICENSE                     # MIT License\n├── DECISIONS.md                # Architectural decisions log\n├── SPONSOR_DEFENSE.md          # SDK integration citations\n├── package.json                # Project script definitions\n├── bundle/\n│   ├── index.html              # Frontend SPA structure\n│   ├── styles.css              # Modern dark theme styles\n│   ├── tokens.css              # Design tokens\n│   ├── app.js                  # State engine, SDK bridge \u0026 fallback mocks\n│   ├── anna-tool-ids.js        # Auto-generated tool bindings\n│   ├── apple-touch-icon.png    # Mobile browser bookmark icon\n│   └── icon.svg                # Embedded app icon\n├── executas/\n│   └── docdrift/\n│       ├── pyproject.toml      # Executa package configuration\n│       ├── executa.json        # Executa config (host_capabilities, distribution)\n│       └── plugin.py           # Stdio JSON-RPC handler + APS KV + R2 upload\n├── fixtures/\n│   └── drift_seed.jsonl        # Dev fixture data for offline testing\n├── data/\n│   └── fixtures/               # Additional seed data\n├── docs/\n│   ├── AUDIT_REPORT.md         # Threat model and invariants\n│   ├── friction-log.md         # Integration friction log\n│   ├── icon.svg                # Document icon\n│   ├── readme-hero.svg         # Tactical vector header SVG\n│   ├── assets/                 # HTML templates and asset generators\n│   └── screenshots/            # Step-by-step UX walkthrough screenshots\n├── public/\n│   ├── icon.svg                # Standalone app icon SVG\n│   ├── og-image.png            # Open Graph banner PNG\n│   └── pitch.html              # Standalone marketing pitch deck HTML\n├── scripts/\n│   ├── bench.py                # Latency and recall benchmarks\n│   ├── verify_offline.py       # Air-gapped container test\n│   └── record-docdrift.mjs     # Puppeteer demo recording\n└── tests/\n    └── test_plugin.py          # Complete unit tests (100% offline coverage)\n```\n\n---\n\n## 🚀 Getting Started\n\n### Prerequisites\n- Python ≥ 3.10\n- Node.js ≥ 20\n- `uv` (Python packaging tool)\n\n### Installation \u0026 Run\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/edycutjong/docdrift.git\n   ```\n2. Navigate to codebase:\n   ```bash\n   cd docdrift\n   ```\n3. Install npm dependencies:\n   Installs the required `@anna-ai/cli` devDependency locally:\n   ```bash\n   npm install\n   ```\n5. Run the development harness:\n   ```bash\n   npm run dev\n   # or\n   npx anna-app dev\n   ```\n\n---\n\n## 🧪 Testing \u0026 CI\n\nDocDrift includes a full verification harness with unit tests, offline air-gap audits, and benchmarks:\n\n```bash\n# ── Run Unit Tests (105+ assertions) ────────\nPYTHONPATH=. python3 tests/test_plugin.py\n\n# ── Run Air-Gapped Offline Verification ──────\nPYTHONPATH=. python3 scripts/verify_offline.py\n\n# ── Run Performance Benchmarks ──────────────\nPYTHONPATH=. python3 scripts/bench.py\n```\n\n| Layer | Tool | Status |\n|---|---|---|\n| Code Quality | Pytest + Local Assertions | ✅ |\n| Unit Testing | 100+ parameterized assertions | ✅ |\n| Air-Gap Scan | Mock socket offline check | ✅ |\n| Latency Audit | bench.py latency analysis | ✅ |\n\n---\n\n## 📄 License\nLicensed under [MIT](LICENSE). Copyright © 2026 Edy Cu.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedycutjong%2Fdocdrift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedycutjong%2Fdocdrift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedycutjong%2Fdocdrift/lists"}