Initial commit

2026-05-25 05:47:28 +00:00
commit 4d6495ffda
97 changed files with 13403 additions and 0 deletions
@@ -0,0 +1,83 @@
+#  System Prompt: Evolutionary Architecture Pipeline Implementation
+
+**Goal:** Build a custom CI/CD script that combines spatial data (where code lives), temporal data (when code changes), and structural data (what the code does) to guide incremental refactoring in a TypeScript + Effect.ts codebase.
+
+**Tech Stack:**
+1.  **Dependency-Cruiser:** To map spatial boundaries (Seams).
+2.  **Hercules:** To map temporal evolutionary coupling. 
+3.  **Opengrep:** To identify data-flow anti-patterns (Tramp Data, Branching).
+4.  **TypeScript (Node.js):** The "glue" script (`refactor-bot.ts`) that synthesizes the data.
+
+---
+
+### Step 1: Establish Spatial Boundaries (Dependency-Cruiser)
+**Agent Instructions:**
+1. Install dependency-cruiser: `npm install -D dependency-cruiser`
+2. Initialize it `npx depcruise --init` and configure it for a TypeScript environment.
+3. Modify the `.dependency-cruiser.js` configuration to define "Seams". Group the application by folders (e.g., Domain boundaries, Layers, or Effect modules).
+4. Create an npm script named `"map:boundaries"` that runs depcruise and outputs the architecture to a JSON file: `npx depcruise src --output-type json > ./.architecture/seams.json`.
+
+---
+
+### Step 2: Establish Temporal Coupling (Hercules / Git Mining)
+**Agent Instructions:**
+1. Set up a tool to extract **Logical Coupling** from the git history. 
+   *(Note for Agent: Use the `src-d/hercules` binary via Docker or Go, OR use the simpler `code-maat` Python/Clojure alternative if Hercules is blocked by local environment constraints).*
+2. Execute a git log command to get history:
+   ```bash
+   git log --all --numstat --date=short --pretty=format:'--%h--%ad--%aN' --no-renames > ./.architecture/logfile.log
+   ```
+3. Run the coupling analysis tool against this log. The goal is to output a `.csv` or `.json` file (`coupling.json`) with three columns/fields: `[FileA, FileB, CoChangePercentage]`.
+4. Ensure this output is saved to `/.architecture/coupling.json`.
+
+---
+
+### Step 3: Implement Deep Static Analysis (Opengrep / Semgrep)
+**Agent Instructions:**
+1. Install the open-source CLI (e.g., `npm install -g opengrep` or use `pip install semgrep`).
+2. Create a folder `/.architecture/rules/`.
+3. Write custom YAML rules to detect code smells specific to **Effect.ts** and functional pipelines. 
+4. **Rule 1: Tramp Data in Pipelines.** Write a rule that looks for a variable passed into a `.pipe()` or `Effect.gen` that traverses across a recognized boundary un-mutated. Use the ellipsis operator (`...`).
+   *Example concept:*
+   ```yaml
+   rules:
+     - id: effect-tramp-data
+       pattern: pipe(..., $MOD_A.get($DATA), ..., $MOD_B.save($DATA), ...)
+       message: "Potential tramp data crossing seam boundaries."
+       languages: [typescript]
+       severity: WARNING
+   ```
+5. Ensure there is a command to run this and output to JSON: `opengrep --config ./.architecture/rules/ --json > ./.architecture/smells.json`
+
+---
+
+### Step 4: Write the Synthesis Script (`refactor-bot.ts`)
+**Agent Instructions:**
+Write a Node.js TypeScript file (`scripts/refactor-bot.ts`) that acts as the brain. This script must:
+
+**1. Load the Data:**
+*   Parse `seams.json` (Which files belong to which boundary).
+*   Parse `coupling.json` (How often files change together).
+*   Parse `smells.json` (Where the AST anti-patterns are).
+
+**2. Detect Cross-Seam Leaks (High External Coupling):**
+*   Look at pairs in `coupling.json` that co-change > 60% of the time, but live in *different* Seams according to `seams.json`.
+*   *Action:* Flag these as **Architectural Leaks**. Check if `smells.json` found tramp data in these specific files. 
+
+**3. Detect Splittable Contexts (Low Internal Cohesion):**
+*   Look at files that exist in the *same* Seam (e.g., both are in `src/payments/`), but have a co-change frequency of < 5%.
+*   *Action:* Flag this boundary as a candidate to be split into two smaller bounded contexts.
+
+**4. Generate the Output/Report:**
+*   Output a Markdown report summarizing:
+    *   **⚠️ High Priority Refactors:** Cross-layer tightly coupled files (includes Semgrep AST context).
+    *   **✂️ Suggested Seam Splits:** Modules with low internal cohesion.
+*   Exit with code `1` if the max coupling threshold is breached to fail the CI/CD pipeline, otherwise exit with `0`.
+
+---
+
+### Definition of Done for Agent:
+1. `dependency-cruiser` is configured and outputs `seams.json`.
+2. Git history pipeline outputs `coupling.json`.
+3. Opengrep/Semgrep YAML rules are written for Effect.ts and output `smells.json`.
+4. `refactor-bot.ts` successfully reads all three files and prints an Evolutionary Architecture Report in the console.