openpencil/scripts/steiger-rules.ts

import { readFileSync } from 'node:fs'
import path from 'node:path'

type TreeEntry = {
  type: 'file' | 'folder'
  path: string
  children?: TreeEntry[]
}

type Diagnostic = {
  message: string
  location: { path: string; line?: number; column?: number }
}

type RuleResult = { diagnostics: Diagnostic[] }
type Rule = { name: string; check: (root: TreeEntry) => RuleResult }

type FileRuleCheck = (sourceRel: string) => string | null

const FILE_PREFIX_GROUP_ALLOWLIST = new Set([
  'packages/core/src/lint/rules::no',
  'tests/engine::visual'
])

type ImportRef = {
  specifier: string
  line: number
  column: number
}

const TEXT_EXTENSIONS = new Set(['.ts', '.tsx', '.vue', '.js', '.jsx', '.mjs', '.mts'])
const ROOT_MARKDOWN_ALLOWLIST = new Set([
  'AGENTS.md',
  'CHANGELOG.md',
  'CONTRIBUTING.md',
  'README.md',
  'SECURITY.md'
])
const PACKAGE_ALIASES: Record<string, string> = {
  '#core/': 'packages/core/src/',
  '#vue/': 'packages/vue/src/',
  '#cli/': 'packages/cli/src/',
  '#mcp/': 'packages/mcp/src/'
}

const PACKAGE_ALIAS_OWNERS: Record<string, string> = {
  '#core/': 'packages/core/src/',
  '#vue/': 'packages/vue/src/',
  '#cli/': 'packages/cli/src/',
  '#mcp/': 'packages/mcp/src/'
}

function normalizePath(filePath: string) {
  return filePath.split(path.sep).join('/')
}

function relativePath(rootPath: string, filePath: string) {
  return normalizePath(path.relative(rootPath, filePath))
}

function collectFiles(entry: TreeEntry, files: string[] = []) {
  if (entry.type === 'file') {
    if (TEXT_EXTENSIONS.has(path.extname(entry.path))) files.push(entry.path)
    return files
  }
  for (const child of entry.children ?? []) collectFiles(child, files)
  return files
}

function collectFolders(entry: TreeEntry, folders: TreeEntry[] = []) {
  if (entry.type !== 'folder') return folders
  folders.push(entry)
  for (const child of entry.children ?? []) collectFolders(child, folders)
  return folders
}

