Metadata-Version: 2.3
Name: memscope-fw
Version: 0.1.0a9
Summary: Local-first firmware footprint intelligence for embedded engineering teams.
Project-URL: Homepage, https://pypi.org/project/memscope-fw/
Author: MemScope
License: MemScope Software License Agreement (Interim v1)
        ==================================================
        
        Copyright (c) 2026 Adrian Dumitrescu. All rights reserved.
        
        This is a commercial software product. Use of this software is governed
        by the terms below. By installing, copying, or otherwise using
        MemScope ("the Software"), you ("the User") accept these terms.
        
        If you have a separately-signed master agreement with the Licensor
        that covers MemScope, that agreement governs your use and supersedes
        this LICENSE file where the two conflict.
        
        NOTE: this is a self-drafted interim license clearly identifying
        MemScope as proprietary commercial software. A more complete
        lawyer-reviewed End User License Agreement will replace this file
        once the Licensor's commercial entity is registered. Until then,
        this LICENSE establishes the baseline that the Software is NOT
        released under any open-source or Free Software license.
        
        
        1. DEFINITIONS
        --------------
        
        "Licensor" means Adrian Dumitrescu, the copyright holder.
        "User" means the individual or entity installing or using the Software.
        "License Key" means a unique activation token issued by the Licensor.
        "Free Edition" means the operating mode available without a License Key
           (as described in Section 3 below).
        "Trial" means the initial 14-day evaluation window during which all
           features are unlocked without a License Key.
        
        
        2. GRANT OF LICENSE
        -------------------
        
        Subject to the User's compliance with this Agreement, the Licensor
        grants the User a non-exclusive, non-transferable, revocable license
        to install and use the Software:
        
          (a) on machines the User owns or is authorized to operate;
          (b) for the User's internal business purposes;
          (c) subject to the operating-mode restrictions in Section 3.
        
        The Software is licensed, not sold. The Licensor retains all rights,
        title, and interest in and to the Software, including all intellectual
        property rights. No rights are granted under any license approved by
        the Open Source Initiative or recognized as a Free Software license
        by the Free Software Foundation.
        
        
        3. OPERATING MODES
        ------------------
        
        MemScope operates in one of three modes depending on activation state:
        
          TRIAL (first 14 days, automatic on first run): all features unlocked
            for evaluation. No License Key required.
        
          FREE EDITION (after Trial expires, no License Key): visibility-only
            mode. The `analyze` command and all reporting (terminal, JSON, HTML,
            diff visualization) remain available indefinitely without time
            limit, subject to a "FREE EDITION" watermark. Build-gating features
            (`--strict` enforcement, `validate` subcommand, custom `[budgets]`
            and `[policies]` config sections, CSV export) are disabled.
        
          PAID (active License Key): all features unlocked, watermark removed.
            Requires a valid License Key issued by the Licensor.
        
        
        4. LICENSE KEYS
        ---------------
        
        License Keys are:
          (a) issued by the Licensor in exchange for payment;
          (b) bound to a specific machine fingerprint at activation time;
          (c) valid for the duration printed in the key (typically one year);
          (d) subject to a 7-day offline grace window between online check-ins;
          (e) revocable by the Licensor in case of fraudulent use, breach of
              this Agreement, or chargeback.
        
        Moving a License Key to a different machine requires running
        `memscope license deactivate` on the original machine first, or
        contacting the Licensor to release the seat manually.
        
        
        5. RESTRICTIONS
        ---------------
        
        The User shall NOT:
        
          (a) redistribute, resell, sublicense, rent, lease, or lend the
              Software or any License Key to any third party without prior
              written permission from the Licensor;
          (b) reverse engineer, decompile, disassemble, or attempt to derive
              the source code of the Software's licensing mechanism, license
              gates, or activation system, except to the extent expressly
              permitted by applicable law notwithstanding this restriction
              (including without limitation Article 6 of EU Directive
              2009/24/EC for interoperability purposes);
          (c) circumvent, disable, or otherwise interfere with the License Key
              validation, trial-clock, or feature-gating mechanisms;
          (d) remove, alter, or obscure any copyright, trademark, license, or
              proprietary notices included in the Software;
          (e) use the Software in any manner that violates applicable law.
        
        Inspecting and modifying the Software's analyzer logic for the User's
        own internal use is permitted; redistribution of any modified version
        is not.
        
        
        6. DATA + PRIVACY
        -----------------
        
        The Software runs analysis entirely on the User's machine. Build
        artifacts (ELF, MAP, linker scripts) and analysis reports are NOT
        transmitted to the Licensor or any third party in the course of
        normal operation.
        
        License Key activation and periodic re-validation contact the
        Licensor's licensing backend (Keygen.sh) and transmit only:
          - The License Key
          - A machine fingerprint hash
          - The Software version
        
        No analysis content, build artifacts, source code, or personally
        identifying information beyond the above is transmitted by the
        Software absent the User's explicit opt-in.
        
        
        7. WARRANTY DISCLAIMER
        ----------------------
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
        NON-INFRINGEMENT. THIS DISCLAIMER DOES NOT EXCLUDE OR LIMIT
        WARRANTIES THAT CANNOT BE EXCLUDED OR LIMITED UNDER APPLICABLE
        CONSUMER PROTECTION LAW, INCLUDING WHERE THE USER IS A NATURAL
        PERSON ACTING OUTSIDE THEIR TRADE, BUSINESS, OR PROFESSION.
        
        
        8. LIMITATION OF LIABILITY
        --------------------------
        
        IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY DIRECT, INDIRECT,
        INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING
        BUT NOT LIMITED TO PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
        OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
        AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
        LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
        ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGE. NOTHING IN THIS LIMITATION EXCLUDES
        LIABILITY THAT CANNOT BE EXCLUDED UNDER APPLICABLE LAW.
        
        
        9. TERMINATION
        --------------
        
        This license terminates automatically if the User materially breaches
        any of its terms and fails to cure the breach within thirty (30) days
        of written notice (where the breach is capable of being cured). Upon
        termination, the User must cease all use of the Software and destroy
        all copies in their possession.
        
        The Licensor may revoke any License Key for material breach of this
        Agreement, fraudulent use, or chargeback.
        
        
        10. CONTACT
        -----------
        
        For license purchases, support inquiries, machine swaps, refunds,
        or any questions about this Agreement:
        
            dumitrescu.adrian121@gmail.com
        
        
        --------------------------------------------------------------------
        INTERIM-VERSION NOTE: this LICENSE is a self-drafted v1 intended to
        clearly identify MemScope as a paid commercial product (NOT open
        source) and to set baseline terms during the period before the
        Licensor's commercial entity is registered. It will be replaced by a
        lawyer-reviewed final EULA before paid License Keys are sold to
        external customers. Customers entering into significant commercial
        relationships should request the Licensor's then-current
        lawyer-reviewed master agreement.
        --------------------------------------------------------------------
