UN-4270 [FEAT] v1 scaffold, strict TypeScript and import boundary

.github/workflows/ci-frontend-lint.yaml

@@ -121,6 +121,18 @@ jobs:
         working-directory: frontend
         run: bun run typecheck
 
+      # src/v1 is excluded from the step above and checked under its own
+      # stricter tsconfig, after scripts/check-v1.mjs rejects non-TS files.
+      - name: Run v1 typecheck
+        working-directory: frontend
+        run: bun run typecheck:v1
+
+      # Biome on src/v1, then the folder import contract, PropTypes and `ant-`
+      # checks in scripts/check-v1.mjs, which `biome ci` cannot express.
+      - name: Run v1 lint
+        working-directory: frontend
+        run: bun run lint:v1
+
   # ci-test.yaml runs the same suite as the rig's `frontend` group, but its
   # tiers skip frontend-only PRs; this job is what gates those.
   vitest:

.gitignore

@@ -41,8 +41,12 @@ eggs/
 lib/
 lib64/
 # The Python `lib/` rule above also matches the frontend's shadcn/ui helper
-# directory (`@/lib/utils` per components.json). Keep that tracked.
+# directory (`@/lib/utils` per components.json), the v1 `lib/` folder and the
+# v1 guardrail fixtures. Keep those tracked, or their files are silently left
+# out of commits.
 !frontend/src/lib/
+!frontend/src/v1/**/lib/
+!frontend/test-fixtures/**/lib/
 parts/
 sdist/
 var/

.pre-commit-config.yaml

@@ -22,9 +22,9 @@ repos:
       - id: check-docstring-first
       - id: check-ast
       - id: check-json
-        # Both files are JSONC — their tooling (VS Code, tsc) allows comments,
+        # These files are JSONC — their tooling (VS Code, tsc) allows comments,
         # but this hook parses with strict `json.loads`, which does not.
-        exclude: "(\\.vscode/launch\\.json|frontend/tsconfig\\.json)$"
+        exclude: "(\\.vscode/launch\\.json|frontend/(src/v1/)?tsconfig\\.json)$"
       - id: check-executables-have-shebangs
       - id: check-shebang-scripts-are-executable
       - id: check-toml

frontend/biome.json

@@ -129,5 +129,73 @@
   "assist": {
     "enabled": true,
     "actions": { "source": { "organizeImports": "on" } }
-  }
+  },
+  "overrides": [
+    {
+      "includes": ["src/v1/**"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noRestrictedImports": {
+              "level": "error",
+              "options": {
+                "paths": {
+                  "prop-types": "v1 is typed with TypeScript; PropTypes are not used under src/v1.",
+                  "antd": "antd is not used under src/v1."
+                },
+                "patterns": [
+                  {
+                    "group": [
+                      "../**",
+                      "..",
+                      "./../**",
+                      "/**",
+                      "@/**",
+                      "src/**"
+                    ],
+                    "message": "v1 imports nothing outside src/v1, and never with '../'. Use './' within a folder and '@v1/...' across folders."
+                  },
+                  {
+                    "group": ["@ant-design/**", "antd/**"],
+                    "message": "antd is not used under src/v1."
+                  },
+                  {
+                    "group": ["prop-types/**"],
+                    "message": "v1 is typed with TypeScript; PropTypes are not used under src/v1."
+                  },
+                  {
+                    "group": ["**/*.css", "!@v1/styles/**"],
+                    "message": "No component .css under src/v1; style with tokens and Tailwind. Global v1 styles live in @v1/styles/."
+                  }
+                ]
+              }
+            }
+          },
+          "suspicious": {
+            "noExplicitAny": "error"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["src/**", "!src/v1/**"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noRestrictedImports": {
+              "level": "error",
+              "options": {
+                "patterns": [
+                  {
+                    "group": ["@v1/**", "**/v1", "**/v1/**", "!@v1"],
+                    "message": "v0 may import only the v1 public entry, as '@v1'."
+                  }
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
 }

frontend/jsconfig.json

@@ -2,9 +2,10 @@
   "compilerOptions": {
     "baseUrl": ".",
     "paths": {
-      "@/*": ["./src/*"]
+      "@/*": ["./src/*"],
+      "@v1": ["./src/v1/index.ts"]
     }
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "build"]
+  "exclude": ["node_modules", "build", "src/v1"]
 }

frontend/package.json

@@ -77,7 +77,10 @@
     "check:fix": "biome check --write src/",
     "lint:all": "biome check --write src/",
     "lint:changed": "(git diff --name-only --diff-filter=ACMR; git ls-files --others --exclude-standard) | grep -E '\\.[jt]sx?$' | sed 's|^frontend/||' | sort -u | xargs -r biome check --write",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "typecheck:v1": "node scripts/check-v1.mjs --files && tsc -p src/v1/tsconfig.json",
+    "lint:v1": "biome lint src/v1/ && node scripts/check-v1.mjs --code",
+    "test:v1": "vitest run --dir src/v1 --passWithNoTests && node --test test-fixtures/v1-boundary/boundary.fixtures.mjs"
   },
   "browserslist": {
     "production": [