drefs 0.1.0__tar.gz

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

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --check
+      - run: cargo clippy -- -D warnings
+
+  test:
+    needs: lint
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo test
+
+  pattern-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: ./scripts/check_pattern_sync.sh

drefs-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            manylinux: "2_28"
+          - os: ubuntu-latest
+            target: aarch64-unknown-linux-gnu
+            manylinux: "2_28"
+          - os: macos-latest
+            target: x86_64-apple-darwin
+          - os: macos-latest
+            target: aarch64-apple-darwin
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          manylinux: ${{ matrix.manylinux || 'auto' }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.target }}
+          path: dist/*.whl
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    needs: [build, sdist]
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  github-release:
+    needs: [build, sdist]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

drefs-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+/target
+__pycache__/
+*.pyc
+editors/pycharm/build/
+editors/pycharm/.gradle/
+editors/pycharm/.intellijPlatform/
+editors/pycharm/.kotlin/
+docs/superpowers/

drefs-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/doublify/pre-commit-rust
+    rev: v1.0
+    hooks:
+      - id: fmt
+      - id: clippy
+        args: ["--", "-D", "warnings"]

drefs-0.1.0/BENCHMARKS.md

@@ -0,0 +1,49 @@
+# Benchmarks
+
+Benchmarks comparing drefs against `mkdocs build --strict` for validating cross-references.
+
+drefs checks cross-references only. `mkdocs build --strict` renders the entire documentation site (Markdown processing, HTML generation, search index, etc.), which includes cross-reference validation as a side effect.
+
+## Setup
+
+- Apple M1 Pro, 16 GB RAM
+- macOS 15.7.1
+- Rust 1.94.0 (release build)
+- Measured with [hyperfine](https://github.com/sharkdp/hyperfine)
+
+## Results
+
+### tinygrad (697 Python files, 32k stars)
+
+Validating cross-references in [tinygrad/tinygrad](https://github.com/tinygrad/tinygrad):
+
+| Command | Mean | Min | Max |
+|:---|---:|---:|---:|
+| `drefs .` | 110 ms | 98 ms | 125 ms |
+| `mkdocs build --strict` | 51.0 s | 48.3 s | 52.5 s |
+
+**~460x faster.**
+
+### httpx (60 Python files, 13k stars)
+
+Validating cross-references in [encode/httpx](https://github.com/encode/httpx):
+
+| Command | Mean | Min | Max |
+|:---|---:|---:|---:|
+| `drefs .` | 19 ms | 16 ms | 50 ms |
+| `mkdocs build --strict` | 872 ms | 845 ms | 921 ms |
+
+**~45x faster.**
+
+## Methodology
+
+```bash
+# drefs (release build)
+cargo build --release
+hyperfine --warmup 3 --ignore-failure './target/release/drefs .'
+
+# mkdocs build --strict
+hyperfine --warmup 3 '.venv/bin/mkdocs build --strict'
+```
+
+drefs and `mkdocs build --strict` are not doing identical work. drefs validates cross-references against source code symbols. `mkdocs build --strict` renders an entire documentation site, which happens to catch some broken references along the way. The comparison shows how fast you can get cross-reference validation without waiting for a full docs build.

drefs-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- MkDocs cross-reference checking (`[text][pkg.mod.Class]`, `[path][]`)
+- Sphinx cross-reference checking (`:class:`, `:func:`, `:meth:`, etc.)
+- drefs-native syntax (`[Symbol]`, `` [`Symbol`] ``) with short name resolution via imports
+- Zero-config auto-detection of src layout and doc style
+- Symbol graph with re-export resolution, inheritance chains, `self.x` attributes
+- External symbol validation via Sphinx `objects.inv` inventories
+- Ruff-compatible output format (`file:line:col: DREF001 message`)
+- PyCharm plugin with Ctrl+Click navigation, syntax highlighting, and squiggles
+- LSP server for editor integration

drefs-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to drefs
+
+## Prerequisites
+
+- [Rust toolchain](https://rustup.rs/) (stable)
+- [uv](https://docs.astral.sh/uv/) for Python package management
+- JDK 21+ (only for PyCharm plugin development)
+
+## Development Setup
+
+```bash
+git clone https://github.com/scriptogre/drefs.git
+cd drefs
+cargo build
+```
+
+## Running Tests
+
+```bash
+# All tests (unit + integration)
+cargo test
+
+# Unit tests only
+cargo test --bin drefs
+
+# Integration tests only
+cargo test --test integration
+
+# A specific test
+cargo test native_syntax
+```
+
+## Linting
+
+```bash
+cargo fmt --check
+cargo clippy
+```
+
+## Project Structure
+
+```
+src/
+  main.rs          # CLI entry point (clap)
+  config.rs        # pyproject.toml config loading
+  discover.rs      # .py file discovery and module path mapping
+  parse.rs         # tree-sitter Python AST parsing
+  extract.rs       # Cross-reference pattern extraction (regex)
+  graph.rs         # Symbol graph data structures and resolution
+  diagnostic.rs    # Reference validation and error reporting
+  inventory.rs     # Sphinx objects.inv parsing
+  lsp.rs           # Language Server Protocol support
+tests/
+  integration.rs   # Integration tests
+  fixtures/        # Test project fixtures
+editors/
+  pycharm/         # PyCharm/IntelliJ plugin (Kotlin)
+```
+
+## PyCharm Plugin
+
+```bash
+cd editors/pycharm
+./gradlew buildPlugin
+```
+
+The built plugin zip will be at `build/distributions/drefs-pycharm-*.zip`.
+
+## Test Fixtures
+
+Test fixtures are minimal Python projects in `tests/fixtures/`. Each has a `pyproject.toml` and a `src/pkg/` directory. Integration tests run `drefs` against these fixtures and assert on the output.
+
+To add a new test case, create a fixture directory and add tests in `tests/integration.rs`.