License-File: LICENSE
Keywords: elf,embedded,firmware,footprint,map,memory
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.11
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: jinja2<4.0.0,>=3.1.4
Requires-Dist: pydantic<3.0.0,>=2.9.2
Requires-Dist: pynacl<2.0.0,>=1.5.0
Requires-Dist: rich<14.0.0,>=13.9.4
Requires-Dist: typer<1.0.0,>=0.12.5
Provides-Extra: build
Requires-Dist: build<2.0.0,>=1.2.2.post1; extra == 'build'
Provides-Extra: dev
Requires-Dist: build<2.0.0,>=1.2.2.post1; extra == 'dev'
Requires-Dist: cython<4.0.0,>=3.0.0; extra == 'dev'
Requires-Dist: hatch-vcs<1.0.0,>=0.4.0; extra == 'dev'
Requires-Dist: jsonschema<5.0.0,>=4.0.0; extra == 'dev'
Requires-Dist: mypy<2.0.0,>=1.11.2; extra == 'dev'
Requires-Dist: pillow<12.0.0,>=10.0.0; extra == 'dev'
Requires-Dist: playwright<2.0.0,>=1.45.0; extra == 'dev'
Requires-Dist: pytest-cov<6.0.0,>=5.0.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=8.3.3; extra == 'dev'
Requires-Dist: ruff<1.0.0,>=0.6.9; extra == 'dev'
Provides-Extra: test
Requires-Dist: jsonschema<5.0.0,>=4.0.0; extra == 'test'
Requires-Dist: pytest-cov<6.0.0,>=5.0.0; extra == 'test'
Requires-Dist: pytest<9.0.0,>=8.3.3; extra == 'test'
Description-Content-Type: text/markdown

# MemScope

**Local-first firmware footprint intelligence for embedded teams.**

MemScope analyzes your ELF, MAP, and linker artifacts to give you a clear picture of where your firmware's flash and RAM are going — and gates your CI build when a regression sneaks in. Built for embedded engineers who want SonarQube-style enforcement without sending build artifacts to a cloud.

```bash
pip install memscope-fw
```

---

## What it does

