PSX: The Project Structure Checker

Source: Dev.to

Why PSX?

• Tired of spending the first hour of a new project creating folders, config files, and boilerplate?
• Clone a repo and discover half the essential files are missing?
• Repeating the same copy‑paste steps for every project (README, .gitignore, CI templates, etc.)?

PSX automates all of that.

What PSX Checks

And the best part? PSX doesn’t just report problems – it can fix them.

Quick Install

Linux / macOS

curl -sSL https://raw.githubusercontent.com/m-mdy-m/psx/main/scripts/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/m-mdy-m/psx/main/scripts/install.ps1 | iex

Full step‑by‑step guide: docs/INSTALLATION.md
Binaries: see the Releases page on GitHub.

Supported Project Types

PSX currently focuses on Go and Node.js projects.
You must tell PSX which type you’re working on by adding a tiny config file at the repository root:

# psx.yml
project:
  type: "go"      # or "nodejs"

If project.type is missing, PSX will prompt you to create it.

Basic Usage

# Move to your project directory
cd my-project

# Validate the layout
psx check

Example output

Detected: go  (based on project.type in psx.yml)

ERRORS (2)
✗ README_REQUIRED
    README.md file not found in project root

✗ LICENSE_REQUIRED
    No LICENSE file found

Summary: 2 errors, 0 warnings
Status: FAILED ✗

Fix the problems

# Interactive mode (asks before creating each file)
psx fix

# Non‑interactive – create everything automatically
psx fix --all

Configuration Details

Basic psx.yml

version: 1

project:
  type: "nodejs"

rules:
  readme: error      # Must have
  license: warning   # Should have
  changelog: info    # Nice to have

ignore:
  - node_modules/
  - dist/

• rules – set the severity (error, warning, info) for each check.
• ignore – paths that PSX should skip.

Custom Files & Folders

custom:
  files:
    - path: ".env.example"
      content: |
        NODE_ENV=development
        PORT=3000

  folders:
    - path: "src/api"
      structure:
        controllers: {}
        middlewares: {}
        routes: {}

See examples/psx.examples.yml for more advanced configurations.

Templates & Resources

PSX ships with language‑specific templates:

• README skeletons
• Multiple LICENSE types
• .gitignore snippets
• Dockerfile & docker‑compose.yml
• ADR / documentation templates

All templates live in the embedded resources directory and can be overridden or extended via your own config.

CI Integration

PSX can output machine‑friendly JSON, perfect for pipelines:

- name: Validate Structure
  run: |
    psx check --output json

Use --fail-on warning (or error) to enforce stricter rules in CI.

Internals (for developers)

The codebase was recently refactored for simplicity: a unified checker/fixer flow, clearer resource separation, and a minimal command surface (check & fix). Browse the rest of the internals at internal/.

Scope & Limitations

• Explicit project type – PSX never guesses; you set project.type.
• Focused templates – only minimal, maintainable CI/quality files are provided. Complex pipelines should be managed separately.
• No plugin system or multi‑project scanning (may be added later).

Contributing

PSX is open‑source (MIT license).

• Bugs: open an issue.
• Feature requests: start a discussion.
• Ideas & improvements: pull requests are welcome.

Extending PSX

1. Add new rules in rules.yml or directly in internal/rules.
2. Drop additional templates under internal/resources.
3. Rebuild the binary.

License

MIT © 2025 — m‑mdy‑m (author of PSX)

Built with Go 1.25 – a single static binary, no runtime dependencies, works everywhere.

One Principle

Don’t make me think about boring stuff.

When I start a project, I want to write code, not spend 30 minutes setting up folders and config files.
When I clone a repo, I want to know it has proper structure without manual inspection.

PSX handles the boring parts so you can focus on the interesting parts.

Install

curl -sSL https://raw.githubusercontent.com/m-mdy-m/psx/main/scripts/install.sh | bash

Check a Project

cd your-project
# make sure psx.yml contains `project.type: "go"` or `"nodejs"`
psx check

Fix Issues

psx fix

Customize

echo "version: 1" > psx.yml
# Add your rules...

Your Thoughts

I’d love to hear your thoughts:

• Does PSX’s focused, type‑first design make project setup more predictable and useful for you?
• Would you prefer broader language support, a plugin system, or richer CI templates?

Start a discussion on GitHub, or email suggestions and security reports to bitsgenix@gmail.com.

Let’s build something that actually saves time!