codexray-analyser 0.1.0__tar.gz

codexray_analyser-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Require maintainer review for all files.
+* @Merlins-Sanctum

codexray_analyser-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,29 @@
+name: Bug report
+description: Report a bug in codexray-analyser
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened?
+      description: What did you expect and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run ...
+        2. Analyse ...
+        3. Observe ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Package version
+      placeholder: 0.1.0
+    validations:
+      required: true

codexray_analyser-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,19 @@
+name: Feature request
+description: Suggest a new feature
+title: "[Feature]: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What user problem are you trying to solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe your proposed approach.
+    validations:
+      required: true

codexray_analyser-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## What changed
+
+- 
+
+## Why
+
+- 
+
+## Validation
+
+- [ ] `python -m ruff check .`
+- [ ] `python -m pytest`
+- [ ] `python -m bandit -q -r src`

codexray_analyser-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test-and-security:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+          python -m pip install pytest ruff bandit pip-audit
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Unit tests
+        run: pytest
+
+      - name: Static security scan
+        run: bandit -q -r src
+
+      - name: Dependency vulnerability scan
+        run: |
+          python - <<'PY'
+          import pathlib
+          import tomllib
+
+          pyproject = tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))
+          deps = pyproject.get("project", {}).get("dependencies", [])
+          pathlib.Path("runtime-requirements.txt").write_text(
+              "\n".join(deps),
+              encoding="utf-8",
+          )
+          print(f"Runtime dependencies found: {len(deps)}")
+          PY
+          if [ -s runtime-requirements.txt ]; then pip-audit -r runtime-requirements.txt --strict; else echo "No runtime dependencies to audit."; fi

codexray_analyser-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/codexray-analyser
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

codexray_analyser-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/

codexray_analyser-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our pledge
+
+We are committed to making participation in this project a harassment-free experience for everyone.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Being respectful and constructive.
+- Accepting feedback gracefully.
+- Focusing on what is best for the community.
+
+Examples of unacceptable behavior include:
+
+- Harassment, threats, or discriminatory language.
+- Personal attacks or insulting comments.
+- Publishing private information without consent.
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing these standards.
+
+## Reporting
+
+Report abusive behavior to the maintainers through private channels listed in `SECURITY.md`.

codexray_analyser-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Thanks for contributing to `codexray-analyser`.
+
+## Local setup
+
+1. Fork and clone the repo.
+2. Install development tools:
+
+```bash
+python -m pip install -e .
+python -m pip install pytest ruff bandit pip-audit build twine
+```
+
+## Before opening a PR
+
+Run all checks locally:
+
+```bash
+python -m ruff check .
+python -m pytest
+python -m bandit -q -r src
+```
+
+## Development guidelines
+
+- Keep offline-first behavior as the default.
+- Avoid adding network dependencies in default analysis flow.
+- Add tests for new rules and parser behavior.
+- Keep dependencies minimal and justified.
+
+## Pull requests
+
+- Use clear titles and explain why the change is needed.
+- Include tests for bug fixes and new features.
+- Keep changes focused and small when possible.

