fluidattacks_core_contextualizes 2.0.0__py3-none-any.whl

fluidattacks_core/contextualizes/__init__.py

@@ -0,0 +1,48 @@
+from fluidattacks_core.contextualizes.components import (
+    MANIFEST_KINDS,
+    Component,
+    ComponentKind,
+    Enrichment,
+    kind_for_manifests,
+)
+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,
+    RelativePath,
+    ensure_relative_path,
+)
+from fluidattacks_core.contextualizes.schema import (
+    SCHEMA_PATH,
+    build_schema,
+    load_schema,
+    render_schema,
+)
+
+__all__ = [
+    "MANIFEST_KINDS",
+    "MAX_PATH_LENGTH",
+    "REPOSITORY_ROOT",
+    "SCHEMA_PATH",
+    "SCHEMA_VERSION",
+    "Component",
+    "ComponentKind",
+    "ContextualizerOutput",
+    "Enrichment",
+    "Observation",
+    "ObservationKind",
+    "RelativePath",
+    "Repository",
+    "RunStatus",
+    "build_schema",
+    "ensure_relative_path",
+    "kind_for_manifests",
+    "load_schema",
+    "render_schema",
+]

fluidattacks_core/contextualizes/components.py

@@ -0,0 +1,111 @@
+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):
+    """Ecosystem of a component, decided by a filename, never by a model.
+
+    Spelled as the platform's package ecosystem ids so a component joins the
+    package inventory without a translation table. `gradle` and `sbt` have no
+    id of their own there; both resolve from the maven registry.
+    """
+
+    CARGO = "cargo"
+    GO = "go"
+    GRADLE = "gradle"
+    MAVEN = "maven"
+    NPM = "npm"
+    NUGET = "nuget"
+    PACKAGIST = "packagist"
+    PUB = "pub"
+    PYPI = "pypi"
+    RUBYGEMS = "rubygems"
+    SBT = "sbt"
+    SWIFTURL = "swifturl"
+    UNKNOWN = "unknown"
+
+
+_GRADLE_FILES = WORKSPACE_MARKERS["gradle"]["declares"] | WORKSPACE_MARKERS["gradle"]["claims"]
+
+# Derived, not copied, so an upstream manifest cannot resolve to UNKNOWN here.
+MANIFEST_KINDS: dict[ComponentKind, frozenset[str]] = {
+    ComponentKind.CARGO: MANIFEST_MARKERS[Language.Rust],
+    ComponentKind.GO: MANIFEST_MARKERS[Language.Go],
+    ComponentKind.GRADLE: (
+        MANIFEST_MARKERS[Language.Kotlin] | (MANIFEST_MARKERS[Language.Java] & _GRADLE_FILES)
+    ),
+    ComponentKind.MAVEN: MANIFEST_MARKERS[Language.Java] - _GRADLE_FILES,
+    ComponentKind.NPM: (
+        MANIFEST_MARKERS[Language.JavaScript] | MANIFEST_MARKERS[Language.TypeScript]
+    ),
+    ComponentKind.NUGET: MANIFEST_MARKERS[Language.CSharp],
+    ComponentKind.PACKAGIST: MANIFEST_MARKERS[Language.PHP],
+    ComponentKind.PUB: MANIFEST_MARKERS[Language.Dart],
+    ComponentKind.PYPI: MANIFEST_MARKERS[Language.Python],
+    ComponentKind.RUBYGEMS: MANIFEST_MARKERS[Language.Ruby],
+    ComponentKind.SBT: MANIFEST_MARKERS[Language.Scala],
+    ComponentKind.SWIFTURL: MANIFEST_MARKERS[Language.Swift],
+}
+
+# A case-insensitive checkout returns whatever spelling it stored.
+_KIND_BY_MANIFEST: dict[str, ComponentKind] = {
+    manifest.casefold(): kind
+    for kind, manifests in MANIFEST_KINDS.items()
+    for manifest in manifests
+}
+
+# A polyglot component belongs to the ecosystem that ships it, not the one
+# that tools it: maturin is pypi, gradle wrapping npm is gradle.
+_KIND_PRIORITY: dict[ComponentKind, int] = {
+    ComponentKind.GRADLE: 90,
+    ComponentKind.MAVEN: 85,
+    ComponentKind.SBT: 80,
+    ComponentKind.SWIFTURL: 75,
+    ComponentKind.PUB: 70,
+    ComponentKind.NUGET: 65,
+    ComponentKind.GO: 60,
+    ComponentKind.PYPI: 55,
+    ComponentKind.CARGO: 50,
+    ComponentKind.RUBYGEMS: 45,
+    ComponentKind.PACKAGIST: 40,
+    ComponentKind.NPM: 35,
+}
+
+
+def kind_for_manifests(manifests: Iterable[str]) -> ComponentKind:
+    """Pick a component's kind from the manifest file names found in it."""
+    matched = {
+        _KIND_BY_MANIFEST[key]
+        for name in manifests
+        if (key := PurePosixPath(name.replace("\\", "/")).name.casefold()) in _KIND_BY_MANIFEST
+    }
+    if not matched:
+        return ComponentKind.UNKNOWN
+
+    return max(matched, key=lambda kind: (_KIND_PRIORITY[kind], kind.value))
+
+
+class Enrichment(StrEnum):
+    """Deep-pass outcome; the only way to tell a missing field from a gap."""
+
+    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/envelope.py

