pyegp-parser 0.1.0__tar.gz

pyegp_parser-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-28
+
+### Added
+
+- Initial public release.
+- Parse SAS Enterprise Guide `.egp` project files into structured JSON.
+- Extraction of project metadata, elements, tasks, queries, data references, and shortcuts.
+- Execution DAG reconstruction and data-lineage tracing.
+- Embedded SAS code, execution log, and ODS result extraction.
+- CLI (`pyegp-parser`) with `parse`, `bulk`, and `print` commands.
+- Optional MCP server (`pyegp-parser-mcp`) and a Claude Agent Skill for AI-assisted exploration.
+- Optional JSON-schema validation of the output.
+- Best-effort credential redaction for passwords embedded in SAS code,
+  execution logs, and task configuration.
+
+[Unreleased]: https://github.com/lamiskin/pyegp-parser/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/lamiskin/pyegp-parser/releases/tag/v0.1.0

pyegp_parser-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to pyegp-parser
+
+Thanks for your interest in contributing!
+
+## Development setup
+
+This project uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/lamiskin/pyegp-parser
+cd pyegp-parser
+uv sync --all-extras         # create the venv and install everything
+uv run pre-commit install    # enable the git hooks (optional but recommended)
+```
+
+## Everyday commands
+
+```bash
+uv run pytest                # run tests
+uv run ruff check            # lint
+uv run ruff format           # auto-format
+uv run mypy                  # type-check
+```
+
+All of the above run in CI on every pull request across Python 3.11–3.14.
+
+## Guidelines
+
+- **Never commit real or confidential `.egp` data.** The test suite generates all
+  input in-memory. Integration tests that need real files skip automatically when
+  none are present — keep it that way.
+- Add or update tests for any behaviour change.
+- Keep public APIs typed (the package ships `py.typed`).
+- Do not bump versions or edit `CHANGELOG.md` by hand — release-please owns
+  both, and generates them from your commit messages.
+
+## Commit messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/)
+(e.g. `feat:`, `fix:`, `docs:`, `ci:`) so releases and the changelog can be
+generated automatically.
+
+## Releases
+
+Releases are automated with release-please: merging the generated "release" PR
+tags a new version and publishes to PyPI via Trusted Publishing. Maintainers do
+not publish manually.
+
+### Bootstrapping the first release (maintainers)
+
+release-please treats `.release-please-manifest.json` as the last *released*
+version, so it will only ever propose versions **after** it. The version
+currently recorded there has to be tagged and released by hand once, or it never
+reaches PyPI:
+
+```bash
+git tag -a v0.1.0 -m "pyegp-parser 0.1.0" && git push origin v0.1.0
+gh release create v0.1.0 --notes-from-tag
+```
+
+Before that, dry-run the whole pipeline without touching real PyPI: run the
+**Publish** workflow manually (`workflow_dispatch`) with target `testpypi`. It
+builds, validates the metadata, smoke-tests the wheel, and publishes to TestPyPI
+only — the PyPI job is unreachable from that trigger.

pyegp_parser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lachlan Miskin
+
+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.

pyegp_parser-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md

pyegp_parser-0.1.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: pyegp-parser
+Version: 0.1.0
+Summary: Parse SAS Enterprise Guide .egp project files into structured JSON
+Author-email: Lachlan Miskin <lamiskin@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lamiskin/pyegp-parser
+Project-URL: Repository, https://github.com/lamiskin/pyegp-parser
+Project-URL: Issues, https://github.com/lamiskin/pyegp-parser/issues
+Project-URL: Changelog, https://github.com/lamiskin/pyegp-parser/blob/main/CHANGELOG.md
+Keywords: sas,enterprise guide,egp,parser,etl,data lineage,project.xml
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+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 :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.0.0; extra == "mcp"
+Dynamic: license-file
+
+# pyegp-parser
+
+Parse **SAS Enterprise Guide `.egp` project files** into structured, machine-readable JSON.
+
+[![CI](https://github.com/lamiskin/pyegp-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/lamiskin/pyegp-parser/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/lamiskin/pyegp-parser/branch/main/graph/badge.svg)](https://codecov.io/gh/lamiskin/pyegp-parser)
+[![PyPI](https://img.shields.io/pypi/v/pyegp-parser.svg)](https://pypi.org/project/pyegp-parser/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyegp-parser.svg)](https://pypi.org/project/pyegp-parser/)
+[![CodeQL](https://github.com/lamiskin/pyegp-parser/actions/workflows/codeql.yml/badge.svg)](https://github.com/lamiskin/pyegp-parser/actions/workflows/codeql.yml)
+[![Docs](https://img.shields.io/badge/docs-lamiskin.github.io-blue)](https://lamiskin.github.io/pyegp-parser/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+An `.egp` file is a ZIP archive containing `project.xml` plus SAS code, task
+configs, execution logs, and ODS results. `pyegp-parser` reads **all** of it and
+produces a single structured representation — think of it as decompiling a SAS
+Enterprise Guide project into JSON you can query, diff, and analyse.
+
+## Features
+
+- Full extraction of project metadata, elements, tasks, queries, data references, and shortcuts
+- Reconstructs the execution **DAG** (process-flow dependencies)
+- Extracts embedded SAS code, execution logs, and ODS output references
+- Data-lineage tracing across tasks
+- Best-effort credential redaction for passwords embedded in SAS code
+- Bulk-parse an entire directory tree of `.egp` files
+- Optional JSON-schema validation of the output
+- Optional [MCP](https://modelcontextprotocol.io) server for AI-assisted exploration
+- No heavy dependencies (just `jsonschema`); pure-Python, cross-platform
+
+## Supported Enterprise Guide versions
+
+The parser is **version-agnostic by design**: it reads whatever structure a
+project contains and has no version gates or version-specific branches. The
+`EGVersion` attribute on the root `ProjectCollection` element is recorded and
+surfaced as `project.metadata.eg_version`, but it never changes how a file is
+parsed. In practice that means an unlisted version is likely to parse, and
+anything the parser does not recognise is reported rather than dropped — see
+[Handling unknown content](#handling-unknown-content) below.
+
+| EG version | Status | How it is verified |
+|---|---|---|
+| **8.1** | Verified against a real project | `tests/fixtures/real_world/eg81_process_flows.egp`, plus most of the synthetic suite |
+| **7.1** | Verified against a real project | `tests/fixtures/real_world/eg71_code_tasks.egp` |
+| Other 7.x / 8.x | Expected to work, untested | No version gating exists, but no sample was available |
+| 9.x and later | Unknown | Not released at the time of writing |
+
+Two caveats worth stating plainly:
+
+- The 7.1 fixture was produced by a third-party 8→7 downgrade converter rather
+  than written by Enterprise Guide 7.1 itself. Its `project.xml`, embedded SAS
+  code, and execution logs are EG-authored, but it is not a pristine 7.1 file.
+- The 8.1 fixture is a *migrated* project: its elements carry
+  `ModifiedByEGVer` values spanning `7.100.5.x` and `8.1.0.x`, so mixed-version
+  element metadata within a single project is covered.
+
+Real-world coverage is limited by sample availability — genuine `.egp` files are
+rarely published, since they are binary ZIP archives. Provenance and the exact
+sanitisation applied to both fixtures are documented in
+[`tests/fixtures/real_world/README.md`](tests/fixtures/real_world/README.md).
+
+### Handling unknown content
+
+Because there is no version gating, an unlisted version is likely to parse. How
+the parser behaves when it meets something it does not understand depends on
+what that something is:
+
+- **Unrecognised archive entries** are listed in `project.unprocessed_entries`
+  and counted in `project.completeness_summary`, so nothing is silently
+  discarded. Comparing `processed_entries` against `total_entries` tells you how
+  much of a project was understood.
+- **Missing optional artifacts** — an absent `code.sas` or task-config file —
+  log a warning and leave the corresponding field `None`.
+- **A missing required section inside an element** raises `ValueError` and
+  aborts the whole parse. This is deliberate: the parser surfaces structural
+  gaps rather than emitting quietly incomplete output. Log elements and
+  process-flow containers are the two exceptions — they are recorded with
+  whatever metadata was readable, because a display-settings or DAG failure does
+  not undermine the rest of the project.
+
+So a newer EG version introducing a *new* element type or archive entry is
+handled gracefully, whereas one that *restructures an existing element* will
+fail loudly. If you hit either, `completeness_summary` and `unprocessed_entries`
+are the place to look first, and a bug report quoting the EG version plus those
+fields is the most useful thing you can send.
+
+## Installation
+
+```bash
+pip install pyegp-parser
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```python
+from pyegp_parser import parse_file
+
+project = parse_file("path/to/project.egp")
+
+print(project.metadata.label)     # project name
+print(len(project.tasks))         # number of tasks
+print(len(project.queries))       # number of Query Builder queries
+```
+
+Write JSON to disk:
+
+```python
+parse_file("project.egp", output_dir="./output")   # writes ./output/project.json
+```
+
+## CLI
+
+```bash
+# Parse a single file
+pyegp-parser parse path/to/project.egp --output-dir ./output
+
+# Recursively parse every .egp under a directory (mirrors the tree)
+pyegp-parser bulk ./source-pipeline --output-dir ./output
+
+# Pretty-print a parsed project.json
+pyegp-parser print ./output/project.json
+```
+
+## Credential redaction
+
+`.egp` projects embed SAS programs and logs verbatim, and SAS code routinely
+carries live credentials. Passwords are therefore redacted automatically when
+output is written:
+
+```python
+from pyegp_parser.redaction import redact_text
+
+redact_text("libname dw oracle user=etluser password=hunter2 path=prod;")
+# ('libname dw oracle user=etluser password=[SENSITIVE - REDACTED] path=prod;', 1)
+```
+
+SAS-encoded passwords (`{SAS002}...`) are redacted too — `PROC PWENCODE` output
+is reversible, so it is treated as plaintext. Column names such as
+`PASSWORD_HASH` are deliberately left intact: a column *name* is schema
+metadata, not a secret.
+
+Redaction applies when `project.json` is written and to MCP server output.
+`to_dict()` is a pure serializer and does not redact.
+
+### Handling real projects
+
+Redaction covers credentials, not everything an `.egp` file reveals. Output also
+includes library paths, server names, schema names, and usernames. Review parser
+output before attaching it to a public issue or sharing it outside your
+organisation — see [SECURITY.md](SECURITY.md) for the full security model.
+
+## AI integration
+
+`.egp` projects are dense and hard to read by hand, which makes them a natural fit
+for AI-assisted exploration. Two complementary options ship with this project:
+
+### MCP server
+
+An [MCP](https://modelcontextprotocol.io) server exposes the parser as tools
+(`parse_egp`, `parse_egp_directory`, `get_project_summary`, `get_sas_code`,
+`get_data_lineage`, `get_queries`) to any MCP-compatible client (Claude Desktop,
+Claude Code, Cursor, …).
+
+```bash
+pip install "pyegp-parser[mcp]"
+```
+
+Then register it with your client. Example config:
+
+```json
+{
+  "mcpServers": {
+    "pyegp-parser": {
+      "command": "pyegp-parser-mcp"
+    }
+  }
+}
+```
+
+### Claude Skill
+
+[`skills/pyegp-parser/SKILL.md`](skills/pyegp-parser/SKILL.md) is a portable
+[Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
+that teaches Claude when and how to parse `.egp` files and interpret the JSON —
+no running server required. Copy the `skills/pyegp-parser/` folder into your
+`.claude/skills/` directory to use it.
+
+Use the **MCP server** for interactive, on-demand parsing inside a client; use the
+**Skill** for a portable, dependency-light way to give any Claude the know-how.
+
+## Documentation
+
+Full documentation lives at
+**[lamiskin.github.io/pyegp-parser](https://lamiskin.github.io/pyegp-parser/)**.
+
+- [Full usage guide & API reference](docs/reference.md)
+- [Guide to interpreting the JSON output (for LLMs and humans)](docs/LLM_CONTEXT.md)
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) and [ruff](https://docs.astral.sh/ruff/).
+
+```bash
+git clone https://github.com/lamiskin/pyegp-parser
+cd pyegp-parser
+uv sync                 # create the venv and install deps (incl. dev tools)
+uv run pytest           # run the test suite
+uv run ruff check       # lint
+uv run ruff format      # format
+```
+
+## Acknowledgements
+
+This library was developed with substantial assistance from AI coding tools. It
+was originally built and validated against a corpus of **real** SAS Enterprise
+Guide `.egp` files during a data-migration project. None of that source data — and
+no files, identifiers, or history derived from it — is included in this repository;
+the test suite runs entirely on synthetic fixtures generated in-memory.
+
+## License
+
+[MIT](LICENSE)

pyegp_parser-0.1.0/README.md

@@ -0,0 +1,223 @@
+# pyegp-parser
+
+Parse **SAS Enterprise Guide `.egp` project files** into structured, machine-readable JSON.
+
+[![CI](https://github.com/lamiskin/pyegp-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/lamiskin/pyegp-parser/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/lamiskin/pyegp-parser/branch/main/graph/badge.svg)](https://codecov.io/gh/lamiskin/pyegp-parser)
+[![PyPI](https://img.shields.io/pypi/v/pyegp-parser.svg)](https://pypi.org/project/pyegp-parser/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyegp-parser.svg)](https://pypi.org/project/pyegp-parser/)
+[![CodeQL](https://github.com/lamiskin/pyegp-parser/actions/workflows/codeql.yml/badge.svg)](https://github.com/lamiskin/pyegp-parser/actions/workflows/codeql.yml)
+[![Docs](https://img.shields.io/badge/docs-lamiskin.github.io-blue)](https://lamiskin.github.io/pyegp-parser/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+An `.egp` file is a ZIP archive containing `project.xml` plus SAS code, task
+configs, execution logs, and ODS results. `pyegp-parser` reads **all** of it and
+produces a single structured representation — think of it as decompiling a SAS
+Enterprise Guide project into JSON you can query, diff, and analyse.
+
+## Features
+
+- Full extraction of project metadata, elements, tasks, queries, data references, and shortcuts
+- Reconstructs the execution **DAG** (process-flow dependencies)
+- Extracts embedded SAS code, execution logs, and ODS output references
+- Data-lineage tracing across tasks
+- Best-effort credential redaction for passwords embedded in SAS code
+- Bulk-parse an entire directory tree of `.egp` files
+- Optional JSON-schema validation of the output
+- Optional [MCP](https://modelcontextprotocol.io) server for AI-assisted exploration
+- No heavy dependencies (just `jsonschema`); pure-Python, cross-platform
+
+## Supported Enterprise Guide versions
+
+The parser is **version-agnostic by design**: it reads whatever structure a
+project contains and has no version gates or version-specific branches. The
+`EGVersion` attribute on the root `ProjectCollection` element is recorded and
+surfaced as `project.metadata.eg_version`, but it never changes how a file is
+parsed. In practice that means an unlisted version is likely to parse, and
+anything the parser does not recognise is reported rather than dropped — see
+[Handling unknown content](#handling-unknown-content) below.
+
+| EG version | Status | How it is verified |
+|---|---|---|
+| **8.1** | Verified against a real project | `tests/fixtures/real_world/eg81_process_flows.egp`, plus most of the synthetic suite |
+| **7.1** | Verified against a real project | `tests/fixtures/real_world/eg71_code_tasks.egp` |
+| Other 7.x / 8.x | Expected to work, untested | No version gating exists, but no sample was available |
+| 9.x and later | Unknown | Not released at the time of writing |
+
+Two caveats worth stating plainly:
+
+- The 7.1 fixture was produced by a third-party 8→7 downgrade converter rather
+  than written by Enterprise Guide 7.1 itself. Its `project.xml`, embedded SAS
+  code, and execution logs are EG-authored, but it is not a pristine 7.1 file.
+- The 8.1 fixture is a *migrated* project: its elements carry
+  `ModifiedByEGVer` values spanning `7.100.5.x` and `8.1.0.x`, so mixed-version
+  element metadata within a single project is covered.
+
+Real-world coverage is limited by sample availability — genuine `.egp` files are
+rarely published, since they are binary ZIP archives. Provenance and the exact
+sanitisation applied to both fixtures are documented in
+[`tests/fixtures/real_world/README.md`](tests/fixtures/real_world/README.md).
+
+### Handling unknown content
+
+Because there is no version gating, an unlisted version is likely to parse. How
+the parser behaves when it meets something it does not understand depends on
+what that something is:
+
+- **Unrecognised archive entries** are listed in `project.unprocessed_entries`
+  and counted in `project.completeness_summary`, so nothing is silently
+  discarded. Comparing `processed_entries` against `total_entries` tells you how
+  much of a project was understood.
+- **Missing optional artifacts** — an absent `code.sas` or task-config file —
+  log a warning and leave the corresponding field `None`.
+- **A missing required section inside an element** raises `ValueError` and
+  aborts the whole parse. This is deliberate: the parser surfaces structural
+  gaps rather than emitting quietly incomplete output. Log elements and
+  process-flow containers are the two exceptions — they are recorded with
+  whatever metadata was readable, because a display-settings or DAG failure does
+  not undermine the rest of the project.
+
+So a newer EG version introducing a *new* element type or archive entry is
+handled gracefully, whereas one that *restructures an existing element* will
+fail loudly. If you hit either, `completeness_summary` and `unprocessed_entries`
+are the place to look first, and a bug report quoting the EG version plus those
+fields is the most useful thing you can send.
+
+## Installation
+
+```bash
+pip install pyegp-parser
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```python
+from pyegp_parser import parse_file
+
+project = parse_file("path/to/project.egp")
+
+print(project.metadata.label)     # project name
+print(len(project.tasks))         # number of tasks
+print(len(project.queries))       # number of Query Builder queries
+```
+
+Write JSON to disk:
+
+```python
+parse_file("project.egp", output_dir="./output")   # writes ./output/project.json
+```
+
+## CLI
+
+```bash
+# Parse a single file
+pyegp-parser parse path/to/project.egp --output-dir ./output
+
+# Recursively parse every .egp under a directory (mirrors the tree)
+pyegp-parser bulk ./source-pipeline --output-dir ./output
+
+# Pretty-print a parsed project.json
+pyegp-parser print ./output/project.json
+```
+
+## Credential redaction
+
+`.egp` projects embed SAS programs and logs verbatim, and SAS code routinely
+carries live credentials. Passwords are therefore redacted automatically when
+output is written:
+
+```python
+from pyegp_parser.redaction import redact_text
+
+redact_text("libname dw oracle user=etluser password=hunter2 path=prod;")
+# ('libname dw oracle user=etluser password=[SENSITIVE - REDACTED] path=prod;', 1)
+```
+
+SAS-encoded passwords (`{SAS002}...`) are redacted too — `PROC PWENCODE` output
+is reversible, so it is treated as plaintext. Column names such as
+`PASSWORD_HASH` are deliberately left intact: a column *name* is schema
+metadata, not a secret.
+
+Redaction applies when `project.json` is written and to MCP server output.
+`to_dict()` is a pure serializer and does not redact.
+
+### Handling real projects
+
+Redaction covers credentials, not everything an `.egp` file reveals. Output also
+includes library paths, server names, schema names, and usernames. Review parser
+output before attaching it to a public issue or sharing it outside your
+organisation — see [SECURITY.md](SECURITY.md) for the full security model.
+
+## AI integration
+
+`.egp` projects are dense and hard to read by hand, which makes them a natural fit
+for AI-assisted exploration. Two complementary options ship with this project:
+
+### MCP server
+
+An [MCP](https://modelcontextprotocol.io) server exposes the parser as tools
+(`parse_egp`, `parse_egp_directory`, `get_project_summary`, `get_sas_code`,
+`get_data_lineage`, `get_queries`) to any MCP-compatible client (Claude Desktop,
+Claude Code, Cursor, …).
+
+```bash
+pip install "pyegp-parser[mcp]"
+```
+
+Then register it with your client. Example config:
+
+```json
+{
+  "mcpServers": {
+    "pyegp-parser": {
+      "command": "pyegp-parser-mcp"
+    }
+  }
+}
+```
+
+### Claude Skill
+
+[`skills/pyegp-parser/SKILL.md`](skills/pyegp-parser/SKILL.md) is a portable
+[Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
+that teaches Claude when and how to parse `.egp` files and interpret the JSON —
+no running server required. Copy the `skills/pyegp-parser/` folder into your
+`.claude/skills/` directory to use it.
+
+Use the **MCP server** for interactive, on-demand parsing inside a client; use the
+**Skill** for a portable, dependency-light way to give any Claude the know-how.
+
+## Documentation
+
+Full documentation lives at
+**[lamiskin.github.io/pyegp-parser](https://lamiskin.github.io/pyegp-parser/)**.
+
+- [Full usage guide & API reference](docs/reference.md)
+- [Guide to interpreting the JSON output (for LLMs and humans)](docs/LLM_CONTEXT.md)
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) and [ruff](https://docs.astral.sh/ruff/).
+
+```bash
+git clone https://github.com/lamiskin/pyegp-parser
+cd pyegp-parser
+uv sync                 # create the venv and install deps (incl. dev tools)
+uv run pytest           # run the test suite
+uv run ruff check       # lint
+uv run ruff format      # format
+```
+
+## Acknowledgements
+
+This library was developed with substantial assistance from AI coding tools. It
+was originally built and validated against a corpus of **real** SAS Enterprise
+Guide `.egp` files during a data-migration project. None of that source data — and
+no files, identifiers, or history derived from it — is included in this repository;
+the test suite runs entirely on synthetic fixtures generated in-memory.
+
+## License
+
+[MIT](LICENSE)

pyegp_parser-0.1.0/SECURITY.md

@@ -0,0 +1,59 @@
+# Security Policy
+
+## Supported versions
+
+The latest released version on PyPI receives security fixes.
+
+## Reporting a vulnerability
+
+Please report security issues privately via GitHub's
+[private vulnerability reporting](https://github.com/lamiskin/pyegp-parser/security/advisories/new)
+rather than opening a public issue.
+
+Please do **not** include real or confidential `.egp` data or parsed output in
+your report — a minimal synthetic reproduction is preferred.
+
+You can expect an initial response within a reasonable timeframe. Thanks for
+helping keep the project and its users safe.
+
+## Security model, and what this tool does not guarantee
+
+`pyegp-parser` reads ZIP archives and XML and produces JSON. It executes no SAS
+code, opens no database connections, and resolves no external XML entities.
+
+The important thing to understand about `.egp` files is that they carry
+**embedded SAS programs and execution logs**, reproduced verbatim in parser
+output. SAS code routinely contains live credentials:
+
+```sas
+libname dw oracle user=etluser password=hunter2 path=prod;
+```
+
+So the parser performs **best-effort credential redaction** when it writes
+output. Detected credentials are replaced with `[SENSITIVE - REDACTED]`:
+
+- `password=` / `passwd=` / `pwd=` / `pw=` / `pass=` assignments, quoted or bare
+- SAS-encoded passwords (`{SAS002}...`) — `PROC PWENCODE` output is reversible,
+  so it is treated as plaintext
+- `%LET` macro assignments whose variable name looks password-like
+- Values under a password-like key
+
+Redaction is applied when a `project.json` is written and to output returned by
+the MCP server. `to_dict()` is a pure serializer and does **not** redact — call
+`pyegp_parser.redaction.redact()` yourself if you route output elsewhere, or
+pass `redact=False` to `serialize_project()` if you deliberately need
+byte-faithful code.
+
+Treat that as a convenience, not a security boundary:
+
+- Redaction targets credentials. It does **not** remove server names, library
+  paths, database or schema names, file paths, or usernames — all of which SAS
+  code and EG logs contain freely.
+- A credential in an unusual form (a custom macro, a value assembled at runtime,
+  an authentication-domain reference) will not match the patterns.
+- Column and macro-variable *names* containing "password" are deliberately left
+  intact, because they are schema metadata rather than secrets.
+
+**Review parser output before sharing it** outside your organisation, attaching
+it to an issue, or feeding it to an external service. If you find a credential
+that survives redaction, please report it privately as a vulnerability.