fluidattacks_core_contextualizes 2.0.0__tar.gz

fluidattacks_core_contextualizes-2.0.0/.envrc

@@ -0,0 +1 @@
+use_flake ".#python311.devShell"

fluidattacks_core_contextualizes-2.0.0/.gitignore

@@ -0,0 +1,9 @@
+dist/
+dist-*/
+/.cargo-cache
+target/
+.direnv/
+.venv/
+.vscode/settings.json
+.zed/settings.json
+*.so

fluidattacks_core_contextualizes-2.0.0/PKG-INFO

@@ -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/build/default.nix

@@ -0,0 +1,19 @@
+{ src, workspace_root }:
+{
+  inherit src workspace_root;
+  root_path = "develops/fluidattacks-core/python/contextualizes";
+  module_name = "fluidattacks_core";
+  pypi_token = {
+    method = "oidc";
+  };
+  override = {
+    checks = {
+      basedpyright = false;
+    };
+    configs = {
+      import_linter = ../import-linter.cfg;
+      mypy = ../mypy.ini;
+      ruff = ../ruff.toml;
+    };
+  };
+}

fluidattacks_core_contextualizes-2.0.0/build/filter.nix

@@ -0,0 +1,13 @@
+path_filter: src:
+path_filter {
+  root = src;
+  include = [
+    "fluidattacks_core"
+    "tests"
+    "import-linter.cfg"
+    "mypy.ini"
+    "pyproject.toml"
+    "ruff.toml"
+    "uv.lock"
+  ];
+}

fluidattacks_core_contextualizes-2.0.0/flake.lock

