Archon One - code analysis platform

These details have not been verified by PyPI

Project description

Archon One - Enterprise Code Analysis, Security Auditing & Repository Intelligence Platform

Archon One is a powerful, offline-first code analysis, security auditing, and repository intelligence platform. It processes software projects locally to compile advanced metrics, detect security hazards, inspect structural characteristics, map contributor profiles, and compute repository health indices—instantly and privately.

This manual documents the architecture, configuration parameters, modules, commands, metrics formulas, and workflows of Archon One.

Project Overview
Motivation
Why Archon One
Key Features
Technology Stack
System Architecture
Repository Structure
Installation
Quick Start
CLI Commands
Scan Workflow
Output Structure
Report Formats
HTML Reports
Settings Manager
Configuration
Module Documentation
- Module 01: Code Metrics
- Module 02: Security
- Module 03: Code Analysis
- Module 04: Contributor Analysis
- Module 05: Repository Intelligence
Metrics Reference
Module-by-Module Output & Reports Breakdown
Security Rules Reference
Detailed Report Descriptions & Metrics Mechanics
Configuration Reference
Performance & Lexical Comment Parser Grammar
Supported Languages
Limitations
FAQ
Development Guide
Contributing
Roadmap
Appendix: Sample Scanner CLI Output & Real Scans Mock Example
Appendix A: Detailed Output Schemas and Sample Tables
Appendix B: Module-by-Module Processing Mechanics
Appendix C: Detailed File Schemas & Fields Reference Catalog (50/50 Reports)
Appendix D: Scores Reference
Appendix E: Thresholds Reference
Appendix F: CLI Exit Codes and Return Behavior
Appendix G: Glossary of Terms
Appendix H: Troubleshooting Guide
Appendix I: Version Compatibility Matrix
Appendix J: Complete Settings Manager Property Table
Appendix K: Master Report Cross-Reference Table
Appendix L: Security Detection Rules Complete Reference
Appendix M: Supported Languages Complete Reference
Credits & Developer Details
License

1. Project Overview

Archon One performs source code scanning, structure auditing, and contributor attribution entirely offline. By analyzing files, syntax trees, patterns, and Git transaction history locally, it generates structured TXT tables, JSON datasets, Markdown files, and standalone interactive HTML reports without transmitting code to cloud APIs.

2. Motivation

Modern software development depends on cloud-based code analysis, security scanners, and metrics tools. However, transmitting proprietary source code to external servers presents intellectual property risk, data residency issues, and bandwidth usage constraints. Archon One was built to address these bottlenecks by offering a robust, multi-language code analysis suite that runs completely client-side.

3. Why Archon One

Zero-Dependency Security: Audits credentials, private keys, and dependencies without internet connections.
Dynamic Adaptability: Features an interactive Settings Manager to fine-tune metrics thresholds on-the-fly.
Git Intelligence: Traces commit activity, directory ownership, knowledge distribution, and bus factors directly from local repositories.
Multi-Format Exporting: Automatically writes ASCII text tables, JSON data payloads, Markdown reports, and stand-alone interactive HTML pages.

4. Key Features

Lexical Parser: Distinguishes code from comments, block docstrings, and strings across 15+ languages.
Vulnerability Checks: Audits hardcoded secrets, weak cryptographic functions, unsafe configurations, and insecure APIs.
Structure Metrics: Maps cyclomatic complexity, cognitive nesting depth, duplications, and circular references.
Unified HTML Viewer: Combines individual reports into a single, offline-first HTML page featuring interactive search-hit badges.

5. Technology Stack

Core Engine: Python 3.11+ (leveraging standard libraries and high-performance algorithms)
CLI Framework: Typer (powered by Click)
Web UI (Settings): HTML5, CSS3, Vanilla JavaScript, embedded HTTP Server
Report Rendering: Tabulate, custom HTML template engines

6. System Architecture

graph TD
    A[CLI / Typer Commands] --> B[Repository Scanner Core]
    C[Settings Server / API] --> B
    B --> D[Code Metrics Module 01]
    B --> E[Security Module 02]
    B --> F[Code Analysis Module 03]
    B --> G[Contributor Analysis Module 04]
    B --> H[Repository Intelligence Module 05]
    D & E & F & G & H --> I[Multi-Format Reporter]
    I --> J[TXT ASCII Tables]
    I --> K[JSON Data Files]
    I --> L[Markdown Documents]
    I --> M[Standalone HTML Reports]
    I --> N[Unified index.html Report]

7. Repository Structure

archonone/
│
├── src/
│   └── archon/
│       ├── __init__.py
│       ├── cli.py                    # CLI command registration and setup
│       │
│       ├── core/
│       │   ├── __init__.py
│       │   ├── scanner.py            # Local directory traverser and ignorer
│       │   ├── html_generator.py     # Standalone report generator
│       │   └── unified_generator.py  # Single HTML file aggregator
│       │
│       ├── modules/
│       │   ├── __init__.py
│       │   ├── code_metrics.py       # LOC and documentation parser (M01)
│       │   ├── security.py           # Hardcoded secrets and IP auditor (M02)
│       │   ├── code_analysis.py      # Complexity and code smells analyzer (M03)
│       │   ├── contributor_analysis.py # Git commits and ownership tracer (M04)
│       │   ├── repository_intelligence.py # Health grade and technical debt (M05)
│       │   └── settings_manager.py   # Settings manager web server
│       │
│       └── templates/
│           └── settings.html         # Settings dashboard UI page
│
├── tests/
│   ├── test_code_analysis.py
│   ├── test_contributor_analysis.py
│   ├── test_repository_intelligence.py
│   └── test_settings_manager.py
│
├── pyproject.toml
└── README.md

8. Installation

From PyPI

To install the production-ready package directly from PyPI, run:

pip install archon-one

From Source (Development Setup)

Clone the repository and install it in editable mode with development dependencies:

git clone https://github.com/v3ravani/archonone.git
cd archonone
pip install -e ".[dev]"

