diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2cc8b60..2a8dc52 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -34,6 +34,8 @@ jobs: path: npm-debug.log - name: Lint run: npm run lint + - name: Check Cycles + run: npm run check:cycles - name: Test run: npm test - name: Report Coverage diff --git a/.oxlintrc.json b/.oxlintrc.json index 8c65b99..e94279c 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -1,11 +1,91 @@ { "$schema": "https://json.schemastore.org/oxlintrc", - "plugins": ["typescript", "unicorn", "oxc"], + "plugins": ["typescript", "unicorn", "oxc", "react", "node", "import", "vitest"], "env": { "es2022": true, "node": true }, "globals": { "process": "readonly" - } + }, + "rules": { + "unicorn/filename-case": [ + "error", + { + "cases": { + "camelCase": true, + "kebabCase": true, + "pascalCase": true + } + } + ] + }, + "overrides": [ + { + "files": ["**/packages/css/types.d.ts"], + "rules": { + "@typescript-eslint/triple-slash-reference": "off" + } + }, + { + "files": ["packages/css/src/**/*.{ts,tsx,js,jsx}", "packages/css/src/**/*.d.ts"], + "rules": { + "unicorn/filename-case": [ + "error", + { + "cases": { "camelCase": true } + } + ] + } + }, + { + "files": ["packages/css/scripts/**/*.js"], + "rules": { + "unicorn/filename-case": [ + "error", + { + "cases": { "kebabCase": true } + } + ] + } + }, + { + "files": ["packages/css/test/**/*.ts"], + "rules": { + "unicorn/filename-case": [ + "error", + { + "cases": { "camelCase": true } + } + ] + } + }, + { + "files": [ + "packages/css/dist/**", + "packages/css/types-stub/**", + "packages/css/stable/**", + "packages/css/coverage/**" + ], + "rules": { + "unicorn/filename-case": "off" + } + }, + { + "files": ["packages/css/src/loader-helpers.ts", "packages/css/src/types-stub/**"], + "rules": { + "unicorn/filename-case": "off" + } + }, + { + "files": [ + "packages/css/test/__snapshots__/**", + "packages/css/test/fixtures/**", + "packages/css/test/helpers/**" + ], + "rules": { + "unicorn/filename-case": "off" + } + } + ] } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f986020 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,41 @@ +# Contributing to @knighted/css + +Thanks for spending time on the Knighted CSS suite! This document highlights the conventions that are hardest to infer from the codebase so you can ship fixes without guesswork. + +## Local setup + +1. Use Node 22+ and npm (the repo scripts assume npm). +2. Install dependencies from the repo root: `npm install`. +3. Run lint and tests before sending a PR: + - `npm run lint` (oxlint across every package) + - `npm test` (delegates to each package's test runner) + +## File naming policy + +We enforce naming gradually with `unicorn/filename-case` so existing camelCase modules keep working while new code stays consistent. + +- **New files**: default to kebab-case (e.g., `module-info.ts`). PascalCase is reserved for files that export React-style components or top-level docs such as `README.md`. +- **Legacy folders**: some directories (especially `packages/css/src/**`) still contain camelCase files. They remain whitelisted in `.oxlintrc.json`. When you touch one of those files, feel free to rename it to kebab-case in a dedicated commit and then tighten the ignore glob. +- **Special cases**: directories such as `__snapshots__` and `.husky/_` intentionally keep underscores—leave those alone. + +## Type stub directories + +The CSS package ships two `types-stub` directories on purpose: + +- `packages/css/src/types-stub/` is the source stub checked into git. The entire repo references this file during development so editors and TypeScript builds succeed before generated selectors exist. +- `packages/css/types-stub/` is a build artifact copied by `packages/css/scripts/copy-types-stub.js` during `npm run build`. It **must** stay in git because npm publishes from `packages/css/` directly; removing it would strip the placeholder declarations that consumers need on fresh installs. + +When editing the stub, always update the version under `src/types-stub/` and let the copy script mirror it. + +## Type entrypoint strategy + +`packages/css/types.d.ts` currently uses triple-slash references to pull in `loader-queries.d.ts` and the stub above. This is intentional for the entire 1.x line so downstream TypeScript consumers enjoy stable behavior. We silence the `typescript-eslint/triple-slash-reference` warning via `.oxlintrc.json`. When we design 2.0.0 we will switch to ESM-style imports and remove that override—please keep that in mind if you are touching the type entrypoint. + +## Pull request checklist + +- Follow the naming rules above for any new files. +- Confirm `npm run lint` emits zero warnings. +- Describe any behavioral changes in the relevant package README or docs (e.g., `docs/combined-queries.md`). +- If you touch the type stub or generator, call it out explicitly in the PR so we can double-check publish artifacts. + +Happy hacking! diff --git a/README.md b/README.md index 3f51f87..1cd5392 100644 --- a/README.md +++ b/README.md @@ -17,10 +17,10 @@ See the [docs/](./docs) directory for deep dives on loaders, type generation, sp ## Workspaces in this repo -| Workspace | NPM Name | What it contains | -| --------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `packages/css` | [`@knighted/css`](https://www.npmjs.com/package/@knighted/css) | The production library: graph walker, compilation pipeline, loader helpers, CLI, and docs. Published to npm and meant for real builds. | -| `packages/playwright` | `@knighted/css-playwright-fixture` | The end-to-end demo + regression suite. Playwright drives Lit + React examples, hash-import workspace scenarios, and SSR checks to ensure the core package keeps working across bundlers. | +| Workspace | NPM Name | What it contains | +| --------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `packages/css` | [`@knighted/css`](./packages/css/README.md) | The production library: graph walker, compilation pipeline, loader helpers, CLI, and docs. Published to npm and meant for real builds. | +| `packages/playwright` | [`@knighted/css-playwright-fixture`](./packages/playwright/README.md) | The end-to-end demo + regression suite. Playwright drives Lit + React examples, hash-import workspace scenarios, and SSR checks to ensure the core package keeps working across bundlers. | Each workspace is a standalone npm project. Run commands from the repo root with `npm run