flo-lang 0.1.0__tar.gz

flo_lang-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.3
+Name: flo-lang
+Version: 0.1.0
+Summary: FLO reference implementation
+Requires-Dist: structlog>=22.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jsonschema>=4.26.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# FLO
+
+FLO is a declarative language for modeling organizational flow.
+
+It allows you to define processes in a minimal, versioned format and
+compile them into a canonical graph representation (FLO IR) for
+visualization and analysis.
+
+User documentation: `docs/User_Manual.md`
+
+------------------------------------------------------------------------
+
+## Example
+
+``` yaml
+spec_version: "0.1"
+
+process:
+  id: onboarding_v1
+  name: Client Onboarding
+  version: 1
+  owner:
+    id: ops_mgr
+    name: Ops Manager
+  business_units:
+    - id: sales
+      name: Sales
+    - id: ops
+      name: Operations
+
+steps:
+  - id: start
+    kind: start
+    name: Start
+
+  - id: collect_docs
+    kind: task
+    name: Collect Documents
+    lane: sales
+
+  - id: verify
+    kind: task
+    name: Verify Documents
+    lane: ops
+
+  - id: approved
+    kind: decision
+    name: Approved?
+    outcomes:
+      yes: finish
+      no: collect_docs
+
+  - id: finish
+    kind: end
+    name: Complete
+```
+
+------------------------------------------------------------------------
+
+## What FLO Provides
+
+-   Deterministic compilation to FLO IR\
+-   Structural and semantic validation\
+-   Graph projections: flowchart, swimlane, spaghetti map, SPPM\
+-   DOT and JSON exports\
+-   Ingredients list and movement report exports\
+-   Stable foundation for analytics
+
+------------------------------------------------------------------------
+
+## What FLO Does Not Provide
+
+-   Workflow execution\
+-   Task scheduling\
+-   Orchestration\
+-   Simulation engines (v0.x)
+
+------------------------------------------------------------------------
+
+## Architecture
+
+-   `src/flo/` --- compiler, validators, renderers, and CLI\
+-   `schema/` --- JSON schemas for FLO IR and types\
+-   `examples/` --- canonical reference examples\
+-   `tests/` --- unit, integration, and conformance tests\
+-   `docs/` --- user manual and design documents
+
+Downstream projects depend on FLO IR.
+
+------------------------------------------------------------------------
+
+## Source of Truth Hierarchy
+
+- Structural contract SSOT: `schema/flo_ir.json`
+- Semantic SSOT: `docs/design/IR.md`
+- User-facing summary: `README.md`
+
+Hierarchy policy and update workflow are defined in
+`docs/design/SSOT_Hierarchy.md`.
+
+------------------------------------------------------------------------
+
+## Current Semantic Constraints (v0.1)
+
+- Exactly one `start` node.
+- At least one `end` node.
+- All edge endpoints must resolve to declared node IDs.
+- Every non-`start` node must have at least one predecessor.
+- Every non-`end` node must have at least one successor.
+- Every node must be reachable from `start`.
+- Every node must be able to reach at least one `end` node.
+- `decision` nodes must have at least two outgoing transitions.
+
+------------------------------------------------------------------------
+
+## Versioning
+
+FLO follows semantic versioning at the spec level.
+
+-   v0.x: rapid iteration\
+-   v1.0: language stability
+
+------------------------------------------------------------------------
+
+## Philosophy
+
+FLO treats processes as first-class artifacts:
+
+-   Explicit\
+-   Versioned\
+-   Portable\
+-   Validatable
+
+It is a small language by design.
+
+------------------------------------------------------------------------
+
+## Schema Contract & Migration
+
+As of v0.1 the compiler emits a schema-shaped canonical IR and the
+runtime enforces that contract. The compiler must set `IR.schema_aligned`
+to `True` and `IR.to_dict()` will produce the top-level mapping with
+`process`, `nodes`, and `edges` fields required by the authoritative
+JSON Schema in `schema/flo_ir.json`.
+
+If you are upgrading from an earlier development version that relied on
+an internal IR translator, update any custom compiler integrations to
+emit the schema-shaped IR directly. The translator was intentionally
+removed; CI now validates example outputs using the same schema and
+will fail when the contract is violated.