codexray_analyser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Hamad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codexray_analyser-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: codexray-analyser
+Version: 0.1.0
+Summary: Offline-first static analyser for Python files and notebooks.
+Project-URL: Homepage, https://github.com/Merlins-Sanctum/codexray-analyser
+Project-URL: Repository, https://github.com/Merlins-Sanctum/codexray-analyser
+Project-URL: Issues, https://github.com/Merlins-Sanctum/codexray-analyser/issues
+Author: Mohammad Hamad
+License: MIT
+License-File: LICENSE
+Keywords: notebook,offline,python,security,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Codexray
+
+Codexray is an offline-first Python static analyser for `.py` and `.ipynb` files.
+It helps teams inspect security risks, code quality problems, and dependency patterns
+without sending source code outside the local machine.
+
+## What Codexray does
+
+- Scans Python files and notebooks.
+- Supports project-level scans, full file scans, and targeted line-range checks.
+- Produces a structured JSON report.
+- Builds a dependency graph view with nodes and edges.
+- Flags common security risks such as shell execution and dangerous builtins.
+
+## Privacy and security behavior
+
+- No telemetry.
+- No source upload.
+- Network features are disabled by default.
+- Strict input limits for file size, notebook size, snippet length, and AST depth.
+
+This tool is designed for local analysis workflows where proprietary code must stay on the client system.
+
+## Installation
+
+```bash
+pip install codexray-analyser
+```
+
+## Quick start with CLI
+
+Analyse a folder:
+
+```bash
+codexray ./my_project
+```
+
+Analyse a single file:
+
+```bash
+codexray ./my_project/app.py
+```
+
+Analyse a code snippet:
+
+```bash
+codexray --snippet "import os; os.system('whoami')"
+```
+
+Analyse only specific lines from one file:
+
+```bash
+codexray ./my_project/app.py --start-line 40 --end-line 80
+```
+
+Save output to JSON:
+
+```bash
+codexray ./my_project --output codexray-report.json
+```
+
+## Python API usage
+
+```python
+from codexray import analyse_file_snippet, analyse_path, analyse_snippet
+
+project_result = analyse_path("./my_project")
+snippet_result = analyse_snippet("import os\nos.system('whoami')")
+range_result = analyse_file_snippet("./my_project/app.py", 20, 50)
+```
+
+## Understanding the report
+
+Each result returns:
+
+- `findings`: list of detected issues.
+- `graph`: nodes and edges representing imports, files, and function relationships.
+- `metadata`: run information such as analysed path and offline mode state.
+
+Example finding shape:
+
+```json
+{
+  "rule_id": "SEC002",
+  "title": "Dangerous builtin eval",
+  "severity": "critical",
+  "message": "Avoid eval on untrusted content.",
+  "file_path": "src/app.py",
+  "line": 18,
+  "column": 4
+}
+```
+
+## Reading graph output
+
+Graph output contains:
+
+- `nodes`: entities such as files, imports, and functions
+- `edges`: relationships such as `imports`, `contains`, and `calls`
+
+Typical use:
+
+1. Run Codexray and save JSON output.
+2. Load `graph.nodes` and `graph.edges` into your graph viewer.
+3. Track dependency hotspots and risky call paths.
+
+## How to use findings to make code changes
+
+Recommended workflow:
+
+1. Sort findings by `severity`.
+2. Fix `critical` and `high` findings first.
+3. Re-run Codexray after each fix batch.
+4. Keep evidence by committing report diffs in your internal workflow.
+
+Examples:
+
+- `SEC001` shell execution:
+  - Replace dynamic shell calls with safe Python APIs.
+  - Avoid passing untrusted input to command execution.
+- `SEC002` dangerous builtin:
+  - Replace `eval` or `exec` with safe parsing and strict allow-lists.
+- `DEP001` unpinned dependency:
+  - Pin versions in requirements files with `==` where practical.
+
+## Troubleshooting
+
+- `File parsing failed`:
+  - Check syntax errors or unsupported file encoding.
+- `exceeds ... bytes/chars`:
+  - Increase limits in config for controlled internal usage.
+- Empty findings:
+  - Confirm the target path includes `.py` or `.ipynb` sources.
+
+## Local development
+
+```bash
+python -m pip install -e .
+python -m pip install pytest ruff bandit pip-audit build twine
+python -m ruff check .
+python -m pytest
+python -m bandit -q -r src
+python -m pip-audit
+python -m build
+python -m twine check dist/*
+```
+
+## Contributing
+
+Read `CONTRIBUTING.md` before opening a pull request.
+Security reports should follow `SECURITY.md`.
+
+## License
+
+MIT. See `LICENSE`.

codexray_analyser-0.1.0/README.md

