charmlint 0.1.1__tar.gz

charmlint-0.1.1/.github/check-conventional-pr-title.py

@@ -0,0 +1,87 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+"""Check that a PR title follows the Conventional Commits specification.
+
+Reads the PR title from the PR_TITLE environment variable.
+Exits with a non-zero status and prints an error message if the title is invalid.
+
+Reference: https://www.conventionalcommits.org/en/v1.0.0/
+
+This repo defines a restricted set of commit types and disallows scopes in PR titles.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+
+_TYPES = frozenset({
+    'chore',
+    'ci',
+    'docs',
+    'feat',
+    'fix',
+    'perf',
+    'refactor',
+    'revert',
+    'test',
+})
+
+# <type>[optional scope][optional !]: <description>
+_PATTERN = re.compile(
+    r'^(?P<type>[A-Za-z]+)'  # lower-case only, but let this be validated by _TYPES
+    r'(?:\((?P<scope>[^()]+)\))?'
+    r'(?P<breaking>!)?'
+    r': '
+    r'(?P<description>.+)$'
+)
+
+# Adjust this URL when copying into a new repo — point at <this repo>/CONTRIBUTING.md#pull-requests.
+_HELP_URL = 'https://github.com/canonical/charmlint/blob/main/CONTRIBUTING.md#pull-requests'
+
+
+def _main() -> None:
+    title = os.environ.get('PR_TITLE', '').strip()
+    if not title:
+        print('PR_TITLE environment variable is not set or empty.', file=sys.stderr)
+        sys.exit(1)
+
+    match = _PATTERN.match(title)
+    if not match:
+        print(
+            f'PR title does not follow Conventional Commits format.\n'
+            f'Expected: <type>[!]: <description>\n'
+            f'Got: {title!r}\n'
+            f'Read more: {_HELP_URL}',
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    scope = match.group('scope')
+    if scope is not None:
+        print(
+            f'Scopes must not be used in PR titles.\n'
+            f'Got: {title!r}\n'
+            f'Read more: {_HELP_URL}',
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    commit_type = match.group('type')
+    if commit_type not in _TYPES:
+        print(
+            f'Invalid type {commit_type!r} in PR title.\n'
+            f'Valid types: {", ".join(sorted(_TYPES))}\n'
+            f'Got: {title!r}\n'
+            f'Read more: {_HELP_URL}',
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    print(f'OK: {title!r}')
+
+
+if __name__ == '__main__':
+    _main()

charmlint-0.1.1/.github/dependabot.yaml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"  # Hard-coded to the 1st of the month.
+    cooldown:
+      default-days: 7  # Don't adopt a release until it's 7 days old.
+    labels:
+      - "dependencies"
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 0  # Security updates only.
+    labels:
+      - "dependencies"

charmlint-0.1.1/.github/workflows/ci.yaml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["**"]
+  workflow_call:
+
+permissions: {}
+
+jobs:
+  python-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
+      - name: uv lock --check
+        run: uv lock --check
+      - name: ruff check
+        run: uv run --group dev ruff check src tests
+      - name: ruff format
+        run: uv run --group dev ruff format --check src tests
+      - name: ty
+        run: uv run --group dev ty check src tests
+
+  python-unit:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Unit tests
+        run: uv run --group dev pytest --cov=charmlint --cov-report=term-missing

charmlint-0.1.1/.github/workflows/dependency-review.yaml

@@ -0,0 +1,22 @@
+name: Dependency Review
+
+on:
+  pull_request:
+    branches: ["**"]
+
+permissions: {}
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/dependency-review-action@v5
+        with:
+          fail-on-severity: high
+          comment-summary-in-pr: on-failure

charmlint-0.1.1/.github/workflows/publish.yaml

@@ -0,0 +1,104 @@
+name: Publish
+
+# Publish to PyPI on tag push.
+# Publish to TestPyPI on manual dispatch to exercise the same key steps.
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  publish:
+    name: Build and publish to ${{ github.event_name == 'push' && 'PyPI' || 'TestPyPI' }} (Trusted Publishing)
+    runs-on: ubuntu-latest
+    environment:
+      # The name must match the environment registered with the trusted
+      # publisher on PyPI (and separately on TestPyPI).
+      name: ${{ github.event_name == 'push' && 'publish-pypi' || 'publish-testpypi' }}
+      # Cosmetic: the link shown against the deployment in the GitHub UI.
+      url: ${{ github.event_name == 'push' && 'https://pypi.org/p/charmlint' || 'https://test.pypi.org/p/charmlint' }}
+    permissions:
+      id-token: write  # OIDC to PyPI + sigstore for attestations.
+      attestations: write  # Write build-provenance + SBOM predicates.
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Check the tag matches the project version
+        if: github.event_name == 'push'
+        env:
+          TAG: ${{ github.ref_name }}
+        shell: python
+        run: |
+          import os, pathlib, sys, tomllib
+          tag = os.environ["TAG"]
+          version = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"]
+          if tag != f"v{version}":
+              print(f"::error::Tag {tag} does not match pyproject.toml version {version} (expected v{version}).")
+              sys.exit(1)
+
+      - name: Give the build a .dev suffix
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          RUN_NUMBER: ${{ github.run_number }}
+        shell: python
+        run: |
+          import os, pathlib, re, sys, tomllib
+          run_number = os.environ["RUN_NUMBER"]
+          path = pathlib.Path("pyproject.toml")
+          # Write dev version.
+          path.write_text(re.sub(
+              r'^version = "([^"]+)"', rf'version = "\1.dev{run_number}"', path.read_text(),
+              count=1, flags=re.MULTILINE,
+          ))
+          # Ensure we wrote the dev version correctly.
+          version = tomllib.loads(path.read_text())["project"]["version"]
+          if not version.endswith(f".dev{run_number}"):
+              print(f"::error::Failed to add a .dev suffix; version is {version}.")
+              sys.exit(1)
+          print(f"Building {version}")
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
+        with:
+          enable-cache: false
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Generate CycloneDX SBOM
+        run: |
+          uv sync --frozen --no-dev
+          uv run --with cyclonedx-bom cyclonedx-py environment .venv \
+            --output-format JSON \
+            --output-file sbom.cdx.json
+
+      - name: Attest build provenance (SLSA)
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6  # v4.2.2
+        with:
+          subject-path: 'dist/*'
+
+      - name: Attest SBOM (CycloneDX)
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6  # v4.2.2
+        with:
+          subject-path: 'dist/*'
+          sbom-path: sbom.cdx.json
+
+      # Only the SBOM is uploaded: the sdist and wheel go to PyPI moments later
+      # and stay there, whereas this is the only convenient copy of the SBOM
+      # (the other being inside the attestation predicate).
+      - name: Upload SBOM artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: sbom
+          path: sbom.cdx.json
+          if-no-files-found: error
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
+        with:
+          repository-url: ${{ github.event_name == 'push' && 'https://upload.pypi.org/legacy/' || 'https://test.pypi.org/legacy/' }}

charmlint-0.1.1/.github/workflows/validate-pr-title.yaml

@@ -0,0 +1,21 @@
+---
+name: "Validate PR Title"
+# Ensure that the PR title conforms to the Conventional Commits and our choice of types and scopes, so that library version bumps can be detected automatically
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+permissions: {}
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - run: python3 .github/check-conventional-pr-title.py
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}

charmlint-0.1.1/.github/workflows/zizmor.yaml

@@ -0,0 +1,34 @@
+name: Workflow static checks
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["**"]
+
+permissions: {}
+
+jobs:
+  zizmor:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
+
+      - name: Run zizmor
+        run: uv run --group dev zizmor --format=sarif . > results.sarif
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload SARIF file
+        uses: github/codeql-action/upload-sarif@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28  # v4.37.8
+        with:
+          sarif_file: results.sarif
+          category: zizmor

charmlint-0.1.1/.github/zizmor.yaml

@@ -0,0 +1,8 @@
+rules:
+  unpinned-uses:
+    config:
+      # SHA-pin everything by default; allow ref/tag pins only for first-party
+      # GitHub-owned actions.
+      policies:
+        "actions/*": ref-pin
+        "github/*": ref-pin

charmlint-0.1.1/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.venv/
+venv/
+ENV/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+
+# Type checker caches
+.ty/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Claude Code (personal/local only; commit shared settings explicitly)
+.claude/settings.local.json
+.claude/worktrees/
+.claude/scratch/

charmlint-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,61 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^tests/fixtures/
+      - id: end-of-file-fixer
+        exclude: ^tests/fixtures/
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: detect-private-key
+
+  # Local hooks run the tools through `uv run`, so the versions come from
+  # pyproject.toml's `dev` dependency group. This keeps pre-commit and CI on
+  # exactly the same tool versions.
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run --group dev -- ruff check --fix --exit-non-zero-on-fix src tests
+        language: system
+        files: \.py$
+        pass_filenames: false
+        require_serial: true
+
+      - id: ruff-format
+        name: ruff format
+        entry: uv run --group dev -- ruff format src tests
+        language: system
+        files: \.py$
+        pass_filenames: false
+        require_serial: true
+
+      - id: ty
+        name: ty
+        entry: uv run --group dev -- ty check src tests
+        language: system
+        files: \.py$
+        pass_filenames: false
+        require_serial: true
+
+      - id: pytest
+        name: pytest
+        entry: uv run --group dev -- pytest --maxfail=1 -q
+        language: system
+        files: \.py$
+        pass_filenames: false
+        stages: [pre-push]
+
+      - id: uv-lock-check
+        name: uv lock --check
+        entry: uv lock --check
+        language: system
+        files: ^(pyproject\.toml|uv\.lock)$
+        pass_filenames: false
+        require_serial: true

charmlint-0.1.1/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md
+
+## What this repo is
+
+`charmlint` is a charm-aware, model-agnostic linter for [Juju](https://juju.is/) charms — rules check charm source code against Canonical's charm best practices (observability, security, testing, metadata, configuration).
+
+## Dev setup
+
+```bash
+uv sync --dev
+```
+
+## Tests
+
+```bash
+uv run --group dev pytest
+```
+
+## Lint
+
+```bash
+uv run --group dev ruff check src tests
+uv run --group dev ruff format --check src tests
+uv run --group dev ty check src tests
+```
+
+`pre-commit` runs the same tools through `uv run` (config in `.pre-commit-config.yaml`); tool versions live in `pyproject.toml`'s `dev` dependency group.
+
+## Conventions
+
+- Commits and PR titles follow [Conventional Commits](https://www.conventionalcommits.org/); PR-title types enforced by `.github/workflows/validate-pr-title.yaml` (see [CONTRIBUTING.md](CONTRIBUTING.md#pull-requests) for the list).
+- Rule IDs follow `PREFIX###` — see [docs/id-scheme.md](docs/id-scheme.md) for the prefix catalogue.
+- Runtime dependencies are kept minimal (PyYAML only); the `_pypi_attest/` helper is stdlib-only by design.
+
+## Security
+
+See [SECURITY.md](SECURITY.md).

charmlint-0.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+This project follows the [Ubuntu Code of
+Conduct](https://ubuntu.com/community/ethos/code-of-conduct).
+
+Concerns and reports go to the
+[Ubuntu Community Council](https://wiki.ubuntu.com/CommunityCouncil),
+which administers the CoC's reporting and enforcement process. See
+the [Ubuntu Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct)
+for details.

charmlint-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+We welcome contributions to this project!
+
+Before working on changes, please consider [opening an issue](https://github.com/canonical/charmlint/issues) explaining your use case. If you would like to chat with us about your use cases or proposed implementation, you can reach us on [Matrix](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) or [Discourse](https://discourse.charmhub.io/).
+
+<!--
+For detailed dev-environment setup, build, and test instructions, link here to
+the substantive doc if one exists (HACKING.md, docs/contributing.md, etc.).
+Most Charm Tech repos keep this section inline rather than redirecting.
+-->
+
+# Project status
+
+charmlint is early work, and the implementation is subject to change (and probably will change). Please don't treat anything under `src/` as settled, or build on it expecting the internals to stay where they are.
+
+What we're trying to get right at the moment is the set of rules. That's where the care goes: what each rule is for, what it does and doesn't match, and the tests that pin that behaviour down. The tests themselves might change shape later - we'd like them to be less Python-specific, since charmlint is meant to be model-agnostic - so it's not worth over-investing in the current fixtures.
+
+The code is almost entirely agent-generated, and that's likely to continue for a while yet.
+
+# Review
+
+Review still matters, but the weight isn't spread evenly.
+
+Most of the attention belongs on the rule itself:
+
+* Is this a good thing to have a rule about at all? A rule that's noisy, or that encodes a personal preference rather than a practice we'd defend, costs more than it's worth.
+* What does it match, and (more importantly) what does it not match? A false positive is worse than a gap.
+* Do the tests actually capture that? A test that only exercises the case the rule was written for isn't telling us much.
+
+The implementation gets a lighter pass. We're more lenient about "agent-isms" here than in the other Charm Tech repos: if the code is more verbose or more defensive than a person would have written it, and it's correct and readable, that's ok. That's not a license to let quality slide - we still want code we'd be happy to maintain, and unnecessary comments (especially ones referring to history) should still go. But if you find yourself choosing, spend the time on the rule rather than on the style of the code implementing it.
+
+# AI
+
+You're welcome to submit pull requests that are partly or entirely generated using generative AI tools. However, you must review the code yourself before moving the PR out of draft -- by submitting the PR, you are claiming personal responsibility for its quality and suitability. If you are not capable of reviewing the PR, please do not submit it (maybe you'd like to open an issue instead). PRs that are clearly (co-)authored by tools will be closed without review unless there is a human author that claims responsibility for the PR.
+
+Please do not use tools (such as GitHub Copilot) to provide PR reviews. The Charm Tech team also has access to these tools, and will use them when appropriate.
+
+# Pull requests
+
+Changes are proposed as [pull requests on GitHub](https://github.com/canonical/charmlint/pulls).
+
+- Work on a branch in your own fork.
+- Sequence your commits logically if possible. But don't worry too much -- we'll squash to `main` after review.
+- Don't force-push after review has started.
+- Follow [conventional commit style](https://www.conventionalcommits.org/en/) for the PR title (not required for individual commits).
+
+The allowed PR-title types — enforced by `.github/workflows/validate-pr-title.yaml` — are:
+
+`chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `test`
+
+Examples:
+
+- feat: add support for X
+- fix!: correct the type hinting for config data
+- docs: clarify how to use Y
+- ci: tighten the publish workflow
+
+We consider this project too small to use scopes, so we don't use them.
+
+## Branch updates
+
+Before you ask for review, please rebase your branch onto `main` so that your changes will merge cleanly.
+
+If you need to bring in the latest changes from `main` after the review has started, please use a merge commit.
+
+# Releasing
+
+<!--
+Most Charm Tech repos that produce a release artefact include a section
+describing how to cut one. The shape depends on what the repo produces:
+
+- PyPI package (uv build → Trusted Publishing): tag → GitHub Release →
+  release workflow publishes via pypa/gh-action-pypi-publish (OIDC).
+- snap (snapcraft / launchpad build recipe): document the release channel
+  promotion flow (edge → beta → candidate → stable).
+- Go binary (goreleaser): document `git tag vX.Y.Z && git push --tags`
+  and which workflow goreleaser runs from.
+- Charm on Charmhub (charmcraft): document the track/channel and the
+  upload-resource / promote-charm flow.
+- Library shipped via canonical/charmlibs: document the version-bump and
+  publish-library flow.
+
+Replace this comment with the actual procedure. Repos that don't produce a
+discrete release artefact (demos, tutorials, specs, registries) can drop the
+whole section.
+-->