Packaging & Build Instructions

For developers wanting to package and distribute Archon One:

Ensure build and twine are installed:
```
pip install build twine
```
Build the source distribution (sdist) and binary wheel distribution:
```
python -m build
```
Check package integrity using Twine:
```
twine check dist/*
```
Release and publish to PyPI:
```
twine upload dist/*
```

9. Quick Start

Run a full scan on the current directory:

archon scan

10. CLI Commands

Command	Description	Arguments	Options	Example
`archon scan`	Scan repository	`[project_path]`	`-o`, `--output`	`archon scan -o C:\Reports`
`archon git`	Clone remote GitHub repo and scan	`<repo_url>`	`-o`, `--output`	`archon git https://github.com/user/repo.git`
`archon report`	Compile to unified HTML	`[scan_path]`	None	`archon report archon-one/latest`
`archon config`	Start Settings server	None	`--port`	`archon config --port 8085`
`archon config reset`	Reset config to default	None	None	`archon config reset`
`archon help`	Display runner guide	None	None	`archon help`
`archon about`	Print developer details	None	None	`archon about`

11. Scan Workflow

sequenceDiagram
    participant C as CLI (scan)
    participant S as Scanner Core
    participant I as Ignorer System
    participant M as Module Runners
    participant R as Reporter Pipeline
    
    C->>S: Instantiate scan(path)
    S->>I: Retrieve active ignore rules
    I-->>S: Return filtered file list
    S->>M: Dispatch filtered files to active modules
    M->>M: Compute metrics, detect security rules & scores
    M-->>S: Return scan metrics dict
    S->>R: Send merged results dictionary
    R->>R: Generate TXT, JSON, MD, HTML and unified reports
    R-->>C: Complete scan and print summary table

12. Output Structure

Scans generate reports grouped by module names under the output directory:

archon-one/
└── 2026-07-10_00-24-14/
    ├── index.html                           # Unified single-file report
    │
    ├── 01_metrics/
    │   ├── 01_repository_summary.txt        # Metrics summary tables
    │   ├── 01_repository_summary.json       # Metrics summary raw JSON
    │   ├── 01_repository_summary.md         # Metrics summary MD file
    │   └── report.html                      # Standalone Metrics Explorer
    │
    ├── 02_security/
    │   ├── 01_security_summary.txt
    │   ├── 01_security_summary.json
    │   ├── 01_security_summary.md
    │   └── report.html
    ...

13. Report Formats

.txt: Formatted ASCII tables for console reading.
.json: Machine-readable structured objects.
.md: Markdown tables wrapped inside code blocks for hosting on GitHub.
.html: Standalone visual report dashboards.

14. HTML Reports

Each module folder includes report.html which is completely standalone and works 100% offline. It reads data from its corresponding JSON report files.

Key Interactive Features:

Instant Search: Filters rows instantly based on keywords.
Live Badges: Computes search hit counts and renders badges (e.g. (5)) next to sections in the sidebar on-the-fly.
Column Sorting & Pagination: Sorts ascending/descending by clicking on columns, featuring custom page navigation buttons.
Export Utility: Exports data immediately into CSV, Markdown, JSON, or copy to the clipboard.

15. Settings Manager

Run archon config to launch the offline dashboard page at http://localhost:8085. It divides settings into 9 configurations:

General: Project name, Output Folder, Timestamp preferences, and Scan paths.
Scan Modules: Enable/disable metrics, security, complexity, or contributor trackers.
Output: Formats selection (TXT, JSON, MD, HTML), tables mode, and row limits.
Ignore Rules: Directories, Extensions, Max sizes, and Binary filters.
Thresholds: Cyclomatic complexity, max parameters, imports limits, and comments density.
Security: Severities bounds, secrets bounds, and scanning patterns.
Performance: Thread pools size, memory usage boundaries, and file caching limits.
Advanced: Logging levels, validation checks, and automatic logs cleanup.
About: System version details.

16. Configuration

Configure scanner rules inside archon-config.json placed in your repository root:

View default configuration schema

{
  "general": {
    "project_name": "Archon One Project",
    "output_folder": "archon-one",
    "create_timestamp_folder": true,
    "default_scan_location": ".",
    "auto_load_previous_config": true,
    "auto_save_settings": true,
    "auto_open_report_folder": false,
    "enable_scan_summary": true,
    "max_scan_history": 10,
    "language_detection": "auto"
  },
  "modules": {
    "code_metrics": true,
    "security": true,
    "code_analysis": true,
    "contributor_analysis": true,
    "repository_intelligence": true,
    "run_selected_only": false
  },
  "output": {
    "txt": true,
    "json": true,
    "md": true,
    "output_tables": "ASCII",
    "sort_reports_by": "Severity",
    "max_rows_per_report": 100,
    "show_empty_reports": false,
    "compress_reports": false,
    "overwrite_existing_reports": true
  },
  "ignore_rules": {
    "ignore_directories": ["node_modules", ".git", "venv", "build", "dist", "coverage"],
    "ignore_files": ["*.min.js", "*.log", "*.lock"],
    "ignore_extensions": ["png", "jpg", "gif", "pdf", "zip"],
    "ignore_hidden_files": true,
    "ignore_hidden_directories": true,
    "ignore_binary_files": true,
    "ignore_generated_files": true,
    "ignore_vendor_libraries": true,
    "ignore_test_files": false,
    "ignore_documentation": false,
    "ignore_empty_files": true,
    "ignore_large_files": true,
    "max_file_size": 10485760,
    "max_directory_depth": 20
  },
  "thresholds": {
    "max_function_length": 100,
    "max_class_length": 500,
    "max_file_length": 1000,
    "max_parameters": 5,
    "max_cyclomatic_complexity": 15,
    "max_cognitive_complexity": 15,
    "max_nesting_depth": 5,
    "max_line_length": 120,
    "max_duplicate_percentage": 5.0,
    "max_duplicate_lines": 10,
    "min_comment_density": 10.0,
    "min_maintainability_score": 50.0,
    "max_technical_debt_score": 50.0,
    "max_dependency_depth": 5,
    "max_import_count": 20,
    "large_file_warning": 2097152,
    "critical_file_size": 5242880,
    "max_folder_size": 104857600
  },
  "security": {
    "enable_secret_detection": true,
    "enable_config_scan": true,
    "enable_dependency_scan": true,
    "enable_credential_scan": true,
    "enable_dangerous_function_detection": true,
    "enable_hardcoded_ip_detection": true,
    "enable_base64_detection": true,
    "enable_weak_crypto_detection": true,
    "enable_regex_scan": true,
    "enable_environment_scan": true,
    "minimum_severity": "Low",
    "max_secret_length": 128,
    "ignore_example_secrets": true
  },
  "performance": {
    "max_worker_threads": 4,
    "max_memory_usage": 1024,
    "max_files": 10000,
    "max_scan_time": 600,
    "enable_cache": true,
    "cache_size": 1000,
    "incremental_scan": false,
    "skip_unchanged_files": false,
    "lazy_loading": false,
    "scan_mode": "full"
  },
  "advanced": {
    "enable_debug_logs": false,
    "verbose_logging": false,
    "save_scan_logs": true,
    "auto_cleanup_old_reports": false,
    "cleanup_after_days": 30,
    "max_report_history": 50,
    "validate_config_before_scan": true
  }
}

