typescript-decompiler/docs/todo/detecting-bounded-contexts.md

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:

   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:

   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.