包简介

README 文档

README

Cognitive Code Analysis is an approach to understanding and improving code by focusing on how human cognition interacts with code. It emphasizes making code more readable, understandable, and maintainable by considering the cognitive processes of the developers who write and work with the code.

"Human short-term or working memory was estimated to be limited to 7 ± 2 variables in the 1950s. A more current estimate is 4 ± 1 constructs. Decision quality generally becomes degraded once this limit of four constructs is exceeded."

Source: Human Cognitive Limitations. Broad, Consistent, Clinical Application of Physiological Principles Will Require Decision Support

A c# version and a Java version are also available.

Features 💎

Cognitive Complexity Analysis:
- Calculates a cognitive complexity score for each class and method
- Provides detailed cognitive complexity metrics
- Generate reports in various formats (JSON, CSV, HTML, Markdown, Checkstyle XML, JUnit XML, SARIF, GitLab Code Quality, GitHub Actions)
- Baseline comparison to track complexity changes over time
- Configurable thresholds and weights for complexity analysis
- Optional result cache for faster subsequent runs (must be enabled in config)
- Custom report generators
- Also provides Halstead Complexity Metrics (must be enabled in config)
- Also provides Cyclomatic Complexity Metrics (must be enabled in config)
Cognitive Complexity Churn Analysis to identify hotspots in the codebase
- Generate reports in various formats (JSON, CSV, HTML)
- Custom report generators

Installation ⚙️

composer require --dev phauthentic/cognitive-code-analysis

Running it 🧑‍💻

Create a project configuration file:

bin/phpcca init                  # interactive setup → creates phpcca.yaml in current directory
bin/phpcca init --silent         # non-interactive, all defaults
bin/phpcca init --path=/path/to/phpcca.yaml

When phpcca.yaml exists in the current working directory, analyse and churn load it automatically. Use --config to specify a different file.

Cognitive Complexity Analysis

bin/phpcca analyse <path-to-folder>
bin/phpcca analyse <path-to-folder> --config=custom.yaml  # explicit config overrides auto-discovery

Generate a report, supported types are json, csv, html, markdown, checkstyle, junit, sarif, gitlab-codequality, github-actions.

bin/phpcca analyse <path-to-folder> --report-type json --report-file cognitive.json

You can also pass a baseline file to compare the results to. The JSON report is used as baseline. The output will now show a delta if a value was changed.

bin/phpcca analyse <path-to-folder> --baseline cognitive.json

Finding Hotspots

Churn is a measure of how much code has changed over time. It helps to find the most changed and complex areas in your codebase, which are often the most error-prone and difficult to maintain. Read the Churn - Finding Hotspots documentation for more details.

Note that this requires a version control system (VCS) to be set up, such as Git.

bin/phpcca churn <path-to-folder>

Documentation 📚

Cognitive Complexity Analysis

Resources 🔗

These pages and papers provide more information on cognitive limitations and readability and the impact on the business.

Cognitive Complexity
- Cognitive Complexity Wikipedia
- Cognitive Complexity and Its Effect on the Code by Emanuel Trandafir.
- Human Cognitive Limitations. Broad, Consistent, Clinical Application of Physiological Principles Will Require Decision Support by Alan H. Morris.
- The Magical Number 4 in Short-Term Memory: A Reconsideration of Mental Storage Capacity by Nelson Cowan
- Neural substrates of cognitive capacity limitations by Timothy J. Buschman,a,1 Markus Siegel,a,b Jefferson E. Roy, and Earl K. Millera.
- Code Readability Testing, an Empirical Study by Todd Sedano.
- An Empirical Validation of Cognitive Complexity as a Measure of Source Code Understandability by Marvin Muñoz Barón, Marvin Wyrich, and Stefan Wagner.
Halstead Complexity
- Halstead Complexity
Cyclomatic Complexity
- Cyclomatic Complexity
Sonars Understandability / Cognitive Complexity
- {Cognitive Complexity} a new way of measuring understandability

Calculated Metrics

The tool computes complementary complexity metrics at class and method level. Optional metrics are enabled in phpcca.yaml.

