{"id":31396222,"url":"https://github.com/shahramvafadar/darwin.solutioninsightforai","last_synced_at":"2026-05-18T19:09:19.046Z","repository":{"id":316650537,"uuid":"1064301679","full_name":"shahramvafadar/Darwin.SolutionInsightForAI","owner":"shahramvafadar","description":"A .NET 9 console utility that maps a .NET solution into a rich JSON index (files, type signatures, member signatures, and cleaned comments) to help AI assistants quickly understand and navigate large codebases. ","archived":false,"fork":false,"pushed_at":"2025-09-25T21:49:52.000Z","size":21,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-25T22:46:13.853Z","etag":null,"topics":["ai","code-analysis","code-index","code-mapping","console-app","csharp","developer-tools","dotnet","llm","roslyn"],"latest_commit_sha":null,"homepage":"","language":"C#","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/shahramvafadar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2025-09-25T20:47:01.000Z","updated_at":"2025-09-25T21:49:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"117180b3-4714-4e8d-aa14-370d8ec38f47","html_url":"https://github.com/shahramvafadar/Darwin.SolutionInsightForAI","commit_stats":null,"previous_names":["shahramvafadar/darwin.solutioninsightforai"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/shahramvafadar/Darwin.SolutionInsightForAI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahramvafadar%2FDarwin.SolutionInsightForAI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahramvafadar%2FDarwin.SolutionInsightForAI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahramvafadar%2FDarwin.SolutionInsightForAI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahramvafadar%2FDarwin.SolutionInsightForAI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shahramvafadar","download_url":"https://codeload.github.com/shahramvafadar/Darwin.SolutionInsightForAI/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahramvafadar%2FDarwin.SolutionInsightForAI/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277503542,"owners_count":25829216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-29T02:00:09.175Z","response_time":84,"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":["ai","code-analysis","code-index","code-mapping","console-app","csharp","developer-tools","dotnet","llm","roslyn"],"created_at":"2025-09-29T11:08:57.746Z","updated_at":"2025-09-29T11:09:00.472Z","avatar_url":"https://github.com/shahramvafadar.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Solution Insight for AI\n\n[![.NET](https://img.shields.io/badge/.NET-9.0-512BD4?logo=dotnet\u0026logoColor=white)](https://dotnet.microsoft.com/)\n[![Build](https://img.shields.io/badge/build-GitHub_Actions-blue?logo=githubactions)](#)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-0.3-blue)](#)\n[![Powered by Roslyn](https://img.shields.io/badge/Powered_by-Roslyn-8A2BE2)](https://learn.microsoft.com/dotnet/csharp/roslyn-sdk/)\n\n**Solution Insight for AI** — A .NET 9 console utility that scans a .NET solution/repository and exports a structured JSON “map” of files, types, and member signatures so AI assistants (e.g., ChatGPT/Copilot/Claude) can quickly understand and navigate your codebase without needing direct, persistent access to your repo.\n\n---\n\n## Table of Contents\n\n- [Problem](#problem)\n- [Solution](#solution)\n- [Features (v0.3)](#features-v03)\n- [Architecture](#architecture)\n- [Quick Start](#quick-start)\n  - [Configuration](#configuration)\n  - [Interactive Session Example](#interactive-session-example)\n- [Usage Playbook](#usage-playbook)\n  - [Prompt Ideas](#prompt-ideas)\n- [Output Schema (Project Mapping JSON)](#output-schema-project-mapping-json)\n- [Privacy \u0026 Safety](#privacy--safety)\n- [Troubleshooting](#troubleshooting)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n- [Project Description \u0026 Topics](#project-description--topics)\n- [Changelog](#changelog)\n\n---\n\n## Problem\n\n- Many AI tools **cannot** directly connect to Git providers, or they impose **strict limits** on how often/how much they can index. Even when possible, indexing large repos is **slow** and **unreliable**.\n- LLMs have **limited context**—even with a connection to your repo, they cannot keep the whole solution “in mind” at once.\n- **Privacy \u0026 sensitivity:** pushing entire source code to an AI service may be unacceptable. Teams need to control **what** is shared.\n- We need a **stable, tool-agnostic index**: a compact, structured summary (files, types, member signatures, cleaned comments) that any AI can ingest quickly, with minimal bandwidth and latency.\n- Developers want **fast Q\u0026A**: “Which methods accept `CartAddItemDto`?”, “Where is the entry point?”, “Show me the signature of XYZ” — without rescanning the repo every time.\n\n---\n\n## Solution\n\n**Solution Insight for AI** builds a **versioned JSON index** (“Project Mapping”) that includes:\n- A list of *important files* (`.cs`, `.cshtml`, `.html`, `.htm`, `.js`, `.css`).\n- For C# source files:\n  - **Class/Record** name **and full declaration signature** (e.g., `public class Foo\u003cT\u003e`).\n  - **Method/Constructor** **full signature line** (from modifiers/return-type up to *but not including* `{`).\n  - **Cleaned leading comments** as a single line (removes `///`, `//`, `/*…*/`, and XML doc tags like `\u003csummary\u003e`).\n- **Windows-style paths** (e.g., `E:\\Project\\...`); in JSON, backslashes are escaped as `\\\\` (standard; parsed value remains `\\`).\n- **No HTML escaping of generics** — angle brackets `\u003c`/`\u003e` are preserved in signatures.\n\nA second task, **Full Code Extract**, aggregates full `.cs` contents for troubleshooting or deeper phases; the primary focus of **v0.3** is the JSON mapping for fast AI ingestion.\n\n---\n\n## Features (v0.3)\n\n- **Project Mapping (JSON)**\n  - Important file listing: `.cs`, `.cshtml`, `.html`, `.htm`, `.js`, `.css`.\n  - For C#: class/record **signature**, method/ctor **signature**, and **cleaned** leading comments.\n  - Single, dated JSON output per run (e.g., `ProjectMapping_YYYYMMDD.json`).\n  - Preserves `\u003c`/`\u003e` in generics; avoids `\\u003C`/`\\u003E`.\n  - Does **not** repeat `filePath` per member; it’s declared once per file.\n\n- **Full Code Extract**\n  - Aggregates all `.cs` contents under a path (recursive optional) into one text file with separators.\n  - Useful for deep dives or when AI requests full source snippets.\n\n- **Config-driven defaults**\n  - `SolutionRoot`, `DomainRoot`, `OutputRoot` via `appsettings.json`.\n\n---\n\n## Architecture\n\n```mermaid\nflowchart LR\n    A[\"Console App\n(.NET 9)\"] --\u003e B[\"Prompts \u0026 Options\"]\n    B --\u003e C[\"Scanner\n(Files \u0026 Filters)\"]\n    C --\u003e D[\"Roslyn Parser\n(Classes/Records/Methods/Ctors)\"]\n    D --\u003e E[\"Comment Cleaner\n(XML, //, /* */)\"]\n    E --\u003e F[\"JSON Exporter\n(Project Mapping)\"]\n    C --\u003e G[\"Full Code Extract\n(.cs aggregation)\"]\n    F --\u003e H[\"AI Assistants\n(ChatGPT/Copilot/...)\"]\n    G --\u003e H\n```\n\n---\n\n## Quick Start\n\n\u003e Requires **.NET 9 SDK**.\n\n```bash\n# build \u0026 run\ndotnet build\ndotnet run --project src/Darwin.SolutionInsightForAI.App/Darwin.SolutionInsightForAI.App.csproj\n```\n\nDuring startup, choose a task and accept defaults or provide custom paths via prompts.\n\n### Configuration\n\nEdit `appsettings.json` to set defaults (Windows-style paths):\n\n```json\n{\n  \"GeneratorOptions\": {\n    \"Paths\": {\n      \"SolutionRoot\": \"E:\\\\_Projects\\\\Darwin\",\n      \"DomainRoot\": \"E:\\\\_Projects\\\\Darwin\\\\src\\\\Darwin.Domain\",\n      \"OutputRoot\": \"E:\\\\_Projects\\\\Darwin.Files\"\n    },\n    \"Export\": {\n      \"SchemaVersion\": \"1.2\",\n      \"StripXmlDocSummaryTags\": true\n    }\n  }\n}\n```\n\n- **SolutionRoot**: default for **Project Mapping** task.  \n- **DomainRoot**: default for **Full Code Extract** task.  \n- **OutputRoot**: where all outputs are written (e.g., `ProjectMapping_YYYYMMDD.json`).  \n\n\u003e Note: In raw JSON, backslashes appear as `\\\\`. When parsed, they become single `\\`.\n\n### Interactive Session Example\n\n```\n=============================================\n  Solution Insight for AI (Phase 1)\n  .NET 9 Console Application\n=============================================\n\nSelect a Task\nChoose what you want the app to do.\n  1. ProjectMapping\n  2. FullCodeExtract\nEnter number [default: ProjectMapping]: 1\n\nEnter the path to the .NET solution or root folder [default: E:\\_Projects\\Darwin]:\nAlso extract class comments? (y/n) [default: Y]: y\nAlso extract method comments? (y/n) [default: N]: n\n\nMapping completed. Output written to:\nE:\\_Projects\\Darwin.Files\\ProjectMapping_20250925.json\n```\n\n---\n\n## Usage Playbook\n\n### Baseline Flow\n1. **Generate the JSON map (Project Mapping)**  \n   Run the app, choose *Project Mapping*, and point to your repo root (or accept defaults).\n2. **Review \u0026 minimize**  \n   Skim the JSON. If anything is sensitive, remove or reduce before sharing.\n3. **Feed it to the AI**  \n   Upload the JSON file to your AI assistant (or paste relevant parts).\n4. **Iterate**  \n   If the AI needs more detail for a specific module, run *Full Code Extract* for that subpath and share it.\n\n### Prompt Ideas\n\n- **Overview**\n  \u003e “Here is a JSON map of the solution (files, types, member signatures, cleaned comments). Please summarize the architecture and identify the key modules, entry points, and cross-cutting concerns.”\n\n- **Find by DTO/return type**\n  \u003e “Using the JSON map, list all methods whose signatures accept `CartAddItemDto` or return `Task\u003cGuid\u003e`. Include file paths and containing classes.”\n\n- **Impact analysis**\n  \u003e “Given this JSON map and this new requirement, which files and methods will likely be affected? Propose a change plan and update steps.”\n\n- **Quality suggestions**\n  \u003e “Review the signatures and comments in the JSON map and propose naming/design improvements aligned with clean architecture.”\n\n---\n\n## Output Schema (Project Mapping JSON)\n\n**File name**\n\n```\nProjectMapping_YYYYMMDD.json\n```\n\n**Structure**\n\n```json\n{\n  \"schema\": \"darwin/project-mapping\",\n  \"schemaVersion\": \"1.2\",\n  \"generatedAtUtc\": \"2025-09-25T08:00:00Z\",\n  \"root\": \"E:\\\\_Projects\\\\Darwin\",\n  \"files\": [\n    {\n      \"filePath\": \"E\\\\_Projects\\\\Darwin\\\\src\\\\Darwin.Application\\\\CartCheckout\\\\Commands\\\\AddItemToCartHandler.cs\",\n      \"members\": [\n        {\n          \"name\": \"AddItemToCartHandler\",\n          \"kind\": \"Class\",\n          \"signature\": \"public class AddItemToCartHandler\",\n          \"summaryComment\": \"Adds or increases a cart line. Computes/validates add-on pricing and merges lines with identical configurations.\"\n        },\n        {\n          \"name\": \"AddItemToCartHandler\",\n          \"kind\": \"Method\",\n          \"signature\": \"public AddItemToCartHandler(IAppDbContext db, IAddOnPricingService addOnPricing)\",\n          \"summaryComment\": \"\"\n        },\n        {\n          \"name\": \"HandleAsync\",\n          \"kind\": \"Method\",\n          \"signature\": \"public async Task\u003cGuid\u003e HandleAsync(CartAddItemDto dto, CancellationToken ct = default)\",\n          \"summaryComment\": \"\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n**Notes**\n- `filePath` appears **once per file**; members do **not** repeat it.\n- `signature` excludes the method/type body `{ ... }`.\n- `summaryComment` is a single-line, cleaned text (no `///`, `//`, `/*…*/`, or XML tags).\n- Backslashes are escaped as `\\\\` in raw JSON (parsed value is `\\`).\n\n---\n\n## Privacy \u0026 Safety\n\n- **You are responsible** for any content you upload to AI services.\n- **Review outputs** and remove/minimize sensitive information before sharing externally.\n- Prefer **module-scoped** exports (map only the parts the AI needs) instead of the whole solution.\n- For enterprises, host the mapping internally; share only **sanitized subsets** to external tools.\n- Use project-level ignore rules (future feature): e.g., exclude secrets, credentials, generated code.\n- Be mindful of **licenses** and third-party code embedded in the repo when exporting.\n- If you need to reference source text, first try the **Project Mapping JSON**; only when required, use\n  **Full Code Extract** for the narrow subpath in question.\n- Avoid including large binary assets or private data (images, PDFs, dumps) in the mapping.\n- Keep your **appsettings.json** outside of VCS if it contains machine-specific or private paths.\n- Consider adding a company policy section in your repo on “**LLM Usage**” (what may/may not be shared).\n\n---\n\n## Troubleshooting\n\n- **Backslashes show as `\\` in JSON**  \n  This is correct per JSON spec for strings; parsed value is a single `\\`.\n\n- **Generics show as `\\u003C` / `\\u003E`**  \n  v0.3 sets `JsonSerializerOptions.Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping`.  \n  If you still see escapes, ensure this encoder is applied at the export call.\n\n- **`AddEnvironmentVariables` not found**  \n  Add packages:  \n  `Microsoft.Extensions.Configuration`, `...Json`, `...EnvironmentVariables`, `...Binder`.\n\n- **Mermaid diagrams not rendering on GitHub**  \n  Use labels with newline escapes instead of HTML tags, e.g., `A[\"Console App\\n(.NET 9)\"]`.\n  Ensure the code block is fenced with ```mermaid and closed properly.\n\n- **Missing comments in output**  \n  Turn on prompts accordingly: class comments (Y), method comments (Y).  \n  Notes: only **leading** comments immediately above declarations are captured.\n\n- **Missing files in mapping**  \n  Only “important” extensions are listed by default (`.cs`, `.cshtml`, `.html`, `.htm`, `.js`, `.css`).  \n  Extend the allow-list in code if you need more.\n\n- **Encoding/locale issues**  \n  Outputs are UTF-8. If you see mojibake, verify your editor’s encoding and font.\n\n---\n\n## Roadmap\n\n- **Dependency Graph (Roslyn Semantic Model)**\n  - Symbol references, call graphs, and per-project dependency trees.\n  - Cross-file navigation hints for AI prompts.\n\n- **Richer JSON Schema**\n  - Accessibility (public/internal/private), static/virtual/override, attributes.\n  - Namespaces, file-scoped namespaces, using directives.\n  - Optional member IDs for stable cross-references.\n\n- **Export Options**\n  - YAML export alongside JSON.\n  - Split-by-project/module outputs for very large solutions.\n  - Optional “display paths” for human-friendly views (single `\\`).\n\n- **Performance \u0026 Filtering**\n  - Parallel IO with throttling.\n  - Ignore patterns (e.g., `bin/obj`, `*.designer.cs`, generated code).\n  - Pluggable “important extensions” list.\n\n- **DX Improvements**\n  - CLI arguments to bypass prompts (CI-friendly).\n  - Dry-run and diff mode (compare two mappings).\n  - Small web viewer for browsing the JSON map.\n\n---\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. **Open an issue** describing the use case or problem first.\n2. Keep code style consistent (**.NET 9**, nullable enabled).\n3. Add focused tests for non-trivial changes when practical.\n4. Avoid introducing breaking changes to the JSON schema without discussion.\n5. Be mindful of privacy; never commit sensitive sample data.\n\n**Dev tips**\n- Prefer Roslyn APIs over regex for C# analysis.\n- Keep comments in **English** inside code; user-facing docs can be localized.\n- For performance, avoid loading entire large files into memory repeatedly; stream where possible.\n\n---\n\n## License\n\nThis project is licensed under the **MIT License**.\nSee the `LICENSE` file at the repository root for the full text.\n\n---\n\n## Project Description \u0026 Topics\n\n**Short description (GitHub Project Settings):**\n\u003e A .NET 9 console utility that maps a .NET solution into a rich JSON index (files, type signatures, member signatures, and cleaned comments) to help AI assistants quickly understand and navigate large codebases.\n\n**Suggested topics (comma-separated):**\n`dotnet, csharp, roslyn, code-analysis, code-index, developer-tools, ai, llm, code-mapping, console-app`\n\n---\n\n## Changelog\n\n### 0.3\n- Project Mapping JSON is the primary output for structure.\n- Preserves `\u003c` and `\u003e` in signatures (no HTML escaping).\n- Cleans `///`, `//`, and `/*…*/` into single-line summaries.\n- Avoids repeating `filePath` for each member; declared once per file.\n- Adds class/record signatures to the output.\n- Configuration via `appsettings.json` for default paths and export options.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshahramvafadar%2Fdarwin.solutioninsightforai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshahramvafadar%2Fdarwin.solutioninsightforai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshahramvafadar%2Fdarwin.solutioninsightforai/lists"}