@sitchco/project-scanner

@sitchco/project-scanner

A utility for scanning WordPress project structures to discover Sitchco modules, assets, and platform units.

Installation

npm install @sitchco/project-scanner
# or
yarn add @sitchco/project-scanner
# or
pnpm add @sitchco/project-scanner

Overview

The platform unit detection system is designed to:

• Automatically detect WordPress platform units (themes, plugins, MU plugins) based on standardized conventions
• Respect .sitchco-module markers for identifying modules within these units
• Provide consistent behavior regardless of the working directory
• Flag invalid or incomplete module structures

Platform Unit Types

The system recognizes three types of platform units:

• Themes: Located in wp-content/themes/, identified by the presence of a style.css file with a Theme Name header
• Plugins: Located in wp-content/plugins/, identified by a main PHP file with a Plugin Name header
• MU Plugins: Located in wp-content/mu-plugins/, can be either single PHP files or directories containing PHP files

Detection Criteria

Themes

A directory is identified as a theme if:

• It is located in wp-content/themes/
• It contains a style.css file with a valid Theme Name header
• It is not named index.php

Additional theme metadata extracted from style.css:

• Version
• Description
• Author
• Template (for child themes)

Plugins

A directory is identified as a plugin if:

• It is located in wp-content/plugins/
• It contains at least one PHP file with a Plugin Name header
• It is not named index.php

The main plugin file is determined by:

• First checking for a PHP file with the same name as the directory
• If not found or no Plugin Name header, scanning all PHP files for a Plugin Name header

Additional plugin metadata extracted from the main PHP file:

• Version
• Description
• Author

MU Plugins

MU plugins can be either:

• Single PHP files directly in wp-content/mu-plugins/
• Directories in wp-content/mu-plugins/ containing PHP files

For single PHP files:

• Must have a .php extension
• Not named index.php
• Plugin Name header is extracted if available, otherwise the filename is used

For directories:

• The main plugin file is determined using the same logic as regular plugins
• Plugin Name header is extracted if available, otherwise the directory name is used

Module Detection

Within each platform unit, the system looks for:

• .sitchco-module marker files that indicate a module
• Entry points (JS, MJS, SCSS files) in standard locations:
  • Module root
  • assets/scripts/ and assets/styles/ directories
  • Block roots within the blocks/ directory
  • Block asset directories

Usage

Command Line Interface

The module-builder CLI has been enhanced with a verbose mode that displays detailed information about detected platform units:

# Clean all build artifacts
npx module-builder clean -v

# Build all module/block assets for production with verbose output
npx module-builder build -v

# Watch module/block assets and rebuild on changes with verbose output
npx module-builder dev -v

Programmatic Usage

import ProjectScanner, { PLATFORM_UNIT_TYPES } from '@sitchco/project-scanner';

// Create a scanner instance
const scanner = new ProjectScanner({ verbose: true });

// Get all platform units
const allUnits = await scanner.getPlatformUnits();

// Get units by type
const themes = await scanner.getPlatformUnitsByType(PLATFORM_UNIT_TYPES.THEME);
const plugins = await scanner.getPlatformUnitsByType(PLATFORM_UNIT_TYPES.PLUGIN);
const muPlugins = await scanner.getPlatformUnitsByType(PLATFORM_UNIT_TYPES.MU_PLUGIN);

// Get a specific unit by name
const specificTheme = await scanner.getPlatformUnitByName('My Theme');

// Validate platform units
const validationResults = await scanner.validatePlatformUnits();

// Get module directories
const moduleDirs = await scanner.getModuleDirs();

// Get entry points
const entrypoints = await scanner.getEntrypoints();

// Find source files with specific extensions
const phpFiles = await scanner.findModuleSourceFiles(['.php']);

// Clean build artifacts
await scanner.cleanBuildArtifacts();

API

Constructor

const scanner = new ProjectScanner(options);

Options:

• projectRoot (string): The root directory of the project to scan. Defaults to process.cwd().
• ignorePatterns (string[]): Glob patterns to ignore. Defaults to ['**/node_modules/**', '**/.git/**', '**/vendor/**', '**/dist/**', '**/build/**'].
• verbose (boolean): Whether to log verbose information. Defaults to false.

Methods

• getModuleDirs(): Gets the list of module directories.
• getEntrypoints(): Gets the list of all entry point files (JS/MJS/SCSS).
• getWebRoot(): Gets the WordPress web root directory path.
• findModuleSourceFiles(extensions): Finds all source files within module directories matching the specified extensions.
• findAllSourceFiles(extensions): Finds all source files within the entire project matching the specified extensions.
• getBuildArtifacts(): Finds all build artifact directories (dist, .vite) within the project root.
• cleanBuildArtifacts(): Removes all found build artifact directories.
• clearCache(): Clears the internal cache.
• getPlatformUnits(): Gets the list of platform units.
• getPlatformUnitsByType(type): Gets platform units of a specific type.
• getPlatformUnitByName(name): Gets a platform unit by name.
• validatePlatformUnits(): Validates all platform units against their requirements.

Adding New Platform Units

To add a new platform unit to the build system:

• For themes:

  • Create a directory in wp-content/themes/
  • Add a style.css file with a valid Theme Name header
  • Optionally add a .sitchco-module file to mark it as a module

• For plugins:

  • Create a directory in wp-content/plugins/
  • Add a main PHP file with a Plugin Name header
  • Optionally add a .sitchco-module file to mark it as a module

• For MU plugins:

  • Add a PHP file directly to wp-content/mu-plugins/, or
  • Create a directory in wp-content/mu-plugins/ with a main PHP file
  • Optionally add a .sitchco-module file to mark it as a module (for directories)

Module Structure

A valid module should have:

• A .sitchco-module marker file
• At least one of the following:
  • JS/SCSS files in the module root
  • JS/SCSS files in assets/scripts/ or assets/styles/
  • Blocks in a blocks/ directory with their own assets

Validation

The system validates platform units against their requirements and provides clear error messages for invalid or incomplete structures. Validation checks include:

• Presence of required files
• Valid headers
• Proper structure

Error Messages

The system provides clear error messages for invalid or incomplete module structures, such as:

• Missing required files
• Missing Theme Name in style.css
• Missing Plugin Name header
• Missing main PHP file in a plugin or MU plugin directory

Dependencies

This package uses:

• glob: For file pattern matching
• chalk: For colorized console output

License

ISC