17. Module Documentation

Module 01: Code Metrics

Computes lines of code (LOC), file sizes, language volumes, comment density, and directory complexity.

Workflow: Traverses files, detects format, and executes lexical comment parsing.
Algorithms: Stateful comment tokenizers matching multi-line and single-line syntax.
Generated Reports: Repository Summary, File Metrics, Directory Metrics, Language Metrics, Documentation Coverage, Extension Metrics, Size Analysis, Project Structure, Scan Statistics, Metadata, Dependencies.

Module 02: Security

Audits repositories for private keys, vulnerabilities, credentials, and misconfigurations.

Workflow: Performs line-by-line checks against regular expression rulesets and insecure method indices.
Vulnerabilities detected: Committed SSH keys, AWS tokens, hardcoded IP configurations, weak crypto hashing, dangerous functions (e.g. eval), hardcoded Authorization headers/tokens, and XML External Entity (XXE) vulnerabilities.
Production-Grade Security Features:
1. License Compliance Scanner: Detects license files and matches GPL, LGPL, AGPL, MIT, Apache, BSD, and Proprietary keywords to warn about commercial copyleft compatibility.
2. File Permission Audit: Analyzes file permission flags for world-writable scripts or incorrect execution flags on scripts (.sh, .py).
3. Sensitive File Detector: Scans repository path structures for committed environment configuration keys (.env, .env.production), certificates, databases, and configuration backups (id_rsa, id_ed25519, .pem, .p12, .keystore, credentials.json, firebase-admin.json, aws-credentials, docker-compose.override.yml).
4. Docker & Container Security Scan: Evaluates container layouts (Dockerfile, docker-compose.yml) for exposed base tags, missing HEALTHCHECK tags, privileged container settings, or root executing permissions.
5. CI/CD Security Scanner: Scans GitHub Actions pipelines (.github/workflows/), GitLab CI configuration, or Azure pipelines workflows for plaintext secrets or unpinned workflows.
6. Git Ignore Security Audit: Compares active repository file extensions against .gitignore to alert on tracked configurations or credentials.
7. Logging Security Analysis: Flags logger output lines (logger.info, console.log) containing variable references to passwords, tokens, hashes, or credentials to prevent leaks.
8. Unsafe File Operation Detection: Detects potentially vulnerable filesystem paths or calls (recursive directories wipe, path string concatenation vulnerabilities).
9. Security Best Practices Audit: Inspects the workspace root for missing lock files, license declarations, environment configs, or gitignore specifications.
10. Cryptographic Key Detection: Audits and classifies committed public, private, or certificate keys (-----BEGIN ... KEY----- or -----BEGIN CERTIFICATE-----).
Reports: Summary, Secrets, Credentials, Insecure Functions, Web Security, Cryptography Checks, Dependency Vulnerabilities, Configurations, Sensitive Files, Metadata.

Module 03: Code Analysis

Measures cyclomatic complexity, cognitive nesting levels, code duplication, and architectural smells.

Workflow: Builds abstract syntax mappings and measures nested block logic.
Smells detected: God Function, Lazy Class, Message Chains, Empty catch/except, Empty Classes, and Deep Nesting.
Reports: Quality Summary, Complexity Analysis, Function Analysis, Class Analysis, Dependency Mapping, Duplicated Code, Architectural Integrity, Code Smells, Maintainability Index, Metadata.

Module 04: Contributor Analysis

Traces contribution transactions, code ownership, activity history, and knowledge silos.

Workflow: Inspects local Git transaction logs using git log and attributes line counts.
Reports: Contributor Summary, Contributor Statistics, Commit Metrics, File Ownership, Collaboration analysis, Knowledge silos, Productivity mapping, Repository Activity, Bus Factor / Risk Analysis, Metadata.

Module 05: Repository Intelligence

Aggregates quality indices to compute health score, overall grade, and prioritized recommendations.

Workflow: Consolidates scores across Modules 01-04.
Reports: Health rating, Hotspot analysis, Technical debt breakdown, Scalability indices, Testing analysis, Refactoring opportunities, Change impact analysis, Risk prioritization, Insights list, Metadata.

18. Metrics Reference

