Skip to content

LINTING.md

Latest commit

 

History

History
147 lines (105 loc) · 4.04 KB

LINTING.md

File metadata and controls

147 lines (105 loc) · 4.04 KB

Linting Rules

Complete reference for all xpkg lint checks.

Overview

The linter analyzes built .xp packages for common issues before distribution. Each rule has an ID, a severity level, and a description.

xpkg lint mypackage-1.0-1-x86_64.xp
xpkg lint mypackage-1.0-1-x86_64.xp --strict   # Treat warnings as errors

Severity Levels

Level Icon Behavior
Error ✗ Always causes lint failure (exit code 1)
Warning ⚠ Causes failure only with --strict
Info ℹ Informational — never causes failure

Permission Checks

Rule ID Severity Description
permissions-world-writable Error File is world-writable (o+w) — security risk
permissions-world-writable-dir Warning Directory is world-writable without sticky bit
permissions-suid Warning File has the SUID bit set
permissions-sgid Warning File has the SGID bit set (non-directory)

Why it matters: World-writable files allow any user to modify them, which is a security vulnerability. SUID/SGID binaries run with elevated privileges and should be reviewed carefully.

Path Checks

Rule ID Severity Description
paths-forbidden-directory Error Package installs files to a forbidden location
paths-non-standard-toplevel Warning Non-standard top-level directory in the package
paths-empty-directory Info Empty directory found

Forbidden directories:

usr/local, var/local, home, root, tmp, run, dev, proc, sys, mnt, media

Allowed top-level directories:

usr, etc, var, srv, boot, opt

Metadata Checks

Rule ID Severity Description
metadata-missing-field Error Required .PKGINFO field is missing
metadata-empty-pkgver Error pkgver field is empty
metadata-empty-description Warning Package description is empty
metadata-placeholder-description Warning Description contains TODO or FIXME
metadata-pkgver-no-release Warning Version string missing release component

Required fields: pkgname, pkgver, pkgdesc, arch, size

Dependency Checks

Rule ID Severity Description
dependency-needed-library Info ELF binary requires a shared library (DT_NEEDED)

This check lists shared library dependencies found in ELF binaries. It is informational only — use it to verify that all runtime dependencies are declared in your XBUILD depends array.

ELF Analysis

Rule ID Severity Description
elf-textrel Warning Binary contains text relocations (TEXTREL)
elf-rpath Warning Binary has a non-standard RPATH

TEXTREL: Text relocations prevent shared library code from being shared across processes and are a security concern. Fix by compiling with -fPIC.

RPATH: Allowed values are empty, $ORIGIN, and $ORIGIN/../lib. Non-standard RPATH values may cause the binary to load libraries from unexpected locations.

Output Formats

Human-readable (default)

✗ [permissions-world-writable] usr/share/data.txt — file is world-writable
⚠ [elf-textrel] usr/lib/libfoo.so — binary contains TEXTREL
ℹ [dependency-needed-library] usr/bin/foo — needs libz.so.1

Summary: 1 error, 1 warning, 1 info

JSON (--json planned)

{
  "errors": 1,
  "warnings": 1,
  "info": 1,
  "issues": [
    {
      "rule": "permissions-world-writable",
      "severity": "error",
      "path": "usr/share/data.txt",
      "message": "file is world-writable"
    }
  ]
}

Summary

Category Rules Errors Warnings Info
Permissions 4 1 3 0
Paths 3 1 1 1
Metadata 5 2 3 0
Dependencies 1 0 0 1
ELF 2 0 2 0
Total 15 4 9 2