linceo 0.1.0__tar.gz

linceo-0.1.0/.devsecops/config.toml

@@ -0,0 +1,25 @@
+# linceo's own policy document — dogfooding this project's tool on its own
+# source (ADR §4/R5's precedent: "gitleaks como hook de pre-commit desde el
+# commit #1"). Not client configuration: R5 is about a *consumer's* values
+# never living in this repository, and this repository is the one being
+# scanned here, exactly the same way `.gitleaks.toml` (repo root) already
+# is gitleaks' own equivalent for this same repository.
+version = 1
+
+# Equivalent strictness to what `gitleaks-action` enforced before this CI
+# job started calling linceo instead: it failed the job on any leak found,
+# with no severity concept of its own. Every `secrets` finding is at least
+# HIGH by category default (ADR §6 — gitleaks emits no native severity), so
+# `fail_on = "high"` blocks on the same set of findings `gitleaks-action`
+# did, never more permissively.
+fail_on = "high"
+
+[tools.gitleaks]
+# Keeps `.gitleaks.toml`'s own [extend]/[allowlist] — the synthetic-fixture
+# allowlist under tests/ (see that file) — applying exactly as it did under
+# `gitleaks-action`, which read it by gitleaks' own convention (a bare
+# `.gitleaks.toml` at the scanned root). `GitleaksIntegration.build_command`
+# (ADR §8.5) translates this into gitleaks' own `--config` flag; relative to
+# the scanned workspace root, which is this repository's own root in CI
+# (`.github/workflows/ci.yml`, job "secrets").
+custom_rules_path = ".gitleaks.toml"

linceo-0.1.0/.dockerignore

@@ -0,0 +1,38 @@
+# Only pyproject.toml, uv.lock, README.md, LICENSE, NOTICE, and src/ are
+# ever COPYed into the build (see Dockerfile) — everything below is
+# excluded purely to keep the build context small and fast, mirroring
+# .gitignore plus the directories the image build itself never touches.
+
+.git/
+.github/
+
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+.venv/
+venv/
+.uv-cache/
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+.vscode/
+.idea/
+.DS_Store
+
+.env
+.env.*
+
+docs/
+tests/
+CONTRIBUTING.md
+AGENTS.md

linceo-0.1.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"

