@forinda/kickjs-lint 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Felix Orinda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @forinda/kickjs-lint
+
+Lint rules for KickJS conventions — DI tokens, plugin/adapter naming, and other framework patterns.
+
+## Install
+
+```bash
+pnpm add -D @forinda/kickjs-lint
+```
+
+## CLI
+
+```bash
+# adopter project — lints `src/`, warns on third-party kick/ squatting
+kick-lint
+
+# framework / first-party packages — lints `packages/`, errors on missing kick/ prefix
+kick-lint --first-party
+
+# custom scope
+kick-lint --scope src,libs
+```
+
+## Programmatic
+
+```ts
+import { runLint, formatViolations } from '@forinda/kickjs-lint'
+
+const result = await runLint({ cwd: process.cwd(), firstParty: false })
+if (result.violations.length > 0) console.error(formatViolations(result.violations))
+```
+
+## Rules
+
+| Rule                        | Default  | Description                                                                        |
+| --------------------------- | -------- | ---------------------------------------------------------------------------------- |
+| `di-token-symbol`           | `error`  | DI tokens must use `createToken<T>()` instead of `Symbol(...)` in token files       |
+| `token-kick-prefix`         | `error`  | First-party tokens must start with the reserved `kick/` prefix                     |
+| `token-reserved-prefix`     | `warn`   | Third-party tokens must not squat the reserved `kick/` prefix                       |
+
+Inline-disable a rule on a single line:
+
+```ts
+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 and the [v3→v4 migration guide](https://forinda.github.io/kick-js/guide/migration-v3-to-v4) for what changed.

package/bin.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * `kick-lint` CLI entry. Wraps {@link runLint} from the package's
+ * programmatic API with argv parsing + process exit translation.
+ *
+ * Usage:
+ *   kick-lint                       lint adopter project (cwd, scope=src)
+ *   kick-lint --first-party         lint framework code (cwd, scope=packages)
+ *   kick-lint --scope src,libs      override scoped subdirectories
+ *   kick-lint --cwd /path/to/repo   override working directory
+ */
+
+import { runLint, formatViolations } from './dist/index.mjs'
+import process from 'node:process'
+
+const args = process.argv.slice(2)
+let cwd = process.cwd()
+let firstParty = false
+let scope = ['src']
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i]
+  if (arg === '--first-party') {
+    firstParty = true
+    if (scope.length === 1 && scope[0] === 'src') scope = ['packages']
+  } else if (arg === '--scope') {
+    const next = args[++i]
+    if (!next) {
+      console.error('kick-lint: --scope requires a value')
+      process.exit(2)
+    }
+    scope = next
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+  } else if (arg === '--cwd') {
+    const next = args[++i]
+    if (!next) {
+      console.error('kick-lint: --cwd requires a value')
+      process.exit(2)
+    }
+    cwd = next
+  } else if (arg === '--help' || arg === '-h') {
+    console.log(
+      'Usage: kick-lint [--first-party] [--scope dir1,dir2] [--cwd path]\n' +
+        '\n' +
+        '  --first-party   enable framework-strict ruleset (default scope: packages)\n' +
+        '  --scope <dirs>  comma-separated subdirectories to walk (default: src)\n' +
+        '  --cwd <path>    working directory override\n',
+    )
+    process.exit(0)
+  } else {
+    console.error(`kick-lint: unknown arg ${arg}`)
+    process.exit(2)
+  }
+}
+
+const result = await runLint({ cwd, firstParty, scope })
+const errors = result.violations.filter((v) => v.severity === 'error').length
+
+if (result.violations.length === 0) {
+  console.log(`kick-lint: ${result.filesScanned} file(s) scanned, no violations`)
+  process.exit(0)
+}
+
+console.error(formatViolations(result.violations))
+process.exit(errors > 0 ? 1 : 0)

package/dist/index.d.mts

@@ -0,0 +1,49 @@
+
+import { LintContext, Rule, Violation, diTokenSymbol, rules, tokenKickPrefix, tokenReservedPrefix } from "./rules.mjs";
+
+//#region src/index.d.ts
+/**
+ * Filenames that historically declare DI tokens. Lint runs only on
+ * these to keep false positives out of unrelated files (e.g. a class
+ * named `Symbol` in a math library).
+ */
+declare const TOKEN_FILE_NAMES: Set<string>;
+interface LintOptions {
+  /** Root directory to walk. Required. */
+  cwd: string;
+  /**
+   * Whether the project being linted is a first-party `@forinda/kickjs-*`
+   * package (enables `token-kick-prefix`, disables `token-reserved-prefix`).
+   * Defaults to `false` so adopter projects use the friendlier ruleset.
+   */
+  firstParty?: boolean;
+  /**
+   * Only lint files inside these subdirectories (relative to `cwd`).
+   * Defaults to `['packages']` for first-party use; pass `['src']` or
+   * `['.']` for adopter projects.
+   */
+  scope?: readonly string[];
+  /** Override the rule set. Defaults to every rule shipped by the package. */
+  rules?: readonly Rule[];
+  /** Filenames to lint (defaults to {@link TOKEN_FILE_NAMES}). */
+  filenames?: ReadonlySet<string>;
+}
+interface LintResult {
+  violations: Violation[];
+  filesScanned: number;
+}
+/**
+ * Walk `cwd` (constrained to `scope` directories), apply every rule to
+ * each token-bearing file, and return the aggregated violations + the
+ * number of files actually checked.
+ */
+declare function runLint(opts: LintOptions): Promise<LintResult>;
+/**
+ * Format a violation list for terminal output. One block per violation,
+ * trailing summary line. Returns `''` when there are no violations so
+ * callers can branch on truthiness.
+ */
+declare function formatViolations(violations: readonly Violation[]): string;
+//#endregion
+export { type LintContext, LintOptions, LintResult, type Rule, TOKEN_FILE_NAMES, type Violation, rules as defaultRules, diTokenSymbol, formatViolations, runLint, tokenKickPrefix, tokenReservedPrefix };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;cA0Ba,gBAAA,EAAgB,GAAA;AAAA,UAWZ,WAAA;;EAEf,GAAA;EAoBA;;;;;EAdA,UAAA;EAuB2B;;;;;EAjB3B,KAAA;EAiBuD;EAfvD,KAAA,YAAiB,IAAA;EAeW;EAb5B,SAAA,GAAY,WAAA;AAAA;AAAA,UAGG,UAAA;EACf,UAAA,EAAY,SAAA;EACZ,YAAA;AAAA;;;;;;iBAQoB,OAAA,CAAQ,IAAA,EAAM,WAAA,GAAc,OAAA,CAAQ,UAAA;;;;;;iBAkD1C,gBAAA,CAAiB,UAAA,WAAqB,SAAA"}

package/dist/index.mjs

@@ -0,0 +1,115 @@
+/**
+ * @forinda/kickjs-lint v4.0.0
+ *
+ * Copyright (c) Felix Orinda
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+import { diTokenSymbol, rules, tokenKickPrefix, tokenReservedPrefix } from "./rules.mjs";
+import { readFile, readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+//#region src/index.ts
+/**
+* Programmatic entry point for `@forinda/kickjs-lint`.
+*
+* Walks a directory tree, applies every enabled rule from
+* {@link ./rules} to each file that matches the token-bearing filename
+* heuristic, and returns the aggregated violations.
+*
+* The CLI binary (`bin.mjs`) wraps this with a process-exit translation
+* layer; downstream tools (devtools, editor extensions) call this
+* directly.
+*
+* @module @forinda/kickjs-lint
+*/
+/**
+* Filenames that historically declare DI tokens. Lint runs only on
+* these to keep false positives out of unrelated files (e.g. a class
+* named `Symbol` in a math library).
+*/
+const TOKEN_FILE_NAMES = new Set([
+	"types.ts",
+	"tokens.ts",
+	"constants.ts",
+	"service.ts",
+	"adapter.ts"
+]);
+/** Directories the walker skips wholesale. */
+const SKIP_DIRS = new Set([
+	"node_modules",
+	"dist",
+	"__tests__",
+	".kickjs"
+]);
+/**
+* Walk `cwd` (constrained to `scope` directories), apply every rule to
+* each token-bearing file, and return the aggregated violations + the
+* number of files actually checked.
+*/
+async function runLint(opts) {
+	const cwd = opts.cwd;
+	const firstParty = opts.firstParty ?? false;
+	const scope = opts.scope ?? ["packages"];
+	const ruleset = opts.rules ?? rules;
+	const filenames = opts.filenames ?? TOKEN_FILE_NAMES;
+	const violations = [];
+	let filesScanned = 0;
+	for (const root of scope) await walk(join(cwd, root), async (file) => {
+		const base = file.slice(file.lastIndexOf("/") + 1);
+		if (!filenames.has(base)) return;
+		const source = await readFile(file, "utf-8");
+		const rel = relative(cwd, file);
+		filesScanned++;
+		for (const rule of ruleset) violations.push(...rule.check({
+			source,
+			file: rel,
+			firstParty
+		}));
+	});
+	return {
+		violations,
+		filesScanned
+	};
+}
+async function walk(dir, visit) {
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (SKIP_DIRS.has(entry.name)) continue;
+			await walk(full, visit);
+		} else if (entry.isFile()) await visit(full);
+	}
+}
+/**
+* Format a violation list for terminal output. One block per violation,
+* trailing summary line. Returns `''` when there are no violations so
+* callers can branch on truthiness.
+*/
+function formatViolations(violations) {
+	if (violations.length === 0) return "";
+	const lines = [];
+	for (const v of violations) {
+		const tag = v.severity === "error" ? "error" : "warn";
+		lines.push(`  [${tag}] ${v.file}:${v.line}  ${v.ruleId}`);
+		lines.push(`    ${v.message}`);
+		if (v.suggestion) lines.push(`    -> ${v.suggestion}`);
+		lines.push("");
+	}
+	const errors = violations.filter((v) => v.severity === "error").length;
+	const warnings = violations.length - errors;
+	lines.push(`${violations.length} violation(s): ${errors} error, ${warnings} warn`);
+	return lines.join("\n");
+}
+//#endregion
+export { TOKEN_FILE_NAMES, rules as defaultRules, diTokenSymbol, formatViolations, runLint, tokenKickPrefix, tokenReservedPrefix };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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 */\nexport const TOKEN_FILE_NAMES = new Set([\n  'types.ts',\n  'tokens.ts',\n  'constants.ts',\n  'service.ts',\n  'adapter.ts',\n])\n\n/** Directories the walker skips wholesale. */\nconst SKIP_DIRS = new Set(['node_modules', 'dist', '__tests__', '.kickjs'])\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,MAAa,mBAAmB,IAAI,IAAI;CACtC;CACA;CACA;CACA;CACA;CACD,CAAC;;AAGF,MAAM,YAAY,IAAI,IAAI;CAAC;CAAgB;CAAQ;CAAa;CAAU,CAAC;;;;;;AAiC3E,eAAsB,QAAQ,MAAwC;CACpE,MAAM,MAAM,KAAK;CACjB,MAAM,aAAa,KAAK,cAAc;CACtC,MAAM,QAAQ,KAAK,SAAS,CAAC,WAAW;CACxC,MAAM,UAAU,KAAK,SAASA;CAC9B,MAAM,YAAY,KAAK,aAAa;CAEpC,MAAM,aAA0B,EAAE;CAClC,IAAI,eAAe;AAEnB,MAAK,MAAM,QAAQ,MAEjB,OAAM,KADQ,KAAK,KAAK,KAAK,EACX,OAAO,SAAS;EAChC,MAAM,OAAO,KAAK,MAAM,KAAK,YAAY,IAAI,GAAG,EAAE;AAClD,MAAI,CAAC,UAAU,IAAI,KAAK,CAAE;EAC1B,MAAM,SAAS,MAAM,SAAS,MAAM,QAAQ;EAC5C,MAAM,MAAM,SAAS,KAAK,KAAK;AAC/B;AACA,OAAK,MAAM,QAAQ,QACjB,YAAW,KAAK,GAAG,KAAK,MAAM;GAAE;GAAQ,MAAM;GAAK;GAAY,CAAC,CAAC;GAEnE;AAGJ,QAAO;EAAE;EAAY;EAAc;;AAGrC,eAAe,KAAK,KAAa,OAAuD;CACtF,IAAI;AACJ,KAAI;AACF,YAAU,MAAM,QAAQ,KAAK,EAAE,eAAe,MAAM,CAAC;SAC/C;AACN;;AAEF,MAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,OAAO,KAAK,KAAK,MAAM,KAAK;AAClC,MAAI,MAAM,aAAa,EAAE;AACvB,OAAI,UAAU,IAAI,MAAM,KAAK,CAAE;AAC/B,SAAM,KAAK,MAAM,MAAM;aACd,MAAM,QAAQ,CACvB,OAAM,MAAM,KAAK;;;;;;;;AAUvB,SAAgB,iBAAiB,YAA0C;AACzE,KAAI,WAAW,WAAW,EAAG,QAAO;CACpC,MAAM,QAAkB,EAAE;AAC1B,MAAK,MAAM,KAAK,YAAY;EAC1B,MAAM,MAAM,EAAE,aAAa,UAAU,UAAU;AAC/C,QAAM,KAAK,MAAM,IAAI,IAAI,EAAE,KAAK,GAAG,EAAE,KAAK,IAAI,EAAE,SAAS;AACzD,QAAM,KAAK,OAAO,EAAE,UAAU;AAC9B,MAAI,EAAE,WAAY,OAAM,KAAK,UAAU,EAAE,aAAa;AACtD,QAAM,KAAK,GAAG;;CAEhB,MAAM,SAAS,WAAW,QAAQ,MAAM,EAAE,aAAa,QAAQ,CAAC;CAChE,MAAM,WAAW,WAAW,SAAS;AACrC,OAAM,KAAK,GAAG,WAAW,OAAO,iBAAiB,OAAO,UAAU,SAAS,OAAO;AAClF,QAAO,MAAM,KAAK,KAAK"}

package/dist/rules.d.mts

@@ -0,0 +1,64 @@
+
+//#region src/rules.d.ts
+/**
+ * Pure rule definitions. Each rule takes a source file's content + path
+ * and returns the violations it found. Stateless and synchronous so the
+ * runner can compose them freely (CLI, devtools, editor extension).
+ */
+interface Violation {
+  ruleId: string;
+  severity: 'error' | 'warn';
+  file: string;
+  /** 1-based line number of the offending construct. */
+  line: number;
+  message: string;
+  suggestion?: string;
+}
+interface LintContext {
+  source: string;
+  file: string;
+  /**
+   * Whether the file lives inside `packages/<name>/src/` of the
+   * `@forinda/kickjs-*` monorepo. First-party files are held to the
+   * stricter `kick/` prefix; third-party adopter code is exempt.
+   */
+  firstParty: boolean;
+}
+interface Rule {
+  id: string;
+  description: string;
+  defaultSeverity: 'error' | 'warn';
+  check(ctx: LintContext): Violation[];
+}
+/**
+ * Forbid `export const X = Symbol('...')` declarations in token-bearing
+ * files. The §22 v4 migration replaced first-party DI tokens with
+ * `createToken<T>()`; this rule blocks regression in framework code and
+ * encourages adopters to follow the same pattern.
+ *
+ * Inline-disable: append `// kick-lint-disable di-token-symbol` to the
+ * declaration line.
+ */
+declare const diTokenSymbol: Rule;
+/**
+ * For first-party files, every `createToken('literal')` literal must
+ * start with the reserved `kick/` prefix. Third-party adopter code is
+ * exempt -- they use their own scope (`mycorp/`, `acme/`, etc.).
+ *
+ * Allowed back-compat exception: literals starting with `kickjs.` or
+ * `kickjs/` (the dotted convention pre-dates section 22 and gets
+ * migrated alongside the symbol-to-string work).
+ */
+declare const tokenKickPrefix: Rule;
+/**
+ * Third-party adopters must NOT squat the reserved `kick/` prefix --
+ * mirror image of {@link tokenKickPrefix}. Runs only on non-first-party
+ * code and warns rather than errors so the rule is informative without
+ * blocking adopter installs.
+ */
+declare const tokenReservedPrefix: Rule;
+/** All rules shipped by this package, in run order. */
+declare const rules: readonly Rule[];
+//#endregion
+export { LintContext, Rule, Violation, diTokenSymbol, rules, tokenKickPrefix, tokenReservedPrefix };
+//# sourceMappingURL=rules.d.mts.map

