agentslint 0.1.0__tar.gz

agentslint-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,88 @@
+name: Bug report
+description: Report an incorrect diagnostic, missed reference, crash, or integration problem.
+title: "[Bug] "
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping improve agentslint. Please reduce the report to the smallest safe repository example you can share. Remove secrets and private source content from all logs and snippets.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched existing issues for the same behavior.
+          required: true
+        - label: I removed secrets, credentials, and private repository content from this report.
+          required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: agentslint version
+      description: Provide the installed or pinned package version.
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: Include Python version, operating system, installation method, and whether the target
+        is a Git worktree.
+      placeholder: "Python 3.12, Ubuntu 24.04, uvx, Git worktree"
+    validations:
+      required: true
+
+  - type: textarea
+    id: command
+    attributes:
+      label: Command
+      description: Provide the exact command and flags used.
+      render: shell
+      placeholder: agentslint check . --strict
+    validations:
+      required: true
+
+  - type: textarea
+    id: fixture
+    attributes:
+      label: Minimal repository example
+      description: Show the relevant AGENTS.md excerpt, directory tree, and manifest fragments. A small
+        public reproduction repository is also welcome.
+      placeholder: |
+        AGENTS.md:
+          Run `example check`.
+
+        Repository:
+          AGENTS.md
+          example.toml
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Include the complete diagnostic or traceback after removing sensitive content.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: Explain what agentslint should have resolved or reported instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add anything relevant about project layout, scope markers, configuration, or CI behavior.
+    validations:
+      required: false

agentslint-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

agentslint-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,77 @@
+name: Feature request
+description: Propose a resolver, reference type, integration, or workflow improvement.
+title: "[Feature] "
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        agentslint favors static, read-only checks that can be proven from repository content. Concrete examples help determine whether a proposal fits that boundary.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched existing issues for a similar proposal.
+          required: true
+        - label: This request does not require agentslint to execute documented commands or application
+            code.
+          required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Command resolver
+        - Path, link, or Markdown extraction
+        - Tool declaration inventory
+        - Configuration
+        - CLI or output format
+        - CI or pre-commit integration
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Use case
+      description: What real AGENTS.md instruction cannot be validated today, and what repository drift
+        should agentslint catch?
+      placeholder: |
+        AGENTS.md contains:
+          Run `example verify api`.
+
+        The repository declares valid tasks in:
+          example.toml
+    validations:
+      required: true
+
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Proposed behavior
+      description: Describe valid, invalid, and ambiguous cases and the diagnostic you would expect.
+    validations:
+      required: true
+
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Static evidence
+      description: Which tracked files or manifests allow agentslint to resolve this without executing
+        a command, importing code, or using the network?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Explain current workarounds, narrower checks, or syntax that could make the instruction
+        unambiguous.
+    validations:
+      required: false

agentslint-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Description
+
+Description for the PR
+
+### Added
+
+- None
+
+### Updated
+
+- None
+
+### Deleted
+
+- None

agentslint-0.1.0/.github/workflows/check.yml

@@ -0,0 +1,33 @@
+name: AGENTS.md Integrity
+
+on:
+  workflow_call:
+    inputs:
+      strict:
+        description: Fail when agentslint emits warnings
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read  # Required by actions/checkout to read repository files.
+
+jobs:
+  agentslint:
+    name: agentslint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          version: "0.11.16"
+          python-version: "3.11"
+          enable-cache: true
+      - name: Check AGENTS.md references
+        if: ${{ !inputs.strict }}
+        run: uvx --from agentslint==0.1.0 agentslint check . --format github
+      - name: Check AGENTS.md references strictly
+        if: ${{ inputs.strict }}
+        run: uvx --from agentslint==0.1.0 agentslint check . --format github --strict

agentslint-0.1.0/.github/workflows/ci_cd.yaml