@@ -0,0 +1,155 @@
+# Codexray
+
+Codexray is an offline-first Python static analyser for `.py` and `.ipynb` files.
+It helps teams inspect security risks, code quality problems, and dependency patterns
+without sending source code outside the local machine.
+
+## What Codexray does
+
+- Scans Python files and notebooks.
+- Supports project-level scans, full file scans, and targeted line-range checks.
+- Produces a structured JSON report.
+- Builds a dependency graph view with nodes and edges.
+- Flags common security risks such as shell execution and dangerous builtins.
+
+## Privacy and security behavior
+
+- No telemetry.
+- No source upload.
+- Network features are disabled by default.
+- Strict input limits for file size, notebook size, snippet length, and AST depth.
+
+This tool is designed for local analysis workflows where proprietary code must stay on the client system.
+
+## Installation
+
+```bash
+pip install codexray-analyser
+```
+
+## Quick start with CLI
+
+Analyse a folder:
+
+```bash
+codexray ./my_project
+```
+
+Analyse a single file:
+
+```bash
+codexray ./my_project/app.py
+```
+
+Analyse a code snippet:
+
+```bash
+codexray --snippet "import os; os.system('whoami')"
+```
+
+Analyse only specific lines from one file:
+
+```bash
+codexray ./my_project/app.py --start-line 40 --end-line 80
+```
+
+Save output to JSON:
+
+```bash
+codexray ./my_project --output codexray-report.json
+```
+
+## Python API usage
+
+```python
+from codexray import analyse_file_snippet, analyse_path, analyse_snippet
+
+project_result = analyse_path("./my_project")
+snippet_result = analyse_snippet("import os\nos.system('whoami')")
+range_result = analyse_file_snippet("./my_project/app.py", 20, 50)
+```
+
+## Understanding the report
+
+Each result returns:
+
+- `findings`: list of detected issues.
+- `graph`: nodes and edges representing imports, files, and function relationships.
+- `metadata`: run information such as analysed path and offline mode state.
+
+Example finding shape:
+
+```json
+{
+  "rule_id": "SEC002",
+  "title": "Dangerous builtin eval",
+  "severity": "critical",
+  "message": "Avoid eval on untrusted content.",
+  "file_path": "src/app.py",
+  "line": 18,
+  "column": 4
+}
+```
+
+## Reading graph output
+
+Graph output contains:
+
+- `nodes`: entities such as files, imports, and functions
+- `edges`: relationships such as `imports`, `contains`, and `calls`
+
+Typical use:
+
+1. Run Codexray and save JSON output.
+2. Load `graph.nodes` and `graph.edges` into your graph viewer.
+3. Track dependency hotspots and risky call paths.
+
+## How to use findings to make code changes
+
+Recommended workflow:
+
+1. Sort findings by `severity`.
+2. Fix `critical` and `high` findings first.
+3. Re-run Codexray after each fix batch.
+4. Keep evidence by committing report diffs in your internal workflow.
+
+Examples:
+
+- `SEC001` shell execution:
+  - Replace dynamic shell calls with safe Python APIs.
+  - Avoid passing untrusted input to command execution.
+- `SEC002` dangerous builtin:
+  - Replace `eval` or `exec` with safe parsing and strict allow-lists.
+- `DEP001` unpinned dependency:
+  - Pin versions in requirements files with `==` where practical.
+
+## Troubleshooting
+
+- `File parsing failed`:
+  - Check syntax errors or unsupported file encoding.
+- `exceeds ... bytes/chars`:
+  - Increase limits in config for controlled internal usage.
+- Empty findings:
+  - Confirm the target path includes `.py` or `.ipynb` sources.
+
+## Local development
+
+```bash
+python -m pip install -e .
+python -m pip install pytest ruff bandit pip-audit build twine
+python -m ruff check .
+python -m pytest
+python -m bandit -q -r src
+python -m pip-audit
+python -m build
+python -m twine check dist/*
+```
+
+## Contributing
+
+Read `CONTRIBUTING.md` before opening a pull request.
+Security reports should follow `SECURITY.md`.
+
+## License
+
+MIT. See `LICENSE`.

codexray_analyser-0.1.0/RELEASING.md

@@ -0,0 +1,38 @@
+# Releasing to PyPI
+
+This project uses GitHub Actions trusted publishing for PyPI.
+
+## One-time setup
+
+1. Create a GitHub repository named `codexray-analyser`.
+2. Push this code to the default branch (`main`).
+3. Create the PyPI project once with the exact package name:
+   - `codexray-analyser`
+4. In PyPI project settings, add a trusted publisher:
+   - Owner: your GitHub user/org
+   - Repository: `codexray-analyser`
+   - Workflow: `.github/workflows/publish.yml`
+   - Environment: `pypi`
+5. In GitHub repository settings, create environment `pypi`.
+
+## Release flow
+
+1. Update version in `pyproject.toml`.
+2. Commit and push to `main`.
+3. Create and push a tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+4. GitHub Actions runs `.github/workflows/publish.yml`.
+5. On success, package is available on PyPI.
+
+## Local validation before tagging
+
+```bash
+python -m pip install --upgrade pip build twine
+python -m build
+python -m twine check dist/*
+```

codexray_analyser-0.1.0/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest release and the previous minor release.
+
+## Reporting a vulnerability
+
+Please do not open public issues for security vulnerabilities.
+
+Report privately by contacting the maintainer with:
+
+- A clear description of the issue
+- Steps to reproduce
+- Impact assessment
+- Suggested remediation (if available)
+
+You will receive an acknowledgement within 72 hours.
+
+## Security principles for this project
+
+- Offline-first by default
+- No telemetry
+- No source upload in default flow
+- Minimal dependency footprint
+- CI security checks (Bandit + dependency audit)