pasika 0.3.8 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # pasika
 
-Documentation, the lint rules derived from it, and the CLI that applies and diagnoses both.
+Documentation, the lint rules derived from it, and the checks that apply and diagnose both.
 
 `pasika` owns the framework's documentation and turns it into checks. Every requirement in `docs/` is recorded in an enforcement registry that says which ESLint rule or `pasika` check governs it — or, when none does, how a reviewer or agent applies it by hand. CI fails when a requirement has no recorded answer.
 
@@ -8,20 +8,24 @@ Documentation, the lint rules derived from it, and the CLI that applies and diag
 
 ```text
 docs/
-  repository-policy.md                 # agent-conduct requirements (Policy)
   repository-policy.md            # repo-wide code and documentation requirements (Policy)
   code-organization-guide/        # placement, extraction, module conventions
   documentation-guide/            # how documents themselves are written
   framework-adoption-guide/       # adopting and updating the framework
   styling-guide/                  # Tailwind theme, composition, variants, states
-enforcement/
+scripts/
   registry.json                   # requirement → enforcement, keyed by content hash
   coverage.ts                     # reconciles the docs against the registry
+  utils/                          # doc parsing, classification, registry IO
+  types/                          # registry schema
+constants/
+  rfc2119.ts                      # single source of truth for RFC 2119 vocabulary
 eslint/
-  pasika/rules/                   # the lint rules, with fixture tests beside them
-  pasika/rules/md/                # the documentation-guide rules, linting docs/ itself
-cli/
-  index.ts                        # the `pasika` command
+  rules/                          # the lint rules, with fixture tests beside them
+  rules/documentation/            # the documentation-guide rules, linting docs/ itself
+  rules/tailwind/                 # the Tailwind stylesheet rules
+  rules/package-json/             # the package.json rules
+  rules/husky/                    # the husky-hook rules
 ```
 
 ## Documentation
@@ -44,60 +48,71 @@ Requirements are identified by a hash of their canonical text, not by a hand-wri
 
 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.
 
-Every requirement carries a `note` explaining how it is met: what the ref'd rule or doctor check does and where it falls short, or — with no `ref` — how a reviewer or agent applies it by hand. When a rule governs the requirement's subject without fully deciding it (e.g. its placement), the `ref` still names that rule and the `note` says what stays judgment, so a partial check never reads as a complete one.
+Every requirement carries a `note` explaining how it is met: what the ref'd rule does and where it falls short, or — with no `ref` — how a reviewer or agent applies it by hand. When a rule governs the requirement's subject without fully deciding it (e.g. its placement), the `ref` still names that rule and the `note` says what stays judgment, so a partial check never reads as a complete one.
 
-`pasika coverage` fails when a requirement has no recorded answer, when its text changed, when it disappeared, when its `ref` names a rule or doctor check that does not exist, or when a requirement a rule governs has no test titled with its text. Confirm a reworded requirement with `pasika coverage --accept`.
+`npm run coverage` fails when a requirement has no recorded answer, when its text changed, when it disappeared, when its `ref` names a rule that does not exist, or when a requirement a rule governs has no test titled with its text. Confirm a reworded requirement with `npx tsx scripts/coverage.ts --accept`.
 
 ## Commands
 
 The documentation guide itself is linted: the `pasika/*` markdown rules run over `docs/**/*.md` and report title, overview, structure, example-pairing, and RFC 2119 violations at the exact node.
 
+The coverage checks are standalone scripts under `scripts/`, run with `tsx`; the drift check is the published `libyear` tool — there is no `pasika` binary:
+
 ```bash
-npx pasika coverage            # check that every requirement has recorded enforcement
-npx pasika coverage --accept   # record reworded and removed requirements
+npm run coverage             # check that every requirement has recorded enforcement
+npm run coverage -- --accept # record reworded and removed requirements
+npx libyear --limit-major-individual=1   # fail when a dependency trails the latest by >1 major (drift check)
 ```
 
-Both accept `--json` for agent use.
+Both acceptance and the report accept `--json` for agent use:
+
+```bash
+npx tsx scripts/coverage.ts            # text report
+npx tsx scripts/coverage.ts --json     # full report as JSON
+npx tsx scripts/coverage.ts --accept   # record accepted changes
+```
 
-A requirement `coverage` reports as `new` is classified with the hash it prints:
+A requirement the report shows as `new` is classified with the hash it prints:
 
 ```bash
-npx pasika coverage --classify d311a1457a --ref pasika/import-boundaries --note "reports imports that cross a feature boundary"
-npx pasika coverage --classify 041b665bd7 --note "no check can compare against the previous state"
+npx tsx scripts/coverage.ts --classify d311a1457a --ref pasika/import-boundaries --note "reports imports that cross a feature boundary"
+npx tsx scripts/coverage.ts --classify 041b665bd7 --note "no check can compare against the previous state"
 ```
 
