pasika 0.3.2 → 0.3.3

package/README.md

@@ -42,7 +42,7 @@ Requirements are identified by a hash of their canonical text, not by a hand-wri
 }
 ```
 
-The `note` field is where a check's known gap is recorded, so a partial check never reads as a complete one.
+The `text` field is the bullet as written in the document (markdown links and code spans intact), so it is greppable in the doc it came from; the `hash` is computed from the same text with links collapsed to their text and code spans unwrapped, so editing a URL or adding backticks does not read as a change. The `note` field is where a check's known gap is recorded, so a partial check never reads as a complete one.
 
 | Kind | Meaning |
 | --- | --- |
@@ -92,6 +92,8 @@ const { eslintConfig } = styleguide({
 export default eslintConfig;
 ```
 
+`zirka` composes the full pasika ruleset over four file scopes: TS/TSX under `src/**`, `globals.css` and other stylesheets, `package.json`, and markdown — each with its own ESLint language.
+
 ### Without Zirka
 
 ```ts
@@ -101,7 +103,9 @@ import { pasikaConfig } from "pasika/eslint";
 export default [pasikaConfig];
 ```
 
-The ruleset applies to `src/**` only, so a repository without a `src/` tree passes it trivially.
+`pasikaConfig` applies the TS/TSX rules to `src/**` only, so a repository without a `src/` tree passes it trivially. The CSS, JSON, and markdown language configs are composed by `zirka`'s `styleguide()`; the individual rule objects (`cssRules`, `jsonRules`, `mdRules`) are exported for manual wiring.
+
+### TS/TSX rules
 
 | Rule | Enforces |
 | --- | --- |
@@ -111,24 +115,76 @@ The ruleset applies to `src/**` only, so a repository without a `src/` tree pass
 | `pasika/no-arbitrary-tailwind` | No arbitrary `-[value]` classes, including inside `cn()` conditionals |
 | `pasika/enforce-cn-merge` | `cn()` instead of `+` or template literals; at most five classes per group |
 | `pasika/enforce-cva-variant-props` | `VariantProps<typeof …>` instead of hand-written unions |
+| `pasika/cva-appearance-props` | Visual option props (`size`, `variant`, …) declared through CVA appearance props |
+| `pasika/cva-boolean-variants` | Boolean appearance props placed on the CVA variant, not as standalone props |
 | `pasika/enforce-barrel-exports` | A nested `index.ts` re-exports only its component |
 | `pasika/component-placement` † | The folder a component's consumers imply |
 | `pasika/support-file-placement` † | The folder a hook, type, schema, constant, or utility belongs in |