function importsIn(content: string): ImportRef[] {
  const imports: ImportRef[] = []
  const patterns = [
    /^\s*(?:import|export)\s+(?:type\s+)?(?:[^'";]*?\s+from\s*)?['"]([^'"]+)['"]/gm,
    /^\s*import\(\s*['"]([^'"]+)['"]\s*\)/gm
  ]

  for (const pattern of patterns) {
    for (const match of content.matchAll(pattern)) {
      const before = content.slice(0, match.index)
      const lines = before.split('\n')
      imports.push({
        specifier: match[1],
        line: lines.length,
        column: lines.at(-1)?.length ?? 0
      })
    }
  }
  return imports
}

function resolveImport(sourceRel: string, specifier: string): string | null {
  if (specifier.startsWith('@/')) return `src/${specifier.slice(2)}`

  for (const [alias, target] of Object.entries(PACKAGE_ALIASES)) {
    if (specifier.startsWith(alias)) return `${target}${specifier.slice(alias.length)}`
  }

  if (specifier.startsWith('.')) {
    return normalizePath(path.join(path.dirname(sourceRel), specifier))
  }

  return null
}

function createFileRule(name: string, checkFile: FileRuleCheck): Rule {
  return {
    name,
    check(root) {
      const diagnostics: Diagnostic[] = []
      for (const file of collectFiles(root)) {
        const sourceRel = relativePath(root.path, file)
        const message = checkFile(sourceRel)
        if (!message) continue
        diagnostics.push({ message, location: { path: file } })
      }
      return { diagnostics }
    }
  }
}

function createImportRule(
  name: string,
  checkImport: (sourceRel: string, specifier: string, resolved: string | null) => string | null
): Rule {
  return {
    name,
    check(root) {
      const diagnostics: Diagnostic[] = []
      for (const file of collectFiles(root)) {
        const sourceRel = relativePath(root.path, file)
        const content = readFileSync(file, 'utf8')
        for (const imported of importsIn(content)) {
          const resolved = resolveImport(sourceRel, imported.specifier)
          const message = checkImport(sourceRel, imported.specifier, resolved)
          if (!message) continue
          diagnostics.push({
            message,
            location: { path: file, line: imported.line, column: imported.column }
          })
        }
      }
      return { diagnostics }
    }
  }
}

function filePrefix(filePath: string): string | null {
  const name = path.basename(filePath).replace(/\.(test|spec|bench)?\.?[cm]?[tj]sx?$|\.vue$/, '')
  const match = /^([a-z][a-z0-9]+)-[a-z0-9-]+$/.exec(name)
  return match?.[1] ?? null
}

const preferDomainFoldersOverFilenamePrefixes: Rule = {
  name: 'open-pencil/prefer-domain-folders-over-filename-prefixes',
  check(root) {
    const diagnostics: Diagnostic[] = []
    for (const folder of collectFolders(root)) {
      const folderRel = relativePath(root.path, folder.path)
      const groups = new Map<string, string[]>()
      for (const child of folder.children ?? []) {
        if (child.type !== 'file' || !TEXT_EXTENSIONS.has(path.extname(child.path))) continue
        const prefix = filePrefix(child.path)
        if (!prefix) continue
        const files = groups.get(prefix) ?? []
        files.push(child.path)
        groups.set(prefix, files)
      }
      for (const [prefix, files] of groups) {
        if (files.length < 3) continue
        if (FILE_PREFIX_GROUP_ALLOWLIST.has(`${folderRel}::${prefix}`)) continue
        diagnostics.push({
          message: `Use a ${prefix}/ domain folder instead of ${files.length} sibling files with the ${prefix}- filename prefix.`,
          location: { path: folder.path }
        })
      }
    }
    return { diagnostics }
  }
}

const strictTestFilePlacement = createFileRule('open-pencil/strict-test-file-placement', (sourceRel) => {
  if (!sourceRel.startsWith('tests/')) return null
  if (!TEXT_EXTENSIONS.has(path.extname(sourceRel))) return null
  const name = path.basename(sourceRel)
  if (name.includes('.tmp.') || name.includes('.profile.')) {
    return 'Temporary/profile test files must not be committed. Move exploratory specs to scratch/ or delete them.'
  }
  if (sourceRel.startsWith('tests/e2e/')) {
    return sourceRel.endsWith('.spec.ts') ? null : 'E2E tests must live under tests/e2e/** and use *.spec.ts.'
  }
  if (sourceRel.startsWith('tests/figma/')) {
    return sourceRel.endsWith('.spec.ts') ? null : 'Figma Playwright tests must live under tests/figma/** and use *.spec.ts.'
  }
  if (sourceRel.startsWith('tests/engine/')) {
    if (sourceRel.endsWith('.test.ts')) return null
    if (sourceRel.endsWith('/helpers.ts') || sourceRel.endsWith('.bench.ts')) return null
    if (/\/visual\/[^/]+\.ts$/.test(sourceRel)) return null
    return 'Engine/unit tests must live under tests/engine/** and use *.test.ts; helpers.ts, *.bench.ts, and domain visual support scripts are allowed.'
  }
  if (sourceRel.startsWith('tests/helpers/')) return null
  return 'Tests must live under tests/e2e/** (*.spec.ts), tests/engine/** (*.test.ts), or tests/helpers/**.'
})

const ENGINE_TEST_DOMAIN_REDIRECTS: Array<{
  from: string
  to: string
  source: string
}> = [
  {
    from: 'tests/engine/fig/',
    to: 'tests/engine/io/fig/',
    source: 'packages/core/src/io/formats/fig/'
  },
  {
    from: 'tests/engine/svg/',
    to: 'tests/engine/io/svg/',
    source: 'packages/core/src/io/formats/svg/'
  },
  {
    from: 'tests/engine/fonts/',
    to: 'tests/engine/text/fonts/',
    source: 'packages/core/src/text/fonts.ts'
  },
  {
    from: 'tests/engine/editor/clipboard/derived-text',
    to: 'tests/engine/text/derived-text/',
    source: 'packages/core/src/text/derived-text/'
  },
  {
    from: 'tests/engine/images/',
    to: 'tests/engine/figma/api/, tests/engine/tools/modify/, tests/engine/clipboard/openpencil/, or tests/engine/io/fig/export/',
    source: 'the image API, tool, clipboard, or IO module under test'
  },
  {
    from: 'tests/engine/figma-api/',
    to: 'tests/engine/figma/api/',
    source: 'packages/core/src/figma-api/'
  },
  {
    from: 'tests/engine/scene-graph/mutation',
    to: 'tests/engine/text/style-runs/, tests/engine/vector/blob/, or tests/engine/scene-graph/undo/',
    source: 'the text, vector, or undo module under test'
  },
  {
    from: 'tests/engine/editor/clipboard/bounds',
    to: 'tests/engine/clipboard/figma/',
    source: 'packages/core/src/clipboard.ts'
  },
  {
    from: 'tests/engine/editor/clipboard/html',
    to: 'tests/engine/clipboard/figma/',
    source: 'packages/core/src/clipboard.ts'
  },
  {
    from: 'tests/engine/editor/clipboard/fixture-roundtrip',
    to: 'tests/engine/clipboard/fixtures/',
    source: 'packages/core/src/clipboard.ts'
  },
  {
    from: 'tests/engine/editor/clipboard/text-outlines',
    to: 'tests/engine/text/opentype/',
    source: 'packages/core/src/text/opentype.ts'
  },
  {
    from: 'tests/engine/vector/basic',
    to: 'tests/engine/vector/blob/, tests/engine/vector/normalize.test.ts, tests/engine/vector/validate.test.ts, or tests/engine/vector/bounds.test.ts',
    source: 'the vector module under test'
  },
  {
    from: 'tests/engine/geometry/basic',
    to: 'tests/engine/geometry/angles.test.ts, tests/engine/geometry/rotation.test.ts, tests/engine/geometry/bounds.test.ts, or tests/engine/geometry/visual-bounds.test.ts',
    source: 'the geometry module under test'
  },
  {
    from: 'tests/engine/profiler/basic',
    to: 'tests/engine/profiler/frame-stats.test.ts, draw-call-counter.test.ts, gpu-timer.test.ts, phase-timer.test.ts, capture-stack.test.ts, or speedscope.test.ts',
    source: 'the profiler module under test'
  }
]

const noMisplacedEngineTestDomainPaths = createFileRule(
  'open-pencil/no-misplaced-engine-test-domain-paths',
  (sourceRel) => {
    const redirect = ENGINE_TEST_DOMAIN_REDIRECTS.find(({ from }) => sourceRel.startsWith(from))
    if (redirect) {
      return `Move tests from ${redirect.from} under ${redirect.to} to mirror ${redirect.source}.`
    }
    if (/^tests\/engine\/[^/]+\.test\.ts$/.test(sourceRel)) {
      return 'Move root-level engine tests under a domain folder that mirrors the source module under test.'
    }
    return null
  }
)

const noEngineOnlyAssertionsInE2E = createImportRule(
  'open-pencil/no-engine-only-assertions-in-e2e',
  (sourceRel, specifier, resolved) => {
    if (!sourceRel.startsWith('tests/e2e/')) return null
    if (specifier === 'bun:test' || resolved?.startsWith('tests/engine/')) {
      return 'E2E tests must drive the UI and visible behavior. Put engine/internal-state assertions in tests/engine/**.'
    }
    return null
  }
)

const noE2EImportsInEngineTests = createImportRule(
  'open-pencil/no-e2e-imports-in-engine-tests',
  (sourceRel, _specifier, resolved) => {
    if (!sourceRel.startsWith('tests/engine/')) return null
    if (resolved?.startsWith('tests/e2e/')) {
      return 'Engine/unit tests must not import E2E tests or fixtures.'
    }
    return null
  }
)

const noRootMarkdownClutter = createFileRule('open-pencil/no-root-markdown-clutter', (sourceRel) => {
  if (sourceRel.includes('/')) return null
  if (!sourceRel.endsWith('.md')) return null
  if (ROOT_MARKDOWN_ALLOWLIST.has(sourceRel)) return null
  return 'Do not add ad hoc root Markdown files. Put durable docs under packages/docs/** or update the root allowlist deliberately.'
})

const noPrototypeOrGeneratedImports = createImportRule(
  'open-pencil/no-prototype-or-generated-imports',
  (sourceRel, _specifier, resolved) => {
    if (!resolved) return null
    if (resolved.startsWith('scratch/')) {
      return 'Committed code must not import scratch prototypes.'
    }
    if (resolved.startsWith('desktop/generated/')) {
      return 'Do not import generated desktop artifacts from TypeScript/app code.'
    }
    if (
      resolved.startsWith('packages/core/src/kiwi/kiwi-schema/') &&
      !sourceRel.startsWith('packages/core/src/kiwi/kiwi-schema/')
    ) {
      return 'Do not import vendored Kiwi schema internals directly; use the supported Kiwi APIs.'
    }
    return null
  }
)

const noPropertyPanelImportsInCanvas = createImportRule(
  'open-pencil/no-property-panel-imports-in-canvas',
  (sourceRel, _specifier, resolved) => {
    const isCanvasSurface =
      sourceRel === 'src/components/EditorCanvas.vue' ||
      sourceRel.startsWith('src/app/editor/canvas/') ||
      sourceRel.startsWith('src/components/canvas/') ||
      sourceRel.startsWith('packages/vue/src/canvas/')

    if (isCanvasSurface && resolved?.startsWith('src/components/properties/')) {
      return 'Canvas/editor overlay code must not import property-panel internals. Extract app-neutral UI or keep concerns local.'
    }
    return null
  }
)

const noAppImportsInWorkspacePackages = createImportRule(
  'open-pencil/no-app-imports-in-workspace-packages',
  (sourceRel, specifier, resolved) => {
    const isWorkspacePackage = /^packages\/[^/]+\/src\//.test(sourceRel)
    if (isWorkspacePackage && (specifier.startsWith('@/') || resolved?.startsWith('src/'))) {
      return 'Workspace packages must not import app-layer src/ code.'
    }
    return null
  }
)

const noPackageInternalsInApp = createImportRule(
  'open-pencil/no-package-internals-in-app',
  (sourceRel, specifier, resolved) => {
    if (!sourceRel.startsWith('src/')) return null
    if (specifier in PACKAGE_ALIASES || Object.keys(PACKAGE_ALIASES).some((alias) => specifier.startsWith(alias))) {
      return 'App code must use package public exports such as @open-pencil/core or @open-pencil/vue, not package-local aliases.'
    }
    if (resolved?.startsWith('packages/')) {
      return 'App code must not import workspace package internals. Use package public exports instead.'
    }
    return null
  }
)

const noForeignPackageLocalAliases = createImportRule(
  'open-pencil/no-foreign-package-local-aliases',
  (sourceRel, specifier) => {
    if (sourceRel.startsWith('scripts/') || sourceRel.startsWith('tests/')) return null
    for (const [alias, owner] of Object.entries(PACKAGE_ALIAS_OWNERS)) {
      if (specifier.startsWith(alias) && !sourceRel.startsWith(owner)) {
        return `Package-local alias ${alias} can only be used inside ${owner}. Use a public package export across package boundaries.`
      }
    }
    return null
  }
)

const noAppImportsComponentsOrViews = createImportRule(
  'open-pencil/no-app-imports-components-or-views',
  (sourceRel, _specifier, resolved) => {
    if (!sourceRel.startsWith('src/app/')) return null
    const importsAppComponent =
      resolved?.startsWith('src/components/') && !resolved.startsWith('src/components/ui/')
    if (importsAppComponent || resolved?.startsWith('src/views/')) {
      return 'App service/domain code must not import app component or view layers. Pass data/actions through app-owned entrypoints instead.'
    }
    return null
  }
)

const noComponentsImportViews = createImportRule(
  'open-pencil/no-components-import-views',
  (sourceRel, _specifier, resolved) => {
    if (!sourceRel.startsWith('src/components/')) return null
    if (resolved?.startsWith('src/views/')) {
      return 'Components must not import views. Views assemble components, not the other way around.'
    }
    return null
  }
)

const noNonUiImportsInSharedUi = createImportRule(
  'open-pencil/no-non-ui-imports-in-shared-ui',
  (sourceRel, _specifier, resolved) => {
    if (!sourceRel.startsWith('src/components/ui/')) return null
    if (resolved?.startsWith('src/components/') && !resolved.startsWith('src/components/ui/')) {
      return 'Shared UI components must only import other shared UI modules from src/components/ui/**.'
    }
    return null
  }
)

const noViewsImportedOutsideEntry = createImportRule(
  'open-pencil/no-views-imported-outside-entry',
  (sourceRel, _specifier, resolved) => {
    if (!resolved?.startsWith('src/views/')) return null
    if (sourceRel === 'src/App.vue' || sourceRel === 'src/main.ts' || sourceRel === 'src/router.ts') return null
    return 'Views are top-level composition entrypoints and must not be imported by app services or reusable components.'
  }
)

const noAppImportsInSharedUi = createImportRule(
  'open-pencil/no-app-imports-in-shared-ui',
  (sourceRel, _specifier, resolved) => {
    if (!sourceRel.startsWith('src/components/ui/')) return null
    if (resolved?.startsWith('src/app/')) {
      return 'Shared UI components must not import app services or stores. Pass data/actions in or move app-specific wrappers outside src/components/ui.'
    }
    return null
  }
)

const noPropertyPanelInternalsOutsidePanel = createImportRule(
  'open-pencil/no-property-panel-internals-outside-panel',
  (sourceRel, _specifier, resolved) => {
    if (!resolved?.startsWith('src/components/properties/')) return null
    if (sourceRel.startsWith('src/components/properties/')) return null
    if (sourceRel === 'src/components/DesignPanel.vue') return null
    return 'Property-panel internals must stay inside the property panel. Extract app-neutral UI before reusing elsewhere.'
  }
)

const noUiImportsInCore = createImportRule(
  'open-pencil/no-ui-imports-in-core',
  (sourceRel, specifier) => {
    if (!sourceRel.startsWith('packages/core/src/')) return null
    if (
      specifier === 'vue' ||
      specifier.startsWith('@vueuse/') ||
      specifier === 'reka-ui' ||
      specifier.startsWith('#vue/') ||
      specifier.startsWith('@open-pencil/vue')
    ) {
      return 'Core must stay framework-agnostic and cannot import Vue/UI modules.'
    }
    return null
  }
)

export const openPencilArchitecturePlugin = {
  meta: { name: 'open-pencil-architecture', version: '0.0.0' },
  ruleDefinitions: [
    preferDomainFoldersOverFilenamePrefixes,
    strictTestFilePlacement,
    noMisplacedEngineTestDomainPaths,
    noEngineOnlyAssertionsInE2E,
    noE2EImportsInEngineTests,
    noRootMarkdownClutter,
    noPrototypeOrGeneratedImports,
    noPropertyPanelImportsInCanvas,
    noAppImportsInWorkspacePackages,
    noPackageInternalsInApp,
    noForeignPackageLocalAliases,
    noAppImportsComponentsOrViews,
    noComponentsImportViews,
    noViewsImportedOutsideEntry,
    noNonUiImportsInSharedUi,
    noAppImportsInSharedUi,
    noPropertyPanelInternalsOutsidePanel,
    noUiImportsInCore
  ]
}