libspec 1.2.0__py3-none-any.whl

libspec/spec_diff.py

@@ -0,0 +1,193 @@
+import sys
+import os
+from pathlib import Path
+from lxml import etree
+from xmldiff import main
+
+def get_latest_xml_files(directory):
+    path = Path(directory)
+    xml_files = list(path.glob('*.xml'))
+    if len(xml_files) == 0:
+        return None
+    
+    file_info = []
+    import datetime
+    for f in xml_files:
+        try:
+            tree = etree.parse(str(f))
+            root = tree.getroot()
+            date_str = root.get('date-created')
+            if date_str:
+                file_info.append((date_str, f))
+            else:
+                # Fallback to file mtime formatted as ISO string
+                mtime = os.path.getmtime(str(f))
+                dt = datetime.datetime.fromtimestamp(mtime).astimezone()
+                file_info.append((dt.isoformat(), f))
+        except Exception:
+            mtime = os.path.getmtime(str(f))
+            dt = datetime.datetime.fromtimestamp(mtime).astimezone()
+            file_info.append((dt.isoformat(), f))
+    
+    # Sort by the timestamp (date-created string or mtime)
+    file_info.sort(key=lambda x: x[0])
+    
+    if len(file_info) == 1:
+        # Only one spec exists — bootstrap case; diff against a null spec
+        return None, file_info[-1][1]
+    
+    return file_info[-2][1], file_info[-1][1]
+
+def resolve_component(root, xpath):
+    """
+    Find the closest parent <specification> and return its type or name.
+    """
+    try:
+        nodes = root.xpath(xpath)
+        if not nodes:
+            return "General System"
+        
+        node = nodes[0]
+        # Traverse up to find 'specification'
+        curr = node
+        while curr is not None:
+            if curr.tag == 'specification':
+                spec_type = curr.get('type')
+                if spec_type:
+                    return f"[{spec_type}]"
+                # Fallback to title in context
+                titles = curr.xpath('.//title/text()')
+                if titles:
+                    return f"[{titles[0]}]"
+                return "[Specification]"
+            curr = curr.getparent()
+    except Exception:
+        pass
+    return "Core System"
+
+def to_human_readable(action, root):
+    """
+    Translates a raw xmldiff Action into a human-readable string.
+    Returns None if the action is purely structural 'noise'.
+    """
+    action_type = type(action).__name__
+    
+    # Target node resolution
+    target_path = getattr(action, 'node', getattr(action, 'target', '/'))
+    try:
+        nodes = root.xpath(target_path)
+        tag = nodes[0].tag if nodes else "unknown"
+    except Exception:
+        tag = "unknown"
+
+    # Filter out structural boilerplate
+    if action_type == 'InsertNode' and tag in ['specification_set', 'specification', 'source', 'context', 'notes', 'description', 'req_id', 'title']:
+        return None
+
+    if action_type == 'UpdateTextIn':
+        text = (action.text or "").strip().replace('\n', ' ')
+            
+        if tag == 'description':
+            return f"Updated description: \"{text}\""
+        if tag == 'notes':
+            return f"Updated requirements: \"{text}\""
+        if tag == 'req_id':
+            return f"Updated cross-reference ID: {text}"
+        if tag == 'title':
+            return f"Updated title: {text}"
+        return f"Updated {tag} text to \"{text}\""
+
+    if action_type == 'InsertAttrib':
+        name = action.name
+        value = action.value
+        if name == 'type':
+            return f"Defined component type as '{value}'"
+        if name == 'file':
+            return f"Set source file to '{value}'"
+        if name == 'lines':
+            return f"Set source lines to {value}"
+        if name == 'target':
+            return f"Set tracking target to '{value}'"
+        return f"Added attribute {name}='{value}'"
+
+    if action_type == 'InsertNode':
+        return f"Added new {tag} element"
+
+    if action_type == 'DeleteNode':
+        return ""
+
+    if action_type == 'MoveNode':
+        return ""
+
+    if action_type == 'UpdateAttrib':
+        return ""
+
+    if action_type == 'RenameNode':
+        return ""
+
+
+    
+    # Fallback for other actions
+    return str(action).replace('\n', '\\n')
+
+NULL_SPEC_XML = """<?xml version='1.0' encoding='utf-8'?>
+<specification_set date-created="" />"""
+
+def generate_patch(dir_arg):
+    files = get_latest_xml_files(dir_arg)
+    if not files:
+        print("Error: No XML spec files found in the directory.")
+        return
+
+    old_file, new_file = files
+
+    if old_file is None:
+        # Bootstrap case: first spec ever — diff against an empty null spec
+        print(f"Diffing State: <null spec> -> {new_file.name}")
+        print("=" * 60)
+        import tempfile, io
+        with tempfile.NamedTemporaryFile(suffix='.xml', mode='w', delete=False) as tmp:
+            tmp.write(NULL_SPEC_XML)
+            tmp_path = tmp.name
+        try:
+            new_tree = etree.parse(str(new_file))
+            new_root = new_tree.getroot()
+            diffs = main.diff_files(tmp_path, str(new_file))
+        finally:
+            os.unlink(tmp_path)
+    else:
+        print(f"Diffing State: {old_file.name} -> {new_file.name}")
+        print("=" * 60)
+        try:
+            new_tree = etree.parse(str(new_file))
+            new_root = new_tree.getroot()
+        except Exception as e:
+            print(f"Error parsing XML: {e}")
+            return
+        diffs = main.diff_files(str(old_file), str(new_file))
+    if not diffs:
+        print("No changes detected.")
+        return
+
+    groups = {}
+    for op in diffs:
+        target_path = getattr(op, 'node', getattr(op, 'target', '/'))
+        component = resolve_component(new_root, target_path)
+        
+        readable = to_human_readable(op, new_root)
+        if readable:
+            if component not in groups:
+                groups[component] = []
+            groups[component].append(readable)
+
+    for component, descriptions in groups.items():
+        print(f"\nCOMPONENT: {component}")
+        for desc in descriptions:
+            print(f"  - {desc}")
+
+if __name__ == "__main__":
+    # Delegate to the unified CLI: `libspec diff <dir>`
+    import sys as _sys
+    from libspec.cli import main as _cli_main
+    _sys.argv.insert(1, 'diff')
+    _cli_main()

