ofplang-validate 0.1.0__tar.gz

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

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[test]"
+      - run: pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check ofplang tests
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: mypy

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

@@ -0,0 +1,93 @@
+name: Publish
+
+# Tag-driven release via PyPI Trusted Publishing (OIDC) — no API tokens.
+#
+# Version comes from the pushed git tag via setuptools-scm (`v0.1.0` -> 0.1.0).
+# Routing:
+#   - a pre-release tag containing `rc` (e.g. v0.1.0rc1) -> TestPyPI (rehearsal)
+#   - any other `v*` tag (e.g. v0.1.0)                    -> PyPI (production)
+#   - manual workflow_dispatch -> choose the target explicitly (run it from a
+#     tagged commit, else setuptools-scm yields a dev+local version PyPI rejects)
+#
+# PyPI-side setup (done once, by the project owner): register a Trusted Publisher
+# for owner=ofplang, repo=validate, workflow=publish.yml, environment=pypi
+# (and environment=testpypi on TestPyPI). First release: register as "pending".
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Publish target"
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm derives the version from tags + history.
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build twine
+      - run: python -m build
+      - run: twine check dist/*
+      # Guard against ambiguous tags: the built version (from setuptools-scm) must
+      # equal the pushed tag — e.g. tag v0.1.0 must build 0.1.0. Catches a commit
+      # carrying two tags (an rc and a release) where git describe can resolve to
+      # the wrong one and publish the wrong artifact.
+      - name: Verify built version matches tag
+        if: startsWith(github.ref, 'refs/tags/')
+        shell: bash
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          built="$(ls dist/*.tar.gz | sed -E 's#.*/[^/]*-([0-9][^-]*)\.tar\.gz#\1#')"
+          echo "tag=$tag built=$built"
+          if [ "$tag" != "$built" ]; then
+            echo "::error::built version $built != tag $tag (ambiguous or misplaced tag?)"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    if: >-
+      github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+      || (github.event_name == 'push' && contains(github.ref_name, 'rc'))
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: build
+    if: >-
+      github.event_name == 'workflow_dispatch' && inputs.target == 'pypi'
+      || (github.event_name == 'push' && !contains(github.ref_name, 'rc'))
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ofplang_validate-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Local working notes, not part of the published project (until explicitly committed).
+CLAUDE.md
+dev-notes/

ofplang_validate-0.1.0/LICENSE

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

