✨ Image Naming - Standardize image filenames to kebab-case across Rules V3 (TinaCMS)

[tiagov8]

Requested by: @tiagov8 via YakShaver.ai 🦬
cc: @tiagov8, @Marxoz, @PothieuG, @Freego1783 @Aibono1225 @hveraus

Hi Team!

  🟥  Watch the video (1 min 33 sec)

  Url from screen share: https://github.com/SSWConsulting/SSW.Rules.Content/blob/main/public/uploads/rules/book-developers-for-a-project/rule.mdx?plain=1

Pain

Create an automated task for Rules V3 (TinaCMS) to detect and rename image files that do not follow the SSW file naming convention. The task should standardize image filenames to kebab-case using lowercase letters and dashes instead of spaces or capital letters. It should also update all affected image references throughout the rules content to prevent broken links. Examples of issues identified include filenames with spaces, capital letters, non-descriptive date-based names, and inconsistent casing.

Acceptance Criteria

1. An automated process exists to scan image filenames used in Rules V3 (TinaCMS).
2. Image filenames containing spaces are renamed to use dashes.
3. Image filenames containing uppercase letters are converted to lowercase.
4. Non-descriptive image filenames are flagged or renamed to a descriptive kebab-case format where possible.
5. All updated image filenames have their references automatically updated across the project.
6. No broken image references exist after the renaming process is completed.
7. The updated filenames comply with the SSW naming convention for documents and files.
8. The automation can be rerun safely without creating duplicate or conflicting filenames.

Screenshot

Figure: Inconsistent image filenames with spaces, capitals, and non-descriptive names

[github-actions]

🤖 Copilot Research Findings

Summary

This is a feature request to build a one-time (but re-runnable) migration script that normalises image filenames in SSW.Rules.Content to kebab-case and updates all MDX references. No duplicates found.

---

Relevant Files

File	Notes
scripts/prepare-content.js	Pattern for scripts that operate on the sibling content repo via LOCAL_CONTENT_RELATIVE_PATH
scripts/generate-people-latest-rules.js	Pattern for resolving the content repo path and walking its files
package.json → scripts section	Where a new normalize:image-filenames npm script entry would be registered

Image files and MDX rules live in SSW.Rules.Content at public/uploads/rules/<rule-uri>/ — this script would need to be pointed at that repo (same LOCAL_CONTENT_RELATIVE_PATH env var pattern used by the existing scripts).

---

Proposed Approach

A Node.js script (scripts/normalize-image-filenames.js) following the existing scripts/ conventions:

// Pseudocode outline
// 1. Resolve content repo path (same as existing scripts)
// 2. Glob all image files under public/uploads/rules/**/*.{png,jpg,jpeg,gif,svg,webp}
// 3. For each image:
//    a. Compute kebab-case target name:
//       - trim, replace spaces with dashes, lowercase everything
//       - collapse multiple dashes
//    b. If name already matches → skip
//    c. If target name already exists (conflict) → skip and log warning
//    d. Rename the file
//    e. Record old → new mapping
// 4. For each .mdx file under public/uploads/rules/**/ and rules/**/
//    a. For each renamed image, replace all occurrences of the old filename with the new one
//    b. Write back only files that changed
// 5. Print summary: renamed N files, updated M MDX references, K conflicts to review manually

This cleanly handles ACs 1–3, 5–6, 7–8.

---

Open Questions / Uncertainties

1. AC4 — "Non-descriptive" filenames (e.g. date-stamped names like 2024-01-15-screenshot.png or image001.png): Automation cannot reliably determine a good descriptive name for an arbitrary image. The safest approach is to flag only (print a report) rather than auto-rename, since guessing names could produce equally non-descriptive kebab-case names. Does the team agree with flag-only for AC4?

2. Where should this script live? The SSW.Rules app repo (scripts/) is a reasonable home since it already hosts content-touching scripts. Alternatively it could live in SSW.Rules.Content itself.

3. Scope of reference updates: Should references inside category MDX files (outside public/uploads/rules/) also be scanned? Are images ever referenced from CSS or JSON files?

4. URL-encoded filenames: Some MDX files may reference images with %20 instead of spaces (URL-encoded). The replacement logic needs to handle both raw and encoded variants.

5. CI integration: Should this run as a one-time migration (run once, commit result, done) or as an ongoing lint check that fails PRs with non-conforming filenames? These are very different scopes.

6. SSW.Rules.Content changes: Since the file renames and MDX edits both happen in the Content repo, the output of this script needs to be committed there (not here). Does the team want this as a PR to SSW.Rules.Content, or as a local developer tool?

---

Confidence Level: ~65% (Low)

The core renaming logic is straightforward, but I'm holding back from submitting a PR because:

• The issue is already labelled Needs Refinement — suggesting the team wants to align on scope before code is written
• AC4 (non-descriptive filenames) is genuinely ambiguous and needs a human decision on whether to flag-only vs attempt auto-rename
• The script would primarily produce changes in SSW.Rules.Content (a repo I can't access here to test against real data)
• URL-encoded references and edge cases need real data to validate

Happy to implement once the open questions above are answered! 🙂

Generated by Issue Triage for issue #2680 · ● 289.7K · ◷