@@ -0,0 +1,57 @@
+import unicodedata
+from enum import StrEnum
+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
+
+SCHEMA_VERSION = 1
+
+
+class RunStatus(StrEnum):
+    """How much of the repository the run covered.
+
+    A consumer reconciles by deleting what the output omits, so it must be
+    able to refuse anything but `complete`.
+    """
+
+    COMPLETE = "complete"
+    FAILED = "failed"
+    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.
+
+    Contextualizer vocabulary only: nothing about scope, groups or asset
+    types, none of which is observable from a bare checkout.
+    """
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", strict=True)
+
+    schema_version: int = Field(ge=1, le=SCHEMA_VERSION)
+    producer: Annotated[str, StringConstraints(min_length=1, max_length=64)]
+    repository: Repository
+    status: RunStatus
+    components: tuple[Component, ...] = ()
+    observations: tuple[Observation, ...] = ()
+
+    @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]
+        if len(set(paths)) != len(paths):
+            msg = "components must not repeat a path"
+            raise ValueError(msg)
+
+        return self

fluidattacks_core/contextualizes/observations.py

@@ -0,0 +1,28 @@
+from enum import StrEnum
+from typing import Annotated, ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+
+from fluidattacks_core.contextualizes.paths import RelativePath
+
+
+class ObservationKind(StrEnum):
+    AI_MODEL = "ai_model"
+    ENDPOINT = "endpoint"
+    PACKAGE = "package"
+
+
+class Observation(BaseModel):
+    """Something found at a path, with no statement of which component owns it.
+
+    Unattributed so a producer need not run the partitioner, and a
+    repartition re-attributes everything with no rewrite here.
+    """
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", strict=True)
+
+    path: RelativePath
+    kind: ObservationKind
+    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

fluidattacks_core/contextualizes/paths.py

@@ -0,0 +1,53 @@
+import re
+from typing import Annotated
+
+from pydantic import AfterValidator, StringConstraints
+
+MAX_PATH_LENGTH = 4096
+
+REPOSITORY_ROOT = "."
+
+# Anchored: a colon is legal in a posix file name.
+_DRIVE_LETTER = re.compile(r"^[A-Za-z]:")
+_FORBIDDEN = re.compile("[\\x00-\\x1f\\x7f\\u202a-\\u202e\\u2066-\\u2069]")
+
+
+def ensure_relative_path(value: str) -> str:
+    """Reject, never normalize, anything but the canonical spelling of a path.
+
+    One spelling per path, so a consumer that folds `./a`, `a//b` and `a/` into
+    a single identity can never be handed two of them as separate entries.
+    """
+    if not value:
+        msg = "path must not be empty"
+        raise ValueError(msg)
+
+    if _FORBIDDEN.search(value):
+        msg = f"path must not hold control or bidi characters: {value!r}"
+        raise ValueError(msg)
+
+    if "\\" in value:
+        msg = f"path must use posix separators: {value!r}"
+        raise ValueError(msg)
+
+    if value.startswith("/") or _DRIVE_LETTER.match(value):
+        msg = f"path must be repository-relative: {value!r}"
+        raise ValueError(msg)
+
+    segments = value.split("/")
+    if any(segment == ".." for segment in segments):
+        msg = f"path must not traverse upwards: {value!r}"
+        raise ValueError(msg)
+
+    if value != REPOSITORY_ROOT and not all(segment and segment != "." for segment in segments):
+        msg = f"path must be in canonical form: {value!r}"
+        raise ValueError(msg)
+
+    return value
+
+
+RelativePath = Annotated[
+    str,
+    StringConstraints(min_length=1, max_length=MAX_PATH_LENGTH),
+    AfterValidator(ensure_relative_path),
+]

fluidattacks_core/contextualizes/schema.py

@@ -0,0 +1,35 @@
+import json
+from pathlib import Path
+
+from fluidattacks_core.contextualizes.envelope import SCHEMA_VERSION, ContextualizerOutput
+
+SCHEMA_PATH = Path(__file__).parent / "schemas" / "contextualizer_output.schema.json"
+
+# Versioned: a validator caches by $id, so v2 must not answer to v1's uri.
+_SCHEMA_ID = f"https://fluidattacks.com/schemas/contextualizer_output/v{SCHEMA_VERSION}.json"
+
+# Declared, or a validator defaulting to draft-07 reads `$defs` differently.
+_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.
+    """
+    schema = ContextualizerOutput.model_json_schema()
+
+    # Spread first, or a pydantic-emitted `$id` would silently win.
+    return {**schema, "$schema": _SCHEMA_DIALECT, "$id": _SCHEMA_ID}
+
+
+def render_schema() -> str:
+    return json.dumps(build_schema(), indent=2, sort_keys=True) + "\n"
+
+
+def load_schema() -> dict[str, object]:
+    content: dict[str, object] = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+
+    return content