Metric	Module	Description	Formula	Unit	Threshold	Importance
LOC	Code Metrics	Lines of Code	`Total Lines - Blank Lines`	Lines	None	High
Comment Density	Code Metrics	Comment coverage percentage	`(Comment Lines / LOC) * 100`	%	`min_comment_density`	High
Cyclomatic Complexity	Code Analysis	Logical pathways complexity	`Edges - Nodes + 2*Parts`	Paths	`max_cyclomatic_complexity`	Critical
Maintainability Index	Code Analysis	Ease of codebase support	`171 - 5.2ln(HV) - 0.23CC - 16.2*ln(LOC)`	Index	`min_maintainability_score`	Critical
Bus Factor	Contributor	Minimum engineers containing core knowledge	Calculated Git ownership	Devs	None	Critical
Technical Debt Hours	Repo Intelligence	Hours needed to repair smells	`Smells * Hours_Per_Smell`	Hours	`max_technical_debt_score`	High

19. Module-by-Module Output & Reports Breakdown

The following tables describe every output report generated by the scanner modules.

Module 01 - Code Metrics Outputs

Filename	Format	Purpose	Columns / Contents	Used By
`01_repository_summary`	TXT, JSON, MD	Broad overview of code statistics	Total files, total LOC, directories, total size, comment densities	Module 05
`02_file_metrics`	TXT, JSON, MD	File-by-file detail breakdown	File, Language, Physical LOC, Logical LOC, Comment Lines, Density	Module 03
`03_directory_metrics`	TXT, JSON, MD	Folder aggregations	Directory, File Count, Total LOC, Average Size, Subdirs	Module 05
`04_language_metrics`	TXT, JSON, MD	Language volumes	Language, File Count, Total LOC, Percentage	Module 05
`05_documentation_metrics`	TXT, JSON, MD	Docs coverage checks	File, Total Lines, Docstring Lines, Comment Lines, Ratio	Module 03
`06_extension_statistics`	TXT, JSON, MD	Extensions inventory	Extension, Category, Count, Bytes	None
`07_size_analysis`	TXT, JSON, MD	Size band distributions	Size Range, File Count, Total Bytes	Module 05
`08_project_structure`	TXT, JSON, MD	Folder nesting metrics	Top-level folders, Deepest directory, Max depth	Module 05
`09_scan_statistics`	TXT, JSON, MD	Execution logging parameters	Start, End, Speed, Files Ignored, Warns	None
`10_metadata`	TXT, JSON, MD	System context parameters	Operating System, Python Version, Scan ID	None
`11_dependencies`	TXT, JSON, MD	External imports tracker	Module, Import Name, Target Source	Module 03

Module 02 - Security Outputs

Filename	Format	Purpose	Columns / Contents	Used By
`01_security_summary`	TXT, JSON, MD	Consolidated findings summary	Total critical, total high, medium, low issues counts	Module 05
`02_secrets`	TXT, JSON, MD	Log of exposed secrets	File, Line, Severity, Secret Type, Recommendation	Module 05
`03_credentials`	TXT, JSON, MD	Credentials audit	File, Line, User, Match Pattern, Insecure details	Module 05
`04_insecure_functions`	TXT, JSON, MD	Insecure routines audit	File, Line, Function Name, Severity, Insecure pattern	Module 05
`05_web_security`	TXT, JSON, MD	Web vulnerabilities list	File, Line, Hazard Type, Risk rating, Recommendation	Module 05
`06_crypto_security`	TXT, JSON, MD	Insecure cryptographies audit	File, Line, Cryptographic routine, Severity, Patch action	Module 05
`07_dependency_security`	TXT, JSON, MD	Outdated package checks	Package name, Scanned version, Max severity, Vulnerability detail	Module 05
`08_configuration_security`	TXT, JSON, MD	Exposed setups audit	File, Setting Key, Hazard, Recommendation	Module 05
`09_sensitive_files`	TXT, JSON, MD	Files exposure audit	File Path, Asset category, Severity, Hazard details	Module 05
`10_scan_metadata`	TXT, JSON, MD	Security runner context	Scan ID, Minimum severity configuration, Audit datetime	None

Module 03 - Code Analysis Outputs

Filename	Format	Purpose	Columns / Contents	Used By
`01_quality_summary`	TXT, JSON, MD	Overall quality metrics summary	Average complexity, average nesting, average duplicate lines	Module 05
`02_complexity_analysis`	TXT, JSON, MD	Cyclomatic complexities audit	File, Total Functions, Max Complexity, Average Complexity	Module 05
`03_function_analysis`	TXT, JSON, MD	Function statistics	Function name, File, Line, Length (LOC), Parameters count	Module 05
`04_class_analysis`	TXT, JSON, MD	Class structures metrics	Class name, File, Line, Length (LOC), Methods count	Module 05
`05_dependency_analysis`	TXT, JSON, MD	Imports metrics	File, Internal dependencies count, External dependencies count	Module 05
`06_duplication_analysis`	TXT, JSON, MD	Copy-pasted code search	Matching block, File A, File B, Lines count, Percentage	Module 05
`07_architecture_analysis`	TXT, JSON, MD	Circular dependencies audit	File A, File B, Target cycle pathway, Hazard details	Module 05
`08_code_smells`	TXT, JSON, MD	Code smells details	File, Line, Smell type (e.g. Long Parameter List), Severity	Module 05
`09_maintainability`	TXT, JSON, MD	Halstead metrics	File, Volume, Vocabulary, Maintainability Index	Module 05
`10_scan_metadata`	TXT, JSON, MD	Runner metadata	Scan ID, Project name, Rules version	None

Module 04 - Contributor Analysis Outputs

