♻️ Rules.Content - Script a one-off reformat of all rule.mdx files to the TinaCMS standard #2683

Activity

1. joshbermanssw

   added

   Type: RefactorA code quality improvement e.g. Tech debtA code quality improvement e.g. Tech debt

   TinaCMSRelates to TinaCMS migrationRelates to TinaCMS migration

   Needs Refinement

   02-medium2 to 4 days2 to 4 days

   on Jul 26, 2026
2. github-actions commented on Jul 26, 2026

   

   github-actionsBot

   on Jul 26, 2026 – with GitHub Actions

   Contributor

   More actions

   🤖 Triage Research

   Summary

   This is a well-scoped feature request. The goal is clear: write a one-off script that runs parseMDX → stringifyMDX (from @tinacms/mdx) over every rule.mdx to normalise it to what TinaCMS would emit on save, so future edits produce minimal diffs. The issue is already well-specified, but a few technical questions need to be answered before the script can be implemented safely.

   ---

   Relevant files

   File	Why it matters
   tina/collection/rule.tsx	Defines the field order that frontmatter keys must follow, and the body field definition needed as input to stringifyMDX
   tina/collection/shared/historyFields.ts	Defines lastUpdated, lastUpdatedBy, lastUpdatedByEmail — these must be explicitly preserved / excluded from reformatting
   scripts/generate-people-latest-rules.js	Good style reference for a script that walks the Content repo and uses gray-matter to read frontmatter
   scripts/prepare-content.js	Shows the LOCAL_CONTENT_RELATIVE_PATH env-var pattern for locating the Content repo
   package.json	Confirms gray-matter ^4.0.3 (direct dep) and tinacms 3.10.0 / @tinacms/cli 2.5.3 (direct); @tinacms/mdx 2.1.9 is a transitive dep (confirmed in pnpm-lock.yaml)

   ---

   Potential approach

   // scripts/reformat-rules.mjs  (rough sketch)
   import fs from "fs";
   import path from "path";
   import matter from "gray-matter";
   import { parseMDX, stringifyMDX } from "`@tinacms/mdx`";       // ← needs API verification
   import { bodyField } from "../tina/collection/rule.tsx";       // body field definition
   
   const CONTENT_PATH = process.env.LOCAL_CONTENT_RELATIVE_PATH ?? "../../SSW.Rules.Content";
   const rulesDir = path.resolve(CONTENT_PATH, "public/uploads/rules");
   
   // Schema field order (from rule.tsx top-to-bottom):
   const FIELD_ORDER = ["type","title","uri","categories","sidebarVideo","authors",
     "related","redirects","guid","seoDescription","thumbnail",
     "created","createdBy","createdByEmail",
     "lastUpdated","lastUpdatedBy","lastUpdatedByEmail",
     "isArchived","archivedreason"];
   
   // Audit fields that MUST NOT be touched
   const PRESERVE_AS_IS = new Set(["lastUpdated","lastUpdatedBy","lastUpdatedByEmail"]);
   
   for (const ruleDir of fs.readdirSync(rulesDir)) {
     const filePath = path.join(rulesDir, ruleDir, "rule.mdx");
     if (!fs.existsSync(filePath)) continue;
   
     const raw = fs.readFileSync(filePath, "utf8");
     const { data: fm, content: body } = matter(raw);
   
     // 1. Re-stringify body via Tina's own serializer
     const ast = parseMDX(body, bodyField);           // ← API TBC
     const newBody = stringifyMDX(ast, bodyField);    // ← API TBC
   
     // 2. Reorder frontmatter keys per schema order
     // 3. Normalise dates, YAML quoting (as Tina does)
     // 4. Reconstruct file
     // 5. Write only if changed
   }

   ---

   Key open questions / blockers

   1. @tinacms/mdx API signatures — parseMDX and stringifyMDX take a field parameter matching a Tina rich-text field definition. The exact signature in v2.1.9 needs to be confirmed. Does it accept the full collection fields array, or just the body field? Does it handle frontmatter too, or only the MDX body? Run node -e "const x = require('@tinacms/mdx'); console.log(Object.keys(x))" in the project root to inspect.

   2. Frontmatter serialisation — the issue lists 5 frontmatter transformations (key reorder, indent, quoting, dates, line-wrapping). parseMDX/stringifyMDX handle the body, not the frontmatter. Frontmatter needs to be rebuilt manually (or via a different Tina internal). The key question is: which YAML serialiser does TinaCMS use, and can it be imported directly? Check node_modules/@tinacms/schema-tools`` or node_modules/tinacms/dist for a `stringifyDocument` or `buildASTDocument` export.

   3. lastUpdated date format drift — if the script normalises date values in frontmatter (step 4 in the issue spec: 2023-01-19 07:01:07+00:00 → 2023-01-19T07:01:07.000Z), does that apply to lastUpdated too? The issue says "leave audit fields untouched" (AC4), so probably not — but it means those rules may still drift slightly on their next Tina save. Needs a decision.

   4. body={<>...</>} trailing whitespace — the issue explicitly warns about blank lines inside JSX children being emitted with surrounding indentation as trailing whitespace (point 8). This must come out of stringifyMDX naturally. Verify this against a known-reformatted file before running at scale.

   5. Script entry point format — other scripts in scripts/ use CommonJS (require). This script needs import for @tinacms/mdx (ESM). Should use .mjs or "type": "module" or a --input-type=module flag. Check whether tina/collection/rule.tsx can be imported directly from a plain Node script (it has JSX + TypeScript), or whether the body field needs to be extracted/duplicated as plain JS.

   ---

   Suggested first steps

   • node -e "const {parseMDX,stringifyMDX}=require('@tinacms/mdx');console.log(parseMDX.toString().slice(0,200))" to inspect the actual function signatures available in this project's node_modules
   • Test the round-trip on a single known-complex rule (e.g. video-editing-terms/rule.mdx) — parse then stringify and diff against production
   • Decide how to handle the tina/collection/rule.tsx import (TSX file — may need a small JS wrapper that re-exports just the body field definition, or use tsx / ts-node to run the script)

   ---

   Confidence

   ~45% — LOW. The overall shape of the script is clear, but the exact @tinacms/mdx v2.1.9 API, the YAML frontmatter serialisation strategy, and the JSX trailing-whitespace behaviour all require hands-on verification before a correct implementation can be written. The issue is correctly labelled "Needs Refinement". Recommend completing the investigation tasks above (especially the parseMDX API check and a single-file round-trip test) before implementing the full script.

   Generated by Issue Triage for issue #2683 · ● 963.3K · ◷