package/dist/rules.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.mts","names":[],"sources":["../src/rules.ts"],"mappings":";;;AAMA;;;;UAAiB,SAAA;EACf,MAAA;EACA,QAAA;EACA,IAAA;EAGA;EADA,IAAA;EACA,OAAA;EACA,UAAA;AAAA;AAAA,UAGe,WAAA;EACf,MAAA;EACA,IAAA;EADA;;;;;EAOA,UAAA;AAAA;AAAA,UAGe,IAAA;EACf,EAAA;EACA,WAAA;EACA,eAAA;EACA,KAAA,CAAM,GAAA,EAAK,WAAA,GAAc,SAAA;AAAA;;;;;;AAmB3B;;;;cAAa,aAAA,EAAe,IAAA;AAmC5B;;;;;AAgCA;;;;AAhCA,cAAa,eAAA,EAAiB,IAAA;AA0D9B;;;;;;AAAA,cA1Ba,mBAAA,EAAqB,IAAA;;cA0BrB,KAAA,WAAgB,IAAA"}

package/dist/rules.mjs

@@ -0,0 +1,124 @@
+/**
+ * @forinda/kickjs-lint v4.0.0
+ *
+ * Copyright (c) Felix Orinda
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+//#region src/rules.ts
+const SYMBOL_DECL_REGEX = /\bexport\s+const\s+([A-Z_][A-Z0-9_]*)\s*=\s*Symbol\s*\(/g;
+const CREATE_TOKEN_LITERAL_REGEX = /createToken\s*(?:<[^>]*>)?\s*\(\s*['"`]([^'"`]+)['"`]/g;
+function lineOf(source, index) {
+	return source.slice(0, index).split("\n").length;
+}
+/**
+* Forbid `export const X = Symbol('...')` declarations in token-bearing
+* files. The §22 v4 migration replaced first-party DI tokens with
+* `createToken<T>()`; this rule blocks regression in framework code and
+* encourages adopters to follow the same pattern.
+*
+* Inline-disable: append `// kick-lint-disable di-token-symbol` to the
+* declaration line.
+*/
+const diTokenSymbol = {
+	id: "di-token-symbol",
+	description: "DI tokens must use createToken<T>() instead of Symbol(...)",
+	defaultSeverity: "error",
+	check({ source, file }) {
+		const out = [];
+		const lines = source.split("\n");
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i];
+			if (line.includes("// kick-lint-disable di-token-symbol")) continue;
+			SYMBOL_DECL_REGEX.lastIndex = 0;
+			const match = SYMBOL_DECL_REGEX.exec(line);
+			if (!match) continue;
+			out.push({
+				ruleId: diTokenSymbol.id,
+				severity: diTokenSymbol.defaultSeverity,
+				file,
+				line: i + 1,
+				message: `\`${match[1]} = Symbol(...)\` declares a DI token via Symbol`,
+				suggestion: `Use \`createToken<T>('kick/<area>/<key>')\` -- see architecture.md section 22`
+			});
+		}
+		return out;
+	}
+};
+/**
+* For first-party files, every `createToken('literal')` literal must
+* start with the reserved `kick/` prefix. Third-party adopter code is
+* exempt -- they use their own scope (`mycorp/`, `acme/`, etc.).
+*
+* Allowed back-compat exception: literals starting with `kickjs.` or
+* `kickjs/` (the dotted convention pre-dates section 22 and gets
+* migrated alongside the symbol-to-string work).
+*/
+const tokenKickPrefix = {
+	id: "token-kick-prefix",
+	description: "First-party DI tokens must start with the reserved `kick/` prefix",
+	defaultSeverity: "error",
+	check({ source, file, firstParty }) {
+		if (!firstParty) return [];
+		const out = [];
+		CREATE_TOKEN_LITERAL_REGEX.lastIndex = 0;
+		let match;
+		while ((match = CREATE_TOKEN_LITERAL_REGEX.exec(source)) !== null) {
+			const literal = match[1];
+			if (literal.startsWith("kick/")) continue;
+			if (literal.startsWith("kickjs.") || literal.startsWith("kickjs/")) continue;
+			out.push({
+				ruleId: tokenKickPrefix.id,
+				severity: tokenKickPrefix.defaultSeverity,
+				file,
+				line: lineOf(source, match.index),
+				message: `\`createToken('${literal}')\` is missing the reserved \`kick/\` prefix`,
+				suggestion: `Rename to \`'kick/${literal}'\` -- first-party tokens own the \`kick/\` namespace`
+			});
+		}
+		return out;
+	}
+};
+/**
+* Third-party adopters must NOT squat the reserved `kick/` prefix --
+* mirror image of {@link tokenKickPrefix}. Runs only on non-first-party
+* code and warns rather than errors so the rule is informative without
+* blocking adopter installs.
+*/
+const tokenReservedPrefix = {
+	id: "token-reserved-prefix",
+	description: "Third-party tokens must not start with the reserved `kick/` prefix",
+	defaultSeverity: "warn",
+	check({ source, file, firstParty }) {
+		if (firstParty) return [];
+		const out = [];
+		CREATE_TOKEN_LITERAL_REGEX.lastIndex = 0;
+		let match;
+		while ((match = CREATE_TOKEN_LITERAL_REGEX.exec(source)) !== null) {
+			const literal = match[1];
+			if (!literal.startsWith("kick/")) continue;
+			out.push({
+				ruleId: tokenReservedPrefix.id,
+				severity: tokenReservedPrefix.defaultSeverity,
+				file,
+				line: lineOf(source, match.index),
+				message: `\`createToken('${literal}')\` squats the reserved \`kick/\` prefix`,
+				suggestion: `Pick an org-scoped prefix instead (e.g. \`'mycorp/...'\`)`
+			});
+		}
+		return out;
+	}
+};
+/** All rules shipped by this package, in run order. */
+const rules = [
+	diTokenSymbol,
+	tokenKickPrefix,
+	tokenReservedPrefix
+];
+//#endregion
+export { diTokenSymbol, rules, tokenKickPrefix, tokenReservedPrefix };
+
+//# sourceMappingURL=rules.mjs.map