libspec/specweb.py

@@ -0,0 +1,13 @@
+# declarative prompts, state what should exist.
+
+class Html:
+    '''
+    
+    '''
+    pass
+
+class Css:
+    '''
+    
+    '''
+    

libspec/user_story.py

@@ -0,0 +1,24 @@
+from libspec import Feature
+
+#
+# https://github.com/github/spec-kit/blob/main/templates/spec-template.md
+#
+
+class UserStory(Feature):
+    '''
+    User Story - {brief-title} (Priority: {priority})
+
+    {user-journey}
+
+    Why this priority: {explanation}
+
+    Independent Test: [Describe how this can be tested independently -
+    e.g., "Can be fully tested by [specific action] and delivers
+    [specific value]"]
+
+    Acceptance Scenarios:
+
+    Given [initial state], When [action], Then [expected outcome]
+    Given [initial state], When [action], Then [expected outcome]
+    '''
+            

libspec/util.py

@@ -0,0 +1,26 @@
+import hashlib
+from pathlib import Path
+import difflib
+
+def easy_hash(text):
+    return hashlib.md5(text.encode()).hexdigest()
+
+def fqn(obj):
+    return f"{type(obj).__module__}.{type(obj).__qualname__}"
+        
+
+def diff_two_latest(dirpath):
+    files = [p for p in Path(dirpath).iterdir() if p.is_file()]
+    if len(files) < 2:
+        raise ValueError("Need at least two files")
+
+    latest = sorted(files, key=lambda p: p.stat().st_mtime, reverse=True)[:2]
+    newer, older = latest[0], latest[1]
+
+    with older.open() as f1, newer.open() as f2:
+        return "".join(difflib.unified_diff(
+            f1.readlines(),
+            f2.readlines(),
+            fromfile=str(older),
+            tofile=str(newer),
+        ))

