[Linting Rule] Package Structure

Generated from 'wiki-linter.ts' on 2026-10-25, 09:29:25 UTC (v2.16.6), do not edit directly.

Package Structure ^[overview]

This rule ports the following steps of R CMD check (see the conformance table for the legend):

#	Step	Coverage	Note
2	whether tarball can be unpacked (book)	🔷	only the path rules of tarballs
3	package directory (book)	🟩
8	for portable file names (book)	🟩
9	for sufficient/correct file permissions (book)	🟩	needs the package on disk
10	for executable files (book)	🟩	needs the package on disk, detects ELF, PE, and Mach-O binaries
11	for hidden files and directories (book)	🟩
12	for .dll and .exe files (book)	🟩
13	for future file timestamps (book)	🟩	needs the package on disk
14	top-level files (book)	🟩	checkbashisms and autoreconf are not run
15	for left-over files (book)	🟩
16	package subdirectories (book)	🟩
17	'build' directory (book)	🟩
18	installed package size (book)	🔷	estimated from the files that would be installed
19	sizes of PDF files under 'inst/doc' (book)	🔷	reports large PDFs, cannot compact them
20	line endings in shell scripts (book)	🟩
21	files in 'vignettes' (book)	🟩
22	for left-overs from vignette generation (book)	🟩
23	installed files from 'inst/doc' (book)	🔷
57	demos (book)	🔷	the demo index and file names, the demos are not run
87	package vignettes (book)	🔷	non-ASCII vignettes without declared encoding are not reported

This rule is a best-effort rule.

Finds problems in the package files: portable names, hidden files, top-level files, subdirectories, permissions, executables, timestamps, sizes, line endings of scripts, and vignette leftovers.
This linting rule is implemented in src/linter/rules/cmd-check/package-structure.ts.

Configuration

Linting rules can be configured by passing a configuration object to the linter query as shown in the example below. The package-structure rule accepts the following configuration options:

• builtPackage
  whether the package is a built tarball (so inst/doc is expected to hold the vignette outputs)
  R CMD check #21
• checkBashisms
  whether to flag /bin/bash and env bash in configure and cleanup (off in R CMD check by default)
  R CMD check #14
• checkFutureTimestamps
  whether to flag files and directories modified in the future (R CMD check does with --as-cran)
  R CMD check #13
• checkTopLevel
  whether to check for non-standard top-level files and directories (R CMD check does with --as-cran)
  R CMD check #14
• cranKnownHidden
  names of hidden files and directories the CRAN package checks know about
  R CMD check #11
• cranPack
  whether to say for each hidden file whether the CRAN package checks know about it
  R CMD check #11
• docDirsNotInstalled
  the directories of inst/doc that should not be installed
  R CMD check #23
• hiddenAllowed
  hidden files and directories (as paths relative to the package root) that are fine
  R CMD check #11
• leftoverExtensions
  the extensions (without dot) of files that are leftovers when found next to vignettes
  R CMD check #21, #23
• maxInstalledSizeMb
  the installed package size in Mb above which a note is given (default 5)
  R CMD check #18
• maxPathLength
  a path of more than this many bytes (with the package name as prefix) is noted (default 100)
  R CMD check #8
• maxPdfBytes
  a PDF in inst/doc of more bytes than this is flagged to be compacted (default 1 MiB)
  R CMD check #19
• reservedInstDirs
  the directories of inst that R uses itself
  R CMD check #16
• standardTopLevel
  the files and directories that may be at the top level of a package
  R CMD check #14

Examples

A project with the code R/code.R:

f <- function() 1

and the files

DESCRIPTION:

Package: pkg
Version: 1.0
Title: A Package
License: MIT

R/a:b.R:

g <- function() 2

The linting query can be used to run this rule on the above example:

[ { "type": "linter",   "rules": [ { "name": "package-structure",     "config": {} } ] } ]

Results (prettified and summarized):

Query: linter (1 ms)
   ╰ Package Structure (package-structure):
       ╰ certain:
           ╰ Found the following file with a non-portable file name: 'R/a:b.R'. This is not a valid file name on all R platforms; please rename the file. at /pkg/R/a:b.R:1.1

More examples are the test cases in test/functionality/linter/cmd-check/lint-package-structure.test.ts.