fluidattacks_core_contextualizes 2.0.0__tar.gz → 3.0.0__tar.gz

{fluidattacks_core_contextualizes-2.0.0 → fluidattacks_core_contextualizes-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fluidattacks_core_contextualizes
-Version: 2.0.0
+Version: 3.0.0
 Summary: Fluid Attacks Core Contextualizes Library
 Author-email: Development <development@fluidattacks.com>
 License: MPL-2.0

{fluidattacks_core_contextualizes-2.0.0 → fluidattacks_core_contextualizes-3.0.0}/fluidattacks_core/contextualizes/__init__.py

@@ -1,17 +1,15 @@
 from fluidattacks_core.contextualizes.components import (
     MANIFEST_KINDS,
-    Component,
     ComponentKind,
     Enrichment,
     kind_for_manifests,
 )
+from fluidattacks_core.contextualizes.entries import Entry, EntryKind
 from fluidattacks_core.contextualizes.envelope import (
     SCHEMA_VERSION,
     ContextualizerOutput,
-    Repository,
     RunStatus,
 )
-from fluidattacks_core.contextualizes.observations import Observation, ObservationKind
 from fluidattacks_core.contextualizes.paths import (
     MAX_PATH_LENGTH,
     REPOSITORY_ROOT,
@@ -31,14 +29,12 @@ __all__ = [
     "REPOSITORY_ROOT",
     "SCHEMA_PATH",
     "SCHEMA_VERSION",
-    "Component",
     "ComponentKind",
     "ContextualizerOutput",
     "Enrichment",
-    "Observation",
-    "ObservationKind",
+    "Entry",
+    "EntryKind",
     "RelativePath",
-    "Repository",
     "RunStatus",
     "build_schema",
     "ensure_relative_path",

{fluidattacks_core_contextualizes-2.0.0 → fluidattacks_core_contextualizes-3.0.0}/fluidattacks_core/contextualizes/components.py

@@ -1,13 +1,9 @@
 from collections.abc import Iterable
 from enum import StrEnum
 from pathlib import PurePosixPath
-from typing import Annotated, ClassVar
 
 from fluidattacks_core.filesystem.defaults import MANIFEST_MARKERS, WORKSPACE_MARKERS
 from fluidattacks_core.filesystem.language import Language
-from pydantic import BaseModel, ConfigDict, Field, StringConstraints
-
-from fluidattacks_core.contextualizes.paths import RelativePath
 
 
 class ComponentKind(StrEnum):
@@ -99,13 +95,3 @@ class Enrichment(StrEnum):
     ABSENT = "absent"
     FAILED = "failed"
     PRESENT = "present"
-
-
-class Component(BaseModel):
-    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", strict=True)
-
-    path: RelativePath
-    name: Annotated[str, StringConstraints(min_length=1, max_length=512)]
-    kind: ComponentKind
-    enrichment: Enrichment
-    properties: dict[str, object] = Field(default_factory=dict)

fluidattacks_core_contextualizes-3.0.0/fluidattacks_core/contextualizes/entries.py

@@ -0,0 +1,55 @@
+from enum import StrEnum
+from typing import Annotated, ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints, model_validator
+
+from fluidattacks_core.contextualizes.components import ComponentKind, Enrichment
+from fluidattacks_core.contextualizes.paths import RelativePath
+
+
+class EntryKind(StrEnum):
+    """What an entry is, not what ecosystem it belongs to."""
+
+    AI_MODEL = "ai_model"
+    COMPONENT = "component"
+    ENDPOINT = "endpoint"
+    PACKAGE = "package"
+
+
+class Entry(BaseModel):
+    """Something found at a path; only a component says a part exists there."""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", strict=True)
+
+    path: RelativePath
+    kind: EntryKind
+    name: Annotated[str, StringConstraints(min_length=1, max_length=512)] | None = None
+    ecosystem: ComponentKind | None = None
+    enrichment: Enrichment | None = None
+    line: Annotated[int, Field(ge=1)] | None = None
+    properties: dict[str, object] = Field(default_factory=dict)
+    seen_by: Annotated[str, StringConstraints(min_length=1, max_length=128)] | None = None
+
+    @model_validator(mode="after")
+    def _reject_fields_foreign_to_the_kind(self) -> "Entry":
+        if self.kind is EntryKind.COMPONENT:
+            missing = [
+                field
+                for field, value in (
+                    ("name", self.name),
+                    ("ecosystem", self.ecosystem),
+                    ("enrichment", self.enrichment),
+                )
+                if value is None
+            ]
+            if missing:
+                msg = f"a component must declare {', '.join(missing)}"
+                raise ValueError(msg)
+            if self.line is not None:
+                msg = "a component must not carry a line"
+                raise ValueError(msg)
+        elif self.enrichment is not None:
+            msg = "only a component may carry enrichment"
+            raise ValueError(msg)
+
+        return self

{fluidattacks_core_contextualizes-2.0.0 → fluidattacks_core_contextualizes-3.0.0}/fluidattacks_core/contextualizes/envelope.py

@@ -4,10 +4,9 @@ from typing import Annotated, ClassVar
 
 from pydantic import BaseModel, ConfigDict, Field, StringConstraints, model_validator
 
-from fluidattacks_core.contextualizes.components import Component
-from fluidattacks_core.contextualizes.observations import Observation
+from fluidattacks_core.contextualizes.entries import Entry, EntryKind
 
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
 
 
 class RunStatus(StrEnum):
@@ -22,13 +21,6 @@ class RunStatus(StrEnum):
     PARTIAL = "partial"
 
 
-class Repository(BaseModel):
-    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", strict=True)
-
-    url: Annotated[str, StringConstraints(min_length=1, max_length=2048)]
-    branch: Annotated[str, StringConstraints(min_length=1, max_length=512)] | None = None
-
-
 class ContextualizerOutput(BaseModel):
     """One contextualizer's report over one repository.
 
@@ -38,18 +30,20 @@ class ContextualizerOutput(BaseModel):
 
     model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", strict=True)
 
-    schema_version: int = Field(ge=1, le=SCHEMA_VERSION)
+    schema_version: int = Field(ge=SCHEMA_VERSION, le=SCHEMA_VERSION)
     producer: Annotated[str, StringConstraints(min_length=1, max_length=64)]
-    repository: Repository
     status: RunStatus
-    components: tuple[Component, ...] = ()
-    observations: tuple[Observation, ...] = ()
+    entries: tuple[Entry, ...] = ()
+
+    @property
+    def components(self) -> tuple[Entry, ...]:
+        return tuple(entry for entry in self.entries if entry.kind is EntryKind.COMPONENT)
 
     @model_validator(mode="after")
     def _reject_duplicate_component_paths(self) -> "ContextualizerOutput":
         # Folded: two normalization forms are two files here, but a consumer
         # keying on the normalized path sees one, and loses an entry.
-        paths = [unicodedata.normalize("NFC", component.path) for component in self.components]
+        paths = [unicodedata.normalize("NFC", entry.path) for entry in self.components]
         if len(set(paths)) != len(paths):
             msg = "components must not repeat a path"
             raise ValueError(msg)

{fluidattacks_core_contextualizes-2.0.0 → fluidattacks_core_contextualizes-3.0.0}/fluidattacks_core/contextualizes/schema.py

@@ -15,9 +15,10 @@ _SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"
 def build_schema() -> dict[str, object]:
     """Render the canonical JSONSchema the Rust producer validates against.
 
-    Structural only. Neither `ensure_relative_path` nor the unique-component
-    rule can be expressed here, so each producer implements both and the
-    fixtures are what prove the implementations agree.
+    Structural only. The path grammar, component uniqueness and the rules
+    conditional on `kind` are not expressed here, so each producer
+    implements them and the fixtures are what prove the implementations
+    agree.
     """
     schema = ContextualizerOutput.model_json_schema()
 

{fluidattacks_core_contextualizes-2.0.0 → fluidattacks_core_contextualizes-3.0.0}/fluidattacks_core/contextualizes/schemas/contextualizer_output.schema.json

@@ -1,41 +1,5 @@
 {
   "$defs": {
-    "Component": {
-      "additionalProperties": false,
-      "properties": {
-        "enrichment": {
-          "$ref": "#/$defs/Enrichment"
-        },
-        "kind": {
-          "$ref": "#/$defs/ComponentKind"
-        },
-        "name": {
-          "maxLength": 512,
-          "minLength": 1,
-          "title": "Name",
-          "type": "string"
-        },
-        "path": {
-          "maxLength": 4096,
-          "minLength": 1,
-          "title": "Path",
-          "type": "string"
-        },
-        "properties": {
-          "additionalProperties": true,
-          "title": "Properties",
-          "type": "object"
-        }
-      },
-      "required": [
-        "path",
-        "name",
-        "kind",
-        "enrichment"
-      ],
-      "title": "Component",
-      "type": "object"
-    },
     "ComponentKind": {
       "description": "Ecosystem of a component, decided by a filename, never by a model.\n\nSpelled as the platform's package ecosystem ids so a component joins the\npackage inventory without a translation table. `gradle` and `sbt` have no\nid of their own there; both resolve from the maven registry.",
       "enum": [
@@ -66,12 +30,34 @@
       "title": "Enrichment",
       "type": "string"
     },
-    "Observation": {
+    "Entry": {
       "additionalProperties": false,
-      "description": "Something found at a path, with no statement of which component owns it.\n\nUnattributed so a producer need not run the partitioner, and a\nrepartition re-attributes everything with no rewrite here.",
+      "description": "Something found at a path; only a component says a part exists there.",
       "properties": {
+        "ecosystem": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/ComponentKind"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "enrichment": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Enrichment"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
         "kind": {
-          "$ref": "#/$defs/ObservationKind"
+          "$ref": "#/$defs/EntryKind"
         },
         "line": {
           "anyOf": [
@@ -86,6 +72,20 @@
           "default": null,
           "title": "Line"
         },
+        "name": {
+          "anyOf": [
+            {
+              "maxLength": 512,
+              "minLength": 1,
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Name"
+        },
         "path": {
           "maxLength": 4096,
           "minLength": 1,
@@ -116,48 +116,20 @@
         "path",
         "kind"
       ],
-      "title": "Observation",
+      "title": "Entry",
       "type": "object"
     },
-    "ObservationKind": {
+    "EntryKind": {
+      "description": "What an entry is, not what ecosystem it belongs to.",
       "enum": [
         "ai_model",
+        "component",
         "endpoint",
         "package"
       ],
-      "title": "ObservationKind",
+      "title": "EntryKind",
       "type": "string"
     },
-    "Repository": {
-      "additionalProperties": false,
-      "properties": {
-        "branch": {
-          "anyOf": [
-            {
-              "maxLength": 512,
-              "minLength": 1,
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Branch"
-        },
-        "url": {
-          "maxLength": 2048,
-          "minLength": 1,
-          "title": "Url",
-          "type": "string"
-        }
-      },
-      "required": [
-        "url"
-      ],
-      "title": "Repository",
-      "type": "object"
-    },
     "RunStatus": {
       "description": "How much of the repository the run covered.\n\nA consumer reconciles by deleting what the output omits, so it must be\nable to refuse anything but `complete`.",
       "enum": [
@@ -169,25 +141,17 @@
       "type": "string"
     }
   },
-  "$id": "https://fluidattacks.com/schemas/contextualizer_output/v1.json",
+  "$id": "https://fluidattacks.com/schemas/contextualizer_output/v2.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "additionalProperties": false,
   "description": "One contextualizer's report over one repository.\n\nContextualizer vocabulary only: nothing about scope, groups or asset\ntypes, none of which is observable from a bare checkout.",
   "properties": {
-    "components": {
-      "default": [],
-      "items": {
-        "$ref": "#/$defs/Component"
-      },
-      "title": "Components",
-      "type": "array"
-    },
-    "observations": {
+    "entries": {
       "default": [],
       "items": {
-        "$ref": "#/$defs/Observation"
+        "$ref": "#/$defs/Entry"
       },
-      "title": "Observations",
+      "title": "Entries",
       "type": "array"
     },
     "producer": {
@@ -196,12 +160,9 @@
       "title": "Producer",
       "type": "string"
     },
-    "repository": {
-      "$ref": "#/$defs/Repository"
-    },
     "schema_version": {
-      "maximum": 1,
-      "minimum": 1,
+      "maximum": 2,
+      "minimum": 2,
       "title": "Schema Version",
       "type": "integer"
     },
@@ -212,7 +173,6 @@
   "required": [
     "schema_version",
     "producer",
-    "repository",
     "status"
   ],
   "title": "ContextualizerOutput",

{fluidattacks_core_contextualizes-2.0.0 → fluidattacks_core_contextualizes-3.0.0}/import-linter.cfg

@@ -11,6 +11,6 @@
   layers =
     schema
     envelope
-    observations
+    entries
     components
     paths

{fluidattacks_core_contextualizes-2.0.0 → fluidattacks_core_contextualizes-3.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fluidattacks_core_contextualizes"
-version = "2.0.0"
+version = "3.0.0"
 description = "Fluid Attacks Core Contextualizes Library"
 authors = [{ name = "Development", email = "development@fluidattacks.com" }]
 license = { text = "MPL-2.0" }

{fluidattacks_core_contextualizes-2.0.0 → fluidattacks_core_contextualizes-3.0.0}/tests/data/discovers_output.json

@@ -1,41 +1,39 @@
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "producer": "discovers",
-  "repository": {
-    "url": "https://example.com/acme/store",
-    "branch": "main"
-  },
   "status": "complete",
-  "components": [],
-  "observations": [
+  "entries": [
     {
       "path": "services/checkout/src/main/java/AssistantController.java",
       "kind": "endpoint",
       "line": 13,
       "properties": {
         "entry_point": "/api/v1/assistant/completions",
+        "framework": "java_spring_boot",
         "http_method": "POST"
       },
-      "seen_by": "java_spring_boot"
+      "seen_by": "api_discovery"
     },
     {
       "path": "services/checkout/src/main/java/AssistantController.java",
       "kind": "ai_model",
-      "line": 15,
+      "line": 42,
       "properties": {
-        "model": "gpt-4o"
+        "model": "gpt-4o",
+        "sdk": "OpenAI"
       },
-      "seen_by": "Spring AI"
+      "seen_by": "ai_models_discovery"
     },
     {
-      "path": "web/src/api/AccountController.java",
+      "path": "web/src/api/account.ts",
       "kind": "endpoint",
-      "line": 16,
+      "line": 15,
       "properties": {
-        "entry_point": "/api/v1/accounts/{id}",
-        "http_method": "GET"
+        "entry_point": "/proxy/{id}",
+        "framework": "express",
+        "http_method": "DELETE"
       },
-      "seen_by": "java_spring_boot"
+      "seen_by": "api_discovery"
     }
   ]
 }

fluidattacks_core_contextualizes-3.0.0/tests/data/explores_output.json

@@ -0,0 +1,50 @@
+{
+  "schema_version": 2,
+  "producer": "explores",
+  "status": "complete",
+  "entries": [
+    {
+      "path": ".",
+      "kind": "component",
+      "name": "store",
+      "ecosystem": "unknown",
+      "enrichment": "absent",
+      "properties": {
+        "title": "Store monorepo",
+        "type": "unknown"
+      }
+    },
+    {
+      "path": "services/checkout",
+      "kind": "component",
+      "name": "checkout",
+      "ecosystem": "gradle",
+      "enrichment": "present",
+      "properties": {
+        "api_protocol": "rest",
+        "framework": "spring_boot",
+        "language": "Java",
+        "title": "Checkout service",
+        "type": "api"
+      }
+    },
+    {
+      "path": "web",
+      "kind": "component",
+      "name": "web",
+      "ecosystem": "npm",
+      "enrichment": "failed",
+      "properties": {
+        "title": "Storefront"
+      }
+    },
+    {
+      "path": "services/checkout/src/main/java/AssistantController.java",
+      "kind": "endpoint",
+      "properties": {
+        "entry_point": "/api/v1/assistant/completions",
+        "http_method": "POST"
+      }
+    }
+  ]
+}

fluidattacks_core_contextualizes-2.0.0/tests/data/invalid_traversal_path.json → fluidattacks_core_contextualizes-3.0.0/tests/data/invalid_absolute_path.json

@@ -1,16 +1,13 @@
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "producer": "explores",
-  "repository": {
-    "url": "https://example.com/acme/store",
-    "branch": "main"
-  },
   "status": "complete",
-  "components": [
+  "entries": [
     {
       "path": ".",
+      "kind": "component",
       "name": "store",
-      "kind": "unknown",
+      "ecosystem": "unknown",
       "enrichment": "absent",
       "properties": {
         "title": "Store monorepo",
@@ -19,8 +16,9 @@
     },
     {
       "path": "services/checkout",
+      "kind": "component",
       "name": "checkout",
-      "kind": "gradle",
+      "ecosystem": "gradle",
       "enrichment": "present",
       "properties": {
         "api_protocol": "rest",
@@ -32,23 +30,21 @@
     },
     {
       "path": "web",
+      "kind": "component",
       "name": "web",
-      "kind": "npm",
+      "ecosystem": "npm",
       "enrichment": "failed",
       "properties": {
         "title": "Storefront"
       }
-    }
-  ],
-  "observations": [
+    },
     {
-      "path": "services/checkout/../../etc/passwd",
+      "path": "/services/checkout/src/main/java/AssistantController.java",
       "kind": "endpoint",
       "properties": {
         "entry_point": "/api/v1/assistant/completions",
         "http_method": "POST"
-      },
-      "seen_by": "explores"
+      }
     }
   ]
 }

{fluidattacks_core_contextualizes-2.0.0 → fluidattacks_core_contextualizes-3.0.0}/tests/data/invalid_attributed_observation.json

@@ -1,16 +1,13 @@
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "producer": "explores",
-  "repository": {
-    "url": "https://example.com/acme/store",
-    "branch": "main"
-  },
   "status": "complete",
-  "components": [
+  "entries": [
     {
       "path": ".",
+      "kind": "component",
       "name": "store",
-      "kind": "unknown",
+      "ecosystem": "unknown",
       "enrichment": "absent",
       "properties": {
         "title": "Store monorepo",
@@ -19,8 +16,9 @@
     },
     {
       "path": "services/checkout",
+      "kind": "component",
       "name": "checkout",
-      "kind": "gradle",
+      "ecosystem": "gradle",
       "enrichment": "present",
       "properties": {
         "api_protocol": "rest",
@@ -32,15 +30,14 @@
     },
     {
       "path": "web",
+      "kind": "component",
       "name": "web",
-      "kind": "npm",
+      "ecosystem": "npm",
       "enrichment": "failed",
       "properties": {
         "title": "Storefront"
       }
-    }
-  ],
-  "observations": [
+    },
     {
       "path": "services/checkout/src/main/java/AssistantController.java",
       "kind": "endpoint",
@@ -48,7 +45,6 @@
         "entry_point": "/api/v1/assistant/completions",
         "http_method": "POST"
       },
-      "seen_by": "explores",
       "component": "services/checkout"
     }
   ]