syncspec 0.1.0__tar.gz

syncspec-0.1.0/LICENSE

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

syncspec-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: syncspec
+Version: 0.1.0
+Summary: Transclusion for Spec Driven Development
+Author-email: Kim Jarvis <kim.jarvis@tpfsystems.com>
+License: MIT
+Project-URL: Homepage, https://github.com/kimjarvis/syncspec
+Project-URL: Issues, https://github.com/kimjarvis/syncspec/issues
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: networkx>=2.5
+Requires-Dist: pydot>=1.4.2
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+# syncspec
+
+Transclusion for Spec Driven Development
+
+# Install
+
+```bash
+pip install syncspec
+```
+
+# Command line usage
+
+```bash
+syncspec -i specs/
+```
+
+# Python interface
+
+```python
+from syncspec import syncspec
+
+syncspec("specs/")
+```

syncspec-0.1.0/README.md

@@ -0,0 +1,23 @@
+# syncspec
+
+Transclusion for Spec Driven Development
+
+# Install
+
+```bash
+pip install syncspec
+```
+
+# Command line usage
+
+```bash
+syncspec -i specs/
+```
+
+# Python interface
+
+```python
+from syncspec import syncspec
+
+syncspec("specs/")
+```

syncspec-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "syncspec"
+version = "0.1.0"
+description = "Transclusion for Spec Driven Development"
+readme = "README.md"
+authors = [
+    {name = "Kim Jarvis", email = "kim.jarvis@tpfsystems.com"}
+]
+license = {text = "MIT"}
+requires-python = ">=3.6"
+dependencies = [
+    "jinja2>=3.0.0",      # Compatible with Python 3.6+
+    "networkx>=2.5",       # networkx 3.x requires Python >=3.8, so use older version
+    "pydot>=1.4.2",       # Compatible with Python 3.6+
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=6.0.0",      # pytest 9.x requires Python >=3.8
+]
+
+[project.urls]
+Homepage = "https://github.com/kimjarvis/syncspec"
+Issues = "https://github.com/kimjarvis/syncspec/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["syncspec*"]

syncspec-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

syncspec-0.1.0/src/syncspec/__init__.py

@@ -0,0 +1,6 @@
+"""SyncSpec - Your package description"""
+
+from .function import syncspec
+
+__all__ = ['syncspec']
+__version__ = "0.1.0"

syncspec-0.1.0/src/syncspec/block.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+from typing import Dict, Any, Optional
+
+@dataclass
+class Block:
+    directive: Dict[str, Any]
+    prefix: str
+    suffix: str
+    text: str
+    line_number: int
+    name: str

syncspec-0.1.0/src/syncspec/combine_errors_context.py

@@ -0,0 +1,6 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict
+
+@dataclass
+class CombineErrorsContext:
+	text: str

syncspec-0.1.0/src/syncspec/combine_nodes.py

@@ -0,0 +1,19 @@
+from src.syncspec.node import Node
+from src.syncspec.edge import Edge
+from src.syncspec.combine_nodes_context import CombineNodesContext
+
+
+def make_combine_nodes(context: CombineNodesContext):
+    def combine_nodes(node: Node) -> Edge:
+        dtype = node.directive_type
+        node_id = f"{dtype}_{node.name}_{node.line_number}"
+        label = f"{dtype}\n{node.name}\n:{node.line_number}"
+        colors = {"source": "lightblue", "export": "red", "include": "lightgreen", "import": "yellow"}
+
+        context.G.add_node(
+            node_id, key=node.key, directive_type=dtype, label=label,
+            shape="rectangle", style="filled", fillcolor=colors.get(dtype, "white")
+        )
+        return Edge(dtype, node.key, node.line_number, node.name)
+
+    return combine_nodes

syncspec-0.1.0/src/syncspec/combine_nodes_context.py

@@ -0,0 +1,7 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict
+import networkx as nx
+
+@dataclass
+class CombineNodesContext:
+	G: nx.DiGraph

syncspec-0.1.0/src/syncspec/combine_strings.py

@@ -0,0 +1,9 @@
+from src.syncspec.string import String
+from src.syncspec.combine_strings_context import CombineStringsContext
+
+
+def make_combine_strings(context: CombineStringsContext):
+    def combine_strings(string: String) -> None:
+        context.text += string.text
+
+    return combine_strings

syncspec-0.1.0/src/syncspec/combine_strings_context.py

