@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 +162 -4
- package/llms.txt +131 -0
- package/package.json +3 -2
- package/src/analyzer.js +109 -0
- package/src/checker.js +736 -0
- package/src/mcp-registry.js +26 -15
- package/src/mcp-server.js +93 -4
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
|
|
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
|
|