@@ -0,0 +1,123 @@
+name: CI/CD
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+permissions:
+  contents: read  # Required by actions/checkout to read repository files.
+
+env:
+  UV_VERSION: "0.11.16"
+  PYTHON_VERSION: "3.11"
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --locked --all-groups
+      - run: uv run --frozen pytest
+
+  quality:
+    name: Quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: ${{ env.PYTHON_VERSION }}
+          enable-cache: true
+      - run: uv sync --locked --all-groups
+      - run: uv run --frozen ruff check .
+      - run: uv run --frozen ruff format --check .
+      - run: uv run --frozen ty check
+      - run: uv run --frozen agentslint check . --strict
+      - run: uv run --frozen pre-commit run --all-files --show-diff-on-failure
+
+  build:
+    name: Build distribution
+    if: ${{ github.event_name == 'pull_request' }} # this also runs on deploy
+    needs: [test, quality]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: ${{ env.PYTHON_VERSION }}
+          enable-cache: true
+      - name: Verify tag matches package version
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
+        run: |
+          if [[ "v$(uv version --short)" != "$GITHUB_REF_NAME" ]]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject.toml version $(uv version --short)."
+            exit 1
+          fi
+      - run: uv build
+
+  deploy:
+    name: Publish release
+    needs: [test, quality]
+    if: ${{ startsWith(github.ref, 'refs/tags/v') }}
+    runs-on: ubuntu-latest
+    env:
+      GH_REPO: ${{ github.repository }}
+    environment:
+      name: pypi
+      url: https://pypi.org/project/agentslint/
+    permissions:
+      contents: write  # Required to create the GitHub release and upload distribution assets.
+      id-token: write  # Required for PyPI trusted publishing through OIDC.
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: ${{ env.PYTHON_VERSION }}
+          enable-cache: true
+      - name: Build release distributions
+        run: uv build
+      - name: Create or update draft GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
+            gh release upload "$GITHUB_REF_NAME" dist/* --clobber
+          else
+            gh release create "$GITHUB_REF_NAME" dist/* --draft --generate-notes --verify-tag
+          fi
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247  # release/v1
+      - name: Publish GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release edit "$GITHUB_REF_NAME" --draft=false --latest
+      - name: Notify deployment result
+        if: ${{ always() }}
+        uses: jyablonski/actions/deploy-notification@3ff8e3e6dcfb804cc5fc0aed41be72e3ed98a718  # v1
+        with:
+          slack-webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+          template: ${{ job.status == 'success' && 'deployment-success' || 'pipeline-failure' }}
+          deployment-url: https://pypi.org/project/agentslint/

agentslint-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv
+docs/plans/**

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

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.0
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/astral-sh/ty-pre-commit
+    rev: v0.0.63
+    hooks:
+      - id: ty
+        args: [--locked]
+
+  - repo: https://github.com/lyz-code/yamlfix
+    rev: 1.19.1
+    hooks:
+      - id: yamlfix
+
+  - repo: https://github.com/adrienverge/yamllint
+    rev: v1.38.0
+    hooks:
+      - id: yamllint
+        args: [--strict]
+
+  - repo: local
+    hooks:
+      - id: agentslint
+        name: agentslint check
+        entry: .venv/bin/python -m agentslint check . --strict
+        language: system
+        always_run: true
+        pass_filenames: false

agentslint-0.1.0/.yamllint.yaml

@@ -0,0 +1,10 @@
+extends: default
+
+rules:
+  comments:
+    min-spaces-from-content: 1
+  document-start: disable
+  line-length: disable
+  truthy:
+    allowed-values: ["true", "false", "on"]
+    check-keys: false

agentslint-0.1.0/AGENTS.md

@@ -0,0 +1,58 @@
+# Repository instructions
+
+## Purpose
+
+agentslint is a Python CLI that statically validates referential integrity in tracked `AGENTS.md` files. It must remain read-only with respect to the repository being checked and must never execute documented commands, import application code, install target-project dependencies, or access external URLs.
+
+## Setup and validation
+
+- Run `make setup` to create or refresh the locked development environment.
+- Run `make test` for the complete pytest suite and coverage gate.
+- Run `make quality` for Ruff, ty, YAML checks, and the strict agentslint self-check.
+- Run `make build` to create the wheel and source distribution.
+- Keep supported Python versions and package metadata in `pyproject.toml`.
+
+## Project layout
+
+- CLI argument and exit-code handling lives in `src/agentslint/cli.py`.
+- Repository discovery and the immutable workspace index live in `src/agentslint/discovery.py` and `src/agentslint/workspace.py`.
+- Markdown extraction lives in `src/agentslint/markdown.py`.
+- Validation orchestration and registered rules live in `src/agentslint/engine.py`.
+- Resolver implementations live under `src/agentslint/resolvers/`.
+- Normal tests live under `tests/`; end-to-end repository fixtures live under `tests/fixtures/e2e/`.
+- Resolver contribution guidance lives in `docs/adding-a-resolver.md`.
+
+## Implementation conventions
+
+- Use keyword-only parameters for functions where possible.
+- Preserve the existing immutable `Reference` and `Diagnostic` contracts.
+- Return tuples of diagnostics and use `resolvers.base.diagnostic` for consistent source locations.
+- Read repository files through `Workspace` so boundary, size, encoding, parsing, and caching protections remain active.
+- Treat confirmed stale references as errors and genuinely ambiguous or unsupported constructs as warnings.
+- Prefer a narrow resolver extension over a general plugin interface during the `0.x` series.
+- Register new diagnostic rules in the engine and add advisory rules to configuration only when severity overrides are safe.
+- Do not weaken validation globally to accommodate an example; use an exact, reasoned ignore when the example is intentional.
+
+## Tests
+
+- Add focused valid, invalid, ambiguous, nested-scope, and hostile-input tests for resolver changes.
+- Extend the end-to-end fixtures when behavior crosses extraction, discovery, configuration, or CLI boundaries.
+- Assert rule, severity, reference, and useful message content rather than only diagnostic counts.
+- Never make a safety test execute repository content.
+- Maintain the coverage floor configured in `pyproject.toml`.
+
+## Documentation
+
+- Keep `README.md` accurate for both GitHub and PyPI.
+- Update `docs/adding-a-resolver.md` when resolver wiring or contributor expectations change.
+- Do not claim support for syntax that is only partially or heuristically validated.
+- Keep prose paragraphs and list items on one logical line.
+
+## Releases
+
+- Keep repository hooks in `.pre-commit-config.yaml`; this repository does not publish remote hook metadata.
+- Treat `pyproject.toml` as the package-version source of truth and read the installed version through distribution metadata.
+- The package version must be committed to `pyproject.toml` and `uv.lock` on synchronized `main` before release.
+- Run `make release VERSION=v0.1.0` with the matching version to create and push an annotated tag.
+- The tag triggers `.github/workflows/ci_cd.yaml`, which validates, builds, uploads GitHub Release assets, and publishes to PyPI.
+- Never bypass the clean-tree, branch, version, or remote synchronization checks in the release target.

agentslint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentslint contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentslint-0.1.0/Makefile

@@ -0,0 +1,61 @@
+SHELL := /bin/sh
+
+UV ?= uv
+
+.PHONY: setup test quality build release
+
+setup:
+	$(UV) sync --locked --all-groups
+
+test:
+	$(UV) run --frozen pytest
+
+quality:
+	$(UV) run --frozen ruff check .
+	$(UV) run --frozen ruff format --check src tests
+	$(UV) run --frozen ty check
+	$(UV) run --frozen agentslint check . --strict
+	$(UV) run --frozen pre-commit run --all-files --show-diff-on-failure
+
+build:
+	$(UV) build
+
+release:
+	@if [ -z "$(VERSION)" ]; then \
+		echo "VERSION is required; use make release VERSION=v0.1.0"; \
+		exit 2; \
+	fi
+	@printf '%s\n' "$(VERSION)" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z.-]+)?$$' || { \
+		echo "VERSION must be a semantic version prefixed with v, such as v0.1.0"; \
+		exit 2; \
+	}
+	@package_version="$$( $(UV) version --short )"; \
+	tag_version="$$(printf '%s' "$(VERSION)" | sed 's/^v//')"; \
+	if [ "$$package_version" != "$$tag_version" ]; then \
+		echo "pyproject.toml version $$package_version does not match $(VERSION)"; \
+		echo "Run: uv version $$tag_version"; \
+		exit 2; \
+	fi; \
+	if ! grep -Fq "agentslint==$$tag_version" .github/workflows/check.yml; then \
+		echo ".github/workflows/check.yml must pin agentslint==$$tag_version"; \
+		exit 2; \
+	fi
+	@if [ "$$(git branch --show-current)" != "main" ]; then \
+		echo "releases must be created from main"; \
+		exit 2; \
+	fi
+	@if [ -n "$$(git status --porcelain)" ]; then \
+		echo "the working tree must be clean before creating a release"; \
+		exit 2; \
+	fi
+	@git fetch --quiet origin main --tags
+	@if [ "$$(git rev-parse HEAD)" != "$$(git rev-parse origin/main)" ]; then \
+		echo "local main must match origin/main before creating a release"; \
+		exit 2; \
+	fi
+	@if git rev-parse --quiet --verify "refs/tags/$(VERSION)" >/dev/null; then \
+		echo "tag $(VERSION) already exists"; \
+		exit 2; \
+	fi
+	git tag --annotate "$(VERSION)" --message "Release $(VERSION)"
+	git push origin "$(VERSION)"