jcl-parser 2.0.3__tar.gz → 2.2.0__tar.gz

{jcl_parser-2.0.3 → jcl_parser-2.2.0}/PKG-INFO

@@ -1,17 +1,16 @@
 Metadata-Version: 2.4
 Name: jcl-parser
-Version: 2.0.3
+Version: 2.2.0
 Summary: Parse IBM JCL (Job Control Language) scripts into Python objects
 Author-email: Samuel Dion <sam94dion@gmail.com>
-License: AGPL-3.0-or-later
+License-Expression: AGPL-3.0-or-later
 Project-URL: Homepage, https://github.com/landparty/jcl-parser
 Project-URL: Repository, https://github.com/landparty/jcl-parser
-Project-URL: Documentation, https://github.com/landparty/jcl-parser/tree/main/docs
+Project-URL: Documentation, https://github.com/landparty/jcl-parser/blob/main/.okf/index.md
 Project-URL: Bug Reports, https://github.com/landparty/jcl-parser/issues
 Keywords: jcl,mainframe,parser,ibm,job-control-language
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
@@ -28,12 +27,14 @@ Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: coverage[toml]>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
 Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
-Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: ruff==0.17.3; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: jsonschema>=4.18; extra == "dev"
 Requires-Dist: tomli>=1.1.0; python_version < "3.11" and extra == "dev"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: pytest-cov>=4.0; extra == "test"
+Requires-Dist: jsonschema>=4.18; extra == "test"
 Requires-Dist: tomli>=1.1.0; python_version < "3.11" and extra == "test"
 Provides-Extra: profiling
 Requires-Dist: psutil>=5.9; extra == "profiling"
@@ -50,7 +51,8 @@ Python library for parsing IBM z/OS JCL (Job Control Language) into structured `
 ## Install
 
 ```bash
-pip install -e ".[dev]"
+pip install jcl-parser        # from PyPI
+pip install -e ".[dev]"       # from a checkout, with the dev tools
 ```
 
 Requires Python 3.10+. No runtime dependencies.
@@ -58,11 +60,20 @@ Requires Python 3.10+. No runtime dependencies.
 ## Quick Start
 
 ```python
+from pathlib import Path
+
 import jclparser
 
-job = jclparser.parse_jcl(source)
+job = jclparser.parse_jcl(Path("PAYROLL.jcl"))  # a str is always JCL text, never a path
 print(job.name)
-print(job.steps[0].program)
+for step in jclparser.iter_execution_steps(job.steps):  # also walks IF/THEN/ELSE blocks
+    print(step.name, step.program or step.procedure)
+
+exploded = jclparser.explode_job(job)  # PROC expansion is a separate call
+errors = jclparser.validate_jcl(
+    Path("PAYROLL.jcl"), level="structure"
+)  # list[ParseError]
+print(job.to_json(indent=2))  # schema: jclparser.JOB_JSON_SCHEMA
 ```
 
 CLI:
@@ -71,7 +82,52 @@ CLI:
 jcl-parser FILE steps          # list all steps
 jcl-parser FILE --validate     # validate JCL
 jcl-parser FILE lint           # run lint rules
-jcl-parser FILE --json         # full parse result as JSON
+jcl-parser FILE --json         # full parse result as JSON (job.to_dict())
+jcl-parser --json-schema       # JSON Schema of that document
+jcl-parser DIR                 # cross-job dataset lineage of a directory of jobs
+jcl-parser DIR lineage mermaid # ... as a Mermaid graph (or `dot`)
+jcl-parser DIR lint --sarif    # lint every job of a directory, as SARIF
+jcl-lint jobs/ --fail-on warning --format sarif -o jcl.sarif   # CI / pre-commit
+```
+
+### Lint in CI
+
+Configure the rules in `pyproject.toml`, and switch one off for one statement
+with a comment:
+
+```toml
+[tool.jcl-parser.lint]
+ignore = ["JCL-LINT-002"]
+fail-on = "warning"
+[tool.jcl-parser.lint.severity]
+"JCL-LINT-004" = "warning"
+```
+
+```jcl
+//* jcl-lint: disable=JCL-LINT-001
+//MASTER   DD DSN=PROD.MASTER.FILE,DISP=SHR
+```
+
+pre-commit (`.pre-commit-config.yaml`):
+
+```yaml
+- repo: https://github.com/landparty/jcl-parser
+  rev: v2.2.0   # first release with the hook
+  hooks:
+    - id: jcl-lint
+```
+
+GitHub Actions (findings appear in code scanning):
+
+```yaml
+permissions:
+  security-events: write
+steps:
+  - uses: actions/checkout@v4
+  - uses: landparty/jcl-parser@v2.2.0   # first release with the action
+    with:
+      paths: jcl
+      glob: "**/*.jcl"
 ```
 
 ## Commands