Filename	Format	Purpose	Columns / Contents	Used By
`01_contributor_summary`	TXT, JSON, MD	Contributions metrics summary	Active devs counts, total commits, bus factor score	Module 05
`02_contributor_statistics`	TXT, JSON, MD	Dev-by-dev metrics	Contributor Name, Commit Count, Lines Added, Lines Deleted	Module 05
`03_commit_analysis`	TXT, JSON, MD	Commit timeline	Commit hash, Contributor, Date, Message, Changed lines	Module 05
`04_file_ownership`	TXT, JSON, MD	Ownership tracing	File Path, Primary Owner, Owner %, Co-Authors count	Module 05
`05_collaboration_analysis`	TXT, JSON, MD	Dev-to-dev intersection checks	Dev A, Dev B, Intersecting files count, Overlap ratio	Module 05
`06_knowledge_distribution`	TXT, JSON, MD	Silo identification	Directory Path, Devs count, Primary owner %	Module 05
`07_productivity_analysis`	TXT, JSON, MD	Lines edit ratios	Contributor, Monthly active status, Code edits count	Module 05
`08_repository_activity`	TXT, JSON, MD	Scans timeline	Month, Commits count, active contributors	Module 05
`09_risk_analysis`	TXT, JSON, MD	Contributor dependency checks	Contributor, Single-owner lines count, Silent files count	Module 05
`10_scan_metadata`	TXT, JSON, MD	Contributor run metadata	Git version, commit history logs timeframe	None

Module 05 - Repository Intelligence Outputs

Filename	Format	Purpose	Columns / Contents	Used By
`01_repository_health`	TXT, JSON, MD	Core repository scores	Health Score %, Overall Grade, Score breakdowns	None
`02_hotspot_analysis`	TXT, JSON, MD	Complex edits mapping	File Path, Edit count, Complexity, Hotspot score	None
`03_technical_debt`	TXT, JSON, MD	Technical debt tracking	Smell count, Refactor hours needed, Estimated days	None
`04_scalability_analysis`	TXT, JSON, MD	Growth metrics	Language ratios, File count growth estimation, Growth score	None
`05_testing_analysis`	TXT, JSON, MD	Tests coverages checks	Test files count, main source files count, Test ratio %	None
`06_refactoring_opportunities`	TXT, JSON, MD	Refactoring prioritizations	File, Suggestion type, Risk score, Recommended action	None
`07_change_impact_analysis`	TXT, JSON, MD	Blast radius mapping	File, Dependent files count, Blast radius score	None
`08_risk_prioritization`	TXT, JSON, MD	Risk index mapping	File, Security score, Maintainability score, Risk priority	None
`09_repository_insights`	TXT, JSON, MD	Overall findings suggestions	Metric category, Observation, Recommendation	None
`10_scan_metadata`	TXT, JSON, MD	Intelligence run metadata	Consolidated run details, Combined module IDs	None

20. Security Rules Reference

View audit security rules list

Rule Key	Severity	Pattern / Check Description	Remediation Action
Private Key	Critical	Matches private key block headers	Revoke certificate, delete from history
AWS Token	Critical	`AKIA[0-9A-Z]{16}` pattern	Invalidate access keys
Hardcoded IP	Medium	Detects hardcoded IP parameters	Use environment variables
Dangerous Eval	High	Usage of `eval()` or `exec()`	Refactor using safe parsing
Weak Hashing	Medium	Matches `md5` or `sha1` routines	Upgrade algorithm to SHA-256 or bcrypt
Insecure Crypt	High	Usage of weak algorithms (DES, RC4)	Refactor with AES-GCM encryption
Sensitive Files	Medium	Leftover `.env`, `.pem`, or backup database files	Clean directory paths
Auth Token	Critical	`Authorization` headers containing plaintext keys	Invalidate keys and retrieve them dynamically
XXE Vulnerability	Medium	XML parsers imported without safe entity settings	Use `defusedxml` to parse files safely

21. Detailed Report Descriptions & Metrics Mechanics

1. `01_repository_summary`

Aggregates general stats for the repository.

Metric Definitions:
- LOC: Physical lines of text, excluding blank lines.
- Comment Density: Percentage of lines containing comments or docstrings.
Interpretation: A comment density of < 10% raises code smell alerts under Module 03. High line counts on single modules indicate that modular refactoring is needed.

2. `02_file_metrics`

Calculates details for every single file.

Fields:
- File: Relative file path.
- Language: Scanned programming language.
- Logical LOC: Count of logical code instructions.
Interpretation: Sort by LOC descending to identify oversized files that violate class length settings.

3. `02_secrets`

Tracks hardcoded credentials.

Fields:
- Severity: Rated Critical or High.
- Secret Type: AWS keys, Slack Webhooks, or generic passwords.
Interpretation: Critical issues block scans if advanced pre-commit integration is enabled.

4. `02_complexity_analysis`

Parses logical branching.

Fields:
- Cyclomatic Complexity: Number of linearly independent paths.
- Cognitive Nesting: Cumulative nesting depth level.
Interpretation: Any function with complexity > 15 raises logical smell warnings.

5. `02_contributor_statistics`

Computes individual developer commits stats.

Fields:
- Contributor: Git author name.
- Lines Added: Cumulative insertions.
Interpretation: High ownership percentages (> 80%) on core folders raise Bus Factor risks.

6. `01_repository_health`

Consolidates overall scores.

Calculation Formula: $$\text{Health} = (\text{Maintainability} \times 0.40) + (\text{Quality} \times 0.30) + (\text{Security} \times 0.20) + (\text{Ownership} \times 0.10)$$
Interpretation: Grades A (>= 90%) to F (< 50%) indicate overall software codebase quality.

22. Configuration Reference

View configuration properties list

Property Path	Type	Default	Description	Validation
`general.project_name`	String	`"Archon One Project"`	Friendly label for scans config	Required
`general.output_folder`	String	`"archon-one"`	Save folder (supports absolute paths)	Required
`thresholds.max_cyclomatic_complexity`	Integer	`15`	Cyclomatic paths warning limit	`> 0`
`thresholds.min_comment_density`	Float	`10.0`	Comments density alert boundary	`0.0` to `100.0`
`security.minimum_severity`	String	`"Low"`	Severity filter cutoff	Critical/High/Medium/Low
`performance.max_worker_threads`	Integer	`4`	Maximum worker threads pool	`1` to `32`

23. Performance & Lexical Comment Parser Grammar

