Create script for guided sync from P.B template (#2333)

Author: imnasnainaec

.github/workflows/platform.bible-extension.yaml

@@ -26,18 +26,20 @@ jobs:
         os: [ubuntu-latest]
     steps:
       - name: Checkout git repo
-        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           path: lexbox
+          persist-credentials: false
 
       - name: Checkout paranext-core repo to use its sub-packages
-        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           path: paranext-core
           repository: paranext/paranext-core
+          persist-credentials: false
 
       - name: Setup Node.js
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           cache: "npm"
           cache-dependency-path: |

platform.bible-extension/.eslintrc.js

@@ -2,20 +2,26 @@
 
 module.exports = {
   extends: [
-    // https://github.com/electron-react-boilerplate/eslint-config-erb/blob/main/index.js
-    // airbnb rules are embedded in erb https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb
-    'erb',
+    // https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb
+    'airbnb',
+    'airbnb/hooks',
+    'plugin:promise/recommended',
+    'plugin:compat/recommended',
     // https://github.com/import-js/eslint-plugin-import?tab=readme-ov-file#typescript
     'plugin:import/recommended',
     'plugin:import/typescript',
     // Make sure this is last so it gets the chance to override other configs.
     // See https://github.com/prettier/eslint-config-prettier and https://github.com/prettier/eslint-plugin-prettier
     'plugin:prettier/recommended',
   ],
+  env: {
+    browser: true,
+    node: true,
+  },
 
   rules: {
     // Some rules in this following shared region are not applied since they are overridden in subsequent regions
-    // #region shared with https://github.com/paranext/paranext-core/blob/main/.eslintrc.js except certain overrides
+    // #region shared with https://github.com/paranext/paranext-core/blob/main/.eslintrc.js
 
     // #region ERB rules
 
@@ -28,6 +34,7 @@ module.exports = {
     'import/no-import-module-exports': 'off',
     'import/no-unresolved': 'error',
     'import/prefer-default-export': 'off',
+    'no-param-reassign': ['error', { props: false }],
     'react/jsx-filename-extension': 'off',
     'react/react-in-jsx-scope': 'off',
 
@@ -45,12 +52,32 @@ module.exports = {
     ],
     '@typescript-eslint/explicit-member-accessibility': ['error', { accessibility: 'no-public' }],
     'lines-between-class-members': 'off',
-    '@typescript-eslint/lines-between-class-members': [
+    '@stylistic/ts/lines-between-class-members': [
       'error',
       'always',
       { exceptAfterSingleLine: true, exceptAfterOverload: true },
     ],
     '@typescript-eslint/member-ordering': 'error',
+    '@typescript-eslint/naming-convention': [
+      'error',
+      {
+        selector: 'variableLike',
+        format: ['camelCase', 'PascalCase', 'UPPER_CASE'],
+        leadingUnderscore: 'allow',
+      },
+      {
+        selector: 'enumMember',
+        format: ['PascalCase'],
+      },
+      {
+        selector: 'function',
+        format: ['camelCase', 'PascalCase'],
+      },
+      {
+        selector: 'typeLike',
+        format: ['PascalCase'],
+      },
+    ],
     'no-empty-function': 'off',
     '@typescript-eslint/no-empty-function': [
       'error',
@@ -123,6 +150,17 @@ module.exports = {
     globalThis: 'readonly',
   },
   overrides: [
+    {
+      files: ['*.ts', '*.tsx'],
+      rules: {
+        // #region shared with https://github.com/paranext/paranext-core/blob/main/.eslintrc.js
+
+        // These are already handled by TypeScript
+        'no-dupe-class-members': 'off',
+
+        // #endregion
+      },
+    },
     {
       // Allow this file to have overrides to rules from paranext-core
       files: ['.eslintrc.*js'],
@@ -151,14 +189,14 @@ module.exports = {
       },
     },
   ],
+  parser: '@typescript-eslint/parser',
   parserOptions: {
     ecmaVersion: 2022,
     sourceType: 'module',
     project: './tsconfig.lint.json',
     tsconfigRootDir: __dirname,
-    createDefaultProgram: true,
   },
-  plugins: ['@typescript-eslint', 'no-type-assertion', 'no-null'],
+  plugins: ['@typescript-eslint', '@stylistic/ts', 'no-type-assertion', 'no-null'],
   settings: {
     'import/resolver': {
       typescript: {

platform.bible-extension/.stylelintrc.js

@@ -4,7 +4,7 @@ module.exports = {
   extends: [
     'stylelint-config-recommended',
     'stylelint-config-sass-guidelines',
-    'stylelint-config-tailwindcss/scss',
+    '@dreamsicle.io/stylelint-config-tailwindcss',
   ],
   overrides: [
     {
@@ -13,22 +13,38 @@ module.exports = {
     },
   ],
   rules: {
+    // Let Prettier handle the space between style property and value (they were fighting when a
+    // value was long enough to be on its own line but not long enough to span multiple lines)
+    '@stylistic/declaration-colon-space-after': null,
+    // Disable Stylelint's function parentheses control for Prettier compatibility
+    '@stylistic/function-parentheses-space-inside': 'never-single-line',
     // Disable Stylelint's indentation control
     '@stylistic/indentation': null,
     // Let Prettier handle selector list formatting
     '@stylistic/selector-list-comma-newline-after': null,
+    'at-rule-no-unknown': null,
     'color-named': null,
     'max-nesting-depth': 2,
     'no-descending-specificity': null,
-    'selector-max-compound-selectors': 4,
-    'selector-max-id': 1,
-    'at-rule-no-unknown': null,
     'scss/at-rule-no-unknown': [
       true,
       {
-        ignoreAtRules: ['tailwind', 'apply', 'layer', 'screen', 'variants'],
+        ignoreAtRules: [
+          'tailwind',
+          'apply',
+          'layer',
+          'screen',
+          'variants',
+          'config',
+          'theme',
+          'plugin',
+          'source',
+          'custom-variant',
+        ],
       },
     ],
+    'selector-max-compound-selectors': 4,
+    'selector-max-id': 1,
   },
 };
 

platform.bible-extension/.vscode/settings.json

@@ -6,9 +6,11 @@
   "editor.rulers": [100],
   "editor.wordWrapColumn": 100,
 
-  "eslint.validate": ["javascript", "javascriptreact", "html", "typescriptreact"],
+  "eslint.validate": ["html", "javascript", "javascriptreact", "typescript", "typescriptreact"],
 
   "files.associations": {
+    "*.css": "tailwindcss",
+    "*.usj": "json",
     ".eslintignore": "ignore",
     ".prettierignore": "ignore",
     ".stylelintignore": "ignore"

platform.bible-extension/README.md

@@ -1,3 +1,5 @@
+<!-- Attention template README maintainers: The content in the portion of this README following the Template Info section roughly parallels that of the paranext-multi-extension-template. When editing one, please consider whether similar changes should also be made in the other.-->
+
 # lexicon
 
 The Platform.Bible extension for managing the lexicon for your project's target/vernacular language.
@@ -186,6 +188,57 @@ useEffect(() => {
   - To use `lexiconService.addEntry`, also import types `IEntry` and `PartialEntry` from `'lexicon'`.
   - To use `lexiconService.getEntries`, also import types `IEntryQuery` and `PartialEntry` from `'lexicon'`.
 
+## Sync template updates into this extension
+
+This extension is based on [`paranext-extension-template`](https://github.com/paranext/paranext-extension-template). Tooling updates (linting, formatting, build config, etc.) can be pulled in interactively using the sync script.
+
+### Prerequisites
+
+Clone `paranext-extension-template` as a sibling of the `languageforge-lexbox` monorepo root:
+
+```bash
+git clone https://github.com/paranext/paranext-extension-template ../paranext-extension-template
+```
+
+### Running the sync
+
+```bash
+npm run template:sync
+```
+
+The script:
+
+1. Runs `git pull --ff-only` in the template repo to get the latest changes.
+2. Lists every tracked template file (respecting `.gitignore`) and shows a `git diff` for each file that differs from this extension.
+3. Prompts you to choose an action for each differing file.
+
+### Prompt options
+
+For each differing file the prompt shows (color-coded to match the diff):
+
+| Key | Color  | Action                                                             |
+| --- | ------ | ------------------------------------------------------------------ |
+| `e` | green  | Keep the **extension** version — no change                         |
+| `t` | red    | Apply the **template** version directly                            |
+| `d` | yellow | **Defer** — skip for now and revisit after the main pass           |
+| `b` | orange | Do **both** — copy the template version, then defer to review/edit |
+
+Files that have extension-specific modifications (`package.json`, `manifest.json`, `README.md`, config files, etc.) have `[t]` blocked, ensuring that if you apply the template version, you have to review them.
+
+Files in `contributions/` and `assets/` are surfaced for reference but block both `[t]` and `[b]` — adapt those manually.
+
+### Deferred files
+
+After the main pass, deferred files are listed and the script pauses so you can edit them. Press Enter to do another pass over only the deferred files. Repeat until all deferred files are resolved.
+
+### Final steps
+
+- Commit changes to your working branch.
+- Review a diff of that branch from `develop` to verify you haven't removed extension-specific updates.
+- Delete `package-lock.json` and `node_modules/`, then run `npm i --no-scripts` to regenerate `package-lock.json`.
+- Run `npm run build` and `npm run lint` and fix any failures. If failures arise from (e.g.) changed lint rules in the template, don't just revert the rule change; either update the code or add a targeted exemption.
+- Commit all, push, and create a pr.
+
 <!--
 ## To package for distribution