@@ -83,7 +139,7 @@ pytest -m unit
 
 # Lint / format / type-check
 ruff check . && ruff format .
-mypy jclparser/
+python scripts/mypy_ratchet.py   # mypy strict against the known-error baseline, as CI runs it
 
 # Vendor sync (after changes to jclparser/) — rm first: plain `cp -r` nests
 # into dest/jclparser/jclparser/ and leaves stale files when dest exists
@@ -92,7 +148,9 @@ rm -rf ../backend/_vendor/jcl-parser/jclparser && cp -r jclparser/ ../backend/_v
 
 ## Documentation
 
-Full reference: [`.okf/index.md`](.okf/index.md)
+Full reference: [`.okf/index.md`](.okf/index.md). Contributors: start with [`CLAUDE.md`](CLAUDE.md)
+(commands, architecture, invariants) and [`.okf/development/invariants.md`](.okf/development/invariants.md).
+Changes are listed in [`CHANGELOG.md`](CHANGELOG.md) (releases) and [`.okf/log.md`](.okf/log.md).
 
 ## License
 

jcl_parser-2.2.0/README.md

@@ -0,0 +1,115 @@
+# jcl-parser
+
+Python library for parsing IBM z/OS JCL (Job Control Language) into structured `Job`, `Step`, and `DD` objects. Supports PROC expansion, validation, lint rules, SQL detection, and dataset lifecycle analysis.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Coverage](https://img.shields.io/badge/coverage-90%25%2B%20enforced-green.svg)](#commands)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
+
+## Install
+
+```bash
+pip install jcl-parser        # from PyPI
+pip install -e ".[dev]"       # from a checkout, with the dev tools
+```
+
+Requires Python 3.10+. No runtime dependencies.
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+import jclparser
+
+job = jclparser.parse_jcl(Path("PAYROLL.jcl"))  # a str is always JCL text, never a path
+print(job.name)
+for step in jclparser.iter_execution_steps(job.steps):  # also walks IF/THEN/ELSE blocks
+    print(step.name, step.program or step.procedure)
+
+exploded = jclparser.explode_job(job)  # PROC expansion is a separate call
+errors = jclparser.validate_jcl(
+    Path("PAYROLL.jcl"), level="structure"
+)  # list[ParseError]
+print(job.to_json(indent=2))  # schema: jclparser.JOB_JSON_SCHEMA
+```
+
+CLI:
+
+```bash
+jcl-parser FILE steps          # list all steps
+jcl-parser FILE --validate     # validate JCL
+jcl-parser FILE lint           # run lint rules
+jcl-parser FILE --json         # full parse result as JSON (job.to_dict())
+jcl-parser --json-schema       # JSON Schema of that document
+jcl-parser DIR                 # cross-job dataset lineage of a directory of jobs
+jcl-parser DIR lineage mermaid # ... as a Mermaid graph (or `dot`)
+jcl-parser DIR lint --sarif    # lint every job of a directory, as SARIF
+jcl-lint jobs/ --fail-on warning --format sarif -o jcl.sarif   # CI / pre-commit
+```
+
+### Lint in CI
+
+Configure the rules in `pyproject.toml`, and switch one off for one statement
+with a comment:
+
+```toml
+[tool.jcl-parser.lint]
+ignore = ["JCL-LINT-002"]
+fail-on = "warning"
+[tool.jcl-parser.lint.severity]
+"JCL-LINT-004" = "warning"
+```
+
+```jcl
+//* jcl-lint: disable=JCL-LINT-001
+//MASTER   DD DSN=PROD.MASTER.FILE,DISP=SHR
+```
+
+pre-commit (`.pre-commit-config.yaml`):
+
+```yaml
+- repo: https://github.com/landparty/jcl-parser
+  rev: v2.2.0   # first release with the hook
+  hooks:
+    - id: jcl-lint
+```
+
+GitHub Actions (findings appear in code scanning):
+
+```yaml
+permissions:
+  security-events: write
+steps:
+  - uses: actions/checkout@v4
+  - uses: landparty/jcl-parser@v2.2.0   # first release with the action
+    with:
+      paths: jcl
+      glob: "**/*.jcl"
+```
+
+## Commands
+
+```bash
+# Tests
+pytest
+pytest -m unit
+
+# Lint / format / type-check
+ruff check . && ruff format .
+python scripts/mypy_ratchet.py   # mypy strict against the known-error baseline, as CI runs it
+
+# Vendor sync (after changes to jclparser/) — rm first: plain `cp -r` nests
+# into dest/jclparser/jclparser/ and leaves stale files when dest exists
+rm -rf ../backend/_vendor/jcl-parser/jclparser && cp -r jclparser/ ../backend/_vendor/jcl-parser/jclparser
+```
+
+## Documentation
+
+Full reference: [`.okf/index.md`](.okf/index.md). Contributors: start with [`CLAUDE.md`](CLAUDE.md)
+(commands, architecture, invariants) and [`.okf/development/invariants.md`](.okf/development/invariants.md).
+Changes are listed in [`CHANGELOG.md`](CHANGELOG.md) (releases) and [`.okf/log.md`](.okf/log.md).
+
+## License
+
+GNU Affero General Public License v3.0 or later — Copyright © 2026 Samuel Dion. See [LICENSE](LICENSE).

{jcl_parser-2.0.3 → jcl_parser-2.2.0}/jcl_parser.egg-info/PKG-INFO

@@ -1,17 +1,16 @@
 Metadata-Version: 2.4
 Name: jcl-parser
-Version: 2.0.3
+Version: 2.2.0
 Summary: Parse IBM JCL (Job Control Language) scripts into Python objects
 Author-email: Samuel Dion <sam94dion@gmail.com>
-License: AGPL-3.0-or-later
+License-Expression: AGPL-3.0-or-later
 Project-URL: Homepage, https://github.com/landparty/jcl-parser
 Project-URL: Repository, https://github.com/landparty/jcl-parser
-Project-URL: Documentation, https://github.com/landparty/jcl-parser/tree/main/docs
+Project-URL: Documentation, https://github.com/landparty/jcl-parser/blob/main/.okf/index.md
 Project-URL: Bug Reports, https://github.com/landparty/jcl-parser/issues
 Keywords: jcl,mainframe,parser,ibm,job-control-language
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
@@ -28,12 +27,14 @@ Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: coverage[toml]>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
 Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
-Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: ruff==0.17.3; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: jsonschema>=4.18; extra == "dev"
 Requires-Dist: tomli>=1.1.0; python_version < "3.11" and extra == "dev"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: pytest-cov>=4.0; extra == "test"
+Requires-Dist: jsonschema>=4.18; extra == "test"
 Requires-Dist: tomli>=1.1.0; python_version < "3.11" and extra == "test"
 Provides-Extra: profiling
 Requires-Dist: psutil>=5.9; extra == "profiling"
@@ -50,7 +51,8 @@ Python library for parsing IBM z/OS JCL (Job Control Language) into structured `
 ## Install
 
 ```bash
-pip install -e ".[dev]"
+pip install jcl-parser        # from PyPI
+pip install -e ".[dev]"       # from a checkout, with the dev tools
 ```
 
 Requires Python 3.10+. No runtime dependencies.
@@ -58,11 +60,20 @@ Requires Python 3.10+. No runtime dependencies.
 ## Quick Start
 
 ```python
+from pathlib import Path
+
 import jclparser
 
-job = jclparser.parse_jcl(source)
+job = jclparser.parse_jcl(Path("PAYROLL.jcl"))  # a str is always JCL text, never a path
 print(job.name)
-print(job.steps[0].program)
+for step in jclparser.iter_execution_steps(job.steps):  # also walks IF/THEN/ELSE blocks
+    print(step.name, step.program or step.procedure)
+
+exploded = jclparser.explode_job(job)  # PROC expansion is a separate call
+errors = jclparser.validate_jcl(
+    Path("PAYROLL.jcl"), level="structure"
+)  # list[ParseError]
+print(job.to_json(indent=2))  # schema: jclparser.JOB_JSON_SCHEMA
 ```
 
 CLI:
@@ -71,7 +82,52 @@ CLI:
 jcl-parser FILE steps          # list all steps
 jcl-parser FILE --validate     # validate JCL
 jcl-parser FILE lint           # run lint rules
-jcl-parser FILE --json         # full parse result as JSON
+jcl-parser FILE --json         # full parse result as JSON (job.to_dict())
+jcl-parser --json-schema       # JSON Schema of that document
+jcl-parser DIR                 # cross-job dataset lineage of a directory of jobs
+jcl-parser DIR lineage mermaid # ... as a Mermaid graph (or `dot`)
+jcl-parser DIR lint --sarif    # lint every job of a directory, as SARIF
+jcl-lint jobs/ --fail-on warning --format sarif -o jcl.sarif   # CI / pre-commit
+```
+
+### Lint in CI
+
+Configure the rules in `pyproject.toml`, and switch one off for one statement
+with a comment:
+
+```toml
+[tool.jcl-parser.lint]
+ignore = ["JCL-LINT-002"]
+fail-on = "warning"
+[tool.jcl-parser.lint.severity]
+"JCL-LINT-004" = "warning"
+```
+
+```jcl
+//* jcl-lint: disable=JCL-LINT-001
+//MASTER   DD DSN=PROD.MASTER.FILE,DISP=SHR
+```
+
+pre-commit (`.pre-commit-config.yaml`):
+
+```yaml
+- repo: https://github.com/landparty/jcl-parser
+  rev: v2.2.0   # first release with the hook
+  hooks:
+    - id: jcl-lint
+```
+
+GitHub Actions (findings appear in code scanning):
+
+```yaml
+permissions:
+  security-events: write
+steps:
+  - uses: actions/checkout@v4
+  - uses: landparty/jcl-parser@v2.2.0   # first release with the action
+    with:
+      paths: jcl
+      glob: "**/*.jcl"
 ```
 
 ## Commands
@@ -83,7 +139,7 @@ pytest -m unit
 
 # Lint / format / type-check
 ruff check . && ruff format .
-mypy jclparser/
+python scripts/mypy_ratchet.py   # mypy strict against the known-error baseline, as CI runs it
 
 # Vendor sync (after changes to jclparser/) — rm first: plain `cp -r` nests
 # into dest/jclparser/jclparser/ and leaves stale files when dest exists
@@ -92,7 +148,9 @@ rm -rf ../backend/_vendor/jcl-parser/jclparser && cp -r jclparser/ ../backend/_v
 
 ## Documentation
 
-Full reference: [`.okf/index.md`](.okf/index.md)
+Full reference: [`.okf/index.md`](.okf/index.md). Contributors: start with [`CLAUDE.md`](CLAUDE.md)
+(commands, architecture, invariants) and [`.okf/development/invariants.md`](.okf/development/invariants.md).
+Changes are listed in [`CHANGELOG.md`](CHANGELOG.md) (releases) and [`.okf/log.md`](.okf/log.md).
 
 ## License
 

{jcl_parser-2.0.3 → jcl_parser-2.2.0}/jcl_parser.egg-info/SOURCES.txt

@@ -9,12 +9,14 @@ jcl_parser.egg-info/requires.txt
 jcl_parser.egg-info/top_level.txt
 jclparser/__init__.py
 jclparser/__main__.py
+jclparser/_include_origins.py
 jclparser/_job_builder.py
 jclparser/_model_factories.py
 jclparser/_post_parse.py
 jclparser/_source_scanner.py
 jclparser/_statement_parser.py
 jclparser/builtin_procs.py
+jclparser/checks.py
 jclparser/cli.py
 jclparser/condition_parser.py
 jclparser/continuation_handler.py
@@ -24,6 +26,7 @@ jclparser/explosion.py
 jclparser/include_loader.py
 jclparser/jcl_file_type.py
 jclparser/jes_statements.py
+jclparser/lineage.py
 jclparser/metrics.py
 jclparser/model.py
 jclparser/parameter_ast.py
@@ -33,6 +36,7 @@ jclparser/proc_loader.py
 jclparser/profiling.py
 jclparser/py.typed
 jclparser/rc_analysis.py
+jclparser/serialization.py
 jclparser/sql_detector.py
 jclparser/system_symbols.py
 jclparser/utils.py
@@ -42,6 +46,7 @@ jclparser/lint/base.py
 jclparser/lint/config.py
 jclparser/lint/rules.py
 jclparser/lint/runner.py
+jclparser/lint/suppress.py
 jclparser/plugins/__init__.py
 jclparser/plugins/base.py
 jclparser/program_profiles/__init__.py

{jcl_parser-2.0.3 → jcl_parser-2.2.0}/jcl_parser.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
+jcl-lint = jclparser.checks:lint_main
 jcl-parser = jclparser.cli:main

{jcl_parser-2.0.3 → jcl_parser-2.2.0}/jcl_parser.egg-info/requires.txt

@@ -4,8 +4,9 @@ pytest>=7.0
 coverage[toml]>=7.0
 pytest-cov>=4.0
 pytest-benchmark>=4.0
-ruff>=0.1
+ruff==0.17.3
 mypy>=1.0
+jsonschema>=4.18
 
 [dev:python_version < "3.11"]
 tomli>=1.1.0
@@ -16,6 +17,7 @@ psutil>=5.9
 [test]
 pytest>=7.0
 pytest-cov>=4.0
+jsonschema>=4.18
 
 [test:python_version < "3.11"]
 tomli>=1.1.0

{jcl_parser-2.0.3 → jcl_parser-2.2.0}/jclparser/__init__.py

@@ -20,7 +20,7 @@ application, for example::
 import logging as _logging
 
 # Package metadata
-__version__ = "2.0.3"  # x-release-please-version
+__version__ = "2.2.0"  # x-release-please-version
 __author__ = "JCL Parser Team"
 __description__ = "Parse IBM JCL scripts into Python objects"
 
@@ -66,7 +66,9 @@ from .include_loader import (
     DictMemberLoader,
     IncludeMemberLoader,
     JCLLIBMemberLoader,
+    LineOrigin,
     resolve_includes,
+    resolve_includes_with_origins,
 )
 from .jcl_file_type import (
     FileType,
@@ -88,6 +90,15 @@ from .jes_statements import (
     XmitStatement,
     parse_jes_control,
 )
+from .lineage import (
+    DatasetLineage,
+    DatasetUse,
+    JobDependency,
+    JobStream,
+    LineageReport,
+    build_lineage,
+    load_job_stream,
+)
 from .lint import (
     LintConfig,
     LintRule,
@@ -100,7 +111,16 @@ from .lint import (
     to_sarif as lint_to_sarif,
 )
 from .metrics import JobMetrics, compute_metrics
-from .model import DDStatement, Job, OutputStatement, Parameter, Statement, Step
+from .model import (
+    ConditionalBlock,
+    DDStatement,
+    Job,
+    OutputStatement,
+    Parameter,
+    Statement,
+    Step,
+    iter_execution_steps,
+)
 from .parser import parse_jcl, parse_statement, validate_jcl
 from .plugins import (
     ParserConfig,
@@ -132,6 +152,12 @@ from .rc_analysis import (
     FeasibilityReport,
     compute_feasible_paths,
 )
+from .serialization import (
+    JOB_JSON_SCHEMA,
+    SCHEMA_VERSION,
+    job_to_dict,
+    job_to_json,
+)
 from .sql_detector import (
     DB2_PROGRAMS,
     SQLDetectionResult,
@@ -156,9 +182,6 @@ from .validators import (
 # default unless the consuming application configures handlers.
 _logging.getLogger(__name__).addHandler(_logging.NullHandler())
 
-# Initialize global plugin registry
-_registry = get_plugin_registry()
-
 # Public API - what gets imported with "from jclparser import *"
 __all__ = [  # noqa: RUF022 — grouped by API tier, not alphabetically
     # ── Tier 1: Stable public API ─────────────────────────────────────────────
@@ -172,6 +195,8 @@ __all__ = [  # noqa: RUF022 — grouped by API tier, not alphabetically
     "Parameter",
     "Statement",
     "OutputStatement",
+    "ConditionalBlock",
+    "iter_execution_steps",
     "JCLParseError",
     "JCLSyntaxError",
     "JCLValidationError",
@@ -230,7 +255,22 @@ __all__ = [  # noqa: RUF022 — grouped by API tier, not alphabetically
     "IncludeMemberLoader",
     "DictMemberLoader",
     "JCLLIBMemberLoader",
+    "LineOrigin",
     "resolve_includes",
+    "resolve_includes_with_origins",
+    # ── Tier 2: JSON export ───────────────────────────────────────────────────
+    "job_to_dict",
+    "job_to_json",
+    "JOB_JSON_SCHEMA",
+    "SCHEMA_VERSION",
+    # ── Tier 2: Cross-job dataset lineage ─────────────────────────────────────
+    "load_job_stream",
+    "build_lineage",
+    "JobStream",
+    "LineageReport",
+    "DatasetLineage",
+    "DatasetUse",
+    "JobDependency",
     # ── Tier 2: Dataset lifecycle analysis ───────────────────────────────────
     "DatasetEvent",
     "analyze_dataset_lifecycle",