package/dist/rules.mjs.map

@@ -0,0 +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,oBAAoB;AAC1B,MAAM,6BAA6B;AAEnC,SAAS,OAAO,QAAgB,OAAuB;AACrD,QAAO,OAAO,MAAM,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC;;;;;;;;;;;AAY5C,MAAa,gBAAsB;CACjC,IAAI;CACJ,aAAa;CACb,iBAAiB;CACjB,MAAM,EAAE,QAAQ,QAAQ;EACtB,MAAM,MAAmB,EAAE;EAC3B,MAAM,QAAQ,OAAO,MAAM,KAAK;AAChC,OAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;GACrC,MAAM,OAAO,MAAM;AACnB,OAAI,KAAK,SAAS,uCAAuC,CAAE;AAC3D,qBAAkB,YAAY;GAC9B,MAAM,QAAQ,kBAAkB,KAAK,KAAK;AAC1C,OAAI,CAAC,MAAO;AACZ,OAAI,KAAK;IACP,QAAQ,cAAc;IACtB,UAAU,cAAc;IACxB;IACA,MAAM,IAAI;IACV,SAAS,KAAK,MAAM,GAAG;IACvB,YAAY;IACb,CAAC;;AAEJ,SAAO;;CAEV;;;;;;;;;;AAWD,MAAa,kBAAwB;CACnC,IAAI;CACJ,aAAa;CACb,iBAAiB;CACjB,MAAM,EAAE,QAAQ,MAAM,cAAc;AAClC,MAAI,CAAC,WAAY,QAAO,EAAE;EAC1B,MAAM,MAAmB,EAAE;AAC3B,6BAA2B,YAAY;EACvC,IAAI;AACJ,UAAQ,QAAQ,2BAA2B,KAAK,OAAO,MAAM,MAAM;GACjE,MAAM,UAAU,MAAM;AACtB,OAAI,QAAQ,WAAW,QAAQ,CAAE;AACjC,OAAI,QAAQ,WAAW,UAAU,IAAI,QAAQ,WAAW,UAAU,CAAE;AACpE,OAAI,KAAK;IACP,QAAQ,gBAAgB;IACxB,UAAU,gBAAgB;IAC1B;IACA,MAAM,OAAO,QAAQ,MAAM,MAAM;IACjC,SAAS,kBAAkB,QAAQ;IACnC,YAAY,qBAAqB,QAAQ;IAC1C,CAAC;;AAEJ,SAAO;;CAEV;;;;;;;AAQD,MAAa,sBAA4B;CACvC,IAAI;CACJ,aAAa;CACb,iBAAiB;CACjB,MAAM,EAAE,QAAQ,MAAM,cAAc;AAClC,MAAI,WAAY,QAAO,EAAE;EACzB,MAAM,MAAmB,EAAE;AAC3B,6BAA2B,YAAY;EACvC,IAAI;AACJ,UAAQ,QAAQ,2BAA2B,KAAK,OAAO,MAAM,MAAM;GACjE,MAAM,UAAU,MAAM;AACtB,OAAI,CAAC,QAAQ,WAAW,QAAQ,CAAE;AAClC,OAAI,KAAK;IACP,QAAQ,oBAAoB;IAC5B,UAAU,oBAAoB;IAC9B;IACA,MAAM,OAAO,QAAQ,MAAM,MAAM;IACjC,SAAS,kBAAkB,QAAQ;IACnC,YAAY;IACb,CAAC;;AAEJ,SAAO;;CAEV;;AAGD,MAAa,QAAyB;CAAC;CAAe;CAAiB;CAAoB"}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@forinda/kickjs-lint",
+  "version": "4.0.0",
+  "description": "Lint rules for KickJS — DI token convention, plugin/adapter naming, and other framework conventions",
+  "keywords": [
+    "kickjs",
+    "lint",
+    "convention",
+    "di",
+    "token",
+    "static-analysis",
+    "@forinda/kickjs",
+    "@forinda/kickjs-cli"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "bin": {
+    "kick-lint": "bin.mjs"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    },
+    "./rules": {
+      "import": "./dist/rules.mjs",
+      "types": "./dist/rules.d.mts"
+    }
+  },
+  "files": [
+    "dist",
+    "bin.mjs"
+  ],
+  "wireit": {
+    "build": {
+      "command": "tsdown",
+      "files": [
+        "src/**/*.ts",
+        "tsdown.config.ts",
+        "tsconfig.json",
+        "package.json"
+      ],
+      "output": [
+        "dist/**"
+      ]
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Felix Orinda",
+  "engines": {
+    "node": ">=20.0"
+  },
+  "homepage": "https://forinda.github.io/kick-js/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forinda/kick-js.git",
+    "directory": "packages/lint"
+  },
+  "bugs": {
+    "url": "https://github.com/forinda/kick-js/issues"
+  },
+  "scripts": {
+    "build": "wireit",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .wireit"
+  }
+}