libspec-1.2.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: libspec
+Version: 1.2.0
+Summary: Spec-driven development library for LLM-assisted coding
+Author-email: "Derek A. Rhodes" <physci@gmail.com>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/drhodes/libspec
+Project-URL: Repository, https://github.com/drhodes/libspec
+Project-URL: Bug Tracker, https://github.com/drhodes/libspec/issues
+Keywords: specification,llm,codegen,spec-driven,development
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: lxml>=6.0.2
+Requires-Dist: mcp>=1.27.0
+Requires-Dist: xmldiff>=2.7.0
+Dynamic: license-file
+
+# libspec
+
+`libspec` is a library for **Specification Driven Development** in
+Python. Similar in spirit to object relation mapping (ORM), libspec
+uses an Object Specification Mapping. Instead of generating SQL, this
+tool generates specs geared towards code generation with LLMs.
+
+Context is managed by diff'ing specs and using source maps with and
+associated agent that can cross reference the specs and generated
+code. The developer workflow is incremental and exploratory, less like
+gambling and more like delegating.
+
+![the general idea](./docs/workflow1.png)
+
+
+### Example Spec
+
+Here is a piece of a spec used to declare a small web app for managing
+a locker system
+
+```python
+from libspec import Requirement, RestMixin, Feature
+from .view_types import PublicView, AdminView
+
+class Django(Requirement):
+    '''Setup a Django environment using 6.0.2, it should use sqlite3 for 
+    now. Configure REST_FRAMEWORK and djangorestframework. 
+    Create a django app (with $ ... startapp) called `lockers` and 
+    wire it up. It should include an example model, view and urls to 
+    get started. 
+ 
+    Please ensure that the models are added to admin interface and 
+    REST API is exposed.
+    '''
+
+class Model(RestMixin, Requirement):
+    '''ensure this django model is added to the admin interface'''
+
+class LockerBank(Model):
+    '''Represent a physical bank of lockers. Should include a unique
+    name.'''
+
+class QrCode(Model):
+    '''Represent a QR code attached to a locker. Should include a
+    unique value, q matching the format in QrCodeRequirement.
+    '''
+
+class Locker(Model):
+    '''Represent an individual locker unit. Should be associated with
+    a LockerBank and two QrCodes (one inside, one outside). Should
+    track occupancy status and the timestamp of the last inside QR
+    code scan.  A locker will have a small number that uniquely
+    identifies it within a locker bank.  When a locker is created, it
+    should automatically create the qr codes associated with it.
+    '''
+
+class GunicornServer(Requirement):
+    '''In the Makefile, create a rule to run the gunicorn server on
+    port 8000'''
+
+class DevelopmentServer(Requirement):
+    '''In the Makefile, create a rule to run the development server on
+    port 8000'''
+
+```
+
+# The Object Model 
+
+Each class declares a specification fragment that is optionally a
+Jinja2 template string. More about that later...
+
+## Inheritance
+
+Inherited specification fragments are prepended to the Base class' doc
+string.
+
+## Mixins 
+
+Mixins help get around the diamond problem. (TODO: write more about this)
+
+## Versioning
+
+Note that the versioning of `libspec` is still being hammered
+out. Currently, the version of `libspec` appears in the generated XML
+(`libspec-version` field). But, how diffs will be performed on
+different versions is unexplored.

libspec-1.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+libspec/__init__.py,sha256=XhjFF8s-kNgHjgbyF9mxQffD7jndc6rPK40tlGaEZq8,165
+libspec/cli.py,sha256=8TqeMRbdUFkexmQtbpkQmIA00VFJsYQuo0xqZcgbShU,9511
+libspec/err.py,sha256=l9lJdeDwCA5j1fsU-ACgbJqnsFHVQGgHrU9aRq-vkRI,1256
+libspec/mcp_server.py,sha256=t_kFJjUXQlQmAI_ikiypVGZh2rSgZdJhoaskf-xc3ow,2783
+libspec/query_map.py,sha256=3pAzvDEyHILzwee8hV_iqwRPF3f72d1HxIdBNMO-LCg,485
+libspec/spec.py,sha256=vQEtY_RvrKU7GkAlVquR2nvQLkesbxz5hdSPOwyaXtY,19343
+libspec/spec_diff.py,sha256=4pOAHAi7deVxzy0NvyGIwE1OS1dOKhIIiEY0YGsWmdk,6203
+libspec/specweb.py,sha256=x0Klc9PH56jH27YzCH85FFpN7sy5sEmbbn75bZ-gxqs,129
+libspec/user_story.py,sha256=9wlLL8sNkG_vDvOgf4n_D-dQugDB_7vLL90JdwXaKv4,595
+libspec/util.py,sha256=w67biTN77EOOFgj7k7bBLwHbkvU-ppikeOkin04cFE8,728
+libspec-1.2.0.dist-info/licenses/LICENSE,sha256=5X8cMguM-HmKfS_4Om-eBqM6A1hfbgZf6pfx2G24QFI,35150
+libspec-1.2.0.dist-info/METADATA,sha256=kTyC1Z4TU7p2b928abgWkiWQohT1TpwwItEbXAfHy5A,3815
+libspec-1.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+libspec-1.2.0.dist-info/entry_points.txt,sha256=FrGhkKwt9AS4ClKgshsq5MNNtTDlOOQD94FHVV-G35A,83
+libspec-1.2.0.dist-info/top_level.txt,sha256=8ln_BTbi05Z_9b7ikS5nD8swQGRWw3-M7re_nd_Coag,8
+libspec-1.2.0.dist-info/RECORD,,

libspec-1.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

libspec-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+libspec = libspec.cli:main
+libspec-mcp = libspec.mcp_server:main