Metadata-Version: 2.4
Name: mamba-scan
Version: 1.0.0
Summary: Scan a project directory and collect per-filetype statistics into a markdown info file.
Project-URL: Homepage, https://github.com/soss-community/mamba-scan
Project-URL: Repository, https://github.com/soss-community/mamba-scan
Project-URL: Bug Tracker, https://github.com/soss-community/mamba-scan/issues
Project-URL: Contact, https://github.com/soss-community
Author: sora7672
License: SOSS Module & Package License (SOSS-MPL) v1.0
        ==============================================
        Copyright (c) 2026 sora7672 & SOSS Community
        Website: https://soss.page
        Organization: https://github.com/soss-community
        
        NOTE: This license may be updated over time.
        Always refer to the latest version at: https://github.com/soss-community
        The version included in this repository was current at time of release.
        
        ---
        
        ACCEPTANCE
        
        By incorporating this package or module into your software, code, or project in any form,
        you confirm that you have read and understood the terms of this license.
        Usage constitutes full acceptance of all conditions stated below.
        
        ---
        
        1. PERMITTED USE
        
           This package/module may be used freely by anyone, for private or commercial purposes,
           subject to the conditions of this license.
        
        2. NO MODIFICATION & DISTRIBUTION
        
           Modification of the original source files is not permitted.
           Modified versions of this package/module may not be redistributed in any form.
        
           Exception:
           You may create child classes or wrapper implementations that extend
           the functionality through inheritance or composition. These must be clearly marked
           as separate works and must not replace or repackage the original.
           This exception exists to allow external verification of behavior, if an issue
           arises in a child class, it can be clearly distinguished from the original.
        
        3. CREDITS & ATTRIBUTION
        
           Any software, project, or codebase that uses this package/module must clearly
           credit it in one of the following locations:
           - A credits section in the README
           - An About screen or page within the software
           - Any other clearly visible location within the project documentation
        
           The credit entry must include:
           - A link to the SOSS community page: https://soss.page
           - The name of the module/package (e.g. "taipan-logger")
           - If multiple SOSS packages/modules are used, all must be listed individually.
        
        4. COMMERCIAL USE
        
           Commercial use of this package/module is explicitly permitted.
           In addition to the credit requirement above, commercial users are strongly encouraged
           to open a discussion on the official GitHub repository with the tag:
           "Using this package/module for my software"
           including the name of their software.
           This will be read and closed by the maintainer.
           This does not replace the credit requirement.
        
        5. ISSUE REPORTING
        
           Issues, bugs, and feature requests are managed exclusively via the official
           GitHub repository of the respective package/module.
           Before reporting an issue, you must have read the README and documentation,
           and must understand the intended purpose of the software.
        
        6. SUPPORT
        
           No official support is provided by the developers or maintainers.
           If you or your organization wish to offer support for this package/module,
           including commercial support, you may apply via the SOSS community page:
           https://soss.page
        
           Approved support providers will be listed there publicly.
           No individual or organization may present themselves as an "official" support
           provider without being listed on the SOSS community page.
        
           Listings may be revoked at any time if quality standards are not maintained.
           The affected party will be notified and the listing updated accordingly.
        
        7. NO MONETIZATION
        
           This package/module is not for sale under any circumstances, regardless of the offer.
        
           Any new maintainer who takes over this project must agree to the same conditions.
           Monetization of this package/module by any maintainer is strictly prohibited.
        
           In the event of a violation, third parties are entitled to pursue legal action
           against the maintainer and to seek the appointment of a new maintainer
           who agrees to these conditions.
        
        8. LEGAL & DISPUTE RESOLUTION
        
           In the event of a dispute arising from improper use or violation of this license,
           all legal costs shall be borne by the party found to be in violation.
           This applies internationally to the extent permitted by applicable law.
        
        9. NO WARRANTY & NO LIABILITY
        
           This package/module is provided "as is", without warranty of any kind.
           The maintainers and contributors make no guarantees regarding functionality,
           fitness for a particular purpose, or absence of errors.
        
           We are human, mistakes can happen. We do our best to keep the code clean and reliable,
           but we accept no liability for any damages, data loss, or other consequences
           arising from the use of this software.
        
        ---
        SOSS-MPL is part of the Sora Open Source Software standard.
        All SOSS-licensed projects must include this license file unchanged.
        Website: https://soss.page
        Organization: https://github.com/soss-community
