feat(generator): gitignore the generated tailwind.sources.css fleet-wide

Merged
MH
1mo ago
+293-1

Closes #71 — raised by cubic on glyphs#11 and locallingo#6.

Summary

bin/build-css regenerates app/assets/stylesheets/tailwind.sources.css on every build via bundle show, so a committed copy churns with machine-specific absolute gem paths (/Users/<user>/.gem/ruby/<version>/...) — and no build path consumes it (.dockerignore excludes it; every build runs bin/build-css first). This ships Option 1 (gitignore it fleet-wide) through the generator, not per-site hand edits:

  • New generator step ignore_generated_css_sources — appends the ignore entry (with a comment) to the site's .gitignore, or creates one when absent. Additive and idempotent: a re-run skips, and a hand-added entry (with or without the leading slash) counts as present. Not --sync-guarded — --sync is exactly how existing sites pick up the convention.
  • New SyncReport drift item — a tailwind.sources.css still tracked by git (gitignore doesn't untrack) is flagged with the exact git rm --cached app/assets/stylesheets/tailwind.sources.css command. Warn-only: the generator never mutates git state. The check uses git -C <root> ls-files --error-unmatch (index-only, works for a docs site in a subdir of a larger repo) and reads any failure — no git, not a repo, untracked — as "no drift".
  • README — the one-time-cleanup drift table gains the new row.

docs-kit new needs nothing extra: it runs docs_kit:install, and rails new's .gitignore gets the appended entry. The dogfood site (docs/) already ignores the file and doesn't track it.

Test plan

  • Generator spec: entry appended to an existing .gitignore / created when absent; idempotent re-run and unslashed hand-added variant add no duplicate; --sync adds it too.
  • Drift spec: warns with the git rm --cached command when the file is tracked (real git init + git add in the tmp skeleton), asserts the index is left untouched; silent when the site isn't a repo.
  • bundle exec rake green (99 generator examples; 94.5% line coverage; RuboCop clean).

Deviations & judgment calls

  • No Migration entry, generator step only — the issue said "generator + --sync migration", but --sync re-runs every unguarded generator method, so an idempotent ignore_generated_css_sources step already covers both fresh installs and syncs; a registry Migration doing the same thing would be redundant (and the registry's contract says it ships empty until a release needs a version-gated transform — an always-safe additive step doesn't).
  • git rm --cached is warn-only (SyncReport), not automated — the issue floated the generator running it, but no existing step mutates git state and SyncReport's contract is "never touches a byte"; staging a deletion behind the user's back crosses that line. The drift checklist prints the exact command instead, and keeps printing it until the site acts.
  • Chose Option 1 (gitignore) over Option 2 (portable globs) — the issue leans that way: the committed copy is consumed by no build path (.dockerignore excludes it; every build runs bin/build-css first), so making it portable would still commit a file nothing reads.

Summary by cubic

Gitignores the generated app/assets/stylesheets/tailwind.sources.css fleet‑wide to stop machine/Ruby‑specific churn. Previously many sites committed it; now the generator adds the ignore and the sync report warns if a tracked copy remains, using git ls-files --cached --ignored --exclude-per-directory=.gitignore so only repo .gitignore rules influence the warning and honoring an explicit ! opt‑out.

  • Adds generator step ignore_generated_css_sources: appends a commented entry to .gitignore or creates one; idempotent; runs under --sync; recognizes bare‑filename and **/‑prefixed lines; CRLF‑tolerant; respects last‑match‑wins so only an effective trailing ! negation counts as an opt‑out.
  • Adds SyncReport drift item: when the file is tracked and effectively ignored by repo rules (scoped to committed .gitignore files via git ls-files --cached --ignored --exclude-per-directory=.gitignore), prints git rm --cached app/assets/stylesheets/tailwind.sources.css (warn‑only). Suppressed when an effective ! negation exists.
  • Updates gemspec homepage and metadata URLs to the zoolutions org.

Rollout

  • If your repo tracks app/assets/stylesheets/tailwind.sources.css, run: git rm --cached app/assets/stylesheets/tailwind.sources.css and commit.
  • Existing sites pick up the ignore by re‑running: bin/rails g docs_kit:install --sync.