@@ -0,0 +1,6 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict
+
+@dataclass
+class CombineStringsContext:
+    text: str

syncspec-0.1.0/src/syncspec/create_blocks.py

@@ -0,0 +1,81 @@
+import logging
+import json
+from typing import Union, Dict, Any
+
+from src.syncspec.utilities import format_error
+from src.syncspec.fragment import Fragment
+from src.syncspec.block import Block
+from src.syncspec.string import String
+from src.syncspec.create_blocks_context import CreateBlocksContext
+
+
+def _parse_json_content(text: str) -> Dict[str, Any]:
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        try:
+            data = json.loads('{' + text + '}')
+        except json.JSONDecodeError:
+            raise ValueError("Invalid JSON structure")
+
+    if not isinstance(data, dict):
+        raise ValueError("JSON root must be an object")
+    if any(k is None for k in data.keys()):
+        raise ValueError("Dictionary contains None keys")
+    return data
+
+
+def make_create_blocks(context: CreateBlocksContext):
+    def create_blocks(fragment: Fragment) -> Union[Block, String, None]:
+        state = context.index % 4
+        result: Union[Block, String, None] = None
+
+        if state == 0:
+            result = String(text=fragment.text, line_number=fragment.line_number, name=fragment.name)
+
+        elif state == 1:
+            context.prefix = fragment.text
+            context.prefix_line_number = fragment.line_number
+            # Spec requests context.prefix_name = fragment.name, but field missing in class.
+
+            try:
+                context.directive = _parse_json_content(fragment.text)
+                context.prefix_valid = True
+                result = None
+            except (json.JSONDecodeError, ValueError):
+                context.prefix_valid = False
+                logging.error(format_error("JSON parsing failed", fragment.name, fragment.line_number))
+                result = String(
+                    text=context.open_delimiter + fragment.text + context.close_delimiter,
+                    line_number=fragment.line_number,
+                    name=fragment.name
+                )
+
+        elif state == 2:
+            if context.prefix_valid:
+                context.text = fragment.text
+                result = None
+            else:
+                result = String(text=fragment.text, line_number=fragment.line_number, name=fragment.name)
+
+        elif state == 3:
+            if context.prefix_valid:
+                result = Block(
+                    directive=context.directive,
+                    prefix=context.prefix,
+                    suffix=fragment.text,
+                    text=context.text,
+                    line_number=context.prefix_line_number,
+                    name=fragment.name
+                )
+            else:
+                result = String(
+                    text=context.open_delimiter + fragment.text + context.close_delimiter,
+                    line_number=fragment.line_number,
+                    name=fragment.name
+                )
+
+        context.index += 1
+        return result
+
+    return create_blocks

syncspec-0.1.0/src/syncspec/create_blocks_context.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict
+
+@dataclass
+class CreateBlocksContext:
+	index: int
+	prefix: str
+	prefix_line_number: int
+	prefix_valid: bool
+	directive: Dict[str, Any]
+	text: str
+	open_delimiter: str
+	close_delimiter: str
+

syncspec-0.1.0/src/syncspec/edge.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+@dataclass
+class Edge:
+    directive_type: str
+    key: str
+    line_number: int
+    name: str

syncspec-0.1.0/src/syncspec/file.py

@@ -0,0 +1,6 @@
+from dataclasses import dataclass
+
+@dataclass
+class File:
+    text: str
+    name: str

syncspec-0.1.0/src/syncspec/fragment.py

@@ -0,0 +1,7 @@
+from dataclasses import dataclass
+
+@dataclass
+class Fragment:
+    text: str
+    line_number: int
+    name: str

syncspec-0.1.0/src/syncspec/fragment_text.py

@@ -0,0 +1,30 @@
+import re
+from typing import List
+from src.syncspec.validated_text import ValidatedText
+from src.syncspec.fragment import Fragment
+from src.syncspec.fragment_text_context import FragmentTextContext
+
+
+def make_fragment_text(context: FragmentTextContext):
+    def fragment_text(text: ValidatedText) -> List[Fragment]:
+        pattern = f"({re.escape(context.open_delimiter)}|{re.escape(context.close_delimiter)})"
+        parts = re.split(pattern, text.text)
+
+        fragments = []
+        current_line = context.line_number
+
+        for part in parts:
+            if part in (context.open_delimiter, context.close_delimiter):
+                current_line += part.count('\n')
+            else:
+                fragments.append(Fragment(
+                    text=part,
+                    name=text.name,
+                    line_number=current_line
+                ))
+                current_line += part.count('\n')
+
+        context.line_number = current_line
+        return fragments
+
+    return fragment_text