License-File: LICENSE
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# mamba-scan

> Scan your project once, get per-filetype stats in a markdown file, move on.

![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Version](https://img.shields.io/badge/version-0.1.0-orange)
[![Community](https://img.shields.io/badge/community-soss.page-purple)](https://soss.page)
<img width=100px height=20 src="https://komarev.com/ghpvc/?username=soss-community-mamba-scan&color=c8f04a&style=flat-square&label=Views:" />

---

The black mamba is one of the fastest snakes on earth. That's the idea here: install, run once, uninstall.  
No config files, no database, no background process. Just a snake that bites once and leaves.

---

## The Problem

At some point in a project you want to know what you actually have. How many Python files, how many lines,  
how much of it is documentation versus actual code. The answer is usually "open a terminal and start counting  
by hand" or "find a tool that requires three config files and a GitHub token to get started."

I wanted something I could drop into any project for thirty seconds, run once, and have a readable result  
sitting in the project root. Not a dashboard, not a CI integration, not a persistent dependency.  
Just a number, written to a file, done.

mamba-scan does exactly that. One import, one call, one markdown block appended to a file in your project root.  
Then you uninstall it and forget it existed.

---

## Features

- **One-call API** - `count_project()` with no required arguments covers the most common case immediately
- **Per-filetype stats** - lines, chars, doc chars, code chars, and type-specific counts broken out per extension
- **Multi-language support** - built-in analyzers for Python, HTML/Jinja2, JavaScript/TypeScript, CSS/SCSS,  
  Java, C, C++, and C#
- **Append-only output** - results are appended with a rounded timestamp so repeated runs don't overwrite history
- **Flexible scoping** - restrict or exclude extensions and directories without touching any config file
- **Extensible** - subclass `FileAnalyzer`, set `extensions`, implement `analyze()` - registration is automatic
- **Unmatched file reporting** - files with no specific analyzer are listed once at the end so nothing is silently missed

---

## Installation

```
pip install mamba-scan
```

Or directly from the repository:

```
pip install git+https://github.com/soss-community/mamba-scan.git
```

---

## Usage

### Quickstart

```python
from mamba_scan import count_project

count_project()
```

That's it. mamba-scan finds the project root automatically, scans all default file types,  
and appends a stats block to `project_info.md` in the project root.

### Filtering what gets scanned

```python
# Only these extensions
count_project(scanned_extensions=[".py", ".html", ".css"])

# Everything default except these
count_project(ignored_extensions=[".md", ".json"])

# Only files inside these directories
count_project(only_dirs=["src", "app"])

# Default directories plus these excluded on top
count_project(ignored_dirs=["migrations", "legacy"])

# Custom output file
count_project(output_filename="my_stats.md")
```

`scanned_extensions` and `ignored_extensions` are mutually exclusive.  
`only_dirs` and `ignored_dirs` are mutually exclusive.

For full working examples see:
- [examples/example_mamba_scan.py](examples/example_mamba_scan.py) - all call variants and a custom analyzer example

---

## Built-in Analyzers

Each analyzer handles one or more extensions and tracks type-specific stats on top of the shared base stats.

| Analyzer | Extensions | Extra stats |
|---|---|---|
| `PythonAnalyzer` | `.py`, `.pyw` | classes, functions, docstrings, inline comments |
| `HtmlAnalyzer` | `.html`, `.htm`, `.jinja`, `.jinja2`, `.j2` | html comments, jinja2 comments |
| `JsTsAnalyzer` | `.js`, `.ts`, `.jsx`, `.tsx` | jsdoc blocks, multiline comments, inline comments |
| `CssAnalyzer` | `.css`, `.scss`, `.sass` | block comments |
| `JavaAnalyzer` | `.java` | classes, methods, javadoc blocks, multiline comments, inline comments |
| `CAnalyzer` | `.c`, `.h` | functions, block comments, inline comments |
| `CppAnalyzer` | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx` | classes, functions, block comments, inline comments |
| `CSharpAnalyzer` | `.cs` | classes, methods, xml doc lines, block comments, inline comments |
| `GenericAnalyzer` | fallback for everything else | basic line and char counts only |

All analyzers share the base stats: `total_lines`, `empty_lines`, `total_chars`, `doc_chars`, `code_chars`.

---

## Custom Analyzers

Subclass `FileAnalyzer`, set `extensions` as a class attribute, implement `analyze()` as a classmethod.  
Registration happens automatically when Python evaluates the class body - no instantiation needed.

```python
import re
from mamba_scan import FileAnalyzer, count_project


class LuaAnalyzer(FileAnalyzer):
    extensions = [".lua"]

    @classmethod
    def analyze(cls, content: str) -> dict:
        total_chars = len(content)
        sl_matches = list(re.finditer(r"--(?!\[).*$", content, re.MULTILINE))
        block_matches = list(re.finditer(r"--\[\[[\s\S]*?\]\]", content))
        doc_chars = sum(len(m.group(0)) for m in sl_matches + block_matches)

        return {
            "total_lines": len(content.splitlines()),
            "empty_lines": sum(1 for l in content.splitlines() if not l.strip()),
            "total_chars": total_chars,
            "doc_chars": doc_chars,
            "code_chars": total_chars - doc_chars,
            "inline_comments": len(sl_matches),
            "block_comments": len(block_matches),
        }


# LuaAnalyzer is registered at this point - just call count_project
count_project(scanned_extensions=[".py", ".lua"])
```

Registering the same extension twice raises a `ValueError` immediately.

---

## Output Format

Each run appends one block to the output file. The block is wrapped in separator lines  
and timestamped to the nearest 5 minutes (UTC), so multiple runs stack cleanly without overwriting.

```
------------------------------

## Project Info Count - 2026-05-04 14:30 UTC

### Config
- Root: /home/user/my_project
- Scanned types: .css, .html, .js, .py
- Ignored dirs: .git, .venv, __pycache__, ...

### General
- Total files: 42
- File types found: .css, .html, .js, .py
- Total lines: 8310
- Empty lines: 1204
- Total chars: 241500
- Doc chars: 38200
- Code chars: 203300

### Python (.py)
- Files: 18
- Lines: 4200
- ...

------------------------------
```

---

## What this is not for and what we excluded

| Feature | Reason |
|---|---|
| Continuous monitoring | mamba-scan is a one-shot tool, not a background service |
| Git integration | Diff stats, blame, or history are out of scope |
| Code quality / linting | No AST analysis, no style checks, no complexity metrics |
| Test coverage | Use coverage.py for that |
| Precise AST-based counting | Regex-based heuristics are good enough for an overview, not for hard analysis |
| Network or remote scanning | Local filesystem only |

---

## Compatibility

Python 3.10 or higher. No external dependencies. Works on Windows, macOS, and Linux.

---

## License

MIT.  
Always refer to the latest version at: [github.com/soss-community](https://github.com/soss-community)

---

## Community and contributing

Part of the Sora Open Source Software community.  
Visit [github.com/soss-community](https://github.com/soss-community)  
for contribution guidelines, issue tracking, and discussion.

> **Author:** [sora7672](https://github.com/sora7672)  
> **Organization:** [soss-community](https://github.com/soss-community)  
> **Website:** [soss.page](https://soss.page)