flo_lang-0.1.0/README.md

@@ -0,0 +1,150 @@
+# FLO
+
+FLO is a declarative language for modeling organizational flow.
+
+It allows you to define processes in a minimal, versioned format and
+compile them into a canonical graph representation (FLO IR) for
+visualization and analysis.
+
+User documentation: `docs/User_Manual.md`
+
+------------------------------------------------------------------------
+
+## Example
+
+``` yaml
+spec_version: "0.1"
+
+process:
+  id: onboarding_v1
+  name: Client Onboarding
+  version: 1
+  owner:
+    id: ops_mgr
+    name: Ops Manager
+  business_units:
+    - id: sales
+      name: Sales
+    - id: ops
+      name: Operations
+
+steps:
+  - id: start
+    kind: start
+    name: Start
+
+  - id: collect_docs
+    kind: task
+    name: Collect Documents
+    lane: sales
+
+  - id: verify
+    kind: task
+    name: Verify Documents
+    lane: ops
+
+  - id: approved
+    kind: decision
+    name: Approved?
+    outcomes:
+      yes: finish
+      no: collect_docs
+
+  - id: finish
+    kind: end
+    name: Complete
+```
+
+------------------------------------------------------------------------
+
+## What FLO Provides
+
+-   Deterministic compilation to FLO IR\
+-   Structural and semantic validation\
+-   Graph projections: flowchart, swimlane, spaghetti map, SPPM\
+-   DOT and JSON exports\
+-   Ingredients list and movement report exports\
+-   Stable foundation for analytics
+
+------------------------------------------------------------------------
+
+## What FLO Does Not Provide
+
+-   Workflow execution\
+-   Task scheduling\
+-   Orchestration\
+-   Simulation engines (v0.x)
+
+------------------------------------------------------------------------
+
+## Architecture
+
+-   `src/flo/` --- compiler, validators, renderers, and CLI\
+-   `schema/` --- JSON schemas for FLO IR and types\
+-   `examples/` --- canonical reference examples\
+-   `tests/` --- unit, integration, and conformance tests\
+-   `docs/` --- user manual and design documents
+
+Downstream projects depend on FLO IR.
+
+------------------------------------------------------------------------
+
+## Source of Truth Hierarchy
+
+- Structural contract SSOT: `schema/flo_ir.json`
+- Semantic SSOT: `docs/design/IR.md`
+- User-facing summary: `README.md`
+
+Hierarchy policy and update workflow are defined in
+`docs/design/SSOT_Hierarchy.md`.
+
+------------------------------------------------------------------------
+
+## Current Semantic Constraints (v0.1)
+
+- Exactly one `start` node.
+- At least one `end` node.
+- All edge endpoints must resolve to declared node IDs.
+- Every non-`start` node must have at least one predecessor.
+- Every non-`end` node must have at least one successor.
+- Every node must be reachable from `start`.
+- Every node must be able to reach at least one `end` node.
+- `decision` nodes must have at least two outgoing transitions.
+
+------------------------------------------------------------------------
+
+## Versioning
+
+FLO follows semantic versioning at the spec level.
+
+-   v0.x: rapid iteration\
+-   v1.0: language stability
+
+------------------------------------------------------------------------
+
+## Philosophy
+
+FLO treats processes as first-class artifacts:
+
+-   Explicit\
+-   Versioned\
+-   Portable\
+-   Validatable
+
+It is a small language by design.
+
+------------------------------------------------------------------------
+
+## Schema Contract & Migration
+
+As of v0.1 the compiler emits a schema-shaped canonical IR and the
+runtime enforces that contract. The compiler must set `IR.schema_aligned`
+to `True` and `IR.to_dict()` will produce the top-level mapping with
+`process`, `nodes`, and `edges` fields required by the authoritative
+JSON Schema in `schema/flo_ir.json`.
+
+If you are upgrading from an earlier development version that relied on
+an internal IR translator, update any custom compiler integrations to
+emit the schema-shaped IR directly. The translator was intentionally
+removed; CI now validates example outputs using the same schema and
+will fail when the contract is violated.

