icdev 1.0.0__py3-none-any.whl

icdev/tools/integration/doors_exporter.py

@@ -0,0 +1,627 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+# Controlled by: Department of Defense
+# CUI Category: CTI
+# Distribution: D
+# POC: ICDEV System Administrator
+"""ReqIF 1.2 exporter for DOORS NG integration.
+
+Exports intake requirements as ReqIF XML documents suitable for import
+into IBM DOORS Next Generation. Uses xml.etree.ElementTree (consistent
+with architectural decisions D7/D25 — zero deps, air-gap safe).
+
+Usage:
+    # Export requirements to ReqIF
+    python tools/integration/doors_exporter.py --session-id sess-abc \\
+        --export-reqif --output-path .tmp/requirements.reqif --json
+
+    # Export without traceability links
+    python tools/integration/doors_exporter.py --session-id sess-abc \\
+        --export-reqif --output-path .tmp/requirements.reqif \\
+        --no-trace --json
+
+    # Validate a ReqIF file
+    python tools/integration/doors_exporter.py --validate \\
+        --file-path .tmp/requirements.reqif --json
+"""
+
+import argparse
+import json
+import os
+import sqlite3
+import uuid
+import xml.etree.ElementTree as ET
+from datetime import datetime, timezone
+from pathlib import Path
+from icdev._paths import get_project_root
+
+BASE_DIR = get_project_root()
+DB_PATH = Path(os.environ.get("ICDEV_DB_PATH", str(BASE_DIR / "data" / "icdev.db")))
+
+# ReqIF 1.2 namespace
+REQIF_NS = "http://www.omg.org/spec/ReqIF/20110401/reqif.xsd"
+XSI_NS = "http://www.w3.org/2001/XMLSchema-instance"
+
+# Graceful import of audit logger
+try:
+    from icdev.tools.audit.audit_logger import log_event
+    _HAS_AUDIT = True
+except ImportError:
+    _HAS_AUDIT = False
+    def log_event(**kwargs) -> int:  # type: ignore[misc]
+        return -1
+
+
+# ---------------------------------------------------------------------------
+# Database helpers
+# ---------------------------------------------------------------------------
+
+def _get_connection(db_path=None):
+    """Get database connection with dict-like row access."""
+    path = db_path or DB_PATH
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Database not found: {path}\nRun: python tools/db/init_icdev_db.py"
+        )
+    conn = sqlite3.connect(str(path))
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def _generate_id(prefix="reqif"):
+    """Generate a unique ID with prefix."""
+    return f"{prefix}-{uuid.uuid4().hex[:12]}"
+
+
+def _now():
+    """ISO-8601 timestamp."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _reqif_identifier():
+    """Generate a ReqIF-style identifier."""
+    return f"_icdev_{uuid.uuid4().hex[:16]}"
+
+
+# ---------------------------------------------------------------------------
+# ReqIF XML construction
+# ---------------------------------------------------------------------------
+
+def _build_reqif_document(requirements, session_id, include_trace=True,
+                          trace_links=None):
+    """Build a ReqIF 1.2 XML document from requirements.
+
+    Args:
+        requirements: List of requirement dicts.
+        session_id: Intake session identifier.
+        include_trace: Whether to include traceability relations.
+        trace_links: List of (source_req_id, target_req_id, link_type) tuples.
+
+    Returns:
+        ElementTree root element.
+    """
+    # Register namespaces
+    ET.register_namespace("", REQIF_NS)
+    ET.register_namespace("xsi", XSI_NS)
+
+    root = ET.Element("REQ-IF", {
+        "xmlns": REQIF_NS,
+        "xmlns:xsi": XSI_NS,
+    })
+
+    # --- THE-HEADER ---
+    the_header = ET.SubElement(root, "THE-HEADER")
+    req_if_header = ET.SubElement(the_header, "REQ-IF-HEADER", {
+        "IDENTIFIER": _reqif_identifier(),
+    })
+    ET.SubElement(req_if_header, "COMMENT").text = (
+        f"Generated by ICDEV RICOAS for session {session_id}"
+    )
+    ET.SubElement(req_if_header, "CREATION-TIME").text = _now()
+    ET.SubElement(req_if_header, "REPOSITORY-ID").text = f"icdev-{session_id}"
+    ET.SubElement(req_if_header, "REQ-IF-TOOL-ID").text = "ICDEV-RICOAS"
+    ET.SubElement(req_if_header, "REQ-IF-VERSION").text = "1.2"
+    ET.SubElement(req_if_header, "SOURCE-TOOL-ID").text = "ICDEV-Integration"
+    ET.SubElement(req_if_header, "TITLE").text = (
+        f"Requirements Export - Session {session_id}"
+    )
+
+    # --- CORE-CONTENT ---
+    core_content = ET.SubElement(root, "CORE-CONTENT")
+    req_if_content = ET.SubElement(core_content, "REQ-IF-CONTENT")
+
+    # --- DATATYPES ---
+    datatypes = ET.SubElement(req_if_content, "DATATYPES")
+
+    # String datatype
+    dt_string_id = _reqif_identifier()
+    ET.SubElement(datatypes, "DATATYPE-DEFINITION-STRING", {
+        "IDENTIFIER": dt_string_id,
+        "LONG-NAME": "T_String",
+        "MAX-LENGTH": "4096",
+    })
+
+    # Priority enum
+    dt_priority_id = _reqif_identifier()
+    dt_priority = ET.SubElement(datatypes, "DATATYPE-DEFINITION-ENUMERATION", {
+        "IDENTIFIER": dt_priority_id,
+        "LONG-NAME": "T_Priority",
+    })
+    sv_priority = ET.SubElement(dt_priority, "SPECIFIED-VALUES")
+    for idx, val in enumerate(["critical", "high", "medium", "low"]):
+        ev = ET.SubElement(sv_priority, "ENUM-VALUE", {
+            "IDENTIFIER": _reqif_identifier(),
+            "LONG-NAME": val,
+        })
+        props = ET.SubElement(ev, "PROPERTIES")
+        ET.SubElement(props, "EMBEDDED-VALUE", {
+            "KEY": str(idx),
+            "OTHER-CONTENT": val,
+        })
+
+    # Requirement type enum
+    dt_type_id = _reqif_identifier()
+    dt_type = ET.SubElement(datatypes, "DATATYPE-DEFINITION-ENUMERATION", {
+        "IDENTIFIER": dt_type_id,
+        "LONG-NAME": "T_RequirementType",
+    })
+    sv_type = ET.SubElement(dt_type, "SPECIFIED-VALUES")
+    for idx, val in enumerate(["functional", "non_functional", "interface",
+                                "security", "performance", "compliance",
+                                "data", "constraint", "operational",
+                                "transitional"]):
+        ev = ET.SubElement(sv_type, "ENUM-VALUE", {
+            "IDENTIFIER": _reqif_identifier(),
+            "LONG-NAME": val,
+        })
+        props = ET.SubElement(ev, "PROPERTIES")
+        ET.SubElement(props, "EMBEDDED-VALUE", {
+            "KEY": str(idx),
+            "OTHER-CONTENT": val,
+        })
+
+    # Status enum
+    dt_status_id = _reqif_identifier()
+    dt_status = ET.SubElement(datatypes, "DATATYPE-DEFINITION-ENUMERATION", {
+        "IDENTIFIER": dt_status_id,
+        "LONG-NAME": "T_Status",
+    })
+    sv_status = ET.SubElement(dt_status, "SPECIFIED-VALUES")
+    for idx, val in enumerate(["draft", "clarified", "validated", "approved",
+                                "rejected", "decomposed", "deferred"]):
+        ev = ET.SubElement(sv_status, "ENUM-VALUE", {
+            "IDENTIFIER": _reqif_identifier(),
+            "LONG-NAME": val,
+        })
+        props = ET.SubElement(ev, "PROPERTIES")
+        ET.SubElement(props, "EMBEDDED-VALUE", {
+            "KEY": str(idx),
+            "OTHER-CONTENT": val,
+        })
+
+    # --- SPEC-TYPES ---
+    spec_types = ET.SubElement(req_if_content, "SPEC-TYPES")
+
+    # Spec object type for requirements
+    sot_id = _reqif_identifier()
+    sot = ET.SubElement(spec_types, "SPEC-OBJECT-TYPE", {
+        "IDENTIFIER": sot_id,
+        "LONG-NAME": "ICDEV Requirement",
+    })
+    spec_attrs = ET.SubElement(sot, "SPEC-ATTRIBUTES")
+
+    # Attribute: ICDEV ID
+    attr_icdev_id = _reqif_identifier()
+    attr_def = ET.SubElement(spec_attrs, "ATTRIBUTE-DEFINITION-STRING", {
+        "IDENTIFIER": attr_icdev_id,
+        "LONG-NAME": "ICDEV_ID",
+    })
+    ad_type = ET.SubElement(attr_def, "TYPE")
+    ET.SubElement(ad_type, "DATATYPE-DEFINITION-STRING-REF").text = dt_string_id
+
+    # Attribute: Title (raw_text)
+    attr_title_id = _reqif_identifier()
+    attr_def = ET.SubElement(spec_attrs, "ATTRIBUTE-DEFINITION-STRING", {
+        "IDENTIFIER": attr_title_id,
+        "LONG-NAME": "Title",
+    })
+    ad_type = ET.SubElement(attr_def, "TYPE")
+    ET.SubElement(ad_type, "DATATYPE-DEFINITION-STRING-REF").text = dt_string_id
+
+    # Attribute: Description (refined_text)
+    attr_desc_id = _reqif_identifier()
+    attr_def = ET.SubElement(spec_attrs, "ATTRIBUTE-DEFINITION-STRING", {
+        "IDENTIFIER": attr_desc_id,
+        "LONG-NAME": "Description",
+    })
+    ad_type = ET.SubElement(attr_def, "TYPE")
+    ET.SubElement(ad_type, "DATATYPE-DEFINITION-STRING-REF").text = dt_string_id
+
+    # Attribute: Priority
+    attr_priority_id = _reqif_identifier()
+    attr_def = ET.SubElement(spec_attrs, "ATTRIBUTE-DEFINITION-ENUMERATION", {
+        "IDENTIFIER": attr_priority_id,
+        "LONG-NAME": "Priority",
+    })
+    ad_type = ET.SubElement(attr_def, "TYPE")
+    ET.SubElement(ad_type, "DATATYPE-DEFINITION-ENUMERATION-REF").text = dt_priority_id
+
+    # Attribute: Type
+    attr_type_id = _reqif_identifier()
+    attr_def = ET.SubElement(spec_attrs, "ATTRIBUTE-DEFINITION-ENUMERATION", {
+        "IDENTIFIER": attr_type_id,
+        "LONG-NAME": "RequirementType",
+    })
+    ad_type = ET.SubElement(attr_def, "TYPE")
+    ET.SubElement(ad_type, "DATATYPE-DEFINITION-ENUMERATION-REF").text = dt_type_id
+
+    # Attribute: Status
+    attr_status_id = _reqif_identifier()
+    attr_def = ET.SubElement(spec_attrs, "ATTRIBUTE-DEFINITION-ENUMERATION", {
+        "IDENTIFIER": attr_status_id,
+        "LONG-NAME": "Status",
+    })
+    ad_type = ET.SubElement(attr_def, "TYPE")
+    ET.SubElement(ad_type, "DATATYPE-DEFINITION-ENUMERATION-REF").text = dt_status_id
+
+    # Spec relation type for traceability
+    srt_id = _reqif_identifier()
+    ET.SubElement(spec_types, "SPEC-RELATION-TYPE", {
+        "IDENTIFIER": srt_id,
+        "LONG-NAME": "Traces To",
+    })
+
+    # Specification type
+    spec_type_id = _reqif_identifier()
+    ET.SubElement(spec_types, "SPECIFICATION-TYPE", {
+        "IDENTIFIER": spec_type_id,
+        "LONG-NAME": "ICDEV Requirements Specification",
+    })
+
+    # --- SPEC-OBJECTS ---
+    spec_objects = ET.SubElement(req_if_content, "SPEC-OBJECTS")
+
+    # Map icdev_id -> spec object identifier for relations
+    id_to_spec_obj = {}
+
+    for req in requirements:
+        so_id = _reqif_identifier()
+        id_to_spec_obj[req["id"]] = so_id
+
+        so = ET.SubElement(spec_objects, "SPEC-OBJECT", {
+            "IDENTIFIER": so_id,
+            "LONG-NAME": (req.get("raw_text") or "")[:80],
+        })
+        values = ET.SubElement(so, "VALUES")
+
+        # ICDEV_ID
+        av = ET.SubElement(values, "ATTRIBUTE-VALUE-STRING", {
+            "THE-VALUE": req["id"],
+        })
+        ad = ET.SubElement(av, "DEFINITION")
+        ET.SubElement(ad, "ATTRIBUTE-DEFINITION-STRING-REF").text = attr_icdev_id
+
+        # Title
+        av = ET.SubElement(values, "ATTRIBUTE-VALUE-STRING", {
+            "THE-VALUE": req.get("raw_text") or "",
+        })
+        ad = ET.SubElement(av, "DEFINITION")
+        ET.SubElement(ad, "ATTRIBUTE-DEFINITION-STRING-REF").text = attr_title_id
+
+        # Description
+        av = ET.SubElement(values, "ATTRIBUTE-VALUE-STRING", {
+            "THE-VALUE": req.get("refined_text") or req.get("raw_text") or "",
+        })
+        ad = ET.SubElement(av, "DEFINITION")
+        ET.SubElement(ad, "ATTRIBUTE-DEFINITION-STRING-REF").text = attr_desc_id
+
+        # Type reference
+        so_type = ET.SubElement(so, "TYPE")
+        ET.SubElement(so_type, "SPEC-OBJECT-TYPE-REF").text = sot_id
+
+    # --- SPEC-RELATIONS ---
+    relations_exported = 0
+    spec_relations = ET.SubElement(req_if_content, "SPEC-RELATIONS")
+
+    if include_trace and trace_links:
+        for src_id, tgt_id, link_type in trace_links:
+            src_ref = id_to_spec_obj.get(src_id)
+            tgt_ref = id_to_spec_obj.get(tgt_id)
+            if not src_ref or not tgt_ref:
+                continue
+
+            sr = ET.SubElement(spec_relations, "SPEC-RELATION", {
+                "IDENTIFIER": _reqif_identifier(),
+                "LONG-NAME": link_type,
+            })
+            source_el = ET.SubElement(sr, "SOURCE")
+            ET.SubElement(source_el, "SPEC-OBJECT-REF").text = src_ref
+            target_el = ET.SubElement(sr, "TARGET")
+            ET.SubElement(target_el, "SPEC-OBJECT-REF").text = tgt_ref
+            sr_type = ET.SubElement(sr, "TYPE")
+            ET.SubElement(sr_type, "SPEC-RELATION-TYPE-REF").text = srt_id
+            relations_exported += 1
+
+    # --- SPECIFICATIONS ---
+    specifications = ET.SubElement(req_if_content, "SPECIFICATIONS")
+    spec = ET.SubElement(specifications, "SPECIFICATION", {
+        "IDENTIFIER": _reqif_identifier(),
+        "LONG-NAME": f"ICDEV Requirements - {session_id}",
+    })
+    spec_el_type = ET.SubElement(spec, "TYPE")
+    ET.SubElement(spec_el_type, "SPECIFICATION-TYPE-REF").text = spec_type_id
+
+    children = ET.SubElement(spec, "CHILDREN")
+    for req in requirements:
+        so_ref = id_to_spec_obj.get(req["id"])
+        if so_ref:
+            hier = ET.SubElement(children, "SPEC-HIERARCHY", {
+                "IDENTIFIER": _reqif_identifier(),
+            })
+            obj_el = ET.SubElement(hier, "OBJECT")
+            ET.SubElement(obj_el, "SPEC-OBJECT-REF").text = so_ref
+
+    return root, relations_exported
+
+
+# ---------------------------------------------------------------------------
+# export_reqif
+# ---------------------------------------------------------------------------
+
+def export_reqif(session_id, output_path, include_trace=True, db_path=None):
+    """Export requirements as ReqIF 1.2 XML for DOORS NG.
+
+    Args:
+        session_id: Intake session identifier.
+        output_path: File path for the output ReqIF file.
+        include_trace: Include traceability relations.
+        db_path: Override database path.
+
+    Returns:
+        dict with session_id, output_path, requirements_exported,
+        relations_exported, file_size.
+    """
+    conn = _get_connection(db_path)
+    try:
+        # Get requirements
+        rows = conn.execute(
+            """SELECT id, session_id, raw_text, refined_text, requirement_type,
+                      priority, status, clarity_score, completeness_score,
+                      acceptance_criteria, classification
+               FROM intake_requirements
+               WHERE session_id = ?
+               ORDER BY id""",
+            (session_id,),
+        ).fetchall()
+
+        if not rows:
+            return {"error": f"No requirements found for session {session_id}",
+                    "requirements_exported": 0}
+
+        requirements = [dict(r) for r in rows]
+
+        # Get trace links between requirements if requested
+        trace_links = []
+        if include_trace:
+            req_ids = [r["id"] for r in requirements]
+            if req_ids:
+                placeholders = ",".join("?" * len(req_ids))
+                links = conn.execute(
+                    f"""SELECT source_id, target_id, link_type
+                        FROM digital_thread_links
+                        WHERE source_type = 'intake_requirement'
+                          AND target_type = 'intake_requirement'
+                          AND source_id IN ({placeholders})""",
+                    req_ids,
+                ).fetchall()
+                trace_links = [(dict(row)["source_id"], dict(row)["target_id"],
+                               dict(row)["link_type"]) for row in links]
+
+        # Build XML
+        root, relations_exported = _build_reqif_document(
+            requirements, session_id, include_trace, trace_links,
+        )
+
+        # Write to file
+        output = Path(output_path)
+        output.parent.mkdir(parents=True, exist_ok=True)
+
+        tree = ET.ElementTree(root)
+        ET.indent(tree, space="  ")
+        tree.write(str(output), encoding="unicode", xml_declaration=True)
+
+        file_size = output.stat().st_size
+
+        # Get project_id for audit
+        session_row = conn.execute(
+            "SELECT project_id FROM intake_sessions WHERE id = ?",
+            (session_id,),
+        ).fetchone()
+        project_id = session_row["project_id"] if session_row else None
+
+        log_event(
+            event_type="reqif_exported",
+            actor="icdev-integration-doors",
+            action=f"Exported {len(requirements)} requirements to ReqIF",
+            project_id=project_id,
+            details={
+                "session_id": session_id,
+                "output_path": str(output),
+                "requirements_exported": len(requirements),
+                "relations_exported": relations_exported,
+                "file_size": file_size,
+            },
+        )
+
+        return {
+            "session_id": session_id,
+            "output_path": str(output),
+            "requirements_exported": len(requirements),
+            "relations_exported": relations_exported,
+            "file_size": file_size,
+        }
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------------
+# validate_reqif
+# ---------------------------------------------------------------------------
+
+def validate_reqif(file_path):
+    """Basic XML validation of ReqIF structure.
+
+    Checks that the file is well-formed XML with the expected ReqIF
+    top-level elements.
+
+    Args:
+        file_path: Path to the ReqIF file.
+
+    Returns:
+        dict with valid (bool), errors (list).
+    """
+    errors = []
+    path = Path(file_path)
+
+    if not path.exists():
+        return {"valid": False, "errors": [f"File not found: {file_path}"]}
+
+    try:
+        tree = ET.parse(str(path))
+    except ET.ParseError as exc:
+        return {"valid": False, "errors": [f"XML parse error: {exc}"]}
+
+    root = tree.getroot()
+
+    # Strip namespace for comparison
+    tag = root.tag
+    if "}" in tag:
+        tag = tag.split("}", 1)[1]
+
+    if tag != "REQ-IF":
+        errors.append(f"Root element is '{tag}', expected 'REQ-IF'")
+
+    # Check required sections
+    required_sections = ["THE-HEADER", "CORE-CONTENT"]
+    for section in required_sections:
+        found = False
+        for child in root:
+            child_tag = child.tag
+            if "}" in child_tag:
+                child_tag = child_tag.split("}", 1)[1]
+            if child_tag == section:
+                found = True
+                break
+        if not found:
+            errors.append(f"Missing required section: {section}")
+
+    # Check CORE-CONTENT has REQ-IF-CONTENT
+    core_content = None
+    for child in root:
+        child_tag = child.tag
+        if "}" in child_tag:
+            child_tag = child_tag.split("}", 1)[1]
+        if child_tag == "CORE-CONTENT":
+            core_content = child
+            break
+
+    if core_content is not None:
+        req_if_content = None
+        for child in core_content:
+            child_tag = child.tag
+            if "}" in child_tag:
+                child_tag = child_tag.split("}", 1)[1]
+            if child_tag == "REQ-IF-CONTENT":
+                req_if_content = child
+                break
+
+        if req_if_content is None:
+            errors.append("CORE-CONTENT missing REQ-IF-CONTENT child")
+        else:
+            expected_children = [
+                "DATATYPES", "SPEC-TYPES", "SPEC-OBJECTS",
+                "SPEC-RELATIONS", "SPECIFICATIONS",
+            ]
+            found_children = set()
+            for child in req_if_content:
+                child_tag = child.tag
+                if "}" in child_tag:
+                    child_tag = child_tag.split("}", 1)[1]
+                found_children.add(child_tag)
+
+            for expected in expected_children:
+                if expected not in found_children:
+                    errors.append(f"REQ-IF-CONTENT missing section: {expected}")
+
+    # Count spec objects
+    spec_obj_count = 0
+    for elem in root.iter():
+        elem_tag = elem.tag
+        if "}" in elem_tag:
+            elem_tag = elem_tag.split("}", 1)[1]
+        if elem_tag == "SPEC-OBJECT":
+            spec_obj_count += 1
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "spec_object_count": spec_obj_count,
+        "file_size": path.stat().st_size,
+    }
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="ReqIF 1.2 exporter for DOORS NG integration"
+    )
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+
+    # Actions
+    parser.add_argument("--export-reqif", action="store_true",
+                        help="Export requirements as ReqIF")
+    parser.add_argument("--validate", action="store_true",
+                        help="Validate a ReqIF file")
+
+    # Export args
+    parser.add_argument("--session-id", help="Intake session ID")
+    parser.add_argument("--output-path", help="Output file path for ReqIF")
+    parser.add_argument("--no-trace", action="store_true",
+                        help="Exclude traceability relations")
+
+    # Validate args
+    parser.add_argument("--file-path", help="ReqIF file to validate")
+
+    args = parser.parse_args()
+
+    result = None
+
+    if args.export_reqif:
+        if not args.session_id or not args.output_path:
+            parser.error("--export-reqif requires --session-id and --output-path")
+        result = export_reqif(
+            session_id=args.session_id,
+            output_path=args.output_path,
+            include_trace=not args.no_trace,
+        )
+    elif args.validate:
+        if not args.file_path:
+            parser.error("--validate requires --file-path")
+        result = validate_reqif(file_path=args.file_path)
+    else:
+        parser.print_help()
+        return
+
+    if args.json:
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        for key, value in result.items():
+            print(f"{key}: {value}")
+
+
+if __name__ == "__main__":
+    main()
+# [TEMPLATE: CUI // SP-CTI]