+| `pasika/application-structure` | The path-based parts of the application structure and configuration rules |
+| `pasika/named-exports` | Named exports for application files (framework routing files may default-export) |
+| `pasika/data-testid-case` | `data-testid` casing where a rendered result carries one |
+| `pasika/support-folder-shape` | A `constants/`, `types/`, or `schemas/` folder defines exports directly in `index.ts` or in named-re-exported files |
+| `pasika/import-through-index` | An extracted constant, type, or schema is imported through its folder's `index.ts` |
+| `pasika/util-file-name` | A single-function utility file is named in the function's kebab-case form |
+| `pasika/no-util-barrel` | A utility is imported directly, without a barrel |
+| `pasika/jsx-hygiene` | Calculations and complex conditions stay out of JSX children and attributes |
+| `pasika/interactive-component` | Interactive elements are component boundaries when mixed with other content |
+| `pasika/ui-state` | Native or ARIA state expression and Tailwind state variants |
+| `pasika/cross-feature-import` | A component importing from two or more feature folders lives in a shared location |
+| `pasika/pure-function-extract` | Pure functions extracted to `utils/`, even with one consumer |
+| `pasika/hook-complexity` | Hook complexity limits (imperative categories per hook) |
+| `pasika/locale-dotted-path` | A namespaced locale is read through its full dotted path |
+| `pasika/locales-location` | Locales live in the named locales object |
+| `pasika/hook-extraction` † | A hook with two or more consumers is extracted to its own file |
+| `pasika/value-extraction` † | A value with cross-folder consumers is extracted |
+| `pasika/config-extraction` † | A type, schema, or utility used outside its config module is moved |
+| `pasika/component-nesting` † | A component is not nested solely because it has support files |
+| `pasika/stay-flat` † | A component stays flat until it has exclusive children |
+| `pasika/type-extraction` † | A type or schema with cross-folder consumers is extracted |
+| `pasika/locale-placement` † | Shared locales at the top level, single-feature locales namespaced |
+| `pasika/shared-style-dedup` † | A className combo used by two or more components becomes a named utility |
+| `pasika/no-eslint-disable` | No `eslint-disable` directives |
+
+### CSS rules
+
+Applied to `src/**/globals.css` (and other stylesheets) through `@eslint/css` with tolerant Tailwind v4 parsing.
+
+| Rule | Enforces |
+| --- | --- |
+| `pasika/theme-reset` | A `--*: initial` theme reset is present |
+| `pasika/root-variables` | `:root` defines the CSS custom properties |
+| `pasika/apply-usage` | `@layer base` uses `@apply` for declarations |
+| `pasika/base-layer-pair` | The base layer applies `base-canvas` and `base-ink` |
+| `pasika/stylesheet-ordering` | Imports → `@custom-variant` → `:root` → `@theme` → `@utility` → `@layer base` |
+| `pasika/css-variable-naming` | Background vars named `--<role>-canvas`, text vars `--<role>-ink` |
+| `pasika/custom-utility-apply` | `@utility` blocks use `@apply` |
+| `pasika/surface-utility` | Repeated canvas+ink combos become a named surface utility |
+| `pasika/theme-variable-namespace` | Utility class groups share a namespace prefix |
+| `pasika/global-css-location` | Global CSS lives in the correct entry point |
+
+### JSON rules
+
+Applied to `package.json` through `@eslint/json`.
+
+| Rule | Enforces |
+| --- | --- |
+| `pasika/no-cache-flag` | Lint scripts don't pass `--cache` |
+| `pasika/no-vulyk-dependency` | `vulyk` is not in `dependencies` |
 
 ### Documentation rules
 
-The `pasika/*` markdown rules enforce the documentation guide over `docs/**/*.md`: file-name suffixes and titles, overview presence and length, guide step structure, Incorrect/Correct pairing, policy document shape, reference block headings, RFC 2119 placement, and template hygiene. They run through `@eslint/markdown` in `eslint.config.ts`; `pasika coverage` verifies each has a test and a registry entry.
+The `pasika/*` markdown rules enforce the documentation guide over `docs/**/*.md` (24 rules): file-name suffixes and titles, overview presence and length, guide step structure, Incorrect/Correct pairing, policy document shape, reference block headings, RFC 2119 placement, template hygiene, link anchoring, and glossary-term linking. They run through `@eslint/markdown`; `pasika coverage` verifies each has a test and a registry entry. Pasika's own `docs/` are linted by them in CI (`npm run docs`).
 
 Run `pasika coverage --json` for the exact requirement each rule covers.
 
 ### † Cross-file rules
 
-Where a component or support file belongs depends on which files import it, so these two rules index the whole `src/` tree instead of looking at one file. Two consequences:
+Where a component, hook, value, type, or style belongs depends on which files use it, so the rules marked † index the whole `src/` tree instead of looking at one file. Two consequences:
 
 - **Do not pass `--cache`.** Move a file and the finding belongs to a *different* file, whose cache entry is unchanged — so ESLint would replay a stale verdict. `agent-policy.md` requires lint commands to run without it.
 - The index is read from disk rather than from ESLint's file list, so a partial run such as `lint-staged` still judges against the true graph.
 
-Both are inert in a repository with no `src/` tree.
+All are inert in a repository with no `src/` tree.
 
 ## Development
 

package/dist/cli/index.js

@@ -64,7 +64,7 @@ program
                 registry: readRegistry(registryPath),
                 input: { hash: options.classify, kind: kind.data, ref: options.ref, note: options.note },
             });
-            writeRegistry(registryPath, result.registry);
+            writeRegistry(registryPath, result.registry, docsRoot);
             const change = result.previousKind === undefined
                 ? `recorded as ${result.requirement.kind}`
                 : `reclassified from ${result.previousKind} to ${result.requirement.kind}`;