flo_lang-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+[project]
+name = "flo-lang"
+version = "0.1.0"
+description = "FLO reference implementation"
+readme = "README.md"
+requires-python = ">=3.14"
+# Runtime dependencies
+dependencies = [
+    "structlog>=22.0",
+    "opentelemetry-api>=1.20.0",
+    "opentelemetry-sdk>=1.20.0",
+    "click>=8.1",
+    "rich>=13.0",
+    "pydantic>=2.0",
+    "PyYAML>=6.0",
+    "jsonschema>=4.26.0",
+]
+
+[project.optional-dependencies]
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "flo"
+module-root = "src"
+
+[project.scripts]
+flo = "flo.core.cli:main"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.5.1",
+    "pydocstyle>=6.3.0",
+    "pyright>=1.1.408",
+    "pytest>=9.0.2",
+    "ruff>=0.15.2",
+    "vulture>=2.14",
+    "radon>=5.1.0",
+    "pytest",
+    "pytest-cov>=4.0",
+    "import-linter>=2.10",
+]
+
+[tool.importlinter]
+# Import-linter rules for enforcing layer boundaries in the FLO project.
+# Note: import-linter expects a specific schema; this section encodes the
+# intended rules in pyproject.toml so CI and tooling can be wired to the
+# enforcement tool. Adjust keys below to match the import-linter version used.
+
+# The top-level package that import-linter should treat as the project's
+# root importable package. This must match the importable package name
+# (e.g. the `flo` package under `src/flo`).
+root_package = "flo"
+
+[tool.importlinter.layers]
+# Logical layer -> package prefix
+# Keep layer names small and map to specific package prefixes.
+core = "flo.core"
+adapters = "flo.adapters"
+compiler = "flo.compiler"
+render = "flo.render"
+services = "flo.services"
+
+[[tool.importlinter.rules]]
+name = "no_core_deps"
+description = "Core/CLI must not be imported by domain layers."
+modules = ["flo.core"]
+forbidden = ["flo.compiler", "flo.adapters", "flo.render", "flo.services"]
+
+[[tool.importlinter.rules]]
+name = "no_compiler_to_core_logging"
+description = "Compiler and adapters must not import core or logging setup."
+modules = ["flo.compiler", "flo.adapters"]
+forbidden = ["flo.core", "flo.services.logging"]
+
+[[tool.importlinter.rules]]
+name = "compiler_ir_independent"
+description = "Compiler IR package must be independent of higher-level concerns."
+modules = ["flo.compiler.ir"]
+forbidden = ["flo.core", "flo.adapters", "flo.render", "flo.services"]
+
+[[tool.importlinter.rules]]
+name = "render_optional"
+description = "Renderers should only depend on compiler layers and services, not on core internals."
+modules = ["flo.render"]
+forbidden = ["flo.core", "flo.services.logging"]
+
+[[tool.importlinter.rules]]
+name = "no_domain_import_core"
+description = "Domain layers must not import core entrypoint modules."
+modules = ["flo.adapters", "flo.compiler", "flo.render", "flo.services"]
+forbidden = ["flo.core"]
+
+[tool.coverage.report]
+omit = [
+    "src/flo/main.py",
+]

flo_lang-0.1.0/src/flo/__init__.py

@@ -0,0 +1,12 @@
+"""FLO package public surface.
+
+Keep the package import lightweight: importing the top-level package should
+not import CLI-related heavy dependencies (like `click`). Use the console
+entrypoint (`flo`) or import from `flo.core.cli` explicitly where needed,
+instead of exposing CLI modules at package import time.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []
+

flo_lang-0.1.0/src/flo/adapters/__init__.py

@@ -0,0 +1,41 @@
+"""Adapters package: YAML/other input adapters for FLO."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+import yaml
+
+
+from .yaml_loader import load_adapter_from_yaml
+from .composition import resolve_includes
+
+
+def parse_adapter(content: str, source_path: str | None = None) -> Dict[str, Any]:
+	"""Parse adapter content and return a validated mapping.
+
+	This dispatcher currently supports YAML input via
+	`load_adapter_from_yaml`. The loader returns an `AdapterModel`
+	which we convert to a plain dict (`model_dump`) so downstream
+	compiler code can continue to operate on mappings.
+	"""
+	try:
+		model = load_adapter_from_yaml(content)
+	except ValueError:
+		# If the content is YAML mapping-shaped FLO, return it directly.
+		# Otherwise preserve the previous permissive text fallback.
+		parsed = yaml.safe_load(content)
+		if isinstance(parsed, dict):
+			return resolve_includes(parsed, source_path=source_path)
+		return {"name": "parsed", "content": content}
+
+	# `model` supports `model_dump()` for Pydantic compatibility
+	try:
+		return model.model_dump()
+	except Exception:
+		# Fallback: if the model does not implement `model_dump`, try
+		# converting via `dict()` for compatibility with lightweight
+		# fallback models.
+		return dict(model)
+
+
+__all__ = ["load_adapter_from_yaml", "parse_adapter"]