@@ -0,0 +1,303 @@
+{
+  "nodes": {
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": "nixpkgs-lib"
+      },
+      "locked": {
+        "lastModified": 1762810396,
+        "narHash": "sha256-dxFVgQPG+R72dkhXTtqUm7KpxElw3u6E+YlQ2WaDgt8=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "0bdadb1b265fb4143a75bd1ec7d8c915898a9923",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
+    "nix_filter": {
+      "locked": {
+        "lastModified": 1757882181,
+        "narHash": "sha256-+cCxYIh2UNalTz364p+QYmWHs0P+6wDhiWR4jDIKQIU=",
+        "owner": "numtide",
+        "repo": "nix-filter",
+        "rev": "59c44d1909c72441144b93cf0f054be7fe764de5",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "nix-filter",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1758690382,
+        "narHash": "sha256-NY3kSorgqE5LMm1LqNwGne3ZLMF2/ILgLpFr1fS4X3o=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "e643668fd71b949c53f8626614b21ff71a07379d",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-lib": {
+      "locked": {
+        "lastModified": 1761765539,
+        "narHash": "sha256-b0yj6kfvO8ApcSE+QmA6mUfu8IYG6/uU28OFn4PaC8M=",
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "rev": "719359f4562934ae99f5443f20aa06c2ffff91fc",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "type": "github"
+      }
+    },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1758690382,
+        "narHash": "sha256-NY3kSorgqE5LMm1LqNwGne3ZLMF2/ILgLpFr1fS4X3o=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "e643668fd71b949c53f8626614b21ff71a07379d",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_3": {
+      "locked": {
+        "lastModified": 1761373498,
+        "narHash": "sha256-Q/uhWNvd7V7k1H1ZPMy/vkx3F8C13ZcdrKjO7Jv7v0c=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "6a08e6bb4e46ff7fcbb53d409b253f6bad8a28ce",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_flake": {
+      "locked": {
+        "lastModified": 1778253243,
+        "narHash": "sha256-KkH2QvU6iRLDTGGEwH5jnMqHWj4zMTuHxi1S1zdr01w=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "4fcda7103530b23c5ca44286344912082aad4220",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "pyproject-build-systems": {
+      "inputs": {
+        "nixpkgs": "nixpkgs",
+        "pyproject-nix": "pyproject-nix",
+        "uv2nix": "uv2nix"
+      },
+      "locked": {
+        "lastModified": 1761781027,
+        "narHash": "sha256-YDvxPAm2WnxrznRqWwHLjryBGG5Ey1ATEJXrON+TWt8=",
+        "owner": "pyproject-nix",
+        "repo": "build-system-pkgs",
+        "rev": "795a980d25301e5133eca37adae37283ec3c8e66",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "build-system-pkgs",
+        "type": "github"
+      }
+    },
+    "pyproject-nix": {
+      "inputs": {
+        "nixpkgs": [
+          "python_builder",
+          "pyproject-build-systems",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1758265079,
+        "narHash": "sha256-amLaLNwKSZPShQHzfgmc/9o76dU8xzN0743dWgvYlr8=",
+        "owner": "nix-community",
+        "repo": "pyproject.nix",
+        "rev": "02e9418fd4af638447dca4b17b1280da95527fc9",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "pyproject.nix",
+        "type": "github"
+      }
+    },
+    "pyproject-nix_2": {
+      "inputs": {
+        "nixpkgs": "nixpkgs_2"
+      },
+      "locked": {
+        "lastModified": 1762427963,
+        "narHash": "sha256-CkPlAbIQ87wmjy5qHibfzk4DmMGBNqFer+lLfXjpP5M=",
+        "owner": "pyproject-nix",
+        "repo": "pyproject.nix",
+        "rev": "4540ea004e04fcd12dd2738d51383d10f956f7b9",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "pyproject.nix",
+        "type": "github"
+      }
+    },
+    "pyproject-nix_3": {
+      "inputs": {
+        "nixpkgs": [
+          "python_builder",
+          "uv2nix",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1760402624,
+        "narHash": "sha256-jF6UKLs2uGc2rtved8Vrt58oTWjTQoAssuYs/0578Z4=",
+        "owner": "pyproject-nix",
+        "repo": "pyproject.nix",
+        "rev": "84c4ea102127c77058ea1ed7be7300261fafc7d2",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "pyproject.nix",
+        "type": "github"
+      }
+    },
+    "python_builder": {
+      "inputs": {
+        "nix_filter": "nix_filter",
+        "nixpkgs_flake": "nixpkgs_flake",
+        "pyproject-build-systems": "pyproject-build-systems",
+        "pyproject-nix": "pyproject-nix_2",
+        "shell-helpers": "shell-helpers",
+        "uv2nix": "uv2nix_2"
+      },
+      "locked": {
+        "dir": "common/utils/python-builder",
+        "lastModified": 1787078362,
+        "narHash": "sha256-HYL7Rn6SuNjYxkt/PwFLksZjsauCiY+ENbOWryLsIlw=",
+        "ref": "refs/heads/trunk",
+        "rev": "09fd25a13309eb5e3b5b2a061bb340df3ae5d281",
+        "shallow": true,
+        "type": "git",
+        "url": "ssh://git@gitlab.com/fluidattacks/universe"
+      },
+      "original": {
+        "dir": "common/utils/python-builder",
+        "rev": "09fd25a13309eb5e3b5b2a061bb340df3ae5d281",
+        "shallow": true,
+        "type": "git",
+        "url": "ssh://git@gitlab.com/fluidattacks/universe"
+      }
+    },
+    "root": {
+      "inputs": {
+        "python_builder": "python_builder"
+      }
+    },
+    "shell-helpers": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "nixpkgs": [
+          "python_builder",
+          "nixpkgs_flake"
+        ]
+      },
+      "locked": {
+        "dir": "common/utils/shell-helpers",
+        "lastModified": 1762806066,
+        "narHash": "sha256-Wz99Fl7SpPU1NkTHJ36XOo6DjOEAMXCw3ThRABOS2Hs=",
+        "ref": "refs/heads/trunk",
+        "rev": "d73cfdc7ae9e7f547e22a4481d4c2ccce38b26a8",
+        "shallow": true,
+        "type": "git",
+        "url": "ssh://git@gitlab.com/fluidattacks/universe"
+      },
+      "original": {
+        "dir": "common/utils/shell-helpers",
+        "rev": "d73cfdc7ae9e7f547e22a4481d4c2ccce38b26a8",
+        "shallow": true,
+        "type": "git",
+        "url": "ssh://git@gitlab.com/fluidattacks/universe"
+      }
+    },
+    "uv2nix": {
+      "inputs": {
+        "nixpkgs": [
+          "python_builder",
+          "pyproject-build-systems",
+          "nixpkgs"
+        ],
+        "pyproject-nix": [
+          "python_builder",
+          "pyproject-build-systems",
+          "pyproject-nix"
+        ]
+      },
+      "locked": {
+        "lastModified": 1758933732,
+        "narHash": "sha256-HAmm1GBS1myZCFuog0DC2ZLaynvZtiUI2Crmo+cdQI0=",
+        "owner": "pyproject-nix",
+        "repo": "uv2nix",
+        "rev": "273ce18f913d8559e0d04f820d724308966d7c4d",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "uv2nix",
+        "type": "github"
+      }
+    },
+    "uv2nix_2": {
+      "inputs": {
+        "nixpkgs": "nixpkgs_3",
+        "pyproject-nix": "pyproject-nix_3"
+      },
+      "locked": {
+        "lastModified": 1761872265,
+        "narHash": "sha256-i25GRgp2vUOebY70L3NTAgkd+Pr1hnn5xM3qHxH0ONU=",
+        "owner": "pyproject-nix",
+        "repo": "uv2nix",
+        "rev": "74dfb62871be152ad3673b143b0cc56105a4f3c5",
+        "type": "github"
+      },
+      "original": {
+        "owner": "pyproject-nix",
+        "repo": "uv2nix",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

fluidattacks_core_contextualizes-2.0.0/flake.nix

@@ -0,0 +1,29 @@
+{
+  description = "Fluid Attacks Core contextualizes package.";
+
+  inputs = {
+    python_builder = {
+      url = "git+ssh://git@gitlab.com/fluidattacks/universe?shallow=1&rev=09fd25a13309eb5e3b5b2a061bb340df3ae5d281&dir=common/utils/python-builder";
+    };
+  };
+
+  outputs =
+    { self, ... }@inputs:
+    let
+      build_args =
+        {
+          system,
+          python_version,
+          nixpkgs,
+          builders,
+          scripts,
+        }:
+        import ./build {
+          src = import ./build/filter.nix nixpkgs.nix-filter self;
+          workspace_root = ./.;
+        };
+    in
+    {
+      packages = inputs.python_builder.outputs.build build_args;
+    };
+}

fluidattacks_core_contextualizes-2.0.0/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-2.0.0/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-2.0.0/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-2.0.0/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