-The command refuses a hash no requirement has, a `ref` naming a rule or doctor check that does not exist, and an entry without a note — so a mismatch cannot reach the registry by hand. Re-running it on an already-recorded requirement replaces the earlier entry.
+The script refuses a hash no requirement has, a `ref` naming a rule that does not exist, and a classification without a note — so a mismatch cannot reach the registry by hand. Re-running it on an already-recorded requirement replaces the earlier entry. All of it reads and writes `scripts/registry.json`.
 
 ## ESLint ruleset
 
 ### With Zirka (recommended)
 
 ```ts
-// eslint.config.ts
+// eslint.config.ts — Next.js application
 import { RuleSeverity, styleguide } from "zirka";
 
 const { eslintConfig } = styleguide({
   next: RuleSeverity.Error,
   node: RuleSeverity.Error,
   typescript: RuleSeverity.Error,
-  pasika: RuleSeverity.Error,
+  pasikaNextjsApp: RuleSeverity.Error,
 });
 
 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.
+For a plain TypeScript repository, enable `pasikaTypescriptApp` instead of `pasikaNextjsApp`. `zirka` composes the 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
-// eslint.config.ts
-import { pasikaConfig } from "pasika/eslint";
+// eslint.config.ts — plain TypeScript repository
+import { typescriptApp } from "pasika/eslint";
 
-export default [pasikaConfig];
+export default typescriptApp;
 ```
 
-`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.
+`typescriptApp` is the plain-TypeScript-repository preset — the package.json manifest, the zirka configuration contract, the `src/**` TypeScript app source, and the docs. `nextjsApp` is the full framework preset: everything in `typescriptApp` plus the Next.js-stack manifest requirement, the Next.js app source rules, and the Tailwind stylesheet blocks. The granular rule objects (`tailwindRules`, `repoPackageJsonRules`, `documentationRules`) stay exported for manual wiring.
+
+Because the preset blocks wire ESLint's language plugins, using them directly (without `zirka`) requires `@eslint/css`, `@eslint/json`, and `@eslint/markdown` to be installed in the consuming project — they are `peerDependencies` of `pasika`. A `zirka`-based setup gets them automatically.
 
 ### TS/TSX rules
 
@@ -140,11 +155,11 @@ export default [pasikaConfig];
 | `pasika/shared-style-dedup` †      | A className combo used by two or more components becomes a named utility                                            |
 | `pasika/repeated-structure`        | A block of elements repeated two or more times is extracted as a named component                                    |
 | `pasika/sole-state-owner`          | A contiguous JSX part that is the sole consumer of a useState hook is extracted into a named component              |
-| `pasika/no-eslint-disable`         | No `eslint-disable` directives                                                                                      |
+| `pasika/zirka-baseline`            | eslint, prettier, and TypeScript configuration come from zirka instead of being restated locally                    |
 | `pasika/zod-schema-validation`     | Runtime validation through Zod schemas, not hand-written type guards                                                |
 | `pasika/source-under-src`          | Application source lives under `src/`, not in root-level folders                                                    |
 
-### CSS rules
+### Tailwind rules
 
 Applied to `src/**/globals.css` (and other stylesheets) through `@eslint/css` with tolerant Tailwind v4 parsing.
 
@@ -161,20 +176,22 @@ Applied to `src/**/globals.css` (and other stylesheets) through `@eslint/css` wi
 | `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
+### Package.json rules
 
-Applied to `package.json` through `@eslint/json`.
+Applied to `package.json` through `@eslint/json`. The framework-agnostic subset (`no-vulyk-dependency`, `exact-version`) applies to any repository, including pasika itself; `nextjs-stack` applies to a Next.js/React application, and `vulyk-docs` to a repository adopting the framework.
 
-| Rule                         | Enforces                          |
-| ---------------------------- | --------------------------------- |
-| `pasika/no-cache-flag`       | Lint scripts don't pass `--cache` |
-| `pasika/no-vulyk-dependency` | `vulyk` is not in `dependencies`  |
+| Rule                         | Enforces                                                                            |
+| ---------------------------- | ----------------------------------------------------------------------------------- |
+| `pasika/no-vulyk-dependency` | `vulyk` is not in `dependencies`                                                    |
+| `pasika/exact-version`       | Dependency and devDependency versions are pinned exactly, never ranges              |
+| `pasika/nextjs-stack`        | All Tech Stack Reference packages are listed in `package.json` (Next.js/React apps) |
+| `pasika/vulyk-docs`          | `vulyk.config.ts` tracks the framework's docs from pasika and `AGENTS.md` exists    |
 
 ### Documentation rules
 