Category	Metric	Description
Cognitive Complexity	Score	Weighted sum of structural inputs (lines, arguments, variables, branching, etc.); each input contributes logarithmically above a configurable threshold
Understandability	Score	Sonar-style control-flow complexity, separate from the weighted cognitive score; risk bands: 0–5 low, 6–10 medium, 11–15 high, 16+ very high
Cyclomatic Complexity	Score	Number of linearly independent paths: base 1 plus decision points and logical operators; risk bands: 1–5 low, 6–10 medium, 11–15 high, 16+ very high
Halstead	Volume	Implementation size derived from operators and operands (`N × log₂(n)`)
Halstead	Difficulty	Effort required to understand the code (`(n₁ / 2) × (N₂ / n₂)`)
Halstead	Effort	Mental effort to develop or maintain the code (`D × V`)

Examples 📖

Cognitive Metrics

Wordpress WP_Debug_Data

Class: \WP_Debug_Data
┌───────────────────┬──────────────┬───────────┬─────────┬─────────────┬────────────┬────────────┬────────────┬────────────┬────────────┐
│ Method Name       │ Lines        │ Arguments │ Returns │ Variables   │ Property   │ If         │ If Nesting │ Else       │ Cognitive  │
│                   │              │           │         │             │ Accesses   │            │ Level      │            │ Complexity │
├───────────────────┼──────────────┼───────────┼─────────┼─────────────┼────────────┼────────────┼────────────┼────────────┼────────────┤
│ check_for_updates │ 6 (0)        │ 0 (0)     │ 0 (0)   │ 0 (0)       │ 0 (0)      │ 0 (0)      │ 0 (0)      │ 0 (0)      │ 0          │
│ debug_data        │ 1230 (6.373) │ 0 (0)     │ 1 (0)   │ 105 (3.073) │ 20 (0.788) │ 58 (4.025) │ 3 (1.099)  │ 33 (3.497) │ 18.855     │
│ get_wp_constants  │ 144 (3.761)  │ 0 (0)     │ 1 (0)   │ 9 (0.875)   │ 0 (0)      │ 5 (1.099)  │ 1 (0)      │ 5 (1.609)  │ 7.345      │
│ get_wp_filesystem │ 60 (0)       │ 0 (0)     │ 1 (0)   │ 9 (0.875)   │ 0 (0)      │ 1 (0)      │ 1 (0)      │ 0 (0)      │ 0.875      │
│ get_mysql_var     │ 15 (0)       │ 1 (0)     │ 2 (0)   │ 2 (0)       │ 0 (0)      │ 1 (0)      │ 1 (0)      │ 0 (0)      │ 0          │
│ format            │ 60 (0)       │ 2 (0)     │ 1 (0)   │ 11 (1.03)   │ 0 (0)      │ 5 (1.099)  │ 1 (0)      │ 5 (1.609)  │ 3.738      │
│ get_database_size │ 14 (0)       │ 0 (0)     │ 1 (0)   │ 4 (0.336)   │ 1 (0)      │ 1 (0)      │ 1 (0)      │ 0 (0)      │ 0.336      │
│ get_sizes         │ 125 (3.512)  │ 0 (0)     │ 1 (0)   │ 14 (1.224)  │ 0 (0)      │ 9 (1.946)  │ 2 (0.693)  │ 5 (1.609)  │ 8.984      │
└───────────────────┴──────────────┴───────────┴─────────┴─────────────┴────────────┴────────────┴────────────┴────────────┴────────────┘

Doctrine Paginator

