# spec-line-endings — LF-only Policy & Audit Playbook

The project standard is **LF (`\n`) only**. CRLF, or mixed CR/LF + LF in the same file, is forbidden because it:

- Breaks WordPress.org SVN submission.
- Poisons webpack bundles — webpack preserves source line endings, so a single CRLF-shipping dependency contaminates the whole emitted bundle.
- Makes git diffs unreadable and noisy.

## Where the rule is enforced

| Layer | Mechanism |
|---|---|
| Editor / IDE | [`.editorconfig`](../.editorconfig) declares `end_of_line = lf`. |
| Build output (`assets/`) | [`webpack.config.js`](../webpack.config.js) installs `normalizeLineEndingsPlugin` (search `NormalizeLineEndingsPlugin`) — every emitted `.js` asset is rewritten to LF before being written to disk. This is the only defense against CRLF-shipping npm dependencies (e.g. `@dnd-kit/utilities`). **Do not remove it.** |
| Source tree (`src/`, PHP, configs) | Manual audit + the playbook below. |

## Audit & normalize playbook

Run from the theme root (`wp-content/themes/onepress/`).

### 1. Audit the working tree

Skip generated/vendor dirs:

```bash
find . -type f \
  -not -path "./node_modules/*" \
  -not -path "./vendor/*" \
  -not -path "./assets/*" \
  -not -path "./release-staging/*" \
  -not -path "./languages/*" \
  -not -path "./.git/*" \
  -exec file {} \; | grep -iE "crlf|cr line"
```

Empty output ⇒ working tree is clean, **stop**.

> Why skip `assets/`: it is regenerated by webpack with the LF normalizer; fixing source then rebuilding is the supported path.
> Why skip `languages/`: contains binary `.mo` files and machine-generated `.pot` that should not be hand-touched here.

### 2. Normalize each flagged file in place

Use Perl (portable across macOS / Linux):

```bash
perl -i -pe 's/\r\n/\n/g' path/to/file
```

**Do not use `sed -i`** — its `-i` flag behaves differently on macOS vs Linux and silently corrupts files.

### 3. Rebuild if `src/` was touched

If any flagged file lives under `src/`, rebuild so `assets/` regenerates from clean source:

```bash
npm run build
```

### 4. Confirm `assets/` is also clean

```bash
find assets -type f \( -name "*.js" -o -name "*.css" \
    -o -name "*.map" -o -name "*.php" \) \
  -exec file {} \; | grep -iE "crlf|cr line"
```

Must return empty. If it doesn't, `normalizeLineEndingsPlugin` has been removed or disabled — restore it from [../webpack.config.js](../webpack.config.js).

### 5. Stage only affected files by name

Never `git add -A` — the project may have unrelated work-in-progress.

```bash
git add <files>
git commit -m "chore: normalize CRLF -> LF in <area>"
```

Commit conventions: see [spec-commits.md](spec-commits.md).

## Rules

- **Never edit files in `assets/` directly.** Fix the source under `src/` and rebuild.
- **Never modify files inside `node_modules/`.** Upstream-shipped CRLF is handled at bundle time by the webpack plugin; leave it alone.
- **Never disable `normalizeLineEndingsPlugin`** without a documented replacement.
- **Never run the audit with `sed -i`** — use `perl -i -pe`.
