arcgraph 0.1.0__tar.gz

arcgraph-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Report a reproducible ArcGraph defect
+title: "[Bug]: "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+What happened?
+
+## Environment
+
+- OS:
+- Python version:
+- Node/npm version, if TypeScript analysis is involved:
+- ArcGraph commit or version:
+
+## Reproduction
+
+```powershell
+# paste the smallest command sequence that reproduces the issue
+```
+
+## Expected Behavior
+
+What did you expect?
+
+## Actual Behavior
+
+What did ArcGraph print or produce?
+
+## Safety Check
+
+Do not include secrets, private repository content, tokens, or sensitive source
+snippets unless you have explicitly sanitized them.
+
+Do not report a security vulnerability or credential exposure here. Follow the
+private reporting path in SECURITY.md instead.

arcgraph-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/glyphevo/arcgraph/blob/main/SECURITY.md
+    about: Do not open a public issue for a vulnerability or credential exposure. Follow the private reporting path in SECURITY.md.

arcgraph-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Propose a scoped ArcGraph improvement
+title: "[Feature]: "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What workflow or evidence gap should this improve?
+
+## Proposed Capability
+
+What should ArcGraph do?
+
+## Current Workaround
+
+How do you handle this today?
+
+## Boundaries
+
+Does this require package publishing, public MCP distribution, network services,
+or production-readiness claims? If so, call that out explicitly.

arcgraph-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Summary
+
+- 
+
+## Validation
+
+- [ ] `python -m pytest arcgraph\tests scripts\tests -q`
+- [ ] `python -m black arcgraph scripts --check`
+- [ ] `python -m ruff check arcgraph scripts`
+- [ ] `python scripts\arcgraph.py ci`
+
+## Public-Safe Checklist
+
+- [ ] No generated artifacts, `dist`, `node_modules`, caches, or smoke outputs
+      are committed.
+- [ ] No secrets, private repository contents, or local process notes are
+      included.
+- [ ] Documentation does not claim production readiness, stable APIs, public
+      package publishing, or public MCP distribution unless separately approved.

arcgraph-0.1.0/.github/dependabot.yml

@@ -0,0 +1,59 @@
+version: 2
+
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: '09:00'
+      timezone: Etc/UTC
+    groups:
+      python-dependencies:
+        patterns:
+          - '*'
+    ignore:
+      # Ruff 0.x minor releases can be breaking. Keep the reviewed upper bound
+      # until a dedicated migration updates the rule policy and codebase.
+      - dependency-name: ruff
+        versions:
+          - '>=0.16.0'
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: deps
+
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: '09:00'
+      timezone: Etc/UTC
+    groups:
+      npm-dependencies:
+        patterns:
+          - '*'
+    ignore:
+      # ArcGraph consumes the TypeScript compiler API. Major upgrades require
+      # an explicit compatibility review before Dependabot may propose them.
+      - dependency-name: typescript
+        update-types:
+          - version-update:semver-major
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: deps
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: '09:00'
+      timezone: Etc/UTC
+    groups:
+      github-actions:
+        patterns:
+          - '*'
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: deps

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