Token State Engine: Uses regular expression buffers to skip string literals (e.g. "hello # world") and count actual lines matching # or //.
Performance benchmarks: Processes up to 10,000 files in under 15 seconds using thread pools and cache tables tracking modify times.

24. Supported Languages

Language	Supported	Parser Type	Features Scanned
Python	Yes	AST / Regex	Comments, functions, complexity, security checks
JavaScript	Yes	Regex	Code-comment density, credentials scan, dangerous APIs
Java	Yes	Regex	Comments, functions parsing, security
C++	Yes	Regex	Single/Multi-line comments, file metrics
HTML/CSS	Yes	Regex	Size analysis, style properties, credentials

25. Limitations

Pattern Matching: Does not compile code. High-obfuscation security gaps might require runtime analysis.
Git History Requirement: Contributor analysis requires a valid local .git repository folder to read commits history.

26. FAQ

View 30+ Troubleshooting FAQ items

1. How does the lexical comment parser handle block string docstrings?

The python parser flags block docstrings as documentation comments, adding them directly to the documentation line count.

2. Can I specify an absolute path to save reports?

Yes. Go to settings or run scan with -o C:\MyCustomOutput.

3. How do I configure custom directories to be ignored?

Edit the ignore_rules.ignore_directories array in your archon-config.json file.

4. What is the difference between cyclomatic and cognitive complexity?

Cyclomatic complexity counts branching paths. Cognitive complexity measures nesting structures.

5. Why are no Git metrics showing in my contributor reports?

Ensure the scanned folder is a valid Git repository containing a .git folder and has at least one commit.

6. Can I disable specific scanning modules?

Yes. Turn off the toggle for the module inside the Settings manager dashboard.

7. How does the settings server save changes?

Saves changes directly to archon-config.json inside your project root.

8. Does Archon One run online?

No. Archon One functions 100% offline.

9. What triggers a circular dependency smell?

Two or more modules importing each other directly or transitively.

10. How do I reset all configurations?

Run archon config reset or click Restore Defaults.

11. Can I import/export configuration files?

Yes, using the Import/Export buttons in the Settings Manager header.

12. How do I view unified report explorer pages?

Run archon report after scanning to generate a unified index.html.

13. How does search matching work in HTML reports?

It filters tables instantly via JS string lookup.

14. What browsers are supported?

Chrome, Firefox, Safari, Edge.

15. What unit does comment density use?

Percentage (%).

16. What is the default port for Settings Manager?

8085.

17. How do I configure the minimum security finding severity?

Update security.minimum_severity key to "Medium" or "High".

18. Does Archon One parse compiled binaries?

No.

19. Can I run incremental scans?

Yes, toggle performance.incremental_scan in settings.

20. How is repository health score computed?

Weighted sum of Maintainability (40%), Quality (30%), Security (20%), and Ownership (10%).

21. How do I shutdown the Settings server?

Click "Shutdown Server" in the Settings Manager header or press Ctrl+C in the CLI.

22. What happens if a scan takes too long?

It auto-terminates after performance.max_scan_time limit is hit.

23. What are the exit codes for CLI?

0 for success, 1 for failures.

24. Does the tool support YAML files?

Yes, reads them for configuration audit checks.

25. How do I add custom rules?

You can contribute by adding regular expressions to security.py.

26. Why was my file skipped?

It was ignored due to size, hidden properties, format constraints, or ignore configurations.

27. Can I scan subfolders only?

Yes, specify the path to that subfolder as a scan argument.

28. What formats are available for table data exports?

CSV, JSON, Markdown, and Clipboard Copy.

29. Can recruiters use this to inspect portfolios?

Yes. It builds comprehensive insights into engineering ownership and structural complexity.

30. How is the Bus Factor calculated?

Finds the minimal number of engineers whose combined edits cover more than 50% of the repository.

31. What absolute paths formatting should Windows systems utilize?

Always format paths using absolute backslashes on Windows command prompt sessions e.g., archon scan C:\Users\Username\Project.

32. Does the Single-File unified index.html load external components?

No. All formatting logic, scripts, and aggregated JSON datasets are embedded directly inside index.html.

33. Can I run config and scans concurrently?

Yes. The settings API reads and writes to archon-config.json synchronously. Scans retrieve configuration rules dynamically at launch.

27. Development Guide

Adding a New Scanner Module Step-by-Step

To extend Archon One's functionality with a new custom module, follow this standard pattern:

Configure Module Toggle: Add a toggle option inside the default configuration parameters in src/archon/modules/settings_manager.py:
```
DEFAULT_CONFIG = {
    "modules": {
        "new_module": True
    }
}
```

Implement Module Logic: Create a new reporter class e.g., src/archon/modules/new_module.py:

class NewModuleReporter:
    def __init__(self, results, output_root):
        self.results = results
        self.output_root = output_root
        
    def generate_reports(self):
        self.output_root.mkdir(parents=True, exist_ok=True)
        # Computes logic & writes txt, json, and md files

Register in Command Pipeline: Modify src/archon/cli.py to trigger the new module during scans:

if config.get('modules', {}).get('new_module', True):
    report_folder_new = report_root / "06_new_module"
    reporter_new = NewModuleReporter(results, report_folder_new)
    reporter_new.generate_reports()

28. Contributing

Please fork the repository, build features in target branches, and run all unit tests before opening a pull request.

29. Roadmap

Short Term: Enhance syntax parser to support Rust and Go.
Medium Term: Implement circular dependency graphics inside unified HTML report.
Long Term: Build visual trend reports tracking metrics changes over multiple scan sessions.

30. Appendix: Sample Scanner CLI Output & Real Scans Mock Example

Below is an example of CLI output when executing archon scan inside a repository path:

================================================================================
                           ARCHON ONE SCANNER                            
================================================================================
[*] Target Directory: C:\Users\ravan\Desktop\asthabyte
[*] Scanner configuration loaded from archon-config.json

