pkglint 0.1.0__tar.gz

pkglint-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+/pkglint
+/public/
+/.cache/
+/dist/
+__pycache__/

pkglint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamison Lahman
+
+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.

pkglint-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: pkglint
+Version: 0.1.0
+Summary: Security-focused linter for Arch Linux PKGBUILDs
+Project-URL: Repository, https://github.com/jmelahman/pkglint
+Author-email: Jamison Lahman <jamison@lahman.dev>
+License: MIT License
+        
+        Copyright (c) 2026 Jamison Lahman
+        
+        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.
+License-File: LICENSE
+Keywords: archlinux,aur,linter,pkgbuild,security,supply-chain,tooling,tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Go
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+
+# pkglint
+
+A security-focused linter for Arch Linux PKGBUILDs.
+
+pkglint statically analyzes PKGBUILDs and their install scriptlets — **without ever
+sourcing them** — and reports findings about source integrity, build hermeticity, code
+execution, and persistence patterns, condensed into a letter grade per package. It is
+built on a real bash AST ([mvdan.cc/sh](https://github.com/mvdan/sh)), so the
+quoting/line-continuation tricks that evade regex-based scanners don't work here.
+
+```
+$ pkglint ~/pkgbuilds/somepkg
+somepkg: grade F, 3 finding(s)
+  PKGBUILD:16:3: critical [PB304] a network download is piped straight into bash and executed
+  PKGBUILD:11:1: error [PB101] remote source "http://..." has no checksum (SKIP): the download is never verified
+  PKGBUILD:24:3: error [PB402] sudo escalates privileges during a build; ...
+```
+
+## Install
+
+```shell
+go install github.com/jmelahman/pkglint@latest
+```
+
+## Usage
+
+```shell
+pkglint [flags] [path ...]     # paths are package dirs or PKGBUILD files (default: .)
+
+  --format text|json           # output format
+  --fail-on SEVERITY           # exit 1 at or above: info, warn, error (default), critical, never
+  --ignore PB105,PB206         # disable rules
+  --rules                      # list every rule with its documentation
+```
+
+Suppress a reviewed, intentional finding inline:
+
+```bash
+# pkglint: ignore=PB204
+go build -o "$pkgname" .
+```
+
+## Rules
+
+| Group | Rules | What they catch |
+|-------|-------|-----------------|
+| Integrity | PB101–PB107 | SKIP/weak checksums, unpinned VCS sources, unencrypted transports, source/url domain mismatches, DLAGENTS overrides |
+| Hermeticity | PB201–PB206 | network access outside `prepare()`, `pip` without `--require-hashes`, unlocked `cargo`, implicit Go module downloads, disabled checksum databases |
+| Execution | PB301–PB307 | top-level code, `eval`, decode-and-execute, download-and-execute (including `eval "$(curl ...)"` and `source <(wget ...)"` variants), `/dev/tcp`, unresolvable command names, embedded payloads |
+| Filesystem | PB401–PB403 | writes outside `$srcdir`/`$pkgdir`, privilege escalation, setuid files |
+| Scriptlets | PB501–PB502 | network access and persistence (crontabs, systemd units, shell profiles, login-capable users) in `.install` files running as root |
+| Consistency | PB601–PB602 | PKGBUILD / .SRCINFO drift, network access in `pkgver()` |
+
+`pkglint --rules` prints the full documentation for each.
+
+Grading: any critical → **F**, any error → **D**, 3+ warns → **C**, 1–2 warns → **B**,
+otherwise **A**.
+
+A grade is a **static hygiene score, not a malware verdict** — it measures how reviewable
+and reproducible a PKGBUILD is. A low grade means "worth reviewing", never "malicious",
+and a high grade is not an endorsement. Static analysis cannot catch a malicious upstream
+release pinned with a perfectly valid checksum.
+
+## Report card site
+
+`site/` generates a static "AUR Report Card" — grades, per-package finding pages,
+per-rule documentation pages, `results.json`, and embeddable SVG badges:
+
+```shell
+go run ./site -maintainer Jamison -top 500 -out public
+```
+
+It downloads the AUR metadata dump once a day, fetches package snapshots politely
+(throttled, cached by `LastModified`), and scans everything in-process.
+
+## Roadmap
+
+- A `makepkg` shim so AUR helpers lint before building (`yay --makepkg pkglint-makepkg`,
+  paru `[bin] Makepkg`)
+- Sandboxed builds: containerized `makepkg` with the package artifact installed on the
+  host via `pacman -U`
+- Hermetic builds: two-phase `makepkg -o` (network) / `makepkg -e` (`--network=none`),
+  with these lint rules enforcing the conventions that make that split work
+
+## License
+
+MIT

pkglint-0.1.0/README.md

@@ -0,0 +1,87 @@
+# pkglint
+
+A security-focused linter for Arch Linux PKGBUILDs.
+
+pkglint statically analyzes PKGBUILDs and their install scriptlets — **without ever
+sourcing them** — and reports findings about source integrity, build hermeticity, code
+execution, and persistence patterns, condensed into a letter grade per package. It is
+built on a real bash AST ([mvdan.cc/sh](https://github.com/mvdan/sh)), so the
+quoting/line-continuation tricks that evade regex-based scanners don't work here.
+
+```
+$ pkglint ~/pkgbuilds/somepkg
+somepkg: grade F, 3 finding(s)
+  PKGBUILD:16:3: critical [PB304] a network download is piped straight into bash and executed
+  PKGBUILD:11:1: error [PB101] remote source "http://..." has no checksum (SKIP): the download is never verified
+  PKGBUILD:24:3: error [PB402] sudo escalates privileges during a build; ...
+```
+
+## Install
+
+```shell
+go install github.com/jmelahman/pkglint@latest
+```
+
+## Usage
+
+```shell
+pkglint [flags] [path ...]     # paths are package dirs or PKGBUILD files (default: .)
+
+  --format text|json           # output format
+  --fail-on SEVERITY           # exit 1 at or above: info, warn, error (default), critical, never
+  --ignore PB105,PB206         # disable rules
+  --rules                      # list every rule with its documentation
+```
+
+Suppress a reviewed, intentional finding inline:
+
+```bash
+# pkglint: ignore=PB204
+go build -o "$pkgname" .
+```
+
+## Rules
+
+| Group | Rules | What they catch |
+|-------|-------|-----------------|
+| Integrity | PB101–PB107 | SKIP/weak checksums, unpinned VCS sources, unencrypted transports, source/url domain mismatches, DLAGENTS overrides |
+| Hermeticity | PB201–PB206 | network access outside `prepare()`, `pip` without `--require-hashes`, unlocked `cargo`, implicit Go module downloads, disabled checksum databases |
+| Execution | PB301–PB307 | top-level code, `eval`, decode-and-execute, download-and-execute (including `eval "$(curl ...)"` and `source <(wget ...)"` variants), `/dev/tcp`, unresolvable command names, embedded payloads |
+| Filesystem | PB401–PB403 | writes outside `$srcdir`/`$pkgdir`, privilege escalation, setuid files |
+| Scriptlets | PB501–PB502 | network access and persistence (crontabs, systemd units, shell profiles, login-capable users) in `.install` files running as root |
+| Consistency | PB601–PB602 | PKGBUILD / .SRCINFO drift, network access in `pkgver()` |
+
+`pkglint --rules` prints the full documentation for each.
+
+Grading: any critical → **F**, any error → **D**, 3+ warns → **C**, 1–2 warns → **B**,
+otherwise **A**.
+
+A grade is a **static hygiene score, not a malware verdict** — it measures how reviewable
+and reproducible a PKGBUILD is. A low grade means "worth reviewing", never "malicious",
+and a high grade is not an endorsement. Static analysis cannot catch a malicious upstream
+release pinned with a perfectly valid checksum.
+
+## Report card site
+
+`site/` generates a static "AUR Report Card" — grades, per-package finding pages,
+per-rule documentation pages, `results.json`, and embeddable SVG badges:
+
+```shell
+go run ./site -maintainer Jamison -top 500 -out public
+```
+
+It downloads the AUR metadata dump once a day, fetches package snapshots politely
+(throttled, cached by `LastModified`), and scans everything in-process.
+
+## Roadmap
+
+- A `makepkg` shim so AUR helpers lint before building (`yay --makepkg pkglint-makepkg`,
+  paru `[bin] Makepkg`)
+- Sandboxed builds: containerized `makepkg` with the package artifact installed on the
+  host via `pacman -U`
+- Hermetic builds: two-phase `makepkg -o` (network) / `makepkg -e` (`--network=none`),
+  with these lint rules enforcing the conventions that make that split work
+
+## License
+
+MIT

pkglint-0.1.0/build-constraints.txt

@@ -0,0 +1,58 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile - -o build-constraints.txt --universal --generate-hashes
+go-bin==1.26.6 \
+    --hash=sha256:13a3a133530ffd2005b2ce805a93b8bf3f4712807af16f31aeea6aecfaa55721 \
+    --hash=sha256:1f4b3a6f8d7987c032d821ebb69e84ab9be7913b1cd8c45514d9aea21e3dfb7d \
+    --hash=sha256:2440ec27b056a19e9ce7c7e4c323f93a1ec0aa220b83838b9adf319487091582 \
+    --hash=sha256:2f8d76337bdf2e8e12b655c2f2c4827a202d4198c5cb87f0fde8b286bfa5b816 \
+    --hash=sha256:46658f18ce37d71122d25fa48bd7457cf46a3389345e86c5b6decabf1d5ec6ad \
+    --hash=sha256:565537475730612936bf42edddff5d627133c108d9a01561f8033ed09dc0c2ff \
+    --hash=sha256:7f30d0141d8052d9349b6e26c679ff51d14465ae3362ca9d1623ba1076e376a4 \
+    --hash=sha256:ab703942cbb119637e5306085b6f1f14eb51bd6a98b56dd2ff0a06b5afb742f8 \
+    --hash=sha256:c0dbc08e9a5a827966c8f2d6fb627668e78ab0f9732035564e24d046a185d92b \
+    --hash=sha256:efc17389b78138c27ce3c74275a146ce5e2b39c3969f57a170bbcfe303baf91b
+hatch-vcs==0.5.0 \
+    --hash=sha256:0395fa126940340215090c344a2bf4e2a77bcbe7daab16f41b37b98c95809ff9 \
+    --hash=sha256:b49677dbdc597460cc22d01b27ab3696f5e16a21ecf2700fb01bc28e1f2a04a7
+hatchling==1.32.0 \
+    --hash=sha256:0bdbde4a52b06c37e3eca395f85a762bf0ef06fe374fd8ae429dc6be10230f5f \
+    --hash=sha256:0e17c9c3b9aa7c625acc8d0f5b622f107d5049af9ecf5ada4de1aada5be7cdbc
+    # via hatch-vcs
+manygo==0.2.0 \
+    --hash=sha256:322567f555f0c9896e163f4cecdcd5aa6402996933a6a8ec1cea7f67dae9accd \
+    --hash=sha256:90a951179f0d294d7063a4fc5446b52646cff140c386f9c92ca391116a287098
+packaging==26.3 \
+    --hash=sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79 \
+    --hash=sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c
+    # via
+    #   hatchling
+    #   setuptools-scm
+    #   vcs-versioning
+pathspec==1.1.1 \
+    --hash=sha256:17db5ecd524104a120e173814c90367a96a98d07c45b2e10c2f3919fff91bf5a \
+    --hash=sha256:a00ce642f577bf7f473932318056212bc4f8bfdf53128c78bbd5af0b9b20b189
+    # via hatchling
+pluggy==1.6.0 \
+    --hash=sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3 \
+    --hash=sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746
+    # via hatchling
+setuptools==84.0.0 \
+    --hash=sha256:51a52592b3b99e102b609654876bd65f19f999935166d1352678931132b0c670 \
+    --hash=sha256:f4695c21257f0d9b537ec2692c941d02ee143b7cc1276941349a546573b2ef73
+    # via setuptools-scm
+setuptools-scm==10.2.1 \
+    --hash=sha256:4fa7dd82cf8c800df59c9a288c90299b1657ff1ecfc3f5cc00287c5dbf5e27a9 \
+    --hash=sha256:b7c82f4102d389ee57dc66ccdb4f9b4bca3c40ba83b43f1f63d68ccd72db2580
+    # via hatch-vcs
+tomlkit==0.15.1 \
+    --hash=sha256:177a05aece5a8ca5266fd3c448abb47b8d352f09d477d3ca8332db4d89b24304 \
+    --hash=sha256:e25bbf38843005246210a12982776f27f99cb9be67160e14434d0c0d21ee1e97
+    # via hatchling
+trove-classifiers==2026.6.1.19 \
+    --hash=sha256:ab4c4ec93cc4a4e7815fa759906e05e6bb3f2fbd92ea0f897288c6a43efd15b3 \
+    --hash=sha256:c5132b4b61a829d11cfbd2d72e97f20a45ed6edb95e45c5efdeb5e00836b2745
+    # via hatchling
+vcs-versioning==2.3.1 \
+    --hash=sha256:806635bd0ea653c96af98a70624be758d408a989f2cd0b390e63474d99f96b63 \
+    --hash=sha256:a11299394e101569a62ab061375260d08bc56cd33d685b7067d85312368f4457
+    # via setuptools-scm

pkglint-0.1.0/go.mod

@@ -0,0 +1,5 @@
+module github.com/jmelahman/pkglint
+
+go 1.26.5
+
+require mvdan.cc/sh/v3 v3.13.1

pkglint-0.1.0/go.sum

@@ -0,0 +1,12 @@
+github.com/go-quicktest/qt v1.101.0 h1:O1K29Txy5P2OK0dGo59b7b0LR6wKfIhttaAhHUyn7eI=
+github.com/go-quicktest/qt v1.101.0/go.mod h1:14Bz/f7NwaXPtdYEgzsx46kqSxVwTbzVZsDC26tQJow=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+mvdan.cc/sh/v3 v3.13.1 h1:DP3TfgZhDkT7lerUdnp6PTGKyxxzz6T+cOlY/xEvfWk=
+mvdan.cc/sh/v3 v3.13.1/go.mod h1:lXJ8SexMvEVcHCoDvAGLZgFJ9Wsm2sulmoNEXGhYZD0=

pkglint-0.1.0/hatch_build.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+import manygo
+
+# Central pin for the Go toolchain, so builds are as hermetic as PEP 517
+# allows: the same compiler version everywhere, pinned in exactly one place.
+# The static backend pins (hatchling, hatch-vcs, manygo) live in
+# pyproject.toml [build-system].requires.
+GO_BIN_PIN = "go-bin==1.26.6"
+
+
+class GoBinaryBuildHook(BuildHookInterface):
+    def dependencies(self) -> list[str]:
+        """Wheel builds always use the pinned Go toolchain.
+
+        Never probing PATH keeps builds hermetic: the binary is produced by
+        the same compiler version on every machine. The sdist carries only
+        sources, so it doesn't need one.
+        """
+        if self.target_name != "wheel":
+            return []
+        return [GO_BIN_PIN]
+
+    def initialize(self, version, build_data) -> None:  # noqa: ANN001, ARG002
+        if self.target_name != "wheel":
+            # The sdist carries sources only; the binary is built when the
+            # sdist is turned into a wheel on the installing machine.
+            return
+        build_data["pure_python"] = False
+        goos = os.getenv("GOOS")
+        goarch = os.getenv("GOARCH")
+        if manygo.is_goos(goos) and manygo.is_goarch(goarch):
+            build_data["tag"] = "py3-none-" + manygo.get_platform_tag(goos=goos, goarch=goarch)
+        else:
+            # Native build: let hatchling tag the wheel for this platform.
+            build_data["infer_tag"] = True
+        binary_name = self.config["binary_name"]
+
+        go = shutil.which("go")
+        if go is None:
+            raise RuntimeError("go is required to build the pkglint binary")
+        env = os.environ.copy()
+        # Pure Go: static binaries on every target, no C toolchain needed.
+        env["CGO_ENABLED"] = "0"
+
+        # Always rebuild: a leftover binary from another target would be
+        # packaged into a wheel tagged for the wrong platform.
+        print(f"Building Go binary '{binary_name}'...")
+        subprocess.check_call(  # noqa: S603
+            [
+                go, "build", "-trimpath",
+                "-ldflags", f"-s -w -X main.version={self.metadata.version}",
+                "-o", str(Path(self.root) / binary_name),
+                ".",
+            ],
+            cwd=self.root,
+            env=env,
+        )
+
+        build_data["shared_scripts"] = {binary_name: binary_name}

pkglint-0.1.0/internal/pkgbuild/pkgbuild.go

@@ -0,0 +1,310 @@
+// Package pkgbuild statically parses PKGBUILD and .install files.
+//
+// PKGBUILDs are untrusted input: they must never be sourced or executed
+// (even `makepkg --printsrcinfo` runs top-level code). Everything here is
+// pure static analysis on the bash AST via mvdan.cc/sh.
+package pkgbuild
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"mvdan.cc/sh/v3/syntax"
+)
+
+// Var is a top-level variable assignment in a PKGBUILD.
+type Var struct {
+	Name   string
+	Values []string // rendered values; one element for scalar assignments
+	Array  bool
+	Pos    syntax.Pos
+}
+
+// Unit is a single bash file under analysis: the PKGBUILD itself or an
+// install scriptlet.
+type Unit struct {
+	Path      string
+	Raw       []byte
+	File      *syntax.File
+	Scriptlet bool
+	Functions map[string]*syntax.FuncDecl
+	TopLevel  []*syntax.Stmt // top-level statements that are not function declarations
+}
+
+// Package is a fully loaded package directory.
+type Package struct {
+	Dir        string
+	PKGBUILD   Unit
+	Scriptlets []Unit
+	Vars       map[string]*Var
+	SrcInfo    *SrcInfo // nil when no .SRCINFO is present
+
+	// Suppressions maps line number -> rule IDs disabled on that line via
+	// "# pkglint: ignore=PB123[,PB456]" (applies to the same and next line).
+	Suppressions map[int]map[string]bool
+}
+
+// newParser returns a fresh parser per parse: syntax.Parser is not safe for
+// concurrent use, and Load is called from concurrent scanners.
+func newParser() *syntax.Parser {
+	return syntax.NewParser(syntax.KeepComments(true), syntax.Variant(syntax.LangBash))
+}
+
+// Load reads the PKGBUILD at path (a file or a directory containing one),
+// plus any install scriptlets referenced by install= or living next to it.
+func Load(path string) (*Package, error) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return nil, err
+	}
+	dir, file := filepath.Split(path)
+	if info.IsDir() {
+		dir = path
+		file = "PKGBUILD"
+	}
+	pkgPath := filepath.Join(dir, file)
+
+	raw, err := os.ReadFile(pkgPath)
+	if err != nil {
+		return nil, err
+	}
+	unit, err := parseUnit(pkgPath, raw, false)
+	if err != nil {
+		return nil, err
+	}
+
+	pkg := &Package{
+		Dir:          dir,
+		PKGBUILD:     unit,
+		Vars:         map[string]*Var{},
+		Suppressions: parseSuppressions(raw),
+	}
+	pkg.extractTopLevel()
+
+	if data, err := os.ReadFile(filepath.Join(dir, ".SRCINFO")); err == nil {
+		pkg.SrcInfo = ParseSrcInfo(data)
+	}
+
+	for _, name := range pkg.installFiles() {
+		p := filepath.Join(dir, name)
+		data, err := os.ReadFile(p)
+		if err != nil {
+			continue // missing scriptlet is reported by a rule
+		}
+		su, err := parseUnit(p, data, true)
+		if err != nil {
+			continue
+		}
+		pkg.Scriptlets = append(pkg.Scriptlets, su)
+		for line, ids := range parseSuppressions(data) {
+			pkg.Suppressions[line] = ids // best effort; line collisions across files are acceptable
+		}
+	}
+	return pkg, nil
+}
+
+func parseUnit(path string, raw []byte, scriptlet bool) (Unit, error) {
+	f, err := newParser().Parse(bytes.NewReader(raw), path)
+	if err != nil {
+		return Unit{}, fmt.Errorf("parse %s: %w", path, err)
+	}
+	u := Unit{
+		Path:      path,
+		Raw:       raw,
+		File:      f,
+		Scriptlet: scriptlet,
+		Functions: map[string]*syntax.FuncDecl{},
+	}
+	for _, stmt := range f.Stmts {
+		if fd, ok := stmt.Cmd.(*syntax.FuncDecl); ok {
+			u.Functions[fd.Name.Value] = fd
+			continue
+		}
+		u.TopLevel = append(u.TopLevel, stmt)
+	}
+	return u, nil
+}
+
+// extractTopLevel records top-level variable assignments from the PKGBUILD.
+func (p *Package) extractTopLevel() {
+	record := func(as *syntax.Assign) {
+		if as.Name == nil {
+			return
+		}
+		v := &Var{Name: as.Name.Value, Pos: as.Pos()}
+		if as.Array != nil {
+			v.Array = true
+			for _, el := range as.Array.Elems {
+				s, _ := RenderWord(el.Value, nil)
+				v.Values = append(v.Values, s)
+			}
+		} else if as.Value != nil {
+			s, _ := RenderWord(as.Value, nil)
+			v.Values = []string{s}
+		}
+		p.Vars[v.Name] = v
+	}
+	for _, stmt := range p.PKGBUILD.TopLevel {
+		switch cmd := stmt.Cmd.(type) {
+		case *syntax.CallExpr:
+			if len(cmd.Args) == 0 {
+				for _, as := range cmd.Assigns {
+					record(as)
+				}
+			}
+		case *syntax.DeclClause:
+			for _, as := range cmd.Args {
+				record(as)
+			}
+		}
+	}
+}
+
+// Scalar returns the rendered value of a scalar variable, expanded against
+// other known scalars.
+func (p *Package) Scalar(name string) (string, bool) {
+	v, ok := p.Vars[name]
+	if !ok || v.Array || len(v.Values) != 1 {
+		return "", false
+	}
+	return p.Expand(v.Values[0]), true
+}
+
+var varRef = regexp.MustCompile(`\$(\{[A-Za-z_][A-Za-z0-9_]*\}|[A-Za-z_][A-Za-z0-9_]*)`)
+
+// Expand substitutes $name / ${name} references using known top-level scalar
+// variables. Unknown references are left as-is.
+func (p *Package) Expand(s string) string {
+	for range 5 {
+		if !strings.Contains(s, "$") {
+			break
+		}
+		out := varRef.ReplaceAllStringFunc(s, func(m string) string {
+			name := strings.Trim(m[1:], "{}")
+			if v, ok := p.Vars[name]; ok && !v.Array && len(v.Values) == 1 {
+				return v.Values[0]
+			}
+			return m
+		})
+		if out == s {
+			break
+		}
+		s = out
+	}
+	return s
+}
+
+// installFiles returns the scriptlet filenames referenced by install= or
+// declared per split package, deduplicated.
+func (p *Package) installFiles() []string {
+	seen := map[string]bool{}
+	var out []string
+	add := func(name string) {
+		name = strings.TrimSpace(name)
+		if name == "" || seen[name] {
+			return
+		}
+		seen[name] = true
+		out = append(out, name)
+	}
+	if v, ok := p.Vars["install"]; ok {
+		for _, val := range v.Values {
+			add(p.Expand(val))
+		}
+	}
+	if p.SrcInfo != nil {
+		for _, val := range p.SrcInfo.All("install") {
+			add(val)
+		}
+	}
+	return out
+}
+
+// Units returns the PKGBUILD followed by any parsed scriptlets.
+func (p *Package) Units() []Unit {
+	return append([]Unit{p.PKGBUILD}, p.Scriptlets...)
+}
+
+var suppressRe = regexp.MustCompile(`#\s*pkglint:\s*ignore=([A-Z0-9, ]+)`)
+
+func parseSuppressions(raw []byte) map[int]map[string]bool {
+	out := map[int]map[string]bool{}
+	for i, line := range strings.Split(string(raw), "\n") {
+		m := suppressRe.FindStringSubmatch(line)
+		if m == nil {
+			continue
+		}
+		ids := map[string]bool{}
+		for _, id := range strings.Split(m[1], ",") {
+			if id = strings.TrimSpace(id); id != "" {
+				ids[id] = true
+			}
+		}
+		out[i+1] = ids
+	}
+	return out
+}
+
+// Suppressed reports whether ruleID is suppressed at the given line by a
+// directive on that line or the line above it.
+func (p *Package) Suppressed(ruleID string, line int) bool {
+	for _, l := range []int{line, line - 1} {
+		if ids, ok := p.Suppressions[l]; ok && ids[ruleID] {
+			return true
+		}
+	}
+	return false
+}
+
+// RenderWord returns an approximate textual form of a word. dynamic is true
+// when the word contains constructs whose value cannot be determined
+// statically (command substitution, process substitution, arithmetic,
+// indirection, or parameter operations). Plain references to unknown
+// variables render as "$name" and are not considered dynamic, so prefix
+// checks like `$pkgdir/...` still work. vars, when non-nil, resolves simple
+// parameter references.
+func RenderWord(w *syntax.Word, vars map[string]string) (s string, dynamic bool) {
+	if w == nil {
+		return "", false
+	}
+	var b strings.Builder
+	dyn := renderParts(&b, w.Parts, vars)
+	return b.String(), dyn
+}
+
+func renderParts(b *strings.Builder, parts []syntax.WordPart, vars map[string]string) bool {
+	dynamic := false
+	for _, part := range parts {
+		switch x := part.(type) {
+		case *syntax.Lit:
+			b.WriteString(x.Value)
+		case *syntax.SglQuoted:
+			b.WriteString(x.Value)
+		case *syntax.DblQuoted:
+			if renderParts(b, x.Parts, vars) {
+				dynamic = true
+			}
+		case *syntax.ParamExp:
+			if x.Excl || x.Length || x.Width || x.Index != nil || x.Slice != nil || x.Repl != nil || x.Exp != nil || x.Names != 0 {
+				b.WriteString("\x00")
+				dynamic = true
+				break
+			}
+			if vars != nil {
+				if v, ok := vars[x.Param.Value]; ok {
+					b.WriteString(v)
+					break
+				}
+			}
+			b.WriteString("$" + x.Param.Value)
+		default:
+			b.WriteString("\x00")
+			dynamic = true
+		}
+	}
+	return dynamic
+}