-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 lint`).
+The `pasika/*` markdown rules enforce the documentation guide over `docs/**/*.md` (22 rules): file-name suffixes and titles, overview shape (presence, sentence count, links), 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`; `npm run coverage` verifies each has a test and a registry entry. Pasika's own `docs/` are linted by them in CI (`npm run lint`).
 
-Run `pasika coverage --json` for the exact requirement each rule covers.
+Run `npx tsx scripts/coverage.ts --json` for the exact requirement each rule covers.
 
 ### † Cross-file rules
 
@@ -185,6 +202,10 @@ Where a component, hook, value, type, or style belongs depends on which files us
 
 All are inert in a repository with no `src/` tree.
 
+## Runtime dependency on typescript
+
+Many of the TS/TSX rules call the TypeScript compiler API directly at lint time, so the published package imports `typescript` at runtime. `tsup` keeps it external (unbundled); `pasika` lists it as a pinned `dependency` so an installing consumer gets a version known to work with the rules. There is no `typescript` `peerDependency`.
+
 ## Development
 
 ```bash

package/dist/eslint/pasika/index.d.ts

@@ -74,12 +74,10 @@ type JsxOpeningElementNode = Rule.Node & {
     parent?: JsxElementNode;
 };
 
-declare const mdRules: {
+declare const documentationRules: {
     "doc-kind-suffix": _eslint_markdown.MarkdownRuleDefinition;
     "title-matches-file-name": _eslint_markdown.MarkdownRuleDefinition;
-    "overview-present": _eslint_markdown.MarkdownRuleDefinition;
-    "overview-length": _eslint_markdown.MarkdownRuleDefinition;
-    "guide-overview-no-links": _eslint_markdown.MarkdownRuleDefinition;
+    overview: _eslint_markdown.MarkdownRuleDefinition;
     "guide-step-single-sentence": _eslint_markdown.MarkdownRuleDefinition;
     "guide-step-single-link": _eslint_markdown.MarkdownRuleDefinition;
     "guide-states-no-requirement": _eslint_markdown.MarkdownRuleDefinition;
@@ -99,9 +97,10 @@ declare const mdRules: {
     "guide-link-anchors": _eslint_markdown.MarkdownRuleDefinition;
     "no-nested-how-to": _eslint_markdown.MarkdownRuleDefinition;
     "glossary-term-linking": _eslint_markdown.MarkdownRuleDefinition;
+    "guide-mentions-documents": _eslint_markdown.MarkdownRuleDefinition;
 };
 
-declare const cssRules: {
+declare const tailwindRules: {
     "theme-reset": _eslint_css.CSSRuleDefinition;
     "root-variables": _eslint_css.CSSRuleDefinition;
     "apply-usage": _eslint_css.CSSRuleDefinition;
@@ -115,26 +114,32 @@ declare const cssRules: {
     "global-stylesheet": _eslint_css.CSSRuleDefinition;
 };
 
-declare const jsonRules: {
+/** Framework-agnostic package.json rules any repository should follow. */
+declare const repoPackageJsonRules: {
     "no-vulyk-dependency": _eslint_json.JSONRuleDefinition;
-    "zirka-installed": _eslint_json.JSONRuleDefinition;
+    "exact-version": _eslint_json.JSONRuleDefinition;
+};
+/** Package.json rules specific to a Next.js (or React) application. */
+declare const nextPackageJsonRules: {
+    "nextjs-stack": _eslint_json.JSONRuleDefinition;
+};
+
+declare const huskyRules: {
+    "husky-hook": _eslint_json.JSONRuleDefinition;
+};
+
+declare const vulykRules: {
+    "vulyk-docs": _eslint_json.JSONRuleDefinition;
 };
 
+/** Every source rule, merged so the Next.js preset applies them all. */
 declare const pasikaRules: {
     "component-placement": eslint.Rule.RuleModule;
-    "support-file-placement": eslint.Rule.RuleModule;
     "application-structure": eslint.Rule.RuleModule;
-    "named-exports": eslint.Rule.RuleModule;
     "data-testid-case": eslint.Rule.RuleModule;
-    "support-folder-shape": eslint.Rule.RuleModule;
-    "import-through-index": eslint.Rule.RuleModule;
-    "util-file-name": eslint.Rule.RuleModule;
-    "no-util-barrel": eslint.Rule.RuleModule;
     "jsx-hygiene": eslint.Rule.RuleModule;
     "interactive-component": eslint.Rule.RuleModule;
     "ui-state": eslint.Rule.RuleModule;
-    "filename-case": eslint.Rule.RuleModule;
-    "import-boundaries": eslint.Rule.RuleModule;
     "no-mixed-concerns": eslint.Rule.RuleModule;
     "no-arbitrary-tailwind": eslint.Rule.RuleModule;
     "enforce-cn-merge": {
@@ -149,38 +154,55 @@ declare const pasikaRules: {
             JSXAttribute(node: JsxAttributeNode): void;
         };
     };
+    "cn-helper": eslint.Rule.RuleModule;
     "enforce-cva-variant-props": eslint.Rule.RuleModule;
     "cva-appearance-props": eslint.Rule.RuleModule;
     "cva-boolean-variants": eslint.Rule.RuleModule;
-    "enforce-barrel-exports": eslint.Rule.RuleModule;
     "cross-feature-import": eslint.Rule.RuleModule;
     "pure-function-extract": eslint.Rule.RuleModule;
     "hook-complexity": eslint.Rule.RuleModule;
     "locale-dotted-path": eslint.Rule.RuleModule;
     "locales-location": eslint.Rule.RuleModule;
     "hook-extraction": eslint.Rule.RuleModule;
-    "value-extraction": eslint.Rule.RuleModule;
-    "config-extraction": eslint.Rule.RuleModule;
     "component-nesting": eslint.Rule.RuleModule;
     "stay-flat": eslint.Rule.RuleModule;
-    "type-extraction": eslint.Rule.RuleModule;
     "locale-placement": eslint.Rule.RuleModule;
     "sole-state-owner": eslint.Rule.RuleModule;
     "locale-key-shape": eslint.Rule.RuleModule;
     "shared-style-dedup": eslint.Rule.RuleModule;
     "repeated-structure": eslint.Rule.RuleModule;
+    "filename-case": eslint.Rule.RuleModule;
+    "import-boundaries": eslint.Rule.RuleModule;
+    "named-exports": eslint.Rule.RuleModule;
+    "support-file-placement": eslint.Rule.RuleModule;
+    "support-folder-shape": eslint.Rule.RuleModule;
+    "import-through-index": eslint.Rule.RuleModule;
+    "util-file-name": eslint.Rule.RuleModule;
+    "no-util-barrel": eslint.Rule.RuleModule;
+    "enforce-barrel-exports": eslint.Rule.RuleModule;
+    "config-extraction": eslint.Rule.RuleModule;
+    "value-extraction": eslint.Rule.RuleModule;
+    "type-extraction": eslint.Rule.RuleModule;
     "zod-schema-validation": eslint.Rule.RuleModule;
     "source-under-src": eslint.Rule.RuleModule;
-    "config-baseline": eslint.Rule.RuleModule;
+    "zirka-baseline": eslint.Rule.RuleModule;
 };
 
-/** Rule ids as they appear in configuration and in lint output. */
-declare const pasikaRuleIds: string[];
-declare const pasikaMdRuleIds: string[];
-declare const pasikaCssRuleIds: string[];
-declare const pasikaJsonRuleIds: string[];
 /** Every rule id, as they appear in configuration and in lint output. */
 declare const allPasikaRuleIds: string[];
-declare const pasikaConfig: Linter.Config;
+/**
+ * TypeScript app preset: the framework-agnostic baseline — the package.json
+ * manifest (incl. husky hook and vulyk requirements), the zirka configuration
+ * contract, the `src/**` TS/TSX source, and the documentation markdown rules.
+ * Use this for a plain TypeScript repository.
+ */
+declare const typescriptApp: Linter.Config[];
+/**
+ * Next.js app preset: the full adopted-to-the-framework stack. Anything in
+ * `typescriptApp` plus the framework-only blocks — the Next.js-stack manifest
+ * requirement, the Next.js app source rules, and the Tailwind stylesheet
+ * rules. `typescriptApp` is a strict subset of `nextjsApp`.
+ */
+declare const nextjsApp: Linter.Config[];
 
-export { allPasikaRuleIds, cssRules, jsonRules, mdRules, pasikaConfig, pasikaCssRuleIds, pasikaJsonRuleIds, pasikaMdRuleIds, pasikaRuleIds, pasikaRules };
+export { allPasikaRuleIds, documentationRules, huskyRules, nextPackageJsonRules, nextjsApp, pasikaRules, repoPackageJsonRules, tailwindRules, typescriptApp, vulykRules };