@lapidist/design-lint-testing 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# @lapidist/design-lint-testing
+
+## 1.0.0
+
+### Major Changes
+
+- 5c9a371: v8: DSR kernel integration — remove v7 token fallback, require tokenProvider
+
+  `createLinter` and the `Linter` constructor now throw when `Environment.tokenProvider` is absent. The v7 inline-config fallback (`ConfigTokenProvider` loaded silently from `config.tokens`) has been removed from both `setup.ts` and `linter.ts`. Callers must supply a `tokenProvider` — the DSR kernel is the authoritative source.
+
+  `DsrOptions.beforeConnect` is a new optional async hook that programmatic callers (LSP, MCP, scripts) can use to auto-start the kernel without depending on the CLI's `prepareEnvironment`.
+
+- 5c9a371: Initial release of eight new design-lint v8 packages: config-recommended, config-strict, config-ai-agent, testing (RuleTester), telemetry (DLTS v1 SDK + OTel), mcp (AEP v1 types), lsp (LSP capability types), rdk (Rule Development Kit)
+
+### Minor Changes
+
+- 5c9a371: feat!: v8 release — DSR kernel integration, MCP/LSP/telemetry packages, RuleTester, config presets, and RDK; the linter now delegates token resolution to the DSR kernel when running, removing internal token/rule state ownership
+- 5c9a371: feat(testing): complete RuleTester coverage for all 30 built-in rules; add DtifFlattenedToken injection to ValidCase/InvalidCase so token-based rules can exercise real validation logic; fix TSX/JSX docType normalisation through FILE_TYPE_MAP so tsx snippets resolve to the TypeScript parser
+
+### Patch Changes
+
+- 5c9a371: feat(testing): export SnippetLinter from package index
+  test(config): add tests for config-recommended, config-strict, and config-ai-agent presets
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [3a76856]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+- Updated dependencies [5c9a371]
+  - @lapidist/design-lint@8.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Brett Dorrans and Contributors
+
+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/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@lapidist/design-lint-testing",
+  "version": "1.0.0",
+  "description": "Testing utilities and RuleTester for @lapidist/design-lint rule authors.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bylapidist/design-lint.git",
+    "directory": "packages/testing"
+  },
+  "bugs": {
+    "url": "https://github.com/bylapidist/design-lint/issues"
+  },
+  "keywords": [
+    "dtif",
+    "design tokens",
+    "lint",
+    "testing",
+    "rule-tester"
+  ],
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@lapidist/design-lint": ">=8.0.0"
+  },
+  "devDependencies": {
+    "@lapidist/design-lint": "8.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "format:check": "prettier --check 'src/**/*.ts'"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { RuleTester } from './rule-tester.js';
+export type { RuleTesterConfig, RuleTesterTests, ValidCase, InvalidCase, ExpectedError } from './rule-tester.js';
+export { SnippetLinter } from './snippet-linter.js';

package/src/rule-tester.ts

@@ -0,0 +1,192 @@
+import type { LintMessage, RuleModule, DtifFlattenedToken } from '@lapidist/design-lint';
+import assert from 'node:assert/strict';
+import { SnippetLinter } from './snippet-linter.js';
+
+/** A file type accepted by the linter. */
+export type FileType = 'css' | 'ts' | 'tsx' | 'vue' | 'svelte';
+
+/** A valid (no-violation) test case. */
+export interface ValidCase {
+  /** Source code snippet to lint. */
+  code: string;
+  /** The file type to lint as. */
+  fileType: FileType;
+  /** Optional rule-specific options. */
+  options?: unknown;
+  /**
+   * Flattened DTIF tokens to inject into the linter for this case.
+   * Required when testing token-based rules that need a non-empty token set
+   * to exercise real validation (rather than the "configure tokens" message).
+   */
+  tokens?: DtifFlattenedToken[];
+}
+
+/** An expected diagnostic produced by an invalid case. */
+export interface ExpectedError {
+  /** The rule id that produced this diagnostic (e.g. `design-token/colors`). */
+  ruleId?: string;
+  /** Substring that the diagnostic message must contain. */
+  message?: string;
+  /** Expected 1-based source line. */
+  line?: number;
+  /** Expected 1-based source column. */
+  column?: number;
+}
+
+/** An invalid (must-produce-violations) test case. */
+export interface InvalidCase {
+  /** Source code snippet to lint. */
+  code: string;
+  /** The file type to lint as. */
+  fileType: FileType;
+  /** Optional rule-specific options. */
+  options?: unknown;
+  /**
+   * Flattened DTIF tokens to inject into the linter for this case.
+   * Required when testing token-based rules that need a non-empty token set
+   * to exercise real validation (rather than the "configure tokens" message).
+   */
+  tokens?: DtifFlattenedToken[];
+  /** The diagnostics that must be reported — at least one required. */
+  errors: [ExpectedError, ...ExpectedError[]];
+  /** Expected auto-fixed output, if the rule is fixable. */
+  output?: string;
+}
+
+/** Top-level test collection passed to {@link RuleTester.run}. */
+export interface RuleTesterTests {
+  valid: ValidCase[];
+  invalid: InvalidCase[];
+}
+
+/** Construction options for {@link RuleTester}. */
+export interface RuleTesterConfig {
+  /** Default file type to use when a case does not specify one. */
+  defaultFileType?: FileType;
+}
+
+/**
+ * Utility for testing individual `@lapidist/design-lint` rules.
+ *
+ * Mirrors the ESLint `RuleTester` API so rule authors have a familiar
+ * testing surface. Each `invalid` case must produce at least the number of
+ * diagnostics listed in `errors`; each `valid` case must produce none.
+ *
+ * @example
+ * ```ts
+ * const tester = new RuleTester({ defaultFileType: 'css' });
+ * await tester.run('design-token/colors', colorsRule, {
+ *   valid: [{ code: 'a { color: var(--color-brand-primary); }', fileType: 'css' }],
+ *   invalid: [{ code: 'a { color: #3B82F6; }', fileType: 'css', errors: [{ ruleId: 'design-token/colors' }] }],
+ * });
+ * ```
+ */
+export class RuleTester {
+  readonly #config: Required<RuleTesterConfig>;
+
+  constructor(config: RuleTesterConfig = {}) {
+    this.#config = {
+      defaultFileType: config.defaultFileType ?? 'css',
+    };
+  }
+
+  /**
+   * Runs the test suite for a single rule.
+   *
+   * @param {string} ruleName - The rule's canonical name (e.g. `design-token/colors`).
+   * @param {RuleModule} rule - The rule module under test.
+   * @param {RuleTesterTests} tests - Valid and invalid test cases.
+   * @returns {Promise<void>} Resolves when all assertions pass.
+   */
+  async run(
+    ruleName: string,
+    rule: RuleModule,
+    tests: RuleTesterTests,
+  ): Promise<void> {
+    for (const testCase of tests.valid) {
+      const fileType = testCase.fileType ?? this.#config.defaultFileType;
+      const diagnostics = await this.#lint(
+        rule,
+        testCase.code,
+        fileType,
+        testCase.options,
+        testCase.tokens,
+      );
+      assert.equal(
+        diagnostics.length,
+        0,
+        `Rule "${ruleName}" reported unexpected diagnostics for valid case:\n${testCase.code}\n\nDiagnostics:\n${JSON.stringify(diagnostics, null, 2)}`,
+      );
+    }
+
+    for (const testCase of tests.invalid) {
+      const fileType = testCase.fileType ?? this.#config.defaultFileType;
+      const diagnostics = await this.#lint(
+        rule,
+        testCase.code,
+        fileType,
+        testCase.options,
+        testCase.tokens,
+      );
+      assert.ok(
+        diagnostics.length >= testCase.errors.length,
+        `Rule "${ruleName}" expected at least ${String(testCase.errors.length)} diagnostic(s) but got ${String(diagnostics.length)}:\n${testCase.code}`,
+      );
+
+      for (let i = 0; i < testCase.errors.length; i += 1) {
+        const expected = testCase.errors[i];
+        const actual = diagnostics[i];
+        if (expected === undefined || actual === undefined) continue;
+
+        if (expected.ruleId !== undefined) {
+          assert.equal(
+            actual.ruleId,
+            expected.ruleId,
+            `Diagnostic ${String(i)} ruleId mismatch`,
+          );
+        }
+        if (expected.message !== undefined) {
+          assert.ok(
+            actual.message.includes(expected.message),
+            `Diagnostic ${String(i)} message "${actual.message}" does not include "${expected.message}"`,
+          );
+        }
+        if (expected.line !== undefined) {
+          assert.equal(
+            actual.line,
+            expected.line,
+            `Diagnostic ${String(i)} line mismatch`,
+          );
+        }
+        if (expected.column !== undefined) {
+          assert.equal(
+            actual.column,
+            expected.column,
+            `Diagnostic ${String(i)} column mismatch`,
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Runs the linter against a code snippet using a `SnippetLinter` that
+   * injects the rule under test directly, bypassing the rule registry.
+   *
+   * @param {RuleModule} rule - The rule module to test.
+   * @param {string} code - Source code to lint.
+   * @param {FileType} fileType - The file type to lint as.
+   * @param {unknown} options - Rule-specific options.
+   * @returns {Promise<LintMessage[]>} Diagnostics produced by the rule.
+   */
+  async #lint(
+    rule: RuleModule,
+    code: string,
+    fileType: FileType,
+    options?: unknown,
+    tokens?: DtifFlattenedToken[],
+  ): Promise<LintMessage[]> {
+    const linter = new SnippetLinter(rule, options, tokens);
+    return linter.lintSnippet(code, fileType);
+  }
+}

package/src/snippet-linter.ts

@@ -0,0 +1,88 @@
+import { Linter, TokenRegistry } from '@lapidist/design-lint';
+import type {
+  RuleModule,
+  LintMessage,
+  LintDocument,
+  LintResult,
+  DtifFlattenedToken,
+} from '@lapidist/design-lint';
+
+/** Minimal enabled-rule shape (mirrors the internal RuleRegistry return type). */
+interface EnabledRule {
+  rule: RuleModule;
+  options: unknown;
+  severity: 'error' | 'warn';
+}
+
+/** Stub DocumentSource — never actually scanned; only lintDocument is used. */
+const stubSource = {
+  scan: async () => ({ documents: [], ignoreFiles: [] }),
+};
+
+/** No-op TokenProvider — SnippetLinter injects tokens via TokenRegistry directly. */
+const stubTokenProvider = {
+  load: () => Promise.resolve({}),
+};
+
+/**
+ * A stripped-down `Linter` subclass used internally by `RuleTester`.
+ *
+ * Overrides `buildRuleContexts` to inject a single rule under test, bypassing
+ * the `RuleRegistry` entirely. This allows testing rules that are not in the
+ * built-in rule set.
+ *
+ * Optionally accepts a list of {@link DtifFlattenedToken}s to inject into the
+ * token registry, enabling `RuleTester` coverage of token-based rules that
+ * need a non-empty token set to exercise their real validation logic (rather
+ * than the "configure tokens" early-exit path).
+ */
+export class SnippetLinter extends Linter {
+  readonly #injected: EnabledRule;
+
+  constructor(
+    rule: RuleModule,
+    options: unknown = undefined,
+    tokens: DtifFlattenedToken[] = [],
+  ) {
+    super({ rules: {} }, { documentSource: stubSource, tokenProvider: stubTokenProvider });
+    this.#injected = { rule, options, severity: 'error' };
+    if (tokens.length > 0) {
+      // The base class's tokensReady promise resolves by setting this.tokenRegistry
+      // from the (empty) config tokens. We chain an additional .then() here so
+      // our injected registry is applied AFTER the base-class resolution, winning
+      // the assignment race.
+      const registry = new TokenRegistry({ default: tokens });
+      this.tokensReady = this.tokensReady.then(() => {
+        this.tokenRegistry = registry;
+      });
+    }
+  }
+
+  /**
+   * Overrides the base `buildRuleContexts` to always use the injected rule
+   * instead of whatever the registry resolves.
+   */
+  protected override buildRuleContexts(
+    _enabled: EnabledRule[],
+    sourceId: string,
+    metadata?: Record<string, unknown>,
+  ): ReturnType<Linter['buildRuleContexts']> {
+    return super.buildRuleContexts([this.#injected], sourceId, metadata);
+  }
+
+  /**
+   * Lints a code snippet and returns the diagnostics produced by the injected rule.
+   *
+   * @param code - Source code to lint.
+   * @param ext - File extension used to select the correct parser (e.g. `"css"`, `"tsx"`).
+   */
+  async lintSnippet(code: string, ext: string): Promise<LintMessage[]> {
+    const doc: LintDocument = {
+      id: `snippet.${ext}`,
+      type: ext,
+      getText: async () => code,
+    };
+    const result: LintResult = await this.lintDocument(doc);
+    return result.messages;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}