@forinda/kickjs-lint 5.2.2 → 5.2.4

package/README.md

@@ -46,4 +46,4 @@ export const FOO = Symbol('Legacy') // kick-lint-disable di-token-symbol
 
 ## Why
 
-See [architecture.md §22](https://github.com/forinda/kick-js/blob/main/architecture.md#22-di-token-convention--symbol-to-string-migration) for the convention rationale. The convention landed in the v3 → v4 migration and has been stable since; refer to the [DI Tokens guide](https://forinda.github.io/kick-js/guide/dependency-injection.html#tokens) for the current shape.
+See [architecture.md §22](https://github.com/forinda/kick-js/blob/main/architecture.md#22-di-token-convention--symbol-to-string-migration) for the convention rationale. The convention landed in the v3 → v4 migration and has been stable since; refer to the [DI Tokens guide](https://kickjs.app/guide/dependency-injection.html#tokens) for the current shape.

package/dist/index.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-lint v5.2.2
+ * @forinda/kickjs-lint v5.2.4
  *
  * Copyright (c) Felix Orinda
  *

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["defaultRules"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * Programmatic entry point for `@forinda/kickjs-lint`.\n *\n * Walks a directory tree, applies every enabled rule from\n * {@link ./rules} to each file that matches the token-bearing filename\n * heuristic, and returns the aggregated violations.\n *\n * The CLI binary (`bin.mjs`) wraps this with a process-exit translation\n * layer; downstream tools (devtools, editor extensions) call this\n * directly.\n *\n * @module @forinda/kickjs-lint\n */\n\nimport { readdir, readFile } from 'node:fs/promises'\nimport { join, relative } from 'node:path'\nimport { rules as defaultRules, type Rule, type Violation } from './rules'\n\nexport type { LintContext, Rule, Violation } from './rules'\nexport { diTokenSymbol, tokenKickPrefix, tokenReservedPrefix, rules as defaultRules } from './rules'\n\n/**\n * Filenames that historically declare DI tokens. Lint runs only on\n * these to keep false positives out of unrelated files (e.g. a class\n * named `Symbol` in a math library).\n *\n * `database.ts`, `interfaces.ts`, `client.ts` were added after a\n * regression where `TENANT_DB = Symbol(...)` slipped past the rule by\n * living in `database.ts` rather than `tokens.ts` / `constants.ts`.\n */\nexport const TOKEN_FILE_NAMES = new Set([\n  'types.ts',\n  'tokens.ts',\n  'constants.ts',\n  'service.ts',\n  'adapter.ts',\n  'database.ts',\n  'interfaces.ts',\n  'client.ts',\n])\n\n/** Directories the walker skips wholesale. */\nconst SKIP_DIRS = new Set([\n  'node_modules',\n  'dist',\n  '__tests__',\n  '.kickjs',\n  // Built static assets (e.g. devtools SPA bundle) live under `public/`\n  // and ship as-is to npm — no token literals to lint there.\n  'public',\n  // VitePress / Vite build outputs that adopters sometimes commit.\n  '.vitepress',\n  '.turbo',\n  '.wireit',\n  'coverage',\n])\n\nexport interface LintOptions {\n  /** Root directory to walk. Required. */\n  cwd: string\n  /**\n   * Whether the project being linted is a first-party `@forinda/kickjs-*`\n   * package (enables `token-kick-prefix`, disables `token-reserved-prefix`).\n   * Defaults to `false` so adopter projects use the friendlier ruleset.\n   */\n  firstParty?: boolean\n  /**\n   * Only lint files inside these subdirectories (relative to `cwd`).\n   * Defaults to `['packages']` for first-party use; pass `['src']` or\n   * `['.']` for adopter projects.\n   */\n  scope?: readonly string[]\n  /** Override the rule set. Defaults to every rule shipped by the package. */\n  rules?: readonly Rule[]\n  /** Filenames to lint (defaults to {@link TOKEN_FILE_NAMES}). */\n  filenames?: ReadonlySet<string>\n}\n\nexport interface LintResult {\n  violations: Violation[]\n  filesScanned: number\n}\n\n/**\n * Walk `cwd` (constrained to `scope` directories), apply every rule to\n * each token-bearing file, and return the aggregated violations + the\n * number of files actually checked.\n */\nexport async function runLint(opts: LintOptions): Promise<LintResult> {\n  const cwd = opts.cwd\n  const firstParty = opts.firstParty ?? false\n  const scope = opts.scope ?? ['packages']\n  const ruleset = opts.rules ?? defaultRules\n  const filenames = opts.filenames ?? TOKEN_FILE_NAMES\n\n  const violations: Violation[] = []\n  let filesScanned = 0\n\n  for (const root of scope) {\n    const start = join(cwd, root)\n    await walk(start, async (file) => {\n      const base = file.slice(file.lastIndexOf('/') + 1)\n      if (!filenames.has(base)) return\n      const source = await readFile(file, 'utf-8')\n      const rel = relative(cwd, file)\n      filesScanned++\n      for (const rule of ruleset) {\n        violations.push(...rule.check({ source, file: rel, firstParty }))\n      }\n    })\n  }\n\n  return { violations, filesScanned }\n}\n\nasync function walk(dir: string, visit: (file: string) => Promise<void>): Promise<void> {\n  let entries\n  try {\n    entries = await readdir(dir, { withFileTypes: true })\n  } catch {\n    return\n  }\n  for (const entry of entries) {\n    const full = join(dir, entry.name)\n    if (entry.isDirectory()) {\n      if (SKIP_DIRS.has(entry.name)) continue\n      await walk(full, visit)\n    } else if (entry.isFile()) {\n      await visit(full)\n    }\n  }\n}\n\n/**\n * Format a violation list for terminal output. One block per violation,\n * trailing summary line. Returns `''` when there are no violations so\n * callers can branch on truthiness.\n */\nexport function formatViolations(violations: readonly Violation[]): string {\n  if (violations.length === 0) return ''\n  const lines: string[] = []\n  for (const v of violations) {\n    const tag = v.severity === 'error' ? 'error' : 'warn'\n    lines.push(`  [${tag}] ${v.file}:${v.line}  ${v.ruleId}`)\n    lines.push(`    ${v.message}`)\n    if (v.suggestion) lines.push(`    -> ${v.suggestion}`)\n    lines.push('')\n  }\n  const errors = violations.filter((v) => v.severity === 'error').length\n  const warnings = violations.length - errors\n  lines.push(`${violations.length} violation(s): ${errors} error, ${warnings} warn`)\n  return lines.join('\\n')\n}\n"],"mappings":";;;;;;;;;;qKA8BA,MAAa,iBAAmB,IAAI,IAAI,CACtC,WACA,YACA,eACA,aACA,aACA,cACA,gBACA,WACF,CAAC,EAGK,UAAY,IAAI,IAAI,CACxB,eACA,OACA,YACA,UAGA,SAEA,aACA,SACA,UACA,UACF,CAAC,EAiCD,eAAsB,QAAQ,KAAwC,CACpE,IAAM,IAAM,KAAK,IACX,WAAa,KAAK,YAAc,GAChC,MAAQ,KAAK,OAAS,CAAC,UAAU,EACjC,QAAU,KAAK,OAASA,MACxB,UAAY,KAAK,WAAa,iBAE9B,WAA0B,CAAC,EAC7B,aAAe,EAEnB,IAAK,IAAM,QAAQ,MAEjB,MAAM,KADQ,KAAK,IAAK,IACT,EAAG,KAAO,OAAS,CAChC,IAAM,KAAO,KAAK,MAAM,KAAK,YAAY,GAAG,EAAI,CAAC,EACjD,GAAI,CAAC,UAAU,IAAI,IAAI,EAAG,OAC1B,IAAM,OAAS,MAAM,SAAS,KAAM,OAAO,EACrC,IAAM,SAAS,IAAK,IAAI,EAC9B,eACA,IAAK,IAAM,QAAQ,QACjB,WAAW,KAAK,GAAG,KAAK,MAAM,CAAE,OAAQ,KAAM,IAAK,UAAW,CAAC,CAAC,CAEpE,CAAC,EAGH,MAAO,CAAE,WAAY,YAAa,CACpC,CAEA,eAAe,KAAK,IAAa,MAAuD,CACtF,IAAI,QACJ,GAAI,CACF,QAAU,MAAM,QAAQ,IAAK,CAAE,cAAe,EAAK,CAAC,CACtD,MAAQ,CACN,MACF,CACA,IAAK,IAAM,SAAS,QAAS,CAC3B,IAAM,KAAO,KAAK,IAAK,MAAM,IAAI,EACjC,GAAI,MAAM,YAAY,EAAG,CACvB,GAAI,UAAU,IAAI,MAAM,IAAI,EAAG,SAC/B,MAAM,KAAK,KAAM,KAAK,CACxB,MAAW,MAAM,OAAO,GACtB,MAAM,MAAM,IAAI,CAEpB,CACF,CAOA,SAAgB,iBAAiB,WAA0C,CACzE,GAAI,WAAW,SAAW,EAAG,MAAO,GACpC,IAAM,MAAkB,CAAC,EACzB,IAAK,IAAM,KAAK,WAAY,CAC1B,IAAM,IAAM,EAAE,WAAa,QAAU,QAAU,OAC/C,MAAM,KAAK,MAAM,IAAI,IAAI,EAAE,KAAK,GAAG,EAAE,KAAK,IAAI,EAAE,QAAQ,EACxD,MAAM,KAAK,OAAO,EAAE,SAAS,EACzB,EAAE,YAAY,MAAM,KAAK,UAAU,EAAE,YAAY,EACrD,MAAM,KAAK,EAAE,CACf,CACA,IAAM,OAAS,WAAW,OAAQ,GAAM,EAAE,WAAa,OAAO,EAAE,OAC1D,SAAW,WAAW,OAAS,OAErC,OADA,MAAM,KAAK,GAAG,WAAW,OAAO,iBAAiB,OAAO,UAAU,SAAS,MAAM,EAC1E,MAAM,KAAK;CAAI,CACxB"}
+{"version":3,"file":"index.mjs","names":["defaultRules"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * Programmatic entry point for `@forinda/kickjs-lint`.\n *\n * Walks a directory tree, applies every enabled rule from\n * {@link ./rules} to each file that matches the token-bearing filename\n * heuristic, and returns the aggregated violations.\n *\n * The CLI binary (`bin.mjs`) wraps this with a process-exit translation\n * layer; downstream tools (devtools, editor extensions) call this\n * directly.\n *\n * @module @forinda/kickjs-lint\n */\n\nimport { readdir, readFile } from 'node:fs/promises'\nimport { join, relative } from 'node:path'\nimport { rules as defaultRules, type Rule, type Violation } from './rules'\n\nexport type { LintContext, Rule, Violation } from './rules'\nexport { diTokenSymbol, tokenKickPrefix, tokenReservedPrefix, rules as defaultRules } from './rules'\n\n/**\n * Filenames that historically declare DI tokens. Lint runs only on\n * these to keep false positives out of unrelated files (e.g. a class\n * named `Symbol` in a math library).\n *\n * `database.ts`, `interfaces.ts`, `client.ts` were added after a\n * regression where `TENANT_DB = Symbol(...)` slipped past the rule by\n * living in `database.ts` rather than `tokens.ts` / `constants.ts`.\n */\nexport const TOKEN_FILE_NAMES = new Set([\n  'types.ts',\n  'tokens.ts',\n  'constants.ts',\n  'service.ts',\n  'adapter.ts',\n  'database.ts',\n  'interfaces.ts',\n  'client.ts',\n])\n\n/** Directories the walker skips wholesale. */\nconst SKIP_DIRS = new Set([\n  'node_modules',\n  'dist',\n  '__tests__',\n  '.kickjs',\n  // Built static assets (e.g. devtools SPA bundle) live under `public/`\n  // and ship as-is to npm — no token literals to lint there.\n  'public',\n  // VitePress / Vite build outputs that adopters sometimes commit.\n  '.vitepress',\n  '.turbo',\n  '.wireit',\n  'coverage',\n])\n\nexport interface LintOptions {\n  /** Root directory to walk. Required. */\n  cwd: string\n  /**\n   * Whether the project being linted is a first-party `@forinda/kickjs-*`\n   * package (enables `token-kick-prefix`, disables `token-reserved-prefix`).\n   * Defaults to `false` so adopter projects use the friendlier ruleset.\n   */\n  firstParty?: boolean\n  /**\n   * Only lint files inside these subdirectories (relative to `cwd`).\n   * Defaults to `['packages']` for first-party use; pass `['src']` or\n   * `['.']` for adopter projects.\n   */\n  scope?: readonly string[]\n  /** Override the rule set. Defaults to every rule shipped by the package. */\n  rules?: readonly Rule[]\n  /** Filenames to lint (defaults to {@link TOKEN_FILE_NAMES}). */\n  filenames?: ReadonlySet<string>\n}\n\nexport interface LintResult {\n  violations: Violation[]\n  filesScanned: number\n}\n\n/**\n * Walk `cwd` (constrained to `scope` directories), apply every rule to\n * each token-bearing file, and return the aggregated violations + the\n * number of files actually checked.\n */\nexport async function runLint(opts: LintOptions): Promise<LintResult> {\n  const cwd = opts.cwd\n  const firstParty = opts.firstParty ?? false\n  const scope = opts.scope ?? ['packages']\n  const ruleset = opts.rules ?? defaultRules\n  const filenames = opts.filenames ?? TOKEN_FILE_NAMES\n\n  const violations: Violation[] = []\n  let filesScanned = 0\n\n  for (const root of scope) {\n    const start = join(cwd, root)\n    await walk(start, async (file) => {\n      const base = file.slice(file.lastIndexOf('/') + 1)\n      if (!filenames.has(base)) return\n      const source = await readFile(file, 'utf-8')\n      const rel = relative(cwd, file)\n      filesScanned++\n      for (const rule of ruleset) {\n        violations.push(...rule.check({ source, file: rel, firstParty }))\n      }\n    })\n  }\n\n  return { violations, filesScanned }\n}\n\nasync function walk(dir: string, visit: (file: string) => Promise<void>): Promise<void> {\n  let entries\n  try {\n    entries = await readdir(dir, { withFileTypes: true })\n  } catch {\n    return\n  }\n  for (const entry of entries) {\n    const full = join(dir, entry.name)\n    if (entry.isDirectory()) {\n      if (SKIP_DIRS.has(entry.name)) continue\n      await walk(full, visit)\n    } else if (entry.isFile()) {\n      await visit(full)\n    }\n  }\n}\n\n/**\n * Format a violation list for terminal output. One block per violation,\n * trailing summary line. Returns `''` when there are no violations so\n * callers can branch on truthiness.\n */\nexport function formatViolations(violations: readonly Violation[]): string {\n  if (violations.length === 0) return ''\n  const lines: string[] = []\n  for (const v of violations) {\n    const tag = v.severity === 'error' ? 'error' : 'warn'\n    lines.push(`  [${tag}] ${v.file}:${v.line}  ${v.ruleId}`)\n    lines.push(`    ${v.message}`)\n    if (v.suggestion) lines.push(`    -> ${v.suggestion}`)\n    lines.push('')\n  }\n  const errors = violations.filter((v) => v.severity === 'error').length\n  const warnings = violations.length - errors\n  lines.push(`${violations.length} violation(s): ${errors} error, ${warnings} warn`)\n  return lines.join('\\n')\n}\n"],"mappings":";;;;;;;;;;qKA8BA,MAAa,iBAAmB,IAAI,IAAI,CACtC,WACA,YACA,eACA,aACA,aACA,cACA,gBACA,WACF,CAAC,EAGK,UAAY,IAAI,IAAI,CACxB,eACA,OACA,YACA,UAGA,SAEA,aACA,SACA,UACA,UACF,CAAC,EAiCD,eAAsB,QAAQ,KAAwC,CACpE,IAAM,IAAM,KAAK,IACX,WAAa,KAAK,YAAc,GAChC,MAAQ,KAAK,OAAS,CAAC,UAAU,EACjC,QAAU,KAAK,OAASA,MACxB,UAAY,KAAK,WAAa,iBAE9B,WAA0B,CAAC,EAC7B,aAAe,EAEnB,IAAK,IAAM,QAAQ,MAEjB,MAAM,KADQ,KAAK,IAAK,IACT,EAAG,KAAO,OAAS,CAChC,IAAM,KAAO,KAAK,MAAM,KAAK,YAAY,GAAG,EAAI,CAAC,EACjD,GAAI,CAAC,UAAU,IAAI,IAAI,EAAG,OAC1B,IAAM,OAAS,MAAM,SAAS,KAAM,OAAO,EACrC,IAAM,SAAS,IAAK,IAAI,EAC9B,eACA,IAAK,IAAM,QAAQ,QACjB,WAAW,KAAK,GAAG,KAAK,MAAM,CAAE,OAAQ,KAAM,IAAK,UAAW,CAAC,CAAC,CAEpE,CAAC,EAGH,MAAO,CAAE,WAAY,YAAa,CACpC,CAEA,eAAe,KAAK,IAAa,MAAuD,CACtF,IAAI,QACJ,GAAI,CACF,QAAU,MAAM,QAAQ,IAAK,CAAE,cAAe,EAAK,CAAC,CACtD,MAAQ,CACN,MACF,CACA,IAAK,IAAM,SAAS,QAAS,CAC3B,IAAM,KAAO,KAAK,IAAK,MAAM,IAAI,EACjC,GAAI,MAAM,YAAY,EAAG,CACvB,GAAI,UAAU,IAAI,MAAM,IAAI,EAAG,SAC/B,MAAM,KAAK,KAAM,KAAK,CACxB,MAAW,MAAM,OAAO,GACtB,MAAM,MAAM,IAAI,CAEpB,CACF,CAOA,SAAgB,iBAAiB,WAA0C,CACzE,GAAI,WAAW,SAAW,EAAG,MAAO,GACpC,IAAM,MAAkB,CAAC,EACzB,IAAK,IAAM,KAAK,WAAY,CAC1B,IAAM,IAAM,EAAE,WAAa,QAAU,QAAU,OAC/C,MAAM,KAAK,MAAM,IAAI,IAAI,EAAE,KAAK,GAAG,EAAE,KAAK,IAAI,EAAE,QAAQ,EACxD,MAAM,KAAK,OAAO,EAAE,SAAS,EACzB,EAAE,YAAY,MAAM,KAAK,UAAU,EAAE,YAAY,EACrD,MAAM,KAAK,EAAE,CACf,CACA,IAAM,OAAS,WAAW,OAAQ,GAAM,EAAE,WAAa,OAAO,CAAC,CAAC,OAC1D,SAAW,WAAW,OAAS,OAErC,OADA,MAAM,KAAK,GAAG,WAAW,OAAO,iBAAiB,OAAO,UAAU,SAAS,MAAM,EAC1E,MAAM,KAAK;CAAI,CACxB"}

package/dist/rules.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-lint v5.2.2
+ * @forinda/kickjs-lint v5.2.4
  *
  * Copyright (c) Felix Orinda
  *

package/dist/rules.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"rules.mjs","names":[],"sources":["../src/rules.ts"],"sourcesContent":["/**\n * Pure rule definitions. Each rule takes a source file's content + path\n * and returns the violations it found. Stateless and synchronous so the\n * runner can compose them freely (CLI, devtools, editor extension).\n */\n\nexport interface Violation {\n  ruleId: string\n  severity: 'error' | 'warn'\n  file: string\n  /** 1-based line number of the offending construct. */\n  line: number\n  message: string\n  suggestion?: string\n}\n\nexport interface LintContext {\n  source: string\n  file: string\n  /**\n   * Whether the file lives inside `packages/<name>/src/` of the\n   * `@forinda/kickjs-*` monorepo. First-party files are held to the\n   * stricter `kick/` prefix; third-party adopter code is exempt.\n   */\n  firstParty: boolean\n}\n\nexport interface Rule {\n  id: string\n  description: string\n  defaultSeverity: 'error' | 'warn'\n  check(ctx: LintContext): Violation[]\n}\n\nconst SYMBOL_DECL_REGEX = /\\bexport\\s+const\\s+([A-Z_][A-Z0-9_]*)\\s*=\\s*Symbol\\s*\\(/g\nconst CREATE_TOKEN_LITERAL_REGEX = /createToken\\s*(?:<[^>]*>)?\\s*\\(\\s*['\"`]([^'\"`]+)['\"`]/g\n\nfunction lineOf(source: string, index: number): number {\n  return source.slice(0, index).split('\\n').length\n}\n\n/**\n * Forbid `export const X = Symbol('...')` declarations in token-bearing\n * files. The §22 v4 migration replaced first-party DI tokens with\n * `createToken<T>()`; this rule blocks regression in framework code and\n * encourages adopters to follow the same pattern.\n *\n * Inline-disable: append `// kick-lint-disable di-token-symbol` to the\n * declaration line.\n */\nexport const diTokenSymbol: Rule = {\n  id: 'di-token-symbol',\n  description: 'DI tokens must use createToken<T>() instead of Symbol(...)',\n  defaultSeverity: 'error',\n  check({ source, file }) {\n    const out: Violation[] = []\n    const lines = source.split('\\n')\n    for (let i = 0; i < lines.length; i++) {\n      const line = lines[i]\n      if (line.includes('// kick-lint-disable di-token-symbol')) continue\n      SYMBOL_DECL_REGEX.lastIndex = 0\n      const match = SYMBOL_DECL_REGEX.exec(line)\n      if (!match) continue\n      out.push({\n        ruleId: diTokenSymbol.id,\n        severity: diTokenSymbol.defaultSeverity,\n        file,\n        line: i + 1,\n        message: `\\`${match[1]} = Symbol(...)\\` declares a DI token via Symbol`,\n        suggestion: `Use \\`createToken<T>('kick/<area>/<key>')\\` -- see architecture.md section 22`,\n      })\n    }\n    return out\n  },\n}\n\n/**\n * For first-party files, every `createToken('literal')` literal must\n * start with the reserved `kick/` prefix. Third-party adopter code is\n * exempt -- they use their own scope (`mycorp/`, `acme/`, etc.).\n *\n * Allowed back-compat exception: literals starting with `kickjs.` or\n * `kickjs/` (the dotted convention pre-dates section 22 and gets\n * migrated alongside the symbol-to-string work).\n */\nexport const tokenKickPrefix: Rule = {\n  id: 'token-kick-prefix',\n  description: 'First-party DI tokens must start with the reserved `kick/` prefix',\n  defaultSeverity: 'error',\n  check({ source, file, firstParty }) {\n    if (!firstParty) return []\n    const out: Violation[] = []\n    CREATE_TOKEN_LITERAL_REGEX.lastIndex = 0\n    let match: RegExpExecArray | null\n    while ((match = CREATE_TOKEN_LITERAL_REGEX.exec(source)) !== null) {\n      const literal = match[1]\n      if (literal.startsWith('kick/')) continue\n      if (literal.startsWith('kickjs.') || literal.startsWith('kickjs/')) continue\n      out.push({\n        ruleId: tokenKickPrefix.id,\n        severity: tokenKickPrefix.defaultSeverity,\n        file,\n        line: lineOf(source, match.index),\n        message: `\\`createToken('${literal}')\\` is missing the reserved \\`kick/\\` prefix`,\n        suggestion: `Rename to \\`'kick/${literal}'\\` -- first-party tokens own the \\`kick/\\` namespace`,\n      })\n    }\n    return out\n  },\n}\n\n/**\n * Third-party adopters must NOT squat the reserved `kick/` prefix --\n * mirror image of {@link tokenKickPrefix}. Runs only on non-first-party\n * code and warns rather than errors so the rule is informative without\n * blocking adopter installs.\n */\nexport const tokenReservedPrefix: Rule = {\n  id: 'token-reserved-prefix',\n  description: 'Third-party tokens must not start with the reserved `kick/` prefix',\n  defaultSeverity: 'warn',\n  check({ source, file, firstParty }) {\n    if (firstParty) return []\n    const out: Violation[] = []\n    CREATE_TOKEN_LITERAL_REGEX.lastIndex = 0\n    let match: RegExpExecArray | null\n    while ((match = CREATE_TOKEN_LITERAL_REGEX.exec(source)) !== null) {\n      const literal = match[1]\n      if (!literal.startsWith('kick/')) continue\n      out.push({\n        ruleId: tokenReservedPrefix.id,\n        severity: tokenReservedPrefix.defaultSeverity,\n        file,\n        line: lineOf(source, match.index),\n        message: `\\`createToken('${literal}')\\` squats the reserved \\`kick/\\` prefix`,\n        suggestion: `Pick an org-scoped prefix instead (e.g. \\`'mycorp/...'\\`)`,\n      })\n    }\n    return out\n  },\n}\n\n/** All rules shipped by this package, in run order. */\nexport const rules: readonly Rule[] = [diTokenSymbol, tokenKickPrefix, tokenReservedPrefix]\n"],"mappings":";;;;;;;;;;AAkCA,MAAM,kBAAoB,2DACpB,2BAA6B,yDAEnC,SAAS,OAAO,OAAgB,MAAuB,CACrD,OAAO,OAAO,MAAM,EAAG,KAAK,EAAE,MAAM;CAAI,EAAE,MAC5C,CAWA,MAAa,cAAsB,CACjC,GAAI,kBACJ,YAAa,6DACb,gBAAiB,QACjB,MAAM,CAAE,OAAQ,MAAQ,CACtB,IAAM,IAAmB,CAAC,EACpB,MAAQ,OAAO,MAAM;CAAI,EAC/B,IAAK,IAAI,EAAI,EAAG,EAAI,MAAM,OAAQ,IAAK,CACrC,IAAM,KAAO,MAAM,GACnB,GAAI,KAAK,SAAS,sCAAsC,EAAG,SAC3D,kBAAkB,UAAY,EAC9B,IAAM,MAAQ,kBAAkB,KAAK,IAAI,EACpC,OACL,IAAI,KAAK,CACP,OAAQ,cAAc,GACtB,SAAU,cAAc,gBACxB,KACA,KAAM,EAAI,EACV,QAAS,KAAK,MAAM,GAAG,iDACvB,WAAY,6EACd,CAAC,CACH,CACA,OAAO,GACT,CACF,EAWa,gBAAwB,CACnC,GAAI,oBACJ,YAAa,oEACb,gBAAiB,QACjB,MAAM,CAAE,OAAQ,KAAM,YAAc,CAClC,GAAI,CAAC,WAAY,MAAO,CAAC,EACzB,IAAM,IAAmB,CAAC,EAC1B,2BAA2B,UAAY,EACvC,IAAI,MACJ,MAAQ,MAAQ,2BAA2B,KAAK,MAAM,KAAO,MAAM,CACjE,IAAM,QAAU,MAAM,GAClB,QAAQ,WAAW,OAAO,GAC1B,QAAQ,WAAW,SAAS,GAAK,QAAQ,WAAW,SAAS,GACjE,IAAI,KAAK,CACP,OAAQ,gBAAgB,GACxB,SAAU,gBAAgB,gBAC1B,KACA,KAAM,OAAO,OAAQ,MAAM,KAAK,EAChC,QAAS,kBAAkB,QAAQ,+CACnC,WAAY,qBAAqB,QAAQ,sDAC3C,CAAC,CACH,CACA,OAAO,GACT,CACF,EAQa,oBAA4B,CACvC,GAAI,wBACJ,YAAa,qEACb,gBAAiB,OACjB,MAAM,CAAE,OAAQ,KAAM,YAAc,CAClC,GAAI,WAAY,MAAO,CAAC,EACxB,IAAM,IAAmB,CAAC,EAC1B,2BAA2B,UAAY,EACvC,IAAI,MACJ,MAAQ,MAAQ,2BAA2B,KAAK,MAAM,KAAO,MAAM,CACjE,IAAM,QAAU,MAAM,GACjB,QAAQ,WAAW,OAAO,GAC/B,IAAI,KAAK,CACP,OAAQ,oBAAoB,GAC5B,SAAU,oBAAoB,gBAC9B,KACA,KAAM,OAAO,OAAQ,MAAM,KAAK,EAChC,QAAS,kBAAkB,QAAQ,2CACnC,WAAY,yDACd,CAAC,CACH,CACA,OAAO,GACT,CACF,EAGa,MAAyB,CAAC,cAAe,gBAAiB,mBAAmB"}
+{"version":3,"file":"rules.mjs","names":[],"sources":["../src/rules.ts"],"sourcesContent":["/**\n * Pure rule definitions. Each rule takes a source file's content + path\n * and returns the violations it found. Stateless and synchronous so the\n * runner can compose them freely (CLI, devtools, editor extension).\n */\n\nexport interface Violation {\n  ruleId: string\n  severity: 'error' | 'warn'\n  file: string\n  /** 1-based line number of the offending construct. */\n  line: number\n  message: string\n  suggestion?: string\n}\n\nexport interface LintContext {\n  source: string\n  file: string\n  /**\n   * Whether the file lives inside `packages/<name>/src/` of the\n   * `@forinda/kickjs-*` monorepo. First-party files are held to the\n   * stricter `kick/` prefix; third-party adopter code is exempt.\n   */\n  firstParty: boolean\n}\n\nexport interface Rule {\n  id: string\n  description: string\n  defaultSeverity: 'error' | 'warn'\n  check(ctx: LintContext): Violation[]\n}\n\nconst SYMBOL_DECL_REGEX = /\\bexport\\s+const\\s+([A-Z_][A-Z0-9_]*)\\s*=\\s*Symbol\\s*\\(/g\nconst CREATE_TOKEN_LITERAL_REGEX = /createToken\\s*(?:<[^>]*>)?\\s*\\(\\s*['\"`]([^'\"`]+)['\"`]/g\n\nfunction lineOf(source: string, index: number): number {\n  return source.slice(0, index).split('\\n').length\n}\n\n/**\n * Forbid `export const X = Symbol('...')` declarations in token-bearing\n * files. The §22 v4 migration replaced first-party DI tokens with\n * `createToken<T>()`; this rule blocks regression in framework code and\n * encourages adopters to follow the same pattern.\n *\n * Inline-disable: append `// kick-lint-disable di-token-symbol` to the\n * declaration line.\n */\nexport const diTokenSymbol: Rule = {\n  id: 'di-token-symbol',\n  description: 'DI tokens must use createToken<T>() instead of Symbol(...)',\n  defaultSeverity: 'error',\n  check({ source, file }) {\n    const out: Violation[] = []\n    const lines = source.split('\\n')\n    for (let i = 0; i < lines.length; i++) {\n      const line = lines[i]\n      if (line.includes('// kick-lint-disable di-token-symbol')) continue\n      SYMBOL_DECL_REGEX.lastIndex = 0\n      const match = SYMBOL_DECL_REGEX.exec(line)\n      if (!match) continue\n      out.push({\n        ruleId: diTokenSymbol.id,\n        severity: diTokenSymbol.defaultSeverity,\n        file,\n        line: i + 1,\n        message: `\\`${match[1]} = Symbol(...)\\` declares a DI token via Symbol`,\n        suggestion: `Use \\`createToken<T>('kick/<area>/<key>')\\` -- see architecture.md section 22`,\n      })\n    }\n    return out\n  },\n}\n\n/**\n * For first-party files, every `createToken('literal')` literal must\n * start with the reserved `kick/` prefix. Third-party adopter code is\n * exempt -- they use their own scope (`mycorp/`, `acme/`, etc.).\n *\n * Allowed back-compat exception: literals starting with `kickjs.` or\n * `kickjs/` (the dotted convention pre-dates section 22 and gets\n * migrated alongside the symbol-to-string work).\n */\nexport const tokenKickPrefix: Rule = {\n  id: 'token-kick-prefix',\n  description: 'First-party DI tokens must start with the reserved `kick/` prefix',\n  defaultSeverity: 'error',\n  check({ source, file, firstParty }) {\n    if (!firstParty) return []\n    const out: Violation[] = []\n    CREATE_TOKEN_LITERAL_REGEX.lastIndex = 0\n    let match: RegExpExecArray | null\n    while ((match = CREATE_TOKEN_LITERAL_REGEX.exec(source)) !== null) {\n      const literal = match[1]\n      if (literal.startsWith('kick/')) continue\n      if (literal.startsWith('kickjs.') || literal.startsWith('kickjs/')) continue\n      out.push({\n        ruleId: tokenKickPrefix.id,\n        severity: tokenKickPrefix.defaultSeverity,\n        file,\n        line: lineOf(source, match.index),\n        message: `\\`createToken('${literal}')\\` is missing the reserved \\`kick/\\` prefix`,\n        suggestion: `Rename to \\`'kick/${literal}'\\` -- first-party tokens own the \\`kick/\\` namespace`,\n      })\n    }\n    return out\n  },\n}\n\n/**\n * Third-party adopters must NOT squat the reserved `kick/` prefix --\n * mirror image of {@link tokenKickPrefix}. Runs only on non-first-party\n * code and warns rather than errors so the rule is informative without\n * blocking adopter installs.\n */\nexport const tokenReservedPrefix: Rule = {\n  id: 'token-reserved-prefix',\n  description: 'Third-party tokens must not start with the reserved `kick/` prefix',\n  defaultSeverity: 'warn',\n  check({ source, file, firstParty }) {\n    if (firstParty) return []\n    const out: Violation[] = []\n    CREATE_TOKEN_LITERAL_REGEX.lastIndex = 0\n    let match: RegExpExecArray | null\n    while ((match = CREATE_TOKEN_LITERAL_REGEX.exec(source)) !== null) {\n      const literal = match[1]\n      if (!literal.startsWith('kick/')) continue\n      out.push({\n        ruleId: tokenReservedPrefix.id,\n        severity: tokenReservedPrefix.defaultSeverity,\n        file,\n        line: lineOf(source, match.index),\n        message: `\\`createToken('${literal}')\\` squats the reserved \\`kick/\\` prefix`,\n        suggestion: `Pick an org-scoped prefix instead (e.g. \\`'mycorp/...'\\`)`,\n      })\n    }\n    return out\n  },\n}\n\n/** All rules shipped by this package, in run order. */\nexport const rules: readonly Rule[] = [diTokenSymbol, tokenKickPrefix, tokenReservedPrefix]\n"],"mappings":";;;;;;;;;;AAkCA,MAAM,kBAAoB,2DACpB,2BAA6B,yDAEnC,SAAS,OAAO,OAAgB,MAAuB,CACrD,OAAO,OAAO,MAAM,EAAG,KAAK,CAAC,CAAC,MAAM;CAAI,CAAC,CAAC,MAC5C,CAWA,MAAa,cAAsB,CACjC,GAAI,kBACJ,YAAa,6DACb,gBAAiB,QACjB,MAAM,CAAE,OAAQ,MAAQ,CACtB,IAAM,IAAmB,CAAC,EACpB,MAAQ,OAAO,MAAM;CAAI,EAC/B,IAAK,IAAI,EAAI,EAAG,EAAI,MAAM,OAAQ,IAAK,CACrC,IAAM,KAAO,MAAM,GACnB,GAAI,KAAK,SAAS,sCAAsC,EAAG,SAC3D,kBAAkB,UAAY,EAC9B,IAAM,MAAQ,kBAAkB,KAAK,IAAI,EACpC,OACL,IAAI,KAAK,CACP,OAAQ,cAAc,GACtB,SAAU,cAAc,gBACxB,KACA,KAAM,EAAI,EACV,QAAS,KAAK,MAAM,GAAG,iDACvB,WAAY,6EACd,CAAC,CACH,CACA,OAAO,GACT,CACF,EAWa,gBAAwB,CACnC,GAAI,oBACJ,YAAa,oEACb,gBAAiB,QACjB,MAAM,CAAE,OAAQ,KAAM,YAAc,CAClC,GAAI,CAAC,WAAY,MAAO,CAAC,EACzB,IAAM,IAAmB,CAAC,EAC1B,2BAA2B,UAAY,EACvC,IAAI,MACJ,MAAQ,MAAQ,2BAA2B,KAAK,MAAM,KAAO,MAAM,CACjE,IAAM,QAAU,MAAM,GAClB,QAAQ,WAAW,OAAO,GAC1B,QAAQ,WAAW,SAAS,GAAK,QAAQ,WAAW,SAAS,GACjE,IAAI,KAAK,CACP,OAAQ,gBAAgB,GACxB,SAAU,gBAAgB,gBAC1B,KACA,KAAM,OAAO,OAAQ,MAAM,KAAK,EAChC,QAAS,kBAAkB,QAAQ,+CACnC,WAAY,qBAAqB,QAAQ,sDAC3C,CAAC,CACH,CACA,OAAO,GACT,CACF,EAQa,oBAA4B,CACvC,GAAI,wBACJ,YAAa,qEACb,gBAAiB,OACjB,MAAM,CAAE,OAAQ,KAAM,YAAc,CAClC,GAAI,WAAY,MAAO,CAAC,EACxB,IAAM,IAAmB,CAAC,EAC1B,2BAA2B,UAAY,EACvC,IAAI,MACJ,MAAQ,MAAQ,2BAA2B,KAAK,MAAM,KAAO,MAAM,CACjE,IAAM,QAAU,MAAM,GACjB,QAAQ,WAAW,OAAO,GAC/B,IAAI,KAAK,CACP,OAAQ,oBAAoB,GAC5B,SAAU,oBAAoB,gBAC9B,KACA,KAAM,OAAO,OAAQ,MAAM,KAAK,EAChC,QAAS,kBAAkB,QAAQ,2CACnC,WAAY,yDACd,CAAC,CACH,CACA,OAAO,GACT,CACF,EAGa,MAAyB,CAAC,cAAe,gBAAiB,mBAAmB"}

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@forinda/kickjs-lint",
-  "version": "5.2.2",
+  "version": "5.2.4",
   "description": "Lint rules for KickJS — DI token convention, plugin/adapter naming, and other framework conventions",
   "keywords": [
     "kickjs",
+    "nodejs",
+    "typescript",
     "lint",
-    "convention",
-    "di",
-    "token",
+    "kickjs-lint",
+    "di-token-convention",
     "static-analysis",
-    "@forinda/kickjs",
-    "@forinda/kickjs-cli"
+    "naming-convention",
+    "framework-lint"
   ],
   "type": "module",
   "main": "dist/index.mjs",
@@ -32,25 +33,11 @@
     "dist",
     "bin.mjs"
   ],
-  "wireit": {
-    "build": {
-      "command": "tsdown",
-      "files": [
-        "src/**/*.ts",
-        "tsdown.config.ts",
-        "tsconfig.json",
-        "package.json"
-      ],
-      "output": [
-        "dist/**"
-      ]
-    }
-  },
   "dependencies": {},
   "devDependencies": {
-    "@types/node": "^25.7.0",
+    "@types/node": "^25.9.2",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.8"
   },
   "publishConfig": {
     "access": "public"
@@ -60,7 +47,7 @@
   "engines": {
     "node": ">=20.0"
   },
-  "homepage": "https://forinda.github.io/kick-js/",
+  "homepage": "https://kickjs.app/",
   "repository": {
     "type": "git",
     "url": "https://github.com/forinda/kick-js.git",
@@ -70,10 +57,10 @@
     "url": "https://github.com/forinda/kick-js/issues"
   },
   "scripts": {
-    "build": "wireit",
+    "build": "tsdown",
     "dev": "tsdown --watch",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "clean": "rm -rf dist .wireit"
   }
 }