@@ -0,0 +1,285 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHONUTF8: '1'
+
+jobs:
+  quality:
+    name: Quality / Ubuntu / Python 3.11
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: '3.11'
+          cache: pip
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: '20'
+          cache: npm
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -e ".[dev,mcp]"
+          npm ci
+
+      - name: Run unit and script tests with coverage
+        env:
+          ARCGRAPH_REQUIRE_TS: '1'
+        run: |
+          mkdir -p output/arcgraph
+          python -m pytest arcgraph/tests scripts/tests -q --cov=arcgraph --cov-report=xml:output/arcgraph/coverage.xml --cov-report=term --cov-fail-under=92
+
+      - name: Check formatting and lint
+        run: |
+          python -m black arcgraph scripts --check
+          python -m ruff check arcgraph scripts
+
+      - name: Build local index
+        run: python scripts/arcgraph.py build
+
+      - name: Run ArcGraph CI
+        run: python scripts/arcgraph.py ci
+
+      - name: Run release gate
+        run: python scripts/arcgraph_release_gate.py
+
+      - name: Upload coverage evidence
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: coverage-python-3.11
+          path: output/arcgraph/coverage.xml
+          if-no-files-found: error
+          retention-days: 14
+
+  test-matrix:
+    name: Tests / ${{ matrix.os }} / Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+        python:
+          - '3.11'
+          - '3.12'
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: '20'
+          cache: npm
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -e ".[dev,mcp]"
+          npm ci
+
+      - name: Run cross-platform tests
+        env:
+          ARCGRAPH_REQUIRE_TS: '1'
+        run: python -m pytest arcgraph/tests scripts/tests -q
+
+  package-matrix:
+    name: Package / ${{ matrix.os }} / Python ${{ matrix.python }} / MCP ${{ matrix.mcp_line }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python: '3.11'
+            mcp_line: lower
+            mcp_spec: mcp==2.0.0
+          - os: ubuntu-latest
+            python: '3.11'
+            mcp_line: latest-2x
+            mcp_spec: mcp>=2.0.0,<3.0.0
+          - os: windows-latest
+            python: '3.12'
+            mcp_line: latest-2x
+            mcp_spec: mcp>=2.0.0,<3.0.0
+          - os: macos-latest
+            python: '3.12'
+            mcp_line: latest-2x
+            mcp_spec: mcp>=2.0.0,<3.0.0
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: '20'
+          cache: npm
+
+      - name: Install package-smoke prerequisites
+        run: |
+          python -m pip install -e ".[dev]"
+          npm ci
+
+      - name: Build, install, and exercise package artifacts
+        run: |
+          python -c "from pathlib import Path; Path('output/release').mkdir(parents=True, exist_ok=True)"
+          python scripts/arcgraph_package_readiness_smoke.py --mcp-version-spec "${{ matrix.mcp_spec }}" > output/release/package-readiness.json
+
+      - name: Upload package provenance
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: package-readiness-${{ matrix.os }}-py${{ matrix.python }}-${{ matrix.mcp_line }}
+          path: output/release/package-readiness.json
+          if-no-files-found: error
+          retention-days: 14
+
+  typescript-acceptance:
+    name: TypeScript / Node ${{ matrix.node }} / TS ${{ matrix.typescript }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - node: '20'
+            typescript: '5.4.5'
+          - node: '20'
+            typescript: '5.9.3'
+          - node: '22'
+            typescript: '5.9.3'
+          - node: '24'
+            typescript: '5.9.3'
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: '3.11'
+          cache: pip
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+
+      - name: Install acceptance toolchain
+        run: |
+          python -m pip install -e ".[dev]"
+          npm ci
+          npm install --no-save --ignore-scripts typescript@${{ matrix.typescript }}
+
+      - name: Run formal TypeScript acceptance contract
+        env:
+          ARCGRAPH_REQUIRE_TS: '1'
+        run: |
+          python -m pytest -q \
+            arcgraph/tests/test_typescript_baseline.py \
+            arcgraph/tests/test_typescript_esm_resolution.py \
+            arcgraph/tests/test_typescript_package_exports.py \
+            arcgraph/tests/test_typescript_conditional_exports.py \
+            arcgraph/tests/test_typescript_express_routes.py \
+            arcgraph/tests/test_typescript_similarity.py
+
+  security:
+    name: Security / Audit and SBOM
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: '3.12'
+          cache: pip
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: '20'
+          cache: npm
+
+      - name: Install security tooling
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install -e ".[dev,mcp,security]"
+          npm ci
+
+      - name: Generate CycloneDX SBOM
+        run: |
+          mkdir -p output/security
+          python -m cyclonedx_py environment --output-format JSON --output-file output/security/arcgraph.cdx.json
+
+      - name: Audit Python dependencies
+        run: |
+          python -m pip freeze --exclude-editable > output/security/python-audit-requirements.txt
+          python -m pip_audit --strict --disable-pip --no-deps --requirement output/security/python-audit-requirements.txt --format json --output output/security/pip-audit.json
+
+      - name: Audit Node development dependencies
+        run: |
+          test "$(npx --yes npm@11.12.1 --version)" = "11.12.1"
+          npx --yes npm@11.12.1 audit --audit-level=high --json > output/security/npm-audit.json
+
+      - name: Scan Python source
+        run: python -m bandit -c pyproject.toml -r arcgraph scripts -x arcgraph/tests,scripts/tests -f json -o output/security/bandit.json
+
+      - name: Upload security evidence
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: security-evidence
+          path: output/security
+          if-no-files-found: error
+          retention-days: 30
+
+  ci-gate:
+    name: CI Gate
+    if: always()
+    runs-on: ubuntu-latest
+    needs:
+      - quality
+      - test-matrix
+      - package-matrix
+      - typescript-acceptance
+      - security
+    steps:
+      - name: Require every CI lane
+        env:
+          QUALITY_RESULT: ${{ needs.quality.result }}
+          TEST_MATRIX_RESULT: ${{ needs['test-matrix'].result }}
+          PACKAGE_MATRIX_RESULT: ${{ needs['package-matrix'].result }}
+          TYPESCRIPT_ACCEPTANCE_RESULT: ${{ needs['typescript-acceptance'].result }}
+          SECURITY_RESULT: ${{ needs.security.result }}
+        run: |
+          test "$QUALITY_RESULT" = "success"
+          test "$TEST_MATRIX_RESULT" = "success"
+          test "$PACKAGE_MATRIX_RESULT" = "success"
+          test "$TYPESCRIPT_ACCEPTANCE_RESULT" = "success"
+          test "$SECURITY_RESULT" = "success"

arcgraph-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+__pycache__/
+.DS_Store
+arcgraph/_build_provenance.json
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+build/
+dist/
+# Approved generated-output fixture used by TypeScript framework scanner tests.
+!arcgraph/tests/fixtures/typescript_frameworks/dist/
+!arcgraph/tests/fixtures/typescript_frameworks/dist/**
+*.egg-info/
+.venv/
+node_modules/
+output/
+.agents/
+.codex/
+viz/graph_data.json
+
+# Private working material stays under docs/_internal and is never committed.
+docs/_internal/
+
+# Generated/runtime/local artifact filename patterns
+*.log
+*.tmp
+*.db
+*.sqlite
+*.sqlite3
+
+# Local operator instructions are not part of the public source tree.
+/AGENTS.md

arcgraph-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,113 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+ArcGraph is currently a beta-stage, single-maintainer project. Until a
+dedicated moderation team exists, the project maintainer is responsible for
+clarifying and enforcing these standards and will take appropriate and fair
+corrective action in response to any behavior deemed inappropriate, threatening,
+offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces associated with this
+project (issues, pull requests, discussions, and any other project
+communication channel), and also applies when an individual is officially
+representing the project in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainer at
+[security@glyphevo.com](mailto:security@glyphevo.com) — the same address used
+for security reports; note "Code of Conduct" in the subject so it is triaged
+correctly. All complaints will be reviewed and investigated promptly and
+fairly.
+
+The maintainer is obligated to respect the privacy and security of the
+reporter of any incident. There is no formal enforcement committee at this
+stage of the project; reports are handled directly by the maintainer.
+
+## Enforcement Guidelines
+
+The maintainer will follow these Community Impact Guidelines in determining
+the consequences for any action deemed in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome.
+
+**Consequence**: A private, written warning, providing clarity around the
+nature of the violation and an explanation of why the behavior was
+inappropriate.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved for a specified period of time. Further
+violations may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the project for a specified period of time.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the project.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

arcgraph-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing To ArcGraph
+
+ArcGraph is a beta-stage, local-first code semantic graph engine.
+Contributions should preserve the current public-safe boundaries:
+source-checkout install, local execution, accurate package claims (name only
+the versions [RELEASE_NOTES.md](RELEASE_NOTES.md) lists as published on PyPI),
+and no claims of a separate MCP distribution.
+
+## Before Opening A Pull Request
+
+- Keep changes focused and explain the user-facing behavior or evidence improved.
+- Run the [local checks](#local-checks) before requesting review.
+- On a clean committed branch, run
+  `python scripts/arcgraph_release_gate.py` and
+  `python scripts/arcgraph_package_readiness_smoke.py`; dirty source is rejected
+  so artifact evidence cannot be confused with uncommitted work.
+- GitHub Actions runs the `CI` workflow. A passing run is evidence only for the
+  commit it ran on; check the run for the exact commit before treating the
+  Ubuntu/Windows/macOS matrix as passing.
+- Do not commit generated output, `dist`, `node_modules`, caches, smoke outputs,
+  credentials, private repository contents, or local process notes.
+- Keep docs honest about current maturity. Describe ArcGraph as beta
+  software until its release status actually changes.
+
+## Local Checks
+
+These are the contributor-level part of the required local gate. Run them from
+a source checkout. `arcgraph docs release-checklist` is the authoritative,
+current list and also covers the steps only a release needs.
+
+```bash
+export ARCGRAPH_REQUIRE_TS=1
+npm ci
+python -m pip install --upgrade pip setuptools wheel
+python -m pip install -e ".[dev,mcp,security]"
+python -m pytest arcgraph/tests scripts/tests -q
+python -m black arcgraph scripts --check
+python -m ruff check arcgraph scripts
+python -m bandit -c pyproject.toml -r arcgraph scripts -x arcgraph/tests,scripts/tests
+mkdir -p output/security
+python -m pip freeze --exclude-editable > output/security/python-audit-requirements.txt
+python -m pip_audit --strict --disable-pip --no-deps --requirement output/security/python-audit-requirements.txt
+npx --yes npm@11.12.1 audit --audit-level=high --json
+python scripts/arcgraph.py build
+python scripts/arcgraph.py ci
+```
+
+`ARCGRAPH_REQUIRE_TS=1` makes the TypeScript golden tests fail instead of
+skipping when Node or the compiler API is unavailable. The commands are
+POSIX-shell syntax; on Windows PowerShell set it with
+`$env:ARCGRAPH_REQUIRE_TS = "1"` and translate `export`, `mkdir -p` and the `>`
+redirect.
+
+## Security
+
+Do not open public issues for vulnerabilities or sensitive data exposure. Follow
+the private reporting path in `SECURITY.md`.
+
+## Code Of Conduct
+
+Participation in this project is governed by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).