Class: Doctrine\ORM\Tools\Pagination\Paginator
┌───────────────────────────────────────────┬────────┬───────────┬─────────┬───────────┬──────────┬───────┬────────────┬───────────┬────────────┐
│ Method Name                               │ Lines  │ Arguments │ Returns │ Variables │ Property │ If    │ If Nesting │ Else      │ Cognitive  │
│                                           │        │           │         │           │ Accesses │       │ Level      │           │ Complexity │
├───────────────────────────────────────────┼────────┼───────────┼─────────┼───────────┼──────────┼───────┼────────────┼───────────┼────────────┤
│ __construct                               │ 10 (0) │ 2 (0)     │ 0 (0)   │ 1 (0)     │ 1 (0)    │ 1 (0) │ 1 (0)      │ 0 (0)     │ 0          │
│ getQuery                                  │ 4 (0)  │ 0 (0)     │ 1 (0)   │ 1 (0)     │ 1 (0)    │ 0 (0) │ 0 (0)      │ 0 (0)     │ 0          │
│ getFetchJoinCollection                    │ 4 (0)  │ 0 (0)     │ 1 (0)   │ 1 (0)     │ 1 (0)    │ 0 (0) │ 0 (0)      │ 0 (0)     │ 0          │
│ getUseOutputWalkers                       │ 4 (0)  │ 0 (0)     │ 1 (0)   │ 1 (0)     │ 1 (0)    │ 0 (0) │ 0 (0)      │ 0 (0)     │ 0          │
│ setUseOutputWalkers                       │ 6 (0)  │ 1 (0)     │ 1 (0)   │ 1 (0)     │ 1 (0)    │ 0 (0) │ 0 (0)      │ 0 (0)     │ 0          │
│ count                                     │ 12 (0) │ 0 (0)     │ 1 (0)   │ 1 (0)     │ 1 (0)    │ 1 (0) │ 1 (0)      │ 0 (0)     │ 0          │
│ getIterator                               │ 46 (0) │ 0 (0)     │ 2 (0)   │ 9 (0.875) │ 2 (0)    │ 3 (0) │ 2 (0.693)  │ 2 (0.693) │ 2.262      │
│ cloneQuery                                │ 13 (0) │ 1 (0)     │ 1 (0)   │ 3 (0.182) │ 0 (0)    │ 0 (0) │ 0 (0)      │ 0 (0)     │ 0.182      │
│ useOutputWalker                           │ 8 (0)  │ 1 (0)     │ 2 (0)   │ 1 (0)     │ 1 (0)    │ 1 (0) │ 1 (0)      │ 0 (0)     │ 0          │
│ appendTreeWalker                          │ 11 (0) │ 2 (0)     │ 0 (0)   │ 1 (0)     │ 0 (0)    │ 1 (0) │ 1 (0)      │ 0 (0)     │ 0          │
│ getCountQuery                             │ 25 (0) │ 0 (0)     │ 1 (0)   │ 4 (0.336) │ 1 (0)    │ 2 (0) │ 1 (0)      │ 1 (0)     │ 0.336      │
│ unbindUnusedQueryParams                   │ 17 (0) │ 1 (0)     │ 0 (0)   │ 6 (0.588) │ 0 (0)    │ 1 (0) │ 1 (0)      │ 0 (0)     │ 0.588      │
│ convertWhereInIdentifiersToDatabaseValues │ 11 (0) │ 1 (0)     │ 1 (0)   │ 5 (0.47)  │ 1 (0)    │ 0 (0) │ 0 (0)      │ 0 (0)     │ 0.47       │
└───────────────────────────────────────────┴────────┴───────────┴─────────┴───────────┴──────────┴───────┴────────────┴───────────┴────────────┘

Reporting Issues 🪲

If you find a bug or have a feature request, please open an issue on the GitHub repository.

Especially the AST-parser used under the hood to analyse the code might have issues with certain code constructs, so please provide a minimal example that reproduces the issue.

License ⚖️

Copyright Florian Krämer

Licensed under the GPL3 license.

phauthentic/cognitive-code-analysis 适用场景与选型建议

phauthentic/cognitive-code-analysis 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 14.2k 次下载、GitHub Stars 达 51，最近一次更新时间为 2024 年 09 月 21 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 phauthentic/cognitive-code-analysis 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 phauthentic/cognitive-code-analysis 我们能提供哪些服务？

定制开发 / 二次开发

基于 phauthentic/cognitive-code-analysis 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

phauthentic/cognitive-code-analysis

包简介