syncspec-0.1.0/src/syncspec/fragment_text_context.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict
+
+@dataclass
+class FragmentTextContext:
+    open_delimiter: str
+    close_delimiter: str
+    line_number: int

syncspec-0.1.0/src/syncspec/function.py

@@ -0,0 +1,12 @@
+"""Core functionality of syncspec"""
+
+
+def syncspec(*args, **kwargs):
+    """
+    Main syncspec function.
+
+    Replace this docstring with your actual function documentation.
+    """
+    # Your function implementation here
+    result = "Hello from syncspec!"
+    return result

syncspec-0.1.0/src/syncspec/graph_edges.py

@@ -0,0 +1,20 @@
+from typing import Callable
+from src.syncspec.edge import Edge
+from src.syncspec.graph_edges_context import GraphEdgesContext
+
+
+def make_graph_edges(context: GraphEdgesContext) -> Callable[[Edge], None]:
+    def graph_edges(edge: Edge) -> None:
+        target_id = f"{edge.directive_type}_{edge.name}_{edge.line_number}"
+        source_map = {"include": "source", "import": "export"}
+        source_type = source_map.get(edge.directive_type)
+
+        if not source_type:
+            return
+
+        nodes = list(context.G.nodes(data=True))
+        for node_id, attrs in nodes:
+            if attrs.get("directive_type") == source_type and attrs.get("key") == edge.key:
+                context.G.add_edge(node_id, target_id)
+
+    return graph_edges

syncspec-0.1.0/src/syncspec/graph_edges_context.py

@@ -0,0 +1,7 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict
+import networkx as nx
+
+@dataclass
+class GraphEdgesContext:
+	G: nx.DiGraph

syncspec-0.1.0/src/syncspec/import_block.py

@@ -0,0 +1,95 @@
+import logging
+from pathlib import Path
+from typing import Union, Tuple, Dict, Any
+
+from src.syncspec.node import Node
+from src.syncspec.utilities import format_error
+from src.syncspec.string import String
+from src.syncspec.block import Block
+from src.syncspec.import_block_context import ImportBlockContext
+
+
+def make_import_block(context: ImportBlockContext):
+    def import_block(block: Block) -> Union[Tuple[String, Node, Node], Block, String]:
+        if "import" not in block.directive:
+            return block
+
+        import_path = block.directive["import"]
+        log_err = lambda msg: _log_and_return_error(msg, block, context)
+
+        # Path Validation
+        try:
+            root = Path(context.import_path).resolve()
+            target = (root / import_path).resolve()
+
+            if not str(target).startswith(str(root) + '/') and str(target) != str(root):
+                return log_err("Path traversal detected")
+            if not target.exists():
+                return log_err("File does not exist")
+            if not target.is_file():
+                return log_err("Not a file")
+
+            # Read and Decode
+            try:
+                v = target.read_text(encoding='utf-8')
+            except UnicodeDecodeError:
+                return log_err("File is not valid UTF-8 text")
+            except PermissionError:
+                return log_err("File is not readable")
+        except Exception as e:
+            return log_err(f"Validation failed: {str(e)}")
+
+        # Head/Tail Validation
+        head = block.directive.get("head", 0)
+        tail = block.directive.get("tail", 0)
+
+        if not isinstance(head, int) or isinstance(head, bool) or head < 0:
+            return log_err("Invalid head value")
+        if not isinstance(tail, int) or isinstance(tail, bool) or tail < 0:
+            return log_err("Invalid tail value")
+
+        u_lines = block.text.splitlines(keepends=True)
+        total_lines = len(u_lines)
+
+        if head + tail > total_lines:
+            return log_err("Head and tail overlap")
+
+        top = "".join(u_lines[:head])
+        bottom = "".join(u_lines[-tail:] if tail > 0 else [])
+
+        # Construct Result String
+        s_text = (
+                context.open_delimiter +
+                block.prefix +
+                context.close_delimiter +
+                top +
+                v +
+                "\n" +
+                bottom +
+                context.open_delimiter +
+                block.suffix +
+                context.close_delimiter
+        )
+        res_string = String(text=s_text, line_number=block.line_number, name=block.name)
+
+        # Construct Nodes
+        n_export = Node(directive_type="export", key=import_path, line_number=0, name=import_path)
+        n_import = Node(directive_type="import", key=import_path, line_number=block.line_number, name=block.name)
+
+        return (res_string, n_export, n_import)
+
+    return import_block
+
+
+def _log_and_return_error(message: str, block: Block, context: ImportBlockContext) -> String:
+    logging.error(format_error(message, block.name, block.line_number))
+    text = (
+            context.open_delimiter +
+            block.prefix +
+            context.close_delimiter +
+            block.text +
+            context.open_delimiter +
+            block.suffix +
+            context.close_delimiter
+    )
+    return String(text=text, line_number=block.line_number, name=block.name)

