<\/p>\n
Most articles about code analysis tools talk about “how many languages they support, how many rules they have, how many vulnerabilities they can detect.” ai-analyze supports 7 languages, 12 security rules, and 4-dimensional quality scoring \u2014 these feature numbers are right there in the README. This article doesn’t rehash the feature list. Instead, it explores five easily overlooked yet deeply worthwhile design decisions \u2014 each with a “why not” story behind it.<\/p>\n
<\/p>\n
<\/p>\n
ai-analyze implements two MCP integration strategies. On the surface, calling Serena’s Python API directly (in-process import) is faster and simpler, while the protocol-compliant stdio client (JSON-RPC 2.0 over subprocess communication) is slower and more cumbersome. It seems like a performance decision.<\/p>\n
<\/p>\n
But the real key difference isn’t performance \u2014 it’s the security boundary<\/strong>. The direct-call strategy exposes all of Serena’s tools \u2014 including <\/p>\n <\/p>\n The core judgment behind the two coexisting strategies: is your MCP service for yourself, or for others? For yourself, direct calls are more efficient and you can control yourself not to do dangerous operations. For others, protocol compliance is mandatory \u2014 you can’t assume other people’s agents will correctly use modification capabilities. Constraining them through architectural boundaries is more reliable than constraining them through documentation.<\/p>\n <\/p>\n <\/p>\n Serena provides symbol structure \u2014 class inheritance, function call chains, cross-file reference relationships. The AST analyzer provides complexity scoring, code smell detection, parameter analysis, and async\/static annotations. When merging the two data sources, which one takes the lead?<\/p>\n <\/p>\n Intuition might pick Serena \u2014 symbol structure is the skeleton of code, while complexity and smells are attributes. But ai-analyze’s <\/p>\n Even more interesting: the <\/p>\n The design philosophy this decision conveys: the main loop of data merging should revolve around actionable dimensions, not structural ones. Structural information provides context; metric information drives decisions.<\/p>\n <\/p>\n <\/p>\n ai-analyze has three DeepSeek AI calls: code quality assessment, Docker strategy suggestions, and framework upgrade analysis. Every call’s prompt embeds structured facts from AST analysis \u2014 Top 5 complex functions, Top 10 code smells, Top 20 dependencies. The AI isn’t asked to discover complexity problems; it’s handed confirmed facts to interpret. This “rules-first, AI-interprets” pattern reduces hallucination risk \u2014 the AI can’t claim “this project has no complexity issues” because the prompt explicitly lists 5 functions with complexity above 10.<\/p>\n <\/p>\n But the least obvious design decision lies in the framework upgrade analysis prompt. There’s one explicit instruction:<\/p>\n <\/p>\n > “If the current version is already the latest stable release, state that clearly \u2014 don’t push for an upgrade.”<\/p>\n <\/p>\n This instruction counters a fundamental LLM tendency: always suggesting changes<\/strong>. LLM training data is full of “upgrade to the latest version” and “migrate to the new framework” suggestions because technical articles and Stack Overflow answers naturally lean toward recommending change. But in real-world scenarios, a React 18 project doesn’t need to upgrade to React 19 RC, and a Python 3.11 project doesn’t need to upgrade to 3.12. Without this instruction, the AI will almost certainly recommend an upgrade \u2014 even when the upgrade has no tangible benefit, even when it introduces compatibility risks.<\/p>\n <\/p>\n This follows the same thinking as the temperature gradient across the three AI calls: code quality assessment uses <\/p>\n <\/p>\n The quality scoring formula: <\/p>\n Why is maintainability weighted highest (0.35)? Because it’s the long-term cost driver \u2014 unmaintainable code gets harder to modify every time, with technical debt growing exponentially. Complexity is a “current state” metric, reliability is a “risk” metric, and maintainability is a “trend” metric. Trends predict future costs, so they deserve the highest weight.<\/p>\n <\/p>\n But the more interesting question is why security is weighted lowest (0.15). The security score is calculated as <\/p>\n The security scanner itself uses 12 regex-matched rules, with risk scoring using severity-weighted geometric weighting (INFO=0.1, LOW=0.25, MEDIUM=0.5, HIGH=0.75, CRITICAL=1.0) plus a saturation curve (10 CRITICAL findings = max score of 100, more than that doesn’t increase). Geometric weighting prevents the gaming strategy of “fixing a bunch of LOW-level issues to inflate the score,” while the saturation curve prevents large legacy projects from getting inflated scores just because they have many findings. These designs make the security scanner itself quite reliable, but the security dimension’s scoring formula is a rough proxy \u2014 so the weight has to be conservative.<\/p>\n <\/p>\n <\/p>\n The standard pattern for a three-level cache system (memory \u2192 file \u2192 Redis) is “write to all layers on write, read from the fastest layer on read.” ai-analyze adds an extra behavior: read-backfill<\/strong>. When a read hits L2 (file cache), the system copies that data to L1 (memory). When it hits L3 (Redis), it backfills to both L1 and L2.<\/p>\n <\/p>\n This means the cache auto-warms up according to usage patterns<\/strong>. The first analysis goes through the full L3\u2192L2\u2192L1 chain; the second time, after hitting L2, it copies to L1; the third time, it hits L1 directly. No warmup steps needed, no manual migration \u2014 the cache naturally flows toward the faster layers with use.<\/p>\n <\/p>\n Redis also has an “absorptive” fault-tolerance design: when the connection fails, <\/p>\n The incremental analyzer has an additional layer of optimization: when merging cached results with new analysis results, it keeps deserialized Python objects in a memory-based <\/p>\n <\/p>\n The common thread across these five decisions: every “why not” is more worth telling than the “how.”<\/strong> Don’t expose modification operations (architectural constraint); don’t center on structure (actionability first); don’t let AI push for upgrades (counteracting innate tendencies); don’t give weak metrics high weight (honesty over precision); don’t let caches wait passively (proactive warming). These decisions aren’t code implementation details \u2014 they’re expressions of design philosophy. They determine that ai-analyze isn’t just another analysis tool, but a system with genuine engineering judgment.<\/p>\n <\/p>\n <\/p>\n <\/p>\nrename_symbol<\/code> and replace_symbol_body<\/code>, which can modify source code. Your code analyzer can rename symbols and replace function bodies, meaning a single misjudged analysis result could directly corrupt your code. The stdio client deliberately does not implement<\/strong> these two modification operations. The reason: the subprocess boundary naturally isolates write operations. stdin\/stdout pipes can only transmit query requests and return results \u2014 they cannot modify the filesystem across processes. This is architecture constraining capability \u2014 not “I don’t want to implement this,” but “I shouldn’t let you do this.”<\/p>\n\nclass StdioMCPClient:\n \"\"\"MCP JSON-RPC 2.0 over stdio transport\"\"\"\n\n async def connect(self):\n self.process = await asyncio.create_subprocess_exec(\n *self.server_command,\n stdin=asyncio.subprocess.PIPE,\n stdout=asyncio.subprocess.PIPE,\n )\n\n async def send_request(self, method, params=None):\n request = {\n \"jsonrpc\": \"2.0\",\n \"id\": self._next_id,\n \"method\": method,\n \"params\": params or {}\n }\n self.process.stdin.write(json.dumps(request).encode() + b\"\\n\")\n await self.process.stdin.drain()\n response = await self.process.stdout.readline()\n return json.loads(response.decode())\n<\/code><\/pre>\nDecision 2: The Merge Layer Uses AST as the Backbone \u2014 Serena Is Just Supplementary Fields<\/h2>\n
UnifiedAnalyzer<\/code> chose AST as the backbone. The reason: AST produces actionable metrics<\/strong> \u2014 “this function’s cognitive complexity is 15, exceeding the threshold of 10” is a finding you can act on immediately. “This class is referenced by 3 modules” is structural information, but it can’t tell you what to do. The merge logic loops primarily through AST’s file list, attaching Serena’s symbol data as supplementary attributes.<\/p>\nUnifiedSymbol<\/code> dataclass has a serena_data<\/code> field, but the merge code never fills it<\/strong>. This isn’t a bug \u2014 it’s an architectural placeholder. The current pipeline can already produce useful analysis reports using AST data alone; Serena data is a future enhancement point that doesn’t block current functionality. Zero runtime overhead for architectural foresight.<\/p>\nDecision 3: The AI Prompt Includes an “Anti-Hype” Instruction<\/h2>\n
temperature=0.3<\/code> (suggestions can have some creativity), Docker strategy and framework upgrades use temperature=0.2<\/code> (output must be conservative). The temperature gradient maps to consequence severity \u2014 a bad quality suggestion is merely annoying, a bad Docker configuration causes deployment failures, and a bad upgrade recommendation causes production incidents. The more severe the consequences, the lower the randomness.<\/p>\nDecision 4: Security Dimension Weight Is Only 0.15 \u2014 Because It’s a “Weak Metric”<\/h2>\n
overall = complexity \u00d7 0.25 + maintainability \u00d7 0.35 + reliability \u00d7 0.25 + security \u00d7 0.15<\/code><\/p>\nmax(0, 100 - code_smells \/\/ 2 * 10)<\/code> \u2014 dividing the number of code smells by 2 and using it as a rough proxy for security issues. The code author acknowledged this in a comment: “should actually use a dedicated security analysis tool.” The security score is an immature metric<\/strong>. Weighting it at 0.25 would let this rough proxy dominate the overall score, producing unreliable results. Giving a weak metric a low weight is more honest than giving it a high weight<\/strong> \u2014 you don’t want a denominator-divided-by-two approximation deciding whether a project can be deployed.<\/p>\nDecision 5: Cache Isn’t “Read From the Fastest Layer” \u2014 It’s “Auto-Migrate to Faster Layers on Read”<\/h2>\n
_client<\/code> is set to None<\/code>, and every subsequent operation checks if not self._client: return None<\/code>. If Redis completely goes down, no exceptions are thrown \u2014 the system silently degrades to L1+L2 and continues running. This doesn’t mean “Redis is optional” \u2014 it means “Redis failure should not block the analysis pipeline.”<\/p>\n_file_result_cache<\/code> dictionary. The MultiLevelCache stores serialized JSON, but the merge phase needs objects. Deserialization is an expensive operation \u2014 keeping object state in memory avoids the overhead of repeatedly reading from cache and deserializing. This is a third, unlabeled cache layer, existing specifically for the merge phase.<\/p>\nSource Code Navigation<\/h2>\n
\n\n
\n \nModule<\/td>\n Source File<\/td>\n Description<\/td>\n<\/tr>\n<\/thead>\n \n MCP Protocol Client<\/td>\n serena_stdio_client.py<\/a><\/td>\n Deliberately excludes modification operations for security boundary<\/td>\n<\/tr>\n \n MCP Direct Call Client<\/td>\n serena_client.py<\/a><\/td>\n In-process full-feature calls, performance-first<\/td>\n<\/tr>\n \n Unified Merge Layer<\/td>\n unified_analyzer.py<\/a><\/td>\n AST as backbone, Serena as supplement, serena_data placeholder<\/td>\n<\/tr>\n \n DeepSeek AI Integration<\/td>\n ai_enhanced_analyzer.py<\/a><\/td>\n Rules-first prompts, anti-hype instructions, temperature gradient<\/td>\n<\/tr>\n \n Quality Scoring<\/td>\n quality_score.py<\/a><\/td>\n Maintainability 0.35 highest, Security 0.15 low-weight honest proxy<\/td>\n<\/tr>\n \n Security Scanner<\/td>\n security_scanner.py<\/a><\/td>\n Severity-weighted geometric scoring + saturation curve<\/td>\n<\/tr>\n \n Three-Layer Cache<\/td>\n multi_level_cache.py<\/a><\/td>\n Read-backfill auto-warming, Redis absorptive fault tolerance<\/td>\n<\/tr>\n \n Incremental Analysis<\/td>\n incremental_analyzer.py<\/a><\/td>\n MD5 change detection + file cache progressive migration + memory object layer<\/td>\n<\/tr>\n \n AST Analyzer<\/td>\n ast_analyzer.py<\/a><\/td>\n Single tree traversal replacing 3 traversals, longest-task-first scheduling<\/td>\n<\/tr>\n \n Pipeline Orchestration<\/td>\n full_analyzer.py<\/a><\/td>\n Skip flags as cost-control grid<\/td>\n<\/tr>\n \n Docker Generation<\/td>\n docker_generator.py<\/a><\/td>\n Content detection over structure detection, Husky removal practical details<\/td>\n<\/tr>\n \n Plugin System<\/td>\n plugin_system.py<\/a><\/td>\n shared_data pipeline, namespace collision prevention<\/td>\n<\/tr>\n \n Exception System<\/td>\n exceptions.py<\/a><\/td>\n error_code + context dict, parseable log format<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n