[*] Scan progress: [====================] 100.0% (143/143) Done
[*] Generating metrics reports...
[*] Generating security reports...
[*] Generating code analysis reports...
[*] Generating contributor analysis reports...
[*] Generating repository intelligence reports...
[*] Finalizing scan and saving reports...

==================================================
               SCAN SUMMARY
==================================================
Total Files Found   204
Files Scanned       143
Files Ignored       61
Total Size Scanned  1.24 MB
Scan Duration       1.854 seconds
==================================================

[+] Reports saved to:
   C:\Users\ravan\Desktop\asthabyte\archon-one\2026-07-10_00-24-14
==================================================

31. Appendix A: Detailed Output Schemas and Sample Tables

This section provides structural examples representing exactly how table cells, headers, and rows are organized for the ASCII text outputs generated by all modules.

Module 01 - Code Metrics Samples

Sample repository summary table

====================================================
            01_REPOSITORY_SUMMARY REPORT            
====================================================
Metric                          Value
----------------------------------------------------
Total Files Found               142 files
Scanned Files                   88 files
Ignored Files                   54 files
Total Repository Size           682.83 KB
Total Physical Lines (LOC)      1542 lines
Total Comment Lines             280 lines
Average Comment Density         18.15 %
====================================================

Sample file metrics table

====================================================
                02_FILE_METRICS REPORT              
====================================================
File                  Language   Physical LOC   Logical LOC   Comment Lines   Comment Density %
------------------------------------------------------------------------------------------------
src/main.py           Python     120            85            25              20.8%
src/utils/parser.js   JavaScript 350            280           40              11.4%
src/core/loader.java  Java       420            310           60              14.3%
tests/test_unit.py    Python     150            110           10              6.7%
====================================================

Sample language metrics table

====================================================
              04_LANGUAGE_METRICS REPORT            
====================================================
Language        File Count   Total LOC   Percentage %
----------------------------------------------------
Python          45           4200        52.5%
JavaScript      22           2500        31.2%
Java            12           1100        13.7%
C++             9            200         2.5%
====================================================

Sample documentation metrics table

====================================================
           05_DOCUMENTATION_METRICS REPORT          
====================================================
File                  Total Lines   Docstring Lines   Comment Lines   Ratio %
------------------------------------------------------------------------------
src/main.py           120           15                10              20.8%
src/core/math.py      350           40                20              17.1%
src/utils/http.js     110           0                 15              13.6%
====================================================

Sample dependencies import metrics table

====================================================
                11_DEPENDENCIES REPORT              
====================================================
Module File           Import Namespace   Dependency Source Type
-----------------------------------------------------------------
src/main.py           os                 Standard Library
src/main.py           typer              Third Party Package
src/utils/parser.js   lodash             External Module
src/core/loader.java  java.io            Java API Namespace
====================================================

Module 02 - Security Checking Samples

Sample security summary table

====================================================
             01_SECURITY_SUMMARY REPORT             
====================================================
Severity Level                  Findings Count
----------------------------------------------------
Critical                        1 findings
High                            3 findings
Medium                          5 findings
Low                             10 findings
====================================================

Sample secrets exposure table

====================================================
                   02_SECRETS REPORT                
====================================================
File Path       Line   Severity   Secret Type   Recommendation
------------------------------------------------------------------------------------------
src/config.py   12     Critical   AWS Token     Invalidate key & remove from Git immediately.
tests/mock.py   45     High       API Key       Move secret to environmental configuration.
====================================================

Sample insecure functions alert table

====================================================
              04_INSECURE_FUNCTIONS REPORT          
====================================================
File Path       Line   Severity   Function Call   Replacement Suggestion
------------------------------------------------------------------------------------
src/loader.py   56     High       eval            Use json.loads or literal_eval
src/hash.py     88     Medium     md5             Upgrade to sha256 or bcrypt algorithm
====================================================

Sample sensitive files exposure table

====================================================
                09_SENSITIVE_FILES REPORT           
====================================================
File Path               Asset Category   Severity   Hazard / Risk Explanation
------------------------------------------------------------------------------------
.env                    Environment      High       Exposes system variables database keys
keys/private.pem        RSA Key          Critical   Exposes server certificates
====================================================

Module 03 - Code Analysis Samples

Sample complexity metrics table

====================================================
             02_COMPLEXITY_ANALYSIS REPORT          
====================================================
File                  Total Functions   Max Complexity   Average Complexity
---------------------------------------------------------------------------
src/main.py           8                 12               4.5
src/core/parser.py    15                28               12.3
src/utils/http.js     5                 4                1.8
====================================================

Sample function metrics table

====================================================
               03_FUNCTION_ANALYSIS REPORT          
====================================================
Function Name   File Path             Line   Length LOC   Parameters Count
-------------------------------------------------------------------------
parse_tokens    src/core/parser.py    42     85           4 params
load_config     src/main.py           105    40           2 params
validate_ip     src/utils/http.js     12     15           1 params
====================================================

Sample duplicate code blocks table

====================================================
              06_DUPLICATION_ANALYSIS REPORT        
====================================================
Duplicate Block   File A Source       File B Source       Identical Lines   Ratio %
-----------------------------------------------------------------------------------
Block Match #1    src/utils/http.js   src/core/loader.js  15 lines          8.2%
Block Match #2    src/main.py         tests/mock.py       12 lines          5.1%
====================================================

Sample code smells metrics table

====================================================
                  08_CODE_SMELLS REPORT             
====================================================
File Path       Line   Smell Key              Severity   Remediation Suggestion
-----------------------------------------------------------------------------------
src/parser.py   42     Long Method            High       Split into smaller helper functions.
src/loader.py   102    Long Parameter List    Medium     Refactor variables into a configuration data class.
====================================================

Module 04 - Contributor Analysis Samples

Sample contributor summary table

====================================================
             01_CONTRIBUTOR_SUMMARY REPORT          
====================================================
Metric                          Value
----------------------------------------------------
Active Developers               5 contributors
Total Commit Transactions       180 commits
Repository Bus Factor           2 developers
Single Owner Modules            3 folders
====================================================