syncspec-0.1.0/src/syncspec/import_block_context.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass, field
+from typing import ClassVar, Dict, Any
+
+@dataclass
+class ImportBlockContext:
+    import_path: str
+    open_delimiter: str
+    close_delimiter: str

syncspec-0.1.0/src/syncspec/include_block.py

@@ -0,0 +1,65 @@
+import logging
+from typing import Union, Tuple
+
+from src.syncspec.node import Node
+from src.syncspec.utilities import format_error
+from src.syncspec.string import String
+from src.syncspec.block import Block
+from src.syncspec.include_block_context import IncludeBlockContext
+
+
+def make_include_block(context: IncludeBlockContext):
+    def include_block(block: Block) -> Union[Tuple[String, Node], Block, String]:
+        def return_error(msg: str) -> String:
+            logging.error(format_error(msg, block.name, block.line_number))
+            return String(
+                text=context.open_delimiter + block.prefix + context.close_delimiter +
+                     block.text +
+                     context.open_delimiter + block.suffix + context.close_delimiter,
+                line_number=block.line_number,
+                name=block.name
+            )
+
+        if "include" not in block.directive:
+            return block
+
+        key = block.directive["include"]
+        if not isinstance(key, str):
+            return return_error("'include' directive must be a string")
+
+        if key not in context.state:
+            return return_error(f"include key '{key}' not found in context")
+
+        v = context.state[key]
+        if not isinstance(v, str):
+            return return_error(f"value for key '{key}' must be a string")
+
+        head = block.directive.get("head", 0)
+        tail = block.directive.get("tail", 0)
+
+        if isinstance(head, bool) or not isinstance(head, int) or head < 0:
+            return return_error("'head' must be a non-negative integer")
+        if isinstance(tail, bool) or not isinstance(tail, int) or tail < 0:
+            return return_error("'tail' must be a non-negative integer")
+
+        lines = block.text.splitlines(keepends=True)
+        total_lines = len(lines)
+
+        if head + tail > total_lines:
+            return return_error(f"head ({head}) + tail ({tail}) exceeds total lines ({total_lines})")
+
+        top = "".join(lines[:head])
+        bottom = "".join(lines[-tail:]) if tail > 0 else ""
+
+        s_text = (
+            context.open_delimiter + block.prefix + context.close_delimiter +
+            top + v + bottom +
+            context.open_delimiter + block.suffix + context.close_delimiter
+        )
+
+        s_obj = String(text=s_text, line_number=block.line_number, name=block.name)
+        n_obj = Node(directive_type="include", key=key, line_number=block.line_number, name=block.name)
+
+        return s_obj, n_obj
+
+    return include_block

syncspec-0.1.0/src/syncspec/include_block_context.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass, field
+from typing import ClassVar, Dict, Any
+
+@dataclass
+class IncludeBlockContext:
+    state: Dict[str, Any]
+    open_delimiter: str
+    close_delimiter: str

syncspec-0.1.0/src/syncspec/node.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+@dataclass
+class Node:
+    directive_type: str
+    key: str
+    line_number: int
+    name: str

syncspec-0.1.0/src/syncspec/production.py

@@ -0,0 +1,20 @@
+import inspect
+from typing import get_type_hints
+
+def build_rules(rule_functions):
+    return [
+        (get_type_hints(fn).get(next(iter(inspect.signature(fn).parameters)), object), fn)
+        for fn in rule_functions
+    ]
+
+def production(facts, rules):
+    for rule_type, fn in rules:
+        new_facts = []
+        for fact in facts:
+            if isinstance(fact, rule_type):
+                res = fn(fact)
+                new_facts.extend(res) if isinstance(res, (list, tuple)) else new_facts.append(res)
+            else:
+                new_facts.append(fact)
+        facts = new_facts
+    return facts