chore: linting and agents file. (#55)

Author: knightedcodemonkey

.oxlintrc.json

@@ -1,6 +1,15 @@
 {
   "$schema": "https://json.schemastore.org/oxlintrc",
-  "plugins": ["typescript", "unicorn", "oxc", "react", "node", "import", "vitest"],
+  "plugins": [
+    "eslint",
+    "typescript",
+    "unicorn",
+    "oxc",
+    "react",
+    "node",
+    "import",
+    "vitest"
+  ],
   "env": {
     "es2022": true,
     "node": true
@@ -9,6 +18,9 @@
     "process": "readonly"
   },
   "rules": {
+    "no-shadow": "off",
+    "@typescript-eslint/no-shadow": "error",
+    "@typescript-eslint/no-explicit-any": "error",
     "unicorn/filename-case": [
       "error",
       {

AGENTS.md

@@ -0,0 +1,104 @@
+---
+name: knighted-css-agent
+description: Specialist coding agent for @knighted/css (TypeScript, Node, Lightning CSS).
+---
+
+You are a specialist engineer for the @knighted/css monorepo. Focus on the core package and its tests, keep changes minimal, and validate with the listed commands.
+
+## Commands (run early and often)
+
+Repo root commands:
+
+- Install: `npm install`
+- Build: `npm run build`
+- Lint: `npm run lint`
+- Format check: `npm run prettier:check`
+- Format write: `npm run prettier`
+- Typecheck: `npm run check-types`
+- Unit tests: `npm run test`
+- E2E tests: `npm run test:e2e`
+
+Workspace-scoped (preferred when changing @knighted/css only):
+
+- Build: `npm run build -w @knighted/css`
+- Typecheck: `npm run check-types -w @knighted/css`
+- Tests: `npm run test -w @knighted/css`
+
+## Project knowledge
+
+**Tech stack**
+
+- Node.js >= 22.21.1, npm >= 10.9.0
+- TypeScript 5.9 (strict, ESM, NodeNext resolution)
+- lightningcss for CSS transforms
+- oxc-resolver and get-tsconfig for module resolution
+- tsx + c8 for unit tests
+- Playwright for end-to-end coverage
+
+**Repository structure**
+
+- packages/css/src — core library (graph walking, compilation, loader helpers)
+- packages/css/test — unit tests
+- packages/css/docs — package docs and deep dives
+- packages/playwright — E2E demo + regression suite
+- docs — root-level documentation
+
+## Code style and conventions
+
+- TypeScript strict is enabled; prefer precise types and `unknown` over `any`.
+- Avoid TypeScript assertions by providing type predicates.
+- Rely on TypeScript inference over explicit typing as much as possible.
+- ESM only (`type: module`).
+- Prettier: single quotes, no semicolons, `printWidth: 90`, `arrowParens: avoid`.
+- Keep functions small and side-effect aware; prefer pure helpers where possible.
+
+### Example style (good)
+
+```ts
+type SelectorNode = { type: string; value?: string }
+
+function toClassSelectors(nodes: SelectorNode[]): SelectorNode[] {
+  return nodes.filter(node => node.type === 'class')
+}
+```
+
+### Example style (avoid)
+
+```ts
+// vague types, implicit any, and unclear intent
+function f(x) {
+  return x
+}
+```
+
+## Testing expectations
+
+- Update or add tests under packages/css/test when modifying behavior.
+- For loader/runtime changes, consider adding or updating Playwright coverage under packages/playwright.
+- Run typecheck after TypeScript edits.
+
+## Git workflow
+
+- Keep changes focused to the smallest surface area.
+- Update tests alongside logic changes.
+- Don’t reformat unrelated files.
+
+## Boundaries
+
+**Always:**
+
+- Follow the commands above to validate changes.
+- Maintain ESM + strict TypeScript compatibility.
+- Keep changes localized to the affected workspace.
+
+**Ask first:**
+
+- Adding or upgrading dependencies.
+- Modifying CI workflows, build scripts, or publishing configuration.
+- Changing public API surface or documented behavior.
+
+**Never:**
+
+- Commit secrets or credentials.
+- Edit generated artifacts (packages/css/dist, packages/css/stable, packages/css/types-stub, coverage, test-results).
+- Modify node_modules or lockfiles unless explicitly requested.

package-lock.json

@@ -47,7 +47,7 @@
     "less": "^4.2.0",
     "lint-staged": "^16.2.7",
     "madge": "^8.0.0",
-    "oxlint": "^1.35.0",
+    "oxlint": "^1.39.0",
     "prettier": "^3.7.4",
     "sass": "^1.80.7",
     "tsx": "^4.19.2",

package.json

@@ -1,8 +1,14 @@
 import { type TransformOptions as LightningTransformOptions } from 'lightningcss'
 
+import type {
+  LightningStyleRule,
+  LightningStyleRuleReturn,
+  LightningVisitor,
+} from './types.js'
+
 export type SpecificitySelector = string | RegExp
 
-export type LightningVisitor = LightningTransformOptions<Record<string, never>>['visitor']
+export type { LightningVisitor }
 
 export type SpecificityStrategy =
   | { type: 'append-where'; token: string }
@@ -27,10 +33,16 @@ export function buildSpecificityVisitor(boost?: {
     const times = Math.max(1, boost.strategy.times ?? 1)
     const visitor: LightningVisitor = {
       Rule: {
-        style(rule: any) {
-          if (!rule || !Array.isArray(rule.selectors)) return rule
-          const newSelectors = rule.selectors.map((sel: any) => {
-            const selectorStr = serializeSelector(sel)
+        style(rule: LightningStyleRule): LightningStyleRuleReturn {
+          const candidate = rule as { selectors?: unknown } | null | undefined
+          if (!candidate || !Array.isArray(candidate.selectors)) {
+            return rule as LightningStyleRuleReturn
+          }
+          const newSelectors = candidate.selectors.map((sel: unknown) => {
+            if (!Array.isArray(sel)) return sel
+            const selectorStr = serializeSelector(
+              sel as Parameters<typeof serializeSelector>[0],
+            )
             if (!shouldApply(selectorStr)) return sel
             const lastClassName = findLastClassName(selectorStr)
             if (!lastClassName) return sel
@@ -40,7 +52,10 @@ export function buildSpecificityVisitor(boost?: {
             }))
             return [...sel, ...repeats]
           })
-          return { ...rule, selectors: newSelectors }
+          return {
+            ...candidate,
+            selectors: newSelectors,
+          } as unknown as LightningStyleRuleReturn
         },
       },
     }
@@ -51,10 +66,16 @@ export function buildSpecificityVisitor(boost?: {
     const token = boost.strategy.token
     const visitor: LightningTransformOptions<never>['visitor'] = {
       Rule: {
-        style(rule: any) {
-          if (!rule || !Array.isArray(rule.selectors)) return rule
-          const newSelectors = rule.selectors.map((sel: any) => {
-            const selectorStr = serializeSelector(sel)
+        style(rule: LightningStyleRule): LightningStyleRuleReturn {
+          const candidate = rule as { selectors?: unknown } | null | undefined
+          if (!candidate || !Array.isArray(candidate.selectors)) {
+            return rule as LightningStyleRuleReturn
+          }
+          const newSelectors = candidate.selectors.map((sel: unknown) => {
+            if (!Array.isArray(sel)) return sel
+            const selectorStr = serializeSelector(
+              sel as Parameters<typeof serializeSelector>[0],
+            )
             if (!shouldApply(selectorStr)) return sel
             return [
               ...sel,
@@ -65,7 +86,10 @@ export function buildSpecificityVisitor(boost?: {
               },
             ]
           })
-          return { ...rule, selectors: newSelectors }
+          return {
+            ...candidate,
+            selectors: newSelectors,
+          } as unknown as LightningStyleRuleReturn
         },
       },
     }

packages/css/src/helpers.ts

@@ -625,7 +625,7 @@ function loadTsconfigPaths(
     if (cached !== undefined) {
       return cached ?? undefined
     }
-    const result = getTsconfig(target, undefined, tsconfigFsCache as Map<string, any>)
+    const result = getTsconfig(target, undefined, tsconfigFsCache as Map<string, unknown>)
     if (!result) {
       tsconfigResultCache.set(target, null)
       return undefined