- **Inspects** ELF + MAP + linker scripts and reconstructs the per-region, per-section, per-symbol, per-component memory layout — everything that's actually placed in your firmware image and what each part costs.
- **Reports** in three forms from a single run: a compact terminal summary for CI logs, a versioned JSON for scripts and dashboards, and a self-contained interactive HTML for engineers to explore.
- **Gates** CI builds when a budget is busted, a region overflows, or a baseline diff exceeds your threshold — fail-fast with deterministic exit codes.
- **Compares** two builds side-by-side via `memscope diff`, showing top regressions and reductions across regions, sections, symbols, and components.
- **Runs entirely offline** after activation. No build artifacts ever leave your machine. No cloud backend.

## Why teams pick MemScope over rolling their own scripts

| Capability | Hand-rolled scripts | MemScope |
|---|---|---|
| Parse ELF + MAP + linker config consistently across toolchains | Different per project | One CLI, GNU + IAR + Keil + Clang/LLD all supported (dedicated parsers per toolchain, normalized to a single internal model) |
| Stable JSON schema your CI can rely on | Brittle | Versioned + `validate` subcommand |
| Drop-in CMake integration | DIY | `cmake/FirmwareFootprint.cmake` |
| Interactive HTML report for design reviews | None | Self-contained, no internet needed to open |
| CI gating with friendly error messages | grep + bash | `--strict` exit codes |
| Multi-core / multi-region partition awareness | Usually missing | First-class |

## Install

```bash
pip install memscope-fw
```

Requires Python ≥ 3.11. Wheels are published per-platform for Windows (x86_64) + Linux (manylinux2014, x86_64) + macOS (Apple Silicon / arm64), each on Python 3.11 / 3.12 / 3.13 / 3.14.

## 5-minute quick start

```bash
# 1. Analyze a single build — produces report.html you can open in any browser
memscope analyze \
  --elf path/to/firmware.elf \
  --map path/to/firmware.map \
  --linker path/to/linker.ld \
  --json report.json \
  --html report.html

# 2. Compare two builds (e.g. before/after a refactor)
memscope diff \
  --current-json report.json \
  --baseline-json baseline.json \
  --html diff.html

# 3. Gate CI on a regression budget (exits non-zero if violated)
memscope analyze --strict \
  --elf firmware.elf --map firmware.map --linker linker.ld \
  --baseline-json baseline.json
```

The HTML report is **fully self-contained** — D3, ECharts, and all interactive visualizations are bundled inline, so it works in air-gapped CI environments and can be archived as a single file.

## Pricing model — TRIAL → FREE → PAID

| State | What works | What's locked |
|---|---|---|
| **TRIAL** (first 14 days, automatic) | Everything | Nothing |
| **FREE** (after day 14, forever, no key) | `analyze` + HTML/JSON reports + `diff` (visualization) + watermark | `--strict` enforcement, `validate` subcommand, custom `[budgets]` / `[policies]`, CSV export |
| **PAID** (with activation key) | Everything, no watermark | Nothing |

**Local builds never break.** When the trial expires the tool silently devolves to FREE — `memscope analyze` keeps running in your dev workflow and your CMake builds keep producing reports. Only the CI-gating features (`--strict`, custom budgets) require activation. This means you can leave MemScope in your `requirements.txt` indefinitely without worrying about builds breaking when the trial ends.

To enable CI gating after the trial:

```bash
memscope license activate <YOUR-KEY>
```

Contact details for purchasing a key are in the seller's distribution channel (commercial license — see your purchase email or the support contact below).

## Documentation

Full documentation (CLI reference, CMake integration, CI tutorial for GitHub Actions / GitLab / Jenkins / Bamboo, report interpretation guide, config schema, troubleshooting) is delivered with your purchase or available on request — email <dumitrescu.adrian121@gmail.com>.

A condensed walkthrough is also available via:

```bash
memscope --help                         # top-level commands
memscope analyze --help                 # per-command reference
memscope license --help                 # license management
```

Every subcommand has built-in `--help` documentation.

## Privacy posture

- All analysis runs **locally**. Your ELF / MAP files never leave your machine.
- License activation phones the licensing server (Keygen) once on activation, then once per online refresh (default: every 7 days during a 7-day offline grace window). Telemetry beyond license validation is opt-in only.
- The full privacy policy and data-flow specification is included with your license materials or available on request.

## Support

For commercial inquiries, license issuance, bug reports, and integration help:

- **Email**: <dumitrescu.adrian121@gmail.com>

When reporting an issue, please include the output of `memscope diagnostics export` — it bundles version, environment, parser diagnostics, and license state into a single ZIP that's safe to attach.

## License

Commercial. Paid use (`--strict` enforcement, `validate`, custom budgets, CSV export) requires a license key issued by the maintainer. The Free Edition — `analyze` + HTML/JSON reports + `diff` visualization, with a watermark — is available to all users indefinitely without a key after the 14-day trial.

For commercial licensing inquiries: <dumitrescu.adrian121@gmail.com>.