Sample contributor statistics table

====================================================
            02_CONTRIBUTOR_STATISTICS REPORT        
====================================================
Contributor Name   Commit Count   Lines Inserted   Lines Removed   Ownership %
-------------------------------------------------------------------------------
Viraj Ravani       120            8500             3200            68.5%
John Doe           45             2500             1100            20.2%
Alice Smith        15             800              300             11.3%
====================================================

Sample file ownership metrics table

====================================================
                04_FILE_OWNERSHIP REPORT            
====================================================
File Path             Primary Owner   Ownership %   Co-Authors Count
--------------------------------------------------------------------
src/main.py           Viraj Ravani    85.0%         1 co-author
src/core/parser.py    Viraj Ravani    92.0%         0 co-authors
src/utils/http.js     John Doe        78.0%         2 co-authors
====================================================

Sample knowledge distribution table

====================================================
           06_KNOWLEDGE_DISTRIBUTION REPORT         
====================================================
Directory Path        Devs Count   Primary Owner   Owner %
--------------------------------------------------------------------
src/core              2            Viraj Ravani    91.2%
src/utils             3            John Doe        65.4%
tests                 3            Alice Smith     80.0%
====================================================

Module 05 - Repository Intelligence Samples

Sample repository health table

====================================================
             01_REPOSITORY_HEALTH REPORT            
====================================================
Health Component                Score / Ratio
----------------------------------------------------
Maintainability Index           85.50 / 100
Quality Excellence Score        90.00 / 100
Security Compliance Score       98.00 / 100
Ownership Stability Score       75.00 / 100

Overall Repository Health Score: 88.35/100
Overall Grade:                   A-
====================================================

Sample hotspot analysis table

====================================================
                02_HOTSPOT_ANALYSIS REPORT          
====================================================
File Path             Edit Count   Max Complexity   Hotspot Risk Rating
------------------------------------------------------------------------
src/core/parser.py    42 commits   28               9.5 / 10 (Critical)
src/main.py           25 commits   12               5.2 / 10 (Medium)
src/utils/http.js     10 commits   4                1.8 / 10 (Low)
====================================================

Sample change impact blast radius table

====================================================
             07_CHANGE_IMPACT_ANALYSIS REPORT       
====================================================
File Path             Dependents Count   Blast Radius Score
------------------------------------------------------------------
src/config.py         12 files           8.5 / 10 (High)
src/utils/http.js     4 files            4.2 / 10 (Medium)
src/core/parser.py    8 files            6.8 / 10 (High)
====================================================

Sample refactoring opportunities table

====================================================
          06_REFACTORING_OPPORTUNITIES REPORT       
====================================================
Priority   File Path             Refactor Action Type   Reasoning Details
--------------------------------------------------------------------------------------------
1          src/core/parser.py    Split Class            Cyclomatic complexity exceeds 25 limits.
2          src/loader.py         Reduce Parameters      Function has more than 6 arguments.
3          src/hash.py           Upgrade Hash Call      Exposed MD5 insecure cryptographic routine.
====================================================

32. Appendix B: Module-by-Module Processing Mechanics

1. Module 01: Code Metrics Processing Mechanics

Module 01 processes all files scanned by walking directories recursively via the python Generator pattern, preventing heavy memory overheads. Each file is opened in UTF-8 mode and scanned line-by-line.

Blank Lines: Checked via line.strip() == "".
Lexical Comment Tokenization: A custom single-character scanner monitors comment boundaries. For C-family syntax (// and /* ... */), state indicators prevent counting comment signs inside string literals. For Python (# and """ ... """), triple-quoted string blocks are validated against their context to determine whether they constitute documentation docstrings or multi-line assignments.
Directories Aggregation: Tracks folder statistics in hash maps and calculates averages/medians on mathematical sets.

2. Module 02: Security Audits Execution Mechanics

Module 02 uses compiled regex objects to scan code constructs.

Entropy scanning: Identifies base64 string segments and analyzes characters randomness. High-entropy blocks matching AWS or Private Key lengths raise alerts.
Function Indexing: Checks function identifiers against index directories of unsafe functions (such as Python's eval, exec, or C++'s strcpy).
Dependency parsing: Scans dependency configuration files (such as package.json or requirements.txt) and queries offline library registries of known vulnerability severities.

3. Module 03: Code Analysis Complexity Mechanics

Module 03 evaluates code nesting levels and duplicates.

Cyclomatic complexity: Counts decision nodes, branch instructions, and logical connectors (and, or, if, while, for, except).
Cognitive complexity: Calculates cognitive weight by adding increments based on indentation levels and logical breaks.
Duplication finder: Utilizes a sliding-window rolling checksum algorithm matching sequences of 10 consecutive lines across different files, computing match ratios.

4. Module 04: Contributor Tracing Mechanics

Module 04 relies on Git bindings to parse history data.

Git log analysis: Runs git log with custom format parameters to parse commit hashes, author names, changesets, and time parameters.
Lines attribution: Uses git blame to map every line of source code back to its original author.
Bus factor calculation: Ranks authors by ownership percentage descending, then finds the minimum number of authors who own > 50% of the codebase lines.

5. Module 05: Repository Intelligence Consolidation Mechanics

Module 05 aggregates the collected metrics data.

Maintainability index: Calculated per file, then averaged to form the general maintainability rating.
Scalability checks: Evaluates file type growth rates based on file sizes and commit activity, predicting repository expansion.
Blast radius: Identifies files imported by the largest number of internal modules, flagging them as highly critical dependencies.
Hotspots scoring: Combines commit frequency and cyclomatic complexity to identify problematic refactoring candidates.

33. Appendix C: Detailed File Schemas & Fields Reference Catalog (50/50 Reports)

This section lists the exact fields, JSON keys, data types, validation constraints, and developer interpretations for all 50 generated sub-report files.