ofplang_validate-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: ofplang-validate
+Version: 0.1.0
+Summary: Object-flow programming language v0 validator
+Author-email: Kazunari Kaizu <kwaizu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ofplang/validate
+Project-URL: Repository, https://github.com/ofplang/validate
+Keywords: ofplang,dataflow,workflow,validator,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Dynamic: license-file
+
+# ofplang validate
+
+[![CI](https://github.com/ofplang/validate/actions/workflows/ci.yml/badge.svg)](https://github.com/ofplang/validate/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ofplang-validate.svg)](https://pypi.org/project/ofplang-validate/)
+
+A validator for **Object-flow Programming Language v0** — a YAML-based dataflow
+workflow IR with linear Object tracking. The language is defined in the
+[ofplang/spec](https://github.com/ofplang/spec) repository.
+
+The validator checks that a document is well-formed portable v0: structure and
+types, the feature model, linear Object tracking, structured nodes, contracts,
+and scheduling policies. It reports findings as stable **error codes** rather
+than free text, so results are easy to consume in tests and tooling.
+
+## Install
+
+```sh
+pip install ofplang-validate
+```
+
+Requires Python 3.10+. The only runtime dependency is PyYAML. For development,
+install editable with the test extra from a clone:
+
+```sh
+pip install -e ".[test]"
+```
+
+## Command line
+
+```sh
+ofp-validate <file>...                 # or: python -m ofplang.validate <file>...
+ofp-validate --mode extension-tolerant doc.yaml
+ofp-validate --format json doc.yaml
+```
+
+Options: `--mode {strict,extension-tolerant}`, `--format {text,json}`,
+`-q/--quiet`, `--no-color`.
+
+Exit codes: `0` all valid, `1` validation errors found, `2` usage/input error.
+
+```
+$ ofp-validate workflow.yaml
+workflow.yaml:7:15: error unknown_type  processes.main.inputs.x.type  unknown type in 'Foo'
+1 error in 1 of 1 file
+```
+
+Diagnostics carry a `file:line:col` source position (an imported fragment's own
+file when the problem is inside an `$import`); `--format json` includes
+`file`/`line`/`col` fields.
+
+This tool is also intended to be exposed as the `validate` subcommand of the
+umbrella `ofp` CLI (a separate repository in the `ofplang` organization).
+
+## Library
+
+```python
+from ofplang.validate import validate
+
+result = validate("workflow.yaml", mode="strict")
+if not result.ok:
+    for d in result.diagnostics:
+        print(d.code, d.path, d.message)
+```
+
+`validate(source, *, mode="strict")` returns a `ValidationResult` with `.ok` and
+`.diagnostics` (each a `Diagnostic(code, message, path, file, line, col)`). The
+validator collects all independent findings rather than stopping at the first;
+only a YAML parse or `$import` resolution failure is terminal.
+
+The package lives under the `ofplang` PEP 420 namespace (`ofplang.validate`),
+shared across the organization's tools.
+
+## Scope
+
+Covers graph-time validation of portable v0. Runtime failures, and run/data-phase
+preflight checks, are out of scope (spec §6.2, §25). Two modes are supported:
+`strict` (portable v0) and `extension-tolerant` (accepts `x-` extension keys).
+
+## Tests
+
+The behavior is pinned by a spec-derived conformance suite that matches on error
+codes (see [tests/conformance/README.md](tests/conformance/README.md)).
+
+```sh
+pytest                         # run everything
+OFPLANG_STRICT_TESTS=1 pytest  # full contract, no pending escapes
+```

ofplang_validate-0.1.0/README.md

@@ -0,0 +1,87 @@
+# ofplang validate
+
+[![CI](https://github.com/ofplang/validate/actions/workflows/ci.yml/badge.svg)](https://github.com/ofplang/validate/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ofplang-validate.svg)](https://pypi.org/project/ofplang-validate/)
+
+A validator for **Object-flow Programming Language v0** — a YAML-based dataflow
+workflow IR with linear Object tracking. The language is defined in the
+[ofplang/spec](https://github.com/ofplang/spec) repository.
+
+The validator checks that a document is well-formed portable v0: structure and
+types, the feature model, linear Object tracking, structured nodes, contracts,
+and scheduling policies. It reports findings as stable **error codes** rather
+than free text, so results are easy to consume in tests and tooling.
+
+## Install
+
+```sh
+pip install ofplang-validate
+```
+
+Requires Python 3.10+. The only runtime dependency is PyYAML. For development,
+install editable with the test extra from a clone:
+
+```sh
+pip install -e ".[test]"
+```
+
+## Command line
+
+```sh
+ofp-validate <file>...                 # or: python -m ofplang.validate <file>...
+ofp-validate --mode extension-tolerant doc.yaml
+ofp-validate --format json doc.yaml
+```
+
+Options: `--mode {strict,extension-tolerant}`, `--format {text,json}`,
+`-q/--quiet`, `--no-color`.
+
+Exit codes: `0` all valid, `1` validation errors found, `2` usage/input error.
+
+```
+$ ofp-validate workflow.yaml
+workflow.yaml:7:15: error unknown_type  processes.main.inputs.x.type  unknown type in 'Foo'
+1 error in 1 of 1 file
+```
+
+Diagnostics carry a `file:line:col` source position (an imported fragment's own
+file when the problem is inside an `$import`); `--format json` includes
+`file`/`line`/`col` fields.
+
+This tool is also intended to be exposed as the `validate` subcommand of the
+umbrella `ofp` CLI (a separate repository in the `ofplang` organization).
+
+## Library
+
+```python
+from ofplang.validate import validate
+
+result = validate("workflow.yaml", mode="strict")
+if not result.ok:
+    for d in result.diagnostics:
+        print(d.code, d.path, d.message)
+```
+
+`validate(source, *, mode="strict")` returns a `ValidationResult` with `.ok` and
+`.diagnostics` (each a `Diagnostic(code, message, path, file, line, col)`). The
+validator collects all independent findings rather than stopping at the first;
+only a YAML parse or `$import` resolution failure is terminal.
+
+The package lives under the `ofplang` PEP 420 namespace (`ofplang.validate`),
+shared across the organization's tools.
+
+## Scope
+
+Covers graph-time validation of portable v0. Runtime failures, and run/data-phase
+preflight checks, are out of scope (spec §6.2, §25). Two modes are supported:
+`strict` (portable v0) and `extension-tolerant` (accepts `x-` extension keys).
+
+## Tests
+
+The behavior is pinned by a spec-derived conformance suite that matches on error
+codes (see [tests/conformance/README.md](tests/conformance/README.md)).
+
+```sh
+pytest                         # run everything
+OFPLANG_STRICT_TESTS=1 pytest  # full contract, no pending escapes
+```

ofplang_validate-0.1.0/ofplang/validate/__init__.py

@@ -0,0 +1,19 @@
+"""ofplang.validate -- validator for Object-flow Programming Language v0."""
+
+from ofplang.validate.validator import (
+    EXTENSION_TOLERANT,
+    MODES,
+    STRICT,
+    Diagnostic,
+    ValidationResult,
+    validate,
+)
+
+__all__ = [
+    "Diagnostic",
+    "ValidationResult",
+    "validate",
+    "STRICT",
+    "EXTENSION_TOLERANT",
+    "MODES",
+]

ofplang_validate-0.1.0/ofplang/validate/__main__.py

@@ -0,0 +1,9 @@
+"""Enable `python -m ofplang <file>...`.
+
+Intent: mirror the console-script entry point so the CLI is reachable without an
+installed script, which is convenient in dev checkouts and CI.
+"""
+
+from ofplang.validate.cli import main
+
+raise SystemExit(main())

ofplang_validate-0.1.0/ofplang/validate/cli.py

@@ -0,0 +1,178 @@
+"""Command-line interface for the ofplang v0 validator.
+
+Intent: this is a thin presentation layer over :func:`ofplang.validate.validate` — it
+does no validation itself, it only parses arguments, drives the library over one
+or more files, and renders results. Keeping all logic in the library means the
+CLI cannot drift from the conformance-tested behavior.
+
+Usage:
+    ofp-validate [--mode {strict,extension-tolerant}] [--format {text,json}]
+                 [-q/--quiet] [--no-color] <file>...
+
+Also invocable as `python -m ofplang.validate`, and (once installed) as the
+`validate` subcommand of the umbrella `ofp` CLI.
+
+Exit codes (linter convention):
+    0  every file is valid
+    1  at least one file has validation errors
+    2  usage / input error (bad arguments, missing input file)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ofplang.validate import validate
+from ofplang.validate.validator import EXTENSION_TOLERANT, STRICT, ValidationResult
+
+# Exit codes are part of the CLI contract (scripts/CI depend on them).
+EXIT_OK = 0
+EXIT_INVALID = 1
+EXIT_USAGE = 2
+
+# ANSI colors, applied only when writing to a TTY and not disabled.
+_RED = "\033[31m"
+_GREEN = "\033[32m"
+_DIM = "\033[2m"
+_RESET = "\033[0m"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ofp-validate",
+        description="Validate ofplang v0 documents.",
+    )
+    parser.add_argument("paths", nargs="+", metavar="FILE", help="document(s) to validate")
+    parser.add_argument(
+        "--mode",
+        choices=[STRICT, EXTENSION_TOLERANT],
+        default=STRICT,
+        help="validation mode (default: strict)",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="output format (default: text)",
+    )
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="suppress per-diagnostic lines; show only the summary",
+    )
+    parser.add_argument("--no-color", action="store_true", help="disable ANSI color output")
+    return parser
+
+
+def _color_enabled(no_color: bool) -> bool:
+    # Color only when explicitly allowed AND attached to a terminal, so piped or
+    # redirected output stays clean and parseable.
+    return not no_color and sys.stdout.isatty()
+
+
+def _render_text(results: list[tuple[str, ValidationResult]], quiet: bool, color: bool) -> str:
+    """Human-oriented report. One block per file, then a one-line summary."""
+    def c(text: str, code: str) -> str:
+        return f"{code}{text}{_RESET}" if color else text
+
+    lines: list[str] = []
+    total_errors = 0
+    invalid_files = 0
+    multi = len(results) > 1
+
+    for path, result in results:
+        if result.ok:
+            # Only announce OK files explicitly when validating several, so
+            # single-file runs stay terse.
+            if not quiet and multi:
+                lines.append(f"{path}: {c('OK', _GREEN)}")
+            continue
+        invalid_files += 1
+        total_errors += len(result.diagnostics)
+        if multi:
+            lines.append(f"{path}:")
+        if not quiet:
+            for d in result.diagnostics:
+                # Prefer a concrete source position as the locator; fall back to
+                # the logical path. When both exist, show the path as a dim
+                # trailing detail (position primary, path for context).
+                if d.location:
+                    locator = d.location
+                    detail = f"  {c(d.path, _DIM)}" if d.path else ""
+                else:
+                    locator = d.path or "<root>"
+                    detail = ""
+                msg = f"  {d.message}" if d.message else ""
+                indent = "  " if multi else ""
+                lines.append(f"{indent}{locator}: {c('error', _RED)} {d.code}{detail}{msg}")
+
+    if total_errors == 0:
+        lines.append(
+            c(f"all valid ({len(results)} file{'s' if len(results) != 1 else ''})", _GREEN)
+        )
+    else:
+        lines.append(
+            c(f"{total_errors} error{'s' if total_errors != 1 else ''} in "
+              f"{invalid_files} of {len(results)} file{'s' if len(results) != 1 else ''}", _RED)
+        )
+    return "\n".join(lines)
+
+
+def _render_json(results: list[tuple[str, ValidationResult]]) -> str:
+    """Machine-readable report for CI/editor integration."""
+    payload = {
+        "ok": all(r.ok for _, r in results),
+        "results": [
+            {
+                "file": path,
+                "ok": result.ok,
+                "diagnostics": [
+                    {
+                        "code": d.code,
+                        "path": d.path,
+                        "message": d.message,
+                        "file": d.file,
+                        "line": d.line,
+                        "col": d.col,
+                    }
+                    for d in result.diagnostics
+                ],
+            }
+            for path, result in results
+        ],
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    # Pre-check inputs so a mistyped/missing path is a usage error (exit 2)
+    # rather than being reported as an in-document diagnostic.
+    missing = [p for p in args.paths if not Path(p).is_file()]
+    if missing:
+        for p in missing:
+            print(f"ofp-validate: cannot open {p!r}: no such file", file=sys.stderr)
+        return EXIT_USAGE
+
+    # Validate each file via the library (the sole source of truth).
+    results: list[tuple[str, ValidationResult]] = [
+        (p, validate(p, mode=args.mode)) for p in args.paths
+    ]
+
+    if args.format == "json":
+        print(_render_json(results))
+    else:
+        print(_render_text(results, args.quiet, _color_enabled(args.no_color)))
+
+    # Exit code reflects the worst outcome across all inputs.
+    return EXIT_OK if all(r.ok for _, r in results) else EXIT_INVALID
+
+
+if __name__ == "__main__":  # pragma: no cover - module entry
+    raise SystemExit(main())