codedebrief 0.11.0__py3-none-any.whl

codedebrief/schema/codedebrief.schema.json

@@ -0,0 +1,449 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:codedebrief:schema:codedebrief:2.0",
+  "title": "CodeDebrief Logical Model",
+  "description": "Canonical decision-flow artifact generated from source code.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "generated_at",
+    "root",
+    "flows",
+    "files",
+    "metadata"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "2.0"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "root": {
+      "type": "string"
+    },
+    "flows": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/flow"
+      }
+    },
+    "files": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/file"
+      }
+    },
+    "metadata": {
+      "$ref": "#/$defs/project_metadata"
+    }
+  },
+  "$defs": {
+    "string_array": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "non_negative_integer": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "ratio": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "json_value": {
+      "description": "Detector-specific structured metadata value.",
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        },
+        {
+          "type": "array"
+        },
+        {
+          "type": "object"
+        }
+      ]
+    },
+    "location": {
+      "type": "object",
+      "required": ["path", "start_line", "end_line"],
+      "properties": {
+        "path": {
+          "type": "string"
+        },
+        "start_line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "end_line": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "node": {
+      "type": "object",
+      "required": [
+        "id",
+        "kind",
+        "label",
+        "location",
+        "evidence",
+        "detail",
+        "metadata"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "kind": {
+          "enum": ["entry", "action", "decision", "call", "terminal", "error"]
+        },
+        "label": {
+          "type": "string"
+        },
+        "location": {
+          "$ref": "#/$defs/location"
+        },
+        "evidence": {
+          "$ref": "#/$defs/evidence"
+        },
+        "detail": {
+          "type": "string"
+        },
+        "metadata": {
+          "type": "object"
+        }
+      },
+      "additionalProperties": false
+    },
+    "edge": {
+      "type": "object",
+      "required": ["id", "source", "target", "label", "evidence"],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "source": {
+          "type": "string"
+        },
+        "target": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "evidence": {
+          "$ref": "#/$defs/evidence"
+        }
+      },
+      "additionalProperties": false
+    },
+    "flow": {
+      "type": "object",
+      "required": [
+        "id",
+        "name",
+        "symbol",
+        "language",
+        "framework",
+        "entry_kind",
+        "is_entrypoint",
+        "location",
+        "nodes",
+        "edges",
+        "calls",
+        "called_by",
+        "tests",
+        "metadata"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "symbol": {
+          "type": "string"
+        },
+        "language": {
+          "enum": [
+            "python",
+            "typescript",
+            "javascript",
+            "go",
+            "java",
+            "csharp",
+            "php",
+            "c",
+            "cpp",
+            "rust",
+            "ruby"
+          ]
+        },
+        "framework": {
+          "type": "string"
+        },
+        "entry_kind": {
+          "type": "string"
+        },
+        "is_entrypoint": {
+          "type": "boolean"
+        },
+        "location": {
+          "$ref": "#/$defs/location"
+        },
+        "nodes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        },
+        "edges": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/edge"
+          }
+        },
+        "calls": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "called_by": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tests": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "metadata": {
+          "type": "object"
+        }
+      },
+      "additionalProperties": false
+    },
+    "file": {
+      "type": "object",
+      "required": ["path", "language", "sha256", "flow_ids"],
+      "properties": {
+        "path": {
+          "type": "string"
+        },
+        "language": {
+          "enum": [
+            "python",
+            "typescript",
+            "javascript",
+            "go",
+            "java",
+            "csharp",
+            "php",
+            "c",
+            "cpp",
+            "rust",
+            "ruby"
+          ]
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "flow_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "dependencies": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "evidence": {
+      "enum": ["VERIFIED", "INFERRED", "POTENTIAL_GAP"]
+    },
+    "project_metadata": {
+      "type": "object",
+      "properties": {
+        "flow_count": {
+          "$ref": "#/$defs/non_negative_integer"
+        },
+        "entrypoint_count": {
+          "$ref": "#/$defs/non_negative_integer"
+        },
+        "languages": {
+          "$ref": "#/$defs/string_array"
+        },
+        "scopes": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/non_negative_integer"
+          }
+        },
+        "enums": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "$ref": "#/$defs/string_array"
+            }
+          }
+        },
+        "quality": {
+          "$ref": "#/$defs/quality"
+        },
+        "language_capabilities": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/language_capability"
+          }
+        },
+        "skipped_files": {
+          "$ref": "#/$defs/skipped_files"
+        }
+      },
+      "additionalProperties": true
+    },
+    "quality": {
+      "type": "object",
+      "properties": {
+        "files": {
+          "type": "object"
+        },
+        "flows": {
+          "type": "object"
+        },
+        "calls": {
+          "type": "object"
+        },
+        "labels": {
+          "type": "object"
+        },
+        "source_locations": {
+          "type": "object"
+        },
+        "graph": {
+          "type": "object"
+        },
+        "languages": {
+          "type": "object"
+        }
+      },
+      "additionalProperties": true
+    },
+    "language_capability": {
+      "type": "object",
+      "required": ["status", "frontend", "suffixes", "features", "limitations"],
+      "properties": {
+        "status": {
+          "type": "string"
+        },
+        "frontend": {
+          "type": "string"
+        },
+        "suffixes": {
+          "$ref": "#/$defs/string_array"
+        },
+        "features": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "limitations": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "skipped_files": {
+      "oneOf": [
+        {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "language", "reason"],
+            "properties": {
+              "path": {
+                "type": "string"
+              },
+              "language": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": true
+          }
+        },
+        {
+          "type": "object",
+          "required": ["total", "by_reason", "sample"],
+          "properties": {
+            "total": {
+              "$ref": "#/$defs/non_negative_integer"
+            },
+            "by_reason": {
+              "type": "object",
+              "additionalProperties": {
+                "$ref": "#/$defs/non_negative_integer"
+              }
+            },
+            "sample": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["path", "language", "reason"],
+                "properties": {
+                  "path": {
+                    "type": "string"
+                  },
+                  "language": {
+                    "type": "string"
+                  },
+                  "reason": {
+                    "type": "string"
+                  }
+                },
+                "additionalProperties": true
+              }
+            }
+          },
+          "additionalProperties": true
+        }
+      ]
+    }
+  },
+  "additionalProperties": false
+}