@@ -98,7 +98,7 @@ program
         `  unclassified ${String(report.issues.filter((issue) => issue.kind === "new").length)}`,
     ].join("\n"));
     if (options.accept) {
-        writeRegistry(registryPath, report.nextRegistry);
+        writeRegistry(registryPath, report.nextRegistry, docsRoot);
         const accepted = report.issues.filter((issue) => issue.kind === "changed" || issue.kind === "removed");
         log(`\nAccepted ${String(accepted.length)} change(s) into ${REGISTRY_RELATIVE_PATH}.`);
         log("Requirements reported as new still need a classification.");

package/dist/enforcement/coverage.d.ts

@@ -48,4 +48,8 @@ export declare function classifyRequirement(options: {
     input: ClassifyInput;
 }): ClassifyResult;
 export declare function readRegistry(registryPath: string): Registry;
-export declare function writeRegistry(registryPath: string, registry: Registry): void;
+/**
+ * Writes the registry sorted in the same order the requirements appear in the
+ * docs: document order, then line order within each document.
+ */
+export declare function writeRegistry(registryPath: string, registry: Registry, docsRoot: string): void;

package/dist/enforcement/coverage.js

@@ -2,6 +2,7 @@ import { readdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { allPasikaRuleIds } from "../eslint/pasika/index.js";
+import { normalizeRequirement } from "./normalize.js";
 import { parseDocs } from "./parse-docs.js";
 import { MECHANICAL_KINDS, registrySchema } from "./types.js";
 /** Ratio of shared words, used only to guess which stored requirement a reworded bullet came from. */
@@ -70,13 +71,13 @@ export function buildCoverageReport(options) {
         if (recorded) {
             matched.add(requirement.hash);
             counts[recorded.kind] += 1;
-            nextRequirements.push({ ...recorded, doc });
+            nextRequirements.push({ ...recorded, doc, text: requirement.raw });
             if (!isRefKnown(recorded)) {
                 issues.push({
                     kind: "unknown-ref",
                     doc,
                     line: requirement.line,
-                    text: requirement.text,
+                    text: requirement.raw,
                     detail: `${recorded.kind} ref "${recorded.ref ?? "(none)"}" does not exist`,
                 });
             }
@@ -85,7 +86,7 @@ export function buildCoverageReport(options) {
                     kind: "missing-test",
                     doc,
                     line: requirement.line,
-                    text: requirement.text,
+                    text: requirement.raw,
                     detail: `no rule test is titled with this requirement`,
                 });
             }
@@ -94,24 +95,24 @@ export function buildCoverageReport(options) {
         // Not recorded under this hash: either a reworded requirement or a new one.
         const candidate = registry.requirements
             .filter((entry) => entry.doc === doc && !matched.has(entry.hash))
-            .map((entry) => ({ entry, score: similarity(entry.text, requirement.text) }))
+            .map((entry) => ({ entry, score: similarity(normalizeRequirement(entry.text), requirement.text) }))
             .sort((left, right) => right.score - left.score)
             .find(({ score }) => score >= 0.5);
         if (candidate) {
             matched.add(candidate.entry.hash);
             counts[candidate.entry.kind] += 1;
-            nextRequirements.push({ ...candidate.entry, doc, text: requirement.text, hash: requirement.hash });
+            nextRequirements.push({ ...candidate.entry, doc, text: requirement.raw, hash: requirement.hash });
             issues.push({
                 kind: "changed",
                 doc,
                 line: requirement.line,
-                text: requirement.text,
+                text: requirement.raw,
                 hash: requirement.hash,
                 detail: `was "${candidate.entry.text}" — re-verify ${candidate.entry.kind}${candidate.entry.ref ? ` ${candidate.entry.ref}` : ""}`,
             });
         }
         else {
-            issues.push({ kind: "new", doc, line: requirement.line, text: requirement.text, hash: requirement.hash });
+            issues.push({ kind: "new", doc, line: requirement.line, text: requirement.raw, hash: requirement.hash });
         }
     }
     for (const entry of registry.requirements) {
@@ -169,7 +170,7 @@ export function classifyRequirement(options) {
     }
     const requirement = {
         doc: match.doc,
-        text: match.requirement.text,
+        text: match.requirement.raw,
         hash: match.requirement.hash,
         kind: input.kind,
         ...(refs.length > 0 ? { ref: refs.join(", ") } : {}),
@@ -188,6 +189,22 @@ export function readRegistry(registryPath) {
     }
     return result.data;
 }
+/**
+ * Sequence position of each requirement in the docs: doc order as `parseDocs`
+ * yields it, then line order within each doc. Entries whose hash no longer
+ * exists in the docs (removed, not yet accepted) sort after everything parsed.
+ */
+function buildDocOrder(docsRoot) {
+    const order = new Map();
+    let position = 0;
+    for (const doc of parseDocs(docsRoot)) {
+        for (const requirement of doc.requirements) {
+            order.set(requirement.hash, position);
+            position += 1;
+        }
+    }
+    return order;
+}
 /**
  * Code-point order on doc then text. Deliberately not `localeCompare`, whose
  * result depends on the host's locale data — a generated file that is committed
@@ -200,7 +217,23 @@ function compareRequirements(left, right) {
         return left.text < right.text ? -1 : 1;
     return 0;
 }
-export function writeRegistry(registryPath, registry) {
-    const sorted = { requirements: [...registry.requirements].sort(compareRequirements) };
+/**
+ * Writes the registry sorted in the same order the requirements appear in the
+ * docs: document order, then line order within each document.
+ */
+export function writeRegistry(registryPath, registry, docsRoot) {
+    const order = buildDocOrder(docsRoot);
+    const withPosition = registry.requirements.map((requirement) => ({
+        requirement,
+        position: order.get(requirement.hash) ?? Number.MAX_SAFE_INTEGER,
+    }));
+    withPosition.sort((left, right) => {
+        if (left.position !== right.position)
+            return left.position - right.position;
+        // Two entries with the same hash cannot coexist; this fallback orders
+        // entries whose hash the docs no longer contain, deterministically.
+        return compareRequirements(left.requirement, right.requirement);
+    });
+    const sorted = { requirements: withPosition.map((entry) => entry.requirement) };
     writeFileSync(registryPath, `${JSON.stringify(sorted, null, 2)}\n`);
 }

package/dist/enforcement/parse-docs.js

@@ -40,6 +40,7 @@ function findDocLinks(line) {
 }
 export function parseDoc(filePath, docsRoot) {
     const body = readFileSync(filePath, "utf8");
+    const sourceLines = body.split("\n");
     const prose = toProse(body, "$<content>");
     const proseWithoutCode = toProse(body, "");
     const fileName = path.basename(filePath);
@@ -56,7 +57,10 @@ export function parseDoc(filePath, docsRoot) {
         }
         if (/^\s*[-*]\s/.test(line) && RFC_2119.test(line)) {
             const text = normalizeRequirement(line);
-            requirements.push({ text, hash: hashRequirement(text), raw: line.replace(/^\s*[-*]\s+/, ""), line: lineNumber });
+            // The raw bullet as written in the source file (code spans and links intact),
+            // so a registry entry's text is greppable in the doc it came from.
+            const raw = (sourceLines[index] ?? "").replace(/^\s*[-*]\s+/, "");
+            requirements.push({ text, hash: hashRequirement(text), raw, line: lineNumber });
         }
         if (/^\s*\d+\.\s/.test(line)) {
             steps.push({ line: lineNumber, text: line.replace(/^\s*\d+\.\s+/, ""), links: findDocLinks(line) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pasika",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Reusable agent setup package",
   "repository": {
     "type": "git",
@@ -19,13 +19,12 @@
     "pasika": "dist/cli/index.js"
   },
   "files": [
-    "dist",
-    "enforcement/registry.json"
+    "dist"
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "coverage": "tsx cli/index.ts coverage",
-    "docs": "eslint docs --config eslint.docs.config.ts",
+    "docs": "eslint docs",
     "fix": "eslint . --fix",
     "lint": "eslint .",
     "prepack": "npm run build",
@@ -52,7 +51,7 @@
     "prettier": "^3.8.1",
     "tsx": "^4.23.12",
     "typescript": "^5.9.2",
-    "zirka": "^0.0.39"
+    "zirka": "^0.0.42"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"