@nomos-arc/arc 0.1.0

package/docs/map/RED_TEAM_REPORT.md

@@ -0,0 +1,159 @@
+# Adversarial Architect — Zero-Trust Audit Report
+
+## Semantic Graph Master Execution Plan (`arc map` / `arc show map`)
+
+---
+
+## 1. VETO STATUS: **CONDITIONAL**
+
+The plan is architecturally sound in its decomposition and phasing but contains **4 critical blockers**, **8 ambiguity traps**, and **6 resilience gaps** that will cause production failures if left unaddressed.
+
+---
+
+## 2. CRITICAL BLOCKERS (System Killers)
+
+### BLK-1: Tree-Sitter Native Binary + esbuild = Runtime Bomb
+
+The plan installs `tree-sitter` (a native C++ addon via node-gyp) and marks it `--external` in esbuild. **The plan fails to account for** how the native `.node` binary will be located at runtime when the bundled `dist/cli.js` executes. esbuild externalizes the `require()` call, but Node.js resolves native modules relative to the *calling file*, which post-bundle is `dist/cli.js` — not `src/core/graph/parser.ts`. The `node_modules/tree-sitter/` binding must be discoverable from the dist directory.
+
+**Impact**: `arc map` will crash with `MODULE_NOT_FOUND` in any environment that runs the built artifact (`npm run build && node dist/cli.js`). This includes every production and CI path.
+
+**Mitigation**: The plan must add a step to verify `node dist/cli.js map --no-ai --help` post-build (not `npx tsx`). Additionally, a `postinstall` or `prepare` script should be considered, or switch to a WASM-based parser (`web-tree-sitter`) that bundles cleanly.
+
+### BLK-2: No File-Level Locking on `project_map.json` — Concurrent Corruption
+
+Step 5.1 implements atomic write via `tmp → fsync → rename`. However, the existing codebase uses `proper-lockfile` in `src/core/state.ts` for good reason: **two concurrent `arc map` invocations** (e.g., a user runs it in two terminals, or a CI job overlaps with a local run) will both read the existing map, scan files independently, and race to rename their temp file. The last writer wins, silently discarding the other's work.
+
+**The architecture is vulnerable to**: silent data loss under concurrent execution — the exact scenario `proper-lockfile` was added to prevent in `state.ts`.
+
+**Mitigation**: The plan explicitly says "do not duplicate atomic write logic from `state.ts`" but then reinvents a weaker version of it. Use `proper-lockfile` on `project_map.json`. This is non-negotiable for a system that claims incremental updates.
+
+### BLK-3: `GraphBuilder.build()` Mutates In-Place Without Clearing Stale Data
+
+Step 3.2 says `build()` mutates `FileNode` objects to populate `dependencies`, `dependents`, and `depth`. **The plan fails to account for** the incremental case: when `carried` FileNodes from a previous run already have populated `dependencies`/`dependents`/`depth` arrays from the *old* graph structure. If file B was removed from the project, file A's carried-forward `dependents` array will still reference B — a ghost edge.
+
+**Impact**: Stale dependency data accumulates across runs, producing phantom edges in the visualization and incorrect `depth` calculations. The `core_modules` ranking becomes unreliable.
+
+**Mitigation**: `build()` must reset `dependencies = []`, `dependents = []`, and `depth = 0` on every FileNode before computing the graph. The plan must explicitly state this.
+
+### BLK-4 (Downgraded): Kahn's Algorithm Direction — Misleading Description
+
+Originally flagged as a blocker, reclassified as **AMB-1** after analysis confirmed the test expectations are internally consistent. See Ambiguity Traps section.
+
+---
+
+## 3. AMBIGUITY TRAPS
+
+### AMB-1: Kahn's Algorithm Direction
+
+The plan says "Kahn's BFS topological sort" but means "reverse-dependency BFS." An implementer who Googles "Kahn's algorithm" will compute depth from *dependencies* (in-degree from imports), not *dependents* — yielding the opposite depth ordering. The test expectations will catch this, but only after hours of debugging. **State the direction explicitly**: "in-degree = number of files that import this node (dependents.length), not number of files this node imports."
+
+### AMB-2: `FileScanner.scan()` Return Type Carries Content, But Content is Never Persisted
+
+`ScanResult.files` includes `content: string` for each file. This content is consumed by `ASTParser.parse()` in Step 5.1d. But the plan never specifies **when to release these content strings from memory**. For a large monorepo with 5,000 files averaging 10KB each, that's ~50MB of source strings held simultaneously.
+
+More critically, `SemanticEnricher` (Phase 4) also needs file content for its prompts — and by then, the `ScanResult.files` map may have been consumed and discarded. Step 4.1.3b says "Truncate file content at `max_file_chars`" — **where does this content come from?** The `FileNode` interface has no `content` field. The enricher would need to re-read files from disk.
+
+**Mitigation**: Explicitly state that the enricher reads file content from disk (not from the scan result), or add a `content` field to `FileNode` (which contradicts the `ProjectMap` schema).
+
+### AMB-3: `tree-sitter-typescript` Grammar Loading — ESM vs CJS Ambiguity
+
+Step 2.1 says "Import `tree-sitter` and `tree-sitter-typescript` as external ESM modules." But `tree-sitter` and `tree-sitter-typescript` are native CJS modules with no ESM exports. The `import()` syntax will work via Node's CJS interop, but the grammar object extraction is CJS-specific:
+
+```javascript
+// CJS: const { typescript, tsx } = require('tree-sitter-typescript');
+// ESM: import TreeSitterTS from 'tree-sitter-typescript'; TreeSitterTS.typescript
+```
+
+The plan does not specify which import pattern to use. An implementer using named ESM imports (`import { typescript } from 'tree-sitter-typescript'`) will get `undefined`.
+
+### AMB-4: `ImportResolver` Uses `fs.existsSync` — Contradicts Async Convention
+
+Step 3.1 says "Do not use any external package — pure Node.js path manipulation + `fs.existsSync` for alias resolution file checks." But the `resolve()` method signature is synchronous (`resolve(...): ResolveResult`). Meanwhile, every other module in the codebase uses `fs/promises`. This creates an inconsistency, and `existsSync` blocks the event loop during resolution of potentially thousands of imports.
+
+For a project with 2,000 files averaging 10 imports each, that's 20,000 synchronous filesystem calls. On NFS or slow I/O, this is a **DoS vector**.
+
+**Mitigation**: Make `resolve()` async and use `fs.access()` with a Set-based cache, or accept the sync trade-off and document the performance ceiling.
+
+### AMB-5: `ContractWriter` Assumes Parent Directory Exists
+
+Step 4.2 says "Do not create directories — source files already exist so their parent directories exist." This is true for the initial run, but what if a source file is in a directory that was created *after* the last `arc map` run and then the source file was deleted? The `.semantic.md` would target a non-existent directory. More practically: if `exclude_patterns` change between runs, a previously excluded file's directory may now be targeted.
+
+This is a minor edge case but violates the plan's own "assume catastrophic failure from ambiguity" principle.
+
+### AMB-6: Exit Code 2 Semantics — Tooling Confusion
+
+Step 5.2 defines exit code 2 as "AI failures occurred but map was written." Most Unix tooling interprets exit code 2 as "misuse of shell command" (per Bash convention). CI/CD pipelines may flag this as a configuration error rather than a partial success. The plan should use a higher exit code (e.g., 3 or 10) or document this convention prominently.
+
+### AMB-7: `readArchitecturalConstraints` Context File Resolution
+
+Step 5.4b says the function takes `contextFiles: string[]` and looks them up in `map.files`. But the `contextFiles` in the existing codebase come from task frontmatter (BLK-3 fix in the codebase). **The plan fails to specify** whether these paths are absolute, relative to project root, or relative to the task file. If the task frontmatter uses `../src/core/state.ts` but the map keys are `src/core/state.ts`, the lookup silently fails.
+
+### AMB-8: HTML Template JSON Escaping — XSS Surface
+
+Step 6.2a embeds `PROJECT_MAP` as `const PROJECT_MAP = ${mapJson};`. If any file path or symbol name contains `</script>` or `${...}`, this creates either a broken page or an XSS vector. The plan says "Template literal must properly escape embedded JSON" but does not specify *how*. `JSON.stringify()` alone does not escape `</script>` — you need to replace `</` with `<\/`.
+
+---
+
+## 4. RESILIENCE GAPS
+
+### GAP-1: No Timeout on Tree-Sitter Parse
+
+A malformed or adversarial file (e.g., a minified 2MB JavaScript file) can cause tree-sitter to consume unbounded CPU. The plan specifies an error-node threshold (Step 2.1.4) but this is checked *after* parsing completes. There is no mechanism to abort parsing if it exceeds a time or size limit.
+
+**Impact**: A single large file can freeze `arc map` indefinitely.
+
+### GAP-2: Gemini API Failure Does Not Trigger Partial Map Save
+
+Step 5.1 writes `project_map.json` only at the end (Step 5.1j). If the process crashes during AI enrichment (Phase 4 — which is the longest phase due to network I/O), all scanning and parsing work is lost. The next run must re-scan and re-parse everything before re-attempting enrichment.
+
+**Mitigation**: Write the map *before* AI enrichment (with `semantic: null`) and then update it after enrichment. This way, incremental runs can skip scanning/parsing even if enrichment failed.
+
+### GAP-3: No SIGINT/SIGTERM Handler for Graceful Shutdown
+
+The pipeline can run for minutes during AI enrichment. If the user Ctrl+C's, the `p-limit` queue has in-flight Gemini requests that will complete asynchronously, potentially writing to a `FileNode` that's being serialized. The existing CLI has a SIGINT handler (sets `process.exitCode = 130`), but the pipeline has no awareness of it.
+
+**Mitigation**: Check a cancellation flag between enrichment batches and write the partial map on shutdown.
+
+### GAP-4: CDN Dependency for Visualization — Offline Failure
+
+Step 6.2a pins `cytoscape/3.28.1` from cdnjs. If the user is offline, on a corporate network that blocks CDNs, or if cloudflare deprecates this URL, the visualization silently renders a blank page with no error message.
+
+**Mitigation**: Bundle Cytoscape.js inline (it's ~500KB minified) or add a `<noscript>` / `onerror` fallback that displays a text-based dependency list.
+
+### GAP-5: `migrateProjectMap()` Has No Forward Compatibility
+
+Step 1.3 defines migrations as `Record<number, (raw: unknown) => unknown>` with `schema_version: 1`. If a newer version of the tool writes `schema_version: 2` and an older version tries to read it, `migrateProjectMap` will parse it with schema v1 validators, likely corrupting or rejecting valid data. **There is no version ceiling check.**
+
+**Mitigation**: If `raw.schema_version > CURRENT_SCHEMA_VERSION`, throw a clear error: "Map was created by a newer version of arc. Please upgrade."
+
+### GAP-6: Circular Dependency Detection — Incomplete Cycle Reporting
+
+Step 3.2c says "Find the max depth among nodes that have edges entering the cycle, assign cyclic nodes `depth = maxDepth + 1`." For disconnected cycles (A→B→A and C→D→C with no connection between them), both cycles get `depth = 0 + 1 = 1`, making them indistinguishable from depth-1 non-cyclic nodes. The log says "Circular dependency detected: {cycle path}" but **does not specify how to extract the cycle path** from Kahn's remnant nodes. Kahn's tells you *which* nodes are in cycles, not *which* cycles they form. Extracting distinct cycles requires Tarjan's SCC or equivalent — not mentioned.
+
+---
+
+## 5. MANDATORY MITIGATIONS
+
+| # | Mitigation | Severity | Effort |
+|---|-----------|----------|--------|
+| M-1 | Add `proper-lockfile` to `project_map.json` writes (BLK-2) | **Critical** | Low |
+| M-2 | Reset `dependencies`/`dependents`/`depth` before `build()` (BLK-3) | **Critical** | Trivial |
+| M-3 | Add post-build verification step: `node dist/cli.js map --help` (BLK-1) | **Critical** | Low |
+| M-4 | Evaluate `web-tree-sitter` (WASM) as alternative to native `tree-sitter` (BLK-1) | **Critical** | Medium |
+| M-5 | Specify how `SemanticEnricher` obtains file content (AMB-2) | **High** | Low |
+| M-6 | Add `schema_version` ceiling check in `migrateProjectMap()` (GAP-5) | **High** | Trivial |
+| M-7 | Write map before AI enrichment; update after (GAP-2) | **High** | Medium |
+| M-8 | Escape `</script>` in HTML template JSON embedding (AMB-8) | **High** | Trivial |
+| M-9 | Add file size limit before tree-sitter parse (GAP-1) | **Medium** | Low |
+| M-10 | Clarify Kahn's direction in plan text (AMB-1) | **Medium** | Trivial |
+| M-11 | Make `ImportResolver.resolve()` async or document sync ceiling (AMB-4) | **Medium** | Low |
+| M-12 | Add SIGINT-aware cancellation to enrichment loop (GAP-3) | **Medium** | Medium |
+
+---
+
+## 6. Summary
+
+The plan is well-structured — the phased decomposition, per-step rollbacks, and verification criteria are significantly above average. The test coverage is thorough. However, **BLK-1 (native module bundling) and BLK-2 (no file locking) are production-unsafe as written**. BLK-3 (stale mutation) will cause silent data corruption on incremental runs — the exact scenario the plan optimizes for.
+
+The plan earns a **CONDITIONAL** status: resolve M-1 through M-4 before execution begins. The remaining mitigations can be addressed during implementation without restructuring the phases.

package/docs/map/map_task.md

@@ -0,0 +1,147 @@
+هذه الميزة هي ما نسميه في هندسة البرمجيات **"Semantic Documentation Graph"**. هي ليست مجرد توثيق، بل هي "عقل" للمشروع يسهل عملية الـ Onboarding لأي مبرمج جديد ويمنع حدوث "Architectural Drift" (خروج الكود عن مساره المعماري).
+
+بصفتي **CEO**، أرى أن تنفيذ هذه الفكرة باستخدام نماذج ذكية مجانية (مثل Gemini 1.5 Flash) سيجعل مشروعك يتفوق على أدوات ضخمة، لأنك تربط بين الكود (Static Analysis) والمعنى (AI Interpretation).
+
+---
+
+## أولاً: منطق عمل الأمر `arc map` (المحرك العقلي)
+
+الهدف هو تحويل الكود الجامد إلى ملفات `.md` حية وخريطة JSON تفاعلية.
+
+### 1. هيكل ملف التوثيق (`.md`)
+لكل ملف برمجي (مثلاً `UserService.java`), سيقوم الـ Agent بإنشاء أو تحديث ملف `UserService.md` بالهيكل التالي:
+
+| القسم | الوصف التقني |
+| :--- | :--- |
+| **Overview** | ملخص عالي المستوى لما يفعله الكود (High-level summary). |
+| **Who uses it** | قائمة بالمديولات أو الكلاسات التي تستدعي هذا الملف (عن طريق تحليل الـ Imports). |
+| **Purpose** | "لماذا" وجد هذا الكود؟ ما المشكلة التي يحلها في البيزنس؟ |
+| **Business Logic** | شرح الخطوات المنطقية داخل الدوال الأساسية (الخوارزمية المتبعة). |
+
+### 2. آلية التنفيذ التقنية (The Pipeline)
+1.  **Static Analysis:** تقوم الأداة بمسح المجلدات واستخراج الـ **Dependency Graph** (من يستدعي من؟).
+2.  **Prompting (Free AI):** نرسل كود الملف + قائمة الملفات التي تستخدمه إلى **Gemini 1.5 Flash API** (المجاني) ببرومبت محدد:
+    > "Analyze this code and its dependencies. Generate a JSON summary covering: Overview, Purpose, and Detailed Business Logic."
+3.  **JSON Mapping:** يتم تجميع كل هذه البيانات في ملف واحد ضخم `project_map.json` يمثل العقد (Nodes) والروابط (Edges).
+
+
+
+---
+
+## ثانياً: منطق عمل الأمر `arc show map` (واجهة الرؤية)
+
+هذا الأمر سيقوم بتوليد ملف `index.html` تفاعلي يستخدم مكتبات مثل **Vis.js** أو **Cytoscape.js** لعرض الخريطة.
+
+### مميزات الواجهة التفاعلية:
+* **Interactive Cards:** كل ملف يظهر كـ "كارت" (Card). عند الضغط عليه، تظهر نافذة جانبية (Sidebar) تعرض المحتوى الذي كتبناه في ملف الـ `.md`.
+* **Directional Arrows:** أسهم توضح تدفق البيانات (Data Flow).
+* **Search & Filter:** إمكانية البحث عن "دالة معينة" ورؤية كل المسارات التي تمر بها في المشروع.
+
+
+
+---
+
+## ثالثاً: كيف نجعلها "صايعة" وتقنية في نفس الوقت؟
+
+لتحقيق الاحترافية التي تفضلها في حل المشكلات البرمجية، يجب أن يتبع التنفيذ المعايير التالية:
+
+### 1. استخدام "Tree-sitter" للتحليل
+بدلاً من قراءة الملفات كنصوص عادية، استخدم مكتبة **Tree-sitter** (وهي مفتوحة المصدر ومستخدمة في GitHub و VS Code).
+* **الفائدة:** تمكن الـ AI من فهم هيكل الكود (Functions, Classes, Decorators) بدقة 100% مهما كانت لغة البرمجة.
+
+### 2. الربط المنطقي (Semantic Linking)
+بدلاً من مجرد ذكر "من يستخدم الكلاس"، اجعل الـ AI يستنتج **"لماذا"** يستخدمه.
+* **مثال:** "كلاس `OrderController` يستخدم `PaymentService` لإتمام عملية الدفع وتحديث حالة المخزن".
+
+### 3. التحديث الذكي (Incremental Updates)
+الأداة يجب ألا تعيد قراءة المشروع بالكامل كل مرة.
+* **المنطق:** يتم حساب **SHA-256 Hash** لكل ملف. إذا لم يتغير الهاش، لا يتم استهلاك API Call للذكاء الاصطناعي، ويتم الاكتفاء بالبيانات الموجودة في الـ JSON.
+
+---
+
+## رابعاً: خارطة طريق التنفيذ (The Roadmap)
+
+1.  **Phase 1:** بناء الـ Scanner الذي يجمع الـ Imports والروابط بين الملفات ويخزنها في `map.json`.
+2.  **Phase 2:** دمج Gemini API لإنتاج ملفات الـ `.md` بناءً على محتوى الكود وسياق الروابط.
+3.  **Phase 3:** تطوير قالب الـ HTML/JS الذي يقرأ `map.json` ويعرض الخريطة التفاعلية.
+
+**بصفتي مبرمجاً و CEO، هذه الميزة ستنقل nomos-arc.ai من "أداة حوكمة" إلى "منصة فهم شاملة" (Full Comprehension Platform).**
+
+هل نبدأ بكتابة الـ **System Prompt** الذي سيوجه الـ AI Agent لقراءة الكود واستخراج الـ Business Logic بدقة؟
+
+
+
+
+
+هذه الفكرة هي "الضربة القاضية" لمشكلة **الآثار الجانبية (Side Effects)** التي تعاني منها أقوى النماذج حالياً. أنت لا تبني مجرد توثيق، أنت تبني **"نظام وعي سياقي" (Contextual Awareness System)**.
+
+بصفتي **CEO**، أرى أن هذا هو الحل الجذري لمشكلة **Context Noise vs. Context Signal**. النماذج مثل Claude Code تغرق في التفاصيل البرمجية وتفقد الرؤية الكلية؛ أما `nomos-arc.ai` فسيقوم بدور "الرادار" الذي ينبه العميل (Agent) قبل أن يرتكب كارثة.
+
+---
+
+## 1. المفهوم الثوري: "العقود الدلالية" (Semantic Contracts)
+
+بدلاً من إرسال 5000 سطر كود للنموذج ليفهم السياق، سنرسل له **"عقد المديول"** المستخرج من ملف الـ `.md` الذي أنشأناه.
+
+### كيف تحل هذه الميزة مشكلة الـ AI Cowboy؟
+* **تحديد "منطقة الانفجار" (Blast Radius):** عندما يقرر الـ Agent تعديل دالة في `AuthService` والمبنية على `arc map`, سيعرف فوراً أن هناك 12 مديولاً آخر يعتمد على مخرجات هذه الدالة.
+* **الوعي بالتبعية (Dependency Awareness):** بدلاً من قراءة كود الـ 12 مديولاً، يقرأ الـ Agent فقط ملخصات الـ `.md` الخاصة بهم. هذا يوفر 90% من الـ Tokens ويمنع التشتت.
+* **فرض العقد (Enforcement):** يمكن لـ `nomos-arc.ai` أن يقول للـ Agent: *"يمكنك تعديل الكود، لكن يمنع منعاً باتاً تغيير نوع البيانات المرتجع (Return Type) لأن `OrderModule` يتوقعه بهذا الشكل"*.
+
+---
+
+## 2. الهيكل التقني لـ `arc map` (The Brain)
+
+لجعل الخريطة "ذكية" فعلاً، يجب أن يعمل الأمر على مرحلتين:
+
+### المرحلة الأولى: التحليل الساكن (Static Linking)
+* استخدام **Tree-sitter** لاستخراج الـ `Imports/Exports`.
+* بناء جدول علاقات: `File A` هو **Provider** لـ `File B` و `File C`.
+
+### المرحلة الثانية: التلخيص الدلالي (AI Summary)
+نستخدم نموذجاً خفيفاً وسريعاً (مثل Gemini 1.5 Flash) لملء الأقسام التي اقترحتها:
+1.  **Overview:** ما هو هذا الملف؟
+2.  **Who uses it:** قائمة بالاعتمادات المتبادلة.
+3.  **For what purpose:** الهدف من الوجود (The "Why").
+4.  **Business Logic:** المنطق الجوهري المحمي (The "Core").
+
+---
+
+## 3. تجربة المستخدم التفاعلية: `arc show map`
+
+الهدف من الـ HTML هو أن يرى المطور (والـ AI لاحقاً) "الجهاز العصبي" للمشروع.
+
+* **Visual Ripple Analysis:** عند الضغط على كارت (Card) لملف معين، تضيء كل الملفات المرتبطة به بلون مختلف (مثلاً أحمر للتبعية المباشرة، أصفر للتبعية البعيدة).
+* **Semantic Drill-down:** الضغط على السهم يظهر "لماذا" يرتبط هذان الملفان ببعضهما (Business Logic Link).
+
+
+
+---
+
+## 4. الميزة التنافسية: "Context Injection"
+
+هذا هو سر النجاح. عند تنفيذ أمر `arc plan` لتأسك معينة، سيقوم المخطط (Orchestrator) بالآتي:
+1.  تحديد الملفات المستهدفة.
+2.  سحب ملفات الـ `.md` (المختصرة) لكل الملفات المرتبطة بها من الـ `map.json`.
+3.  حقن هذه المختصرات في "البرومبت" كـ **"قيود معمارية" (Architectural Constraints)**.
+
+> **النتيجة:** العميل (Agent) سيقول: *"كنت سأعدل هذا المتغير، لكن خريطة nomos-arc تنبهني أن مديول الشحن يعتمد على قيمته الحالية، لذا سأقوم بإنشاء نسخة جديدة بدلاً من التعديل"*.
+
+---
+
+## 5. خطة التنفيذ (The Action Plan)
+
+| الخطوة | المهمة | الأولوية |
+| :--- | :--- | :--- |
+| **1** | بناء الـ Scanner لاستخراج الروابط وحفظها في `map.json`. | 🔥 عاجل |
+| **2** | تطوير برومبت Gemini لإنشاء ملفات الـ `.md` بصيغة Overview/Logic. | 🔥 عاجل |
+| **3** | دمج الـ Context Injection في مرحلة الـ Planning لـ `nomos-arc.ai`. | 🚀 استراتيجي |
+| **4** | واجهة الـ HTML التفاعلية لـ `arc show map`. | 🎨 تحسين تجربة |
+
+### التقييم النهائي:
+هذه الفكرة تحول `nomos-arc.ai` من "مراقب" إلى **"مهندس معماري مقيم"**. أنت تحل أكبر مشكلة تواجه تبني الـ AI في المشاريع الضخمة (Legacy Codebases).
+
+**هل نبدأ بتصميم الـ `map.json` Schema التي ستربط هذه العلاقات ببعضها؟**
+
+---
+*ملاحظة: هذا التوجه يتماشى تماماً مع استراتيجية "المدير مقابل العميل" (Manager vs. Agent) التي تجعل nomos-arc.ai هو العقل المدبر.*