codedebrief/util.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Any, cast
+
+
+def stable_id(*parts: str, length: int = 16) -> str:
+    payload = "\x1f".join(parts).encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()[:length]
+
+
+def file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    try:
+        return cast(dict[str, Any], json.loads(text))
+    except json.JSONDecodeError as error:
+        # Name the offending file: a bare "Expecting value: line 1 column 1" gives a
+        # caller no way to find which cache/model file is corrupt.
+        raise ValueError(f"invalid JSON in {path}: {error}") from error
+
+
+def write_json(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(data, indent=2, ensure_ascii=False, sort_keys=False) + "\n",
+        encoding="utf-8",
+    )
+
+
+def compact_text(value: str, limit: int = 100) -> str:
+    value = re.sub(r"\s+", " ", value).strip()
+    if len(value) <= limit:
+        return value
+    return value[: limit - 1].rstrip() + "..."
+
+
+def metadata_scope_names(metadata: dict[str, Any]) -> list[str]:
+    scopes = metadata.get("scope", [])
+    if isinstance(scopes, str):
+        return [scopes] if scopes else []
+    if not isinstance(scopes, (list, tuple, set)):
+        return []
+    names: list[str] = []
+    for scope in scopes:
+        if scope is None:
+            continue
+        name = scope if isinstance(scope, str) else str(scope)
+        if name:
+            names.append(name)
+    return names
+
+
+def relpath(path: Path, root: Path) -> str:
+    return path.resolve().relative_to(root.resolve()).as_posix()