flo_lang-0.1.0/src/flo/adapters/composition.py

@@ -0,0 +1,211 @@
+"""Composition helpers for include-based FLO source documents."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+_RESOURCE_KEYS = ("materials", "equipment", "locations", "workers")
+_LIST_KEYS = ("steps", "transitions", "edges", "lanes")
+
+
+def resolve_includes(document: dict[str, Any], source_path: str | None = None) -> dict[str, Any]:
+    """Resolve include directives and return a composed mapping.
+
+    Include syntax:
+
+    includes:
+      - relative/or/absolute/path.yaml
+    """
+    root_path = Path(source_path).resolve() if source_path else None
+    return _compose_document(document=document, current_path=root_path, include_stack=[])
+
+
+def _compose_document(
+    document: dict[str, Any],
+    current_path: Path | None,
+    include_stack: list[Path],
+) -> dict[str, Any]:
+    include_paths = _normalize_include_entries(document)
+    composed: dict[str, Any] = {}
+
+    for include_ref in include_paths:
+        include_path = _resolve_include_path(include_ref=include_ref, current_path=current_path)
+        include_doc = _load_include_mapping(include_path=include_path, include_stack=include_stack)
+        nested = _compose_document(
+            document=include_doc,
+            current_path=include_path,
+            include_stack=[*include_stack, include_path],
+        )
+        composed = _merge_documents(base=composed, incoming=nested)
+
+    local = dict(document)
+    local.pop("include", None)
+    local.pop("includes", None)
+    composed = _merge_documents(base=composed, incoming=local)
+
+    _validate_unique_ids(composed)
+    return composed
+
+
+def _normalize_include_entries(document: dict[str, Any]) -> list[str]:
+    include_value = document.get("includes")
+    if include_value is None:
+        include_value = document.get("include")
+
+    if include_value is None:
+        return []
+
+    if isinstance(include_value, str):
+        text = include_value.strip()
+        return [text] if text else []
+
+    if not isinstance(include_value, list):
+        raise ValueError("include/includes must be a string or list of strings")
+
+    out: list[str] = []
+    for idx, entry in enumerate(include_value):
+        if not isinstance(entry, str) or not entry.strip():
+            raise ValueError(f"includes[{idx}] must be a non-empty string path")
+        out.append(entry.strip())
+    return out
+
+
+def _resolve_include_path(include_ref: str, current_path: Path | None) -> Path:
+    raw = Path(include_ref)
+    if raw.is_absolute():
+        return raw.resolve()
+
+    base_dir = current_path.parent if current_path is not None else Path.cwd()
+    return (base_dir / raw).resolve()
+
+
+def _load_include_mapping(include_path: Path, include_stack: list[Path]) -> dict[str, Any]:
+    if include_path in include_stack:
+        chain = " -> ".join(str(path) for path in [*include_stack, include_path])
+        raise ValueError(f"include cycle detected: {chain}")
+
+    if not include_path.exists():
+        raise ValueError(f"include file not found: {include_path}")
+
+    try:
+        content = include_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ValueError(f"unable to read include file '{include_path}': {exc}") from exc
+
+    parsed = yaml.safe_load(content)
+    if not isinstance(parsed, dict):
+        raise ValueError(f"include file '{include_path}' must contain a YAML mapping")
+
+    return parsed
+
+
+def _merge_documents(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+
+    for key, value in incoming.items():
+        if key in _LIST_KEYS:
+            merged[key] = _merge_list_values(key=key, base_value=merged.get(key), incoming_value=value)
+            continue
+
+        if key in _RESOURCE_KEYS:
+            merged[key] = _merge_resource_values(key=key, base_value=merged.get(key), incoming_value=value)
+            continue
+
+        if key == "process":
+            merged[key] = _merge_process(base_value=merged.get(key), incoming_value=value)
+            continue
+
+        if key == "spec_version":
+            merged.setdefault(key, value)
+            continue
+
+        merged[key] = value
+
+    return merged
+
+
+def _merge_list_values(key: str, base_value: Any, incoming_value: Any) -> list[Any]:
+    if incoming_value is None:
+        return list(base_value) if isinstance(base_value, list) else []
+    if not isinstance(incoming_value, list):
+        raise ValueError(f"{key} must be a list")
+
+    out: list[Any] = []
+    if isinstance(base_value, list):
+        out.extend(base_value)
+    elif base_value is not None:
+        raise ValueError(f"{key} must be a list")
+
+    out.extend(incoming_value)
+    return out
+
+
+def _merge_resource_values(key: str, base_value: Any, incoming_value: Any) -> Any:
+    if base_value is None:
+        return incoming_value
+    if incoming_value is None:
+        return base_value
+
+    if isinstance(base_value, list) and isinstance(incoming_value, list):
+        return [*base_value, *incoming_value]
+
+    if isinstance(base_value, dict) and isinstance(incoming_value, dict):
+        merged = dict(base_value)
+        for child_key, child_value in incoming_value.items():
+            if child_key == "name":
+                merged.setdefault("name", child_value)
+                continue
+            if child_key in merged:
+                merged[child_key] = _merge_resource_values(
+                    key=f"{key}.{child_key}",
+                    base_value=merged[child_key],
+                    incoming_value=child_value,
+                )
+            else:
+                merged[child_key] = child_value
+        return merged
+
+    raise ValueError(f"{key} include merge type mismatch: expected list/list or dict/dict")
+
+
+def _merge_process(base_value: Any, incoming_value: Any) -> Any:
+    if base_value is None:
+        return incoming_value
+    if incoming_value is None:
+        return base_value
+    if not isinstance(base_value, dict) or not isinstance(incoming_value, dict):
+        raise ValueError("process must be an object when present")
+
+    merged = dict(base_value)
+    for key, value in incoming_value.items():
+        if key == "metadata" and isinstance(merged.get("metadata"), dict) and isinstance(value, dict):
+            merged["metadata"] = {**merged["metadata"], **value}
+            continue
+        merged[key] = value
+    return merged
+
+
+def _validate_unique_ids(document: dict[str, Any]) -> None:
+    _ensure_unique_id_list(document=document, key="steps")
+    _ensure_unique_id_list(document=document, key="lanes")
+
+
+def _ensure_unique_id_list(document: dict[str, Any], key: str) -> None:
+    value = document.get(key)
+    if not isinstance(value, list):
+        return
+
+    seen: set[str] = set()
+    for idx, item in enumerate(value):
+        if not isinstance(item, dict):
+            continue
+        item_id = item.get("id")
+        if item_id is None:
+            continue
+        item_id_text = str(item_id)
+        if item_id_text in seen:
+            raise ValueError(f"duplicate {key[:-1]} id '{item_id_text}' detected at {key}[{idx}]")
+        seen.add(item_id_text)

flo_lang-0.1.0/src/flo/adapters/models.py

@@ -0,0 +1,20 @@
+"""Adapter models for FLO inputs.
+
+Prefer Pydantic v2 models for runtime validation and parsing. If
+Pydantic isn't available the module will still import but some helper
+callers may choose a dict-based fallback.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class AdapterModel(BaseModel):
+    """Pydantic-backed AdapterModel used for adapter inputs."""
+
+    name: str
+    content: str
+
+    # Pydantic v2 provides `model_validate` and `model_dump` so callers
+    # can use the same API as before without needing a runtime fallback.