linceo-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,125 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  UV_LOCKED: "1"
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  types:
+    name: Types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run mypy -p linceo
+      - run: uv run mypy tests
+      - run: uv run mypy --strict -p linceo.core
+
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --frozen
+      - run: uv run pytest
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv build
+      - name: Install the built wheel into a clean environment
+        run: |
+          uv venv /tmp/linceo-smoke-test
+          uv pip install --python /tmp/linceo-smoke-test/bin/python dist/*.whl
+          /tmp/linceo-smoke-test/bin/linceo --version
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  secrets:
+    name: Secret scan
+    runs-on: ubuntu-latest
+    env:
+      GITLEAKS_VERSION: "8.30.1"
+      # Copied verbatim from gitleaks' own published
+      # gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz.sha256 entry for this
+      # release — the same version, and the same checksum-verification
+      # practice, the reference container image pins (ADR R4, Dockerfile).
+      GITLEAKS_SHA256: "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # Full history, not just the pushed range: gitleaks (via linceo's
+          # `secrets` integration) scans it entirely by design (ADR §10) —
+          # this is also, precisely, what a range-based diff scan
+          # (gitleaks-action's approach) cannot do on a repository's first
+          # push, where the range's parent commit does not exist yet.
+          fetch-depth: 0
+
+      - name: Install gitleaks (pinned, checksum-verified)
+        run: |
+          set -eu
+          curl -fsSL -o gitleaks.tar.gz \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          printf '%s  gitleaks.tar.gz\n' "${GITLEAKS_SHA256}" > gitleaks.tar.gz.sha256
+          sha256sum -c gitleaks.tar.gz.sha256
+          tar -xzf gitleaks.tar.gz gitleaks
+          chmod 0755 gitleaks
+          sudo mv gitleaks /usr/local/bin/gitleaks
+          rm -f gitleaks.tar.gz gitleaks.tar.gz.sha256
+          gitleaks version
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+
+      - name: linceo scan secrets (dogfooding this project's own tool)
+        run: uv run linceo scan secrets --format sarif > linceo-secrets.sarif
+
+      - name: Upload SARIF
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: linceo-secrets-sarif
+          path: linceo-secrets.sarif

linceo-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,117 @@
+name: Release
+
+# Triggered by pushing a release tag (`vX.Y.Z`, e.g. `v0.2.0`), never by a
+# branch push — see docs/RELEASING.md for the full procedure, including the
+# recovery steps for a release that fails partway through.
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+concurrency:
+  # Scoped to the tag itself: two different release tags may build in
+  # parallel, but the same tag can't race itself. Never cancelled
+  # mid-flight — a publish to PyPI must not be interrupted partway.
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  UV_LOCKED: "1"
+
+jobs:
+  # Mirrors the `lint`/`types`/`test` jobs in ci.yml: the publish job below
+  # must not run unless all three pass, and a release tag is not guaranteed
+  # to point at a commit that already went through ci.yml (a tag can be
+  # pushed against any commit) — so this workflow re-runs them itself
+  # rather than relying on ci.yml having already run.
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  types:
+    name: Types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run mypy -p linceo
+      - run: uv run mypy tests
+      - run: uv run mypy --strict -p linceo.core
+
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --frozen
+      - run: uv run pytest
+
+  publish:
+    name: Build and publish to PyPI
+    needs: [lint, types, test]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/linceo
+    permissions:
+      contents: read
+      # Trusted Publishing (OIDC): PyPI exchanges this token for a
+      # short-lived upload credential — no `PYPI_API_TOKEN` secret exists
+      # in this repository. Requires the `pypi` environment below to match
+      # exactly what's registered on PyPI for this project (owner
+      # `jdiegoisaza`, repo `linceo`, workflow `release.yml`, environment
+      # `pypi`).
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # Full history *and* tags: hatch-vcs (see pyproject.toml) derives
+          # the package version from the pushed tag, and a shallow clone
+          # would hide it, silently falling back to a dev version instead.
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - run: uv build
+
+      - name: Verify the git tag and the built package version match
+        run: |
+          set -eu
+          tag="${GITHUB_REF_NAME}"
+          expected_version="${tag#v}"
+          wheel="$(ls dist/*.whl)"
+          actual_version="$(basename "$wheel" | cut -d- -f2)"
+          if [ "$expected_version" != "$actual_version" ]; then
+            echo "::error::Tag $tag (expected version $expected_version) does not match the built package version $actual_version. Refusing to publish — see docs/RELEASING.md." >&2
+            exit 1
+          fi
+          echo "Verified: tag $tag matches package version $actual_version"
+
+      - name: Publish to PyPI (Trusted Publishing, OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

linceo-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# uv
+.uv-cache/
+
+# Test and coverage artifacts
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Editors and OS
+.vscode/
+.idea/
+.DS_Store
+
+# Local configuration overrides — never a source of truth for this
+# repository (see AGENTS.md, "no client configuration" and ADR-000 §R5)
+.env
+.env.*

linceo-0.1.0/.gitleaks.toml

@@ -0,0 +1,22 @@
+title = "linceo gitleaks configuration"
+
+# Extends gitleaks' own default ruleset rather than replacing it — this
+# project's dogfooding hook (AGENTS.md, ADR §4/R5) is meant to catch a real
+# secret landing anywhere in the repository, not a narrower custom ruleset.
+[extend]
+useDefault = true
+
+# `tests/` deliberately contains synthetic, gitleaks-rule-shaped values: the
+# golden fixtures under `tests/unit/fixtures/gitleaks/` are literal captured
+# output from real gitleaks runs against disposable repositories (see that
+# directory's README.md), and a handful of test modules inline the same
+# synthetic values to construct the fingerprints those fixtures should
+# produce. None of these are real credentials — allowlisting the whole test
+# tree is simpler to keep correct over time than chasing every new synthetic
+# value with its own regex, and "a real secret would only ever land in
+# `tests/`" is not a risk this project accepts anywhere else.
+[allowlist]
+description = "Synthetic secrets in test fixtures and test code (ADR §11) — not real credentials"
+paths = [
+  '''^tests/.*''',
+]

linceo-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,54 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-toml
+      - id: check-yaml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.12.9
+    hooks:
+      - id: uv-lock
+
+  # Dogfooding: this project ships a secrets-scanning integration (§10) and
+  # runs it on its own history from the first commit (§4/R5).
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+
+  # Local hook rather than mirrors-mypy: this project has a runtime
+  # dependency (Typer), and mirrors-mypy's isolated hook environment would
+  # need it declared separately and kept in sync by hand. Running through
+  # `uv run` reuses the same environment and pinned mypy version as CI.
+  - repo: local
+    hooks:
+      - id: mypy-project
+        name: mypy (project)
+        entry: uv run mypy -p linceo
+        language: system
+        pass_filenames: false
+        types: [python]
+      - id: mypy-tests
+        name: mypy (tests)
+        entry: uv run mypy tests
+        language: system
+        pass_filenames: false
+        types: [python]
+      - id: mypy-core-strict
+        name: mypy --strict (linceo.core)
+        entry: uv run mypy --strict -p linceo.core
+        language: system
+        pass_filenames: false
+        types: [python]

linceo-0.1.0/AGENTS.md

@@ -0,0 +1,106 @@
+# Repository conventions
+
+This document describes how this repository is organized and the hard rules
+that apply to any change made to it. The architectural contract itself lives
+in [`docs/adr/ADR-000-arquitectura-base-y-alcance-v0.1.md`](docs/adr/ADR-000-arquitectura-base-y-alcance-v0.1.md);
+this file is the day-to-day operating summary of that contract, not a
+substitute for it. Where the two disagree, the ADR wins.
+
+## Layout
+
+```
+src/linceo/
+  core/       Domain and ports. No third-party dependencies, no imports
+              from adapters/, providers/, or cli/. See "Layer boundaries"
+              below.
+  adapters/   Concrete ToolIntegration implementations (Gitleaks, Trivy).
+  providers/  Concrete ContextProvider implementations (local, azure_devops).
+              The only layer allowed to read os.environ.
+  testing/    Permanent test doubles and fixtures (FakeContextProvider,
+              FakeToolExecutor, golden fixtures). Public API, versioned with
+              the same backward-compatibility guarantees as any other
+              public module — see ADR §11.
+  cli/        Console entry point. Argument parsing and translation into
+              domain objects only; no orchestration logic of its own.
+
+tests/unit/         Fast tests, no real tool binaries required.
+tests/integration/  Tests that require real tool binaries on PATH. See
+                     tests/integration/README.md. Deselected by default
+                     (pytest marker `integration`); always run in this
+                     project's own CI.
+docs/adr/            Architecture decision records.
+```
+
+## Layer boundaries (hard rule)
+
+- `core/` imports nothing beyond the standard library and other `core`
+  modules. No `adapters`, `providers`, `cli`, or third-party package —
+  Typer included.
+- `adapters/` and `providers/` never import `typer`, `click`, or
+  `linceo.cli`.
+- `os.environ` is read only inside `providers/`, and only within that
+  package.
+
+`tests/unit/test_import_boundaries.py` enforces this by walking the AST of
+every module under `src/linceo/`. A change that violates a boundary fails
+that test, not just code review.
+
+## No placeholder code
+
+Nothing is committed as `pass`-only, a bare `...`, or a `TODO` / `FIXME`
+comment standing in for real logic. If a piece of functionality is not
+implemented, it is not created — including its empty function, its stub
+class, or its unused parameter. `ruff`'s `FIX` rule set enforces the
+TODO/FIXME/XXX/HACK part of this in CI; the rest is a review responsibility.
+
+A package `__init__.py` containing only a module docstring is not a
+placeholder — it documents what the package holds and makes it importable.
+
+## Language
+
+README, source code, docstrings, and commit messages are written in
+English. This applies to every file in the repository except the ADRs
+under `docs/adr/`, which are written in the language they were originally
+recorded in.
+
+Documentation in this repository is written for whoever reads the codebase
+next — it describes the project, not the process that produced a given
+change.
+
+## CLI framework: Typer, confined to `cli/`
+
+Typer is the only third-party dependency of the base package (see
+ADR §8.3 for the full decision record). Three rules follow directly from
+that decision:
+
+1. Typer is imported only inside `cli/`.
+2. The CLI layer translates arguments into domain objects and contains no
+   logic of its own — a full run must be executable from Python without
+   going through Typer.
+3. It is pinned to a major version range (`>=0.12,<1.0`) and its lockfile
+   entry is reviewed like any other dependency change.
+
+## Testing
+
+- `pytest` runs with coverage and the `integration` marker deselected by
+  default; see `tests/integration/README.md` for what belongs there.
+- Test doubles under `linceo.testing` are permanent, versioned public API —
+  not scaffolding to delete once real adapters exist (ADR §11).
+- `FakeToolExecutor` replays previously recorded output from a real tool
+  rather than simulating it from scratch, to minimize drift between what
+  the fake allows and what the real tool produces.
+
+## Plugin entry points
+
+Third-party tool integrations and context providers register under the
+`linceo.tool_integrations` and `linceo.context_providers` entry point
+groups declared in `pyproject.toml`. These groups exist from the first
+commit, even before any third-party plugin uses them, so the extension
+point is a stable part of the package's public contract rather than
+something bolted on later.
+
+## Task commands
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full list of `uv run`
+commands used to lint, type-check, test, and build this project. There is
+no Makefile — `uv` is already the project's task runner (ADR §3).

linceo-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+This project uses [`uv`](https://docs.astral.sh/uv/) for dependency
+management, environments, and Python interpreter management — there is no
+Makefile; every task below runs through `uv run` (see
+[`docs/adr/ADR-000-arquitectura-base-y-alcance-v0.1.md`](docs/adr/ADR-000-arquitectura-base-y-alcance-v0.1.md),
+§3). Repository conventions and hard rules live in
+[`AGENTS.md`](AGENTS.md); read it before making a change.
+
+## Setup
+
+```bash
+uv sync                          # installs the project and dev dependency group
+uv run pre-commit install        # installs the git hooks used by this repository
+```
+
+`uv sync` reads `uv.lock`. If `pyproject.toml` and `uv.lock` disagree, `uv
+sync --frozen` (used in CI) fails loudly instead of silently re-resolving —
+run `uv lock` locally and commit the updated lockfile if that happens.
+
+## Task commands
+
+| Task | Command |
+|---|---|
+| Lint | `uv run ruff check .` |
+| Format check | `uv run ruff format --check .` |
+| Apply formatting | `uv run ruff format .` |
+| Type-check (project) | `uv run mypy -p linceo` |
+| Type-check (tests) | `uv run mypy tests` |
+| Type-check (`core/`, strict) | `uv run mypy --strict -p linceo.core` |
+| Unit tests + coverage | `uv run pytest` |
+| Integration tests | `uv run pytest -m integration` (requires real tool binaries on `PATH`; see `tests/integration/README.md`) |
+| Build the package | `uv build` |
+| Run all pre-commit hooks | `uv run pre-commit run --all-files` |
+
+`uv run pytest` deselects the `integration` marker by default and enforces
+full coverage of `src/linceo` (`--cov-fail-under=100`, set in
+`pyproject.toml`). `core/` is checked with `mypy --strict` as a separate
+invocation from the rest of the project, rather than as a per-module
+override, because mypy has no `strict = true` config-file flag scoped to a
+single module — expanding `--strict`'s flag set by hand would silently
+drift from it whenever mypy changes what `--strict` means.
+
+## Before opening a pull request
+
+- `uv run pre-commit run --all-files` passes clean.
+- New code in `core/`, `adapters/`, `providers/`, or `cli/` includes tests;
+  coverage does not regress.
+- Commit messages are in English and describe the reasoning behind a
+  change, not just its mechanics.
+- Changes to the architectural contract in `docs/adr/` are proposed as a
+  new ADR or an explicit amendment to an existing one — never as a silent
+  edit that erases the record of what was previously decided and why.