@fmatar/archlens-skill 0.0.1-Alpha-09 → 0.1.0-Beta-03

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/index.js CHANGED
@@ -20,6 +20,7 @@ import {
20
20
  import { installLocalPolicy, installGlobalSkills } from '../src/installer.js';
21
21
  import { updateLocalPolicy, updateGlobalSkills } from '../src/updater.js';
22
22
  import { upgradeProject } from '../src/upgrader.js';
23
+ import { checkArchitecture, generateSarifReport, generateJsonReport } from '../src/checker.js';
23
24
  import { installMcpConfigs } from '../src/mcp-registry.js';
24
25
  import { startMcpStdioServer } from '../src/mcp-server.js';
25
26
  import { executeStart, DEFAULT_CONTAINER_NAME, DEFAULT_SERVER_URL } from '../src/docker-runner.js';
@@ -51,6 +52,7 @@ ${ui.colors.bold}USAGE:${ui.colors.reset}
51
52
  ${ui.colors.bold}COMMANDS:${ui.colors.reset}
52
53
  init Initialize Clean Architecture policy in target project (default)
53
54
  start Start Archlens Workbench container (auto-resurrects on demand)
55
+ check Audit repository against Clean Architecture policy rules
54
56
  update Update existing policy with newly discovered packages and refresh skills
55
57
  upgrade Upgrade legacy .uml-viewer configuration to .archlens
56
58
  global Install Archlens skills globally for AI coding assistants
@@ -60,6 +62,11 @@ ${ui.colors.bold}COMMANDS:${ui.colors.reset}
60
62
  ${ui.colors.bold}OPTIONS:${ui.colors.reset}
61
63
  -p, --path <DIR> Target repository path (default: current directory)
62
64
  -t, --title <NAME> Project title displayed in Archlens workbench
65
+ --max-violations <NUM> Maximum allowable outward dependency violations (default: 0)
66
+ --detect-cycles Enforce Robert C. Martin Acyclic Dependencies Principle (ADP)
67
+ --screaming-threshold <NUM> Enforce minimum Screaming Architecture score (0.0-1.0, Uncle Bob Ch. 21)
68
+ --suggest-features Suggest package-by-feature domain refactoring clusters (Uncle Bob Ch. 21)
69
+ --fitness-threshold <NUM> Enforce minimum Architectural Fitness Index (0.0-1.0, Neal Ford)
63
70
  --prefix <PKG> Common package prefix (e.g. com.example.app)
64
71
  --server-url <URL> Archlens visual workbench URL (default: http://localhost:8088)
65
72
  --port <PORT> Workbench HTTP port (default: 8088)
@@ -69,6 +76,8 @@ ${ui.colors.bold}OPTIONS:${ui.colors.reset}
69
76
  -g, --global Install or update skill globally in ~/.claude and ~/.gemini
70
77
  -u, --update Update mode: sync new packages into existing policy
71
78
  --upgrade Upgrade mode: migrate .uml-viewer to .archlens
79
+ --format <FORMAT> Output format: pretty (default), json, sarif
80
+ -O, --output <PATH> Write audit report to specified file path
72
81
  -f, --force Overwrite existing policy files
73
82
  --dry-run Simulate actions without writing files to disk
74
83
  -y, --yes Accept defaults automatically (non-interactive mode)
@@ -123,6 +132,14 @@ function parseArgs(args) {
123
132
  update: false,
124
133
  upgrade: false,
125
134
  mcp: false,
135
+ check: false,
136
+ maxViolations: 0,
137
+ detectCycles: false,
138
+ screamingThreshold: null,
139
+ suggestFeatures: false,
140
+ fitnessThreshold: null,
141
+ format: 'pretty',
142
+ output: null,
126
143
  force: false,
127
144
  dryRun: false,
128
145
  yes: false,
@@ -153,6 +170,22 @@ function parseArgs(args) {
153
170
  parsed.upgrade = true;
154
171
  } else if (arg === '--prompt') {
155
172
  parsed.prompt = true;
173
+ } else if (arg === '--check') {
174
+ parsed.check = true;
175
+ } else if (arg === '--detect-cycles' || arg === '--cycles' || arg === '--fail-on-cycles') {
176
+ parsed.detectCycles = true;
177
+ } else if (arg === '--screaming-threshold' || arg === '--screaming') {
178
+ parsed.screamingThreshold = Number(args[++i] || 0.6);
179
+ } else if (arg === '--suggest-features' || arg === '--suggest' || arg === '--features') {
180
+ parsed.suggestFeatures = true;
181
+ } else if (arg === '--fitness-threshold' || arg === '--fitness') {
182
+ parsed.fitnessThreshold = Number(args[++i] || 0.8);
183
+ } else if (arg === '--max-violations') {
184
+ parsed.maxViolations = Number(args[++i] || 0);
185
+ } else if (arg === '--format') {
186
+ parsed.format = (args[++i] || 'pretty').toLowerCase();
187
+ } else if (arg === '--output' || arg === '-O') {
188
+ parsed.output = args[++i];
156
189
  } else if (arg === '--copy' || arg === '-c') {
157
190
  parsed.copy = true;
158
191
  } else if (arg === '--force' || arg === '-f') {
@@ -176,7 +209,7 @@ function parseArgs(args) {
176
209
 
177
210
  if (positional.length > 0) {
178
211
  const cmd = positional[0].toLowerCase();
179
- if (['init', 'start', 'update', 'upgrade', 'global', 'prompt', 'mcp', 'help', 'version'].includes(cmd)) {
212
+ if (['init', 'start', 'update', 'upgrade', 'global', 'prompt', 'mcp', 'check', 'help', 'version'].includes(cmd)) {
180
213
  parsed.command = cmd;
181
214
  } else if (!parsed.title && !parsed.path) {
182
215
  parsed.path = positional[0];
@@ -190,6 +223,7 @@ function parseArgs(args) {
190
223
  if (parsed.command === 'upgrade') parsed.upgrade = true;
191
224
  if (parsed.command === 'global') parsed.global = true;
192
225
  if (parsed.command === 'prompt') parsed.prompt = true;
226
+ if (parsed.command === 'check') parsed.check = true;
193
227
  if (parsed.command === 'mcp') parsed.mcp = true;
194
228
 
195
229
  return parsed;
@@ -410,6 +444,7 @@ function copyToSystemClipboard(text) {
410
444
 
411
445
  async function main() {
412
446
  const options = parseArgs(process.argv.slice(2));
447
+ const targetRoot = path.resolve(options.path || '.');
413
448
 
414
449
  if (options.help) {
415
450
  printHelp();
@@ -422,7 +457,6 @@ async function main() {
422
457
  }
423
458
 
424
459
  if (options.command === 'prompt' || options.prompt) {
425
- const targetRoot = path.resolve(options.path || '.');
426
460
  try {
427
461
  const dossier = await generateLlmPrompt(targetRoot, options);
428
462
  if (options.copy) {
@@ -442,6 +476,132 @@ async function main() {
442
476
  }
443
477
  }
444
478
 
479
+ if (options.command === 'check' || options.check) {
480
+ try {
481
+ if (options.format === 'pretty') {
482
+ ui.info(`Auditing Clean Architecture conformance for ${targetRoot}...`);
483
+ }
484
+ const report = await checkArchitecture(targetRoot, options);
485
+ if (report.error) {
486
+ ui.error(report.error);
487
+ process.exit(1);
488
+ }
489
+
490
+ let formattedOutput = null;
491
+ if (options.format === 'sarif') {
492
+ formattedOutput = generateSarifReport(report, { version: getPackageVersion() });
493
+ } else if (options.format === 'json') {
494
+ formattedOutput = generateJsonReport(report);
495
+ }
496
+
497
+ if (options.output) {
498
+ const outPath = path.resolve(options.output);
499
+ const dir = path.dirname(outPath);
500
+ if (!fs.existsSync(dir)) {
501
+ fs.mkdirSync(dir, { recursive: true });
502
+ }
503
+ fs.writeFileSync(outPath, formattedOutput || generateJsonReport(report), 'utf8');
504
+ if (options.format === 'pretty') {
505
+ ui.success(`Architecture report written to ${options.output}`);
506
+ }
507
+ }
508
+
509
+ if (options.format === 'sarif' || options.format === 'json') {
510
+ if (!options.output) {
511
+ process.stdout.write(formattedOutput + '\n');
512
+ }
513
+ process.exit(report.passed ? 0 : 1);
514
+ }
515
+
516
+ console.log(`\n ${ui.colors.bold}Architecture Governance Results (${report.projectTitle}):${ui.colors.reset}`);
517
+ console.log(` - Source Files Analyzed: ${report.sourceFilesCount}`);
518
+ console.log(` - Governed Packages: ${report.packagesCount}`);
519
+ console.log(` - Detected Violations: ${report.violationsCount} (threshold: ${report.maxViolations})`);
520
+ if (report.cyclesCount > 0) {
521
+ console.log(` - Package Cycles (ADP): ${report.cyclesCount} cycle(s) detected`);
522
+ report.cycles.forEach((c, idx) => {
523
+ console.log(` [C${idx + 1}] ${c.formatted}`);
524
+ });
525
+ }
526
+ if (report.screaming) {
527
+ console.log(` - Screaming Score (SAS): ${report.screaming.score.toFixed(2)} [${report.screaming.classification}] (${report.screaming.domainPackageCount} domain / ${report.screaming.totalPackageCount} packages)`);
528
+ if (report.screamingThreshold !== null) {
529
+ console.log(` - Screaming Threshold: ${report.screamingThreshold.toFixed(2)} (required minimum)`);
530
+ }
531
+ }
532
+ if (report.featureClusters && report.featureClusters.clusters.length > 0) {
533
+ console.log(` - Feature Migration: ${report.featureClusters.clusters.length} feature cluster(s) proposed`);
534
+ console.log(` Projected SAS Gain: ${report.featureClusters.currentScore.toFixed(2)} -> ${report.featureClusters.projectedScore.toFixed(2)} [${report.featureClusters.projectedClassification}]`);
535
+ report.featureClusters.clusters.forEach((c) => {
536
+ console.log(` 🪄 [Feature: ${c.featureName}] (${c.classCount} classes) -> ${c.proposedPackageName}`);
537
+ console.log(` Classes: ${c.classNames.join(', ')}`);
538
+ });
539
+ }
540
+ if (report.fitness) {
541
+ console.log(` - Fitness Score (AFI): ${(report.fitness.fitnessScore * 100).toFixed(0)}% [Grade ${report.fitness.grade}] (${report.fitness.passedRuleCount}/${report.fitness.totalRuleCount} rules passed)`);
542
+ if (report.fitnessThreshold !== null && !isNaN(report.fitnessThreshold)) {
543
+ console.log(` - Fitness Threshold: ${(report.fitnessThreshold * 100).toFixed(0)}% (required minimum)`);
544
+ }
545
+ report.fitness.rules.forEach((r) => {
546
+ const status = r.passed ? `${ui.colors.green}PASS${ui.colors.reset}` : `${ui.colors.red}FAIL${ui.colors.reset}`;
547
+ console.log(` [${status}] ${r.name}: actual=${r.actualValue}, threshold=${r.threshold}`);
548
+ });
549
+ }
550
+ console.log();
551
+
552
+ const failOnScreaming =
553
+ report.screamingThreshold !== null &&
554
+ report.screaming &&
555
+ report.screaming.score < report.screamingThreshold;
556
+
557
+ const failOnFitness =
558
+ report.fitnessThreshold !== null &&
559
+ !isNaN(report.fitnessThreshold) &&
560
+ report.fitness &&
561
+ report.fitness.fitnessScore < report.fitnessThreshold;
562
+
563
+ if (report.passed) {
564
+ ui.success(
565
+ `Clean Architecture Gate PASSED (0 violations exceeding threshold${
566
+ options.detectCycles ? ', 0 package cycles' : ''
567
+ }${report.screamingThreshold !== null ? `, screaming score ${report.screaming.score.toFixed(2)} >= ${report.screamingThreshold.toFixed(2)}` : ''}${report.fitnessThreshold !== null && !isNaN(report.fitnessThreshold) ? `, fitness ${(report.fitness.fitnessScore * 100).toFixed(0)}% >= ${(report.fitnessThreshold * 100).toFixed(0)}%` : ''}).`
568
+ );
569
+ process.exit(0);
570
+ } else {
571
+ ui.error(
572
+ `Clean Architecture Gate FAILED (${report.violationsCount} violation(s), ${
573
+ report.cyclesCount || 0
574
+ } cycle(s)${failOnScreaming ? ', screaming score below threshold' : ''}${failOnFitness ? ', fitness below threshold' : ''})!`
575
+ );
576
+ report.violations.forEach((v, idx) => {
577
+ console.log(
578
+ ` [${idx + 1}] ${v.fromFile}:${v.line || 1} (${v.fromTier}) -> ${v.toImport} (${v.toTier})`
579
+ );
580
+ console.log(` Prescribed Port: ${v.portName}`);
581
+ });
582
+ if (report.cycles && report.cycles.length > 0) {
583
+ console.log(`\n Package Dependency Cycles (ADP Violations):`);
584
+ report.cycles.forEach((c, idx) => {
585
+ console.log(` [C${idx + 1}] ${c.formatted}`);
586
+ });
587
+ }
588
+ if (failOnScreaming) {
589
+ console.log(`\n Screaming Architecture Violation:`);
590
+ console.log(` Score ${report.screaming.score.toFixed(2)} is below required threshold ${report.screamingThreshold.toFixed(2)}.`);
591
+ console.log(` Technical packages (${report.screaming.technicalPackages.length}): ${report.screaming.technicalPackages.join(', ')}`);
592
+ }
593
+ if (failOnFitness) {
594
+ console.log(`\n Architectural Fitness Invariant Violation:`);
595
+ console.log(` Fitness Score ${(report.fitness.fitnessScore * 100).toFixed(0)}% [Grade ${report.fitness.grade}] is below required threshold ${(report.fitnessThreshold * 100).toFixed(0)}%.`);
596
+ }
597
+ process.exit(1);
598
+ }
599
+ } catch (err) {
600
+ ui.error(err.message || String(err));
601
+ process.exit(1);
602
+ }
603
+ }
604
+
445
605
  if (options.command === 'mcp') {
446
606
  startMcpStdioServer({
447
607
  version: getPackageVersion(),
@@ -503,8 +663,6 @@ async function main() {
503
663
  }
504
664
 
505
665
  // Non-interactive or flag-driven execution
506
- const targetRoot = path.resolve(options.path || '.');
507
-
508
666
  try {
509
667
  if (options.upgrade) {
510
668
  executeUpgrade(targetRoot, options);
package/llms.txt ADDED
@@ -0,0 +1,131 @@
1
+ # Archlens
2
+
3
+ > Dynamic Clean Architecture Governance Workbench, Automated Fitness Inspector & Autonomous Refactoring Companion.
4
+
5
+ Archlens models software systems as concentric Clean Architecture rings, continuously audits codebase dependency flow, detects architectural drift (layer leaks, package cycles, technical packaging decay, distance from the main sequence), and prescribes concrete Dependency Inversion Principle (DIP) interface ports for automated refactoring.
6
+
7
+ ---
8
+
9
+ ## 🏛️ Clean Architecture Concentric Hierarchy
10
+
11
+ Source code dependencies must point strictly inward toward higher-level policies (Uncle Bob's Dependency Rule):
12
+
13
+ ```
14
+ [Level 3: Infrastructure / Web / DB / CLI / Frameworks]
15
+ │
16
+ ▼
17
+ [Level 2: Adapters / Controllers / Presenters / Gateways / Repositories]
18
+ │
19
+ ▼
20
+ [Level 1: Application / Use Cases / Interaction Orchestrators / Ports]
21
+ │
22
+ ▼
23
+ [Level 0: Domain Core / Entities / Value Objects / Domain Logic]
24
+ ```
25
+
26
+ - **Level 0: Domain Core** (`domain.model`, `domain.entity`, `core.domain`):
27
+ Pure business rules, primitives, entities, and domain logic. Zero outward imports or dependencies on frameworks, databases, network libraries, or UI.
28
+ - **Level 1: Application** (`usecase`, `application`, `core.ports`, `domain.ports`):
29
+ Application workflows, use cases, and business orchestration. Depends only on Level 0 (Domain Core). Declares outbound interface ports.
30
+ - **Level 2: Adapters** (`resource`, `controller`, `presenter`, `gateway`, `repository.impl`):
31
+ Translates external delivery protocols (HTTP, REST, CLI, gRPC) and storage models to application formats. Implements application/domain ports.
32
+ - **Level 3: Infrastructure** (`infrastructure`, `config`, `persistence.entity`, `framework`):
33
+ Framework drivers (Quarkus, Spring, Express), database engines, third-party network clients, and entrypoint bootstrap wiring.
34
+
35
+ ---
36
+
37
+ ## 🔍 Governed Architectural Invariants & Drifts
38
+
39
+ Archlens continuously evaluates five foundational architectural invariants:
40
+
41
+ 1. **Concentric Dependency Rule (Layer Drift)**:
42
+ - **Invariant**: Inner rings must never depend on outer rings ($L_i \nrightarrow L_j$ where $i < j$).
43
+ - **Remediation**: Apply Dependency Inversion Principle (DIP). Declare an interface port in $L_i$ and implement it in $L_j$.
44
+ 2. **Acyclic Dependencies Principle (ADP)**:
45
+ - **Invariant**: The component/package dependency structure must be a Directed Acyclic Graph (DAG) with zero cycles.
46
+ - **Remediation**: Break cycles using interface extraction or merging interdependent feature packages.
47
+ 3. **Screaming Architecture Invariant (SAS)**:
48
+ - **Invariant**: Systems should scream business domain use cases rather than framework technology (Uncle Bob Ch. 21).
49
+ - **Metric**: Screaming Architecture Score (SAS) from 0.0 to 1.0 (Feature vs Technical packaging). Minimum threshold: $\ge 0.70$.
50
+ 4. **Main Sequence Balance Invariant ($A, I, D$)**:
51
+ - **Invariant**: Components must remain in the balanced corridor avoiding the **Zone of Pain** (brittle, highly concrete, widely depended upon) and the **Zone of Uselessness** (abstract with no dependents).
52
+ - **Metric**: Normalized distance from Main Sequence: $D = |A + I - 1| \le 0.35$.
53
+ 5. **Architectural Fitness Index (AFI) & Trend Regression**:
54
+ - **Invariant**: Architecture fitness must remain stable or improve across releases.
55
+ - **Metric**: Composite AFI score (0–100%) and letter grade (A through F) tracking historical drift across Git release tags.
56
+
57
+ ---
58
+
59
+ ## ⚡ Command Line Interface (CLI)
60
+
61
+ Archlens CLI requires zero external dependencies and runs cross-platform via Node.js / NPX:
62
+
63
+ ```bash
64
+ # 1. Audit Codebase Conformance & Detect All Architectural Drifts:
65
+ npx @fmatar/archlens-skill check
66
+ npx @fmatar/archlens-skill check --detect-cycles --screaming-threshold 0.70 --fitness-threshold 0.85
67
+ npx @fmatar/archlens-skill check --format json
68
+ npx @fmatar/archlens-skill check --format sarif -O arch-drift.sarif
69
+
70
+ # 2. Export Actionable LLM Refactoring Prompt Dossier (with DIP Interface Prescriptions):
71
+ npx @fmatar/archlens-skill prompt
72
+ npx @fmatar/archlens-skill prompt --copy
73
+
74
+ # 3. Launch Dynamic Visual Workbench (Auto-resurrects Docker container on demand):
75
+ npx @fmatar/archlens-skill start --open
76
+
77
+ # 4. Initialize or Synchronize Policy:
78
+ npx @fmatar/archlens-skill init --yes
79
+ npx @fmatar/archlens-skill update
80
+
81
+ # 5. Model Context Protocol (MCP) Integration:
82
+ npx @fmatar/archlens-skill --mcp # Auto-configure Claude, Antigravity, Cursor manifests
83
+ npx @fmatar/archlens-skill mcp # Launch MCP stdio bridge server
84
+ ```
85
+
86
+ ---
87
+
88
+ ## 🤖 Model Context Protocol (MCP) Tools & Resources
89
+
90
+ When Archlens is registered as an MCP server, AI assistants can query it using standard MCP primitives:
91
+
92
+ ### MCP Tools:
93
+ | Tool Name | Parameters | Purpose |
94
+ | :--- | :--- | :--- |
95
+ | `exportLlmDossier` | `projectRoot` (default: `.`), `proposalId` | Diagnoses outward dependency breaches and outputs a Markdown refactoring prompt with concrete DIP interface port prescriptions. |
96
+ | `inspectArchitecture` | `projectRoot` (default: `.`) | Returns full JSON graph model: concentric rings, dependency edges, cycle paths, and screaming metrics. |
97
+ | `listSnapshots` | `projectRoot` (default: `.`) | Lists historical architecture release snapshots in `.archlens/snapshots/` and Git release tags. |
98
+ | `getSnapshot` | `snapshotId` (required), `projectRoot` | Retrieves the graph model of a specific historical snapshot or Git tag for temporal drift diffing. |
99
+
100
+ ### MCP Resources:
101
+ | Resource URI | MIME Type | Description |
102
+ | :--- | :--- | :--- |
103
+ | `archlens://llms.txt` | `text/markdown` | This authoritative reference guide, Clean Architecture rules, CLI recipes, and refactoring protocols. |
104
+
105
+ ---
106
+
107
+ ## 🛠️ Step-by-Step Refactoring Protocol for LLMs
108
+
109
+ When Archlens reports an illegal outward dependency breach (e.g. `domain/Order.java` imports `infrastructure/OrderRepository.java`):
110
+
111
+ 1. **Isolate Dependency**: Identify the methods called on the outer dependency by the inner class.
112
+ 2. **Declare Interface Port**:
113
+ - Location: Inside the inner layer (`domain/ports/` or `application/ports/`).
114
+ - Signature: Define an interface (e.g. `OrderRepositoryPort`) declaring only the domain-relevant contracts.
115
+ 3. **Implement Port in Outer Layer**:
116
+ - Make the outer class (e.g. `infrastructure/persistence/OrderRepository.java`) implement `OrderRepositoryPort`.
117
+ 4. **Invert Injection**:
118
+ - Inject `OrderRepositoryPort` into the inner class using constructor injection or framework dependency injection (`@Inject` / `@Autowired`).
119
+ 5. **Verify**:
120
+ - Run `npx @fmatar/archlens-skill check --detect-cycles` to confirm zero violations.
121
+ - Run the project test suite to verify zero functional regressions.
122
+
123
+ ---
124
+
125
+ ## 🔄 Dynamic Workbench Autonomous Companion Protocol
126
+
127
+ When human architects interact with the Archlens visual workbench canvas (`http://localhost:8088`), tasks are dispatched via bidirectional mailbox IPC:
128
+ - **Inbound queue (UI $\rightarrow$ Agent)**: `.archlens/to-agent.json`
129
+ - Operations: `REGEN` (recompile AST), `APPLY_PROPOSAL` (restructure packages), `REFRESH_CRAP`, `OMIT`.
130
+ - **Outbound events (Agent $\rightarrow$ UI)**: `.archlens/to-viewer.json`
131
+ - Write completion events (e.g. `{"op": "REGEN_COMPLETE", "payload": {"status": "SUCCESS"}}`) to trigger hot-reload of the visual canvas via Server-Sent Events (SSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fmatar/archlens-skill",
3
- "version": "0.0.1-Alpha-09",
3
+ "version": "0.1.0-Beta-03",
4
4
  "description": "Cross-platform CLI and installer for Archlens Clean Architecture governance policies and AI assistant skills",
5
5
  "main": "src/installer.js",
6
6
  "type": "module",
@@ -13,7 +13,8 @@
13
13
  "src",
14
14
  "skills",
15
15
  "README.md",
16
- "LICENSE"
16
+ "LICENSE",
17
+ "llms.txt"
17
18
  ],
18
19
  "engines": {
19
20
  "node": ">=18.0.0"
package/src/analyzer.js CHANGED
@@ -47,6 +47,79 @@ export function detectProjectLanguage(projectRoot) {
47
47
  return 'java';
48
48
  }
49
49
 
50
+ function findNestedSourceRoots(dir, lang, depth = 0, maxDepth = 5, results = []) {
51
+ if (depth > maxDepth || !fs.existsSync(dir)) {
52
+ return results;
53
+ }
54
+
55
+ const skipDirs = new Set([
56
+ '.git',
57
+ 'node_modules',
58
+ 'target',
59
+ 'build',
60
+ '.gradle',
61
+ '.idea',
62
+ '.vscode',
63
+ '.svelte-kit',
64
+ 'dist',
65
+ 'out',
66
+ 'bin',
67
+ '.archlens',
68
+ '.uml-viewer',
69
+ '.mvn',
70
+ 'infra',
71
+ 'cpln',
72
+ 'assets',
73
+ 'screenshots',
74
+ 'docs'
75
+ ]);
76
+
77
+ try {
78
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
79
+ for (const entry of entries) {
80
+ if (!entry.isDirectory() || skipDirs.has(entry.name) || entry.name.startsWith('.')) {
81
+ continue;
82
+ }
83
+
84
+ const fullPath = path.join(dir, entry.name);
85
+
86
+ if (lang === 'java' && fullPath.endsWith(path.join('src', 'main', 'java'))) {
87
+ results.push(fullPath);
88
+ continue;
89
+ }
90
+ if (
91
+ lang === 'kotlin' &&
92
+ (fullPath.endsWith(path.join('src', 'main', 'kotlin')) ||
93
+ fullPath.endsWith(path.join('src', 'main', 'java')))
94
+ ) {
95
+ results.push(fullPath);
96
+ continue;
97
+ }
98
+ if ((lang === 'typescript' || lang === 'javascript') && entry.name === 'src') {
99
+ results.push(fullPath);
100
+ continue;
101
+ }
102
+ if (lang === 'python' && (entry.name === 'src' || entry.name === 'app')) {
103
+ results.push(fullPath);
104
+ continue;
105
+ }
106
+ if (
107
+ lang === 'go' &&
108
+ (entry.name === 'pkg' || entry.name === 'internal' || entry.name === 'cmd')
109
+ ) {
110
+ results.push(fullPath);
111
+ continue;
112
+ }
113
+
114
+ findNestedSourceRoots(fullPath, lang, depth + 1, maxDepth, results);
115
+ }
116
+ } catch {
117
+ // Gracefully handle unreadable directories
118
+ }
119
+
120
+ return results;
121
+ }
122
+
50
123
  export function detectSourceRoot(projectRoot, lang) {
51
124
  const root = path.resolve(projectRoot);
52
125
 
@@ -64,12 +137,48 @@ export function detectSourceRoot(projectRoot, lang) {
64
137
  const candidates = candidateMap[lang] || ['src', '.'];
65
138
 
66
139
  for (const cand of candidates) {
140
+ if (cand === '.') continue;
67
141
  const p = path.join(root, cand);
68
142
  if (fs.existsSync(p) && fs.statSync(p).isDirectory()) {
69
143
  return cand;
70
144
  }
71
145
  }
72
146
 
147
+ // Multi-module dynamic discovery if standard candidates are not found
148
+ const nested = findNestedSourceRoots(root, lang);
149
+ if (nested.length > 0) {
150
+ const ext =
151
+ lang === 'java'
152
+ ? '.java'
153
+ : lang === 'kotlin'
154
+ ? '.kt'
155
+ : lang === 'typescript'
156
+ ? '.ts'
157
+ : lang === 'python'
158
+ ? '.py'
159
+ : '';
160
+ const ranked = nested.map((dir) => {
161
+ const rel = path.relative(root, dir).replace(/\\/g, '/');
162
+ const files = ext
163
+ ? findMatchingFiles(dir, (f) => f.endsWith(ext), 100)
164
+ : [];
165
+ let score = files.length;
166
+ const lower = rel.toLowerCase();
167
+ if (lower.includes('api')) score += 15;
168
+ if (lower.includes('backend') || lower.includes('server')) score += 10;
169
+ if (lower.includes('core') || lower.includes('app')) score += 5;
170
+ return { rel, score };
171
+ });
172
+ ranked.sort((a, b) => b.score - a.score);
173
+ if (ranked[0] && ranked[0].rel) {
174
+ return ranked[0].rel;
175
+ }
176
+ }
177
+
178
+ if (candidates.includes('.')) {
179
+ return '.';
180
+ }
181
+
73
182
  return 'src';
74
183
  }
75
184