fluidattacks_core/contextualizes/schemas/contextualizer_output.schema.json

@@ -0,0 +1,220 @@
+{
+  "$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": [
+        "cargo",
+        "go",
+        "gradle",
+        "maven",
+        "npm",
+        "nuget",
+        "packagist",
+        "pub",
+        "pypi",
+        "rubygems",
+        "sbt",
+        "swifturl",
+        "unknown"
+      ],
+      "title": "ComponentKind",
+      "type": "string"
+    },
+    "Enrichment": {
+      "description": "Deep-pass outcome; the only way to tell a missing field from a gap.",
+      "enum": [
+        "absent",
+        "failed",
+        "present"
+      ],
+      "title": "Enrichment",
+      "type": "string"
+    },
+    "Observation": {
+      "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.",
+      "properties": {
+        "kind": {
+          "$ref": "#/$defs/ObservationKind"
+        },
+        "line": {
+          "anyOf": [
+            {
+              "minimum": 1,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Line"
+        },
+        "path": {
+          "maxLength": 4096,
+          "minLength": 1,
+          "title": "Path",
+          "type": "string"
+        },
+        "properties": {
+          "additionalProperties": true,
+          "title": "Properties",
+          "type": "object"
+        },
+        "seen_by": {
+          "anyOf": [
+            {
+              "maxLength": 128,
+              "minLength": 1,
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Seen By"
+        }
+      },
+      "required": [
+        "path",
+        "kind"
+      ],
+      "title": "Observation",
+      "type": "object"
+    },
+    "ObservationKind": {
+      "enum": [
+        "ai_model",
+        "endpoint",
+        "package"
+      ],
+      "title": "ObservationKind",
+      "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": [
+        "complete",
+        "failed",
+        "partial"
+      ],
+      "title": "RunStatus",
+      "type": "string"
+    }
+  },
+  "$id": "https://fluidattacks.com/schemas/contextualizer_output/v1.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": {
+      "default": [],
+      "items": {
+        "$ref": "#/$defs/Observation"
+      },
+      "title": "Observations",
+      "type": "array"
+    },
+    "producer": {
+      "maxLength": 64,
+      "minLength": 1,
+      "title": "Producer",
+      "type": "string"
+    },
+    "repository": {
+      "$ref": "#/$defs/Repository"
+    },
+    "schema_version": {
+      "maximum": 1,
+      "minimum": 1,
+      "title": "Schema Version",
+      "type": "integer"
+    },
+    "status": {
+      "$ref": "#/$defs/RunStatus"
+    }
+  },
+  "required": [
+    "schema_version",
+    "producer",
+    "repository",
+    "status"
+  ],
+  "title": "ContextualizerOutput",
+  "type": "object"
+}

fluidattacks_core_contextualizes-2.0.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.5
+Name: fluidattacks_core_contextualizes
+Version: 2.0.0
+Summary: Fluid Attacks Core Contextualizes Library
+Author-email: Development <development@fluidattacks.com>
+License: MPL-2.0
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: fluidattacks-core-filesystem<15,>=14.0.0
+Requires-Dist: pydantic<3,>=2.12.3

fluidattacks_core_contextualizes-2.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+fluidattacks_core/contextualizes/__init__.py,sha256=KnIpVThsTcVV76bWyx7rk4kDP2kHoIWet45KvkNiqs0,1063
+fluidattacks_core/contextualizes/components.py,sha256=tMUxxrudm0Fh5-BE6DvfBsf5ZjeuqTyOg0lqzMFWYyg,3825
+fluidattacks_core/contextualizes/envelope.py,sha256=egzBdg8pYsxkPGW_RfnBdlY23ZU1n_ArDfoDn8-L7jM,1985
+fluidattacks_core/contextualizes/observations.py,sha256=ceQCVD5IDXlD34Lv7OdVGWNoscf82uGcQStlmSK1Bco,899
+fluidattacks_core/contextualizes/paths.py,sha256=OeUX5MG3liuQWth286sMx_TJp9gOMPxbtN4ISXXlwqY,1617
+fluidattacks_core/contextualizes/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fluidattacks_core/contextualizes/schema.py,sha256=dbEAJ_trPyLONRsmbQCsUrpALYMwqhvTAsgdUco2iRk,1302
+fluidattacks_core/contextualizes/schemas/contextualizer_output.schema.json,sha256=HiC0LmPRs7FshfjAyHjRlLJLI-T_NAMyL287p1_-p8s,5411
+fluidattacks_core_contextualizes-2.0.0.dist-info/METADATA,sha256=jTgye4mDmUxB6Q8Dz_i_tiAs6G7hGzbsA-SFIDL1V9Q,637
+fluidattacks_core_contextualizes-2.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+fluidattacks_core_contextualizes-2.0.0.dist-info/RECORD,,

fluidattacks_core_contextualizes-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any