create-backbone-template 0.1.0

package/template/client/packages/design-system-lint/test/design-system-architecture.test.ts

@@ -0,0 +1,243 @@
+import assert from "node:assert/strict"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import test from "node:test"
+import { checkDesignSystemArchitecture } from "../src/design-system-architecture.js"
+
+test("accepts the app design-system architecture", () => {
+  const result = checkDesignSystemArchitecture({
+    contractSrcDir: path.resolve("../design-system-contract/src"),
+    implementationSrcDir: path.resolve("../design-system-basic/src"),
+  })
+
+  assert.deepEqual(result.errors, [])
+})
+
+test("rejects missing matching contract and implementation component files", () => {
+  const fixture = createFixture({
+    contract: {
+      "button.ts": "export type ButtonProps = unknown\nexport type ButtonComponent = unknown\n",
+      "card.ts": "export type CardProps = unknown\nexport type CardComponent = unknown\n",
+      "index.ts": "export type * from './button'\nexport type * from './card'\n",
+    },
+    implementation: {
+      "button.stories.tsx": "export const Default = () => null\n",
+      "button.tsx": "export const Button = () => null\n",
+      "index.tsx": "export * from './button'\n",
+    },
+  })
+
+  try {
+    const result = checkDesignSystemArchitecture(fixture)
+
+    assert.deepEqual(result.errors, [
+      'Component "card" exists in contract but is missing from implementation.',
+    ])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+test("rejects implementation component files without colocated stories", () => {
+  const fixture = createFixture({
+    contract: {
+      "button.ts": "export type ButtonProps = unknown\nexport type ButtonComponent = unknown\n",
+      "index.ts": "export type * from './button'\n",
+    },
+    implementation: {
+      "button.tsx": "export const Button = () => null\n",
+      "index.tsx": "export * from './button'\n",
+    },
+  })
+
+  try {
+    const result = checkDesignSystemArchitecture(fixture)
+
+    assert.deepEqual(result.errors, [
+      'Implementation component "button" must have a colocated story file at "button.stories.tsx".',
+    ])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+test("rejects contract files without matching props and component exports", () => {
+  const fixture = createFixture({
+    contract: {
+      "button.ts": "export type ButtonComponent = unknown\nexport type ButtonConfig = unknown\n",
+      "index.ts": "export type * from './button'\n",
+    },
+    implementation: {
+      "button.stories.tsx": "export const Default = () => null\n",
+      "button.tsx": "export const Button = () => null\n",
+      "index.tsx": "export * from './button'\n",
+    },
+  })
+
+  try {
+    const result = checkDesignSystemArchitecture(fixture)
+
+    assert.deepEqual(result.errors, [
+      'Contract component file "button.ts" must export exactly "ButtonComponent" and "ButtonProps".',
+    ])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+test("rejects multiple named exports from an implementation component file", () => {
+  const fixture = createFixture({
+    contract: {
+      "button.ts": "export type ButtonProps = unknown\nexport type ButtonComponent = unknown\n",
+      "index.ts": "export type * from './button'\n",
+    },
+    implementation: {
+      "button.stories.tsx": "export const Default = () => null\n",
+      "button.tsx": "export const Button = () => null\nexport const ButtonIcon = () => null\n",
+      "index.tsx": "export * from './button'\n",
+    },
+  })
+
+  try {
+    const result = checkDesignSystemArchitecture(fixture)
+
+    assert.deepEqual(result.errors, [
+      'Implementation component file "button.tsx" must export exactly "Button".',
+    ])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+test("rejects implementation exports that do not match the component file name", () => {
+  const fixture = createFixture({
+    contract: {
+      "text-input.ts":
+        "export type TextInputProps = unknown\nexport type TextInputComponent = unknown\n",
+      "index.ts": "export type * from './text-input'\n",
+    },
+    implementation: {
+      "index.tsx": "export * from './text-input'\n",
+      "text-input.stories.tsx": "export const Default = () => null\n",
+      "text-input.tsx": "export const Input = () => null\n",
+    },
+  })
+
+  try {
+    const result = checkDesignSystemArchitecture(fixture)
+
+    assert.deepEqual(result.errors, [
+      'Implementation component file "text-input.tsx" must export exactly "TextInput".',
+    ])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+test("rejects mismatched subfolder structure", () => {
+  const fixture = createFixture({
+    contract: {
+      "forms/button.ts":
+        "export type ButtonProps = unknown\nexport type ButtonComponent = unknown\n",
+      "index.ts": "export type * from './forms/button'\n",
+    },
+    implementation: {
+      "button.stories.tsx": "export const Default = () => null\n",
+      "button.tsx": "export const Button = () => null\n",
+      "index.tsx": "export * from './button'\n",
+    },
+  })
+
+  try {
+    const result = checkDesignSystemArchitecture(fixture)
+
+    assert.deepEqual(result.errors, [
+      'Component "button" exists in implementation but is missing from contract.',
+      'Component "forms/button" exists in contract but is missing from implementation.',
+    ])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+test("rejects missing barrel exports", () => {
+  const fixture = createFixture({
+    contract: {
+      "button.ts": "export type ButtonProps = unknown\nexport type ButtonComponent = unknown\n",
+      "text-input.ts":
+        "export type TextInputProps = unknown\nexport type TextInputComponent = unknown\n",
+      "index.ts": "export type * from './button'\n",
+    },
+    implementation: {
+      "button.stories.tsx": "export const Default = () => null\n",
+      "button.tsx": "export const Button = () => null\n",
+      "index.tsx": "export * from './button'\n",
+      "text-input.stories.tsx": "export const Default = () => null\n",
+      "text-input.tsx": "export const TextInput = () => null\n",
+    },
+  })
+
+  try {
+    const result = checkDesignSystemArchitecture(fixture)
+
+    assert.deepEqual(result.errors, [
+      'Contract barrel "index.ts" must export "./text-input".',
+      'Implementation barrel "index.tsx" must export "./text-input".',
+    ])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+test("rejects extra barrel exports", () => {
+  const fixture = createFixture({
+    contract: {
+      "button.ts": "export type ButtonProps = unknown\nexport type ButtonComponent = unknown\n",
+      "index.ts": "export type * from './button'\nexport type * from './card'\n",
+    },
+    implementation: {
+      "button.stories.tsx": "export const Default = () => null\n",
+      "button.tsx": "export const Button = () => null\n",
+      "index.tsx": "export * from './button'\nexport * from './button.stories'\n",
+    },
+  })
+
+  try {
+    const result = checkDesignSystemArchitecture(fixture)
+
+    assert.deepEqual(result.errors, [
+      'Contract barrel "index.ts" must not export "./card".',
+      'Implementation barrel "index.tsx" must not export "./button.stories".',
+    ])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+function createFixture(files: {
+  contract: Record<string, string>
+  implementation: Record<string, string>
+}) {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), "backbone-design-system-architecture-"))
+  const contractSrcDir = path.join(rootDir, "contract")
+  const implementationSrcDir = path.join(rootDir, "implementation")
+
+  writeFiles(contractSrcDir, files.contract)
+  writeFiles(implementationSrcDir, files.implementation)
+
+  return { contractSrcDir, implementationSrcDir, rootDir }
+}
+
+function writeFiles(rootDir: string, files: Record<string, string>) {
+  for (const [filePath, content] of Object.entries(files)) {
+    const absolutePath = path.join(rootDir, filePath)
+
+    fs.mkdirSync(path.dirname(absolutePath), { recursive: true })
+    fs.writeFileSync(absolutePath, content)
+  }
+}
+
+function removeFixture(fixture: { rootDir: string }) {
+  fs.rmSync(fixture.rootDir, { force: true, recursive: true })
+}

package/template/client/packages/design-system-lint/test/oxlint-fixtures.test.ts

@@ -0,0 +1,159 @@
+import assert from "node:assert/strict"
+import { spawnSync } from "node:child_process"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import test from "node:test"
+
+type OxlintDiagnostic = {
+  code?: string
+  filename?: string
+  labels?: Array<{
+    message?: string
+    span?: {
+      column?: number
+      line?: number
+    }
+  }>
+  message?: string
+}
+
+type OxlintJsonOutput = {
+  diagnostics?: OxlintDiagnostic[]
+}
+
+const packageRoot = process.cwd()
+
+test("fixture files without boundary violations pass real Oxlint", () => {
+  const result = runOxlint("fixtures/valid")
+
+  assert.equal(result.status, 0)
+  assert.deepEqual(result.diagnostics, [])
+})
+
+test("fixture files with boundary violations report stable diagnostics", () => {
+  const result = runOxlint("fixtures/invalid")
+
+  assert.equal(result.status, 1)
+  assert.deepEqual(
+    result.diagnostics.map((diagnostic) => ({
+      code: diagnostic.code,
+      column: diagnostic.column,
+      file: path.basename(diagnostic.filename ?? ""),
+      line: diagnostic.line,
+      message: diagnostic.message,
+    })),
+    [
+      {
+        code: "backbone-design-system/no-external-ui-imports",
+        column: 24,
+        file: "external-ui-import.tsx",
+        line: 1,
+        message: 'Import "@mui/material" bypasses the design system boundary.',
+      },
+      {
+        code: "backbone-design-system/no-raw-dom-jsx",
+        column: 11,
+        file: "raw-dom-jsx.tsx",
+        line: 2,
+        message:
+          "Raw JSX element <button> is not allowed in app code; use @backbone/design-system components.",
+      },
+      {
+        code: "backbone-design-system/no-external-ui-imports",
+        column: 20,
+        file: "two-violations.tsx",
+        line: 1,
+        message: 'Import "styled-components" bypasses the design system boundary.',
+      },
+      {
+        code: "backbone-design-system/no-raw-dom-jsx",
+        column: 11,
+        file: "two-violations.tsx",
+        line: 6,
+        message:
+          "Raw JSX element <main> is not allowed in app code; use @backbone/design-system components.",
+      },
+    ],
+  )
+})
+
+function runOxlint(fixturePath: string) {
+  const { configDir, configPath } = writeOxlintConfig()
+
+  try {
+    const result = spawnSync(
+      process.platform === "win32" ? "pnpm.cmd" : "pnpm",
+      ["exec", "oxlint", "--config", configPath, "--format", "json", fixturePath],
+      {
+        cwd: packageRoot,
+        encoding: "utf8",
+      },
+    )
+
+    if (result.error !== undefined && result.status === null) {
+      throw result.error
+    }
+
+    const diagnostics = parseDiagnostics(result.stdout)
+
+    return {
+      diagnostics,
+      status: result.status,
+      stderr: result.stderr,
+      stdout: result.stdout,
+    }
+  } finally {
+    fs.rmSync(configDir, { force: true, recursive: true })
+  }
+}
+
+function writeOxlintConfig() {
+  const configDir = fs.mkdtempSync(path.join(os.tmpdir(), "backbone-design-system-oxlint-"))
+  const configPath = path.join(configDir, "oxlint.json")
+
+  fs.writeFileSync(
+    configPath,
+    JSON.stringify({
+      jsPlugins: [path.join(packageRoot, "dist/src/oxlint-plugin.js")],
+      rules: {
+        "backbone-design-system/no-external-ui-imports": "error",
+        "backbone-design-system/no-raw-dom-jsx": "error",
+      },
+    }),
+  )
+
+  return { configDir, configPath }
+}
+
+function parseDiagnostics(output: string) {
+  if (output.trim() === "") {
+    return []
+  }
+
+  const parsed = JSON.parse(output) as OxlintJsonOutput
+
+  return (parsed.diagnostics ?? [])
+    .filter((diagnostic) => diagnostic.code?.startsWith("backbone-design-system"))
+    .map((diagnostic) => ({
+      code: normalizeRuleCode(diagnostic.code),
+      column: diagnostic.labels?.[0]?.span?.column,
+      filename: diagnostic.filename,
+      line: diagnostic.labels?.[0]?.span?.line,
+      message: diagnostic.message ?? diagnostic.labels?.[0]?.message,
+    }))
+    .sort((left, right) => {
+      const leftFile = left.filename ?? ""
+      const rightFile = right.filename ?? ""
+
+      if (leftFile !== rightFile) {
+        return leftFile.localeCompare(rightFile)
+      }
+
+      return (left.code ?? "").localeCompare(right.code ?? "")
+    })
+}
+
+function normalizeRuleCode(code: string | undefined) {
+  return code?.replace(/^backbone-design-system\((.+)\)$/, "backbone-design-system/$1")
+}

package/template/client/packages/design-system-lint/test/page-architecture.test.ts

@@ -0,0 +1,175 @@
+import assert from "node:assert/strict"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import test from "node:test"
+import { checkPageArchitecture } from "../src/page-architecture.js"
+
+const validHelloPage = `
+import { Button } from "@backbone/design-system"
+import type { Page } from "../page"
+
+export type HelloPageStaticProps = {
+  label: string
+}
+
+export type HelloPageDynamicProps = {
+  onSubmitted(): void
+}
+
+export const helloPageDynamicPropKeys = ["onSubmitted"] as const
+
+export const HelloPage: Page<HelloPageStaticProps, HelloPageDynamicProps> = ({
+  label,
+  onSubmitted,
+}) => <Button onClick={onSubmitted}>{label}</Button>
+`
+
+test("accepts the app page architecture", () => {
+  const result = checkPageArchitecture({
+    pagesSrcDir: path.resolve("../../src/pages"),
+  })
+
+  assert.deepEqual(result.errors, [])
+})
+
+test("accepts pages that follow the named page contract", () => {
+  const fixture = createFixture({
+    "page.ts":
+      "export type Page<StaticProps, DynamicProps> = (props: StaticProps & DynamicProps) => unknown\n",
+    "hello/hello-page.tsx": validHelloPage,
+  })
+
+  try {
+    const result = checkPageArchitecture({ pagesSrcDir: fixture.pagesSrcDir })
+
+    assert.deepEqual(result.errors, [])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+test("rejects pages missing named exports", () => {
+  const fixture = createFixture({
+    "hello/hello-page.tsx": `
+      import type { Page } from "../page"
+      export type StaticProps = { label: string }
+      export type DynamicProps = { onSubmitted(): void }
+      export const HelloPage: Page<StaticProps, DynamicProps> = () => null
+    `,
+  })
+
+  try {
+    const result = checkPageArchitecture({ pagesSrcDir: fixture.pagesSrcDir })
+
+    assert.deepEqual(result.errors, [
+      'Page file "hello/hello-page.tsx" must export type "HelloPageStaticProps".',
+      'Page file "hello/hello-page.tsx" must export type "HelloPageDynamicProps".',
+      'Page file "hello/hello-page.tsx" must export const "helloPageDynamicPropKeys".',
+      'Page component "HelloPage" in "hello/hello-page.tsx" must be typed as "Page<HelloPageStaticProps, HelloPageDynamicProps>".',
+    ])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+test("rejects dynamic props that are not on-prefixed callbacks", () => {
+  const fixture = createFixture({
+    "hello/hello-page.tsx": `
+      import type { Page } from "../page"
+      export type HelloPageStaticProps = { label: string }
+      export type HelloPageDynamicProps = {
+        submitted(): void
+        isSubmitting: boolean
+      }
+      export const helloPageDynamicPropKeys = ["submitted", "isSubmitting"] as const
+      export const HelloPage: Page<HelloPageStaticProps, HelloPageDynamicProps> = () => null
+    `,
+  })
+
+  try {
+    const result = checkPageArchitecture({ pagesSrcDir: fixture.pagesSrcDir })
+
+    assert.deepEqual(result.errors, [
+      'Dynamic prop "submitted" in "hello/hello-page.tsx" must start with "on" followed by an uppercase letter.',
+      'Dynamic prop "isSubmitting" in "hello/hello-page.tsx" must be a function callback.',
+      'Dynamic prop "isSubmitting" in "hello/hello-page.tsx" must start with "on" followed by an uppercase letter.',
+    ])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+test("rejects dynamic prop key mismatches", () => {
+  const fixture = createFixture({
+    "hello/hello-page.tsx": `
+      import type { Page } from "../page"
+      export type HelloPageStaticProps = { label: string }
+      export type HelloPageDynamicProps = {
+        onSubmitted(): void
+        onCancelled(): void
+      }
+      export const helloPageDynamicPropKeys = ["onSubmitted", "onUnknown"] as const
+      export const HelloPage: Page<HelloPageStaticProps, HelloPageDynamicProps> = () => null
+    `,
+  })
+
+  try {
+    const result = checkPageArchitecture({ pagesSrcDir: fixture.pagesSrcDir })
+
+    assert.deepEqual(result.errors, [
+      'Dynamic prop keys in "hello/hello-page.tsx" must include "onCancelled".',
+      'Dynamic prop keys in "hello/hello-page.tsx" must not include unknown key "onUnknown".',
+    ])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+test("rejects page template imports outside the page boundary", () => {
+  const fixture = createFixture({
+    "hello/hello-page.tsx": `
+      import { Button } from "@backbone/design-system"
+      import type { Page } from "../page"
+      import { createClient } from "@connectrpc/connect"
+      import { helper } from "./helper"
+      export type HelloPageStaticProps = { label: string }
+      export type HelloPageDynamicProps = { onSubmitted(): void }
+      export const helloPageDynamicPropKeys = ["onSubmitted"] as const
+      export const HelloPage: Page<HelloPageStaticProps, HelloPageDynamicProps> = () => null
+    `,
+  })
+
+  try {
+    const result = checkPageArchitecture({ pagesSrcDir: fixture.pagesSrcDir })
+
+    assert.deepEqual(result.errors, [
+      'Page file "hello/hello-page.tsx" must not import "@connectrpc/connect"; page templates may only import @backbone/design-system and ../page.',
+      'Page file "hello/hello-page.tsx" must not import "./helper"; page templates may only import @backbone/design-system and ../page.',
+    ])
+  } finally {
+    removeFixture(fixture)
+  }
+})
+
+function createFixture(files: Record<string, string>) {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), "backbone-page-architecture-"))
+  const pagesSrcDir = path.join(rootDir, "pages")
+
+  writeFiles(pagesSrcDir, files)
+
+  return { pagesSrcDir, rootDir }
+}
+
+function writeFiles(rootDir: string, files: Record<string, string>) {
+  for (const [filePath, content] of Object.entries(files)) {
+    const absolutePath = path.join(rootDir, filePath)
+
+    fs.mkdirSync(path.dirname(absolutePath), { recursive: true })
+    fs.writeFileSync(absolutePath, content)
+  }
+}
+
+function removeFixture(fixture: { rootDir: string }) {
+  fs.rmSync(fixture.rootDir, { force: true, recursive: true })
+}

package/template/client/packages/design-system-lint/test/rules.test.ts

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import { noExternalUiImports, noRawDomJsx } from "../src/rules.js"
+
+type RuleReport = {
+  message: string
+  node: unknown
+}
+
+function runRule<VisitorName extends string, Node>(
+  rule: {
+    create(context: { report(report: RuleReport): void }): Record<VisitorName, (node: Node) => void>
+  },
+  visitorName: VisitorName,
+  node: Node,
+) {
+  const reports: RuleReport[] = []
+  const context = {
+    report(report: RuleReport) {
+      reports.push(report)
+    },
+  }
+
+  rule.create(context)[visitorName](node)
+
+  return reports
+}
+
+test("no-raw-dom-jsx flags raw DOM JSX in app code", () => {
+  const reports = runRule(noRawDomJsx, "JSXOpeningElement", {
+    name: { type: "JSXIdentifier", name: "button" },
+  })
+
+  assert.equal(reports.length, 1)
+  const report = reports[0]
+  assert.ok(report)
+  assert.match(report.message, /Raw JSX element <button>/)
+})
+
+test("no-raw-dom-jsx allows design system components", () => {
+  const reports = runRule(noRawDomJsx, "JSXOpeningElement", {
+    name: { type: "JSXIdentifier", name: "Button" },
+  })
+
+  assert.deepEqual(reports, [])
+})
+
+test("no-external-ui-imports flags direct imports from external UI libraries", () => {
+  const reports = runRule(noExternalUiImports, "ImportDeclaration", {
+    source: { value: "@mui/material" },
+  })
+
+  assert.equal(reports.length, 1)
+  const report = reports[0]
+  assert.ok(report)
+  assert.match(report.message, /bypasses the design system boundary/)
+})
+
+test("no-external-ui-imports allows imports from the design system", () => {
+  const reports = runRule(noExternalUiImports, "ImportDeclaration", {
+    source: { value: "@backbone/design-system" },
+  })
+
+  assert.deepEqual(reports, [])
+})

package/template/client/packages/design-system-lint/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noUncheckedSideEffectImports": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "allowUnreachableCode": false,
+    "allowUnusedLabels": false,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}